Iteration Spaces

Iteration Spaces#

class pystencils.backend.kernelcreation.iteration_space.IterationSpace(spatial_indices)#

Represents the n-dimensonal iteration space of a pystencils kernel.

Instances of this class represent the kernel’s iteration region during translation from SymPy, before any indexing sources are generated. It provides the counter symbols which should be used to translate field accesses to array accesses.

There are two types of iteration spaces, modelled by subclasses:

  • The full iteration space translates to an n-dimensional loop nest or the corresponding device indexing scheme.

  • The sparse iteration space translates to a single loop over an index list which in turn provides the spatial indices.

Parameters:

spatial_indices (Sequence[PsSymbol])

class pystencils.backend.kernelcreation.iteration_space.FullIterationSpace(ctx, dimensions, archetype_field=None)#

N-dimensional full iteration space.

Each dimension of the full iteration space is represented by an instance of FullIterationSpace.Dimension. Dimensions are ordered slowest-to-fastest: The first dimension corresponds to the slowest coordinate, translates to the outermost loop, while the last dimension is the fastest coordinate and translates to the innermost loop.

Parameters:
class Dimension(start, stop, step, counter)#

One dimension of a dense iteration space

Parameters:
static create_with_ghost_layers(ctx, ghost_layers, archetype_field)#

Create an iteration space over an archetype field with ghost layers.

Return type:

FullIterationSpace

Parameters:
static create_from_slice(ctx, iteration_slice, archetype_field=None)#

Create an iteration space from a sequence of slices, optionally over an archetype field.

Parameters:
property dimensions#

The dimensions of this iteration space

property lower: tuple[PsExpression, ...]#

Lower limits of each dimension

property upper: tuple[PsExpression, ...]#

Upper limits of each dimension

property steps: tuple[PsExpression, ...]#

Iteration steps of each dimension

property archetype_field: Field | None#

Field whose shape and memory layout act as archetypes for this iteration space’s dimensions.

property loop_order: tuple[int, ...]#

Return the loop order of this iteration space, ordered from slowest to fastest coordinate.

dimensions_in_loop_order()#

Return the dimensions of this iteration space ordered from the slowest to the fastest coordinate.

If this iteration space has an archetype field set, its field layout is used to determine the ideal loop order; otherwise, the dimensions are returned as they are

Return type:

Sequence[Dimension]

actual_iterations(dimension=None)#

Construct an expression representing the actual number of unique points inside the iteration space.

Parameters:

dimension (Union[int, Dimension, None]) – If an integer or a Dimension object is given, the number of iterations in that dimension is computed. If None, the total number of iterations inside the entire space is computed.

Return type:

PsExpression

compressed_counter()#

Expression counting the actual number of items processed at the iteration defined by the counter tuple.

Used primarily for indexing buffers.

Return type:

PsExpression

class pystencils.backend.kernelcreation.iteration_space.SparseIterationSpace(spatial_indices, index_list, coordinate_members, sparse_counter)#

Represents a sparse iteration space defined by an index list.

Parameters:
pystencils.backend.kernelcreation.iteration_space.get_archetype_field(fields, check_compatible_shapes=True, check_same_layouts=True, check_same_dimensions=True)#

Retrieve an archetype field from a collection of fields, which represents their common properties.

Raises:

KernelConstrainsError – If any two fields with conflicting properties are encountered.

Parameters:

  • fields (set[Field])

  • check_compatible_shapes (bool)

  • check_same_layouts (bool)

  • check_same_dimensions (bool)

pystencils.backend.kernelcreation.iteration_space.create_full_iteration_space(ctx, assignments, ghost_layers=None, iteration_slice=None, infer_ghost_layers=False)#

Create a dense iteration space from a sequence of assignments and iteration slice information.

This function finds all accesses to fields in the given assignment collection, analyzes the set of fields involved, and determines the iteration space bounds from these. This requires that either all fields are of the same, fixed, shape, or all of them are variable-shaped. Also, all fields need to have the same memory layout of their spatial dimensions.

Parameters:
Returns:

The constructed iteration space.

Return type:

IterationSpace

Raises:

Attention

The ghost_layers and iteration_slice arguments are mutually exclusive. Also, if infer_ghost_layers=True, none of them may be set.

Contents