compiled_build

Build once, run later: a frozen plan’s compiled firmware, bound to its plan and saved so any host can verify, relocate and capture from it, each run saved as a verifiable result that loads back on any host, how model state carries across a run’s invocations, and the build and capture records a compiled build and a run result carry. The hpx freeze, hpx build, hpx validate build and hpx run commands drive the same flow from the command line.

Every name on this page is imported from helia_profiler.

API tier: experimental

Generated from the src/helia_profiler tree f38e378c801d34438affb680257217e0b58d2cd1.

Machine-readable model

LifecycleclassState handling across invocations.
hpx_cache_rootfunctionReturn the root directory for hpx's persistent caches.
CompiledBuildclassA frozen plan and the firmware compiled from it, verifiable on any host.
RunResultErrorclassA saved run result that does not load; code names the check it failed.
RunResultRecordclassA saved run result, loaded and verified.
load_runfunctionRead and verify a run result saved by :meth:RunResult.save, resolving paths under roots.
RunResultclassOne capture from a :class:CompiledBuild.
buildfunctionCompile plan for fixture's pinned inputs and return the compiled build.
load_buildfunctionRead and verify a compiled build written by :meth:CompiledBuild.save.
run_buildfunctionFlash compiled's image, capture one run and compare outputs; see :meth:CompiledBuild.run.

Lifecycle()

State handling across invocations.

CARRY initializes one instance and keeps its internal state through warmups and timed invocations, restoring only the fixed inputs each time. SINGLE runs one measured invocation per initialized instance, so no state carries between invocations. Where an instance ends is the engine’s :class:InstanceBoundary: for a boot engine SINGLE is one timed invocation and no warmups per boot; for an invocation engine, such as ExecuTorch, every invocation is its own instance, so several measurements are several instances, never one carried state. The fixture firmware refuses a timed span of zero ticks of its 32.768 kHz timer, so a SINGLE invocation shorter than about 30.5 µs can fail as TIMING_BOUND.

API tier: experimental

CARRY = 'carry'

SINGLE = 'single'

hpx_cache_root() -> Path

Return the root directory for hpx’s persistent caches.

Resolved at call time so environment overrides apply per-invocation; callers must not cache the result at import time.

API tier: experimental

CompiledBuild(plan: FrozenRun, build: FixtureBuild, lifecycle: Lifecycle, binding: str) -> None

dataclass

A frozen plan and the firmware compiled from it, verifiable on any host.

binding, an hpx.binding semantic hash, ties the build to the plan and lifecycle it was compiled from; :func:build computes it and :meth:verify recomputes it.

API tier: experimental

plan: FrozenRun

build: FixtureBuild

lifecycle: Lifecycle

binding: str

identity: RunIdentity

The build’s identity, with its plan’s intent_hash; observation_hash is None until it runs.

verify() -> None

Re-check the build against its pinned files and its plan; raise on any mismatch.

The build’s files must match their hashes, the plan its intent hash, and the binding the plan, lifecycle and build. The facts the build records must be the ones the plan states: engine, board, model, toolchain and its version, arena and weights placement, arena size, clock profile and the lifecycle’s invocation counts.

The runtime version and commit and the kernel commit are compared wherever both the plan and the build state one; a build or plan that states none of a fact is not compared on it. heliaRT and heliaAOT compare with the plan’s pins. LiteRT compares with this HPX’s prepared LiteRT record, because the plan pins the modules an ordinary profile builds from source, which a fixture build does not link.

Raises

Errors raised by verify
Type	Description
`ConfigError`	Naming the first fact that does not match.

save(path: str | Path, *, roots: Mapping[str, Path]) -> Path

Write the build as JSON with paths relative to roots and return its path.

load(path: str | Path, *, roots: Mapping[str, Path]) -> CompiledBuild

classmethod

Read and verify a build written by :meth:save, resolving paths under roots.

run(
    *,
    guard: FixtureCaptureGuard,
    jlink_serial: str,
    evidence_dir: Path,
    settle_seconds: float,
    expect: Expect | None = None,
    expected_duration_s: float | None = None,
    power: FixtureRailPowerRequest | FixtureBoardPowerRequest | None = None,
    power_guard: FixturePowerGuard | None = None,
) -> RunResult

Flash the recorded image, capture one run and compare outputs when expect is given.

A failed capture comes back with capture.state == "failure" and no verification; errors raised while capturing propagate.

power selects the instrument: a :class:FixtureRailPowerRequest measures the MCU rail of a build compiled with the same power_sync wiring, and a :class:FixtureBoardPowerRequest powers the board through a configured supply for a timing capture of a build without power wiring. Either needs power_guard, the station’s authority over that instrument and rail; guard keeps its authority over the board and probe. Every refusal comes before the device is touched.

Raises

Errors raised by run
Type	Description
`ConfigError`	The build does not verify, expect cannot be compared, or power does not fit the build or the run API's rail-energy route.
`CaptureError`	The device reports counts other than the build's.

