gtopt Input Data Structure Documentation

Directory Layout

case_name/
├── case_name.json            # Main configuration file
└── <input_directory>/        # External data files
    ├── Demand/
    │   └── lmax.parquet      # Demand load profile
    ├── Generator/
    │   └── pmax.parquet      # Generator capacity profile
    └── ...

Input settings

Model parameters

Note: annual_discount_rate has moved to the simulation section (see Section 2). For backward compatibility, it is still accepted here.

Output settings

Solver selection

Logging and debugging

Deprecated LP solver fields

These fields are still accepted for backward compatibility but are superseded by the solver_options sub-object (see Section 1.1).

Example

{
  "options": {
    "output_format": "csv",
    "use_single_bus": false,
    "demand_fail_cost": 1000,
    "scale_objective": 1000,
    "use_kirchhoff": true,
    "input_directory": "system_c0",
    "input_format": "parquet",
    "method": "monolithic",
    "solver_options": {
      "algorithm": 3,
      "presolve": true
    }
  }
}

1.1 SolverOptions

LP solver configuration exposed as a sub-object under options. Individual top-level fields (lp_algorithm, lp_threads, lp_presolve) are still respected for backward compatibility and take precedence over the corresponding solver_options sub-fields.

Example:

{
  "options": {
    "solver_options": {
      "algorithm": 3,
      "threads": 4,
      "presolve": true,
      "optimal_eps": 1e-8,
      "feasible_eps": 1e-8,
      "log_level": 1
    }
  }
}

1.2 VariableScale

Per-class or per-element LP variable scaling factors. Convention: physical_value = LP_value * scale. Defined as an array under options.variable_scales.

Resolution priority when the solver looks up a scale:

1. Per-element entry matching (class_name, variable, uid)
2. Per-class entry matching (class_name, variable) with uid = -1
3. Fallback: 1.0 (no scaling)

Note: Per-element fields (Battery::energy_scale, Reservoir::energy_scale) and global options (scale_theta) take precedence over entries in variable_scales.

Example:

{
  "options": {
    "variable_scales": [
      {"class_name": "Bus", "variable": "theta",
       "uid": -1, "scale": 0.001},
      {"class_name": "Reservoir", "variable": "volume",
       "uid": -1, "scale": 1000.0},
      {"class_name": "Battery", "variable": "energy",
       "uid": 1, "scale": 10.0}
    ]
  }
}

1.3 SDDPOptions

SDDP-specific solver configuration, specified as a sub-object under options.sddp_options. Field names omit the sddp_ prefix since the section name already provides the namespace. All fields are optional.

For full algorithmic details, see SDDP Solver.

1.4 CascadeOptions (multi-level hybrid solver)

These options configure the cascade solver (method = "cascade"), which runs a multi-level hybrid algorithm with progressive LP refinement. They are set in their own cascade_options sub-object (not inside sddp_options). See Cascade Method for full documentation, and SDDP Solver – S10 for a summary.

The cascade_options object contains three top-level fields:

Each element in the level_array is an object with the following optional fields:

**model_options fields** (same structure at both cascade and level scope):

Note: annual_discount_rate has moved to the simulation section. For backward compatibility, it is still accepted in model_options.

**sddp_options fields** (per-level solver parameters):

**transition fields:**

See CASCADE_SOLVER.md §4.5 for detailed cut forgetting semantics and the two-phase solve behavior.

SDDP example:

{
  "options": {
    "method": "sddp",
    "sddp_options": {
      "max_iterations": 200,
      "convergence_tol": 1e-5,
      "stationary_tol": 0.01,
      "stationary_window": 10,
      "cut_sharing_mode": "expected",
      "cut_directory": "cuts",
      "elastic_mode": "single_cut",
      "elastic_penalty": 1e7,
      "cut_recovery_mode": "keep",
      "boundary_cuts_mode": "separated",
      "apertures": []
    }
  }
}

Cascade example:

{
  "options": {
    "method": "cascade",
    "sddp_options": {
      "max_iterations": 30,
      "convergence_tol": 0.01
    },
    "cascade_options": {
      "level_array": [
        {
          "name": "uninodal_benders",
          "model_options": {
            "use_single_bus": true,
            "use_kirchhoff": false,
            "use_line_losses": false
          },
          "sddp_options": {
            "max_iterations": 10,
            "apertures": [],
            "convergence_tol": 0.05
          }
        },
        {
          "name": "transport_sddp",
          "model_options": {
            "use_single_bus": false,
            "use_kirchhoff": false
          },
          "sddp_options": {
            "max_iterations": 15,
            "apertures": [1, 2, 3]
          },
          "transition": {
            "inherit_targets": true,
            "target_rtol": 0.05,
            "target_min_atol": 1.0,
            "target_penalty": 500
          }
        },
        {
          "name": "full_sddp",
          "model_options": {
            "use_kirchhoff": true,
            "use_line_losses": true
          },
          "sddp_options": {
            "max_iterations": 30,
            "apertures": [1, 2, 3]
          },
          "transition": {
            "inherit_optimality_cuts": true,
            "inherit_feasibility_cuts": true,
            "optimality_dual_threshold": 1e-6
          }
        }
      ]
    }
  }
}

