Model Utilities¶

mef_agri.models.utils.py

Utility functions and classes used for model evaluation.

Units of model quantities¶

class mef_agri.models.utils.__UNITS__¶

Helper class which holds the string values defining a certain unit. It is recommended to use/import Units from this module - being an instance of this class - which holds the initialized properties.

property MJ_kg¶

Returns:: Mega Joule per kg \(\frac{MJ}{kg}\)
Return type:: str

property MJ_m2¶

Returns:: Mega Joule per square meter \(\frac{MJ}{m^2}\)
Return type:: str

property MJ_m2xday¶

Returns:: Mega Joule per square meter \(\frac{MJ}{m^2\cdot day}\)
Return type:: str

property W_m2¶

Returns:: Watt per square meter \(\frac{W}{m^2}\)
Return type:: str

property Wh_m2xday¶

Returns:: Watt hours per square meter and day \(\frac{Wh}{m^2\cdot day}\)
Return type:: str

property boolean¶

Returns:: boolean value
Return type:: str

property cm¶

Returns:: centimeters \(cm\)
Return type:: str

convert(value, u_source, u_target)¶

Method to convert physical units.

Parameters:

value (float or numpy.ndarray) – value which should be converted
u_source (str) – unit of value
u_target (str) – target unit, to which the value should be converted

Returns:

converted value

Return type:

float or numpy.ndarray

property day¶

Returns:: days \(day\)
Return type:: str

property deg¶

Returns:: angular degrees \(^\circ\)
Return type:: str

property degC¶

Returns:: degree Celsius \(^\circ C\)
Return type:: str

property degK¶

Returns:: degree Kelvin \(^\circ K\)
Return type:: str

property frac¶

Returns:: fraction (usally corresponds to percent, in the range [0, 1])
Return type:: str

property g_cm3¶

Returns:: bulk density \(\frac{g}{cm^3}\)
Return type:: str

property g_ha¶

Returns:: gram per hectar \(\frac{g}{ha}\)
Return type:: str

property h¶

Returns:: hours \(h\)
Return type:: str

property kPa¶

Returns:: pressure in kilo Pascal \(kPa\)
Return type:: str

property kPa_degC¶

Returns:: kilo Pascal per degree Celsius (e.g. psychrometric constant) \(\frac{kPa}{^\circ C}\)
Return type:: str

property kg_ha¶

Returns:: kilogram per hectar \(\frac{kg}{ha}\)
Return type:: str

property kg_haxday¶

Returns:: kilogram per hectar and day \(\frac{kg}{ha\cdot day}\)
Return type:: str

property kg_m3¶

Returns:: bulk density \(\frac{kg}{m^3}\)
Return type:: str

property kg_t¶

Returns:: kg nutrient per ton biomass \(\frac{kg}{t}\)
Return type:: str

property kgxm2_haxMJxday¶

Returns:: unit used for factor to convert energy to biomass \(\frac{kg\cdot m^2}{MJ\cdot ha\cdot day}\)
Return type:: str

property l_ha¶

Returns:: liters per hectar \(\frac{l}{ha}\)
Return type:: str

property m¶

Returns:: meters \(m\)
Return type:: str

property m_s¶

Returns:: velocity in meters per second \(\frac{m}{s}\)
Return type:: str

property mm¶

Returns:: millimeters \(mm\)
Return type:: str

property mm_day¶

Returns:: mm per day (e.g. hydraulic conductivity) \(\frac{mm}{day}\)
Return type:: str

property mm_m2xday¶

Returns:: mm per square meter and day (e.g. precipitation) \(\frac{mm}{m^2\cdot day}\)
Return type:: str

property n_degC¶

Returns:: per degree Celsius \(\frac{1}{^\circ C}\)
Return type:: str

property n_ha¶

Returns:: amount/number per hectar \(\frac{1}{ha}\)
Return type:: str

property n_m2¶

Returns:: amount/number per square meter \(\frac{1}{m^2}\)
Return type:: str

