Skip to content
heliaPROFILER
Reference
HELIA

identity

Shared identity vocabulary: the identity of a captured run and the build, run, energy, runtime and kernel facts it names, canonical engine and kernel names with today’s spellings as aliases, unknown facts that carry their reason, and the semantic hashes that name their kind and basis version.

Every name on this page is imported from helia_profiler.

API tier: experimental

Generated from the src/helia_profiler tree f38e378c801d34438affb680257217e0b58d2cd1.

Machine-readable model

  • CanonicalEngineclassAn inference engine, by its shared name.
  • CanonicalKernelclassA kernel library, by its shared name.
  • UnknownclassA fact that could not be determined, with the reason.
  • SemanticHashclassA hash that names its producer, its kind and its basis version.
  • canonical_enginefunctionThe shared name for an engine, from its canonical name or any alias.
  • canonical_kernelfunctionThe shared name for a kernel library, from its canonical name or any alias.
  • RuntimeIdentityclassThe runtime a build linked: its engine, source repository, version and commit.
  • KernelIdentityclassThe kernel library a build linked, taken from the module or archive it linked.
  • BuildFactsclassHow the image was built and placed.
  • EnergyFactsclassThe method a run's energy is measured with, whether or not the capture succeeded.
  • RunFactsclassHow the model was run: state handling, invocation counts, the timed span and its clock.
  • RunIdentityclassEverything a comparison needs to know about what ran.
class

CanonicalKernel

Python

A kernel library, by its shared name.

src/helia_profiler/identity.py:33

CanonicalKernel()

A kernel library, by its shared name.

CMSIS_NN is Arm’s CMSIS-NN. HELIA_CORE is heliaCORE, the product name of Ambiq’s ns-cmsis-nn library.

API tier: experimental

class

SemanticHash

Python

A hash that names its producer, its kind and its basis version.

src/helia_profiler/_semantic_hash.py:71

SemanticHash(producer: str, kind: str, version: int, hex: str) -> None

dataclass

A hash that names its producer, its kind and its basis version.

The text form is <producer>.<kind>/<version>:sha256:<hex>: producer and kind are lowercase words joined by -, the version a positive integer, and the hex 64 lowercase digits. heliaPROFILER’s hashes have the producer hpx and the kinds intent, build, observation, binding, inputs and target-config; :meth:parse reads any producer’s. Compare two hashes only when their producer, kind and version match.

API tier: experimental

method

parse

Python

Read text, refusing anything not in the semantic hash form.

src/helia_profiler/_semantic_hash.py:97

parse(text: str) -> SemanticHash

classmethod

Read text, refusing anything not in the semantic hash form.

Raises

Errors raised by parse
TypeDescription
ValueError*text* is not ``<producer>.<kind>/<version>:sha256:<hex>``, for example bare hex, uppercase hex or a missing version.
function

canonical_engine

Python

The shared name for an engine, from its canonical name or any alias.

src/helia_profiler/identity.py:84

canonical_engine(name: str) -> CanonicalEngine

The shared name for an engine, from its canonical name or any alias.

API tier: experimental

function

canonical_kernel

Python

The shared name for a kernel library, from its canonical name or any alias.

src/helia_profiler/identity.py:89

canonical_kernel(name: str) -> CanonicalKernel

The shared name for a kernel library, from its canonical name or any alias.

API tier: experimental

class

RuntimeIdentity

Python

The runtime a build linked: its engine, source repository, version and commit.

src/helia_profiler/identity.py:105

RuntimeIdentity(
    engine: CanonicalEngine,
    repository: str | Unknown,
    version: str | Unknown,
    commit: str | Unknown,
) -> None

dataclass

The runtime a build linked: its engine, source repository, version and commit.

API tier: experimental

class

KernelIdentity

Python

The kernel library a build linked, taken from the module or archive it linked.

src/helia_profiler/identity.py:115

KernelIdentity(
    library: CanonicalKernel | Unknown,
    repository: str | Unknown,
    version: str | Unknown,
    commit: str | Unknown,
) -> None

dataclass

The kernel library a build linked, taken from the module or archive it linked.

API tier: experimental

class

BuildFacts

Python

