Primitives (Basic Objects)

Expression base class

class pymbolic.primitives.Expression

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 when Pymbolic is used under Python 3.10.

a

attr

mapper_method

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

__getitem__()

__getinitargs__()

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)

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

Subclasses should generally not override this method, but instead provide an implementation of is_equal().

is_equal(other)

__hash__()

Provides caching for hash values.

Subclasses should generally not override this method, but instead provide an implementation of get_hash().

get_hash()

__str__()

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

__repr__()

Provides a default repr() based on the Python pickling interface __getinitargs__().

Logical operator constructors

not_()

Return self wrapped in a LogicalNot.

Added in version 2015.2.

and_(other)

Return LogicalAnd between self and other.

Added in version 2015.2.

or_(other)

Return LogicalOr between self and other.

Added in version 2015.2.

Comparison constructors

eq(other)

Return a Comparison comparing self to other.

Added in version 2015.2.

ne(other)

Return a Comparison comparing self to other.

Added in version 2015.2.

lt(other)

Return a Comparison comparing self to other.

Added in version 2015.2.

le(other)

Return a Comparison comparing self to other.

Added in version 2015.2.

gt(other)

Return a Comparison comparing self to other.

Added in version 2015.2.

ge(other)

Return a Comparison comparing self to other.

Added in version 2015.2.

Sums, products and such

class pymbolic.primitives.Variable(name)

name

mapper_method = 'map_variable'

class pymbolic.primitives.Call(function, parameters)

A function invocation.

function

A Expression that evaluates to a function.

parameters

A tuple of positional parameters, each element of which is a Expression or a constant.

mapper_method = 'map_call'

class pymbolic.primitives.CallWithKwargs(function, parameters, kw_parameters)

A function invocation with keyword arguments.

function

A Expression that evaluates to a function.

parameters

A tuple of positional parameters, each element of which is a Expression or a constant.

kw_parameters

A dictionary mapping names to arguments, , each of which is a Expression or a constant, or an equivalent value accepted by the dict constructor.

mapper_method = 'map_call_with_kwargs'

class pymbolic.primitives.Subscript(aggregate, index)

An array subscript.

aggregate

index

index_tuple

Return index wrapped in a single-element tuple, if it is not already a tuple.

mapper_method = 'map_subscript'

class pymbolic.primitives.Lookup(aggregate, name)

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

mapper_method = 'map_lookup'

class pymbolic.primitives.Sum(children)

children

A tuple.

mapper_method = 'map_sum'

class pymbolic.primitives.Product(children)

children

A tuple.

mapper_method = 'map_product'

class pymbolic.primitives.Quotient(numerator, denominator=1)

numerator

denominator

mapper_method = 'map_quotient'

class pymbolic.primitives.FloorDiv(numerator, denominator=1)

numerator

denominator

mapper_method = 'map_floor_div'

class pymbolic.primitives.Remainder(numerator, denominator=1)

numerator

denominator

mapper_method = 'map_remainder'

class pymbolic.primitives.Power(base, exponent)

base

exponent

mapper_method = 'map_power'

Shift operators

class pymbolic.primitives.LeftShift(shiftee, shift)

shiftee

shift

mapper_method = 'map_left_shift'

class pymbolic.primitives.RightShift(shiftee, shift)

shiftee

shift

mapper_method = 'map_right_shift'

Bitwise operators

class pymbolic.primitives.BitwiseNot(child)

child

mapper_method = 'map_bitwise_not'

class pymbolic.primitives.BitwiseOr(children)

children

A tuple.

mapper_method = 'map_bitwise_or'

class pymbolic.primitives.BitwiseXor(children)

children

A tuple.

mapper_method = 'map_bitwise_xor'

class pymbolic.primitives.BitwiseAnd(children)

children

A tuple.

mapper_method = 'map_bitwise_and'

Comparisons and logic

class pymbolic.primitives.Comparison(left, operator, right)

left

operator

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

right

Note

Unlike other expressions, comparisons are not implicitly constructed by comparing Expression objects. See Expression.eq().

mapper_method = 'map_comparison'

class pymbolic.primitives.LogicalNot(child)

child

mapper_method = 'map_logical_not'

class pymbolic.primitives.LogicalAnd(children)

children

A tuple.

mapper_method = 'map_logical_and'

class pymbolic.primitives.LogicalOr(children)

children

A tuple.

mapper_method = 'map_logical_or'

class pymbolic.primitives.If(condition, then, else_)

condition

then

else_

mapper_method = 'map_if'

Code generation helpers

class pymbolic.primitives.CommonSubexpression(child, prefix=None, scope=None)

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

prefix

scope

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

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

mapper_method = 'map_common_subexpression'

class pymbolic.primitives.cse_scope

Determines the lifetime for the saved value of a CommonSubexpression.

EVALUATION

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

EXPRESSION

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

The evaluated result lives until the execution context dies.

pymbolic.primitives.make_common_subexpression(field, prefix=None, scope=None)

Wrap field in a CommonSubexpression with prefix. If field is a numpy object array, each individual entry is instead wrapped. If field is a pymbolic.geometric_algebra.MultiVector, each coefficient is individually wrapped.

See CommonSubexpression for the meaning of prefix and scope.

Helper functions

pymbolic.primitives.is_zero(value)

pymbolic.primitives.is_constant(value)

pymbolic.primitives.flattened_sum(terms)

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)

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=None)

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

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 = 'map_nan'