numericalmodel package¶

numericalmodel Python module

Subpackages¶

numericalmodel.gui package

Submodules¶

numericalmodel.equations module¶

class numericalmodel.equations.DerivativeEquation(variable=None, description=None, long_description=None, input=None)[source]¶

Bases: numericalmodel.equations.Equation

Class to represent a derivative equation

derivative(time=None, variablevalue=None)[source]¶

Calculate the derivative (right-hand-side) of the equation

Parameters:	time (single numeric, optional) – the time to calculate the derivative. Defaults to the variable’s current (last) time. variablevalue (numpy.ndarray, optional) – the variable vaulue to use. Defaults to the value of self.variable at the given time.
Returns:	the derivatives corresponding to the given time
Return type:	numpy.ndarray

independent_addend(time=None)[source]¶

Calculate the derivative’s addend part that is independent of the variable.

Parameters:	time (single numeric, optional) – the time to calculate the derivative. Defaults to the variable’s current (last) time.
Returns:	the equation’s variable-independent addend at the corresponding time
Return type:	numpy.ndarray

linear_factor(time=None)[source]¶

Calculate the derivative’s linear factor in front of the variable

Parameters:	time (single numeric, optional) – the time to calculate the derivative. Defaults to the variable’s current (last) time.
Returns:	the equation’s linear factor at the corresponding time
Return type:	numpy.ndarray

nonlinear_addend(time=None, variablevalue=None)[source]¶

Calculate the derivative’s addend part that is nonlinearly dependent of the variable.

Parameters:	time (single numeric, optional) – the time to calculate the derivative. Defaults to the variable’s current (last) time. variablevalue (numpy.ndarray, optional) – the variable vaulue to use. Defaults to the value of self.variable at the given time.
Returns:	the equation’s nonlinear addend at the corresponding time
Return type:	numpy.ndarray

class numericalmodel.equations.DiagnosticEquation(variable=None, description=None, long_description=None, input=None)[source]¶

Bases: numericalmodel.equations.Equation

Class to represent diagnostic equations

class numericalmodel.equations.Equation(variable=None, description=None, long_description=None, input=None)[source]¶

Bases: numericalmodel.utils.LoggerObject, numericalmodel.utils.ReprObject

Base class for equations

Parameters:	description (str, optional) – short equation description long_description (str, optional) – long equation description variable (StateVariable, optional) – the variable obtained by solving the equation input (SetOfInterfaceValues, optional) – set of values needed by the equation

__str__()[source]¶

Stringification

Returns:	a summary
Return type:	str

depends_on(id)[source]¶

Check if this equation depends on a given InterfaceValue

Parameters:	id (str or InterfaceValue) – an `InterfaceValue` or an id
Returns:	`True` if ‘id’ is in `input`, `False` otherwise
Return type:	bool

description¶

The description of the equation

Type:	`str`

input¶

The input needed by the equation. Only real dependencies should be included. If the equation depends on the variable, it should also be included in input.

Type:	`SetOfInterfaceValues`

long_description¶

The longer description of this equation

Type:	`str`

variable¶

The variable the equation is able to solve for

Type:	`StateVariable`

class numericalmodel.equations.PrognosticEquation(variable=None, description=None, long_description=None, input=None)[source]¶

Bases: numericalmodel.equations.DerivativeEquation

Class to represent prognostic equations

class numericalmodel.equations.SetOfEquations(elements=[])[source]¶

Bases: numericalmodel.utils.SetOfObjects

Base class for sets of Equations

Parameters:	elements (`list` of `Equation`, optional) – the list of `Equation` instances

_object_to_key(obj)[source]¶

key transformation function.

Parameters:	obj (object) – the element
Returns:	the unique key for this object. The `Equation.variable`‘s `id` is used.
Return type:	str

numericalmodel.genericmodel module¶

class numericalmodel.genericmodel.GenericModel(name=None, version=None, description=None, long_description=None, authors=None)[source]¶

