Struct SystemBuilder 

pub struct SystemBuilder { /* private fields */ }

Builder for constructing a validated, immutable System.

Accepts entity collections, sorts entities by ID, checks for duplicate IDs, builds topology, and returns the System. All entity collections default to empty; only supply the collections your test case requires.

Examples

use cobre_core::{Bus, DeficitSegment, EntityId, SystemBuilder};

let system = SystemBuilder::new()
    .buses(vec![
        Bus { id: EntityId(2), name: "B".to_string(), deficit_segments: vec![], excess_cost: 0.0 },
        Bus { id: EntityId(1), name: "A".to_string(), deficit_segments: vec![], excess_cost: 0.0 },
    ])
    .build()
    .expect("valid system");

// Canonical ordering: id=1 comes before id=2.
assert_eq!(system.buses()[0].id, EntityId(1));
assert_eq!(system.buses()[1].id, EntityId(2));

Implementations

impl SystemBuilder

pub fn new() -> Self

Create a new empty builder. All entity collections start empty.

New fields default to empty/default values so that pre-existing tests continue to work without modification.

pub fn buses(self, buses: Vec<Bus>) -> Self

Set the bus collection.

pub fn lines(self, lines: Vec<Line>) -> Self

Set the line collection.

pub fn hydros(self, hydros: Vec<Hydro>) -> Self

Set the hydro plant collection.

pub fn thermals(self, thermals: Vec<Thermal>) -> Self

Set the thermal plant collection.

pub fn pumping_stations(self, stations: Vec<PumpingStation>) -> Self

Set the pumping station collection.

pub fn contracts(self, contracts: Vec<EnergyContract>) -> Self

Set the energy contract collection.

pub fn non_controllable_sources( self, sources: Vec<NonControllableSource>, ) -> Self

Set the non-controllable source collection.

pub fn stages(self, stages: Vec<Stage>) -> Self

Set the stage collection (study and pre-study stages).

Stages are sorted by id in build to canonical order.

pub fn policy_graph(self, policy_graph: PolicyGraph) -> Self

Set the policy graph.

pub fn penalties(self, penalties: ResolvedPenalties) -> Self

Set the pre-resolved penalty table.

Populated by cobre-io after the three-tier penalty cascade is applied.

pub fn bounds(self, bounds: ResolvedBounds) -> Self

Set the pre-resolved bounds table.

Populated by cobre-io after base bounds are overlaid with stage overrides.

pub fn resolved_generic_bounds( self, resolved_generic_bounds: ResolvedGenericConstraintBounds, ) -> Self

Set the pre-resolved generic constraint RHS bound table.

Populated by cobre-io after converting raw parsed bound rows into the indexed lookup structure.

pub fn resolved_load_factors( self, resolved_load_factors: ResolvedLoadFactors, ) -> Self

Set the pre-resolved per-block load scaling factors.

Populated by cobre-io after resolving load_factors.json entries.

pub fn resolved_exchange_factors( self, resolved_exchange_factors: ResolvedExchangeFactors, ) -> Self

Set the pre-resolved per-block exchange capacity factors.

Populated by cobre-io after resolving exchange_factors.json entries.

pub fn resolved_ncs_bounds(self, resolved_ncs_bounds: ResolvedNcsBounds) -> Self

Set the pre-resolved per-stage NCS available generation bounds.

Populated by cobre-io after resolving ncs_bounds.parquet entries.

pub fn resolved_ncs_factors( self, resolved_ncs_factors: ResolvedNcsFactors, ) -> Self

Set the pre-resolved per-block NCS generation scaling factors.

Populated by cobre-io after resolving non_controllable_factors.json entries.

pub fn inflow_models(self, inflow_models: Vec<InflowModel>) -> Self

Set the PAR(p) inflow model collection.

pub fn load_models(self, load_models: Vec<LoadModel>) -> Self

Set the load model collection.

pub fn ncs_models(self, ncs_models: Vec<NcsModel>) -> Self

Set the NCS availability noise model collection.

pub fn correlation(self, correlation: CorrelationModel) -> Self

Set the correlation model.

pub fn initial_conditions(self, initial_conditions: InitialConditions) -> Self

Set the initial conditions.

pub fn generic_constraints( self, generic_constraints: Vec<GenericConstraint>, ) -> Self

Set the generic constraint collection.

Constraints are sorted by id in build to canonical order.

pub fn scenario_source(self, scenario_source: ScenarioSource) -> Self

Set the scenario source configuration.

pub fn build(self) -> Result<System, Vec<ValidationError>>

Build the System.

Sorts all entity collections by EntityId (canonical ordering). Checks for duplicate IDs within each collection. Validates all cross-reference fields (e.g., bus_id, downstream_id) against the appropriate index to ensure every referenced entity exists. Builds CascadeTopology and NetworkTopology. Validates the cascade graph for cycles and checks hydro filling configurations. Constructs lookup indices.

Returns Err with a list of all validation errors found across all collections. All invalid references across all entity types are collected before returning — no short-circuiting on first error.

Errors

Returns Err(Vec<ValidationError>) if:

• Duplicate IDs are detected in any entity collection.
• Any cross-reference field refers to an entity ID that does not exist.
• The hydro cascade graph contains a cycle.
• Any hydro filling configuration is invalid (non-positive inflow or missing entry_stage_id).

All errors across all collections are reported together.

Trait Implementations

impl Default for SystemBuilder

fn default() -> Self

Returns the “default value” for a type.