# Configure a run

Turn a one-off command into a run you can repeat, diff and hand to
someone else. This page introduces the configuration file, shows the fields
a first profile actually touches, and explains how the file and the
command line combine. The full key-by-key reference is generated from the
source on [Configuration](https://ambiqai.github.io/helia-profiler/reference/configuration/).

## Prerequisites

A completed [First profile](https://ambiqai.github.io/helia-profiler/getting-started/first-profile/), so you have a
`summary.json` to take the arena size from.

## Steps

### 1. Write a minimal file

```yaml title="hpx.yml"
model:
  path: examples/quickstart/kws_model.tflite

engine:
  type: helia-rt

target:
  board: apollo510_evb
  toolchain: gcc
```

Run it:

```bash
hpx profile --config hpx.yml
```

Everything not in the file falls back to the defaults you saw on First
profile: the `rtt` transport, the CPU counter group, 100 iterations, results
in `./results/`. `gcc` is the accepted short name for `arm-none-eabi-gcc`.

### 2. Understand the merge

The file is the baseline and every flag overrides the matching key, so a
file holds what does not change and the command line holds the experiment:

```bash
hpx profile --config hpx.yml --iterations 10 --board apollo3p_evb
hpx profile --config hpx.yml --toolchain armclang
hpx profile --config hpx.yml --power --power-duration 10
```

Common settings have CLI flags; engine-specific options and nested settings
may require YAML. Use the [command reference](https://ambiqai.github.io/helia-profiler/reference/cli/profile/)
for available flags and the [configuration reference](https://ambiqai.github.io/helia-profiler/reference/configuration/)
for all file keys.
Unknown fields in typed configuration sections are errors. `engine.config`
is a freeform mapping owned by the selected engine; see
[Engine configuration](https://ambiqai.github.io/helia-profiler/reference/engine-configuration/) for its supported options.

### 3. Set the fields a first profile touches

```yaml title="hpx.yml"
model:
  path: examples/quickstart/kws_model.tflite
  arena_size: 131072            # bytes; set from allocated_arena in summary.json
  arena_location: tcm           # writable memory supported by your target; omit for auto
  weights_location: mram

engine:
  type: helia-rt
  config:
    variant: release-with-logs  # keeps profiling hooks and SWO printf

target:
  board: apollo510_evb
  toolchain: arm-none-eabi-gcc
  transport: rtt

profiling:
  pmu_counters:
    cpu: default                # a curated group; all runs every counter in passes
    memory: default
  per_layer: true
  iterations: 100
  warmup: 5

output:
  format: csv
  dir: ./results
  model_explorer: true
```

| Block | What it decides | Read more |
|---|---|---|
| `model` | The model file, the tensor arena size, and where the arena and the weights live | [Memory placement](https://ambiqai.github.io/helia-profiler/guide/memory/) |
| `engine` | Which runtime executes the model and its build variant | [Engines](https://ambiqai.github.io/helia-profiler/guide/engines/) |
| `target` | The board, the compiler and the capture transport | [Boards](https://ambiqai.github.io/helia-profiler/guide/boards/), [Toolchains](https://ambiqai.github.io/helia-profiler/guide/toolchains/), [Transports](https://ambiqai.github.io/helia-profiler/guide/transports/) |
| `profiling` | Which counters, how many iterations, per-layer or whole-model | [PMU counters](https://ambiqai.github.io/helia-profiler/guide/pmu-counters/) |
| `output` | Format, directory and the Model Explorer overlay | [Output files](https://ambiqai.github.io/helia-profiler/guide/output/) |

The three top-level blocks not shown here, `power`, `timeouts` and `build`, and the
nested ones (`target.clock`, `target.psram`, `target.heartbeat`,
`power.ina228`, `build.nsx_modules`) exist for specific situations and are
documented with their defaults in the generated reference.

### 4. Keep runs apart

Two configurations side by side, two output directories:

```bash
hpx profile --config hpx_rt.yml  --output-dir results/rt
hpx profile --config hpx_aot.yml --output-dir results/aot
hpx compare results/rt results/aot
```

`hpx compare` reads both bundles and reports what changed and whether the
two runs are comparable at all; [Analysis and comparison](https://ambiqai.github.io/helia-profiler/guide/analysis-comparison/)
covers the rules it applies.

## Expected output

The same `results/` directory as First profile, now produced by
`hpx profile --config hpx.yml` with no other flags, and a file you can commit
next to the model. `run_metadata.json` in the bundle records the resolved
configuration, so you can inspect the effective settings, including CLI overrides.

## What next

[Where next](https://ambiqai.github.io/helia-profiler/getting-started/where-next/) routes you by what you want to measure. The
shipped configurations under `examples/quickstart/` and `configs/` are
complete files for common cases; the [Examples](https://ambiqai.github.io/helia-profiler/examples/) section
walks through them.