Bases: numericalmodel.utils.LoggerObject, numericalmodel.utils.ReprObject

Base class for models

Parameters:

name (str, optional) – the model name
version (str, optional) – the model version
description (str) – a short model description
long_description (str) – an extended model description
authors (str, list or Dictionary displays, optional) –
the model author(s). One of

str:

name of single author

list of str:

list of author names

Dictionary displays:

Dictionary displays of {'task': ['name1','name1']} pairs

__str__()[source]¶

Stringification

Returns:	a summary
Return type:	str

authors¶

The model author(s)

str:: name of single author
list of str:: list of author names
Dictionary displays:: Dictionary displays of {'task': ['name1','name1']} pairs

description¶

The model description

Type:	`str`

long_description¶

Longer model description

Type:	`str`

name¶

The model name

Type:	`str`

version¶

The model version

Type:	`str`

numericalmodel.interfaces module¶

class numericalmodel.interfaces.ForcingValue(name=None, id=None, unit=None, time_function=None, interpolation=None, values=None, times=None, bounds=None, remembrance=None)[source]¶

Bases: numericalmodel.interfaces.InterfaceValue

Class for forcing values

class numericalmodel.interfaces.InterfaceValue(name=None, id=None, unit=None, time_function=None, interpolation=None, values=None, times=None, bounds=None, remembrance=None)[source]¶

Bases: numericalmodel.utils.LoggerObject, numericalmodel.utils.ReprObject

Base class for model interface values

Parameters:

name (str, optional) – value name
id (str, optional) – unique id
values (1d numpy.ndarray, optional) – all values this InterfaceValue had in chronological order
times (1d numpy.ndarray, optional) – the corresponding times to values
unit (str,optional) – physical unit of value
bounds (list, optional) – lower and upper value bounds
interpolation (str, optional) – interpolation kind. See scipy.interpolate.interp1d for documentation. Defaults to “zero”.
time_function (callable, optional) – function that returns the model time as utc unix timestamp
remembrance (float, optional) – maximum time difference to keep past values

__call__(times=None)[source]¶

When called, return the value, optionally at a specific time

Parameters:	times (numeric, optional) – The times to obtain data from

__str__()[source]¶

Stringification

Returns:	a summary
Return type:	str

forget_old_values()[source]¶

Drop values and times older than remembrance.

Returns:	`True` is data was dropped, `False` otherwise
Return type:	bool

bounds¶

The values‘ bounds. Defaults to an infinite interval.

Getter:	Return the current bounds
Setter:	If the bounds change, check if all `values` lie within the new bounds.
Type:	`list`, `[lower, upper]`

id¶

The unique id

Type:	`str`

interpolation¶

The interpolation kind to use in the __call__ method. See scipy.interpolate.interp1d for documentation.

Getter:	Return the interplation kind.
Setter:	Set the interpolation kind. Reset the internal interpolator if the interpolation kind changed.
Type:	`str`

interpolator¶

The interpolator for interpolation of values over times. Creating this interpolator is costly and thus only performed on demand, i.e. when __call__ is called and no interpolator was created previously or the previously created interolator was unset before (e.g. by setting a new value or changing interpolation)

Type:	`scipy.interpolate.interp1d`

name¶

The name.

Type:	`str`

next_time¶

The next time to use when value is set.

Getter:	Return the next time to use. Defaults to the value of `time_function` if no `next_time` was set.
Setter:	Set the next time to use. Set to `None` to unset and use the default time in the getter again.
Type:	`float`

remembrance¶

How long should this InterfaceValue store it’s values? This is the greatest difference the current time may have to the smallest time. Values earlier than the remembrance time are discarded. Set to None for no limit.

Type:	`float` or `None`

time¶

The current time

Getter:	Return the current time, i.e. the last time recorded in `times`.
Type:	`float`

time_function¶

times¶

