Primitives (Basic Objects)

Typing helpers

pymbolic.Bool = bool | numpy.bool

Represent a PEP 604 union type

E.g. for int | str

pymbolic.RealNumber = int | numpy.integer | float | numpy.floating

Represent a PEP 604 union type

E.g. for int | str

Mainly distinguished from Number by having a total ordering, i.e. not including the complex numbers.

pymbolic.Number = int | numpy.integer | float | complex | numpy.inexact

Represent a PEP 604 union type

E.g. for int | str

pymbolic.Scalar = int | numpy.integer | float | complex | numpy.inexact | bool | numpy.bool

Represent a PEP 604 union type

E.g. for int | str

pymbolic.ArithmeticExpression

A narrower type alias than Expression that is returned by arithmetic operators, to allow continue doing arithmetic with the result. alias of int | integer | float | complex | inexact | ExpressionNode

pymbolic.typing.Expression

A union of types that are considered as part of an expression tree.

alias of int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, …]

Note

For backward compatibility, pymbolic.Expression will alias pymbolic.primitives.ExpressionNode for now. Once its deprecation period is up, it will be removed, and then, in the further future, pymbolic.Expression may become this type alias.

class pymbolic.typing.ArithmeticOrExpressionT

A type variable that can be either an ArithmeticExpression or an Expression.

alias of TypeVar(‘ArithmeticOrExpressionT’, int | ~numpy.integer | float | complex | ~numpy.inexact | ExpressionNode, int | ~numpy.integer | float | complex | ~numpy.inexact | bool | ~numpy.bool | ExpressionNode | tuple[Expression, …])

Expression base class

class pymbolic.ExpressionNode

Superclass for parts of a mathematical expression. Overrides operators to implicitly construct Sum, Product and other expressions.

Expression objects are immutable.

Changed in version 2022.2: PEP 634-style pattern matching is now supported.

property a: _AttributeLookupCreator

Provide a spelling expr.a.name for encoding attribute lookup.

attr(name: str) → Lookup

Return a Lookup for name in self.

mapper_method: ClassVar[str]

The pymbolic.mapper.Mapper method called for objects of this type.

__getitem__(subscript: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...] | EmptyOK) → ExpressionNode

Return an expression representing self[subscript].

make_stringifier(originating_stringifier=None)

Return a pymbolic.mapper.Mapper instance that can be used to generate a human-readable representation of self. Usually a subclass of pymbolic.mapper.stringifier.StringifyMapper.

Parameters:

originating_stringifier – If provided, the newly created stringifier should carry forward attributes and settings of originating_stringifier.

__eq__(other) → bool

Provides equality testing with quick positive and negative paths based on id() and __hash__().

__hash__() → int

Provides caching for hash values.

__str__() → str

Use the make_stringifier() to return a human-readable string representation of self.

__repr__() → str

Return repr(self).

Logical operator constructors

not_() → LogicalNot

Return self wrapped in a LogicalNot.

Added in version 2015.2.

and_(other) → LogicalAnd

Return LogicalAnd between self and other.

Added in version 2015.2.

or_(other) → LogicalOr

Return LogicalOr between self and other.

Added in version 2015.2.

Comparison constructors

eq(other) → Comparison

Return a Comparison comparing self to other.

Added in version 2015.2.

ne(other) → Comparison

Return a Comparison comparing self to other.

Added in version 2015.2.

lt(other) → Comparison

Return a Comparison comparing self to other.

Added in version 2015.2.

le(other) → Comparison

Return a Comparison comparing self to other.

Added in version 2015.2.

gt(other) → Comparison

Return a Comparison comparing self to other.

Added in version 2015.2.

ge(other) → Comparison

Return a Comparison comparing self to other.

Added in version 2015.2.

pymbolic.expr_dataclass(init: bool = True, eq: bool = True, hash: bool = True) → Callable[[type[_T]], type[_T]]

A class decorator that makes the class a dataclass() while also adding functionality needed for ExpressionNode. Specifically, it adds cached hashing, equality comparisons with self is other shortcuts as well as some methods/attributes for backward compatibility (e.g. __getinitargs__, init_arg_names).

It also adds a ExpressionNode.mapper_method based on the class name if not already present. If mapper_method is inherited, it will be viewed as unset and replaced.

Note that the class to which this decorator is applied need not be a subclass of ExpressionNode.

Added in version 2024.1.

class pymbolic.Variable(name: str)

Bases: Leaf

name: str

mapper_method: ClassVar[str] = 'map_variable'

Expressions

class pymbolic.primitives.AlgebraicLeaf

Bases: ExpressionNode

