Model Layer. Reference Documentation

Transcription

1 Model Layer Reference Documentation

2 Release Issue Date 1 1 March 2015 Copyright European Union, Reproduction is authorised, provided the source is acknowledged, save where otherwise stated. Where prior permission must be obtained for the reproduction or use of textual and multimedia information (sound, images, software, etc.), such permission shall cancel the above mentioned general permission and shall clearly indicate any restrictions on use. Disclaimer On any of the MARS pages you may find reference to a certain software package, a particular contractor, or group of contractors, the use of one or another sensor product, etc. In all cases, unless specifically stated, this does not indicate any preference of the Commission for that particular product, party or parties. When relevant, we include links to pages that give you more information about the references. Feel free to contact us, in case you need additional explanations or information. 2 Model Layer Documentation

3 Contents 1 About this document About the Model Layer The BioMA three layers architecture Purposes of the Model layer Model Layer Applications Model Layer libraries overview Model Components Design and Use Components Design Summary Design Patterns used Main Interfaces IDomainClass Interface VarInfo Class IStrategy Interface Model Layer Documentation 1

4 CONTENTS 2 Model Layer Documentation

5 About this document 1 This document describes the BioMA Model Layer, one of the architectural layers of the BioMA Framework and is targeted to advanced users/modelers who want to create a new component. Tip: This document describes how the Model Layer is designed. It is not aimed to provide instructions on how to create a component. For step-by-step instructions, see the Tutorial - How to create a component, which you can download here Before reading this document, it is suggested to read these documents about the BioMA Framework: BioMA Framework User Guide, which you can find here bioma.jrc.ec.europa.eu/components/componentstools/bioma/ WebHelp/index.htm The topics are organized as follows: Topic About the Model Layer on page 5 Model Components Design and Use on page 13 Description What the Model layer is with respect to the BioMA framework architecture Main purposes of the Model layer Summary of the components design Design patterns used Main Interfaces of the Model Layer Model Layer Documentation 3

6 1 ABOUT THIS DOCUMENT 4 Model Layer Documentation

7 About the Model Layer 2 This chapter is organized into the following sections: The BioMA three layers architecture on page 6 Purposes of the Model layer on page 7 Related topics: Model Components Design and Use on page 13 Model Layer Documentation 5

8 2 ABOUT THE MODEL LAYER The BioMA three layers architecture The BioMA modelling framework simulation system has been discretized in layers, each with its own purposes. Tip: For further information of the architecture and the components of the BioMA framework, please refer to the Web-based User Guide. The following diagram shows the framework layers. The model layer is where fine granularity models are implemented as discrete units. The composition layer is where basic models from different components are composed to build a modelling solution. (See bioma.jrc.ec.europa.eu/documentation/ Composition%20Layer%20Documentation.pdf). The configuration layer is where information and data (configuration items) can be added to a modelling solution to make it usable in a specific context. (See Configuration%20Layer%20Documentation.pdf). See also: Purposes of the Model layer on page 7 6 Model Layer Documentation

9 PURPOSES OF THE MODEL LAYER Purposes of the Model layer In the modeling solution development process, the Model Layer is the starting point for a modeler/programmer. He/she creates a modeling solution using SCC, DCC, and other Model Layer tools (see Model Layer Applications on page 8). Each model is implemented as a strategy class which: Contains the algorithm/equation of the model Contains the definition of its own parameters Implements the test of pre and post conditions (inputs/params/ outputs validation) May use other classes (strategies) sharing the same interface Implements a scalable logging system Exposes the list of its inputs, outputs, simulation options, and parameters Exposes instances of concepts defined in a reference ontology Each variable used by the models (input, output or parameter) is represented by a set of properties detailing a description, max/min/ default values, units, value type. (VarInfo class) Each set of related variables is contained in a domain class which represents a state of the simulated process (e.g. State of a plant) All the strategies of the same library (component) share the same domain classes, since the models share the same simulated physical domain. Models are implemented using structural and behavioral design patterns which foster extensibility and reusability: Composite (facilitating the use of composite and simple strategies) Strategy (allowing a context specific selection of models at run time) Bridge (allowing the replacement of model components) For further information: Model Layer Applications on page 8 Model Layer libraries overview on page 8 Model Layer Documentation 7

10 2 ABOUT THE MODEL LAYER Model Layer Applications Currently, the applications that use the model layer are: Application What it is used for See the Help online Model Component Explorer (MCE) Domain Class Coder (DCC) Strategy Class Coder (SCC) Model Parameter Editor (MPE) Explore component interfaces and domain classes. Identify inputs, parametes, outputs, and associated models, as well export information as XML files. Generate the code of domain classes and parameter classes. Generate the code of model classes, that is the strategies. View and edit the value of the model parameters. components/componentstools/mce/ WebHelp/index.htm components/componentstools/dcc/ WebHelp/index.htm components/componentstools/scc/ WebHelp/index.htm components/componentstools/mpe/ WebHelp/index.htm Model Layer libraries overview A rich library of biophysical models is already implemented under the BioMa framework. All the models of this library and their documentation are available online through the BioMA component portal and can be freely re used by any modeler working with the BioMA platform. The following schema shows the BioMA Model Layer libraries currently available: 8 Model Layer Documentation

