pystencils.sympyextensions.random.Philox

pystencils.sympyextensions.random.Philox#

class pystencils.sympyextensions.random.Philox(name, dtype, seed, offsets=(), periodicity=(), num_cells=())#

Implementation of the Philox counter-based RNG with W = 32 and N = 4.

See https://doi.org/10.1145/2063384.2063405.

This Philox RNG computes 128 random bits using a bijection b_k, as b_k (n). Here, k is a subsequence key, and n is a 128-bit unsigned integer counter. The subsequence key of this implementation is given by the seed argument and an internal invocation key that is incremented by one at each call to get_random_vector.

The counter n is constructed by bitwise concatenation of a user-provided 32-bit external counter (passed to get_random_vector) and the up to three 32-bit spatial iteration indices of the kernel. The spatial indices may be shifted by user-defined offsets, set in the offsets parameter.

Parameters:

  • name (str) – Name of this RNG

  • dtype (str | type | dtype | PsType) – Data type of the random numbers; must be either float32 or float64

  • seed (Expr | int) – Expression or integer; the 32-bit unsigned integer seed for this RNG

  • offsets (Sequence[Expr | int]) – Optionally, offsets that are added to the iteration space counters when computing the random values

  • periodicity (Sequence[bool]) – Sequence of booleans indicating which spatial dimensions are periodic. For periodic dimensions, the spatial counter (after adding the offset) is wrapped using integer remainder with the corresponding num_cells entry, ensuring that cells on both sides of a periodic boundary receive the same random numbers.

  • num_cells (Sequence[Expr | int | None]) – Sequence of expressions or integers giving the number of cells (domain size) in each spatial dimension. Must be provided (non-None) for every dimension where periodicity is True.

class PhiloxState(name, dtype, invocation_key, seed, offsets, periodicity, num_cells)#
Parameters:
next()#

Return the RNG state for the next invocation

Return type:

PhiloxState

get_keys()#

Return the key tuple identifying the given RNG invocation’s number stream.

Parameters:

invocation – Expression that is a call to this RNG’s generator function

Return type:

tuple[Expr | int, ...]

Note

Must match the key arguments of the underlying RNG engine; see pystencils.backend.functions.PsRngEngineFunction.

get_counters(invocation, rank)#

Return the symbolic counter tuple identifying the position in the RNG’s number stream of the given invocation.

Parameters:

  • invocation – Expression that is a call to this RNG’s generator function

  • rank – Rank of the kernel’s iteration space

Return type:

tuple[Expr | int, ...]

Note

Must match the counter arguments of the underlying RNG engine; see pystencils.backend.functions.PsRngEngineFunction.

Contents