Primitives (Basic Objects)#

Expression base class#

class pymbolic.primitives.Expression[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 when Pymbolic is used under Python 3.10.

a#
attr[source]#
mapper_method#

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

__getitem__()[source]#
__getinitargs__()[source]#
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 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)[source]#

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)[source]#
__hash__()[source]#

Provides caching for hash values.

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

get_hash()[source]#
__str__()[source]#

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

__repr__()[source]#

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

Logical operator constructors

not_()[source]#

Return self wrapped in a LogicalNot.

New in version 2015.2.

and_(other)[source]#

Return LogicalAnd between self and other.

New in version 2015.2.

or_(other)[source]#

Return LogicalOr between self and other.

New in version 2015.2.

Comparison constructors

eq(other)[source]#

Return a Comparison comparing self to other.

New in version 2015.2.

ne(other)[source]#

Return a Comparison comparing self to other.

New in version 2015.2.

lt(other)[source]#

Return a Comparison comparing self to other.

New in version 2015.2.

le(other)[source]#

Return a Comparison comparing self to other.

New in version 2015.2.

gt(other)[source]#

Return a Comparison comparing self to other.

New in version 2015.2.

ge(other)[source]#

Return a Comparison comparing self to other.

New in version 2015.2.

Sums, products and such#

class pymbolic.primitives.Variable(name)[source]#
name#
mapper_method = 'map_variable'#
class pymbolic.primitives.Call(function, parameters)[source]#

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)[source]#

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)[source]#

An array subscript.

aggregate#
index[source]#
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)[source]#

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

mapper_method = 'map_lookup'#
class pymbolic.primitives.Sum(children)[source]#
children#

A tuple.

mapper_method = 'map_sum'#
class pymbolic.primitives.Product(children)[source]#
children#

A tuple.

mapper_method = 'map_product'#
class pymbolic.primitives.Quotient(numerator, denominator=1)[source]#
numerator#
denominator#
mapper_method = 'map_quotient'#
class pymbolic.primitives.FloorDiv(numerator, denominator=1)[source]#
numerator#
denominator#
mapper_method = 'map_floor_div'#
class pymbolic.primitives.Remainder(numerator, denominator=1)[source]#
numerator#
denominator#
mapper_method = 'map_remainder'#
class pymbolic.primitives.Power(base, exponent)[source]#
base#
exponent#
mapper_method = 'map_power'#

Shift operators#

class pymbolic.primitives.LeftShift(shiftee, shift)[source]#
shiftee#
shift#
mapper_method = 'map_left_shift'#
class pymbolic.primitives.RightShift(shiftee, shift)[source]#
shiftee#
shift#
mapper_method = 'map_right_shift'#

Bitwise operators#

class pymbolic.primitives.BitwiseNot(child)[source]#
child#
mapper_method = 'map_bitwise_not'#
class pymbolic.primitives.BitwiseOr(children)[source]#
children#

A tuple.

mapper_method = 'map_bitwise_or'#
class pymbolic.primitives.BitwiseXor(children)[source]#
children#

A tuple.

mapper_method = 'map_bitwise_xor'#
class pymbolic.primitives.BitwiseAnd(children)[source]#
children#

A tuple.

mapper_method = 'map_bitwise_and'#

Comparisons and logic#

class pymbolic.primitives.Comparison(left, operator, right)[source]#
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)[source]#
child#
mapper_method = 'map_logical_not'#
class pymbolic.primitives.LogicalAnd(children)[source]#
children#

A tuple.

mapper_method = 'map_logical_and'#
class pymbolic.primitives.LogicalOr(children)[source]#
children#

A tuple.

mapper_method = 'map_logical_or'#
class pymbolic.primitives.If(condition, then, else_)[source]#
condition#
then#
else_#
mapper_method = 'map_if'#

Code generation helpers#

class pymbolic.primitives.CommonSubexpression(child, prefix=None, scope=None)[source]#

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[source]#

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)[source]#

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)[source]#
pymbolic.primitives.is_constant(value)[source]#
pymbolic.primitives.flattened_sum(terms)[source]#

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)[source]#

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_)[source]#
pymbolic.primitives.unregister_constant_class(class_)[source]#
pymbolic.primitives.variables(s)[source]#

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'>)[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)
pymbolic.primitives.make_sym_array(name, shape, var_factory=<class 'pymbolic.primitives.Variable'>)[source]#

Constants#

class pymbolic.primitives.NaN(data_type=None)[source]#

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'#