Welcome to PyCrop2ML Documentation

Contents .. _pycropml:

CropML documentation

Module description

What is PyCrop2ML?

PyCrop2ML is a free, open-source library for defining and exchanging CropML models.It is used to generate components of modeling and simulation platforms from the CropML specification and allow component exchange between different platform.
It allows to parse the models described in CropML format and automatically generate the equivalent executable Python, java, C#, C++ components and packages usable from existing crop simulation platform.

What is Crop2ML ?

CropML is a XML-(JSON-)based language used to represent different biological processes involved in the crop models.
CropML project aims to provide common framework for defining and exchanging descriptions of crop growth models between crop simulation frameworks.
Objectives

Our main objectives are:

  • define a declarative language to describe either an atomic model or a composition of models
  • add semantic dimension to CropML language by annotation of the models to allow the composition of components of different platforms by using the standards of the semantic web
  • develop a library to allow the transformation and the exchange of CropML model between different Crop modelling and simulation platform
  • provide a web repository enabling registration, search and discovery of CropML Models
  • facilitate Agricultural Model Exchange Initiative
Context
Nowadays, we observe the emergence of plant growth models which are built in different platforms. Although standard platform development initiatives are emerged, there is a lack of transparency, reusability, and exchange code between platforms due to the high diversity of modeling languages leading to a lack of benchmarking between the different platforms.
This project aims to gather developers and plant growth modelers to define a standard framework based on the development of declarative language and libraries to improve exchange model components between platforms.
Motivation
Our motivation is to:
  • Strengthen the synergy between crop modelers, users and scientific researchers
  • Facilitate model intercomparison (at the process level) and model improvement through the exchange of model components (algorithms) and code reuse between platforms/models.
  • Bridge the gap between ecophysiologists who develop models at the process level with crop modelers and model users and facilitate the integration in crop models of new knowledge in plant science (i.e. we are seeking the exchange of knowledge rather than black box models).
  • Increase capabilities and responsiveness to stakeholder’ needs.
  • Propose a solution to the AgMIP community for NexGen crop modeling tools.
Vision
  • Facilitate the development of complex models
  • Use modular modelling to share knowledge and rapidly develop operational tools.
  • Reuse model parts to leverage the expertise of third parties;
  • Renovate legacy code.
  • Realize the benefit of sharing and complementing different expertise.
  • Promote model sharing and reuse

CropML Description

In CropML, a model is either a model unit or a composition of models. A ModelUnit represents the atomic unit of a crop model define by the modelers. A model composition is a model resulting from the composition of two or more atomic model or composite models.
These models have a specific formal definition in CropML.
Formal definition of a Model Unit in CropML
The structure of a Model Unit in CropML MUST be conform to a specific Document Type Definition named ModelUnit.dtd .
So a Model Unit CropML document is a XML document well-formed and also obeys the rules given in the ModelUnit structure.
This structure MAY be described by the below tree:
_images/modelunit.png
Element Description
ModelUnit
The root of an atomic model in CropML which make the difference from a composite model.
Description
some basic information related to the name of the model, its authors and others elements used to reference it.
Inputs
A list of inputs characterized by their names, initial states, the range of values and others. Its input variables are related to climate, soil and cropping system
Outputs
A list of outputs defining the processes involved, the variables whose dynamics we want to observe.
Algorithm
The description of the behaviour of the model made by the mathematical relationship between the inputs and the outputs with some control structure.
Parametersets
Some sets of parameters which are invariant and used for the simulation of the models.
Testsets
Set of model configuration used to compare estimated and desired outputs .
In the next, we define the major elements of a CropML model unit.
ModelUnit element
An atomic model in CropML is declared with <<ModelUnit>> element, the usual root of CropML ModelUnit document.
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE ModelUnit PUBLIC "-//SIMPLACE/DTD SOL 1.0//EN" "https://raw.githubusercontent.com/AgriculturalModelExchangeInitiative/xml_representation/master/ModelUnit.dtd">
<ModelUnit modelid=" " timestep=" " name=" " version="">
        ....
</ModelUnit>
This element MUST contain a Description, an Algorithm, Parametersets and Testsets elements and MAY optionally have Inputs and Outputs elements. The restriction of the length of different lists is not imposed.
ModelUnit element MUST have an modelid and name attributes which are used to reference an atomic model. It MUST also contain a timestep attribute to define the temporality of the model and a version attribute for each version of the model.
Description element

