implementing/re-implementing a simulation model using a … · implementing/re-implementing a...

Implementing/re-implementing a simulation

model using a component based approach

- Phase 1, the conceptual model -

January, 2015

Version 1.2

The Team of Work Package 2

2

Implementing simulation models using a component…

Summary __________________________________________

Introduction ......................................................................................................................................................... 3

Target users of this document ......................................................................................................................... 3

Phases in model implementation – the whole picture ....................................................................................... 4

Phase 1: Formalizing the conceptual model .................................................................................................... 4

Phase 2: Creating model components ............................................................................................................. 4

Phase 3: Composing modelling solutions ........................................................................................................ 4

Phase 4: Interfacing to a simulation system .................................................................................................... 4

Modelling solution features ................................................................................................................................ 5

Describing the domain ......................................................................................................................................... 5

What information for each variable? .............................................................................................................. 6

Core variables: States, Rates, Auxiliary ........................................................................................................... 7

External quantities: ExternalStates, ExternalRates, Exogenous ...................................................................... 7

The case of agricultural management ............................................................................................................. 8

What about parameters? ................................................................................................................................ 8

Formalizing the description of the domain ..................................................................................................... 9

Model units ........................................................................................................................................................ 10

What granularity for model units? ................................................................................................................ 10

Simple models ............................................................................................................................................... 11

Composite models ......................................................................................................................................... 11

“Simple models” or “functions”?................................................................................................................... 11

Example calculations ..................................................................................................................................... 12

Context models .............................................................................................................................................. 12

Examples ............................................................................................................................................................ 13

Reference evapotranspiration ....................................................................................................................... 13

The WOFOST crop model .............................................................................................................................. 13

Preparing documentation for the next phase ................................................................................................... 14

Composition ................................................................................................................................................... 16

Credits ................................................................................................................................................................ 17

History of the document ............................................................................................................................... 17

Glossary ............................................................................................................................................................. 18

References ............................................................................................................................................................. 19

__________________________________________

3


Introduction Current technology makes available both to modellers and to model users options to improve both the

development and maintenance of simulation tools, and the transparency both of software constructs and their

behavior at run time. In other terms, much more than running a model black box is now easily at reach; this

suggests many modellers to use such technologies either for new implementations, or to re-implement their

legacy code of modelling solutions. There are several advantages in using a component-based, fine-

granularity, model implementation, which can be summarized as easier re-use, greater transparency of the

model construct, and ease of maintenance, the last aspect both with respect to new developments and to sub-

model comparison (Donatelli and Rizzoli, 2008; Donatelli et al., 2014).

However, implementing or re-implementing a simulation model using a component-based approach is often

estimated as a very challenging task, which requires substantial software coding skills. This is not the case and,

in fact, the first and most important phase does not require coding at all.

Instead, what can actually be limiting in this process is, as it will appear evident, the precise knowledge by

either a modeler or a modelling team of the model to be implemented (or re-implemented). In theory, from a

model documentation a third party should be able to reproduce a model implementation, but this is never the

case in the experience of all who have done it. Consequently, the benefit of implementation or re-

implementation using the approach proposed is not only the new implementation per se. In fact, what is often

a partial picture from at times not updated documentation becomes a complete and updated description of

the model. In other words, the advantages go beyond the pure, functional, new implementation.

The goal of this document is to provide guidance on the first phase of model (modelling solution)

implementation or re-implementation. One of the major objectives is consequently to concretely bridge

modellers to those who will finalize the software implementation, in case the modeller will not do any coding

at all.

What follows is about the model engine, which means that neither I/O functions, nor graphical user interfaces,

will be considered. Some of the concepts presented and of component-oriented programming also apply to

those parts of a simulation system, but this document is strictly about biophysical model implementation in a

component based system.

Although the concepts and procedures of the first phase are completely independent from any specific choice

as software either platform or architecture, in the following phases – as anticipated, not necessarily of interest

for a modeler, we will refer to the BioMA (VV.AA., 2013) architecture and software to develop concrete

examples.

Target users of this document

Experienced modellers who want to implement (or have implemented by a third party) a modelling solution in

a software component-based system. Without knowledge of modelling techniques and approaches for

biophysical systems the content of this document will result excessively abstract.

4


Phases in model implementation – the whole picture Implementing a modelling solution as a software according to the approach proposed for a component-based

