Formats¶
The exact schema of every file you upload and every file you receive, as enforced by helyx validate and by the service. A complete valid example set is at intraday-docs.helyx-energy.com/examples/ (pm_targets.jsonl, da_cleared.csv, delivered.csv, config.yaml, request.json) and is written locally by helyx examples.
Conventions that apply to every file
- Timestamps are UTC:
YYYY-MM-DD HH:MM:SS(2026-03-02 12:00:00) or ISO 8601 withZor an offset. A timestamp without a zone is taken as UTC. - Delivery periods are 15 minutes and start on a quarter hour (
:00,:15,:30,:45). - A delivery day is 00:00–23:45 UTC.
- Names (
request_id, dataset names, config names): lower-case letters, digits,.,_,-; arequest_idis 3–64 characters, a dataset or config name 1–64.
Uploads¶
pm_targets.jsonl — Position Manager targets¶
JSON Lines: one JSON object per line, one line per target revision. No other format is accepted (a JSON array, CSV or Parquet is refused, not converted).
| Field | Type | Required | Rule |
|---|---|---|---|
portfolio_id |
string | yes | the same value on every record of the file |
delivery_from_utc |
timestamp | yes | start of the 15-minute delivery period; quarter-hour aligned |
delivery_to_utc |
timestamp | yes | end of the period |
created_utc |
timestamp | yes | when this revision was issued; must be before delivery_from_utc |
target |
array of levels | yes | at least one level; see below |
da_position_delta |
array of objects | yes | the components of the position, see below |
| any other field | — | no | additional fields in Position Manager records are permitted and ignored by the backtest (for example strategy) |
Each element of target is a price–volume level:
| Field | Type | Rule |
|---|---|---|
quantity_mw |
number | signed: negative = sell, positive = buy; all levels of one record carry the same sign |
min_price_eur_per_mwh |
number | sell floor; for a sell level |min_price| ≤ 5000 (no "infinite" floors) |
max_price_eur_per_mwh |
number | buy ceiling; for a buy level |max_price| ≤ 5000 |
The levels of one record add up to the net target for the period. Level 0 is worked above its floor (below its ceiling); each further level is worked only at its own, worse, limit.
Each element of da_position_delta carries reference_time and the components forecast, schedule, availability (numbers, MW; a missing component counts as zero). The element with reference_time: "da" is used; if none has it, the first element is used. The position's tag is derived from it, once per delivery period, from the last revision of that period, and applies to every revision of it: the component with the largest absolute value decides — forecast → forecast_update, schedule → schedule, availability → availability_update; a tie is resolved in that order. Per-tag configuration parameters apply according to this tag.
Revisions: records with the same delivery_from_utc are one position; they are ordered by created_utc and replayed in that order. The last revision is the converged target. A period whose converged |Σ quantity_mw| is below 0.1 MW (the exchange minimum) is dropped as untradeable.
{"portfolio_id": "example_portfolio_nl", "delivery_from_utc": "2026-03-02 06:00:00", "delivery_to_utc": "2026-03-02 06:15:00", "created_utc": "2026-03-02 00:00:00", "target": [{"quantity_mw": -0.3, "min_price_eur_per_mwh": 20.0, "max_price_eur_per_mwh": 4000.0}], "da_position_delta": [{"reference_time": "da", "forecast": -0.3, "schedule": 0.0, "availability": 0.0}]}
{"portfolio_id": "example_portfolio_nl", "delivery_from_utc": "2026-03-02 06:00:00", "delivery_to_utc": "2026-03-02 06:15:00", "created_utc": "2026-03-02 04:00:00", "target": [{"quantity_mw": -0.6, "min_price_eur_per_mwh": 20.0, "max_price_eur_per_mwh": 4000.0}], "da_position_delta": [{"reference_time": "da", "forecast": -0.6, "schedule": 0.0, "availability": 0.0}]}
Two revisions of the 06:00 period: at 00:00 sell 0.3 MW, revised at 04:00 to sell 0.6 MW, floor €20/MWh, tagged forecast_update.
da_cleared.csv or .parquet — cleared day-ahead position¶
| Column | Type | Rule |
|---|---|---|
delivery_from_utc |
timestamp | one row per 15-minute period; complete grid from first to last row, no gaps, no duplicates |
cleared_mwh |
number | MWh cleared in the day-ahead auction for the period; negative = sold, positive = bought; no missing values |
delivery_from_utc,cleared_mwh
2026-03-02 06:00:00,-0.55
2026-03-02 06:15:00,-0.70
delivered.csv or .parquet — realised production¶
| Column | Type | Rule |
|---|---|---|
delivery_from_utc |
timestamp | same grid rules as above |
delivered_mwh |
number | metered MWh delivered in the period; positive = produced; no missing values |
Both volume files must cover every period the Position Manager file trades inside the requested run period. CSV: header row, comma-separated, . decimal separator, no thousands separators. Parquet: the same two columns.
config.yaml — run configuration¶
Only the parameters below may appear; any other key is refused. Every parameter is optional; an omitted one takes the policy version's default. Bounds are enforced on upload.
schema_version: "1" # required, exactly "1"
deadband_mw: 1.0 # number, 0–2
flush_minutes: 0 # number, 0–120; 0 = the deadband is never lifted
fee_eur_mwh: 0.10 # number, 0–1
tags: # per tag; tag names: forecast_update, schedule, availability_update, uncommitted_volume
schedule:
default_window_minutes: 1440 # number, 5–2880
urgency_schedule: [[360, 0.0], [120, 0.3], [30, 0.6], [5, 0.9]] # [[minutes_to_gate, urgency 0–1], …], minutes decreasing
pacing_curve: [[0.0, 0.0], [0.25, 0.5], [0.5, 0.75], [1.0, 1.0]] # [[elapsed 0–1, done 0–1], …] or null
hold_back_mw: 1.0 # number, 0–20 (policy v1.3.0 and later)
da_price_gate: # (policy v1.3.0 and later)
sell_only_below: -5 # number or null, −500–4000, EUR/MWh
buy_only_above: null # number or null, −500–4000, EUR/MWh
Parameters marked v1.3.0 are refused by earlier policy versions. helyx policies prints, per version, the exposed parameters and their defaults.
request.json — run request¶
Written by helyx request; shown here so that a request can also be produced by other tooling.
{
"schema_version": "0.2",
"request_id": "esg-2026-09-24-floor20",
"pm_targets": "improved_floor20",
"da_cleared": "actual_da",
"delivered": "realised",
"config": "gate5-holdback1",
"policy": "v1.3.0",
"start": "2026-03-01",
"end": "2026-05-31",
"notes": "optional, up to 2000 characters"
}
| Field | Rule |
|---|---|
schema_version |
exactly "0.2" |
request_id |
3–64 characters, ^[a-z0-9][a-z0-9._-]{2,63}$; names the run and its results folder |
pm_targets, da_cleared, delivered |
names of uploaded datasets; all three required |
config |
name of an uploaded configuration; omit for the policy defaults |
policy |
a published version, vMAJOR.MINOR.PATCH |
start, end |
YYYY-MM-DD, inclusive UTC delivery days; start ≤ end, at most 366 days, inside the published coverage and avoiding its gaps |
notes |
optional; not part of the run identity |
Results¶
economics_<YYYY-MM-DD>.csv — one file per delivery day¶
96 rows (one per 15-minute period of the UTC day), in the order of the columns below. Volumes in MW for the period unless the name says MWh; cash in EUR, received positive.
| Column | Unit | Meaning |
|---|---|---|
cet |
hh:mm | local clock label of the period start (display only) |
delivery_start_utc |
timestamp | period start, UTC |
dah_forecast_mw |
MW | cleared day-ahead sold volume, as a positive quantity |
actual_mwh |
MWh | realised production |
actual_mw |
MW | realised production |
delta_mw |
MW | realised minus day-ahead sold, before intraday: positive = long, negative = short |
dah_price |
EUR/MWh | day-ahead price |
imb_long_eur_mwh |
EUR/MWh | imbalance price, long leg |
imb_short_eur_mwh |
EUR/MWh | imbalance price, short leg |
imb_price_applied |
EUR/MWh | the leg applied to the final residual position |
id_sell_mw |
MW | intraday volume sold |
id_sell_vwap |
EUR/MWh | volume-weighted average sell price (0 when nothing sold) |
id_buy_mw |
MW | intraday volume bought |
id_buy_vwap |
EUR/MWh | volume-weighted average buy price (0 when nothing bought) |
net_id_mw |
MW | signed intraday volume: buy positive, sell negative |
A_total_eur |
EUR | day-ahead cash flow |
B_total_eur |
EUR | A + imbalance settlement without intraday trading |
C_total_eur |
EUR | A + intraday cash flows + imbalance settlement of the residual |
id_value_add_eur |
EUR | C − B |
delivery_date |
date | the UTC day of the file |
economics_monthly.csv — the run in daily rows¶
One row per delivery day, then one YYYY-MM TOTAL row per month, then one N-DAY TOTAL row for the run. Totals are sums of the daily rows; the VWAP columns are empty on total rows.
| Column | Unit | Meaning |
|---|---|---|
delivery_date |
date or TOTAL label | |
dah_mwh |
MWh | day-ahead sold volume |
actual_mwh |
MWh | realised production |
id_sell_mwh, id_buy_mwh |
MWh | intraday sold and bought |
id_sell_vwap, id_buy_vwap |
EUR/MWh | daily volume-weighted average prices |
A_total_eur, B_total_eur, C_total_eur, id_value_add_eur |
EUR | as above, summed over the day |
month |
YYYY-MM |
run_parameters.json — what ran¶
{
"request_id": "esg-2026-09-24-floor20",
"identity_sha256": "cedaf60ac38d00a1e31cd268a7e6e9c2f63378d49f80812939b23faf8ad8a96a",
"inputs": {
"pm_targets": {"sha256": "…", "name": "improved_floor20", "generation": 1790108301159686},
"da_cleared": {"sha256": "…", "name": "actual_da", "generation": 1790108303050979},
"delivered": {"sha256": "…", "name": "realised", "generation": 1790108305021316},
"config": {"sha256": "…", "name": "gate5-holdback1", "generation": 1790108306000000}
},
"parameters": {"deadband_mw": 1.0, "flush_minutes": 0, "fee_eur_mwh": 0.1,
"tags": {"schedule": {"default_window_minutes": 1440, "hold_back_mw": 1.0, "da_price_gate": {"sell_only_below": -5}}}},
"policy": "v1.3.0",
"market_corpus_revision": "mc-33406daa0d193927",
"period": {"start": "2026-03-01", "end": "2026-05-31"},
"frozen_at": "2026-09-24T20:07:37+00:00"
}
identity_sha256 identifies the experiment: two runs with the same value have byte-identical results. parameters is the fully resolved configuration, defaults included. generation is the stored version of each uploaded dataset that this run used.
status.json¶
| Field | Meaning |
|---|---|
state |
queued, deferred, rejected, running, done, failed |
reason |
for rejected and failed, why; for done, a one-line summary |
identity_sha256 |
as above, once accepted |
results_from |
set when an identical earlier run's results were reused |
submitted_at, accepted_at, started_at, finished_at, updated_at |
timestamps, UTC |
validation.json¶
The checks applied at acceptance: for each dataset and for the request, a list of {name, ok, detail} and a status of valid or rejected.