Model Base

mef_agri.models.base.py

Model Quantities

class mef_agri.models.base.__QS__

Helper Class which holds the string values of the model quantities. It is recommended to use/import Quantities from this module - being an instance of __QS__ - which holds the initialized properties.

property DOUT

Deterministic outputs are similar to the random outputs except that they do not exhibit a probability distribution.

property HPARAM

Hyper parameters are quantities which define the model behavior. They exhibit a considerably lower dynamic behavior than the states or can be also treated as stationary random processes.

property HPFUNC

Hyper parametric functions are an extension of the hyper parameters. They combine a number of hyper parameters which should not introduced directly to the models to keep the complexity lower.

property OBS

Observations are the driving variables in the model propagation step as well as the quantities which are used in the state update step.

property ROUT

Random outputs are random quantities which are computed by the models and are available for model analysis and to get deeper insights into crop growth.

property STATE

States are the target quantities which should be determined through model evaluation. They exhibit a dynamic behavior and temporal variability.

Model Base-Class

class mef_agri.models.base.Model(**kwargs)

Base class for all models which should be evaluated for computing crop growth. Each model which should be evaluated and connected with other models has to inherit from this class.

Only the root/top-level model has to be initialized “manually”. In this case, only the model_name of the model has to be provided as keyword argument. All child models in the model-tree (added with is_child_model()) are initialized and added to the model-tree automatically in the initialization of the root/top-level model. The model_name of child models equals the name of the decorated method.

The conversion of decorated methods (quantity, child model or requirement) into attributes happens at the time of model initialization.

Quantities

There are five main types of quantities (summarized in __QS__). In order to add such quantities as attributes to a model, one can use the decorator is_quantity(), provided as static method in this class. Methods, with this decorator are automatically accessable from outside of the model as attributes (similar to the python built-in property decorator).

Child Models

Child models are added as methods decorated with is_child_model(). In the decorator, the model-tree will be extended (see mef_agri.models.tree.ModelTree) and the child model is implemented as an attribute.

Requirements

Requirements are quantities contained in other models of the model-tree which are necessary in the computations of the current model. The advantage of using mef_agri.models.requ.Requirement is, that unit conversions are automatically applied. Required quantities from child models could be also directly accessed via the corresponding attributes. But in these cases unit conversions have to be done manually. Another option to access required quantities from other models is, to use the model_tree() property of this class.

kwargs

  • model_name (str) - has to be provided in the initialization of the root/top-level model, otherwise it is automatically passed in the is_child_model() decorator

  • model_id (str) - is automatically passed in the is_child_model() decorator, when a child model is initialized

  • model_tree (mef_agri.models.tree.ModelTree) - is automatically passed in the is_child_model() decorator, when a child model is initialized

property current_epoch
Returns:

current epoch of the model (i.e. for which epoch, the computations in Model.update() have already been performed)

Return type:

date

property deterministic_output_names
Returns:

names of the deterministic outputs in the model

Return type:

list[str]

get_obs_epoch(obs_name)

Get the epoch related to the last observations. New observations are set from outside together with the current epoch. Thus, this method can be used to indicate, that new observations are available.

Parameters:

obs_name (str) – name of the observation in the model

Returns:

epoch related to the last set observations

Return type:

datetime.date

property hp_function_names
Returns:

names of the functions acting as hyper-parameters in the model

Return type:

list[str]

property hyper_parameter_names
Returns:

names of hyper parameters contained in the model

Return type:

list[str]

initialize(epoch)

Method which performs initial computations within the model before it is being updated regularly with update(). This method can be implemented by child classes. In this case, the super call super().initialize(epoch) is mandatory.

Here, the is_initialized flag as well as the initialization-epoch is set, as well as the random outputs are initialized with nan-arrays ( length according to self.model_tree.n_particles). If this is not intended for certain random outputs, this has to be overridden in the child class.

States, hyper-parameters, hp-functions and observations are not initialized with nan-arrays, because these quantities have to be provided a priori respectively are set from “outside” of this class

Parameters:

epoch (datetime.date) – intialization epoch

static is_child_model(child_class)

Add another model (class which inherits from Model) as child-model. The provided child_class will be initialized in the decorator and inserted into the model-tree (model_tree() property) appropriately (see mef_agri.models.tree.ModelTree.extend_model_tree() and mef_agri.models.tree.ModelTree.add_model_reference())

Parameters:

child_class (mef_agri.models.base.Model) – class which represents the child model

property is_initialized
Returns:

flag if model is initialized (i.e. Model.initialize() has been called)

Return type:

bool

static is_quantity(qd, unit, discrete=False)

Decorator to define model quantities (see __QS__).

Parameters:

  • qd (str) – type of model quantity (properties of __QS__)

  • unit (str) – unit of the model quantity (see mef_agri.models.utils.__UNITS__)

  • discrete (bool, optional) – specify if the quantity exhibits a discrete probability distribution (only matters for the TODO evalDB), defaults to False

static is_required(qname, model_id, unit)

Decorator to add required quantities which are part of another model in the model-tree. The decorated method is converted to an attribute being an instance of mef_agri.models.requ.Requirement (i.e. the value of the required quantity has to be accessed via the value property of the attribute).

Parameters:

  • qname (str) – name of the required quantity in the corresponding model of the model-tree

  • model_id (str) – id of the model which contains the required quantity

  • unit (str) – required unit of the quantity

property model_id
Returns:

ID of the model in the model_tree

Return type:

str

property model_name
Returns:

name of the model

Return type:

str

property model_tree
Returns:

reference of the model-tree

Return type:

ModelTree

property observation_names
Returns:

names of observations contained in the model

Return type:

list[str]

property output_names
Returns:

names of other output quantities (random and deterministic) contained in the model

Return type:

list[str]

property quantity_names
Returns:

names of all quantities contained in the model

Return type:

list[str]

property random_output_names
Returns:

names of the random outputs in the model

Return type:

list[str]

property requirements
Returns:

dictionary containing the required quantities from other models in the model tree (sorted according to the time of requirement - initialization or update)

Return type:

dict

reset_quantities(qs, force=False)

Reset specified quantities to nan-arrays.

Parameters:

qs (list[str] | str) – model quantities which should be reset

property state_names
Returns:

names of states contained in the model

Return type:

list[str]

update(epoch)

Method which does the computations on a daily interval. This method has to be implemented by child classes. The super call super().update(epoch) is mandatory.

Parameters:

epoch (datetime.date) – current epoch