An expression that serves as a leaf for arithmetic evaluation. This may end up having child nodes still, but they’re not reached by ways of arithmetic.

mapper_method: ClassVar[str] = 'map_algebraic_leaf'

class pymbolic.primitives.Leaf

Bases: AlgebraicLeaf

An expression that is irreducible, i.e. has no Expression-type parts whatsoever.

mapper_method: ClassVar[str] = 'map_leaf'

class pymbolic.primitives.Wildcard

Bases: Leaf

A general wildcard that can be used to substitute expressions.

mapper_method: ClassVar[str] = 'map_wildcard'

class pymbolic.primitives.DotWildcard(name: str)

Bases: Leaf

A wildcard that can be substituted for a single expression.

mapper_method: ClassVar[str] = 'map_dot_wildcard'

class pymbolic.primitives.StarWildcard(name: str)

Bases: Leaf

A wildcard that can be substituted by a sequence of expressions of non-negative length.

mapper_method: ClassVar[str] = 'map_star_wildcard'

Function Calls

class pymbolic.primitives.Call(function: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], parameters: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])

Bases: AlgebraicLeaf

A function invocation.

function: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

Evaluates to the function to be called.

parameters: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...]

A tuple of positional parameters.

mapper_method: ClassVar[str] = 'map_call'

class pymbolic.primitives.CallWithKwargs(function: _Expression, parameters: tuple[_Expression, ...], kw_parameters: Mapping[str, _Expression])

Bases: AlgebraicLeaf

A function invocation with keyword arguments.

function: _Expression

Evaluates to the function to be called.

parameters: tuple[_Expression, ...]

A tuple of positional parameters.

kw_parameters: Mapping[str, _Expression]

A dictionary mapping names to arguments.

mapper_method: ClassVar[str] = 'map_call_with_kwargs'

class pymbolic.primitives.Subscript(aggregate: int | ~numpy.integer | float | complex | ~numpy.inexact | bool | ~numpy.bool | ~pymbolic.primitives.ExpressionNode | tuple[Expression, ...], index: int | ~numpy.integer | float | complex | ~numpy.inexact | bool | ~numpy.bool | ~pymbolic.primitives.ExpressionNode | tuple[Expression, ...] = <function ExpressionNode.index>)

Bases: AlgebraicLeaf

An array subscript.

mapper_method: ClassVar[str] = 'map_subscript'

class pymbolic.primitives.Lookup(aggregate: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], name: str)

Bases: AlgebraicLeaf

Access to an attribute of an aggregate, such as an attribute of a class.

mapper_method: ClassVar[str] = 'map_lookup'

Sums, products and such

class pymbolic.primitives.Sum(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])

Bases: ExpressionNode

children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...]

__add__(other)

__radd__(other)

__sub__(other)

__bool__()

mapper_method: ClassVar[str] = 'map_sum'

class pymbolic.primitives.Product(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])

Bases: ExpressionNode

children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...]

__mul__(other)

__rmul__(other)

__bool__()

mapper_method: ClassVar[str] = 'map_product'

class pymbolic.primitives.Min(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])

Bases: ExpressionNode

children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...]

mapper_method: ClassVar[str] = 'map_min'

class pymbolic.primitives.Max(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])

Bases: ExpressionNode

children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...]

mapper_method: ClassVar[str] = 'map_max'

class pymbolic.primitives.Quotient(numerator: ArithmeticExpression, denominator: ArithmeticExpression)

Bases: ExpressionNode

numerator: ArithmeticExpression

denominator: ArithmeticExpression

mapper_method: ClassVar[str] = 'map_quotient'

class pymbolic.primitives.FloorDiv(numerator: ArithmeticExpression, denominator: ArithmeticExpression)

Bases: ExpressionNode

numerator: ArithmeticExpression

denominator: ArithmeticExpression

mapper_method: ClassVar[str] = 'map_floor_div'

class pymbolic.primitives.Remainder(numerator: ArithmeticExpression, denominator: ArithmeticExpression)

Bases: ExpressionNode

numerator: ArithmeticExpression

denominator: ArithmeticExpression

mapper_method: ClassVar[str] = 'map_remainder'

class pymbolic.primitives.Power(base: ArithmeticExpression, exponent: ArithmeticExpression)

Bases: ExpressionNode

base: ArithmeticExpression

exponent: ArithmeticExpression

mapper_method: ClassVar[str] = 'map_power'

Shift operators

class pymbolic.primitives.LeftShift(shiftee: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], shift: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...])

Bases: ExpressionNode.

shiftee: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

shift: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

mapper_method: ClassVar[str] = 'map_left_shift'

