reno.components.TrackedReference#

class reno.components.TrackedReference(eq=None, label=None, doc=None, min=None, max=None, init=None, dim=1, group='', 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.)

Parameters:

  • eq (EquationPart) – The equation that describes this reference.

  • label (str) – Visual label for the reference. In the context of a model, is set to the name assigned on the model if not explicitly provided.

  • doc (str) – A docstring/description explaining what this component is.

  • min (EquationPart) – An equation describing the minimum value of this reference.

  • max (EquationPart) – An equation describing the maximum value of this reference.

  • init (int | float | Distribution | Scalar | EquationPart) – The initial value for this component at t = 0.

  • dim (int) – Size of an optional extra dimension, allowing a given reference to describe a vector of values at every timestep. Default is 1 implying no extra dimension.

  • group (str) – An optional string to help group related references together, primarily only used for visually tightening up elements in the stock/flow graphs.

  • dtype (type) – The underlying data type to use, e.g. int or float.

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, ...])

clip(min, max)

equal(obj)

eval([t, save, compute_mask, force])

Compute the equation for the given timestep.

find_refs_of_type(search_type[, already_checked])

Actually recursive as opposed to seek_refs, returns a list of all equation parts matching passed type.

from_dict(data, refs)

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

get_shape()

For now this is returning an integer because we only allow a single additional dimension.

get_type()

Similar to shape, this gets computed recursively, used to automatically determine if the value needs to be initialized with a certain numpy type.

history(index_eq)

Get a reference to a previous value of this reference.

initial_vals()

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().

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.

min_refs()

Get any references found in the min constraint equation.

not_equal(obj)

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()

Immediate refs only, depth=1.

series_max()

series_min()

sum([axis])

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

Get a timeseries view of the data (includes all historical data across all timesteps.)

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.
__annotations__ = {}#
__module__ = 'reno.components'#
__repr__()#

Return repr(self).

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, compute_mask=None, 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)

  • compute_mask (ndarray)

  • force (bool)

Return type:

int | float | ndarray

from_dict(data, refs)#

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

Parameters:
get_shape()#

For now this is returning an integer because we only allow a single additional dimension. Note that this shape _does not_ incoporate time or batch dimensions, only the “data” dimension if applicable. This should be overridden by subclasses, e.g. operations which would change the shape.

Return type:

int

get_type()#

Similar to shape, this gets computed recursively, used to automatically determine if the value needs to be initialized with a certain numpy type.

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.

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()#

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().

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.

populate(n, steps)#

Initialize the matrix of values with size n x steps. All values initially nan to indicate they need to be computed still

Parameters:

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

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

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)

resolve_init_array(obj_or_eq)#

Convert a number or scalar/distribution into correct starting array. Can be used within initial_vals subclass definition.

to_dict()#

Serialize class into a dictionary for saving to file.

Return type:

dict