reno.components.TrackedReference

class reno.components.TrackedReference(eq=None, label=None, doc=None, min=None, max=None, init=None, dim=1, group='', cgroup='', dtype=None)

Bases: Reference

A reference that keeps a matrix of all its values over a simulation for caching and reporting purposes. This is the base class for the fancier components: Flow, Variable, and Stock.

Probably should be using one of the subclasses of this.

A reminder that when Flows and Vars are evaluated, they are based on the current timestep, e.g.:

` flow1(t) = flow2(t) + var1(t) `

As opposed to stocks, whose update equations are based on timestep t-1. This means that flows and vars should not have circular references (causing infinite recursion errors.)

Note

The shape of the value of a tracked reference depends on _sample_dim and _static with the following cases:

1. if _static and not _sample_dim:

   • raw value (float or int)

   • (dim,) (when dim > 1)

2. if _static and _sample_dim:

   • (sample,)

   • (sample, dim) (when dim > 1)

3. if not _static:

   • (sample, t)

   • (sample, t, dim) (when dim > 1)

computed_mask similarly varies based on these cases:

1. bool

2. numpy array of bools with shape (sample,)

3. numpy array of bools with shape (sample, timesteps)

Methods

__init__([eq, label, doc, min, max, init, ...])	Create a TrackedReference node, this is likely only called from subclasses.
astype(dtype)	Returns a symbolic operation to convert the output of this equation to the specified type.
clip(min, max)	Returns a symbolic operation for enforcing the output is between the passed min and max.
equal(obj)	Returns a symbolic operation for checking equality with passed object.
eval([t, save, force])	Compute the equation for the given timestep.
find_parts_of_type(search_type[, ...])	Recursively search for all EquationParts in the tree of the specified type.
from_dict(data, refs)	Deserialize reference and parse data from dictionary previously saved from to_dict().
get_shape()	Get the size of the additional "data" dimension.
get_type()	Get the type of the target output of this equation expression.
history(index_eq)	Get a reference to a previous value of this reference.
initial_vals()	Assign the starting values for t=0, this is the first step of the simulation.
is_static()	Convenience shortcut for reno.utils.is_static() - True if this equation doesn't rely on any dynamic values (thus constant), False if it does.
latex(**kwargs)	String representation suitable for a latex display.
max_refs()	Get any references found in the max constraint equation.
mean([axis])	Returns a symbolic operation to find the series-wise mean of the array.
min_refs()	Get any references found in the min constraint equation.
not_equal(obj)	Returns a symbolic operation for checking inequality with passed object.
plot([ax])	Plot (or add to passed axes) this reference's values.
populate(n, steps)	Initialize the matrix of values with size n x steps.
pt(**refs)	Get a pytensor graph representing this piece of an equation.
pt_str(**refs)	Construct a string containing relevant pytensor code for this piece of the equation.
qual_name([dot])	Get a string with both the model and the reference name if this model is a submodel of something else.
resolve_init_array(obj_or_eq)	Convert a number or scalar/distribution into correct starting array.
seek_refs([include_ref_types])	Recursively find a list of all References immediately underneath this part.
series_max()	Returns a symbolic operation to find the series-wise maximum of the array.
series_min()	Returns a symbolic operation to find the series-wise minimum of the array.
sum([axis])	Returns a symbolic operation to find the series-wise sum of the array.
to_dict()	Serialize class into a dictionary for saving to file.

Attributes

dtype	The type of each underlying value.
shape	The size of the data dimension, 1 by default.
timeseries	Returns symbolic operation for getting a timeseries view of the data.
model	Keep a reference to container model, makes it easier to compare refs across multiple models.
init	Initial value/equation for initial value for stock/flow/var at t=0
dim	Size of an optional extra dimension, allowing a given reference to describe a vector of values at every timestep.
implicit	Implicit components (normally created as subcomponents of more advanced operations) don't show up in diagrams, latex, or output JSON, since they are created by operations.
computed_mask	Follows same shape as value (up through first two dimensions), set of booleans indicating which values have already been evaluated and saved.
label	Label is what's used in any visual representation (e.g. allows spaces where name does not.).
doc	A docstring to explain/describe the reference.

Parameters:

• eq (EquationPart)

• label (str)

• doc (str)

• min (EquationPart)

• max (EquationPart)

• init (int | float | Distribution | Scalar | EquationPart)

• dim (int)

• group (str)

• cgroup (str | list[str])

• dtype (type)

__annotations__ = {}

__module__ = 'reno.components'

__repr__()

Return repr(self).

Return type:

str

computed_mask: ndarray | bool

Follows same shape as value (up through first two dimensions), set of booleans indicating which values have already been evaluated and saved.

dim: int

Size of an optional extra dimension, allowing a given reference to describe a vector of values at every timestep. A value of 1 implying no extra dimension.

eval(t=0, save=False, force=False, **kwargs)

Compute the equation for the given timestep. If we’ve already computed for this step (indicated by a value in the matrix that is not NaN), return that instead (unless told otherwise with force=True).

Note that evaluation output is only stored in the tracking matrix if save is True, this class and subclasses are why save is being passed through all other .eval() methods.

Parameters:

• t (int)

• save (bool)

• force (bool)

• kwargs (dict)

Return type:

int | float | ndarray

from_dict(data, refs)

Deserialize reference and parse data from dictionary previously saved from to_dict().

Parameters:

• data (dict)

• refs (dict[str, TrackedReference])

Return type:

None

get_shape()

Get the size of the additional “data” dimension.

Prefer using shape property over directly calling this function.

If a dim was specified on this instance, that will be returned unless the the shape of the sub-equation output doesn’t match.

Return type:

int

get_type()

Get the type of the target output of this equation expression.

Prefer using dtype property over directly calling this function.

If a dtype was specified on this instance, that type will be returned.

Return type:

type

history(index_eq)

Get a reference to a previous value of this reference.

Parameters:

index_eq (EquationPart) – An equation defining the timestep in this ref’s historical values to use. Note that currently, pymc conversions only support static time-based equations, e.g. t - 3.

Return type:

HistoricalValue

implicit: bool

Implicit components (normally created as subcomponents of more advanced operations) don’t show up in diagrams, latex, or output JSON, since they are created by operations.

init: int | float | Distribution | Scalar | EquationPart

Initial value/equation for initial value for stock/flow/var at t=0

initial_vals()

Assign the starting values for t=0, this is the first step of the simulation.

Subclasses that have a special way of defining the initial set of values (e.g. stocks with their _0 values) can override this function, automatically called at the end of populate().

Return type:

None

max_refs()

Get any references found in the max constraint equation.

Currently mostly only used to aid in diagrams.

Return type:

list

min_refs()

Get any references found in the min constraint equation.

Currently mostly only used to aid in diagrams.

Return type:

list

model

Keep a reference to container model, makes it easier to compare refs across multiple models.

plot(ax=None, **figargs)

Plot (or add to passed axes) this reference’s values. Note that this entails a simulation having already run.

Note that this will plot as a distribution for variables.

Parameters:

• ax (matplotlib.axes.Axes) – Optional, add this reference’s values to a pre-existing plot.

• **figargs (dict) – If no axes passed, use these args in the plt.subplots(**figargs) call.

Return type:

Axes

populate(n, steps)

Initialize the matrix of values with size n x steps.

Parameters:

• n (int) – The number of samples to simulate.

• steps (int) – How many steps will be run in the simulation.

Return type:

None

pt(**refs)

Get a pytensor graph representing this piece of an equation.

Parameters:

refs (dict[str, TensorVariable])

Return type:

TensorVariable

pt_str(**refs)

Construct a string containing relevant pytensor code for this piece of the equation. This is useful for “compiling” into pymc code.

Parameters:

refs (dict[str, str])

Return type:

str

qual_name(dot=False)

Get a string with both the model and the reference name if this model is a submodel of something else.

This is primarily used for helping distinguish things in a multimodel setup.

Parameters:

dot (bool)

Return type:

str

resolve_init_array(obj_or_eq)

Convert a number or scalar/distribution into correct starting array.

Can be used within initial_vals subclass definition.

Parameters:

obj_or_eq (int | float | ndarray | EquationPart)

Return type:

int | float | ndarray

to_dict()

Serialize class into a dictionary for saving to file.

Return type:

dict