All times the value has ever been set in chronological order

Type:	`numpy.ndarray`

unit¶

The SI-unit.

Type:	`str`, SI-unit

value¶

The current value.

Getter:	the return value of `__call__`, i.e. the current value.
Setter:	When this property is set, the given value is recorded to the time given by `next_time`. If this time exists already in `times`, the corresponding value in `values` is overwritten. Otherwise, the new time and value are appended to `times` and `values`. The value is also checked to lie within the `bounds`.
Type:	numeric

values¶

All values this InterfaceValue has ever had in chronological order

Getter:	Return the current values
Setter:	Check if all new values lie within the `bounds`
Type:	`numpy.ndarray`

class numericalmodel.interfaces.Parameter(name=None, id=None, unit=None, time_function=None, interpolation=None, values=None, times=None, bounds=None, remembrance=None)[source]¶

Bases: numericalmodel.interfaces.InterfaceValue

Class for parameters

class numericalmodel.interfaces.SetOfForcingValues(elements=[])[source]¶

Bases: numericalmodel.interfaces.SetOfInterfaceValues

Class for a set of forcing values

class numericalmodel.interfaces.SetOfInterfaceValues(elements=[])[source]¶

Bases: numericalmodel.utils.SetOfObjects

Base class for sets of interface values

Parameters:	values (`list` of `InterfaceValue`, optional) – the list of values

__call__(id)[source]¶

Get the value of an InterfaceValue in this set

Parameters:	id (str) – the id of an `InterfaceValue` in this set
Returns:	the `value` of the corresponding `InterfaceValue`
Return type:	float

_object_to_key(obj)[source]¶

key transformation function.

Parameters:	obj (object) – the element
Returns:	the unique key for this object. The `InterfaceValue.id` is used.
Return type:	key (str)

time_function¶

The time function of all the InterfaceValue s in the set.

Getter:	Return a `list` of time functions from the elements
Setter:	Set the time function of each element
Type:	(`list` of) callables

class numericalmodel.interfaces.SetOfParameters(elements=[])[source]¶

Bases: numericalmodel.interfaces.SetOfInterfaceValues

Class for a set of parameters

class numericalmodel.interfaces.SetOfStateVariables(elements=[])[source]¶

Bases: numericalmodel.interfaces.SetOfInterfaceValues

Class for a set of state variables

class numericalmodel.interfaces.StateVariable(name=None, id=None, unit=None, time_function=None, interpolation=None, values=None, times=None, bounds=None, remembrance=None)[source]¶

Bases: numericalmodel.interfaces.InterfaceValue

Class for state variables

numericalmodel.numericalmodel module¶

class numericalmodel.numericalmodel.NumericalModel(name=None, version=None, description=None, long_description=None, authors=None, initial_time=None, parameters=None, forcing=None, variables=None, numericalschemes=None)[source]¶

Bases: numericalmodel.genericmodel.GenericModel

Class for numerical models

Parameters:

name (str, optional) – the model name
version (str, optional) – the model version
description (str) – a short model description
long_description (str) – an extended model description
authors (str, list or Dictionary displays, optional) –
the model author(s). One of

str:

name of single author

list of str:

list of author names

Dictionary displays:

Dictionary displays of {'task': ['name1','name1']} pairs
initial_time (float) – initial model time (UTC unix timestamp)
parameters (SetOfParameters, optional) – model parameters
forcing (SetOfForcingValues, optional) – model forcing
variables (SetOfStateVariables, optional) – model state variables
numericalschemes (SetOfNumericalSchemes, optional) – model schemes with equation

__str__()[source]¶

Stringification

Returns:	a summary
Return type:	str

get_model_time()[source]¶

The current model time

Returns:	current model time
Return type:	float

integrate(final_time)[source]¶

Integrate the model until final_time

Parameters:	final_time (float) – time to integrate until

run_interactively()[source]¶

Open a GTK window to interactively run the model:

change the model variables, parameters and forcing on the fly
directly see the model output
control simulation speed
pause and continue or do stepwise simulation

Note

This feature is still in development and currently not really functional.

forcing¶

The model forcing

Type:	`SetOfForcingValues`

initial_time¶

The initial model time

Type:	`float`

model_time¶

The current model time

Type:	`float`

numericalschemes¶

The model numerical schemes

Type:	`str`

parameters¶

The model parameters

Type:	`SetOfParameters`

variables¶

The model variables

Type:	`SetOfStateVariables`

numericalmodel.numericalschemes module¶

class numericalmodel.numericalschemes.EulerExplicit(description=None, long_description=None, equation=None, fallback_max_timestep=None, ignore_linear=None, ignore_independent=None, ignore_nonlinear=None)[source]¶

Bases: numericalmodel.numericalschemes.NumericalScheme

Euler-explicit numerical scheme

step(time=None, timestep=None, tendency=True)[source]¶

class numericalmodel.numericalschemes.EulerImplicit(description=None, long_description=None, equation=None, fallback_max_timestep=None, ignore_linear=None, ignore_independent=None, ignore_nonlinear=None)[source]¶

Bases: numericalmodel.numericalschemes.NumericalScheme

Euler-implicit numerical scheme

step(time=None, timestep=None, tendency=True)[source]¶

Integrate one “timestep” from “time” forward with the Euler-implicit scheme and return the resulting variable value.

Parameters:	time (single numeric) – The time to calculate the step FROM timestep (single numeric) – The timestep to calculate the step tendency (bool, optional) – return the tendency or the actual value of the variable after the timestep?
Returns:	The resulting variable value or tendency
Return type:	numpy.ndarray
Raises:	`AssertionError` – when the equation’s nonlinear part is not zero and `ignore_nonlinear` is not set to `True`

class numericalmodel.numericalschemes.LeapFrog(description=None, long_description=None, equation=None, fallback_max_timestep=None, ignore_linear=None, ignore_independent=None, ignore_nonlinear=None)[source]¶

Bases: numericalmodel.numericalschemes.NumericalScheme

Leap-Frog numerical scheme

step(time=None, timestep=None, tendency=True)[source]¶

class numericalmodel.numericalschemes.NumericalScheme(description=None, long_description=None, equation=None, fallback_max_timestep=None, ignore_linear=None, ignore_independent=None, ignore_nonlinear=None)[source]¶

Bases: numericalmodel.utils.ReprObject, numericalmodel.utils.LoggerObject

Base class for numerical schemes

Parameters:

description (str) – short equation description
long_description (str) – long equation description
equation (DerivativeEquation) – the equation
fallback_max_timestep (single numeric) – the fallback maximum timestep if no timestep can be estimated from the equation
ignore_linear (bool) – ignore the linear part of the equation?
ignore_independent (bool) – ignore the variable-independent part of the equation?
ignore_nonlinear (bool) – ignore the nonlinear part of the equation?

__str__()[source]¶

Stringification

Returns:	a summary
Return type:	str

_needed_timesteps_for_integration_step(timestep=None)[source]¶

Given a timestep to integrate from now on, what other timesteps of the dependencies are needed?

Parameters:	timestep (single numeric) – the timestep to calculate
Returns:	the timesteps
Return type:	numpy.ndarray

Note

timestep 0 means the current time

independent_addend(time=None)[source]¶

Calculate the equation’s addend part that is independent of the variable.

Parameters:	time (single numeric, optional) – the time to calculate the derivative. Defaults to the variable’s current (last) time.
Returns:	the independent addend or 0 if `ignore_independent` is `True`.
Return type:	numeric

integrate(time=None, until=None)[source]¶

Integrate until a certain time, respecting the max_timestep.

Parameters:	time (single numeric, optional) – The time to begin. Defaults to current variable `time`. until (single numeric, optional) – The time to integrate until. Defaults to one `max_timestep` further.

