Symbol#

pybamm.simplify_if_constant(symbol: Symbol)[source]#: Utility function to simplify an expression tree if it evalutes to a constant scalar, vector or matrix

class pybamm.Symbol(name: str, children: Sequence[Symbol] | None = None, domain: DomainType = None, auxiliary_domains: AuxiliaryDomainType = None, domains: DomainsType = None)[source]#

Base node class for the expression tree.

Parameters:

name (str) – name for the node
children (iterable Symbol, optional) – children to attach to this node, default to an empty list
domain (iterable of str, or str) – list of domains over which the node is valid (empty list indicates the symbol is valid over all domains)
auxiliary_domains (dict of str) – dictionary of auxiliary domains over which the node is valid (empty dictionary indicates no auxiliary domains). Keys can be “secondary”, “tertiary” or “quaternary”. The symbol is broadcast over its auxiliary domains. For example, a symbol might have domain “negative particle”, secondary domain “separator” and tertiary domain “current collector” (domain=”negative particle”, auxiliary_domains={“secondary”: “separator”, “tertiary”: “current collector”}).
domains (dict) – A dictionary equivalent to {‘primary’: domain, auxiliary_domains}. Either ‘domain’ and ‘auxiliary_domains’, or just ‘domains’, should be provided (not both). In future, the ‘domain’ and ‘auxiliary_domains’ arguments may be deprecated.

__abs__() → AbsoluteValue[source]#: return an AbsoluteValue object, or a smooth approximation.

__add__(other: ChildSymbol) → pybamm.Addition[source]#: return an Addition object.

__array_ufunc__(ufunc, method, *inputs, **kwargs)[source]#: If a numpy ufunc is applied to a symbol, call the corresponding pybamm function instead.

__eq__(other)[source]#: Return self==value.

__ge__(other: Symbol) → EqualHeaviside[source]#: return a EqualHeaviside object, or a smooth approximation.

__gt__(other: Symbol) → NotEqualHeaviside[source]#: return a NotEqualHeaviside object, or a smooth approximation.

__hash__()[source]#: Return hash(self).

__init__(name: str, children: Sequence[Symbol] | None = None, domain: DomainType = None, auxiliary_domains: AuxiliaryDomainType = None, domains: DomainsType = None)[source]#

__le__(other: Symbol) → EqualHeaviside[source]#: return a EqualHeaviside object, or a smooth approximation.

__lt__(other: Symbol | float) → NotEqualHeaviside[source]#: return a NotEqualHeaviside object, or a smooth approximation.

__matmul__(other: ChildSymbol) → pybamm.MatrixMultiplication[source]#: return a MatrixMultiplication object.

__mod__(other: Symbol) → Modulo[source]#: return an Modulo object.

__mul__(other: ChildSymbol) → pybamm.Multiplication[source]#: return a Multiplication object.

__neg__() → Negate[source]#: return a Negate object.

__pow__(other: ChildSymbol) → pybamm.Power[source]#: return a Power object.

__radd__(other: ChildSymbol) → pybamm.Addition[source]#: return an Addition object.

__repr__()[source]#: returns the string __class__(id, name, children, domain)

__rmatmul__(other: ChildSymbol) → pybamm.MatrixMultiplication[source]#: return a MatrixMultiplication object.

__rmul__(other: ChildSymbol) → pybamm.Multiplication[source]#: return a Multiplication object.

__rpow__(other: Symbol) → Power[source]#: return a Power object.

__rsub__(other: ChildSymbol) → pybamm.Subtraction[source]#: return a Subtraction object.

__rtruediv__(other: ChildSymbol) → pybamm.Division[source]#: return a Division object.

__str__()[source]#: return a string representation of the node and its children.

__sub__(other: ChildSymbol) → pybamm.Subtraction[source]#: return a Subtraction object.

__truediv__(other: ChildSymbol) → pybamm.Division[source]#: return a Division object.

__weakref__#: list of weak references to the object

property auxiliary_domains#: Returns auxiliary domains.

property children#

returns the cached children of this node.

Note: it is assumed that children of a node are not modified after initial creation

clear_domains()[source]#: Clear domains, bypassing checks.

copy_domains(symbol: Symbol)[source]#: Copy the domains from a given symbol, bypassing checks.

create_copy(new_children: list[Symbol] | None = None, perform_simplifications: bool = True)[source]#

