Skip to content

Initial Condition Files

This page documents initial_conditions.json, which holds the reservoir storage and the pre-study records at the start of a study. The File summary maps every case file to its page, and Conventions states the rules shared by all of them.


Methodology: State Augmentation · System Element Modeling Overview

Initial reservoir storage, pre-study releases already in transit on declared travel-time arcs, and recent observations at the start of the study.

NameTypeRequiredDefaultUnitsDescription
storagearrayYes——Array of { "hydro_id": integer, "value_hm3": number } entries for hydros without a filling configuration
filling_storagearrayYes——Array of { "hydro_id": integer, "value_hm3": number } entries for hydros with a filling configuration
past_defluencesarrayNo——Array of windowed pre-study release records seeding the in-transit buckets of a declared travel-time arc (see below)
recent_observationsarrayNo——Array of observed inflow entries for mid-season study starts (see below)
past_anticipated_commitmentsarrayNo——Array of windowed committed-MW records for anticipated thermals — the plant’s pre-study decisions, whether they deliver in-study or past the horizon (see below)

storage[] and filling_storage[] entry fields:

NameTypeRequiredDefaultUnitsDescription
storage[].hydro_idintegerYes——Identifier of a hydro without a filling configuration; unique within storage and absent from filling_storage
storage[].value_hm3numberYes—hm³Initial reservoir volume; >= 0 and inside the hydro’s [min_storage_hm3, max_storage_hm3]
filling_storage[].hydro_idintegerYes——Identifier of a hydro with a filling configuration; unique within filling_storage and absent from storage
filling_storage[].value_hm3numberYes—hm³Initial reservoir volume; in [0, min_storage_hm3), and 0 when filling.start_stage_id is greater than 0

Storage validation. The array a hydro’s entry belongs to follows from its system/hydros.json record: a hydro with a filling configuration listed under storage, or one without listed under filling_storage, is refused at load. A storage value outside the hydro’s own storage range [min_storage_hm3, max_storage_hm3] is refused at load too, within a relative tolerance of 1e-9, including for a hydro that enters service later in the study. The value is the storage at the start of the first stage and is used as declared: the stage min_storage_hm3 and max_storage_hm3 of constraints/hydro_bounds.parquet bound the storage at the end of their stage, not the initial storage. When the value lies outside those end-of-stage bounds at the hydro’s first operating stage, validation warns and names the stage, because that stage must reach the bound from its own inflow or release the excess. A hydro dormant at the start of the study keeps this storage at every stage before it enters service or starts filling (System Element Modeling Overview). A hydro listed in neither array starts at its min_storage_hm3, or at 0 when it has a filling configuration or is out of service at the first study stage, and an entry whose hydro_id names no hydro is ignored; neither draws a diagnostic. The filling_storage rules are listed under Validation on Hydro Plant Files.

The PAR lag chain and the mid-period accumulator are seeded from scenarios/inflow_history.parquet’s windowed record, shadowed day-wise by recent_observations wherever the two overlap.

past_defluences supplies the pre-study releases already in transit on a declared travel-time arc (hydros[].travel_time_hours), so the first stages’ delayed-arrival buckets are seeded rather than empty. Each entry gives a release window and its average rate for an upstream plant whose outflow feeds a downstream arc:

NameTypeRequiredDefaultUnitsDescription
past_defluences[].hydro_idintegerYes——Upstream plant whose release feeds the arc
past_defluences[].start_datestringYes——Start of the release window (inclusive), ISO 8601 YYYY-MM-DD
past_defluences[].end_datestringYes——End of the release window (exclusive), ISO 8601 YYYY-MM-DD; must be after start_date
past_defluences[].value_m3snumberYes—m³/sAverage release rate over the window in m³/s; finite and non-negative

The windows must cover the arc’s in-transit span at study start — [start_0 − travel_time, start_0) — with no gap and none future-dated past the study start; otherwise the study is rejected. There is no fallback for incomplete coverage. Optional; defaults to an empty array when no arc needs seeding.