framework can be discretized into four phases. The first three listed below are essential to make a reusable

software unit of a modelling “engine”, matching the requirements summarized in the introduction and later

expanded; the fourth phase is an example on how to make use of such modelling engine to develop software

applications for final users of a system for biophysical modelling.

Phase 1: Formalizing the conceptual model

Phase one is actually the prerequisite to implementation of a modelling solution as discrete units of software,

hence, no programming at all is required at this stage. It consists of formalizing what is the domain to be

modelled, what are the mathematical functions involved, and how functions are linked to produce the outputs

of interest. Even having a detailed documentation which would not require formalizing most of what needed

as model description, in this phase design choices are made on how to discretize knowledge into code units in

the following phases. In other words, even if in this phase no coding is done, it must be always clear that the

final goal is a software implementation, thus all details need to be identified and documented.

Phase 2: Creating model components

Based on the work of phase one, this phase is concerned with the development of the code units of each

model at fine-granularity. All code units referring to the same domain (e.g. “Crop”, “SoilWater”) will be

implemented in a specific software component. Within a model component, code units may build permanent

compositions (e.g. the composition “Phenology”, composing “ThermalTime and “PhotoPeriod”). Models from

components will be later composed (e.g. link PotentialPlantWaterUptake to SoilPlantAvailableWater to

estimate ActualPlantWaterUptake) to create a modelling solution (e.g. a crop-soil model to estimate water

limited crop production). Components have semantically rich interfaces and are developed for reuse and

composition. They have few and clearly specified dependencies.

Phase 3: Composing modelling solutions

Once model components are available, models can be linked within the infrastructure to handle time, event-

driven calls, to accept initial conditions and parameters, to generate outputs, creating a modelling solution.

The modelling solution built in this phase has neither a graphical user interface nor an infrastructure to provide

data persistence in general. At this stage, a modeling solution can be reused in different simulation

environments via a dedicated adapter, which can be built easily given the semantically rich interfaces exposed.

It works as a composition but its basic, constituent units are easily identifiable, and can be replaced for further

development creating alternate modelling solutions.

Phase 4: Interfacing to a simulation system

Once a modelling solution is made available as package of components, it can be easily interfaced through

their API to a specific simulation system (in MODEXTREME, BioMA), which in turn provides with controls via a

GUI and takes care of data persistence, output data use, and interfacing to other applications, e.g. for

sensitivity analysis or optimization. Of no lesser importance, a the simulation system with the features

described allows for multiple modelling solutions either for comparison or ensemble runs, while it provides

access to simulation messaging at runtime and to modelling solution structure. Interfacing to a simulation

system will be exemplified by building an adapter to the BioMA Configuration Layer, and showing the use of

5


the modelling solution built in the applications BioMA-Spatial and BioMA-Site, all allowing the use of several

components as summarized above.

Modelling solution features When targeting the modelling of a biophysical system, such as the crop-soil interaction, we refer to dynamic

models defined by differential equations, which most of the time have no analytical solution. Numerical

solutions can obtained via simulations, which in turn are characterized by a reference time step, which should

be adequate to capture the variability of the processes. The time step of the modelling solution determines

when integration of state variables occurs for the whole system, and, in implementation terms, when different

parts of the MS (either discretized as components or simply as routines of a structured programming

implementation) communicate. Single models of the modelling solutions may have shorter time steps than the

one of the modelling solution, being such time steps constant (e.g. hour in modelling solutions which are based

on a daily time step) or variable (e.g. as in water redistribution models in the soil profile models, where the

time step is variable to reach convergence). The design and implementation of a modelling solution needs to

define the simulation time steps. In case of model outputs that use a shorter time step than the whole

modelling solutions those need to be available as ancillary outputs in the corresponding data structures.

Describing the domain The first step in modeling solution development is a clear definition of the domain. A modelling solution is the

description of an abstraction of a system, chosen with respect to a specific purpose. Consequently, the

description of a domain must be tailored to its intended use in the modelling exercise, and it will not be an

attempt to formalize all knowledge available for the domain. In other words, soil, crop, or soil water, soil

nitrogen must be described in terms of the quantities needed to model their dynamics, primarily as states of

the system and as rates of change.

A very important choice is the definition of the subdivision of the whole system to be modelled in different

domains, because this will impact both implementation and its result in terms of understanding of interfaces,