Simulation mode example:

{
  "options": {
    "method": "sddp",
    "sddp_options": {
      "simulation_mode": true,
      "cut_recovery_mode": "keep",
      "cut_directory": "cuts"
    }
  }
}

1.5 MonolithicOptions

Monolithic-solver-specific configuration, specified as a sub-object under options.monolithic_options. All fields are optional.

For full details, see Monolithic Solver.

Note: boundary_cuts_file has moved to the simulation section. For backward compatibility, it is still accepted in monolithic_options.

Example:

{
  "options": {
    "method": "monolithic",
    "monolithic_options": {
      "solve_mode": "monolithic",
      "boundary_cuts_mode": "separated"
    }
  },
  "simulation": {
    "boundary_cuts_file": "boundary_cuts.csv"
  }
}

Simulation-level fields

In addition to the arrays below, the simulation object accepts these scalar fields:

Backward compatibility: annual_discount_rate is also accepted in options or options.model_options. boundary_cuts_file is also accepted in options.sddp_options or options.monolithic_options. The simulation location is preferred.

When phase_array or scene_array are empty, a single default Phase / Scene covering all stages / scenarios is created automatically.

2.1 Block

A block is the smallest indivisible time unit. energy [MWh] = power [MW] × duration [h].

2.2 Stage

A stage groups consecutive blocks into a planning/investment period.

2.3 Scenario

A scenario represents a possible future realization (hydrology, demand level, etc.).

2.4 Phase

A phase groups consecutive planning stages into a higher-level period. This allows modelling distinct investment or operational windows (e.g. a 5-year construction phase followed by a 20-year operational phase). When only one phase is needed (the common case), it is created automatically with defaults covering all stages.

2.5 Scene

A scene groups consecutive scenarios into a logical set. Scenes are used by the solver to partition scenarios when building LP sub-problems (one LP per scene/phase combination). When no scene_array is provided, a single default scene covering all scenarios is created.

2.6 Aperture

An aperture represents one hydrological (or stochastic) realization used in the SDDP backward pass. Each aperture references a source scenario whose affluent data (flow bounds) are applied to the cloned phase LP before solving. Apertures allow the backward pass to sample a different set of scenarios than the forward pass.

When no aperture_array is provided, the SDDP solver falls back to the legacy behaviour controlled by sddp_num_apertures (first N scenarios or all scenarios).

Note: When aperture_directory is set in sddp_options, the source scenario is first looked up in that directory; if not found there, it falls back to the regular input_directory.

Example

{
  "simulation": {
    "block_array": [
      {"uid": 1, "duration": 1},
      {"uid": 2, "duration": 2}
    ],
    "stage_array": [
      {"uid": 1, "first_block": 0, "count_block": 1, "active": 1},
      {"uid": 2, "first_block": 1, "count_block": 1, "active": 1}
    ],
    "scenario_array": [
      {"uid": 1, "probability_factor": 1}
    ],
    "phase_array": [
      {"uid": 1, "first_stage": 0, "count_stage": 2}
    ],
    "scene_array": [
      {"uid": 1, "first_scenario": 0, "count_scenario": 1}
    ],
    "aperture_array": [
      {"uid": 1, "source_scenario": 1, "probability_factor": 0.5},
      {"uid": 2, "source_scenario": 2, "probability_factor": 0.5}
    ]
  }
}

3.1 Bus

An electrical bus (node) in the network.

3.2 Generator

A generation unit connected to a bus.

Note: Fields that accept number|array|string can be a numeric constant, an inline array (indexed by [stage][block]), or a filename referencing an external Parquet/CSV file in input_directory/Generator/.

3.3 Demand

An electrical demand (load) connected to a bus.

3.4 Line

A transmission line connecting two buses.

3.5 Battery

A battery energy storage system (BESS).

{
  "uid": 1, "name": "bess1",
  "bus": 3,
  "input_efficiency": 0.95, "output_efficiency": 0.95,
  "emin": 0, "emax": 200,
  "pmax_charge": 60, "pmax_discharge": 60,
  "gcost": 0,
  "capacity": 200
}

{
  "uid": 1, "name": "bess1",
  "bus": 3,
  "source_generator": "solar1",
  "input_efficiency": 0.95, "output_efficiency": 0.95,
  "emin": 0, "emax": 200,
  "pmax_charge": 60, "pmax_discharge": 60,
  "gcost": 0,
  "capacity": 200
}

