The SIMPLACE framework is implemented in the Java(R) programming language based on the object-oriented paradigm (Gamma et al. 1995). It contains several packages developed for advanced input/output (I/O) handling, relational databases for internal data resources structure and exchange across components, and multi-threading simulations. The external input data formats currently accepted in SIMPLACE v5.0 are SQL-database, CSV, JSON, NetCDF, DBF and XML. It can also read JSON and XML directly from URL-based data streaming servers.
Once an external input data is read it’s internally converted into a tabular structure and stored in a data container (“VarMap”) to be exchanged among objects during the simulation runtime. Variables stored in the data container are named “SimVariables”, and can be declared as objects with unique data types such as characters (CHAR), dates (DATE), numerical (DOUBLE, INT) and logical (BOOLEAN). Numerical data arrays can also be defined as CHARARRAY, DOUBLEARRAY or INTARRAY. Data types MAP, DATEARRAY and DOUBLEMATRIX are available but only for private variables and not motivated to be used for compatibility with module exchange interfaces, for example, Crop2ML (Midingoyi et al. 2021). SimVariables can also hold unique attributes such as their own ID, a description, minimum, maximum and default values, and unit. These are important not only for documentation purposes but for assisting automated checks during simulation runtime.
In SIMPLACE, a model structure is referred to as a “ModelSolution” and consists of discrete, replaceable, and interchangeable software units, or sub-models, called “SimComponents”. A SIMPLACE ModelSolution is specified in an XML file and can be executed stand-alone or several times provided an optional second XML file called “SimulationProject”. A native package called “ProjectController” initialises and controls the execution of a ModelSolution in multiple parallel simulations. This package also provides support for simple sensitivity analysis and model calibration (further described in Section 2.4).
The framework operates at regular daily timesteps based on the Euler integration principle. Therefore, SIMPLACE calls each SimComponent and exchanges its state/rate variables at regular daily timesteps following the order prescribed in the ModelSolution XML file. Sub-daily calculations are only possible within a SimComponent containing sub-daily loop calculations. In these cases, sub-daily outputs are made accessible to other SimComponents or Outputs through SimVariables of array type (e.g. a vector of 24 values of canopy temperature for each hour of the day).
The VarMap is the main data container of the simulation instance and enables a static design of the SimComponents. A suite of data transformers packages is available for internal aggregation and harmonisation of input data. To support further data processing, a JEXL Rule Engine is implemented which parses arithmetic and logical expressions (including small scripts) from the ModelSolution for intermediate calculations, data aggregation/disaggregation and controlling of boolean switches. The latter is particularly important to trigger crop management interventions such as harvesting, irrigation, and fertilisation, as well as the frequency with which data interfaces are accessed or updated for better performance of simulation running time.
Moreover, SimComponents, data Interfaces and Transformers can be implemented and added by developers to support their own needs in the simulation experiment setup. This structure enables developers to attach their own algorithms, sub-models, data formats and data transformation routines seamlessly into the model structure and therefore allows for an easy plug-in for the use of different approaches in the simulation processes at a user-defined sequential logic. An overview of the main relationship and encapsulation hierarchy between these components and features is depicted in Fig. 1. The SIMPLACE-specific terms (text in bold) are presented on the Glossary page.
Fig. 1 Simplified overview of a ModelSolution within the SIMPLACE framework including a calibration project. By default, each simulation listed in the ProjectController is treated independently and is simulated in parallel for better use of computation resources (“Simulation Thread”). The “Best Simulation” represents the simulation that matches the user-defined criteria in the SimulationSelector feature of SIMPLACE, which is typically used for simple calibration purposes (source: https://doi.org/10.1093/insilicoplants/diad006)
The next topics will focus on describing these components and features in detail.