of ease of maintenance, and of ease of reuse. For instance, possible choices split the plant-soil system into

“Crop” and “Soil”. Other subdomains can be “Insects” and “FungalDiseases”; however, the choice can be more

articulated, for instance subdividing soil into “SoilRunoffErosion”, “SoilWater”, “SoilNitrogen”, and

“SoilTemperature”. The subdivision will impact on the grouping of variables. The subdivision into components

is discussed in the paragraph Composition.

Some variables can be duplicated in such grouping; for instance, CropWaterPotentialUptake, estimated by a

crop model, can also be in the “SoilWater” group as needed to estimate the matching between crop water

demand and soil water availability, enabling a link between the two models crop and soil water.

The choices of variables can be easily updated, but it is more difficult to change the groups (i.e. the sub-

domains) as it will become clear in the coming paragraphs. Within a domain (the groups discussed so far),

variables are further grouped into collections to make easier to understand and use, as software, the

interfaces. These collections are called Domain Classes, referring to discrete classes in an object-oriented

programming implementation.

6


As with any software designing exercise, these definitions very often, if not always, require several attempts to

make model links to reach the first running version of collections. Via an iterative approach, the definitions are

at times refined and extended when new modelling approaches are added as alternate solution to specific

modelling problems.

What information for each variable?

Variables will not be described only by their name. Other information is useful not only for documentation, but

it is also needed to implement specific functionalities in the software, as it will become clear in the document

of Phase 2.

The name of the variables conventionally attempts being descriptive in English. For instance, to

name a variable which is above ground biomass, the name AboveGroundBiomass, rather than

AGB, will be used. It could also be BiomassAboveGround.

The additional attributes for each variable are:

1. Description

2. Maximum value

3. Minimum value

4. Default value

5. Numerical type (e.g. integer/decimal; scalar/vector)

6. Units

7. (URL)

Minimum and maximum values are defined to represent the range of possible variation in our system (not

necessarily the range possible in each possible system); for instance, daily maximum air temperature could be

defined as -20 to 45 °C.

The default value has a clear meaning for a model parameter, as we will discuss later. However, even for model

variables the default value can be of use during the process of model development and more specifically under

testing.

The numerical type is important as it will impact the software interface which will be defined (e.g. even for a

modelling solution with a daily time step, it might be of interest to access the hourly outputs of a stress model,

even if other models in the same modelling solution will use a daily value derived from the hourly values;

hourly values will require definition of vectors with 24 items).

The units can be potentially used during composition, to ensure that no dimension conversion is needed; in

any case they are an essential part of documentation.

The units are not standardized; the type of notation should be kept consistent for at least a

model component.

The URL, as optional, may ideally link to subclasses of concepts in a shared ontology, or to any form of online

dictionary/documentation.

7


Core variables: States, Rates, Auxiliary

Given that most models use the descrete event simulation approach, they describe the system via states

(which should be observable in the physical system) and via rates, which determine the change of state at each

time step. Also auxiliary variables are used (e.g. the total amount of water received as irrigation, the number of

irrigations applied). The variables in these three groups (which will become each a Domain Class) are the

quantities modelled by the model to be implemented. Some examples follow.

States

Rates

Auxiliary

External quantities: ExternalStates, ExternalRates, Exogenous

External quantities are needed in cases that models are required to be linked to each other. (e.g. “Crop” likely

requires links to “Soil”). For instance, a model may need to access some state that is modeled by another

component. As an example consider a “Soil” model implementation that provides with

PotentialPlantWaterUptake, while a “Crop” model needs to access it in order to estimate

ActualPlantWaterUptake. In this case, the “Soil” component must declare PotentialPlantWaterUptake as an

ExternalRate, so that “Crop” implementation can link to.

In general, models require links for sure to driving forces, typically weather variables, which are included into

the exogenous collection. Example of exogenous follows.

8


Exogenous

The case of agricultural management

Different from the previous sections, a specific approach to agro-management modelling is considered, de

facto using a standard. About the reason for such specificity, for now let’s just focus on one point: the agro-

management models publish agro-management events, but it is up to other models in other components (e.g.

SoilWater, Crop) to implement the impact. This implies that agro-management models publish objects at run

time that must be recognizable by different components to implement the impact. In code terms, this can be

achieved if the objects that the agro-management models publish are known, as type, to the components

implementing the impact; again in code terms, this means that the components implementing impacts will