This element gives the general information on the model and is composed by a set of character elements. It MUST contain Title, Authors, Institution and abstract elements and MAY optionally contain URI and Reference elements.

<ModelUnit modelid=" " timestep=" " name=" " version =" ">
        <Description>
                <Title>title</Title>
                <Authors>authors</Authors>
                <Institution>institution</Institution>
                <URI>uri</URI>
                <Abstract><![CDATA[abstract]]></Abstract>
        </Description>
        ...
</ModelUnit>
Inputs elements

The inputs of Model are listed inside an XML element called Inputs within a dictionary structure composed by their attributes which declarations are optional(default, max, min, parametercategory, variablecategory and uri) or required(name, datatype, description, inputtype, unit ) and their corresponding value. Inputs element MUST contain one or more Input elements.

<ModelUnit modelid=" " timestep=" " name=" " version =" ">
   ...
   <Inputs>
      <Input name=" " description=" " parametercategory=" " datatype=" " min=" " max=" " default=" " unit=" " uri="" inputtype=" "/>
      <Input name=" " description=" " parametercategory=" " datatype=" " min=" " max=" " default=" " unit=" " uri=" " inputtype=" "/>
      ...
   </Inputs>
   ...
</ModelUnit>
  • The required datatype attribute is the type of input value specified in default (the default value in the input), min (the minimum value in the input) and max (the maximum value in the input). It MAY be one type of the set of types used in the existing crop modeling platform.
  • The inputtype attribute makes it possible to distinguish the variables and the parameters of the model. So it MUST take one of two possible values: parameter and variable.
  • The parametercategory attribute defines the category of parameter which is specified by one of the following values: constant, species, soil and genotypic.
  • The variablecategory defines the category of variable depending on whether it is a state, a rate or an “auxiliary” variable. State variable characterize the behavior of the model and rate variable characterizes the changes in state variables.
Outputs element

The outputs of Model are listed inside an XML element called Outputs within a dictionary structure composed by their attributes which declarations are:

  • optional(variabletype and URI)
  • required(name, datatype, description, unit, max and min )
  • and their corresponding value

Outputs MUST contain zero or more output elements.

<ModelUnit modelid=" " timestep=" " name=" " version =" ">
   ...
   <Outputs>
      <Output name=" " description=" " datatype=" " min=" " max=" "  unit=" " uri=" "/>
      <Output name=" " description=" " datatype=" " min=" " max=" "  unit=" " uri=" "/>
      ...
   </Outputs>
   ...
</ModelUnit>
The definition of different attributes is same as Input’s attributes.
Algorithm element
The Algorithm element defines the building block of CropML model unit and shows the computational method to determine the outputs from the inputs.
It consists of a set of mathematical equations (relation between inputs), loops and conditional instructions which are well structured in a specific language, the algorithm’s attribute.
<ModelUnit modelid=" " timestep=" " name=" " version =" ">
   ...
   <Algorithm language =""><![CDATA[
      ...
      ]]>
   </Algorithm>
   ...
</ModelUnit>
Parametersets element
Parametersets element contains one or more Parameterset elements that define the different ways of setting the model. Each Parameterset element MUST have name and description attributes that respectively represents the name and the description of each setting.
The different parameterset MUST contain a list of Param elements that show in attribute the name of the parameter (an input which inputtype equals parameter) and the fixed value of this one.
<ModelUnit modelid=" " timestep=" " name=" " version =" ">
    ...
    <Parametersets>
       <Parameterset name="" description="" uri = ""/>
       <Parameterset name="" description="" >
          <Param name="">value</Param>
          <Param name="">value</Param>
          ...
       </Parameterset>
       ...
    ...
 </ModelUnit>
Testsets element
Testsets element contains one or more Testset elements that define the different run for evaluating the outputs of the model.
Each Testset element MUST have name, description and parameterset attributes that respectively represents the name, the description of each run and the name of the parameterset related to the Testset. This one allow to retrieve the name and the value of different parameters includes in this parameterset.
The different Testset MUST contain a list of InputValue and OutputValue elements corresponding respectively to the values of inputs used in the run and the values of Outputs that will be asserted.
<ModelUnit modelid=" " timestep=" " name=" " version =" ">
   ...
   <Testsets>
      <Testset name="" parameterset = "" description="" uri = ""/>
      <Testset name="" parameterset = "" description="" >
         <Test name="">
            <InputValue name="">value</InputValue>
            ...
            <OutputValue name="" precision ="">value</OutputValue>
            ...
         </Test>
         ...
      </Testset>
      ...
  </Testsets>
  ...
