numbox.core.vector

Overview

Generic growable numba vector backed by a numpy array.

Compared to numba.typed.List:

• List supports arbitrary element types (including other structrefs) and exposes a richer API (append, pop, insert, remove, slicing).

• Vector is restricted to scalar element types where str(elem_type) matches a numpy dtype (float64, int64, etc.). make_vector memoises instances by elem_type.key, so cached code keeps the same type identity across processes. Storage is a single numpy.ndarray, so per-element overhead is the scalar itself plus amortised geometric growth.

Modules

numbox.core.vector.vector

class numbox.core.variable.variable.CompiledGraph(ordered_nodes: list[numbox.core.variable.variable.CompiledNode], required_external_variables: dict[str, dict[str, numbox.core.variable.variable.Variable]], debug: bool = False, dependents: dict[numbox.core.variable.variable.Variable, list[numbox.core.variable.variable.CompiledNode]] = <factory>)

Bases: object

debug: bool = False

dependents: dict[Variable, list[CompiledNode]]

execute(external_values: dict[str, dict[str, Any]], values: Storage)

Main entry point to calculate values of nodes of the compiled graph. Calculation requires the following inputs:

Parameters:

external_values – actual values of all required external

variables, this can be a superset of what is really needed for the calculation. The map is first from the name of the external namespace and then from the name of the variable within that source to the variable’s actual value. :param values: runtime storage of all values, e.g., an instance of Values.

ordered_nodes: list[CompiledNode]

recompute(changed: dict[str, dict[str, Any]], values: Storage)

Parameters:

changed – dict of sources to names to new values of changed

Variable`s coming from either `External or Variables source. :param values: storage of all the Variable values.

required_external_variables: dict[str, dict[str, Variable]]

class numbox.core.variable.variable.CompiledNode(variable: numbox.core.variable.variable.Variable, inputs: list[numbox.core.variable.variable.Variable])

Bases: object

inputs: list[Variable]

variable: Variable

class numbox.core.variable.variable.External(name: str)

Bases: Namespace

An ‘external’ namespace that facilitates discovery of requested names.

When requesting a Variable with the given name via a typical __getitem__ call, if the Variable is not found, it will be created and added to this dictionary. This way the graph will be able to infer which variables are required from the external source abstracted by this namespace.

class numbox.core.variable.variable.Graph(variables_lists: dict[str, list[VarSpec]], external_source_names: list[str])

Bases: object

compile(required: list[str] | str, debug: bool = False) → CompiledGraph

Required:

list of qualified variables names that need to be calculated.

dependents_of(qual_names: list[str] | set[str] | str) → set[str]

Return qualified names of Variable`s that directly or indirectly depend on any of `qual_names.

explain(qual_name: str, right_to_left: bool = True) → str

Follow the dependencies chain to explain how the given variable is derived.

Uses metadata of the Variable instances.

Parameters:

• qual_name – qualified name of the Variable.

• right_to_left – when True (default), begin explanation

with qual_name. That is, move towards the ends of the graph.

class numbox.core.variable.variable.Namespace

Bases: ABC

keys()

name: str

update(key: str, var: Variable) → None

Post-initialization update for dynamically generated `Variable`s.

class numbox.core.variable.variable.Storage(*args, **kwargs)

Bases: Protocol

cache: dict[tuple[Variable, tuple[Any, ...]], Any]

get(variable: Variable) → Value

Principal access point to the requested variable. Instantiates the corresponding value when first invoked for the given variable.

class numbox.core.variable.variable.Value(variable: ~numbox.core.variable.variable.Variable, value: ~typing.Any | ~numbox.core.variable.variable._Null = <factory>)

Bases: object

Value of the corresponding Variable. Best used when created indirectly by the Values storage.

value: Any | _Null

variable: Variable

class numbox.core.variable.variable.Values

Bases: object

Values of all `Variable`s, computed and external, will be held here.

get(variable: Variable) → Value

class numbox.core.variable.variable.VarSpec

Bases: VarSpecBase

cacheable: bool

formula: Callable

inputs: dict[str, str]

metadata: str

name: str

class numbox.core.variable.variable.VarSpecBase

Bases: TypedDict

name: str

class numbox.core.variable.variable.Variable(name: str, source: str = '', inputs: ~typing.Mapping[str, str] = <factory>, formula: ~typing.Callable = None, metadata: str | None = None, cacheable: bool = False)

Bases: object

An instance of Variable is anything that can be calculated from the values of the given inputs dependencies using the provided formula (i.e., a Python function).

Calculated value can be None, that is why a non-calculated value is designated with _null.

An instance of Variable is best created within the given Namespace. For example, when the Variables subtype of the Namespace is instantiated, it gets populated with the freshly created Variable instances per the VarSpec specifications passed to it. Or, when the External subtype of the Namespace is queried for the given variable name, if a Variable with such a name is not already present in that external namespace, it will be created and stored there.

Parameters:

• name – name of the Variable instance.

• source – name of the Namespace instance which is

the namespace / source of this Variable. :param inputs: (optional) map from names of the Variable inputs (which are names of other Variable instances) to names of their Namespace`s. :param formula: (optional) function that calculates the value of this `Variable from its sources. :param metadata: any possible metadata associated with this variable. :param cacheable: (default False) when True, the corresponding Value (see below) will be cached during calculation. When attempting to recompute with the same inputs, cached value will be returned instead. Use sparingly!

cacheable: bool = False

formula: Callable = None

inputs: Mapping[str, str]

metadata: str | None = None

name: str

qual_name() → str

Qualified name of Variable incorporates both the name of the Variable and the name of its source / namespace.

source: str = ''

class numbox.core.variable.variable.Variables(name: str, variables: list[VarSpec])

Bases: Namespace

numbox.core.variable.variable.make_qual_name(namespace_name: str, var_name: str) → str

Each Variable instance is best initialized in and owned by a Namespace object (such as, instances of External and Variables), with the given namespace_name.

This function thereby returns qualified name of the Variable instance.