Run MAAT simulations

Running MAAT starts by setting up a MAAT project. This creates (or installs to) a directory on your system and sets up a few environment variables so that when you run MAAT from that directory the call scripts know where to look for the MAAT code. In the project space you can customise the simulations and all the template files needed to do that will be copied across to the project directory. You cannot edit the source code from the project space, the call scripts always look to the maat source code directory so be sure to be on the branch/tag you intend to be when running a simulation. Any edits to MAAT source code can be done on a new branch of your choosing - see git documentation for how to do that.

Set up & run MAAT

• Set up a MAAT project. A MAAT project is a directory on your hard drive where multiple related MAAT simulations can be defined, run, and have output stored. These project directories (as many as you like can be set up) are isolated from the source code. For beginners with git, DO NOT set up a MAAT project in the source code directory. To set up a new project run the following command from within the maat source code directory on your machine:

./run_scripts/setup_MAAT_project.bs <modelobject> <projectpath>

where <modelobject> is the name of the system model to be used in the project and <projectpath> is the full path of where the project is to be set up. The lowest level directory in the path will be created if it does not already exist. The first time you set up a MAAT project try running the above command with leaf as <modelobject> and your prefered path to set up a test case MAAT project. Change directory to the project directory and a simple instance of MAAT can be run:

cd <projectpath>
./call_run_MAAT.bs

This should provide a simple simulation of Aci curves with three different electron transport functions. The variables of the run are defined in init_MAAT.R in the project directory.

• Initialisation files. Once the above steps have been completed and MAAT is working without error, the next step is to customise the run. A MAAT ensemble is defined by the process representations, the parameter values, and the environmental variables that a user defines. These values can be defined as static, i.e. values that are invariant across the whole ensemble, or dynamic values i.e. values that are varied across the ensemble. The values of the static variables and dynamic variables are defined by the user as either lists in an R script init_MAAT.R or as separate XML files init_user_static.xml and init_user_dynamic.xml. These are expected to be found in the highest level project directoryi, i.e. <projectpath>. So that multiple simulations can be run from within the same project, these initialisation file names and be appended with _<runid> where <runid> is a character string that identifies the particular ensemble. For example, you can create a new init file, edit it, and then rerun MAAT with the runid as the first argument to the call script. Assuming you are still in the project directory:

cp init_MAAT.R init_MAAT_yourrun.R
vim init_MAAT_yourrun.R   # change some of the values of the dynamic variables
./call_run_MAAT.bs yourrun

• Options. MAAT can be configured in many different ways. The names of the variables and their various options can be found in <model_object>_options.xml in the source directory. Alternative command line options, their names, and how to specify them on the command line can be found on lines 33 - 110 of run_MAAT.R.

• Meteorological data files. The path and filename for meteorological data can be passed as an option to run_MAAT.R through any of the call_*.bs scripts. Currently all the meteorological data must reside in a single file in csv format with the first row (and only the first row) as a column header. A file named <modelobject>_user_met.xml must also exist in the directory <projectpath>. An example xml is copied across to that directory when the project is set up. The xml is structured to represent the input data of the model object, i.e. the env list in the data struture. To allow MAAT to read your meteorological data file, the values in the <modelobject>_user_met.xml list should be the name in the column header of the meteorological file of the variable that corresponds to the variable name in the MAAT env list. Note that not all variables in the env list must be specified in the xml or the met data file, in this case the default or the value set in the static or dynamic input is used. In the case where a variable appears in the static or dynamic list AND the met data file, the values in the met data file will be used.