SimulationProject

While model solutions provide high flexibility to customise model structures to the analytical question at hand, the SimulationProject encapsulates a ModelSolution for batch-run purposes. This is done by executing SIMPLACE in project mode which takes both SimulationProject and ModelSolution XML files as input arguments (e.g. In Console).

The list of simulations and respective parameters provided in the SimulationProject is executed in parallel, replacing the value of the corresponding parameter matching the SimVariable names declared in the <variables> section of the ModelSolution. This feature allows multiple simulations considering, for example, different soil, weather, and crop traits and/or control parameters. The outputs are organised with the corresponding simulation and project IDs given in the SimulationProject file.

The structure of a SimulationProject is similar to a ModelSolution in the sense that it also has <interface>, <resource> and <output> objects. A simple SimulationProject can be composed only by one <interface> and its corresponding <resource> object. The <interface> can point to a CSV data table file containing the combination of parameters values, simulation and project IDs; whereas the <resource> must be declared within the <projects> section and named “projectdata”, containing the corresponding SimVariables for the simulations. The list of simulation IDs assigned to each project ID is executed in parallel. By default, the multi-threading controller creates n-1 simulation threads (where n is the number of available threads in the system) to run the ModelSolution independently.

fig6

Fig Simplified diagram depicting how a SimVariable can be declared and iterated using the SimulationProject and ModelSolution XML files. The dashed red arrows represent the information flow and the “...” represents parts of the XML files that were omitted for simplicity. In this example, the ModelSolution will be executed five times with different weather input files (e.g. weather_${vSiteID}.csv). As all five simulation IDs (simulationid=1 to 5) are assigned to a single project ID (projectid=1), these simulations will be executed in parallel. The output files from the ModelSolution will automatically contain two columns with the corresponding project and simulation IDs (source: https://doi.org/10.1093/insilicoplants/diad006)

How projects drive solutions

With a project, you can:

- Change variables defined in a solution (e.g. startdate, soiltype, cropname)

- Change interfaces, so that data is read from different files

- Redirect output to other targets (e.g. another file or a database)

Constraints for common use of projects and solutions

There are several constrains:

- Projects can change only variables defined in the solution

- If interfaces are changed, the datafiles or databases must have the same structure, so that they are compatible with the resource definitions of the solution

- Input and output sources change only, when the project id changes.

- Data should be logically consistent (e.g. start- and enddate should lie within the period of supplied weatherdata)

Defining Projects

Projects are defined as a XML-File. There are three ways of defining a project:

- Defining every run and it‘s parameters directly in the projectfile. This is suitable, if you want to run a solution two, three times.

- Defining every run and it‘s parameter in an external resource (file or database).

- Defining the runs by a generator, that changes some variables in a given range and runs the simulation with the generated values.

Project file

<var id="vCropName" datatype="CHAR">spring wheat</var>

</simulation>

<var id="vCropName" datatype="CHAR">winther wheat</var>

</simulation>

</project>

The project contains two runs with different start-/enddates and crops. The value of the variable vLUE is used in both runs and replaces the value defined in the solution.

External resource

<filename>gecros/GecrosSensitivityStartDate.csv</filename>

</interface>

</interfaces>

</header>

</resource>

</projects>

The projectdata is located in a CSV file that is referenced in the interface section. For each line in the data file there is a solution run.

The value of the variable vSowingDoy is replaced with the corresponding value from the datafile.

Generator

see the generator page

Other features

•You can substitute the files/databases from the solutions interface section by adding interfaces with the same id in the project file.

•Interfaces for resources can reference filenames with placeholders (e.g. /data/${vClimatezone}_weather.txt). If the variable is different for each run, then a different data file is loaded.

•The same holds for outputs. They are now also changeable.

•The type of the interface is changeable, so that you can use a database instead of a file.

•You can define a selector in your project, that evaluates the results of all runs and points out the one, that matches best the criteria defined in the selector

•Data is read from file/database only for a project, not for each simulations. If you want to change the source of data, you have to make a new project (e. g. by giving a new projectid in the projectdatafile).

•Simulations in a project run parallel, therefore a simulation started later might finish earlier, which results in unsorted output data.

Running a project

To run a project, you can create an unit test where you mention the solution and the project file you want to use.

@Test

public void testGecrosSensitivity()

{

String tSolutionFileName = "gecros/Gecros.sol.xml";

String tProjectFileName = "GecrosSensitivityTest.proj.xml";

FWSimEngine.runProject(tProjectFileName, tSolutionFileName);

}