RunResultError(code: str, message: str, *, hint: str | None = None) -> None

A saved run result that does not load; code names the check it failed.

The codes are the verified result reader’s: invalid_json (not strict JSON), unsupported_schema (another schema or version), invalid_path (unusable roots, or a result not where it records itself), artifact_changed (a pinned file missing or changed), runtime_missing (the build’s prepared runtime is not in the cache), identity_mismatch (the identity or output comparison does not recompute) and invalid_evidence (anything else: an unreadable or malformed result, a build that does not verify, a power request the build cannot take).

API tier: experimental

code = code

RunResultRecord(
    path: Path,
    size_bytes: int,
    sha256: str,
    hpx_version: str,
    result: RunResult,
    document: Mapping[str, Any],
) -> None

dataclass

A saved run result, loaded and verified.

path, size_bytes and sha256 identify the saved document, document is its JSON, which the portable view cites by JSON pointer, hpx_version is the heliaPROFILER that wrote it, and result is the run it records.

API tier: experimental

path: Path

size_bytes: int

sha256: str

hpx_version: str

result: RunResult

document: Mapping[str, Any]

load_run(path: str | Path, *, roots: Mapping[str, Path]) -> RunResultRecord

Read and verify a run result saved by :meth:RunResult.save, resolving paths under roots.

API tier: experimental

Raises

Errors raised by load_run
Type	Description
`RunResultError`	A ``ConfigError`` naming the first check that fails: the schema or version, the compiled build, a pinned file, the identity or the output comparison.

RunResult(
    compiled: CompiledBuild,
    capture: FixtureCaptureResult,
    identity: RunIdentity,
    verification: Verification | None,
    power: FixtureRailPowerRequest | FixtureBoardPowerRequest | None = None,
) -> None

dataclass

One capture from a :class:CompiledBuild.

power is the power request the run was captured with, or None.

API tier: experimental

compiled: CompiledBuild

capture: FixtureCaptureResult

identity: RunIdentity

verification: Verification | None

power: FixtureRailPowerRequest | FixtureBoardPowerRequest | None = None

succeeded: bool

True only for a success capture.

energy: FixtureRailEnergy | None

The capture’s gross MCU-rail energy, or None when it measured none.

It holds the measured iterations, duration, mean power and current, energy and energy per iteration, the rail and instrument serial, the hash-pinned raw instrument trace, and the protocol-2 READY, GO, gate and DONE samples in completion. A failed capture measures none.

save(path: str | Path, *, roots: Mapping[str, Path], build: str | Path) -> Path

Write the run as a hpx.run-result with paths relative to roots and return its path.

build is the file the run’s compiled build was saved to; the result pins it by sha256 and size. The capture’s files are pinned as they are; the reference outputs of a verification are written beside the result under unique names and pinned too. Every path must sit under one of roots. :func:load_run reads it back.

Raises

Errors raised by save
Type	Description
`ConfigError`	build is not this run's compiled build, a file is missing or changed, a path is under no root, or the identity or verification does not recompute from the build and capture.

build(
    plan: FrozenRun,
    fixture: TypedFixture,
    *,
    method: FixtureMethod,
    lifecycle: Lifecycle = Lifecycle.CARRY,
    runtime: PreparedUpstreamRuntime | None = None,
    model: str | Path | None = None,
    host: Mapping[str, object] | None = None,
    observe_aot_arenas: bool = False,
    observe_ram: bool = False,
) -> CompiledBuild

Compile plan for fixture’s pinned inputs and return the compiled build.

lifecycle must be one the plan’s engine implements; it sets the timed iterations and warmups the firmware runs. A method with power_sync compiles the protocol-2 power firmware, which a run measures with a matching :class:~helia_profiler.FixtureRailPowerRequest; it is admitted for a heliaAOT or LiteRT plan on the apollo510_evb under Lifecycle.CARRY, and refused otherwise. A plan frozen with power enabled needs such a method. host supplies host-local settings, such as {"work_dir": ...}, as :meth:FrozenRun.config does. heliaRT and LiteRT link a prepared runtime: without runtime, the one the plan names is taken from the HPX cache (hpx runtimes prepare), never downloaded or built. The result is verified before it is returned.

API tier: experimental

load_build(path: str | Path, *, roots: Mapping[str, Path]) -> CompiledBuild

Read and verify a compiled build written by :meth:CompiledBuild.save.

API tier: experimental

run_build(
    compiled: CompiledBuild,
    *,
    guard: FixtureCaptureGuard,
    jlink_serial: str,
    evidence_dir: Path,
    settle_seconds: float,
    expect: Expect | None = None,
    expected_duration_s: float | None = None,
    power: FixtureRailPowerRequest | FixtureBoardPowerRequest | None = None,
    power_guard: FixturePowerGuard | None = None,
) -> RunResult

Flash compiled’s image, capture one run and compare outputs; see :meth:CompiledBuild.run.

API tier: experimental

Machine-readable: compiled_build.json · compiled_build.md, complete and lossless.