How the image was built and placed.

src/helia_profiler/identity.py:125

BuildFacts(
    toolchain: str | Unknown,
    toolchain_version: str | Unknown,
    board: str,
    cpu_hz: int | Unknown,
    clock_profile: str | Unknown,
    arena_location: str | Unknown,
    weights_location: str | Unknown,
    arena_bytes: int | Unknown,
) -> None

dataclass

How the image was built and placed.

API tier: experimental

class

EnergyFacts

Python

The method a run's energy is measured with, whether or not the capture succeeded.

src/helia_profiler/identity.py:142

EnergyFacts(scope: str, rail: str | Unknown, subtraction: str, completion_protocol: int) -> None

dataclass

The method a run’s energy is measured with, whether or not the capture succeeded.

scope is what the measured window covers: gross_rail_restore_and_invoke is everything the rail draws over the timed restore-and-invoke loop. rail is the physical rail the run measures, such as MCU: the rail requested, also after a failed capture, and unknown only where no request is at hand, as in a build’s identity before it runs. subtraction is what is taken off the measurement, none when nothing is. completion_protocol is the version of the firmware’s READY, GO and DONE handshake that bounds the window. The measurement itself, or its absence, is the run’s outcome, such as RunResult.energy.

API tier: experimental

class

RunFacts

Python

How the model was run: state handling, invocation counts, the timed span and its clock.

src/helia_profiler/identity.py:164

RunFacts(
    lifecycle: str,
    iterations: int,
    warmups: int,
    timing_scope: str,
    instance_boundary: str | Unknown = _UNRECORDED,
    first_invoke_initializer: bool | Unknown = _UNRECORDED,
    first_invoke_window: str | Unknown = _UNRECORDED,
    timing_clock: str | Unknown = _UNRECORDED,
    timing_clock_hz: int | Unknown = _UNRECORDED,
    timing_statistic: str | Unknown = _UNRECORDED,
    energy: EnergyFacts | Unknown | None = None,
) -> None

dataclass

How the model was run: state handling, invocation counts, the timed span and its clock.

timing_scope is what each timed span covers: invoke_only or restore_and_invoke, which also restores the fixed inputs. instance_boundary is where one model instance ends: boot when the engine initializes once and every invocation reuses it, invocation when each invocation loads and initializes its own. first_invoke_initializer is whether the first invocation of an instance runs the model’s one-time initializer, such as a LiteRT CALL_ONCE subgraph, and first_invoke_window where that invocation falls: warmup or measured. timing_clock is the clock that times the span, cpu cycles or the 32.768 kHz stimer; timing_clock_hz is its configured rate, not a measured one. timing_statistic is what the reported time is: the total over the measured invocations or their mean. energy is the method the run’s energy is measured with, stated after a failed capture too, and None when the run measures no energy; whether it was measured is the outcome, not a fact here.

API tier: experimental

class

RunIdentity

Python

Everything a comparison needs to know about what ran.

src/helia_profiler/identity.py:199

RunIdentity(
    runtime: RuntimeIdentity,
    kernels: KernelIdentity,
    prepared_archive_sha256: str | None,
    build: BuildFacts,
    baseline_id: str | Unknown,
    dependency_lock_sha256: str | Unknown,
    model_sha256: str | Unknown,
    inputs_hash: str | Unknown,
    run: RunFacts,
    producer: str | Unknown,
    build_hash: str | Unknown,
    observation_hash: str | None = None,
    intent_hash: str | None = None,
) -> None

dataclass

Everything a comparison needs to know about what ran.

build_hash covers the flashed image, the dependency lock, the linked runtime archive and the model, and never the HPX release (producer), so it changes only when what runs changes. observation_hash covers a capture’s measured facts, so the same firmware measured twice gives two. intent_hash is the :attr:~helia_profiler.FrozenRun.intent_hash of the plan a run was built from, and None for a run built without one. inputs_hash covers each pinned input’s tensor name and data sha256. The four are :class:~helia_profiler.SemanticHash strings of the kinds hpx.build, hpx.observation, hpx.intent and hpx.inputs; each *_sha256 fact is the bare hex sha256 of one file’s bytes.

API tier: experimental

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