# Profile with hpx

Measure the module on the board rather than estimating it from the conversion
log. The two configurations select different engines and retain separate
results. Record engine, runtime and build differences when comparing them.

| Field | Value |
| --- | --- |
| Model | kws_ref, MLPerf Tiny keyword spotting, int8 |
| Target | `apollo510_evb` |
| Shows | The two-config comparison recipe and how to read it |
| CI | Manual. `hpx` builds firmware, flashes a board over a debug probe and runs the model on it; no runner here has one. |

The model is `audio/mlperf-tiny/kws_ref/model.tflite` from helia-model-zoo:
int8, 53,936 bytes, SHA-256 `aeea4368…bd0ae`, fetched by `run.sh` and checked
against the fixed SHA-256 recorded in the checked-in run script. Model licensing is not established by these hashes; see [Model provenance](https://ambiqai.github.io/helia-aot/examples/).

## Prerequisites

Use a repository checkout with Bash and the environment from [Running examples](https://ambiqai.github.io/helia-aot/examples/): `uv sync --frozen --group ci`, then activate `.venv`. Fetched models require network access, `curl` and `sha256sum` or `shasum`. Run the commands below from this example directory. Unlike the conversion-only examples, this script builds, flashes and runs firmware on the connected board.

## Run it

```sh
hpx --version
hpx doctor
./run.sh
```

Install and provision heliaPROFILER using its own version-matched setup
instructions before these commands. This AOT recipe does not pin or qualify a
current profiler release, probe or board setup. Record `hpx --version`, review
the configuration against that version, and reserve your board before running
`run.sh`, which builds and flashes firmware.

`hpx doctor` checks installed host tools and Python dependencies, not a
connected probe or board. Install the profiler's `aot` extra for this recipe;
a successful default doctor check alone does not establish AOT readiness. The script then runs both configs and the compare:

```sh
hpx profile --config hpx_rt.yml
hpx profile --config hpx_aot.yml
hpx compare results/comparison_rt results/comparison_aot --output-dir results/rt-vs-aot
```

## The two configs

[hpx_rt.yml](https://github.com/AmbiqAI/helia-aot/blob/cf2246a7ad439fa38d57462118e7840e5497a685/examples/profile-with-hpx/hpx_rt.yml) and [hpx_aot.yml](https://github.com/AmbiqAI/helia-aot/blob/cf2246a7ad439fa38d57462118e7840e5497a685/examples/profile-with-hpx/hpx_aot.yml) name the same model,
the same board and the same counters. They differ in the `engine` block and
the result destination (`output.dir`):

```yaml
engine:
  type: helia-rt
  config:
    variant: release-with-logs
```

```yaml
engine:
  type: helia-aot
  config:
    prefix: hpx
    module_name: hpx_model
```

## How to read the comparison

The script requests `compare_summary.json` under `results/rt-vs-aot`.
Inspect that summary's comparability decisions before quoting a difference.
Model identity, validity, topology and power scope can qualify different
metric families separately; a produced report is not blanket approval of all
metrics. Exact rules belong to the profiler version you ran.

Keep model inputs and intended board settings fixed. Runtime libraries,
compiler flags, logging and placement can still differ between engines;
record these as confounders. A profiling-image size is not runtime-only
support size, and source or flash bytes do not measure inference cycles.

Quote any measurement with the board, the two engine versions and the date it
was taken. A figure without them is not reproducible and does not survive the
next release of either engine.

## Next

- [Measure a conversion](https://ambiqai.github.io/helia-aot/guide/measure/)
  for the canonical AOT measurement workflow and interpretation.
- [MLPerf Tiny benchmark](https://ambiqai.github.io/helia-aot/guide/benchmarks/)
  for a comparison already run, with its labels.