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 ofint
|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 anExpression
.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[source]¶
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.
- 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 [source]¶
Return an expression representing
self[subscript]
.
- make_stringifier(originating_stringifier=None)[source]¶
Return a
pymbolic.mapper.Mapper
instance that can be used to generate a human-readable representation of self. Usually a subclass ofpymbolic.mapper.stringifier.StringifyMapper
.- Parameters:
originating_stringifier – If provided, the newly created stringifier should carry forward attributes and settings of originating_stringifier.
- __eq__(other) bool [source]¶
Provides equality testing with quick positive and negative paths based on
id()
and__hash__()
.
- __str__() str [source]¶
Use the
make_stringifier()
to return a human-readable string representation of self.
Logical operator constructors
- not_() LogicalNot [source]¶
Return self wrapped in a
LogicalNot
.Added in version 2015.2.
- and_(other) LogicalAnd [source]¶
Return
LogicalAnd
between self and other.Added in version 2015.2.
Comparison constructors
- eq(other) Comparison [source]¶
Return a
Comparison
comparing self to other.Added in version 2015.2.
- ne(other) Comparison [source]¶
Return a
Comparison
comparing self to other.Added in version 2015.2.
- lt(other) Comparison [source]¶
Return a
Comparison
comparing self to other.Added in version 2015.2.
- le(other) Comparison [source]¶
Return a
Comparison
comparing self to other.Added in version 2015.2.
- gt(other) Comparison [source]¶
Return a
Comparison
comparing self to other.Added in version 2015.2.
- ge(other) Comparison [source]¶
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]] [source]¶
A class decorator that makes the class a
dataclass()
while also adding functionality needed forExpressionNode
. Specifically, it adds cached hashing, equality comparisons withself 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. Ifmapper_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.
Expressions¶
- class pymbolic.primitives.AlgebraicLeaf[source]¶
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.
- class pymbolic.primitives.Leaf[source]¶
Bases:
AlgebraicLeaf
An expression that is irreducible, i.e. has no Expression-type parts whatsoever.
- class pymbolic.primitives.Wildcard[source]¶
Bases:
Leaf
A general wildcard that can be used to substitute expressions.
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, ...], ...])[source]¶
Bases:
AlgebraicLeaf
A function invocation.
- function: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]¶
Evaluates to the function to be called.
- class pymbolic.primitives.CallWithKwargs(function: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], parameters: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...], kw_parameters: Mapping[str, int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]])[source]¶
Bases:
AlgebraicLeaf
A function invocation with keyword arguments.
- 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.
- 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>)[source]¶
Bases:
AlgebraicLeaf
An array subscript.
- class pymbolic.primitives.Lookup(aggregate: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], name: str)[source]¶
Bases:
AlgebraicLeaf
Access to an attribute of an aggregate, such as an attribute of a class.
Sums, products and such¶
- class pymbolic.primitives.Sum(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])[source]¶
Bases:
ExpressionNode
- class pymbolic.primitives.Product(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])[source]¶
Bases:
ExpressionNode
- class pymbolic.primitives.Min(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])[source]¶
Bases:
ExpressionNode
- class pymbolic.primitives.Max(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])[source]¶
Bases:
ExpressionNode
- class pymbolic.primitives.Quotient(numerator: ArithmeticExpression, denominator: ArithmeticExpression)[source]¶
Bases:
ExpressionNode
- numerator: ArithmeticExpression¶
- denominator: ArithmeticExpression¶
- class pymbolic.primitives.FloorDiv(numerator: ArithmeticExpression, denominator: ArithmeticExpression)[source]¶
Bases:
ExpressionNode
- numerator: ArithmeticExpression¶
- denominator: ArithmeticExpression¶
- class pymbolic.primitives.Remainder(numerator: ArithmeticExpression, denominator: ArithmeticExpression)[source]¶
Bases:
ExpressionNode
- numerator: ArithmeticExpression¶
- denominator: ArithmeticExpression¶
- class pymbolic.primitives.Power(base: ArithmeticExpression, exponent: ArithmeticExpression)[source]¶
Bases:
ExpressionNode
- base: ArithmeticExpression¶
- exponent: ArithmeticExpression¶
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, ...])[source]¶
Bases:
ExpressionNode
.- shiftee: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]¶
- 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, ...])[source]¶
Bases:
ExpressionNode
.- shiftee: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]¶
Bitwise operators¶
- class pymbolic.primitives.BitwiseNot(child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...])[source]¶
Bases:
ExpressionNode
- class pymbolic.primitives.BitwiseOr(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])[source]¶
Bases:
ExpressionNode
- class pymbolic.primitives.BitwiseXor(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])[source]¶
Bases:
ExpressionNode
- class pymbolic.primitives.BitwiseAnd(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])[source]¶
Bases:
ExpressionNode
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, ...])[source]¶
Bases:
ExpressionNode
- left: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]¶
- right: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]¶
Note
Unlike other expressions, comparisons are not implicitly constructed by comparing
ExpressionNode
objects. Seepymbolic.ExpressionNode.eq()
and related.- operator_to_name: ClassVar[dict[str, str]] = {'!=': 'ne', '<': 'lt', '<=': 'le', '==': 'eq', '>': 'gt', '>=': 'ge'}¶
- class pymbolic.primitives.LogicalNot(child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...])[source]¶
Bases:
ExpressionNode
- class pymbolic.primitives.LogicalAnd(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])[source]¶
Bases:
ExpressionNode
- class pymbolic.primitives.LogicalOr(children: tuple[int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], ...])[source]¶
Bases:
ExpressionNode
- 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, ...])[source]¶
Bases:
ExpressionNode
- condition: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]¶
- then: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]¶
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])[source]¶
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¶
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')[source]¶
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, ...]¶
See
pymbolic.mapper.c_code.CCodeMapper
for an example.
- class pymbolic.primitives.cse_scope[source]¶
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.
- 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, ...] [source]¶
Wrap expr in a
CommonSubexpression
with prefix.If expr is a
numpy
object array, each individual entry is instead wrapped. If expr is apymbolic.geometric_algebra.MultiVector
, each coefficient is individually wrapped. In general, the function tries to avoid re-wrapping existingCommonSubexpression
if the same scope is given.See
CommonSubexpression
for the meaning of prefix and scope. The scope defaults tocse_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, ...], ...])[source]¶
Bases:
ExpressionNode
Work-alike of
Subs
.- child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...]¶
- class pymbolic.primitives.Derivative(child: int | integer | float | complex | inexact | bool | bool | ExpressionNode | tuple[Expression, ...], variables: tuple[str, ...])[source]¶
Bases:
ExpressionNode
Work-alike of sympy’s
Derivative
.
Helper functions¶
- pymbolic.primitives.is_constant(value: object) TypeIs[int | integer | float | complex | inexact | bool | bool] [source]¶
- pymbolic.primitives.flattened_sum(terms: Iterable[ArithmeticExpression]) ArithmeticExpression [source]¶
Recursively flattens all the top level
Sum
s in terms.
- pymbolic.primitives.flattened_product(terms: Iterable[ArithmeticExpression]) ArithmeticExpression [source]¶
Recursively flattens all the top level
Product
s 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.
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'>)[source]¶
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)
Constants¶
- class pymbolic.primitives.NaN(data_type: Callable[[float], Any] | None = None)[source]¶
Bases:
AlgebraicLeaf
An expression node representing not-a-number as a floating point number. Unlike,
math.nan
, all instances ofNaN
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 ofisinstance()
.
Helper classes¶
References¶
- class pymbolic.primitives.DataclassInstance¶
An instance of a
dataclass()
.
- class pymbolic.primitives.ArithmeticExpression¶
- class pymbolic.primitives._T¶
A type variable.
- class numpy.bool_¶
Deprecated alias for
numpy.bool
.
- class typing_extensions.TypeIs¶
- class typing_extensions.Variable¶
See
pymbolic.Variable
.
- class typing_extensions.Expression¶
- class pymbolic.Comparison¶
- class pymbolic.LogicalNot¶
- class pymbolic.LogicalAnd¶
- class pymbolic.LogicalOr¶
- class pymbolic.Lookup¶