Variables

When you parse a system, you get its states, parameters and observables as a VariableSet ordered by name. States and parameters keep their default values in a ValuedSet. A ParameterSet also records whether you sweep each parameter in a batch solve or fix it at a value, and you get a new one for each combination of swept parameters and fixed values you solve with.

class cubie.odesystems.variables.Variable(name, unit='dimensionless')[source]

Bases: object

A named quantity the equations read or produce.

Parameters:

  • name (str) – Symbol name, unique within its set.

  • unit (str) – Unit string, shown in result legends.

name: str
unit: str
class cubie.odesystems.variables.State(name, unit='dimensionless', default=0.0)[source]

Bases: Variable

A state variable.

Parameters:

default (float) – Initial value a run starts from when the caller gives none.

default: float
class cubie.odesystems.variables.Parameter(name, unit='dimensionless', default=0.0)[source]

Bases: Variable

A parameter.

Parameters:

default (float) – Value used when a batch neither sweeps the parameter nor gives it a value.

default: float
class cubie.odesystems.variables.CompiledParameter(name, unit='dimensionless', swept=False, value: float | None = None)[source]

Bases: Variable

A parameter that is either swept or fixed at a value.

The generated code reads a swept parameter from the parameters array in each run, and writes a fixed parameter’s value into the source as a constant. Give a swept parameter no value, and give a fixed parameter its value.

Parameters:

  • swept (bool) – True to read the parameter from the parameters array in each run.

  • value (float | None) – The value of a fixed parameter, or None for a swept parameter.

Raises:

ValueError – If a swept parameter has a value or a fixed one has none.

swept: bool
value: float | None
class cubie.odesystems.variables.VariableSet(entries)[source]

Bases: object

An ordered, immutable set of variables.

The order is the layout of every array that holds one value per variable, so a variable’s index is its row in those arrays.

Parameters:

entries (Tuple[cubie.odesystems.variables.Variable, ...]) – The variables, in array order.

property empty: bool

Whether the set holds no variables.

entries: Tuple[Variable, ...]
get_indices(keys_or_indices: str | int | slice | List[str | int] | ndarray, silent: bool = False) → ndarray[source]

Convert names, indices or a slice into an index array.

Parameters:

  • keys_or_indices – A name, an index, a slice, or a sequence of names or of indices.

  • silent – Skip names that are not in the set instead of raising.

Returns:

int32 row indices.

Return type:

numpy.ndarray

Raises:

  • KeyError – If a name is not in the set and silent is False.

  • IndexError – If an index is out of range.

  • TypeError – If the input mixes names and indices or has another type.

get_labels(indices: List[int] | ndarray) → List[str][source]

Return the names at indices.

index(name: str) → int[source]

Return the row of the variable called name.

Raises:

KeyError – If no variable has that name.

property n: int

Number of variables.

property names: Tuple[str, ...]

Variable names, in array order.

classmethod of(kind: Type[Variable], values: Mapping[str, float] | Iterable[str] | None, units: Mapping[str, str] | None = None) → VariableSet[source]

Build a set of kind records from names or defaults.

Parameters:

  • kind – Variable, State or Parameter.

  • values – Names mapped to defaults, or bare names, in array order. Bare names of a valued kind default to 0.0.

  • units – Unit strings by name; names left out are dimensionless.

Returns:

A ValuedSet for states or parameters, and a plain set for valueless variables.

Return type:

VariableSet

subset(names: Iterable[str]) → VariableSet[source]

Return the named variables as a set, in this set’s order.

Parameters:

names – Names of variables in this set, in any order.

Raises:

KeyError – If a name is not in the set.

property units: Dict[str, str]

Unit string of each variable, by name.

without_values() → VariableSet[source]

Return the names and units of this set, with no defaults.

class cubie.odesystems.variables.ValuedSet(entries)[source]

Bases: VariableSet

A set of states or parameters, with their defaults.

Parameters:

entries (Tuple[cubie.odesystems.variables.Variable, ...]) – The State or Parameter records, in array order.

property defaults: Dict[str, float]

Default value of each variable, by name, in array order.

defaults_array(precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64]) → ndarray[source]

Return the defaults as an array of precision.

entries: Tuple[Variable, ...]
with_defaults(values: Mapping[str, float]) → ValuedSet[source]

Return a copy with new defaults for the named variables.

Parameters:

values – Names mapped to new default values.

Raises:

KeyError – If a name is not in the set.

class cubie.odesystems.variables.ParameterSet(entries)[source]

Bases: VariableSet

The swept and fixed parameters of a specialised system.

Hold one CompiledParameter per parameter, in the system’s parameter order, and no defaults. Pass parameter arrays with one row per swept parameter, in that order.

Parameters:

entries (Tuple[cubie.odesystems.variables.Variable, ...]) – One CompiledParameter per parameter, in system order.

static _resolve(parameters: ValuedSet, swept: Iterable[str], values: Mapping[str, float] | None) → Tuple[Tuple[str, bool, float | None], ...][source]

Return (name, swept, value) for every parameter, in order.

Raises:

  • KeyError – If a name is not a parameter.

  • ValueError – If a swept name repeats or also has a value.

classmethod build(parameters: ValuedSet, swept: Iterable[str] = (), values: Mapping[str, float] | None = None) → ParameterSet[source]

Return the set that sweeps swept and fixes the others.

Parameters:

  • parameters – The declared parameters with their default values.

  • swept – Names of the parameters to sweep, in any order. Pass parameter arrays with one row per swept parameter, in the system’s parameter order.

  • values – Fixed values for a subset of the other parameters. build fixes every parameter neither swept nor named here at its default value.

Returns:

The swept and fixed parameters.

Return type:

ParameterSet

Raises:

  • KeyError – If a name is not a parameter.

  • ValueError – If a swept name repeats or also has a value.

entries: Tuple[Variable, ...]
property fixed: Dict[str, float]

The fixed value of every parameter that is not swept.

property swept: Tuple[str, ...]

Names of the swept parameters, in row order.