have a dependency to the specific software unit implementing agro-management models. As a concrete

example, the agro-management model publishes an irrigation event via an object “Irrigation”, which specifies

the type of irrigation, the amount and possibly other variables. For example, a “SoilWater” component

recognizes the object “Irrigation” and applies the “impact”, that is, applies the given amount of water to soil

surface, estimates runoff if any, makes water redistribution in the soil profile (meaning updating the state

SoilWaterContent by layer).

The example above implies, from the point of view of defining the domain, that the “SoilWater”

model/component – in this example, can and should record the irrigation occurrence and the amount actually

applied. As a consequence, the “SoilWater” component will have likely an auxiliary variable, say

AgroManagementIrrigationApplied, which will be an output of the component and consequently of simulation.

The modelling of agricultural management in BioMA is made via the model AgroManagement:

http://www.apesimulator.org/public/tutorials/agromanagement.htm

What about parameters?

In a modelling approach we can identify two types of parameters: those which have no biological meaning, and

those which can have one. We start from the ones which do not have any biological meaning. Let’s consider for

example a model which uses a Weibull distribution. Such function has a parameter, commonly called alpha.

This parameter not only has no biological meaning, but it is defined only when using the Weibull distribution,

and has no meaning if using other probability distribution functions. Consequently, alpha will not be included

in the description of the domain.

http://www.apesimulator.org/public/tutorials/agromanagement.htm

9


The case of parameters with a biological meaning is more articulated. Here we identify two options: One is

when they do not change value during the entire simulation, and the other is when their value changes as a in

response to simulated events or conditions. The second case may require to load specific value(s) during

simulation (e.g. crop parameters in the simulation of a rotation via a generic crop simulator; when a new crop

is planted, new parameter values are loaded). In other cases different modelling approaches are selected (e.g.

SpecificLeafArea in some modelling approaches is a parameter, in others it is computed via simulation, that is,

it may change value during simulation in response to the conditions of simulation). When a quantity is

modelled, it must be included in one of the domain variables collections as above, often having the definition

of a state and a of a rate. Finally, back to the example above, SpecificLeafArea can be both a parameter in a

model class, as described in section Model Units, and a variable as above; in a specific modelling solution it will

be either one according to the choices made building the modelling solution.

Formalizing the description of the domain

One application can be used to store data description, serving also the purpose of facilitating code

development. The application, complete of documentation, is downloadable at:

http://components.biomamodelling.org/components/dcc/

Some of variables discussed in the in the previous examples are screen-shots of the software application that,

at a later stage, will seamlessly allow generating code. In other words, whether the variables to describe the

domain can be saved in various groups using for instance a spreadsheet, the application called DCC – Domain

Class Coder allows declaring and saving variables, and then generate the relevant code as we will see in the

document of Phase 2.

Within a domain, which will correspond to a software component (e.g. MyCropModelLibrary), the application

allows storing the variables and attributes in “groups” (the groups will correspond to classes in the

implementation). Once a list of variables is completed (there will still be the possibility of editing/extending),

the “save XML” button can be used to save definitions as an XML file, which can be reloaded at a later time for

editing or code generation. Summarizing, one XML file per collection of variables, corresponding to States,

Rates, Auxiliary etc.; these XML files will considerably speed up Phase 2.

http://components.biomamodelling.org/components/dcc/

10


Model units This part of the document is about formalizing the discrete units that will be composed building a modelling

solution. In this section, one part of the system to be modelled is considered at the time. For instance, see the

section Describing the domain, it could be “Crop”, or “SoilWater”, or else. In other terms, a part of the system

to be modelled for which the description of the domain, in terms of the quantities to be modelled, was

previously done as described in the previous sections; that quantities will be inputs or outputs of each model

unit.

There is basically no difference in articulating the description of a new process-based model compared to

merely re-implementing it in a component based framework. Τhe procedure and the final result follow the

same guidelines. In the frame of a component-oriented architecture, building a new model consists in making

the discretization of a complex model into simpler units; from the vision of the whole model to obtain the

output of interest, a hierarchical structure is developed, and finally all the needed slots are filled with

modelling approaches. Re-implementing a model requires re-building the possible structure again with a top-

down analysis. As example, a “Crop” modelling solution can be subdivided into “Phenology”,

“LightInterception”, “BiomassFixation” etc., and, further, “Phenology” can be subdivided into