integrate_step(time=None, timestep=None)[source]¶

Integrate “timestep” forward and set results in-place

Parameters:	time (single numeric, optional) – The time to calculate the step FROM. Defaults to the current variable time. timestep (single numeric, optional) – The timestep to calculate the step. Defaults to `max_timestep`.

linear_factor(time=None)[source]¶

Calculate the equation’s linear factor in front of the variable.

Parameters:	time (single numeric, optional) – the time to calculate the derivative. Defaults to the variable’s current (last) time.
Returns:	the linear factor or 0 if `ignore_linear` is `True`.
Return type:	numeric

max_timestep_estimate(time=None, variablevalue=None)[source]¶

Based on this numerical scheme and the equation parts, estimate a maximum timestep. Subclasses may override this.

Parameters:	time (single numeric, optional) – the time to calculate the derivative. Defaults to the variable’s current (last) time. variablevalue (numpy.ndarray, optional) – the variable vaulue to use. Defaults to the value of self.variable at the given time.
Returns:	an estimate of the current maximum timestep. Definitely check the result for integrity.
Return type:	single numeric or bogus
Raises:	`Exception` – any exception if something goes wrong

needed_timesteps(timestep)[source]¶

Given a timestep to integrate from now on, what other timesteps of the dependencies are needed?

Parameters:	timestep (single numeric) – the timestep to calculate
Returns:	the timesteps
Return type:	numpy.ndarray

Note

timestep 0 means the current time

nonlinear_addend(time=None, variablevalue=None)[source]¶

Calculate the derivative’s addend part that is nonlinearly dependent of the variable.

Parameters:	time (single numeric, optional) – the time to calculate the derivative. Defaults to the variable’s current (last) time. variablevalue (numpy.ndarray, optional) – the variable vaulue to use. Defaults to the value of self.variable at the given time.
Returns:	the nonlinear addend or 0 if ignore_nonlinear is True.
Return type:	res (numeric)

step(time, timestep, tendency=True)[source]¶

Integrate one “timestep” from “time” forward and return value

Parameters:	time (single numeric) – The time to calculate the step FROM timestep (single numeric) – The timestep to calculate the step tendency (bool, optional) – return the tendency or the actual value of the variable after the timestep?
Returns:	The resulting variable value or tendency
Return type:	numpy.ndarray

description¶

The numerical scheme description

Type:	`str`

equation¶

The equation the numerical scheme’s should solve

Type:	`DerivativeEquation`

fallback_max_timestep¶

The numerical scheme’s fallback maximum timestep

Type:	`float`

ignore_independent¶

Should this numerical scheme ignore the equation’s variable-independent addend?

Type:	`bool`

ignore_linear¶

Should this numerical scheme ignore the equation’s linear factor?

Type:	`bool`

ignore_nonlinear¶

Should this numerical scheme ignore the equation’s nonlinear addend?

Type:	`bool`

long_description¶

The longer numerical scheme description

Type:	`str`

max_timestep¶

Return a maximum timestep for the current state. First tries the max_timestep_estimate, then the fallback_max_timestep.

Parameters:	time (single numeric, optional) – the time to calculate the derivative. Defaults to the variable’s current (last) time. variablevalue (numpy.ndarray, optional) – the variable vaulue to use. Defaults to the value of self.variable at the given time.
Returns:	an estimate of the current maximum timestep
Return type:	float

class numericalmodel.numericalschemes.RungeKutta4(description=None, long_description=None, equation=None, fallback_max_timestep=None, ignore_linear=None, ignore_independent=None, ignore_nonlinear=None)[source]¶

Bases: numericalmodel.numericalschemes.NumericalScheme

Runte-Kutta-4 numerical scheme

step(time=None, timestep=None, tendency=True)[source]¶

class numericalmodel.numericalschemes.SetOfNumericalSchemes(elements=[], fallback_plan=None)[source]¶

