Simulation inputs

These types describe NumSim inputs and numerical comparisons. Unless otherwise noted, import them from tirx_harness.numsim. Fields and defaults below are read from the Python source. These are data classes; construct them with the listed field names as keyword arguments.

Reusable cases and comparisons

class tirx_harness.numsim.NumSimCase

kernel: Any

args: dict[str, numpy.ndarray | Any]

outputs: tuple[str, ...] | dict[str, str] | None

reference: collections.abc.Callable[[], dict[str, Any]]

comparisons: dict[str, ComparisonSpec]

subset: Any | None = None

assumptions: ExecutionAssumptions | None = None

kernel is the specialized TIRx function; args binds its parameters, including output storage. outputs selects the result buffers. reference is a zero-argument callable returning a dictionary of expected outputs; comparisons maps output names to comparison specifications. Pass the case to run_case().

class tirx_harness.numsim.ComparisonSpec

rtol: float = 1e-05

atol: float = 1e-08

equal_nan: bool = False

actual_encoding: str | None = None

regions: tuple[ComparisonRegion, ...] = ()

rtol and atol are finite, nonnegative relative and absolute tolerances. equal_nan controls whether matching not-a-number values compare equal. actual_encoding="bfloat16" decodes a simulated output’s integer backing storage before comparison. regions optionally restricts the compared areas.

class tirx_harness.numsim.ComparisonRegion

actual: tuple[int | slice, ...]

expected: tuple[int | slice, ...] | None = None

actual and expected are tuples of integer indices or slices. If expected is omitted, the same selection is used for both arrays. Selected regions must be nonempty and have matching shapes.

Tensor maps

A tensor map describes the storage and tile shape for a tensor-memory transfer. Use TensorMap(...).numpy() to create a simulator descriptor, then bind that array under the kernel’s tensor-map parameter name. This descriptor is for CPU simulation.

class tirx_harness.numsim.TensorMap

Build NumSim’s copyable 128-byte TensorMap descriptor image.

global_strides contains exactly rank - 1 descriptor byte strides; the contiguous innermost element stride is implicit. tma_dtype may select tf32, float32_ftz or tf32_ftz on float32 storage, or uint6 on packed uint8 storage. FTZ affects tensor reductions, not ordinary copies. U6 has direction-specific shared packing.

base: numpy.ndarray

global_shape: tuple[int, ...]

global_strides: tuple[int, ...]

box_shape: tuple[int, ...]

element_strides: tuple[int, ...]

dtype: str | None = None

tma_dtype: str | None = None

fp4_shared_layout: str | None = None

swizzle: str | None = None

interleave: str | None = None

fill_mode: str | None = None

im2col: Im2col | None = None

numpy() → numpy.ndarray

Return a copyable uint8[128] descriptor image.

Shapes and element strides follow the descriptor’s dimension order, with the innermost dimension first; global strides are in bytes. Tensor Memory Accelerator (TMA) dtype overrides include TensorFloat-32 (tf32), flush-to-zero (ftz) floating-point modes, and packed six-bit unsigned values (uint6). fp4_shared_layout selects a four-bit floating-point storage layout.

class tirx_harness.numsim.Im2col

Spatial filter-base bounds, in W/H/D order; upper corners are end-relative.

For wide mode only W has bounds. TensorMap.box_shape is the resulting two-dimensional column shape: (channels per pixel, pixels per column).

lower_corner: tuple[int, ...]

upper_corner: tuple[int, ...]

wide: bool = False

Im2col describes an image-to-column transfer for convolution. Its spatial coordinates use width, height, and depth order (W/H/D).

Launch selection

Most callers execute the full launch. To select complete clusters or thread blocks, import ExecutionSubset from tirx_harness.numsim.api and pass it as subset to Engine.run. A cooperative thread array (CTA) is a thread block. For a multi-kernel launch, use a mapping from phase indices to selections.

class tirx_harness.numsim.api.ExecutionSubset

Select launch domains for execution.

cluster_ids are cluster coordinates. cta_ids are flattened global CTA IDs and must select a union of complete clusters; a single CTA is a complete cluster when ctas_per_cluster == 1. When both are present, NumSim executes their intersection.

cluster_ids: tuple[int, ...] | list[int] | None = None

cta_ids: tuple[int, ...] | list[int] | None = None

tirx_harness.numsim.api.ExecutionSubsetSelection

This type alias accepts an ExecutionSubset or a mapping from integer phase indices to ExecutionSubset objects.

class tirx_harness.numsim.ExecutionAssumptions

Optional external launch facts accepted by the execution API.

External grid dependencies are satisfied automatically at an isolated NumSim launch boundary; explicit phase entries remain accepted for compatibility.

external_grid_dependencies_satisfied: tuple[int, ...] | list[int] = ()