</ModelUnit>
Formal definition of a Composite Model in CropML
A Composite Model CropML is an assembly of processes which are described by a set of model units or a composition of models. Given a composite model is a model, this one has also inputs, outputs and internal state which describe the orchestration of different independent models composed.
The structure of a Composite Model in CropML MUST conform to a specific Document Type Definition named ModelComposition.dtd .
The composition is represented as a directed port graph of models:
Vertices are the different models that form the composition.
Ports are the inputs and outputs of each model.
Edges are directed and connect one output port to an input port of another model.
It contains in addition to all Elements of a model unit a Composition Element for the composition of models.
This structure MAY be described by the below tree:
user/images/modelcomposition.png
In the next, we define the major elements of a CropML model unit.
Inputs element

It MUST contain one or more input element which provide a set of independent models entries. If two or more input variables of independent models are the same (same unit, interval, description) a link should be made to one input variable of the composite model.

Outputs element

It MUST contain one or more output element which provide a set of independent models outputs or a result of a combination of models .

Composition element

It’s a list of models elements which contains a list of links elements. Link provides the mechanism for mapping inputs declared within one modelUnit to output in another modelUnit, allowing information to be exchanged between the various atomic models in the composite model.

Algorithm element

The implementation differs from the platform:

  • Discrete Events Models and Formalisms (RECORD)
  • Actor model framework (OpenAlea)
  • A sequence of algorithmic instructions witch implement the control flow (BIOMA)

PyCropML User Guide

Version:0.1.1
Release:0.1.1
Date:Dec 11, 2019

This reference manual details functions, modules, and objects included in OpenAlea.Core, describing what they are and what they do. For a complete reference guide, see core_reference.

Warning

This “Reference Guide” is still very much in progress. Many aspects of OpenAlea.Core are not covered.

Manual

Note

The following examples assume you have installed the packages and setup your python path correctly.

Installation
conda install -c openalea pycropml

or

python setup.py install
Overview of the different classes

src

pycropml package
Subpackages
pycropml.interface package
Submodules
pycropml.interface.design module
pycropml.interface.version module
Module contents
pycropml.transpiler package
Subpackages
pycropml.transpiler.generators package
Submodules
pycropml.transpiler.generators.checkGenerator module
pycropml.transpiler.generators.csharpGenerator module
pycropml.transpiler.generators.docGenerator module
pycropml.transpiler.generators.fortranGenerator module
pycropml.transpiler.generators.javaGenerator module
pycropml.transpiler.generators.openaleaGenerator module
pycropml.transpiler.generators.pythonGenerator module
pycropml.transpiler.generators.recordGenerator module
<vle_project version=”1.1.x” date=”2012-Oct-03 13:01:13” author=”Eric Casellas”>
<structures>
<model width=”2184” height=”1280” name=”2CV_parcelle” type=”coupled”>
<submodels>
<model observables=”vueDecision” conditions=”condDecFSA” dynamics=”dynDecFSA” debug=”false” width=”100” height=”75” x=”132” y=”26” name=”Decision” type=”atomic”></model> <model width=”100” height=”165” x=”316” y=”127” name=”2CV” type=”coupled”></model>

</submodels> <connections> </connections>

</model>

</structures> <dynamics> </dynamics> <experiment name=”2CV_parcelle”> </experiment>

</vle_project>

pycropml.transpiler.generators.simplaceGenerator module
pycropml.transpiler.generators.siriusGenerator module
Module contents
pycropml.transpiler.lib package
Module contents
pycropml.transpiler.rules package
Submodules
pycropml.transpiler.rules.csharpRules module
pycropml.transpiler.rules.fortranRules module
pycropml.transpiler.rules.generalRule module
class pycropml.transpiler.rules.generalRule.GeneralRule[source]

Bases: object

” Abstract class of Rules

