Calculation

Calculation.calculate	The main method of a calculation
Calculation.indices	For a given variable name, return the appropriate positions in the vector
Calculation.mass_vector	Each entry corresponds to an equation.
Calculation.__len__	Number of slots used by the calculation, meaning length of calculate()'s output
Calculation.variables	All variables owned by calculation
Calculation.load	Given a state of the calculation, return the untagged corresponding array, which may be used to calculate the next step.
Calculation.save	Given input for "calculate" (which is a legal state of the system), tag the information, i.e. create a "State" and return it.
Calculation.__repr__
Calculation.should_continue	A function to be used in transient calculations to determine stopping conditions at physical states of a system.
Calculation.change_state	A function to be used in transient calculations called at physical states of a system.

A module defining what is a Calculation, in the sense of a first order in time differential and algebraic system of equation. A Calculation is a subset of such a system.

class Calculation(*args, **kwargs)

Bases: Protocol

A calculation in the context of STREAM is derived from the following DAE, which is a first order in time differential and algebraic equation: \(M\frac{d\vec{y}}{dt} = \vec{F}\left(\vec{y}, t\right)\)

Where \(M_{ii}=1,0\) is the matrix defining whether \(F_i(\vec{y}, t)\) is the differential or an algebraic equation \(F_i(\vec{y},t) = 0\). \(\vec{y}\) is the variable vector, from which a subset is the input for each individual calculation. The calculation yields a subset of \(F(\vec{y}, t)\), for which it is deemed the unique owner.

Therefore,

Note

One may say that a Calculation is a subset of \(\vec{F} \left(\vec{y}, t\right)\)

Three kinds of inputs are distinguished:

1. Model Parameters: Attributes of the calculation itself, independent of all other inputs. Supposedly, these are component and physical constants.

2. Input Functions: These are functions through which a user may interfere with a system. Namely, they are only time-dependent. A calculation should not be made aware of the separation between them and Variables.

3. Variables: These are the main input for a calculation. Every property having distinct time dependence which is not user defined is a variable.

abstractmethod calculate(variables, **_)

The main method of a calculation

Parameters:

variables (Sequence[float]) – the variables required for the calculation, which the calculation handles itself.

Return type:

ndarray

Requested external variables can be passed via keyword arguments.

Returns:

Output results – subset of the differential/algebraic functional result.

Return type:

Array1D

Parameters:

variables (Sequence[float])

change_state(variables, **_)

A function to be used in transient calculations called at physical states of a system. If the calculation has an internal state which depends on the physical state, this state should be changed here.

This function’s inputs should equal those of save and calculate.

Parameters:

variables (Sequence[float]) – Input

indices(variable, asking=None)

For a given variable name, return the appropriate positions in the vector

Parameters:

• variable (Name) – Name of requested variable

• asking (Calculation or None) – What calculation is asking for the indices? For example, this is important in Kirchhoff.

Returns:

indices – The place in which the calculation uses the variable, or a dictionary with variable names related to this name and their places.

Return type:

Place or dict[Calculation, Place]

load(state)

Given a state of the calculation, return the untagged corresponding array, which may be used to calculate the next step.

The default method implemented here assumes the state is completely described by the variables presented in self.variables.

Parameters:

state (CalcState) – Tagged information regarding system state

Returns:

y – Calculation ready array

Return type:

Array1D

save(vector, **_)

Given input for “calculate” (which is a legal state of the system), tag the information, i.e. create a “State” and return it.

The default method implemented here assumes the state is completely described by the variables presented in self.variables. This may not be the best descriptor of the state, as there can be more favourable expressions. This is the separation between strict_save, which is the vanilla version described above, and save, which should be free to add other keys to the “State”.

Parameters:

vector (Sequence[float]) – Input

Returns:

state – Tagged information regarding system state

Return type:

CalcState

should_continue(variables, **_)

A function to be used in transient calculations to determine stopping conditions at physical states of a system. Returning False signals the calculation is to be stopped. Logging the reason is encouraged.

This function’s inputs should equal those of save and calculate.

Note

Implementation in Aggregator dictates the change_state method is called right before should_continue, with the same input.

Parameters:

variables (Sequence[float]) – Input

Returns:

should_continue – Should the transient simulation continue?

Return type:

bool

strict_save(vector, **_)

Given input for “calculate” (which is a legal state of the system), tag the information, i.e. create a “State” and return it.

The default method implemented here assumes the state is completely described by the variables presented in self.variables. This may not be the best descriptor of the state, as there can be more favourable expressions. This is the separation between strict_save, which is the vanilla version described above, and save, which should be free to add other keys to the “State”.

Parameters:

vector (Sequence[float]) – Input

Returns:

state – Tagged information regarding system state

Return type:

CalcState

abstract property mass_vector: Sequence[bool]

Each entry corresponds to an equation. For each entry the value is either 0 or 1:

0. Algebraic equation \(F(\vec{y},t)=0\)

1. Differential equation \(\dot{y}=F(\vec{y},t)\)

Returns:

mass – The “mass” of each variable under this calculation’s control. Values are 0 for algebraically defined terms and 1 for differentially defined terms.

Return type:

Sequence[bool]

name: str

abstract property variables: dict[str, int | slice | ndarray]

All variables owned by calculation

unpacked(calculate=None, *, exclude=())

This is a decorator for Calculation methods (calculate and save, mostly), to be applied when the origin of the external variables is unimportant.

Parameters:

• calculate (callable) – Calculation.calculate actualized method

• exclude (Iterable[str]) – Which variables to exclude from unpacking

Returns:

calculate* – The method which now receives its keyword arguments as np.arrays or as floats and not a dictionary

Return type:

callable