Array Expressions#

Note

Expression trees based on this package are picklable as long as no non-picklable data (e.g. pyopencl.array.Array) is referenced from DataWrapper.

Array Interface#

class pytato.Array(axes: Tuple[Axis, ...], tags: FrozenSet[Tag])[source]#

A base class (abstract interface + supplemental functionality) for lazily evaluating array expressions. The interface seeks to maximize numpy compatibility, though not at all costs.

Objects of this type are hashable and support structural equality comparison (and are therefore immutable).

Note

Hashability and equality testing does break numpy compatibility, purposefully so.

FIXME: Point out our equivalent for numpy’s ==.

shape#

A tuple of integers or scalar-shaped Arrays. Array-valued shape components may be (at most affinely) symbolic in terms of SizeParams.

Note

Affine-ness is mainly required by code generation for IndexLambda, but IndexLambda is used to produce references to named arrays. Since any array that needs to be referenced in this way needs to obey this restriction anyway, a decision was made to requir the same of all array expressions.

dtype#

An instance of numpy.dtype.

axes#

A tuple of Axis instances. One corresponding to each dimension of the array.

tags#

A frozenset of pytools.tag.Tag instances.

Motivation: RDF triples (subject: implicitly the array being tagged, predicate: the tag, object: the arg).

Inherits from pytools.tag.Taggable.

tagged(tags: Optional[Union[Iterable[Tag], Tag]]) Self[source]#

Return a copy of self with the specified tag or tags added to the set of tags. If the resulting set of tags violates the rules on pytools.tag.UniqueTag, an error is raised.

Parameters:

tags – An instance of Tag or an iterable with instances therein.

without_tags(tags: Optional[Union[Iterable[Tag], Tag]], verify_existence: bool = True) Self[source]#

Return a copy of self without the specified tags.

Parameters:
  • tags – An instance of Tag or an iterable with instances therein.

  • verify_existence – If set to True, this method raises an exception if not all tags specified for removal are present in the original set of tags. Default True.

Array interface:

__getitem__(slice_spec: Union[int, slice, Array, None, ellipsis, Tuple[Union[int, slice, Array, None, ellipsis], ...]]) Array[source]#

Warning

Out-of-bounds accesses via Array indices are undefined behavior and may pass silently.

T#
__mul__()[source]#
__rmul__()[source]#
__add__()[source]#
__radd__()[source]#
__sub__()[source]#
__rsub__()[source]#
__truediv__()[source]#
__rtruediv__()[source]#
__neg__()[source]#
__pos__()[source]#
__and__()[source]#
__rand__()[source]#
__or__()[source]#
__ror__()[source]#
__xor__()[source]#
__rxor__()[source]#
__abs__()[source]#
conj()[source]#
all(axis: int = 0) Union[Array, number, int, bool_, bool, float][source]#

Equivalent to pytato.all().

any(axis: int = 0) Union[Array, number, int, bool_, bool, float][source]#

Equivalent to pytato.any().

with_tagged_axis(iaxis: int, tags: Union[Sequence[Tag], Tag]) Array[source]#

Returns a copy of self with iaxis-th axis tagged with tags.

real#
imag#

Derived attributes:

ndim#
class pytato.Axis(tags: FrozenSet[Tag])[source]#

A type for recording the information about an Array’s axis.

class pytato.ReductionDescriptor(tags: FrozenSet[Tag])[source]#

Records information about a reduction dimension in an Array’.