11 PURPOSES OF THE MODEL LAYER Figure 1 - BiOMA Model Layer Libraries Description: The Plant library is made of modular strategies that combined together allow to replicate the behavior of models such as CROPSYST, WOFOST, WARM, CANEGROW or STICS. The Weather library provides algorithm related to the computation of weather variables that influence the plant growth. The Stress library deals with the stress that can affect the growth of the plants, should they be biotic or abiotic. The Soil library offers different way to model the evolution of the water, nitrogen and carbon content of the soil. The Agriculture Management library implements the management events in a simulation model. The following table summarizes the main components currently available in the BioMA component portal: Model Layer Documentation 9

12 2 ABOUT THE MODEL LAYER Component AbioticDamage AgroManagement AirTemperature Blast ClimIndices CropML Description JRC.IPSC.MARS.Crop.AbioticDamage is a software component implementing several approaches for the simulation of abiotic damages affecting crop. Models are implemented using the strategy pattern, with a fine granularity. The models currently implemented belongs to six categories: lodging, frost, cold induced spikelet sterility, heat induced spikelet sterility, ozone and salinity. AgroManagement is a software component to implement management events in a simulation model. It formalizes the decision making process via models called rules, and it formalizes the drivers of the implementation of the impact on the biophysical system via set of parameters encapsulated in data types called impacts. The component can be extended without recompilation, both as rules and as impacts. The information on the biophysical system is passed via a data type called StatesAgroMan; states also can be extended. AirTemperature is a component containing routines to generate longterm series of air temperature values using existing daily or monthly minimum and maximum temperature records. Alternative approaches are implemented for generating either daily values of maximum and minimum air temperature, or hourly values. The dew point temperature, that is the temperature to which the air needs to be cooled to make the air saturated, is also estimated. BlastDisease is a daily time step component for the simulation of the development of blast disease on rice crop starting form meteorological data. It considers both the pathogen growth and the interactions between the pathogen and the crop development. ClimIndices is a component containing routines to calculate weather indicators from multi year series of daily weather data. Basic indicators are computed as simple statistics on weather inputs (yearly series of daily precipitation, maximum and minimum air temperatures, incoming solar radiation, and reference evapotranspiration). Other indicators are derived, grouped into six classes: dates, counts, thermal sums, water, waves, indices. JRC.IPSC.MARS.Crop.CropML is a software component implementing several approaches to model crop development and growth. Models are implemented using a fine granularity, and they are also used in composite structures which can used as simulation models in applications. The models currently being implemented using this criterion are CropSyst, WARM and WOFOST. 10 Model Layer Documentation

13 PURPOSES OF THE MODEL LAYER Component Diseases EvapoTranspiration LeafWetness PTF Rain SolarRadiation Wind Description JRC.MARS.Diseases.Airborne is a software framework containing components to estimate the impacts of plant disease epidemics on plant growth and yield. It is specifically aimed at scenario analysis and developed to be generic and coupled to a crop growth model. It consists of four components: DiseaseProgress, to simulate epidemic development in function of meteorological variables and host resistance InoculumPressure, to simulate initial conditions for the epidemic development ImpactsOnPlants, to provide diverse kind of approaches for yield loss simulation AgroManagementDisease, to simulate the impact of agromanagement practices on pathogen populations ET is a cross platform component containing routines to estimate daily and hourly values of evapotranspiration from the reference surface, according to alternative approaches. LeafWetness is a software library containing different models to estimate hourly values of leaf wetness according to alternative approaches. Leaf wetness duration is a driving variable in epidemiological models for simulating risk of yield losses due to plant diseases. It is strictly related to the epidemiology of many important crops, so its modelization is essential for the forecasting of the development rates of plant diseases and, consequently, for crop protection. PTF (PedoTransfer Functions) is a software component to estimate both soil water content and saturated hydraulic conductivity by means of alternative pedotransfer functions. Rain is a cross platform component containing routines to generate long term series of precipitation values using parameters from existing daily or monthly precipitation records. Precipitation includes the amount of rainfall and snowfall. GSRad is a cross platform component containing routines to calculate daily and hourly values of extra terrestrial and ground level global solar radiation. Wind is a component containing models to generate long term series of wind speed values using parameters from existing wind speed records. See also: The BioMA three layers architecture on page 6 Model Layer Documentation 11

14 2 ABOUT THE MODEL LAYER 12 Model Layer Documentation

