Interactive Python session

Goal

Use hpx as a library. You will learn how a Session is built from YAML or from method calls, why every with_* call returns a new session, how to inspect a resolved configuration before a build, and how to profile and compare from Python.

Hardware and wiring

None for the discovery and resolve steps. An Apollo510 EVB on J-Link for the profile step.

Software prerequisites

hpx in the notebook’s kernel. From a source checkout:

uv sync --group notebook --extra analysis --extra aot

analysis enables Session.analyze() and aot the heliaAOT branch. Toolchains, CMake, Ninja and J-Link come from the kernel’s PATH.

Config file

examples/quickstart/hpx_rt.yml, loaded with Session.from_yaml; the same keys can be given as method arguments instead.

Run

import helia_profiler as hpx

session = hpx.Session.from_yaml("examples/quickstart/hpx_rt.yml")
config = session.resolve()
print(config.target.board, config.engine.type, config.target.toolchain,
      config.profiling.pmu_counters, config.model.arena_size)

aot = session.with_engine("helia-aot").with_output(dir="results/aot")
print(aot.resolve().engine.type, aot.resolve().output.dir)

doctor = session.show(session.doctor())

Then, with a board attached:

rt_result = session.with_output(dir="results/rt").profile()
aot_result = aot.profile()
comparison = session.compare(rt_result, aot_result, output_dir="results/rt-vs-aot")

Expected output

The first block, run on the host on 2026-09-21 with hpx 0.1.6 from the repository root:

apollo510_evb helia-rt arm-none-eabi-gcc {'cpu': 'default', 'memory': 'default'} 131072
helia-aot results/aot

followed by the hpx doctor table that show() renders. The profile step returns a ProfileResult without console presentation. Pass a progress_sink callback to receive structured progress updates.

How to read it

• resolve() returns the fully validated ProfileConfig the pipeline would run: every default filled in, every key checked, no hardware touched. Print it, or session.save("experiment.yml") to write the intent back out as YAML.
• A session is immutable, so session is unchanged after with_engine; a base session can fan out into engine, placement, counter or power branches that share everything else.
• show() renders a Rich table and returns the typed value, so doctor.ok and doctor.checks remain available for a script.
• ProfileResult carries the merged layers, PMU presets and groups, firmware metadata, memory placement, optional power data, run provenance, report_paths, and optional evaluation; compare() accepts results or result directories and returns the CompareResult the CLI prints.
• session.analyze() runs the host-side model analysis for the configured engine; session.boards(), engines(), counters("cpu"), probes() and ports() are the discovery calls, each typed.

result.evaluation exposes the report’s existing RunEvaluation, whose payload remains experimental. None means no evaluation was supplied, not VALID. The optional field is appended, so existing positional construction still works; dataclass field introspection includes the new field. This in-memory addition does not change saved profile, build or run schemas. output.fail_on_invalid controls CLI exit status only; Python callers receive the result even when its evaluation is INVALID.

Variations

• Without a file: hpx.Session().with_model(hpx.examples.tiny_cnn(), arena_size=65536).with_target(board="apollo510_evb", toolchain="gcc", transport="rtt") uses the packaged tiny CNN, a deterministic int8 model materialised into the hpx cache, so no checkout is needed.
• with_profiling(iterations=100, warmup=5, pmu_counters={"cpu": "all"}) and with_power(enabled=True, driver="joulescope") branch the other sections.
• Session.load("experiment.yml") restores a saved intent; with_overrides({...}) applies a mapping of dotted keys.
• The walkthrough notebook examples/notebooks/hpx_walkthrough.ipynb runs the packaged model through heliaRT and heliaAOT and then digs into layer timing distributions, compute-unit lanes, hotspots, memory regions, engine comparison and exports, with optional power capture.

Validated on

Host-only steps validated: the resolve and branch block above was executed on 2026-09-21 with hpx 0.1.6 and produced the output shown. The profile and compare steps are not yet validated from Python; the same configuration run through the CLI is validated on Profile a model. The walkthrough notebook is not yet validated on hardware.