Cells

class Cells(_impl)

Callable object with a formula that computes and caches values based on arguments.

Cells represent formulas in modelx that can compute values for different argument combinations. They function like spreadsheet cells but with parameters, allowing you to define recursive formulas with automatic dependency tracking and caching.

Key Characteristics:

• Callable: Invoke like a function to compute values

• Cached: Results are stored and reused (configurable via is_cached)

• Parameterized: Accept arguments like regular Python functions

• Recursive: Can reference themselves and other cells

• Dependency-tracked: The modelx system tracks formula dependencies automatically

• Dictionary-like (Not available within formulas): Access cached values via subscription (cells[args])

Creation:

Cells can be created in several ways:

Using decorator (recommended):

>>> @mx.defcells
... def present_value(t):
...     if t == 0:
...         return 0
...     return cashflow(t) / (1 + disc_rate()) ** t + present_value(t-1)

Using new_cells method:

>>> def pv_formula(t):  # Can be any valid identifier, such as '_'
...     return cashflow(t) / (1 + disc_rate()) ** t
>>> space.new_cells(name='pv', formula=pv_formula)

Usage:

Cells can be called like functions or accessed like dictionaries:

>>> present_value(10)  # Call with argument
95420.5

>>> present_value[10]  # Access cached value
95420.5

>>> 10 in present_value  # Check if value exists
True

Caching Behavior:

By default, computed values are cached. For unhashable arguments, set is_cached to False:

>>> @mx.defcells
... def process_data(data: list):  # list is unhashable
...     return sum(data)

>>> process_data.is_cached = False
>>> process_data([1, 2, 3])
6

Input vs Calculated Values:

Cells distinguish between input values (assigned directly) and calculated values (computed by formula):

>>> cells[5] = 100  # Input value
>>> cells.is_input(5)
True

>>> cells(10)  # Calculated value
250
>>> cells.is_input(10)
False

See also

defcells(): Decorator to create cells cached(): Decorator for cached cells (default) uncached(): Decorator for uncached cells new_cells(): Create cells programmatically UserSpace: Container for cells

Changed in version 0.1.0: Separated clear() (calculated values only) from clear_all() (all values including input)

Basic properties

name	Name of the object.
fullname	Dotted name of the object.
doc	Documentation string
set_doc(doc[, insert_indents])	Set the doc property
allow_none	Whether a cells can have None as its value.
model	The model this object belongs to.
parent	The parent of this object.
properties
set_property(name, value)	Set property name
is_cached	Property to get or set whether the Cells is cached.
info	An object whose repr summarizes this Interface.

Cells operations

rename(name)	Rename the Cells
copy(parent[, name])	Make a copy of itself

Value operations

clear()	Clear all calculated values.
clear_all()	Clear all values.
clear_at(*args, **kwargs)	Clear value for given arguments.
is_input(*args, **kwargs)	True if this is input.
match(*args, **kwargs)	Returns the best matching args and their value.
value	Get, set, delete the scalar value.

Formula operations

formula	Property to get, set, delete formula.
set_formula(func)	Set formula from a function.
clear_formula()	Clear the formula.
parameters	A tuple of parameter strings.

Node operations

node(*args, **kwargs)	Return a Node object for the given arguments.
preds(*args, **kwargs)	Return a list of predecessors of a cell.
succs(*args, **kwargs)	Return a list of successors of a cell.
precedents(*args, **kwargs)	Return a list of the precedents.

Exporting to Pandas objects

series	Alias of to_series().
frame	Alias of to_frame().
to_series(*args)	Convert the cells itself into a Pandas Series and return it.
to_frame(*args)	Convert the cells itself into a Pandas DataFrame and return it.