Skip to content

MONICA Configuration Files

General overview

MONICA uses a set of configuration files to either parameterize the model or set up all input data necessary to run the model.

The following four files are necessary to run the model:

  • climate.csv
  • sim.json
  • site.json
  • crop.json

The three .json files contain the necessary input information to run the MONICA model. These files contain all information for a model run. Optionally, these files can reference other .json files with actual parameters of the MONICA model (crop, general soil, or general environmental parameters). All necessary data can also be obtained from a SQLite database instead of the .json files. Either way (file or database), at runtime every one of the three .json files (sim.json, site.json, crop.json) will hold all information for a MONICA run. Because of that, it is also possible to manually include all parameters in these three files instead of referencing other parameter files or database data. This makes particular sense if these files are being generated by an external tool for bulk processing.

All .json configuration files reflect, to some degree, the data structures internally used in MONICA. In case of missing configuration values, MONICA uses built-in default values. These can usually be taken from the corresponding .h (C++ header file) in the MONICA source code. Real parameters for the MONICA model should all have default values. In contrast, missing input data (e.g., a soil profile in site.json) cannot be compensated for, and MONICA will not run.

Example: Parameter definition

In the following JSON code snippet taken from the sim.json example file, two settings are declared: UseAutomaticIrrigation which is set to false, and AutoIrrigationParams, which is set to a JSON object (key/value map). This object/map contains three parameters: irrigationParameters, another JSON object; amount, a JSON array (list of values) [17, "mm"]; and threshold, a floating-point (double) value 0.35. For amount, MONICA allows a JSON array with two or three elements instead of a simple value like 17. The second element (in this case "mm") will be treated as the unit describing the value (17). An optional third value can be added as a description of the value.

Note

Even though the JSON array syntax can be used to add units of measure and an optional description, this information is currently ignored by MONICA. It is meant purely as a description of the value. For the correct units of measure and dimensions, please refer to the MONICA documentation or the example files.

"UseAutomaticIrrigation": false,
"AutoIrrigationParams": {
  "irrigationParameters": {
    "nitrateConcentration": [0, "mg dm-3"],
    "sulfateConcentration": [0, "mg dm-3"]
  },
  "amount": [17, "mm"],
  "threshold": 0.35
},

All necessary data can be included in the configuration files either as (potentially deeply nested) JSON objects or by using a reference and include mechanism to fetch data from a SQLite database or files in the filesystem. Where applicable (e.g., crop.json), JSON objects can be referenced in multiple places.

Default values

Most of the JSON object data that may be included from a database or from a file support an optional key named DEFAULT, which enables the user to load/include data but overwrite some of them manually. In the example below, an EnvironmentParameters JSON object is being defined. It will be initialized completely from a file, but the keys LeachingDepth and WindSpeedHeight will be overwritten. This way, a user can keep rarely changing data in a file and always include them via DEFAULT, while from project to project only a few values need to be changed or updated.

Example:

"EnvironmentParameters": {
  "DEFAULT": ["include-from-file", "../monica-parameters/user-parameters/hermes-environment.json"],
  "LeachingDepth": 2.0,
  "WindSpeedHeight": 2.5
}

Functions in JSON

Currently, there exists a single mechanism to add some dynamics to the otherwise static configuration files. In the value position of a key/value pair, a JSON array can appear that starts with a string/text value. In that case, upon reading and interpreting the configuration file, MONICA will check internally if there is a function with a name corresponding to the string value. If so, it interprets the whole JSON array as a function call. The first argument represents the function being called, and the rest of the array's elements represent the arguments to this function (similar to function calls in Lisp-style programming languages). The result of this "function call" will again be a JSON value (e.g., a JSON object) and will replace the JSON array. If for some reason (e.g., wrong spelling, typo, etc.) no internal function is found, the JSON array remains unchanged; this being the reason for the Lisp-style syntax, to retain a valid JSON document.

Include data from a file

To include data from a file, the example from above would look like the one below. The name of the function is include-from-file, with its only parameter being the path to the file to include. The entire contents of the named file should be valid JSON and will be included. The included JSON data may again contain other functions.

"cropParams": {
  "species": ["include-from-file", "../monica-parameters/crops/rye.json"],
  "cultivar": ["include-from-file", "../monica-parameters/crops/rye/winter rye.json"]
},
"residueParams": ["include-from-file", "../monica-parameters/crop-residues/rye.json"]

In order to keep paths to the files to be included reasonably short and readable, relative paths will be prepended by the contents of the contents of the key include-file-base-path. This key is defined in sim.json and is allowed in crop.json and site.json. In the latter case, a "local" definition of include-file-base-path will replace the one in sim.json. By default, include-file-base-path in sim.json is defined as "${MONICA_PARAMETERS}/". This means it will take the value of the environment variable MONICA_PARAMETERS, which after a MONICA installation will point to the directory where all the MONICA parameters were installed (usually something like C:\\users\\USER_NAME\\MONICA\monica-parameters).

Keep in mind that if include-from-file has a relative path as its first parameter, include-file-base-path will be prepended and must resolve to a valid filesystem path. If include-from-file's first parameter is an absolute path (e.g., starting with C:\\ on Microsoft Windows or / under Linux), nothing else will be done to the path.

Reference data within a file

Crops that are defined in crop.json can be referenced multiple times using the ref function. In the example below, taken from the worksteps section of a crop, the Sowing workstep, among other worksteps, uses the key/value pair crop: winter rye. The ref function takes two parameters: the first being a name ("crops") which is a key in the top-level JSON object of the file that also contains another JSON object where the key = WR returns the JSON object to replace the function call. Thus, in the example crop.json, under the key crops, arbitrary crop name shortcuts are mapped to crop parameter objects. The objects themselves can be included by using the include-from-db or include-from-file functions.

{ "date": "1991-09-23", "type": "Sowing", "crop": ["ref", "crops", "WR"] },

Other functions

Function Name Parameter 1 (Example) Parameter 2 (Example) Description
"humus-class->corg" humus class (1) - Converts the humus class to Corg value
"bulk-density-class->raw-density" effective bulk density class (1-5) clay content (0.0-1.0) Converts the effective bulk density, given the clay content, to raw density
"KA5-texture-class->clay" KA5 texture class (fSms) - Returns the average clay content given the KA5 texture class
"KA5-texture-class->sand" KA5 texture class (Lt3) - Returns the average sand content given the KA5 texture class
"sand-and-clay->lambda" sand content (0.0-1.0) clay content (0.0-1.0) Calculates the lambda value given sand and clay content

As shown in the following example taken from site.json, the function calls can be nested:

"SoilRawDensity": ["bulk-density-class->raw-density", 2, ["KA5-texture-class->clay", "Sl2"]],
"Lambda": ["sand-and-clay->lambda", ["KA5-texture-class->sand", "Sl2"], ["KA5-texture-class->clay", "Sl2"]]

JSON data format

Currently, MONICA uses JSON as the format for its files. Please ensure that you adhere to the rules and formatting conventions of JSON! To check and/or reformat existing code, tools like this online JSON Viewer or this JSON Formatter can be used.

Warning

JSON has no syntax for comments, it is a pure data format. To make the configuration files more self-descriptive while keeping them valid JSON files, comments are encoded as keys beginning with two underscores __ and an empty string "" as their value. This method can also be used to comment out structures that should currently not be used, simply by making a key invalid (e.g., adding an underscore character in front, _, or renaming it to a name unknown to MONICA).