“ThermalResponse” and “Photoperiod”. All of these will be discrete model units, but some will be

compositions of others units.

When the discretization is completed, each model unit will be characterized by a list of inputs, outputs, and

parameters. The meaning given to parameters here is quantities, which do not vary during a run (or vary

because of specific events as discussed already).

What granularity for model units?

There is no unique answer, but a concept is the steering principle: the algorithm(s) which consist a model unit

must be a solution to a specific modelling problem. This makes a difference when comparing such basic model

unit to a mathematical function: a simple evapotranspiration model may be a single equation like a specific

mathematical function, but the former serves to estimate evapotranspiration, whereas the latter is generic.

The first one will have an interface which uses semantically explicit quantities, which are part of a description

of a domain, the latter will have generic both inputs and outputs.

There is no point in isolating in a model unit equations which does not produce an output of interest for the

domain, like an intermediate step of calculations with no biophysical meaning; nobody would reuse it. We

might still isolate specific, generic mathematical functions in a discrete unit because such functions are re-used

multiple times; but this will be a utility library, not a biophysical models library.

Using the concept of the solution to a modelling problem, there could be a “model unit” for

instance estimating Yield, hence including many sub-models. The definition of the units of the

modelling solution will then consist in identifying basic model units, with a top-down approach.

Later such units will be composed to create a model unit which has as main output Yield, but

having behind a clearly articulated structure of single, replaceable, basic model units.

11


A fine-granularity implementation makes maintenance easier, and alternate modelling approaches can be

compared by replacing the original ones. See as example Donatelli et al. (2014).

Simple models

The basic discrete units of model implementation are called Strategies, in the sense of the software design

term. A basic model unit does not make internal use of other model units. Following up the previous example,

“PhotoperiodResponse” can be one of such basic model units. The terms basic models and simple strategies

are synonyms in this document.

Composite models

Composite models use at least one other basic model (of the same component). “Use” in this case means that

such model(s) is called within the composite; the call is hard-coded. Composite models also contain the logic

to use such basic models.

Composite models provide all the outputs of basic models, plus the ones computed by its internal logic.

Parameters of the composite are all the parameters from basic models plus, if any, the ones introduced with

the logic of the composite. Inputs, instead, are all inputs of basic models except the ones which are auto filled

in the composite (see table – example of composite using two basic models).

Model Inputs Outputs Parameters

Basic model 1 Var1 Var2 Par1, Par2

Basic model 2 Var2 Var3 Par3

Composite model Var1 * Var2, Var3, Var4 Par1, Par2, Par3

* Var2 is not an input of the Composite model because it is provided to Basic model 2 by Basic model 1.

Var4 is the additional output computed via the logic of Composite model. In a library containing the models

above, composite and basic models can be used independently; one of the basic models may be replaceable by

another having same output and which would be an alternate way to calculate the same output; one basic

model might be re-used by several composite models.

Composite model may have “switches”, that is a kind of parameters which may enable a specific basic model,

or select among alternate ones. With switches choices are explicitly pre-made, whereas, as discussed when

considering Context models in the following paragraph, model selection can be context-driven at run time.

“Simple models” or “functions”?

The basic difference between a “simple model” and a “function” is that the former has inputs and outputs

which have a precise biophysical meaning. A function, e.g. a logistic function, might be used in many models,

and has input and the response variable which are generic. According to the conceptual model discussed in this

note, the implication is that its public interface will not contain domain objects, instead only the scalars and

vectors which are needed to compute the response. The method to call it will not return a void, instead it will

return a specific type. When discussing the second phase, that is components implementation, functions will

be classes belonging to a library, and they will not share the common interface of all models.

12


Example calculations

For each model unit, basic or composite, example calculations should be provided, at least for basic models.

Such examples are records of values of inputs and parameters, and the corresponding output. Meaningful

records (possibly more than one) will provide numerical values for points which might be critical for the

specific model, such as discontinuities in the response. These example calculations are useful both for

documentation, and for actual software implementations (“unit tests”), with a direct impact on software

quality.

Context models

Context model are a type of composite model. The logic they include, however, has the purpose of selecting

which basic model (or which composite model) should be used. One possible example is a Context model

called EvapoTrannspiration, which uses the Penman-Monteith and the Hargreaves models for estimating