15 Model Components Design and Use 3 This chapter is organized into the following sections: Components Design Summary on page 14 Design Patterns used on page 15 Main Interfaces on page 16 Model Layer Documentation 13

16 3 MODEL COMPONENTS DESIGN AND USE Components Design Summary The Model Layer was developed by Donatelli et al. (CRA institute) following a set of software design patterns to maximize both reusability and openness of the code and to increase the transparency and the traceability of performances of the modelling solutions being built compared to legacy code available. Note: The following is an excerpt from the paper Donatelli and Rizzoli (Donatelli, M., Rizzoli, A., A Design for Framework-Independent Model Components of Biophysical Systems. ), which summarizes the requirements identified to build re-usable components, and which are matched by the design proposed and implemented. Design requirements The re usability of software components can be enhanced by addressing the following requirements: The component must target the solution of a sufficiently widespread modeling problem The published interface of the component must be well documented and it must be consistent The configuration of the component should not require excessive preexisting knowledge and help should be provided in the definition of the model parameters The model implemented in the component should be extensible by third parties The dependencies on other components should be limited and explicit The behavior of the component should be robust, and degrade gracefully, raising appropriate exceptions The component behavior should be traceable and such a trace should be scalable (browsable at different debug levels) The component software implementation should be made using technologies with a widespread adoption. 14 Model Layer Documentation

17 DESIGN PATTERNS USED Design Patterns used The architecture of Model Layer's components is based on four different software design pattern in order to implement the desirable features extensibility and modularity The keystone pattern used is the Composite pattern. Different types of model units, that is, simple strategies and composite strategies, implement the same interface (e.g., IStrategyComponent interface, where 'Component' is the name of the component). This means that composite strategies are associated with simple strategies and they implement the same operations (i.e., a composite strategy calls the methods specified in the interface also for associated strategies). Thanks to this, composite and simple strategies are treated in the same way and can be accessed through the same API method. From the modelling point of view, the software design can be seen as an implementation of the Transparent Façade pattern; composite strategies offer a unique entrance to layers of modelling, hiding the complexity behind them but preserving a robust, modular structure. Simple strategies are still accessible. A third type of model unit, the context class, is defined by imposing the implementation of the same IStrategyComponent interface. Context classes are defined in the pattern Strategy; in a context class decisions on the strategies to be used at run time (simple or composite) are taken based on a specific model, responding to the context of operation. A typical use of such context classes is the selection of the appropriate strategy based on the inputs available in the instance of the domain class (classes). Finally, by keeping interfaces, domain classes, and the component API class in one single component, and all model units (simple and composite strategies, contexts) in a different one, the Bridge pattern is implemented. This pattern de couples the abstraction (data structures, methods declaration) from the implementation (models). In fact, a client will have a dependency on the data and interface component, and no dependency on the model component. This allows both easy replaceability of the latter, and the extensibility to multiple model components without the need of recompiling the client. Model Layer Documentation 15

18 3 MODEL COMPONENTS DESIGN AND USE Main Interfaces This section describes the main interfaces of the Model Layer: IDomainClass Interface on page 16 VarInfo Class on page 17 IStrategy Interface on page 18 IDomainClass Interface Interface implemented by domain classes. Domain classes are the container of the model's variables (input, outputs of the model's algorithms). Model's variables are the public properties of the domain class. Domain classes can be automatically generated using the DCC (Domain Class Coder) tool of the BioMA Framework. See bioma.jrc.ec.europa.eu/components/componentstools/dcc/webhelp/ index.htm. Existing domain classes can be analyzed using the MCE (Model Component Explorer) tool of the Bioma framework. See bioma.jrc.ec.europa.eu/components/componentstools/mce/webhelp/ index.htm The table below shows the main method of the IDomainClass interface: Icon Member Description ClearValues Clears the values of the properties of the domain class. Returns true if the method succeedes. This operation should be implemented by using the GetConstructingString method of the VarInfoValueType related to the type of the property (e.g. new double[3] for a double array of size 3). If the GetConstructingString method returns null, the default value for the type of the property should be used (e.g '0' for numbers, 'the empty string' for strings, etc.). The table below shows the main properties of the IDomainClass interface: Icon Member Description Description Description of the class (Inherited from IAnnotatable). 16 Model Layer Documentation