pycropml.transpiler.rules.javaRules module
pycropml.transpiler.rules.pythonRules module
pycropml.transpiler.rules.sqRules module
Module contents
Submodules
pycropml.transpiler.Parser module
pycropml.transpiler.api_transform module
pycropml.transpiler.ast_transform module
pycropml.transpiler.builtin_typed_api module
pycropml.transpiler.checkingModel module
class pycropml.transpiler.checkingModel.Checking[source]

Module used to check units validity in model equation based on model xml files. This checking can also use for python code with metadata

pycropml.transpiler.codeGenerator module
pycropml.transpiler.env module
class pycropml.transpiler.env.Env(values=None, parent=None)[source]
child_env(values=None)[source]
pycropml.transpiler.errors module
exception pycropml.transpiler.errors.PseudoCythonNotTranslatableError(message, suggestions=None, right=None, wrong=None)[source]

Bases: pycropml.transpiler.errors.PseudoError

exception pycropml.transpiler.errors.PseudoCythonTypeCheckError(message, suggestions=None, right=None, wrong=None)[source]

Bases: pycropml.transpiler.errors.PseudoError

exception pycropml.transpiler.errors.PseudoError(message, suggestions=None, right=None, wrong=None)[source]

Bases: exceptions.Exception

pycropml.transpiler.errors.beautiful_error(exception)[source]
pycropml.transpiler.errors.cant_infer_error(name, line)[source]
pycropml.transpiler.errors.tab_aware(location, code)[source]

if tabs in beginning of code, add tabs for them, otherwise spaces

pycropml.transpiler.errors.translation_error(data, location=None, code=None, wrong_type=None, **options)[source]
pycropml.transpiler.errors.type_check_error(data, location=None, code=None, wrong_type=None, **options)[source]
pycropml.transpiler.helpers module
pycropml.transpiler.helpers.prepare_table(types, original_methods=None)[source]
pycropml.transpiler.helpers.safe_serialize_type(l)[source]

serialize only with letters, numbers and _

pycropml.transpiler.helpers.serialize_type(l)[source]
pycropml.transpiler.interface module
pycropml.transpiler.main module
pycropml.transpiler.nodeVisitor module
pycropml.transpiler.pseudo_tree module
pycropml.transpiler.version module

Maintain version for this package. Do not edit this file, use ‘version’ section of config.

pycropml.transpiler.version.MAJOR = 0

(int) Version major component.

pycropml.transpiler.version.MINOR = 0

(int) Version minor component.

pycropml.transpiler.version.POST = 2

(int) Version post or bugfix component.

Module contents
Submodules
pycropml.algorithm module
class pycropml.algorithm.Algorithm(language, development, platform, filename=None)[source]

Bases: object

pycropml.checking module
class pycropml.checking.Test(name)[source]

Bases: pycropml.checking.Testset

class pycropml.checking.Testset(name, parameterset, description, uri=None)[source]

Bases: object

Test

pycropml.checking.testset(model, name, kwds)[source]
pycropml.code2nbk module
pycropml.composition module
pycropml.cyml module
pycropml.description module
class pycropml.description.Description[source]

Bases: object

Model Unit Description.

A description is defined by:
  • Title
  • Author
  • Institution
  • Reference
  • Abstract
pycropml.error module

Created on Wed Apr 10 17:01:34 2019

@author: midingoy

exception pycropml.error.Error(message)[source]

Bases: exceptions.Exception

pycropml.formater_f90 module
pycropml.formater_f90.formater(code)[source]
pycropml.formater_f90.formaterNext(line)[source]
pycropml.function module
class pycropml.function.Function(name, language, filename, type, description)[source]

Bases: object

pycropml.initialization module
class pycropml.initialization.Initialization(name, language, filename)[source]

Bases: object

Function

pycropml.inout module
class pycropml.inout.Input(kwds)[source]

Bases: pycropml.inout.InputOutput

class pycropml.inout.InputOutput(kwds)[source]

Bases: object

class pycropml.inout.Output(kwds)[source]

Bases: pycropml.inout.InputOutput

pycropml.main module
pycropml.model module
pycropml.modelunit module

Model Description and Model Unit.

class pycropml.modelunit.ModelDefinition(kwds)[source]

Bases: object

class pycropml.modelunit.ModelUnit(kwds)[source]

Bases: pycropml.modelunit.ModelDefinition

Formal description of a Model Unit.

add_description(description)[source]

TODO

pycropml.package module
pycropml.parameterset module
class pycropml.parameterset.Parameterset(name, description, uri=None)[source]

