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[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
Array
s. Array-valued shape components may be (at most affinely) symbolic in terms ofSizeParam
s.Note
Affine-ness is mainly required by code generation for
IndexLambda
, butIndexLambda
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 require the same of all array expressions.
- dtype¶
An instance of
numpy.dtype
.
- tags¶
A
frozenset
ofpytools.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: Iterable[Tag] | Tag | None) 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: Iterable[Tag] | Tag | None, 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: int | slice | Array | ellipsis | None | tuple[int | slice | Array | ellipsis | None, ...]) Array [source]¶
Warning
Out-of-bounds accesses via
Array
indices are undefined behavior and may pass silently.
- T¶
- all(axis: int = 0) Array | int | integer | float | complex | inexact | bool | bool [source]¶
Equivalent to
pytato.all()
.
- any(axis: int = 0) Array | int | integer | float | complex | inexact | bool | bool [source]¶
Equivalent to
pytato.any()
.
- with_tagged_axis(iaxis: int, tags: Iterable[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], non_equality_tags: frozenset[Tag] = frozenset({}))[source]¶
An entry in a
AbstractResultWithNamedArrays
. Holds a reference back to the containing instance as well as the name by which self is known there.
- class pytato.DictOfNamedArrays(data: Mapping[str, Array], *, tags: frozenset[Tag] | None = None)[source]¶
A container of named results, each of which can be computed as an array expression provided to the constructor.
Implements
AbstractResultWithNamedArrays
.
- class pytato.AbstractResultWithNamedArrays(*, tags: frozenset[Tag])[source]¶
An abstract array computation that results in multiple
Array
s, 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
orDictOfNamedArrays
.- abstract __getitem__(name: str) NamedArray [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: int | None = 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: Sequence[int] | None = 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 torange(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 shapeaxis – 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: int | ~numpy.integer | ~pytato.array.Array | ~collections.abc.Sequence[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: int | ~numpy.integer | ~pytato.array.Array | ~collections.abc.Sequence[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: int | integer | Array | Sequence[int | integer | Array], fill_value: int | integer | float | complex | inexact | bool | bool | NaN, dtype: 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: int | None = 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: Array | int | integer | float | complex | inexact | bool | bool, x2: Array | int | integer | float | complex | inexact | bool | bool) Array | bool [source]¶
Returns (x1 == x2) element-wise.
- pytato.not_equal(x1: Array | int | integer | float | complex | inexact | bool | bool, x2: Array | int | integer | float | complex | inexact | bool | bool) Array | bool [source]¶
Returns (x1 != x2) element-wise.
- pytato.less(x1: Array | int | integer | float | complex | inexact | bool | bool, x2: Array | int | integer | float | complex | inexact | bool | bool) Array | bool [source]¶
Returns (x1 < x2) element-wise.
- pytato.less_equal(x1: Array | int | integer | float | complex | inexact | bool | bool, x2: Array | int | integer | float | complex | inexact | bool | bool) Array | bool [source]¶
Returns (x1 <= x2) element-wise.
- pytato.greater(x1: Array | int | integer | float | complex | inexact | bool | bool, x2: Array | int | integer | float | complex | inexact | bool | bool) Array | bool [source]¶
Returns (x1 > x2) element-wise.
- pytato.greater_equal(x1: Array | int | integer | float | complex | inexact | bool | bool, x2: Array | int | integer | float | complex | inexact | bool | bool) Array | bool [source]¶
Returns (x1 >= x2) element-wise.
- pytato.logical_or(x1: Array | int | integer | float | complex | inexact | bool | bool, x2: Array | int | integer | float | complex | inexact | bool | bool) Array | bool [source]¶
Returns the element-wise logical OR of x1 and x2.
- pytato.logical_and(x1: Array | int | integer | float | complex | inexact | bool | bool, x2: Array | int | integer | float | complex | inexact | bool | bool) Array | bool [source]¶
Returns the element-wise logical AND of x1 and x2.
- pytato.logical_not(x: Array | int | integer | float | complex | inexact | bool | bool) Array | bool [source]¶
Returns the element-wise logical NOT of x.
- pytato.where(condition: Array | int | integer | float | complex | inexact | bool | bool, x: Array | int | integer | float | complex | inexact | bool | bool | None = None, y: Array | int | integer | float | complex | inexact | bool | bool | None = None) Array | int | integer | float | complex | inexact | bool | bool [source]¶
Elementwise selector between x and y depending on condition.
- pytato.maximum(x1: Array | int | integer | float | complex | inexact | bool | bool, x2: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [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: Array | int | integer | float | complex | inexact | bool | bool, x2: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [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: Mapping[str, ReductionDescriptor] | None = None) Einsum [source]¶
Einstein summation subscripts on operands.
- pytato.dot(a: Array | int | integer | float | complex | inexact | bool | bool, b: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [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) Array | int | integer | float | complex | inexact | bool | bool [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[int | integer | Array, ...]) Array [source]¶
Returns array broadcasted to shape.
- pytato.squeeze(array: Array, axis: Collection[int] | None = None) Array [source]¶
Remove single-dimensional entries from the shape of an array.
- Parameters:
axis – Subset of 1-long axes of array that must be removed. If None all 1-long axes are removed.
- pytato.expand_dims(array: Array, axis: tuple[int, ...] | int) Array [source]¶
Reshapes array by adding 1-long axes at axis dimensions of the returned array.
- pytato.abs(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.sqrt(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.sin(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.cos(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.tan(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.arcsin(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.arccos(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.arctan(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.conj(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.arctan2(y: Array | int | integer | float | complex | inexact | bool | bool, x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.sinh(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.cosh(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.tanh(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.exp(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.log(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.log10(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.isnan(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.real(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.imag(x: Array | int | integer | float | complex | inexact | bool | bool) Array | int | integer | float | complex | inexact | bool | bool [source]¶
- pytato.pad.pad(array: Array, pad_width: int | integer | Sequence[int | integer], mode: str = 'constant', **kwargs: Any) Array [source]¶
Returns an array with padded elements along each axis.
- Parameters:
array – The array to be padded.
pad_width –
Number of elements to be padded along each axis. Can be one of:
An instance of
int
denoting the constant number of elements to pad before and after each axis.A tuple of the form
(before, after)
denoting that before number of padded elements must precede each axis and after number of padded elements must succeed each axis.A sequence with i-th element as the tuple
(before_i, after_i)
denoting that before_i number of padded elements must precede the i-th axis and after_i number of padded elements must succeed the i-th axis.
mode –
An instance of
str
denoting the values of the padded elements in the returned array. It can be one of:"constant"
denoting that the padded elements must be filled with constant entries. See constant_values.
constant_values –
Optional argument when operating under
"constant"
mode. Can be one of:An instance of
int
denoting the value of every padded element.A
tuple
of the form(before, after)
denoting that every padded element that precedes array’s axes must be set to before and every padded element that succeeds array’s axes must be set to after.A sequence with the i-th element of the form
(before_i, after_i)
denoting that the padded elements preceding array’s i-th axis must be set to before_i and the padded elements succeeding array’s i-th axis must be set to after_i.
Defaults to 0.
Note
As of March, 2023 the values of the padded elements that are preceding wrt certain axes and succeeding wrt other axes is undefined as per
numpy.pad()
‘s spec.
- pytato.sum(a: Array, axis: int | tuple[int, ...] | None = None, initial: Any = 0, axis_to_reduction_descr: Mapping[int, ReductionDescriptor] | None = 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 theIndexLambda
is to be instantiated with.
- pytato.amin(a: ~pytato.array.Array, axis: int | tuple[int, ...] | None = None, initial: ~typing.Any = <class 'pytato.reductions._NoValue'>, axis_to_reduction_descr: ~collections.abc.Mapping[int, ~pytato.array.ReductionDescriptor] | None = 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 theIndexLambda
is to be instantiated with.
- pytato.amax(a: ~pytato.array.Array, axis: int | tuple[int] | None = None, *, initial: ~typing.Any = <class 'pytato.reductions._NoValue'>, axis_to_reduction_descr: ~collections.abc.Mapping[int, ~pytato.array.ReductionDescriptor] | None = 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 theIndexLambda
is to be instantiated with.
- pytato.prod(a: Array, axis: int | tuple[int, ...] | None = None, initial: Any = 1, axis_to_reduction_descr: Mapping[int, ReductionDescriptor] | None = 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 theIndexLambda
is to be instantiated with.
- pytato.all(a: Array, axis: int | tuple[int, ...] | None = None, axis_to_reduction_descr: Mapping[int, ReductionDescriptor] | None = 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 theIndexLambda
is to be instantiated with.
- pytato.any(a: Array, axis: int | tuple[int, ...] | None = None, axis_to_reduction_descr: Mapping[int, ReductionDescriptor] | None = 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 theIndexLambda
is to be instantiated with.
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(shape: ShapeType, dtype: np.dtype[Any], expr: ScalarExpression, bindings: Mapping[str, Array], var_to_reduction_descr: Mapping[str, ReductionDescriptor], *, axes: AxesT, tags: frozenset[Tag], non_equality_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 byVariable
s with names_1
,_2
, and so on.- expr¶
A scalar-valued
pymbolic
expression such asa[_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 theArray
interface, making array expressions available for use inexpr
.
- var_to_reduction_descr¶
A mapping from reduction variables in
expr
to theirReductionDescriptor
.
- with_tagged_reduction(reduction_variable: str, tags: Tag | Iterable[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, ...], redn_axis_to_redn_descr: Mapping[EinsumReductionAxis, ReductionDescriptor], *, axes: tuple[Axis, ...], tags: frozenset[Tag], non_equality_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 inEinsum.args
. An access_descriptor is a tuple ofEinsumAxisDescriptor
denoting how each axis of the argument will be operated in the einstein summation.
- 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 friendlierwith_tagged_reduction()
.
- with_tagged_reduction(redn_axis: EinsumReductionAxis, tags: Tag | Iterable[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], non_equality_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], non_equality_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)[source]¶
Base class for operations that remap the indices of an array.
Note that index remappings can also be expressed via
IndexLambda
.
- class pytato.array.Roll(array: Array, shift: int, axis: int, *, axes: tuple[Axis, ...], tags: frozenset[Tag], non_equality_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], non_equality_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[int | integer | Array, ...], order: str, *, axes: tuple[Axis, ...], tags: frozenset[Tag], non_equality_tags: frozenset[Tag] = frozenset({}))[source]¶
Reshape an array.
- array¶
The array to be reshaped
- newshape¶
The output shape
- order¶
Output layout order, either
C
orF
.
- class pytato.array.IndexBase(array: Array, indices: tuple[int | integer | NormalizedSlice | Array | None, ...], *, axes: tuple[Axis, ...], tags: frozenset[Tag], non_equality_tags: frozenset[Tag] = frozenset({}))[source]¶
Abstract class for all index expressions on an array.
- indices¶
- class pytato.array.BasicIndex(array: Array, indices: tuple[int | integer | NormalizedSlice | Array | None, ...], *, axes: tuple[Axis, ...], tags: frozenset[Tag], non_equality_tags: frozenset[Tag] = frozenset({}))[source]¶
An indexing expression with all indices being either an
int
orslice
.
- class pytato.array.AdvancedIndexInContiguousAxes(array: Array, indices: tuple[int | integer | NormalizedSlice | Array | None, ...], *, axes: tuple[Axis, ...], tags: frozenset[Tag], non_equality_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 inIndexBase.indices
.The reason for the existence of this class and
AdvancedIndexInNoncontiguousAxes
is thatnumpy
treats those two cases differently, and we’re bound to follow its precedent.
- class pytato.array.AdvancedIndexInNoncontiguousAxes(array: Array, indices: tuple[int | integer | NormalizedSlice | Array | None, ...], *, axes: tuple[Axis, ...], tags: frozenset[Tag], non_equality_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 thatnumpy
treats those two cases differently, and we’re bound to follow its precedent.
Input Arguments¶
- class pytato.array.InputArgumentBase[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[int | integer | Array, ...], *, axes: tuple[Axis, ...], tags: frozenset[Tag], non_equality_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 apyopencl.array.Array
. This must offershape
anddtype
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 ofdata
is(3, 4)
, andshape
is(nrows, ncolumns)
, then this represents a (global) constraint that thatnrows == 3
andncolumns == 4
. Arithmetic and other operations inpytato
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, aDataWrapper
instances compare equal to themselves (i.e. the very same instance).
- class pytato.array.Placeholder(shape: tuple[int | integer | Array, ...], dtype: dtype[Any], name: str, *, axes: tuple[Axis, ...], tags: frozenset[Tag], non_equality_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.
- class pytato.array.SizeParam(*, axes: tuple[Axis, ...] = (), tags: frozenset[Tag], non_equality_tags: frozenset[Tag] = frozenset({}), name: str)[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], *, tags: frozenset[Tag] = frozenset({})) DictOfNamedArrays [source]¶
Make a
DictOfNamedArrays
object.- Parameters:
data – member keys and arrays
- pytato.array.make_placeholder(name: str, shape: int | ~numpy.integer | ~pytato.array.Array | ~collections.abc.Sequence[int | ~numpy.integer | ~pytato.array.Array], dtype: ~typing.Any = <class 'numpy.float64'>, tags: frozenset[~pytools.tag.Tag] = frozenset({}), axes: tuple[~pytato.array.Axis, ...] | None = 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
, default isnumpy.float64
)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: str | None = None, shape: int | integer | Array | Sequence[int | integer | Array] | None = None, tags: frozenset[Tag] = frozenset({}), axes: tuple[Axis, ...] | None = 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: int | integer | Array, stop: int | integer | Array, step: int | integer)[source]¶
A normalized version of
slice
. “Normalized” is explained instart
andstop
.- start¶
An instance of
ShapeComponent
. Normalized to satisfy the relation0 <= start <= (axis_len-1)
, whereaxis_len
is the length of the axis being sliced.
- stop¶
An instance of
ShapeComponent
. Normalized to satisfy the relation-1 <= stop <= axis_len
, whereaxis_len
is the length of the axis being sliced.
- step¶
Traceback functionality¶
Please consider these undocumented and subject to change at any time.
- pytato.array.set_traceback_tag_enabled(enable: bool = True) None [source]¶
Enable or disable the traceback tag.
- class pytato.tags._PytatoFrameSummary(filename: str, lineno: int | None, name: str, line: str | None)[source]¶
Class to store a single call frame, similar to
traceback.FrameSummary
, but immutable.
- class pytato.tags._PytatoStackSummary(frames: tuple[_PytatoFrameSummary, ...])[source]¶
Class to store a list of
_PytatoFrameSummary
call frames, similar totraceback.StackSummary
, but immutable.
Internal stuff that is only here because the documentation tool wants it¶
- class pytato.array.IntegerT¶
An integer data type which is a union of integral types of
numpy
andint
.
- class pytato.array.Tag[source]¶
See
pytools.tag.Tag
.
Functions in Pytato IR¶
- pytato.trace_call(f: ~collections.abc.Callable[[...], ~pytato.function.ReturnT], *args: ~pytato.array.Array, identifier: ~collections.abc.Hashable | None = <class 'pytato.function._Guess'>, **kwargs: ~pytato.array.Array) ReturnT [source]¶
Returns the expressions returned after calling f with the arguments args and keyword arguments kwargs. The subexpressions in the returned expressions are outlined (opposite of ‘inlined’) as a
FunctionDefinition
.- Parameters:
identifier – A hashable object that acts as
pytato.tags.FunctionIdentifier.identifier
for theFunctionIdentifier
tagged to the outlinedFunctionDefinition
. IfNone
the function definition is not tagged with aFunctionIdentifier
tag, if_Guess
the function identifier is guessed fromf.__name__
.
- class pytato.function.Call(function: FunctionDefinition, bindings: Mapping[str, Array], *, tags: frozenset[Tag])[source]¶
Records an invocation to a
FunctionDefinition
.- function¶
The instance of
FunctionDefinition
being called by this call site.
- bindings¶
A mapping from the placeholder names of
FunctionDefinition
to their corresponding parameters in the invocation tofunction
.
- class pytato.function.NamedCallResult(_container: AbstractResultWithNamedArrays, name: str, *, axes: AxesT, tags: frozenset[Tag], non_equality_tags: frozenset[Tag] = frozenset({}))[source]¶
One of the arrays that are returned from a call to
FunctionDefinition
.- call¶
The function invocation that led to self.
- name¶
The name by which the returned array is referred to in
FunctionDefinition.returns
.
- class pytato.function.FunctionDefinition(parameters: frozenset[str], return_type: ReturnType, returns: Mapping[str, Array], *, tags: frozenset[Tag])[source]¶
A function definition that represents its outputs as instances of
Array
with the inputs beingPlaceholder
s. The outputs of the function can be a singlepytato.Array
, a tuple ofpytato.Array
s or an instance ofMapping[str, Array]
.- parameters¶
Names of the input
Placeholder
s to the function node. This is a superset of the names ofPlaceholder
instances encountered inreturns
. Unused parameters are allowed.
- return_type¶
An instance of
ReturnType
.
- returns¶
The outputs of the function call which are array expressions that depend on the parameters. The keys of the mapping depend on
return_type
as:If the function returns a single
pytato.Array
, then returns contains a single array expression with"_"
as the key.If the function returns a
tuple
ofpytato.Array
s, then returns contains entries with the key"_N"
mapping theN
-th entry of the result-tuple.If the function returns a
dict
mapping identifiers topytato.Array
s, then returns uses the same mapping.
- get_placeholder(name: str) Placeholder [source]¶
Returns the instance of
pytato.array.Placeholder
corresponding to the parameter name in function body.
Note
A
FunctionDefinition
comes with its own namespace based onparameters
. AMapper
-implementer must ensure not to reuse the cached result between the caller’s expressions and a function definition’s expressions to avoid unsound cache hits that could lead to incorrect mappings.Note
At this point, code generation/execution does not support distributed-memory communication nodes (
DistributedSend
,DistributedRecv
) within function bodies.
- class pytato.function.ReturnType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶
Records the function body’s return type in
FunctionDefinition
.
- class pytato.function.ReturnT¶
A type variable corresponding to the return type of the function
pytato.trace_call()
.
Internal stuff that is only here because the documentation tool wants it¶
- class pytato.function.Tag[source]¶
See
pytools.tag.Tag
.
- class pytato.function.AxesT¶
A
tuple
ofpytato.array.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: lp.TranslationUnit, bindings: Mapping[str, ArrayOrScalar], entrypoint: str, *, tags: frozenset[Tag])[source]¶
An array expression node representing a call to an entrypoint in a
loopy
translation unit.
- class pytato.loopy.LoopyCallResult(_container: LoopyCall, name: str, *, axes: AxesT, tags: frozenset[Tag], non_equality_tags: frozenset[Tag] = frozenset({}))[source]¶
Named array for
LoopyCall
’s result. Inherits fromNamedArray
.
- pytato.loopy.call_loopy(translation_unit: TranslationUnit, bindings: dict[str, Array | int | integer | float | complex | inexact | bool | bool], entrypoint: str | None = 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]
topytato.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¶
See
pytools.tag.Tag
.
- class pytato.loopy.AxesT¶
See
pytato.array.AxesT
.
- class lp.TranslationUnit¶
Scalar Expressions¶
Scalar expressions occur in shapes and in the
pytato.array.IndexLambda
.
- class pytato.scalar_expr.ScalarExpression¶
Like
ArithmeticExpressionT
inpymbolic
, but also allows Boolean values.
- pytato.scalar_expr.parse(s: str) ScalarExpression [source]¶
- pytato.scalar_expr.get_dependencies(expression: Expression, 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: Expression, variable_assignments: Mapping[str, Any] | None) Expression [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_assignments – A mapping from variable names to substitutions
- class pytato.scalar_expr.Expression¶