3.6 Converter

Links a battery to a discharge generator and a charge demand.

3.7 Junction

A hydraulic node in the water network.

3.8 Waterway

A water channel connecting two junctions.

3.9 Reservoir

A water reservoir connected to a junction. Volume units: hm³ (1 hm³ = 10⁶ m³).

3.10 Turbine

A hydro turbine linking a waterway to a generator.

3.11 Flow (Inflow)

A water inflow or outflow at a junction.

3.12 Reservoir Seepage (formerly Filtration)

Piecewise-linear seepage model from a waterway to an adjacent reservoir, representing water losses due to soil permeability (Darcy's law approximation). The seepage flow through the waterway is constrained to:

seepage [m³/s] = slope [m³/s/hm³] × avg_reservoir_volume [hm³] + constant [m³/s]

where avg_reservoir_volume = (eini + efin) / 2. This captures the hydrostatic-head dependence of seepage. Corresponds to PLP plpfilemb.dat.

When piecewise-linear segments are provided, the active segment is selected based on the reservoir's current volume (vini from the previous phase). The LP constraint coefficients (slope and RHS) are updated dynamically — the same mechanism used by Reservoir Production Factor for turbine conversion rates. If segments is empty, the static slope and constant fields are used as a simple linear model.

JSON array name: reservoir_seepage_array

Each segment in the segments array describes one piece of the concave filtration envelope:

The seepage rate at volume V is computed as the minimum over all segments: seepage(V) = min_i { constant_i + slope_i × (V − volume_i) }. This is analogous to the piecewise-linear evaluation used in Reservoir Production Factor.

Example with segments:

{
  "uid": 1,
  "name": "filt1",
  "waterway": "w1_2",
  "reservoir": "r1",
  "slope": 0.001,
  "constant": 1.0,
  "segments": [
    { "volume": 0.0, "slope": 0.0003, "constant": 0.5 },
    { "volume": 5000.0, "slope": 0.0001, "constant": 2.0 }
  ]
}

3.13 Reservoir Production Factor

Piecewise-linear turbine efficiency as a function of reservoir volume (hydraulic head). Models the PLP "rendimiento" concept: the turbine conversion rate varies with the current water level in the reservoir. Corresponds to PLP plpcenre.dat (Archivo de Rendimiento de Embalses).

When the SDDP solver runs, it updates the turbine's conversion-rate LP coefficient at each forward-pass iteration using the current reservoir volume. For the first iteration, the reservoir's eini value is used. If the LP solver does not support in-place coefficient modification (supports_set_coeff()), the static conversion_rate from the Turbine element is used unchanged.

JSON array name: reservoir_production_factor_array

Each segment in the segments array has the following fields:

The efficiency is computed as the minimum over all segments:

efficiency(V) = min_i { constant_i + slope_i × (V − volume_i) }

Segments should have slopes in decreasing order so the function forms a concave envelope. The result is clamped to zero (efficiency cannot be negative).

Example:

{
  "reservoir_production_factor_array": [
    {
      "uid": 1,
      "name": "eff_colbun",
      "turbine": "COLBUN",
      "reservoir": "COLBUN",
      "mean_efficiency": 1.53,
      "segments": [
        { "volume": 0.0, "slope": 0.0002294, "constant": 1.2558 },
        { "volume": 500.0, "slope": 0.0001, "constant": 1.53 }
      ]
    }
  ]
}

3.14 Reservoir Discharge Limit

Piecewise-linear volume-dependent discharge limit for reservoirs. This is a safety/environmental constraint that limits the hourly-average discharge as a function of the reservoir volume (e.g. to prevent landslides or excessive drawdown).

The constraint per stage is:

qeh ≤ slope × V_avg + constant

where qeh is the stage-average hourly discharge [m³/s], V_avg is the average reservoir volume (eini + efin) / 2 [hm³], and slope/constant are from the active piecewise-linear segment.

Generalizes the PLP "Ralco" constraint (plpralco.dat).

JSON array name: reservoir_discharge_limit_array

Each segment has:

3.15 Generator Profile

A time-varying capacity-factor profile for a generator.

3.16 Demand Profile

A time-varying load-shape profile for a demand element.

3.17 Reserve Zone

A spinning-reserve requirement zone.

3.18 Reserve Provision

A generator's contribution to reserve zones.

3.19 User Constraint

User-defined linear constraints applied to the LP formulation. See User Constraints for the full syntax reference and examples.

System-level fields:

File Format

External data files (CSV or Parquet) follow a tabular format with columns:

Example CSV

"scenario","stage","block","uid:1"
1,1,1,10
1,2,2,15
1,3,3,8