property none¶

Returns:: no units, i.e. unitless
Return type:: str

property per_day¶

Returns:: daily unitless rates \(\frac{1}{day}\)
Return type:: str

property perc¶

Returns:: percent
Return type:: str

property rad¶

Returns:: angular radians \(rad\)
Return type:: str

property s¶

Returns:: seconds \(s\)
Return type:: str

property s_m¶

Returns:: used for resistance term in evapotranspiration \(\frac{s}{m}\)
Return type:: str

property t_ha¶

Returns:: tons per hectar \(\frac{kg}{ha}\)
Return type:: str

property t_haxday¶

Returns:: tons per hectar and day \(\frac{t}{ha\cdot day}\)
Return type:: str

property undef¶

Returns:: unit not defined
Return type:: str

Hyper-Parameter Function¶

class mef_agri.models.utils.HPFunction¶

This class represents a function which acts as hyper-parameter in the models. The object is callable and returns the output value based on the provided input value. The input value can be a numeric value, a 1D numpy.ndarray with length 1 or with length equal to the number of particles representing the distributions.

The following function types are supported:

PIECEWISE_LINEAR

Is defined by a set of x- and y-values (equal length!). The fdef dictionary of define() contains the following keys

ftype - str specifying the function type, see FTYPE
values-x - array of values on the x-axis of the function (i.e. the input values), used as mean/mode value for the distribution
values-y - array of values on the y-axis of the function (i.e. the output values), used as mean/mode value for the distribution
distr-x - distribution of the x-values, dict which contains the distr_id, and further distribution parameters according to stats_utils, the assumption is, that the distribution is equal for all x-values
distr-y - distribution of the y-values, dict which contains the distr_id, and further distribution parameters according to stats_utils, the assumption is, that the distribution is equal for all y-values
sample - specifies if hp-function should be sampled or not

values-x and values-y are necessary, the other ones are optional

class FTYPE¶

Helper class which holds the string values (class variables) to define the type of a hyper parametric function

PIECEWISE_LINEAR = 'piecewise-linear'

class PiecewiseLinear(fdef)¶

Class representing a piecewise linear function. Based on the provided x- and y-values, intervals are defined, in which a linear function is used to interpolate values.

Parameters:: fdef (dict) – dictionary containing information about the function (see HPFunction)

compute(value)¶

Compute interpolated values. In the case, that the HP-function is sampled, each value in value is used for interpolation together with one sample of supporting points (i.e. one row of the \(nsampels\times n\) arrays representing the x- and y-values).

Parameters:

value (numpy.ndarray) – x-values for which y-values should be interpolated - should be a one-dimensional array

Raises:

ValueError – if value has more than one dimension
ValueError – if len(value) does not match nsamples of sample()

Returns:

interpolated values

Return type:

numpy.ndarray

sample(rvs, nsamples)¶

If the HP-function is sampled, the arrays of x- and y-values with length \(n\) (values in fdef provided to __init__()) are sampled as often as specified by nsamples. Thus, the arrays of x- and y-values (representing the supporting points) exhibit the dimensions \(nsamples\times n\) instead of \(1\times n\).

Parameters:

rvs (RVSampler) – TODO
nsamples (int) – number of samples

property current_value¶

Returns:: current values computed with HP-Function definition and input values
Return type:: numpy.ndarray

define(fdef)¶

Define the hyper-parametric function.

Parameters:: fdef (dict) – dictionary containing information about the function
Raises:: ValueError – if 'ftype' in fdef is not supporte by this class

property is_sampled¶

Returns:: flag if hp-function is sampled
Return type:: bool

sample(rvs, nsamples)¶

TODO

Parameters:

rvs (RVSampler) – _description_
nsamples (int) – _description_

Other stuff¶

mef_agri.models.utils.day_of_year(epoch)¶

Parameters:: epoch (datetime.date) – current epoch
Returns:: n-th day of the year
Return type:: int