19 MAIN INTERFACES Icon Member Description PropertiesDescription URL Returns the descriptions (reflection's PropertyInfo objects of the public properties of the domain class). The keys of the dictionary are the properties names. The URL of the class metadata (Inherited from IAnnotatable.) VarInfo Class The class VarInfo represents a variable (input/output or pararameter of a strategy). The type of the value of the variable is defined by the ValueType property. It extends the IVarInfo interface. The table below shows the main methods of the VarInfo class. Icon Member Description VarInfo Equals(Object) Equals(VarInfo) Finalize GetHashCode GetType IsTypeCorrect MemberwiseClone ParseValueType ToString Initializes a new instance of the VarInfo class. Calls Equals(VarInfo) (Overrides Object.Equals(Object). Returns true if other is a VarInfo and it has the same Name as this, false otherwise. Allows an Object to attempt to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.) Returns the hashcode of the Name. (Overrides Object.GetHashCode().) Gets the Type of the current instance. (Inherited from Object.) Returns true if the Type of the CurrentValue is consistent with the variable ValueType. Creates a swallow copy of the current Object. (Inherited from Object). Parses the value type contained in the source argument and set it on the destination parameter definition. Returns a String that represents the current Object. (Inherited from Object). The table below shows the properties of the VarInfo class: Model Layer Documentation 17

20 3 MODEL COMPONENTS DESIGN AND USE Icon Member Description CurrentValue DefaultValue Description Id MaxValue MinValue Name Size Units URL ValueType VarType Value at run time Default value (if applicable) Variable description VarInfo identifier Maximum value allowed (if applicable) Minimum value allowed (if applicable) Variable name Size of the array of the list if ValueType property requires a size (e.g. arrays) Units of measure of the variable Variable metadata URL Variable value type (typesafe enumeration VarInfoValueTypes) Variable type (enumeration EC.JRC.MARS.ModelLayer.Core.VarInfo.Type) The table below shows the main event of the VarInfo class: Icon Member Description CurrentValueSet Event thrown when the CurrentValue is set IStrategy Interface Interface implemented by Strategy classes. Strategies are the container of the model's logics. Each sub model in the Bioma framework is implemented as a strategy class which: Contains the algorithm/equation of the model Contains the definition of its own parameters Implements the test of pre and post conditions (inputs/params/ outputs validation) May use other classes (strategies) sharing the same interface Implements a scalable logging system Exposes the list of its inputs, outputs, simulation options, and parameters Exposes instances of concepts defined in a reference ontology 18 Model Layer Documentation

21 MAIN INTERFACES Each variable used by the strategy (input, output or parameter) is represented by a set of properties detailing a description, max/min/ default values, units, value type (VarInfo class). Those variables are managed throught the ModellingOptionsManager object of the strategy. Each set of related variables is contained in a domain class which represents a state of the simulated process (e.g. State of a plant). All the strategies of the same library (component) share the same domain classes, since the models share the same simulated physical domain. The strategy design pattern allows a context specific selection of models at run time. Strategies can be automatically generated using the SCC (Strategy Class Coder) tool of the Bioma framework. See components/componentstools/scc/webhelp/index.htm Existing strategies can be analyzed using the MCE (Model Component Explorer) tool of the Bioma framework. See bioma.jrc.ec.europa.eu/components/componentstools/mce/webhelp/ index.htm The following table shows the main methods (and extension methods) of the IStrategy Interface: Icon Member Description GetStrategyDomainClassType AllPossibleAssociatedSTrategies AllPossibleInputs AllPossibleOutputs AllPossibleParameters Associated Strategies Inputs Returns the types of the domain classes used by the strategy. Returns all the possible associated classes of the strategy, not relying on the value of the strategy switches. (Defined by IStrategyExtensionMethods). Returns all the possible inputs of the strategy, not relying on the value of the strategy switches. (Defined by IStrategyExtensionMethods). Returns all the possible outputs of the strategy, not relying on the value of the strategy switches. (Defined by IStrategyExtensionMethods.) Returns all the possible parameters of the strategy, not relying on the value of the strategy switches (Defined by IStrategyExtensionMethods.) Returns the description of the associated strategies depending on the switches values. (Defined by IStrategyExtensionMethods.) Returns the description of the input properties depending on the switches values. (Defined by IStrategyExtensionMethods.) Model Layer Documentation 19

22 3 MODEL COMPONENTS DESIGN AND USE Icon Member Description Outputs Parameters SetParameterValueThroughReflect ion Returns the description of the output properties depending on the switches values. (Defined by IStrategyExtensionMethods.) IStrategy extension method. Returns the parameters of the strategy depending on the switches that the strategy allows (if any). If the strategy has no switches the returned parameters set will be always the same. (Defined by IStrategyExtensionMethods.) Set the value to the property of the strategy by using the reflection to get the property (Defined by IStrategyExtensionMethods). The table below shows the main properties of the IStrategy Interface: Icon Member Description Description Domain IsContext ModellingOptionsManager ModelType PublisherData TimeStep URL Description of the class. (Inherited from IAnnotatable). Model domain definition. True if the strategy is a context strategy (the strategy uses specific models according to the context given by the inputs provided), false otherwise. Returns the ModellingOptionsManager of the strategy. Model type definition. Publisher data associated to the strategy Time step definition. The URL of the class metadata. (Inherited from IAnnotable). 20 Model Layer Documentation