Model-Tree¶

mef_agri.models.tree.py

This module contains the ModelTree class, which ensures, that models are connected and that all model-quantities are accessible from every location in the model-tree.

ModelTree class¶

class mef_agri.models.tree.ModelTree(model)¶

Crop and soil models are connected and arranged in a tree-representation. Thus, there is one root/top-level model (model argument in the initialization) and further models are added by decorating attributes of a parent-model (instance of a class inheriting from mef_agri.models.base.Model) with the decorator mef_agri.models.base.Model.is_child_model().

An unique model-id is assigned to each model in the model-tree. This id corresponds to the model_id attribute of mef_agri.models.base.Model. The model-id is designed like an absolute path, where each level corresponds to the name of the model ( model_name attribute of mef_agri.models.base.Model). The separation character is a point or dot. The extend_model_tree() method is used to create the appropriate model-id and it extends the dictionary (_tree attribute or property tree_dict()) which represents the model tree and holds references to all models. An example of _tree is shown in the following where the root model name is m1 and its two child models m2 and m3

self._tree = {
    'm1': {
        'ref': mdl1,  # object reference
        'parent_id': None,  # no parent for the root model
        'child_ids': ['m1.m2', 'm1.m3']
    },
    'm1.m2': {
        'ref': mdl2,  # object reference
        'parent_id': 'm1',
        'child_ids: []
    },
    'm1.m3': {
        'ref': mdl3,  # object reference
        'parent_id': 'm1',
        'child_ids: []
    }
}

Parameters:: model (mef_agri.models.base.Model) – root/top-level model in the tree

add_model_reference(model)¶

Add a model-reference to the model tree. This method is used by mef_agri.models.base.Models.is_child_model().

Parameters:: model (mef_agri.models.base.Model) – object representing a model

connnect(tree)¶

Connect two model trees. This method does the connection bi-directional, i.e. it sets the provided model-tree object in the _conn dictionary of this model-tree object and vice versa. Thus, it is not necessary to call this method a second time from the provided model-tree object. The _conn dictionary holds the reference to the model-tree object with its key being equal to the model-id of the root/top-level model.

Parameters:: tree (mef_agri.models.tree.ModelTree) – model-tree object which should be connected to this model-tree object

disconnect(tree)¶

Disconnect model-trees (i.e. remove the corresponding entries in the _conn dictionaries of this model-tree and the provided model-tree).

Parameters:: tree (mef_agri.models.tree.ModelTree) – model-tree object which should be disconnected from this model-tree object

extend_model_tree(parent_model_id, child_model_name)¶

Get the desired structure of the model-id in the model-tree. The returned model-id can be seen as an absolute path, where the individual levels correspond to the model names which are separated by points. This method is used by mef_agri.models.base.Models.is_child_model()

Parameters:

parent_model_id (str) – model-id of the parent-model (attribute model_id of mef_agri.models.base.Model)
child_model_name (str) – name of the child-model (attribute model_name of mef_agri.models.base.Model)

Returns:

unique model-id in the tree

Return type:

str

get_model(model_id)¶

Get model from model-tree or from other connnected model-trees. If return value is None, no model with provided model_id is found.

Parameters:: model_id (str) – model-id of the required model
Returns:: object representing the requested model
Return type:: mef_agri.models.base.Model

get_model_id_from_relative_path(model_id, relpath)¶

Get the model-id from a given relative path representing the way of “walking” through the model tree. A relative path starts with a dot followed either by

the model names (attribute model_name of mef_agri.models.base.Model) which means to go “down” in the model-tree
or the string __parent__ indicating to go “up” in the model tree.

Parameters:

model_id (str) – model-id of the model which is the “starting point” of the provided relative path
relpath (str) – the relative path representing the way to the desired model in the model tree

Raises:

ValueError – if relpath does not start with a dot

Returns:

model-id of the desired model

Return type:

str

get_obs_epoch(obs_name, model_id)¶

Returns the epoch of the current observations.

Parameters:

obs_name (str) – name of the observation (i.e. quantity) in the model
model_id (str) – id of the model wich contains the quantity

Returns:

epoch of the observation

Return type:

datetime.date

get_qinfos(qname, model_id)¶

Get information about a model-quantity (see arguments of ssc_csm.models.base.Model.is_quantity())

Parameters:

qname (str) – name of the model-quantity
model_id (str) – model-id of the model containing the required quantity

Returns:

dictionary with quantity information (keys: qtype, unit, distr_type, epoch in the case of observations)

Return type:

dict

get_quantity(qname, model_id, unit=None)¶

Get a model-quantity from a model in the model-tree. If it is not found, also the connected trees are screened. If unit is provided, the appropriate conversion is applied.

Parameters:

qname (str) – name of the quantity in the model
model_id (str) – id of the model which contains the quantity
unit (str, optional) – desired unit of the requested quantity (see mef_agri.models.utils.__UNITS__), defaults to None

Returns:

requested quantity

Return type:

any

has_model(model_id)¶

Check if the model-tree contains a model.

Parameters:: model_id (str) – model-id of requested model
Returns:: boolean indicator
Return type:: bool

is_q_discrete(qname, model_id)¶

Check if quantity exhibits a discrete distribution

Parameters:

qname (str) – name of the model-quantity
model_id (str) – model-id of the model containing the required quantity

Returns:

boolean indicator

Return type:

bool

property model_ids¶

Returns:: ids of the models in the tree (also connected trees are considered)
Return type:: list[str]

property models¶

Returns:: references to the objects representing the models in the tree (also connected trees are considered)
Return type:: list

property n_particles¶

Returns:: number of particles (i.e. realization or values) representing the distributions of the model quantities
Return type:: int

set_quantity(qname, model_id, value, unit=None, epoch=None)¶

Set the value of a quantity in a model in the tree. If unit is provided and value is not a dict (i.e. set a mef_agri.models.utils.HPFunction), the appropriate conversion is applied.

Parameters:

qname (str) – name of the quantity in the model
model_id (str) – id of the model which contains the quantity
value (float or 1D numpy.ndarray, dict for HPFunction) – value which should be set for the quantity
unit (str, optional) – unit of the provided value (see mef_agri.models.utils.__UNITS__), defaults to None
epoch (datetime.date) – epoch of an observation, which is necessary to indicate new incoming observations

property text_representation¶

Returns:: text representation of the model tree
Return type:: str

property tree_dict¶

Returns:: model-tree representation as dictionary
Return type:: dict