Bases: numericalmodel.utils.SetOfObjects

Base class for sets of NumericalSchemes

Parameters:

elements (list of NumericalScheme, optional) – the the numerical schemes
fallback_plan (list, optional) –
the fallback plan if automatic planning fails. Depending on the combination of numerical scheme and equations, a certain order or solving the equations is crucial. For some cases, the order can be determined automatically, but if that fails, one has to provide this information by hand. Has to be a list of [varname, [timestep1,timestep2,...]] pairs.

varname:

the name of the equation variable. Obviously there has to be at least one entry in the list for each equation.

timestepN:

the normed timesteps (betw. 0 and 1) to calculate. Normed means, that if it is requested to integrate the set of numerical equations by an overall timestep, what percentages of this timestep have to be available of this variable. E.g. an overall timestep of 10 is requested. Another equation needs this variable at the timesteps 2 and 8. Then the timesteps would be [0.2,0.8]. Obviously, the equations that looks farest into the future (e.g. Runge-Kutta or Euler-Implicit) has to be last in this fallback_plan list.

_object_to_key(obj)[source]¶

key transformation function.

Parameters:	obj (object) – the element
Returns:	the unique key for this object. The equation’s variable’s id is used.
Return type:	key (str)

integrate(start_time, final_time)[source]¶

Integrate the model until final_time

Parameters:	start_time (float) – the starting time final_time (float) – time to integrate until

fallback_plan¶

The fallback plan if automatic plan determination does not work

Type:	`list`

plan¶

The unified plan for this set of numerical schemes. First try to determine the plan automatically, if that fails, use the fallback_plan.

Type:	`list`

numericalmodel.utils module¶

class numericalmodel.utils.LoggerObject(logger=<logging.Logger object>)[source]¶

Bases: object

Simple base class that provides a ‘logger’ property

Parameters:	logger (logging.Logger) – the logger to use

logger¶: the logging.Logger used for logging. Defaults to logging.getLogger(__name__).

class numericalmodel.utils.ReprObject[source]¶

Bases: object

Simple base class that defines a __repr__ method based on an object’s __init__ arguments and properties that are named equally. Subclasses of ReprObject should thus make sure to have properties that are named equally as their __init__ arguments.

__repr__()[source]¶

Python representation of this object

Returns:	a Python representation of this object based on its `__init__` arguments and corresponding properties.
Return type:	str

classmethod _full_variable_path(var)[source]¶

Get the full string of a variable

Parameters:	var (any) – The variable to get the full string from
Returns:	The full usable variable string including the module
Return type:	str

class numericalmodel.utils.SetOfObjects(elements=[], element_type=<class 'object'>)[source]¶

Bases: numericalmodel.utils.ReprObject, numericalmodel.utils.LoggerObject, collections.abc.MutableMapping

Base class for sets of objects

__str__()[source]¶

Stringification

Returns:	a summary
Return type:	str

_object_to_key(obj)[source]¶

key transformation function. Subclasses should override this.

Parameters:	obj (object) – object
Returns:	the unique key for this object. Defaults to `repr(obj)`
Return type:	str

add_element(newelement)[source]¶

Add an element to the set

Parameters:	newelement (object of type `element_type`) – the new element

element_type¶: The base type the elements in the set should have

elements¶

return the list of values

Getter:	get the list of values
Setter:	set the list of values. Make sure, every element in the list is an instance of (a subclass of) `element_type`.
Type:	`list`

numericalmodel.utils.is_numeric(x)[source]¶

Check if a given value is numeric, i.e. whether numeric operations can be done with it.

Parameters:	x (any) – the input value
Returns:	`True` if the value is numeric, `False` otherwise
Return type:	bool

numericalmodel.utils.utcnow()[source]¶

Get the current utc unix timestamp, i.e. the utc seconds since 01.01.1970.

Returns:	the current utc unix timestamp in seconds
Return type:	float