class pymbolic.primitives.RightShift(shiftee: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], shift: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...])

Bases: ExpressionNode.

shiftee: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

shift: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

mapper_method: ClassVar[str] = 'map_right_shift'

Bitwise operators

class pymbolic.primitives.BitwiseNot(child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...])

Bases: ExpressionNode

child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

mapper_method: ClassVar[str] = 'map_bitwise_not'

class pymbolic.primitives.BitwiseOr(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])

Bases: ExpressionNode

children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...]

mapper_method: ClassVar[str] = 'map_bitwise_or'

class pymbolic.primitives.BitwiseXor(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])

Bases: ExpressionNode

children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...]

mapper_method: ClassVar[str] = 'map_bitwise_xor'

class pymbolic.primitives.BitwiseAnd(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])

Bases: ExpressionNode

children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...]

mapper_method: ClassVar[str] = 'map_bitwise_and'

Comparisons and logic

class pymbolic.primitives.Comparison(left: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], operator: str, right: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...])

Bases: ExpressionNode

left: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

operator: str

One of [">", ">=", "==", "!=", "<", "<="].

right: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

Note

Unlike other expressions, comparisons are not implicitly constructed by comparing ExpressionNode objects. See pymbolic.ExpressionNode.eq() and related.

operator_to_name: ClassVar[dict[str, str]] = {'!=': 'ne', '<': 'lt', '<=': 'le', '==': 'eq', '>': 'gt', '>=': 'ge'}

name_to_operator: ClassVar[dict[str, str]] = {'eq': '==', 'ge': '>=', 'gt': '>', 'le': '<=', 'lt': '<', 'ne': '!='}

mapper_method: ClassVar[str] = 'map_comparison'

class pymbolic.primitives.LogicalNot(child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...])

Bases: ExpressionNode

child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

mapper_method: ClassVar[str] = 'map_logical_not'

class pymbolic.primitives.LogicalAnd(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])

Bases: ExpressionNode

children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...]

mapper_method: ClassVar[str] = 'map_logical_and'

class pymbolic.primitives.LogicalOr(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])

Bases: ExpressionNode

children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...]

mapper_method: ClassVar[str] = 'map_logical_or'

class pymbolic.primitives.If(condition: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], then: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], else_: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...])

Bases: ExpressionNode

condition: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

then: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

else_: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

mapper_method: ClassVar[str] = 'map_if'

Slices

class pymbolic.primitives.Slice(children: tuple[()] | tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...] | None] | tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...] | None, int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...] | None] | tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...] | None, int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...] | None, int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...] | None])

Bases: ExpressionNode

A slice expression as in a[1:7].

children: tuple[()] | tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...] | None] | tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...] | None, int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...] | None] | tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...] | None, int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...] | None, int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...] | None]

property start

property stop

property step

mapper_method: ClassVar[str] = 'map_slice'

Code generation helpers

class pymbolic.primitives.CommonSubexpression(child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], prefix: str | None = None, scope: str = 'pymbolic_eval')

Bases: ExpressionNode

A helper for code generation and caching. Denotes a subexpression that should only be evaluated once. If, in code generation, it is assigned to a variable, a name starting with prefix should be used.

child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

prefix: str | None = None

scope: str = 'pymbolic_eval'

One of the values in cse_scope. See there for meaning.

See pymbolic.mapper.c_code.CCodeMapper for an example.

mapper_method: ClassVar[str] = 'map_common_subexpression'

class pymbolic.primitives.cse_scope

Determines the lifetime for the saved value of a CommonSubexpression.

EVALUATION: str

The evaluated result lives for the duration of the evaluation of the current expression and is discarded thereafter.

EXPRESSION: str

The evaluated result lives for the lifetime of the current expression (across multiple evaluations with multiple parameters) and is discarded when the expression is.

GLOBAL: str

The evaluated result lives until the execution context dies.

pymbolic.primitives.make_common_subexpression(expr: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], prefix: str | None = None, scope: str | None = None, *, wrap_vars: bool = True) → int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

Wrap expr in a CommonSubexpression with prefix.

If expr is a numpy object array, each individual entry is instead wrapped. If expr is a pymbolic.geometric_algebra.MultiVector, each coefficient is individually wrapped. In general, the function tries to avoid re-wrapping existing CommonSubexpression if the same scope is given.

See CommonSubexpression for the meaning of prefix and scope. The scope defaults to cse_scope.EVALUATION.

Parameters:

wrap_vars – If True, this also wraps a Variable and its subscripts. Otherwise, these expressions are returned as is.

Symbolic derivatives and substitution

Inspired by similar functionality in sympy.