ReferenceEvapotranspiration. Its internal logic will select either one according, for instance, if data of air

relative humidity are provided as inputs at run time.

Model Inputs Outputs Parameters

Basic model 1 Var0, Var1 Var3 Par1, Par2

Basic model 2 Var0, Var2 Var3 Par3

Context model Var0, and Var1 or Var2 Var3, ModelUsed Par1, Par2, Par3

In general, context models provide the same output of a set of basic models implementing alternate

approaches to estimate the same variable; they require the parameters of all the basic models used, because

either basic model could be used at run-time. Context models may accept (as in the case of the table above) a

subset of all inputs. The output will also include the specification of the model used at each call.

The definition of context models is done when the whole set of basic and composite models is defined, as their

availability can be useful to facilitate modelling solutions use in some applications.

13


Examples The examples below show discretization as fine-granularity model units. The case described are implemented

as actual software libraries, but the description below is only meant to present concrete examples of

application of the principles described so far.

Reference evapotranspiration

We use as example the models to estimate reference evapotranspiration according to the FAO approach (Allen

et al., 1998). The composite model, i.e. the Penman-Monteith equation, is then split into a number of simpler

models. Note that some of the basic model units can be re-used by other composite models, or used stand

alone.

arcr

a

ptn

s

r

CVPDKGRs

ET

1

10

Where:

ET0 = reference crop evapotranspiration

(mm d-1

);

= latent heat of vaporization (MJ kg-1

);

s = slope of the saturation vapour pressure-

temperature relationship (kPa °C-1

);

Rn = net radiation (MJ m-2

d-1

);

G = soil heat flux (MJ m-2

d-1

);

Kt = unit conversion factor (86400 s d-1

for ET0 in

mm d-1

);

VPD = vapour pressure deficit of the air (kPa);

= mean atmospheric density (kg m-3

);

Cp = specific heat of the air (MJ kg-1

°C-1

);

ra = aerodynamic resistance;

= psychrometric constant (kPa °C-1

);

rc = canopy resistance.

Simple models Symbol Explanation

DADSmith Atmospheric density

DAVPRHFAO ea Actual vapour pressure

DSVPTetens es Saturation vapour pressure

DSVPDTetens s Slope of saturation vapour pressure deficit

DPsychrometric Constant

Psychrometric constant

DARFAO ra Aerodynamic resistance

DVPDFAO VPD Vapour pressure Deficit (requires es and ea)

DNRFAO Rn Net radiation

Composite model

DRETFAO56 ET0 Reference evapotranspiration

The WOFOST crop model

This second example shows the discretization of the WOFOST model – the crop part (Confalonieri et al., 2012)

into units of fine-granularity, and their composition; the first box from the left represents the highest

aggregation, which actually serves as entrance point for the modelling solution WOFOST-Crop. Light blue

boxes are composite models, whereas orange boxes are utilities.

Each model unit will is characterized by inputs, outputs, and parameters, as described above.

14


Preparing documentation for the next phase The next phase is creating model components. If the results of the work described in this document must be

communicated to a third party which will do the actual implementation – i.e. if the modeller does not what to

experience directly how doable is making it! – a diagram like the one above, and the XML files of the variables

declaration collections, must be integrated with information which will regard each of the boxes of a diagram

like the one above; an example is shown below only to provide a synthesis of the information required for the

following phase. Note that equations can be missing at this stage; it will become clear in phase 2 why are not

needed at this point.

Be aware that each of the variables of the example are assumed to be declared previously in the

description of the domain (first part of this document).

15


Name

Description

Reference

TimeStep(s)

Contact

Type:

Inputs (from domain collections)

Outputs (from domain collections)

Parameters Max Min Default Units

Equations

Example calculations Input1 Input2 Input3 Param1 Param2 Output1 Output2 Output3

Associated models

Description

Simple Composite Context

16


Composition

Once the domain to be modelleld is subdivided into subdomains, the different target components are defined.

Input-output connections between different models can then be implemented via links. Within a component

based implementation of a modelling solution, the links – mostly within time step, can be of three types:

1. Between models within components, hard-coded (Composite models);

2. Between models within components, external to the code of the component;

3. Between models/data sources in different components.

In principle, type 2 should be avoided. If a link between two models of the same component has a “modelling

meaning”, both for original developers and for third parties users it makes sense to make the link more easily

reusable building a link of type 1, that is, implementing a composite model which adds a further option for