class pytato.NamedArray(container: AbstractResultWithNamedArrays, name: str, axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

An entry in a AbstractResultWithNamedArrays. Holds a reference back to thecontaining instance as well as the name by which self is known there.

__init__(container: AbstractResultWithNamedArrays, name: str, axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({})) None[source]#

Constructor for all objects that possess a tags attribute.

Parameters:

tags – a frozenset of Tag objects. Tags can be modified via the tagged() and without_tags() routines. Input checking of tags should be performed before creating a Taggable instance, using check_tag_uniqueness().

class pytato.DictOfNamedArrays(data: Mapping[str, Array])[source]#

A container of named results, each of which can be computed as an array expression provided to the constructor.

Implements AbstractResultWithNamedArrays.

__init__(data: Mapping[str, Array])[source]#
class pytato.AbstractResultWithNamedArrays[source]#

An abstract array computation that results in multiple Arrays, each named. The way in which the values of these arrays are computed is determined by concrete subclasses of this class, e.g. pytato.loopy.LoopyCall or DictOfNamedArrays.

__init__()#
abstract __contains__(name: object) bool[source]#
abstract __getitem__(name: str) NamedArray[source]#
abstract __len__() int[source]#

Note

This container deliberately does not implement arithmetic.

NumPy-Like Interface#

These functions generally follow the interface of the corresponding functions in numpy, but not all NumPy features may be supported.

pytato.matmul(x1: Array, x2: Array) Array[source]#

Matrix multiplication.

Parameters:
  • x1 – first argument

  • x2 – second argument

pytato.roll(a: Array, shift: int, axis: Optional[int] = None) Array[source]#

Roll array elements along a given axis.

Parameters:
  • a – input array

  • shift – the number of places by which elements are shifted

  • axis – axis along which the array is shifted

pytato.transpose(a: Array, axes: Optional[Sequence[int]] = None) Array[source]#

Reverse or permute the axes of an array.

Parameters:
  • a – input array

  • axes – if specified, a permutation of [0, 1, ..., a.ndim-1]. Defaults to range(a.ndim)[::-1]. The returned axis at index i corresponds to the input axis axes[i].

pytato.stack(arrays: Sequence[Array], axis: int = 0) Array[source]#

Join a sequence of arrays along a new axis.

The axis parameter specifies the position of the new axis in the result.

Example:

>>> import pytato as pt
>>> arrays = [pt.zeros(3)] * 4
>>> pt.stack(arrays, axis=0).shape
(4, 3)
Parameters:
  • arrays – a finite sequence, each of whose elements is an Array of the same shape

  • axis – the position of the new axis, which will have length len(arrays)

pytato.concatenate(arrays: Sequence[Array], axis: int = 0) Array[source]#

Join a sequence of arrays along an existing axis.

Example:

>>> import pytato as pt
>>> arrays = [pt.zeros(3)] * 4
>>> pt.concatenate(arrays, axis=0).shape
(12,)
Parameters:
  • arrays – a finite sequence, each of whose elements is an Array . The arrays are of the same shape except along the axis dimension.

  • axis – The axis along which the arrays will be concatenated.

pytato.zeros(shape: ~typing.Union[int, ~numpy.integer, ~pytato.array.Array, ~typing.Sequence[~typing.Union[int, ~numpy.integer, ~pytato.array.Array]]], dtype: ~typing.Any = <class 'float'>, order: str = 'C') Array[source]#

Returns an array of shape shape with all entries equal to 0.

pytato.ones(shape: ~typing.Union[int, ~numpy.integer, ~pytato.array.Array, ~typing.Sequence[~typing.Union[int, ~numpy.integer, ~pytato.array.Array]]], dtype: ~typing.Any = <class 'float'>, order: str = 'C') Array[source]#

Returns an array of shape shape with all entries equal to 1.

pytato.full(shape: Union[int, integer, Array, Sequence[Union[int, integer, Array]]], fill_value: Union[number, int, bool_, bool, float], dtype: Optional[Any] = None, order: str = 'C') Array[source]#

Returns an array of shape shape with all entries equal to fill_value.

pytato.eye(N: int, M: ~typing.Optional[int] = None, k: int = 0, dtype: ~typing.Any = <class 'numpy.float64'>) Array[source]#

Returns a 2D-array with ones on the k-th diagonal

Parameters:
  • N – Number of rows in the output matrix

  • M – Number of columns in the output matrix. Equal to N if None.

pytato.arange(*args: Any, **kwargs: Any) Array[source]#

arange([start, ]stop, [step, ]dtype=None)

Semantically equivalent to numpy.arange().

pytato.equal(x1: Union[Array, number, int, bool_, bool, float], x2: Union[Array, number, int, bool_, bool, float]) Union[Array, bool][source]#

Returns (x1 == x2) element-wise.

pytato.not_equal(x1: Union[Array, number, int, bool_, bool, float], x2: Union[Array, number, int, bool_, bool, float]) Union[Array, bool][source]#

Returns (x1 != x2) element-wise.

pytato.less(x1: Union[Array, number, int, bool_, bool, float], x2: Union[Array, number, int, bool_, bool, float]) Union[Array, bool][source]#

Returns (x1 < x2) element-wise.

pytato.less_equal(x1: Union[Array, number, int, bool_, bool, float], x2: Union[Array, number, int, bool_, bool, float]) Union[Array, bool][source]#

Returns (x1 <= x2) element-wise.

pytato.greater(x1: Union[Array, number, int, bool_, bool, float], x2: Union[Array, number, int, bool_, bool, float]) Union[Array, bool][source]#

Returns (x1 > x2) element-wise.

pytato.greater_equal(x1: Union[Array, number, int, bool_, bool, float], x2: Union[Array, number, int, bool_, bool, float]) Union[Array, bool][source]#

Returns (x1 >= x2) element-wise.

pytato.logical_or(x1: Union[Array, number, int, bool_, bool, float], x2: Union[Array, number, int, bool_, bool, float]) Union[Array, bool][source]#

Returns the element-wise logical OR of x1 and x2.

pytato.logical_and(x1: Union[Array, number, int, bool_, bool, float], x2: Union[Array, number, int, bool_, bool, float]) Union[Array, bool][source]#

Returns the element-wise logical AND of x1 and x2.

pytato.logical_not(x: Union[Array, number, int, bool_, bool, float]) Union[Array, bool][source]#

Returns the element-wise logical NOT of x.

pytato.where(condition: Union[Array, number, int, bool_, bool, float], x: Optional[Union[Array, number, int, bool_, bool, float]] = None, y: Optional[Union[Array, number, int, bool_, bool, float]] = None) Union[Array, number, int, bool_, bool, float][source]#

Elementwise selector between x and y depending on condition.

pytato.maximum(x1: Union[Array, number, int, bool_, bool, float], x2: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#

Returns the elementwise maximum of x1, x2. x1, x2 being array-like objects that could be broadcasted together. NaNs are propagated.

pytato.minimum(x1: Union[Array, number, int, bool_, bool, float], x2: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#

Returns the elementwise minimum of x1, x2. x1, x2 being array-like objects that could be broadcasted together. NaNs are propagated.

pytato.einsum(subscripts: str, *operands: Array, index_to_redn_descr: Optional[Mapping[str, ReductionDescriptor]] = None) Einsum[source]#

Einstein summation subscripts on operands.

pytato.dot(a: Union[Array, number, int, bool_, bool, float], b: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#

For 1-dimensional arrays a and b computes their inner product. See numpy.dot() for behavior in the case when a and b aren’t single-dimensional arrays.

pytato.vdot(a: Array, b: Array) Union[Array, number, int, bool_, bool, float][source]#

Returns the dot-product of conjugate of a with b. If the input arguments are multi-dimensional arrays, they are ravel-ed first and then their vdot is computed.

pytato.broadcast_to(array: Array, shape: Tuple[Union[int, integer, Array], ...]) Array[source]#

Returns array broadcasted to shape.

pytato.squeeze(array: Array) Array[source]#

Remove single-dimensional entries from the shape of an array.

pytato.abs(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.sqrt(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.sin(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.cos(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.tan(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.arcsin(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.arccos(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.arctan(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.conj(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.arctan2(y: Union[Array, number, int, bool_, bool, float], x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.sinh(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.cosh(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.tanh(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.exp(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.log(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.log10(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.isnan(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.real(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.imag(x: Union[Array, number, int, bool_, bool, float]) Union[Array, number, int, bool_, bool, float][source]#
pytato.sum(a: Array, axis: Optional[Union[int, Tuple[int, ...]]] = None, initial: Any = 0, axis_to_reduction_descr: Optional[Mapping[int, ReductionDescriptor]] = None) Array[source]#

Sums array a’s elements along the axis axes.

Parameters:
  • a – The pytato.Array on which to perform the reduction.

  • axis – The axes along which the elements are to be sum-reduced. Defaults to all axes of the input array.

  • initial – The value returned for an empty array, if supplied. This value also serves as the base value onto which any additional array entries are accumulated.

  • axis_to_reduction_descr – A mapping from axis in axis to the corresponding instance of ReductionDescriptor that the IndexLambda is to be instantiated with.

pytato.amin(a: ~pytato.array.Array, axis: ~typing.Optional[~typing.Union[int, ~typing.Tuple[int, ...]]] = None, initial: ~typing.Any = <class 'pytato.reductions._NoValue'>, axis_to_reduction_descr: ~typing.Optional[~typing.Mapping[int, ~pytato.array.ReductionDescriptor]] = None) Array[source]#

Returns the min of array a’s elements along the axis axes.

Parameters:
  • a – The pytato.Array on which to perform the reduction.

  • axis – The axes along which the elements are to be min-reduced. Defaults to all axes of the input array.

  • initial – The value returned for an empty array, if supplied. This value also serves as the base value onto which any additional array entries are accumulated. If not supplied, an ValueError will be raised if the reduction is empty. In that case, the reduction size must not be symbolic.

  • axis_to_reduction_descr – A mapping from axis in axis to the corresponding instance of ReductionDescriptor that the IndexLambda is to be instantiated with.

pytato.amax(a: ~pytato.array.Array, axis: ~typing.Optional[~typing.Union[int, ~typing.Tuple[int]]] = None, *, initial: ~typing.Any = <class 'pytato.reductions._NoValue'>, axis_to_reduction_descr: ~typing.Optional[~typing.Mapping[int, ~pytato.array.ReductionDescriptor]] = None) Array[source]#

Returns the max of array a’s elements along the axis axes.

Parameters:
  • a – The pytato.Array on which to perform the reduction.

  • axis – The axes along which the elements are to be max-reduced. Defaults to all axes of the input array.

  • initial – The value returned for an empty array, if supplied. This value also serves as the base value onto which any additional array entries are accumulated. If not supplied, an ValueError will be raised if the reduction is empty. In that case, the reduction size must not be symbolic.

  • axis_to_reduction_descr – A mapping from axis in axis to the corresponding instance of ReductionDescriptor that the IndexLambda is to be instantiated with.

pytato.prod(a: Array, axis: Optional[Union[int, Tuple[int, ...]]] = None, initial: Any = 1, axis_to_reduction_descr: Optional[Mapping[int, ReductionDescriptor]] = None) Array[source]#

Returns the product of array a’s elements along the axis axes.

Parameters:
  • a – The pytato.Array on which to perform the reduction.

  • axis – The axes along which the elements are to be product-reduced. Defaults to all axes of the input array.

  • initial – The value returned for an empty array, if supplied. This value also serves as the base value onto which any additional array entries are accumulated.

  • axis_to_reduction_descr – A mapping from axis in axis to the corresponding instance of ReductionDescriptor that the IndexLambda is to be instantiated with.

pytato.all(a: Array, axis: Optional[Union[int, Tuple[int, ...]]] = None, axis_to_reduction_descr: Optional[Mapping[int, ReductionDescriptor]] = None) Array[source]#

Returns the logical-and array a’s elements along the axis axes.

Parameters:
  • a – The pytato.Array on which to perform the reduction.

  • axis – The axes along which the elements are to be product-reduced. Defaults to all axes of the input array.

  • axis_to_reduction_descr – A mapping from axis in axis to the corresponding instance of ReductionDescriptor that the IndexLambda is to be instantiated with.

pytato.any(a: Array, axis: Optional[Union[int, Tuple[int, ...]]] = None, axis_to_reduction_descr: Optional[Mapping[int, ReductionDescriptor]] = None) Array[source]#

Returns the logical-or of array a’s elements along the axis axes.

Parameters:
  • a – The pytato.Array on which to perform the reduction.

  • axis – The axes along which the elements are to be product-reduced. Defaults to all axes of the input array.

  • axis_to_reduction_descr – A mapping from axis in axis to the corresponding instance of ReductionDescriptor that the IndexLambda is to be instantiated with.

class pytato.reductions.ReductionOperation[source]#
abstract neutral_element(dtype: dtype[Any]) Any[source]#
abstract __hash__() int[source]#

Return hash(self).

abstract __eq__(other: Any) bool[source]#

Return self==value.

class pytato.reductions.SumReductionOperation[source]#
class pytato.reductions.ProductReductionOperation[source]#
class pytato.reductions.MaxReductionOperation[source]#
class pytato.reductions.MinReductionOperation[source]#
class pytato.reductions.AllReductionOperation[source]#
class pytato.reductions.AnyReductionOperation[source]#

Concrete Array Data#

class pytato.array.DataInterface(*args, **kwargs)[source]#

A protocol specifying the minimal interface requirements for concrete array data supported by DataWrapper.

See typing.Protocol for more information about protocols.

Code generation targets may impose additional restrictions on the kinds of concrete array data they support.

shape#
dtype#

Built-in Expression Nodes#

class pytato.array.IndexLambda(expr: Expression, shape: Tuple[Union[int, integer, Array], ...], dtype: dtype[Any], bindings: Dict[str, Array], axes: Tuple[Axis, ...], var_to_reduction_descr: Mapping[str, ReductionDescriptor], tags: FrozenSet[Tag] = frozenset({}))[source]#

Represents an array that can be computed by evaluating expr for every value of the input indices. The input indices are represented by Variables with names _1, _2, and so on.

expr#

A scalar-valued pymbolic expression such as a[_1] + b[_2, _1].

Identifiers in the expression are resolved, in order, by lookups in bindings.

Scalar functions in this expression must be identified by a dotted name representing a Python object (e.g. pytato.c99.sin).

bindings#

A dict mapping strings that are valid Python identifiers to objects implementing the Array interface, making array expressions available for use in expr.

var_to_reduction_descr#

A mapping from reduction variables in expr to their ReductionDescriptor.

with_tagged_reduction(reduction_variable: str, tag: Tag) IndexLambda[source]#

Returns a copy of self with the ReductionDescriptor associated with reduction_variable tagged with tag.

Parameters:

reduction_variable – Name of reduction variable in self that is to be tagged.

class pytato.array.Einsum(access_descriptors: Tuple[Tuple[EinsumAxisDescriptor, ...], ...], args: Tuple[Array, ...], axes: Tuple[Axis, ...], redn_axis_to_redn_descr: Mapping[EinsumReductionAxis, ReductionDescriptor], index_to_access_descr: Mapping[str, EinsumAxisDescriptor], tags: FrozenSet[Tag] = frozenset({}))[source]#

An array expression using the Einstein summation convention. See numpy.einsum() for a similar construct.

Note

Use pytato.einsum() to create this type of expression node in user code.

access_descriptors#

A tuple of access_descriptor for each arg in Einsum.args. An access_descriptor is a tuple of EinsumAxisDescriptor denoting how each axis of the argument will be operated in the einstein summation.

args#

A tuple of array over which the Einstein summation is being performed.

access_descr_to_index#

Mapping from the access descriptors to the index used by the user during the instantiation of the Einsum node. This is a strictly non-semantic attribute and only present to support a friendlier with_tagged_reduction().

with_tagged_reduction(redn_axis: Union[EinsumReductionAxis, str], tag: Tag) Einsum[source]#

Returns a copy of self with the ReductionDescriptor associated with redn_axis tagged with tag.

class pytato.array.Stack(arrays: Tuple[Array, ...], axis: int, axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

Join a sequence of arrays along a new axis.

arrays#

The sequence of arrays to join

axis#

The output axis

class pytato.array.Concatenate(arrays: Tuple[Array, ...], axis: int, axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

Join a sequence of arrays along an existing axis.

arrays#

An instance of tuple of the arrays to join. The arrays must have same shape except for the dimension corresponding to axis.

axis#

The axis along which the arrays are to be concatenated.

Index Remapping#

class pytato.array.IndexRemappingBase(array: Array, axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

Base class for operations that remap the indices of an array.

Note that index remappings can also be expressed via IndexLambda.

array#

The input Array

class pytato.array.Roll(array: Array, shift: int, axis: int, axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

Roll an array along an axis.

shift#

Shift amount.

axis#

Shift axis.

class pytato.array.AxisPermutation(array: Array, axis_permutation: Tuple[int, ...], axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

Permute the axes of an array.

array#
axis_permutation#

A permutation of the input axes.

class pytato.array.Reshape(array: Array, newshape: Tuple[Union[int, integer, Array], ...], order: str, axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

Reshape an array.

array#

The array to be reshaped

newshape#

The output shape

order#

Output layout order, either C or F.

class pytato.array.IndexBase(array: Array, indices: Tuple[Union[int, integer, NormalizedSlice, Array, None, ellipsis], ...], axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

Abstract class for all index expressions on an array.

indices#
class pytato.array.BasicIndex(array: Array, indices: Tuple[Union[int, integer, NormalizedSlice, Array, None, ellipsis], ...], axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

An indexing expression with all indices being either an int or slice.

class pytato.array.AdvancedIndexInContiguousAxes(array: Array, indices: Tuple[Union[int, integer, NormalizedSlice, Array, None, ellipsis], ...], axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

An indexing expression with at least one Array index and all the advanced indices (i.e. scalars/array) appearing contiguously in IndexBase.indices.

The reason for the existence of this class and AdvancedIndexInNoncontiguousAxes is that numpy treats those two cases differently, and we’re bound to follow its precedent.

class pytato.array.AdvancedIndexInNoncontiguousAxes(array: Array, indices: Tuple[Union[int, integer, NormalizedSlice, Array, None, ellipsis], ...], axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

An indexing expression with advanced indices (i.e. scalars/arrays) appearing non-contiguously in IndexBase.indices.

The reason for the existence of this class and AdvancedIndexInContiguousAxes is that numpy treats those two cases differently, and we’re bound to follow its precedent.

Input Arguments#

class pytato.array.InputArgumentBase(axes: Tuple[Axis, ...], tags: FrozenSet[Tag])[source]#

Base class for input arguments.

Note

Creating multiple instances of any input argument with the same name in an expression is not allowed.

class pytato.array.DataWrapper(data: DataInterface, shape: Tuple[Union[int, integer, Array], ...], axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

Takes concrete array data and packages it to be compatible with the Array interface.

data#

A concrete array (containing data), given as, for example, a numpy.ndarray, or a pyopencl.array.Array. This must offer shape and dtype attributes but is otherwise considered opaque. At evaluation time, its type must be understood by the appropriate execution backend.

Starting with the construction of the DataWrapper, this array may not be updated in-place.

shape#

The shape of the array is represented separately from array to allow symbolic shapes to be used, and to ease pytato’s job in recognizing shapes of arrays as equal. For example, if the shape of data is (3, 4), and shape is (nrows, ncolumns), then this represents a (global) constraint that that nrows == 3 and ncolumns == 4. Arithmetic and other operations in pytato do not currently resolve these constraints to assess whether shapes match, and thus it is important that a canonical (symbolic) form of the shape tuple is used.

name#

An (optional, string) name by which this object can be identified. Hypothetically, this could be used to ‘swap out’ the data captured here, but that functionality is not currently available.

Note

Since we cannot compare instances of DataInterface being wrapped, a DataWrapper instances compare equal to themselves (i.e. the very same instance).

class pytato.array.Placeholder(name: str, shape: Tuple[Union[int, integer, Array], ...], dtype: dtype[Any], axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

A named placeholder for an array whose concrete value is supplied by the user during evaluation.

name#

The name by which a value is supplied for the argument once computation begins.

__init__(name: str, shape: Tuple[Union[int, integer, Array], ...], dtype: dtype[Any], axes: Tuple[Axis, ...], tags: FrozenSet[Tag] = frozenset({}))[source]#

Should not be called directly. Use make_placeholder() instead.

class pytato.array.SizeParam(name: str, axes: Tuple[Axis, ...] = (), tags: FrozenSet[Tag] = frozenset({}))[source]#

A named placeholder for a scalar that may be used as a variable in symbolic expressions for array sizes.

name#

The name by which a value is supplied for the argument once computation begins.

User-Facing Node Creation#

Node constructors such as Placeholder.__init__ and __init__ offer limited input validation (in favor of faster execution). Node creation from outside pytato should use the following interfaces:

class pytato.array.ShapeComponent#
class pytato.array.ConvertibleToShape#
pytato.array.make_dict_of_named_arrays(data: Dict[str, Array]) DictOfNamedArrays[source]#

Make a DictOfNamedArrays object.

Parameters:

data – member keys and arrays

pytato.array.make_placeholder(name: str, shape: Union[int, integer, Array, Sequence[Union[int, integer, Array]]], dtype: Any, tags: FrozenSet[Tag] = frozenset({}), axes: Optional[Tuple[Axis, ...]] = None) Placeholder[source]#

Make a Placeholder object.

Parameters:
  • name – name of the placeholder array, generated automatically if not given

  • shape – shape of the placeholder array

  • dtype – dtype of the placeholder array (must be convertible to numpy.dtype)

  • tags – implementation tags

pytato.array.make_size_param(name: str, tags: FrozenSet[Tag] = frozenset({})) SizeParam[source]#

Make a SizeParam.

Size parameters may be used as variables in symbolic expressions for array sizes.

Parameters:
  • name – name

  • tags – implementation tags

pytato.array.make_data_wrapper(data: DataInterface, *, name: Optional[str] = None, shape: Optional[Union[int, integer, Array, Sequence[Union[int, integer, Array]]]] = None, tags: FrozenSet[Tag] = frozenset({}), axes: Optional[Tuple[Axis, ...]] = None) DataWrapper[source]#

Make a DataWrapper.

Parameters:
  • data – an instance obeying the DataInterface

  • name – an optional name, generated automatically if not given

  • shape – optional shape of the array, inferred from data if not given

  • tags – implementation tags

Internal API#

class pytato.array.EinsumAxisDescriptor[source]#

Records the access pattern of iterating over an array’s axis in a Einsum.

class pytato.array.EinsumElementwiseAxis(dim: int)[source]#

Describes an elementwise access pattern of an array’s axis. In terms of the nomenclature used by IndexLambda, EinsumElementwiseAxis(dim=1) would correspond to indexing the array’s axis as _1 in the expression.

class pytato.array.EinsumReductionAxis(dim: int)[source]#

Describes a reduction access pattern of an array’s axis. In terms of the nomenclature used by IndexLambda, EinsumReductionAxis(dim=0) would correspond to indexing the array’s axis as _r0 in the expression.

class pytato.array.NormalizedSlice(start: Union[int, integer, Array], stop: Union[int, integer, Array], step: Union[int, integer])[source]#

A normalized version of slice. “Normalized” is explained in start and stop.

start#

An instance of ShapeComponent. Normalized to satisfy the relation -1 <= start <= axis_len, where axis_len is the length of the axis being sliced.

stop#

An instance of ShapeComponent. Normalized to satisfy the relation -1 <= stop <= axis_len, where axis_len is the length of the axis being sliced.

step#

Internal stuff that is only here because the documentation tool wants it#

class pytato.array.AxesT#

A tuple of Axis objects.

Raising IndexLambda nodes#

class pytato.raising.HighLevelOp[source]#

Base class for all high level operations that could be raised from a pytato.array.IndexLambda.

pytato.raising.index_lambda_to_high_level_op(expr: IndexLambda) HighLevelOp[source]#

Returns a HighLevelOp corresponding expr.

Calling loopy kernels in an array expression#

class pytato.loopy.LoopyCall(translation_unit: TranslationUnit, bindings: Dict[str, Union[Array, number, int, bool_, bool, float]], entrypoint: str)[source]#

An array expression node representing a call to an entrypoint in a loopy translation unit.

class pytato.loopy.LoopyCallResult(loopy_call: LoopyCall, name: str, axes: AxesT, tags: FrozenSet[Tag] = frozenset({}))[source]#

Named array for LoopyCall’s result. Inherits from NamedArray.

pytato.loopy.call_loopy(translation_unit: TranslationUnit, bindings: Dict[str, Union[Array, number, int, bool_, bool, float]], entrypoint: Optional[str] = None) LoopyCall[source]#

Invokes an entry point of a loopy.TranslationUnit on the array inputs as specified by bindings.

Restrictions on the structure of translation_unit[entrypoint]:

  • array arguments of translation_unit[entrypoint] must either be either input-only or output-only.

  • all input-only arguments of translation_unit[entrypoint] must appear in bindings.

  • all output-only arguments of translation_unit[entrypoint] must appear in bindings.

  • if translation_unit has been declared with multiple entrypoints, entrypoint can not be None.

Parameters:
  • translation_unit – the translation unit to call.

  • bindings – mapping from argument names of translation_unit[entrypoint] to pytato.array.Array.

  • entrypoint – the entrypoint of the translation_unit parameter.

Internal stuff that is only here because the documentation tool wants it#

class pytato.loopy.Tag[source]#

See pytools.tag.Tag.

class pytato.loopy.AxesT#

See pytato.array.AxesT.

Attaching metadata to arrays#

Pre-Defined Tags#

class pytato.tags.ImplementationStrategy[source]#

Metadata to be attached to pytato.Array to convey information to a pytato.target.Target on how it is supposed to be lowered.

class pytato.tags.ImplStored[source]#

An ImplementationStrategy that is tagged to an Array to indicate that the Target must allocate a buffer for storing all the array’s elements, and, all the users of the array must read from that buffer.

class pytato.tags.ImplInlined[source]#

An ImplementationStrategy that is tagged to an Array to indicate that the Target should inline the tagged array’s expression into its users.

class pytato.tags.CountNamed(name: str)[source]#

Tagged to a bool-dtyped Array A. If A appears as one of the indices in IndexBase, the number of True values in A is assigned to a variable named name in the generated code.

name#
class pytato.tags.Named(name: str)[source]#

Tagged to an Array to indicate the Target that if the tagged array is allocated to a variable, then it must be named name.

name#
class pytato.tags.PrefixNamed(prefix: str)[source]#

Tagged to an Array to indicate the Target that if the tagged array is allocated to a variable, then its name must begin with prefix.

prefix#
class pytato.tags.AssumeNonNegative[source]#

A tag attached to a Array to indicate the Target that all entries of the tagged array are non-negative.

Scalar Expressions#

Scalar expressions occur in shapes and in the pytato.array.IndexLambda.

pytato.scalar_expr.ScalarExpression#

A type for scalar-valued symbolic expressions. Expressions are composable and manipulable via pymbolic.

Concretely, this is an alias for Union[Number, np.bool_, bool, pymbolic.primitives.Expression].

pytato.scalar_expr.parse(s: str) Union[number, int, bool_, bool, float, Expression][source]#
pytato.scalar_expr.get_dependencies(expression: Any, include_idx_lambda_indices: bool = True) FrozenSet[str][source]#

Return the set of variable names in an expression.

Parameters:

expression – A scalar expression, or an expression derived from such (e.g., a tuple of scalar expressions)

pytato.scalar_expr.substitute(expression: Any, variable_assigments: Optional[Mapping[str, Any]]) Any[source]#

Perform variable substitution in an expression.

Parameters:
  • expression – A scalar expression, or an expression derived from such (e.g., a tuple of scalar expressions)

  • variable_assigments – A mapping from variable names to substitutions