class pymbolic.primitives.Substitution(child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], variables: tuple[str, ...], values: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])

Bases: ExpressionNode

Work-alike of Subs.

child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

variables: tuple[str, ...]

values: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...]

mapper_method: ClassVar[str] = 'map_substitution'

class pymbolic.primitives.Derivative(child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], variables: tuple[str, ...])

Bases: ExpressionNode

Work-alike of sympy’s Derivative.

child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]

variables: tuple[str, ...]

mapper_method: ClassVar[str] = 'map_derivative'

Helper functions

pymbolic.primitives.is_zero(value: object) → bool

pymbolic.primitives.is_constant(value: object) → TypeIs[int | integer | float | complex | inexact | bool | bool]

pymbolic.primitives.is_expression(value: object) → TypeIs[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]]

Added in version 2024.2.3.

pymbolic.primitives.is_arithmetic_expression(value: object) → TypeIs[ArithmeticExpression]

pymbolic.primitives.flattened_sum(terms: Iterable[ArithmeticExpression]) → ArithmeticExpression

Recursively flattens all the top level Sums in terms.

Parameters:

terms – an Iterable of expressions.

Returns:

a Sum expression or, if there is only one term in the sum, the respective term.

pymbolic.primitives.flattened_product(terms: Iterable[ArithmeticExpression]) → ArithmeticExpression

Recursively flattens all the top level Products in terms.

This operation does not change the order of the terms in the products, so it does not require the product to be commutative.

Parameters:

terms – an Iterable of expressions.

Returns:

a Product expression or, if there is only one term in the product, the respective term.

pymbolic.primitives.register_constant_class(class_)

pymbolic.primitives.unregister_constant_class(class_)

pymbolic.primitives.variables(s)

Return a list of variables for each (space-delimited) identifier in s.

Interaction with numpy arrays

numpy.ndarray instances are supported anywhere in an expression. In particular, numpy object arrays are useful for capturing vectors and matrices of pymbolic objects.

pymbolic.primitives.make_sym_vector(name, components, var_factory=<class 'pymbolic.primitives.Variable'>)

Return an object array of components subscripted Variable (or subclass) instances.

Parameters:

• components – Either a list of indices, or an integer representing the number of indices.

• var_factory – The Variable subclass to use for instantiating the scalar variables.

For example, this creates a vector with three components:

>>> make_sym_vector("vec", 3)
array([Subscript(Variable('vec'), 0), Subscript(Variable('vec'), 1),
       Subscript(Variable('vec'), 2)], dtype=object)

pymbolic.primitives.make_sym_array(name, shape, var_factory=<class 'pymbolic.primitives.Variable'>)

Constants

class pymbolic.primitives.NaN(data_type: Callable[[float], Any] | None = None)

Bases: AlgebraicLeaf

An expression node representing not-a-number as a floating point number. Unlike, math.nan, all instances of NaN compare equal, as one might reasonably expect for program representation. (If this weren’t so, programs containing NaNs would effectively be unhashable, because they don’t compare equal to themselves.)

Note that, in Python, this equality comparison is made even more complex by this issue, due to which np.nan == np.nan is False, but (np.nan,) == (np.nan,) is True.

data_type: Callable[[float], Any] | None = None

The data type used for the actual realization of the constant. Defaults to None. If given, This must be a callable to which a NaN float can be passed to obtain a NaN of the yield the desired type. It must also be suitable for use as the second argument of isinstance().

mapper_method: ClassVar[str] = 'map_nan'

Helper classes

class pymbolic.primitives.EmptyOK(child: '_Expression')

class pymbolic.primitives._AttributeLookupCreator(aggregate: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...])

Helper used by pymbolic.ExpressionNode.a to create lookups.

__getattr__(name: str) → Lookup

References

class pymbolic.primitives.DataclassInstance

An instance of a dataclass().

class pymbolic.primitives.ArithmeticExpression

See pymbolic.ArithmeticExpression

class pymbolic.primitives._T

A type variable.

class numpy.bool_

Deprecated alias for numpy.bool.

class typing_extensions.TypeIs

See typing_extensions.TypeIs.

class typing_extensions.Variable

See pymbolic.Variable.

class typing_extensions.Expression

See pymbolic.typing.Expression.

class pymbolic.Comparison

See pymbolic.primitives.Comparison.

class pymbolic.LogicalNot

See pymbolic.primitives.LogicalNot.

class pymbolic.LogicalAnd

See pymbolic.primitives.LogicalAnd.

class pymbolic.LogicalOr

See pymbolic.primitives.LogicalOr.

class pymbolic.Lookup

See pymbolic.primitives.Lookup.