Numerical simulation¶

NumSim is the CPU numerical simulator exposed by from tirx_harness import numsim. It compiles a specialized TIRx function into a cached Rust artifact, executes it with concrete inputs, and lets you compare its outputs with an independent reference. See the runnable example and supported-model limitations.

Compile and execute¶

tirx_harness.numsim.transpile(func: Any, *, cache_dir: str | pathlib.Path | None = None, _default_generated_opt_level: int = 3, _analysis_capable: bool = False, _analysis_checker: Literal['synccheck', 'racecheck'] | None = None) → CompiledModule¶: Verify, emit, build, and cache a native Rust NumSim artifact.

Pass a TIRx function, such as a TIRx-lite kernel’s .func, and optionally a cache directory. Keyword parameters beginning with _ are implementation controls; ordinary callers should leave them at their defaults.

class tirx_harness.numsim.CompiledModule¶

property cache_key: str¶

property rust_source: str¶

property library_path: pathlib.Path¶

Obtain a compiled module from transpile; pass it to Engine.run or the inspection helpers below.

class tirx_harness.numsim.Engine(max_workers: int | Literal['auto'] = 8, *, native_loop_iteration_budget: int = _DEFAULT_NATIVE_LOOP_ITERATION_BUDGET, native_loop_reschedule_quantum: int = _DEFAULT_NATIVE_LOOP_RESCHEDULE_QUANTUM)¶

Python facade for a generated artifact’s Rust-owned EngineState.

property max_workers: int¶

property native_loop_iteration_budget: int¶

property native_loop_reschedule_quantum: int¶

run(module: CompiledModule, inputs: dict[str, Any], *, subset: ExecutionSubsetSelection | None = None, assumptions: ExecutionAssumptions | None = None, outputs: collections.abc.Iterable[str] | collections.abc.Mapping[str, str] | None = None) → NumSimResult¶

max_workers must be a positive integer, or "auto" to use the detected CPU count. The loop budget bounds native loop iterations; the reschedule quantum controls how often loop execution yields to other work. Both must be positive integers.

For run, inputs maps kernel parameter names to concrete scalars and CPU NumPy buffers, including output storage. outputs selects buffer names or maps result names to buffer names; None selects the bound output buffers. The input types describe optional launch subsets and assumptions.

class tirx_harness.numsim.NumSimResult¶

outputs: dict[str, Any]¶

diagnostics: list[dict[str, Any]] = []¶

stats: dict[str, Any]¶

property verdict: str¶

assert_close(expected: dict[str, Any], tolerances: dict[str, ComparisonSpec] | None = None) → None¶

outputs contains the selected arrays, diagnostics contains simulator messages, and stats contains execution statistics. The result’s verdict reflects simulator advisories; compare against a reference to check numerical correctness. assert_close performs that comparison and raises on a mismatch. Simulation statistics do not measure GPU latency.

Compare outputs¶

tirx_harness.numsim.compare(result: NumSimResult, expected: dict[str, Any], *, tolerances: dict[str, ComparisonSpec] | None = None) → NumSimReport¶

expected must be a nonempty mapping from output names to reference arrays. Use tolerances to supply a ComparisonSpec per output. Without an explicit specification, integer and boolean arrays use exact equality; floating-point comparisons use the specification’s defaults.

tirx_harness.numsim.run_case(case: NumSimCase, *, engine: Engine | None = None) → NumSimReport¶

Compile, execute, and compare a NumSimCase in one call. Supply an existing engine to reuse its execution configuration.

class tirx_harness.numsim.report.NumSimReport¶

ok: bool¶

mismatches: list[Mismatch] = []¶

diagnostics: list[dict] = []¶

property verdict: str¶

require_ok() → None¶

require_ok() raises AssertionError when a numerical comparison fails. An advisory can leave ok=True while verdict is review; keep the diagnostics alongside the numerical result.

class tirx_harness.numsim.report.Mismatch¶

output: str¶

index: tuple[int, ...]¶

actual: object¶

expected: object¶

render() → str¶

Inspect the simulator artifact¶

tirx_harness.numsim.dump_rust(module: CompiledModule) → str¶: Return the exact Rust source compiled for an artifact.

tirx_harness.numsim.dump_semantic_manifest(module: CompiledModule) → dict[str, Any]¶: Return the serializable compile-time TIRx coverage/source manifest.

Exceptions¶

These exceptions describe transpilation, build, and execution failures. Checker entry points instead return reports for the failures they handle; inspect their verdicts as described in Checkers and reports.

exception tirx_harness.numsim.NumSimError¶

Bases: RuntimeError

Base class for NumSim failures.

exception tirx_harness.numsim.UnsupportedTIRxError(message: str, *, unsupported: tuple[str, ...] = (), source_span: Any = None)¶