pystencils.grids.staggered_field.StaggeredField

pystencils.grids.staggered_field.StaggeredField#

class pystencils.grids.staggered_field.StaggeredField(name, stencil, tensor_shape, patch=None, *, dtype=DynamicType.NUMERIC_TYPE, layout=MemoryLayout.LEFTMOST, ghost_layers=None)#

Field whose degrees of freedom live on the edges (faces) of a cell grid.

A staggered field stores one value – scalar or tensor-valued – per cell and per stored edge of a Staggering stencil. Only one of each pair of opposite directions is stored: the value belonging to the opposite direction lives on the corresponding edge of the neighbouring cell, seen with reversed orientation. The buffer therefore has shape

(*spatial_shape, len(stencil.staggered_entries), *tensor_shape)

linearized according to the field’s MemoryLayout – by default MemoryLayout.LEFTMOST, i.e. the leftmost spatial axis has stride one.

Accessing Values Two accessors are available, both taking an optional sequence of spatial offsets – interpreted relative to the current cell – followed by a direction selector:

  • u[...] addresses a stored edge directly. The selector may be a direction string, an offset tuple, or a stored-edge index. Addressing a direction that is not stored is an error.

  • u.face[...] addresses a cell face by any full-stencil direction. For a stored direction it yields the stored value; for its inverse it yields the negated value on the neighbouring cell’s edge.

Tensor components are selected by calling the resulting access, as for TensorField.

Examples:

u["e"]              # value stored on the eastern edge of the current cell
u[1, -1, 0, "e"]    # ... of the neighbour cell at offset (1, -1, 0)
u["e"](1)           # ... tensor component 1
u[i]                # the i-th stored edge of the current cell

u.face["e"]         # ->  u[0, 0, 0, "e"]
u.face["w"]         # -> -u[-1, 0, 0, "e"]
Parameters:

  • name (str) – Name of the staggered field

  • stencil (Staggering) – Staggering defining the stored edges and the spatial dimensionality

  • tensor_shape (tuple[int, ...]) – Shape of the tensor stored per cell and edge; () for a scalar field

  • patch (Patch | None) – Simulation-domain patch this field is defined on, or None for a free-standing field

  • dtype (str | type | dtype | PsType | DynamicType) – Data type of the field’s entries

  • layout (str | MemoryLayout) – Memory layout of the field’s memory buffers at runtime

  • ghost_layers (Union[int, Sequence[int | tuple[int, int]], None]) – Ghost-cell halo, either a single width for all sides, or a per-axis sequence of widths or (low, high) pairs. Defaults to the minimal halo under which every face access on an interior cell is in bounds, as dictated by stencil; pass 0 explicitly for a halo-free field.

property name: str#

Name of the field

property dtype: PsNumericType | DynamicType#

Data type of the field’s elements

property layout: MemoryLayout#

Memory layout of runtime buffers

property grid: PatchGrid | None#

The patch grid this field is defined on (cell placement), or None for a free-standing staggered field. Part of the IField protocol.

property patch: Patch | None#

The simulation-domain patch this field is defined on, or None.

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

Ghost-cell halo as a (low, high) pair per axis.

get_buffer_spec()#

Return the buffer specification defining the field’s memory properties

Return type:

FieldBufferSpec

get_iteration_limits()#

Return the iteration limits for kernels operating on this field

Return type:

IterationLimits

create_ndarray(array_module, spatial_shape, *, dtype=None, **kwargs)#

Allocate a backing array for this staggered field.

The spatial extent is the interior spatial_shape (the patch’s cell counts) enlarged by the field’s asymmetric ghost layers; the trailing dimensions hold the stored edges and, for vector grids, the components:

shape = (N_d + low_d + high_d for each axis) + (n_stored,) + tensor_shape

The array’s strides are set up to match the field’s layout.

Parameters:
view_ndarray(arr)#

Return the interior view of arr, stripping the ghost layers.

property face: _FaceProxy[StaggeredFieldAccess]#

Accessor for cell faces addressed by any full-stencil direction.

Subscripts are parsed as for [], but any full-stencil direction is admissible. For a stored direction the accessor yields the stored value; for its inverse it yields the negated value on the corresponding edge of the neighbouring cell – the same face, seen with reversed orientation:

u.face["e"]   # ->  u[0, 0, 0, "e"]
u.face["w"]   # -> -u[-1, 0, 0, "e"]
Contents