Bases: object

Parameter set

pycropml.parameterset.parameterset(model, name, kwds)[source]
pycropml.pparse module
pycropml.render_R module
pycropml.render_csharp module
pycropml.render_cyml module
pycropml.render_fortran module
pycropml.render_java module
pycropml.render_notebook module
pycropml.render_notebook_csharp module
pycropml.render_notebook_java module
pycropml.render_python module
pycropml.test_generator module
pycropml.topology module
pycropml.version module

Maintain version for this package. Do not edit this file, use ‘version’ section of config.

pycropml.version.MAJOR = 0

(int) Version major component.

pycropml.version.MINOR = 1

(int) Version minor component.

pycropml.version.POST = 1

(int) Version post or bugfix component.

pycropml.wf2xml module
pycropml.writeTest module
pycropml.writeTest_f90 module
pycropml.xml2wf module
Module contents

Usecases

Licence

PyCropML is released under a MIT License.

Usecases

Glossary

Terminology

Model
Simplified representation of the crop system within specific objectives.

Overview

Documentation

  • A PDF version of |core| documentation is available.

History

creation (2018-01-18)

  • First release on PyPI.

Indices and tables

History

creation (2018-01-18)

  • First release on PyPI.

License

PyCropML is released under a MIT License.

Welcome to CropML’s documentation!

Contents:

Contributing Guide

This is a wiki for anything related to the contributing on [[Crop2ML|https://github.com/AgriculturalModelExchangeInitiative|Crop2ML]] which is a project of the Agricultural Model Exchange Initiative. For more information about this project, please visit CropML documentation [[Crop2ML|https://cropmlformat.readthedocs.io/en/latest/?badge=latest|documentation]]:

People

[[Stefan Behnel|http://scoder.behnel.de/|Stefan Behnel]], [[Robert Bradshaw|http://www.math.washington.edu/~robertwb/|Robert Bradshaw]], [[Dag Seljebotn|http://heim.ifi.uio.no/dagss/|Dag Seljebotn]], Lisandro Dalcin.

Mailing Lists

Our development mailing list is [[cython-dev|http://mail.python.org/mailman/listinfo/cython-devel|cython-dev]] and user mailing list at http://groups.google.com/group/cython-users.

In the past we also used a [[Google group|http://groups.google.com/group/cython|Google group]] and a list at [[BerliOS Developer|https://lists.berlios.de/mailman/listinfo/cython-dev|BerliOS Developer]]. You can still read [[the archives at Gmane|http://blog.gmane.org/gmane.comp.python.cython.devel|the archives at Gmane]].

Project Goals

  • Fully supported easy-to-use test suite, including the normal CPython test suite.
  • Easy installation and usage.
  • Rich, accessible documentation. Make sure the examples are plenty and can be automatically tested.
  • Make Cython part of the standard distribution of Python (like ctypes).
  • Compile all Python code except for possibly some obvious exclusions, which will be worked out by developers.
  • Very fast when the user explicitly declares types (but we’re not going to make promises with type inference). Precise benchmarks.
  • Mitigate or eliminate the need for users to invoke the Python/C API directly without sacrificing performance.

Documentation

  • See http://docs.cython.org/.
  • Official Pyrex [[Language Overview|http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/version/Doc/LanguageOverview.html|Language Overview]] (note the [[changes|http://hg.cython.org/cython|changes]] though).
  • [[Extension Types|http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/version/Doc/Manual/extension_types.html|Extension Types]]
  • [[Sharing Declarations Between Pyrex Modules|http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/version/Doc/Manual/sharing.html|Sharing Declarations Between Pyrex Modules]]
  • [[FAQ|http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/version/Doc/FAQ.html|FAQ]]
  • [[Quick Guide to Pyrex|http://ldots.org/pyrex-guide/|Quick Guide to Pyrex]] from Michael JasonSmith.
  • CategoryCythonDoc lists pages that are related to Cython documentation.
  • [[ Pure Python mode|pure| Pure Python mode]]
  • SAGE Days 4 talk highlighting some of the [[differences between Pyrex and SageX|http://cython.org/talks/SageX.pdf|differences between Pyrex and SageX]] (the predecessor of Cython).

CategoryHomepage

Indices and tables

Supported by:

_images/openalea.png
_images/record.jpg
_images/bioma.png
images/siriusquality.png
images/simplace.png