Make a new copy of a symbol, to avoid Tree corruption errors while bypassing copy.deepcopy(), which is slow.

If new_children are provided, they are used instead of the existing children.

If perform_simplifications = True, some classes (e.g. BinaryOperator, UnaryOperator, Concatenation) will perform simplifications and error checks based on the new children before copying the symbol. This may result in a different symbol being returned than the one copied.

Turning off this behaviour to ensure the symbol remains unchanged is discouraged.

diff(variable: Symbol)[source]#

Differentiate a symbol with respect to a variable. For any symbol that can be differentiated, return 1 if differentiating with respect to yourself, self._diff(variable) if variable is in the expression tree of the symbol, and zero otherwise.

Parameters:: variable (pybamm.Symbol) – The variable with respect to which to differentiate

property domain#

list of applicable domains.

Return type:: iterable of str

Evaluate expression tree (wrapper to allow using dict of known values).

Parameters:

t (float or numeric type, optional) – time at which to evaluate (default None)
y (numpy.array, optional) – array with state values to evaluate when solving (default None)
y_dot (numpy.array, optional) – array with time derivatives of state values to evaluate when solving (default None)
inputs (dict, optional) – dictionary of inputs to use when solving (default None)

Returns:

the node evaluated at (t,y)

Return type:

number or array

evaluate_for_shape()[source]#

Evaluate expression tree to find its shape.

For symbols that cannot be evaluated directly (e.g. Variable or Parameter), a vector of the appropriate shape is returned instead, using the symbol’s domain. See pybamm.Symbol.evaluate()

evaluate_ignoring_errors(t: float | None = 0)[source]#

Evaluates the expression. If a node exists in the tree that cannot be evaluated as a scalar or vector (e.g. Time, Parameter, Variable, StateVector), then None is returned. If there is an InputParameter in the tree then a 1 is returned. Otherwise the result of the evaluation is given.

See also

evaluate: evaluate the expression

jac(variable: Symbol, known_jacs: dict[Symbol, Symbol] | None = None, clear_domain=True)[source]#: Differentiate a symbol with respect to a (slice of) a StateVector or StateVectorDot. See pybamm.Jacobian.

property name#: name of the node.

property ndim_for_testing#: Number of dimensions of an object, found by evaluating it with appropriate t and y

property orphans#: Returning new copies of the children, with parents removed to avoid corrupting the expression tree internal data

post_order(filter=None)[source]#: returns an iterable that steps through the tree in post-order fashion.

pre_order()[source]#

returns an iterable that steps through the tree in pre-order fashion.

Examples

>>> a = pybamm.Symbol('a')
>>> b = pybamm.Symbol('b')
>>> for node in (a*b).pre_order():
...     print(node.name)
*
a
b

property quaternary_domain#: Helper function to get the quaternary domain of a symbol.

relabel_tree(symbol: Symbol, counter: int)[source]#: Finds all children of a symbol and assigns them a new id so that they can be visualised properly using the graphviz output

render()[source]#: Print out a visual representation of the tree (this node and its children)

property secondary_domain#: Helper function to get the secondary domain of a symbol.

set_id()[source]#

Set the immutable “identity” of a variable (e.g. for identifying y_slices).

Hashing can be slow, so we set the id when we create the node, and hence only need to hash once.

property shape#: Shape of an object, found by evaluating it with appropriate t and y.

property shape_for_testing#: Shape of an object for cases where it cannot be evaluated directly. If a symbol cannot be evaluated directly (e.g. it is a Variable or Parameter), it is instead given an arbitrary domain-dependent shape.

property size#: Size of an object, found by evaluating it with appropriate t and y

property size_for_testing#: Size of an object, based on shape for testing.

property tertiary_domain#: Helper function to get the tertiary domain of a symbol.

test_shape()[source]#

Check that the discretised self has a pybamm shape, i.e. can be evaluated.

Raises:: pybamm.ShapeError – If the shape of the object cannot be found

to_casadi(t: casadi.MX | None = None, y: casadi.MX | None = None, y_dot: casadi.MX | None = None, inputs: dict | None = None, casadi_symbols: Symbol | None = None)[source]#: Convert the expression tree to a CasADi expression tree. See pybamm.CasadiConverter.

to_json()[source]#: Method to serialise a Symbol object into JSON.

visualise(filename: str)[source]#

Produces a .png file of the tree (this node and its children) with the name filename

Parameters:: filename (str) – filename to output, must end in “.png”