Adding new SimComponents require a basic understanding of the modularization scheme of SIMPLACE and Java programming language. There's a set of steps involved in the process of creating a new SimComponent, which is described in the figure below:
Steps to Create and use new SimComponent
Building Data File
Before developing the new SimComponent its highly important to build a dataset for testing at the simulation context for the desired SimComponent. This could be done in a new ModelSolution and following the SimExperiment Setup standards.
Creating Interface <interface>
The <interface> objects should be properly linked in the ModelSolution:
1.choose the interface id
2.specify the format type of created file
3.define the number of connections of files that it can store at a time
4.define a divider to read files properly
5.the name of the file which was prepared in first step
| Possible file formats: |
 |
Defining Resource
Adding the resource means to specify the names of the columns and its data type that is mentioned in the data file.
•Possible values for frequency: ONCE, DAILY, YEARLY, COMPLEX: Rule
•Key is a link to the data value. More then one key is possible
•For resource unit and description can be specified
Making Java Class
New SimComponents must follow a structured format containing five prerequisites to become operable with the SIMPLACE main engine:
i.it inherits the abstract class “FWSimComponent” of SIMPLACE;
ii.it has the appropriate declaration of constants, inputs and outputs variables in the method “createVariables”. The declared variables in this method will be converted into SimVariables and stored in the simulation data container (VarMap);
iii.it has a method called “init” with the equations and rules for (re)initialization of the SimComponent’s state variables. For example, this method will be executed by SIMPLACE at beginning of the simulation run time or when some initialization or reset flag is activated during the simulation (e.g. “DoHarvest”);
iv.a method called “process” containing the algorithm of the SimComponent, which SIMPLACE executes on a regular daily timestep. This is normally composed of step-rate equations, which can be simple (e.g. phenology models) or quite elaborate (e.g. water flux) with internal sub-daily loops depending on the level of modularization needed;
v.and a method called “clone” that allows the replication of the SimComponent objects in multiple-thread simulations.
Generally, the model developer can only focus on coding the equations that describe the desired algorithm in the methods “init” and “process” (Java language), as the other requirements are mainly boilerplate code. Thus, the level of difficulty is usually defined by the algorithm's complexity rather than by making it operable with the framework. Transpiler platforms such as Crop2ML can potentially automate this process for components coded in other modelling platforms (Midingoyi et al. 2021). Yet, a new SimComponent may still require finer adjustments to become seamlessly operable with the existing SimComponents. For example, matching ontology units of variables so they can be linked directly to other SimComponents without an intermediate step to scale/convert units; or to make the appropriate separation between initialization and step-rate processes.
Once the new SimComponent file is created (usually a unique Java-type file, eg. “MySimComponent.Java”), it should be compiled with the SIMPLACE framework to become available for a ModelSolution. To invoke the corresponding SimComponent in a ModelSolution, modellers should use the Java classpath at the compilation process (e.g. “class” attribute). For example, the SimComponent object “CropPhenology” in Fig. 4 is created using the Java-type file compiled in the system path: <repository>/src/net/simplace/sim/components/models/lintul5/Phenology.Java, or conversely class=“net.simplace.sim.components.models.lintul5.Phenology”. The list of SimComponents distributed with SIMPLACE (https://simplace.net/doc/simplace_modules/) is maintained by the framework developers at the University of Bonn. The algorithms of these SimComponents were previously documented or scientifically tested by the community members (see section 4 of the main manuscript). To add new SimComponents to the official list a request should be sent to one of the framework developers (or a ticket request should be created in the SVN managing system Redmine). Before being added, the SimComponent algorithm must not be limited to licence constraints and should be evaluated for quality assurance (Quality assurance).
Defining SimComponent
Defining the Output
•Defines in flexible and performing way the output of the model. It is independent of the data format and depends on an interface. Ensures the efficient use of the computer’s resources.
•Possible values for frequency: ONCE, DAILY, YEARLY, COMPLEX: Rule
Unit Test
Unit Tests have to be implemented for executing the ModelSolution where the new SimComponent is being tested.