component reuse.

In this section the focus on links of type 3. Examples of such links were made already in the introduction (Phase

2: Creating model components). Going back to the example: link PotentialPlantWaterUptake to

SoilPlantAvailableWater to estimate ActualPlantWaterUptake. This connection must actually be implemented

as two separate links:

The Crop component estimates a demand; the Soil component estimates the availability.

PotentialWaterUptake and ActualWaterUptake are variables defined in the domain classes of both

components (not necessarily using the same names), where are used by specific models.

Each link has three features:

1. The input – output connections to variables, which implies direction;

2. The timing of execution (in the example, link 2 must be executed after link 1);

3. A possible need for units conversion (no other logic allowed in a link).

Feature 3 is likely to be needed when using components from third parties.

Specifying links, which is not directly needed for Phase II – components, and specific for Phase III –

composition, impacts also on the definition of the domain variables, and is part of the definition of the

conceptual model.

Crop component

PotentialWaterUptake (rate)

ActualWaterUptake (rate)

Soil component

PotentialWaterUptake (rate)

ActualWaterUptake (rate)

link 1

link 2

17


Credits The research leading to these results has received funding from the European Community’s Seven Framework

Programme-FP7 (KBBE.2013.1.4-09) under Grant Agreement No. 613817.2013-2016. Modelling vegetation

response to EXTREMe Events (MODEXTREME, modextreme.org).

History of the document

Author Date Comments

Marcello Donatelli 12/09/2014 Version 1.0

Ioannis N. Athanasiadis 30/9/2014 Comments and edits to version 1.0

Marcello Donatelli 31/10/2014 Revision; final version 1.0

Marcello Donatelli 20/12/2014 Paragraph on agro-management, glossary

Marcello Donatelli 13/01/2015 Composition; version 1.1

Marcello Donatelli 26/10/2015 Simple models and functions; edits to version 1.1

18


Glossary

Basic model The smallest model unit, often a single process (synonymous: simple strategy)

Component A discrete unit of code which includes basic, composite, and context models units sharing the same description of the domain

Composite model A model unit which uses several basic models (synonymous: composite strategy)

Context model A model unit which uses several basic or composite models, inclusive of the logic to select model based on the context at run-time (synonymous: context strategy)

Composition A set of components and links between them to create a modelling solution, inclusive of the infrastructure to run time-dependent simulation

Domain class A group of variables including the description, units, minimum, maximum and default values

Modelling solution See Composition. Often the term model is used instead of modelling solution, ignoring that an operational model is, in fact, a composition of several models built for a specific purpose.

Parameter A model input which either does not change value during simulation, or changes value in response to specific events

Type [Programming languages] The full name of a class. Full name means that it includes the namespace (e.g. MyInstitution.SoilWater.Irrigation, were “Irrigation” is the name of a class in a software component with MyInstitution.SoilWater as namespace)

19


References Allen R.G., L.S. Pereira, D. Raes, M. Smith Crop evapotranspiration: Guidelines for computing crop water

requirements. [Report]. - [s.l.] : Irr. & Drain. Paper 56. UN-FAO, Rome, Italy., 1998.

Confalonieri R., Bregaglio, S., Stella, T., Negrini, G., Acutis, M., Donatelli, M. An extensible, multi-model

software library for simulating crop growth and development [Conference] // Proceedings of the 6th biannual

meeting of the International Environmental Modelling and Software Society. - Liepzig : [s.n.], 2012.

Donatelli M., Bregaglio S., Confalonieri R., De Mascellis R., Acutis M. A generic framework for evaluating

hybrid models by reuse and composition – A case study on soil temperature simulation. [Journal] //

Environmental Modelling & Software http://dx.doi.org/10.1016/j.envsoft.2014.04.011 . - 2014.

Donatelli M., Rizzoli A. A design for framework-independent model components of biophysical systems

[Conference] // Proceedings of the iEMSs Fourth Biennial Meeting.. - Barcelona :

http://www.iemss.org/iemss2008/uploads/Main/Vol2-iEMSs2008-Proceedings.pdf, 2008. - Vol. II. - pp. 727-

734.

VV.AA. The BioMA framework [Online] // Wikipedia. - 2013. - https://en.wikipedia.org/wiki/BioMA.

implementing/re-implementing a simulation model using a … · implementing/re-implementing a...

Documents