recent_observations provides observed inflow data for partial periods before the study start. Used to seed the lag accumulator when a study begins mid-season (e.g., a coupled study starting on January 5 needs observed inflow for January 1—4). Each entry has:

NameTypeRequiredDefaultUnitsDescription
recent_observations[].hydro_idintegerYes——Hydro plant identifier
recent_observations[].start_datestringYes——Start of the observation period (inclusive), ISO 8601 YYYY-MM-DD
recent_observations[].end_datestringYes——End of the observation period (exclusive), ISO 8601 YYYY-MM-DD
recent_observations[].value_m3snumberYes—m³/sAverage inflow observed during the period, in m³/s

Date ranges for the same hydro must not overlap; adjacent ranges (start_date == previous end_date) are accepted. Values must be finite; a negative value is accepted — the quantity is incremental inflow (a plant’s natural flow minus its upstream plants’), so a negative window is real hydrology, and the configured inflow non-negativity method decides how the water balance treats it. Semantic validation reports one warning per file naming the negative count and the most-negative value’s hydro, so a genuinely sign-flipped series still stands out. Optional; defaults to an empty array when absent.

past_anticipated_commitments supplies the externally-decided committed MW rate for an anticipated thermal plant — every delivery the plant decided before the study begins, whether that delivery matures inside the horizon (seeding its ring slot at the first stage) or past it (a commitment decided before the study and delivered past the horizon; for the equivalent term in other planning tools, see the Glossary). Each entry is a dated window carrying a constant rate:

NameTypeRequiredDefaultUnitsDescription
past_anticipated_commitments[].thermal_idintegerYes——Anticipated thermal plant identifier; must reference a thermal declaring anticipated_config
past_anticipated_commitments[].start_datestringYes——Start of the commitment window (inclusive), ISO 8601 YYYY-MM-DD
past_anticipated_commitments[].end_datestringYes——End of the commitment window (exclusive), ISO 8601 YYYY-MM-DD; must be after start_date
past_anticipated_commitments[].value_mwnumberYes—MWCommitted MW rate held constant over the window; finite

A plant’s windows must tile every delivery stage the plant decided before the study, exactly — coverage 1.0, no gap, no overlap. Those stages may fall on either side of the horizon: the leading in-study delivery stages, and any post-horizon stages of a delivery decided before the study. A window may never cover a stage the study itself decides, and a single window may not straddle the horizon end — split it into an in-study window ending at the horizon and a post-study window starting there. A stretch with no scheduled commitment still needs an explicit 0.0-rate window rather than a gap left to be inferred. An in-study window’s value_mw is checked against the resolved generation bounds of every covered stage at which the plant is in service, and a purely post-horizon window’s against the plant’s static [min_generation_mw, max_generation_mw]; a non-zero window may not cover a stage outside the plant’s commissioning window, when it declares one. The values are sunk cost: their fuel never enters the study objective. With a boundary loaded, a post-horizon window’s state contribution is folded once, at load, into every boundary cut’s intercept, and the window is echoed at its real delivery date in anticipated/fixed_deliveries.parquet. Optional; defaults to an empty array when no anticipated thermals are present.

See System Element Modeling Overview §4 for the delivery-stage mechanics the windows tile against.

{
"past_anticipated_commitments": [
{
"thermal_id": 2,
"start_date": "2026-01-01",
"end_date": "2026-02-01",
"value_mw": 0.0
}
]
}

Example:

{
"storage": [{ "hydro_id": 0, "value_hm3": 15000.0 }],
"filling_storage": [],
"recent_observations": [
{
"hydro_id": 0,
"start_date": "2026-04-01",
"end_date": "2026-04-04",
"value_m3s": 500.0
},
{
"hydro_id": 0,
"start_date": "2026-04-04",
"end_date": "2026-04-11",
"value_m3s": 480.0
}
]
}