Struct StudySetup 

pub struct StudySetup {
    pub stage_data: StageData,
    pub stochastic: StochasticContext,
    pub fcf: FutureCostFunction,
    pub hydro_models: PrepareHydroModelsResult,
    pub scenario_libraries: ScenarioLibraries,
    pub loop_params: LoopParams,
    pub simulation_config: SimulationConfig,
    pub policy_path: String,
    /* private fields */
}

All precomputed study state built once before training and simulation.

Constructed by StudySetup::new from a validated System and cobre_io::Config. Owns all data so it can be held across async boundaries (e.g., Python GIL release) without lifetime issues.

Callers build TrainingContext and StageContext by borrowing from StudySetup.

Fields

stage_data: StageData

Stage-indexed data: LP templates, indexer, stages, entity counts, blocks, lag transitions, noise groups, and scaling report.

stochastic: StochasticContext

Stochastic context holding sampling distributions, libraries, and provenance.

fcf: FutureCostFunction

Future cost function (cut pool) updated by the backward pass during training.

hydro_models: PrepareHydroModelsResult

Pre-computed hydro production models (FPHA, turbine curves, etc.).

scenario_libraries: ScenarioLibraries

Sampling schemes and pre-built libraries for training and simulation phases.

Replaces the 14 flat inflow_scheme / sim_inflow_scheme / … fields. Access via scenario_libraries.training.<field> or scenario_libraries.simulation.<field>.

loop_params: LoopParams

Iteration-loop parameters projected from crate::config::LoopConfig.

Holds the five pure-data fields of crate::config::LoopConfig that are stable across training invocations. n_fwd_threads is excluded (derived at runtime) and supplied as a per-call argument to StudySetup::train.

simulation_config: SimulationConfig

Simulation pipeline parameters, stored directly as crate::simulation::SimulationConfig.

policy_path: String

Relative path to the policy output directory (e.g. "training/policy").

Implementations

impl StudySetup

pub fn replace_fcf(&mut self, fcf: FutureCostFunction)

Replace the FCF with a pre-loaded policy.

pub fn set_start_iteration(&mut self, iteration: u64)

Set the starting iteration for resumed training.

pub fn set_warm_start_basis_cache(&mut self, cache: Vec<Option<CapturedBasis>>)

Seed the per-stage warm-start basis cache for warm-start / resume training.

cache carries one entry per stage (as built by build_basis_cache_from_checkpoint from the checkpoint’s stored solver bases). StudySetup::train takes this out of self and replicates each stage’s basis across every forward-pass worker so iteration 1’s cut-loaded LPs warm-start.

Leave unset (the default None) for a fresh start.

pub fn set_export_states(&mut self, export: bool)

Enable state archiving for export.

pub fn set_budget(&mut self, budget: Option<u32>)

Set the active-cut budget cap per stage.

pub fn energy_conversion(&self) -> &EnergyConversionSet

Return the pre-computed EnergyConversionSet for this study.

Provides ρ_eq, V_ref, Q_ref, and ρ_acum (accumulated cascade productivity) for every (hydro, stage) pair. Consumed by the energy-balance LP constraints and inflow-energy / stored-energy extraction.

pub fn simulation_config(&self) -> &SimulationConfig

Return a reference to the simulation configuration.

pub fn stage_indexer(&self) -> &StageIndexer

Return a reference to the per-stage LP column/row indexer.

Provides LP layout constants — column and row ranges for every entity class (storage, thermal, anticipated state, etc.) — so that callers can locate specific primal or state-vector entries without hard-coding offsets.

The same indexer applies to every stage (the layout is uniform across stages in a study).

pub fn num_stages(&self) -> usize

Number of stages in the planning horizon.

Used by the CLI summary to express the pool-level active-row total on a per-stage basis, so it is directly comparable to the per-solve rows-in-LP metric reported for Dynamic Cut Selection.

pub fn stage_ctx(&self) -> StageContext<'_>

Construct a StageContext borrowing from this setup.

impl StudySetup

