Trials

A trial is one container execution with one parameter set. It should run your workload once, emit metrics, and exit.

A trial is one run

Keep each trial deterministic enough to compare. If you need randomness, seed it from an explicit parameter or a stable experiment setting so results are explainable.

Trial lifecycle

Schedule: The platform selects a parameter set from the search space.
Start: Your image starts with managed CLI arguments and platform env vars.
Complete: Your workload finishes and exits with a status code.
Collect: Matching hpo.metrics.* lines become trial metrics.

Statuses (high level)

Phase	Statuses
Active	`created`, `queued`, `admitted`, `running`
Terminal	`succeeded`, `failed`, `cancelled`, `timed_out`, `preempted`, `lost`

A successful optimization step needs a terminal success and the configured objective metric keys present in collected metrics.

Platform environment

Every trial receives:

HYPEROPTIMIZER_TRIAL_ID
HYPEROPTIMIZER_EXPERIMENT_ID
HYPEROPTIMIZER_ORG_ID

Use these for logging or unique output paths. Do not set custom env vars with the HYPEROPTIMIZER_ prefix.

What not to do

Do not batch multiple backtests

A trial should represent one parameter set. Batching several backtests inside one container hides the data the optimizer needs.

Do not write metrics only to files

HyperOptimizer collects metrics from stdout. You can write artifacts too, but metric lines must be printed.

Do not mutate shared state unsafely

Parallel trials may run at the same time. Avoid shared output paths unless they include trial-specific identifiers.

Do not ignore failures

If a parameter set is invalid, fail clearly or print a penalty metric your objective can understand.