pub fn train<S, C: Communicator>( &mut self, solver: &mut S, comm: &C, n_threads: usize, solver_factory: impl Fn() -> Result<S, SolverError>, event_sender: Option<Sender<TrainingEvent>>, shutdown_flag: Option<&Arc<AtomicBool>>, ) -> Result<TrainingOutcome, SddpError>

where S: SolverInterface<Profile = ActiveProfile> + Send,

Execute the training loop.

Constructs TrainingConfig and TrainingContext, then delegates to crate::train. Mutates self.fcf to store generated cuts.

Errors

Returns SddpError::Infeasible, SddpError::Solver, or SddpError::Communication on LP, solver, or MPI failure.

pub fn simulate<S, C: Communicator>( &self, workspaces: &mut [SolverWorkspace<S>], comm: &C, result_tx: &SyncSender<SimulationScenarioResult>, event_sender: Option<Sender<TrainingEvent>>, baked_templates: Option<&[StageTemplate]>, stage_bases: &[Option<CapturedBasis>], ) -> Result<SimulationRunResult, SimulationError>

where S: SolverInterface<Profile = ActiveProfile> + Send,

Run simulation using the trained future cost function.

The caller provides channels, event sender, and thread management. baked_templates enables the baked-template LP load path (no add_rows per stage); pass None for the legacy load_model + add_rows fallback. stage_bases enables warm-start; pass &[] for cold-start.

Errors

Returns SimulationError on LP infeasibility, solver failure, channel closure, or if baked_templates.len() != num_stages.

pub fn build_training_output( &self, result: &TrainingResult, events: &[TrainingEvent], ) -> TrainingOutput

Convert TrainingResult and events into training output.

Delegates to crate::build_training_output with cut statistics from self.fcf.

pub fn create_workspace_pool<S: SolverInterface + Send, C: Communicator>( &self, comm: &C, n_threads: usize, solver_factory: impl Fn() -> Result<S, SolverError>, ) -> Result<WorkspacePool<S>, SolverError>

Create a WorkspacePool sized for this study.

Pool size equals n_threads. Each workspace gets a fresh solver instance. comm is used to read the MPI rank that is stamped into each workspace’s rank field for downstream per-worker observability.

Errors

Returns SolverError if solver creation fails.

Panics

Panics if comm.rank() > i32::MAX. MPI world sizes are bounded well below this on all real systems.

impl StudySetup

pub fn new( system: &System, config: &Config, stochastic: StochasticContext, hydro_models: PrepareHydroModelsResult, ) -> Result<Self, SddpError>

Build all precomputed study state from a validated system and config.

The constructor performs:

1. Config field extraction (seed, forward passes, stopping rules, etc.)
2. Delegates to StudySetup::from_broadcast_params with the extracted values.

Errors

• SddpError::Validation — if build_stage_templates succeeds but the template list is empty (“system has no study stages”).
• SddpError::Solver — propagated from build_stage_templates on LP construction failure.
• SddpError::Validation — if parse_cut_selection_config returns an invalid config string.

pub fn from_broadcast_params( system: &System, stochastic: StochasticContext, config: ConstructionConfig, hydro_models: PrepareHydroModelsResult, training_source: &ScenarioSource, simulation_source: &ScenarioSource, ) -> Result<Self, SddpError>

Build all precomputed study state from pre-resolved broadcast parameters.

This constructor accepts the scalar fields already extracted from either a cobre_io::Config (on rank 0) or a broadcast config struct (on non-root ranks). It performs the expensive computation steps that cannot be serialised:

1. build_stage_templates — constructs LP skeletons for each stage
2. StageIndexer::with_equipment — computes LP column/row offsets
3. build_initial_state — extracts initial storage and past inflows from system IC
4. max_iterations_from_rules — sizes the FCF cut pool
5. FutureCostFunction::new — pre-allocates cut storage
6. HorizonMode::Finite — wraps stage count
7. Risk measures from stage configs
8. build_entity_counts — entity ID and productivity vectors
9. Block layout derivation (block_counts_per_stage, max_blocks)

Errors

• SddpError::Validation — if build_stage_templates succeeds but the template list is empty (“system has no study stages”).
• SddpError::Solver — propagated from build_stage_templates on LP construction failure.

Trait Implementations

impl Debug for StudySetup

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.