Planning Options Reference

Option Class Hierarchy

MainOptions                    (CLI-only, not in JSON)
  |
  +-- PlanningOptions          (JSON key: "options")
        |
        +-- ModelOptions           (JSON key: "model_options")
        +-- MonolithicOptions      (JSON key: "monolithic_options")
        |     +-- SolverOptions        (JSON key: "solver_options")
        +-- SddpOptions            (JSON key: "sddp_options")
        |     +-- SolverOptions        (JSON key: "forward_solver_options")
        |     +-- SolverOptions        (JSON key: "backward_solver_options")
        +-- CascadeOptions         (JSON key: "cascade_options")
        +-- SolverOptions          (JSON key: "solver_options")
        +-- LpBuildOptions         (JSON key: "lp_build_options")
        +-- VariableScale[]        (JSON key: "variable_scales")

C++ headers:

Backward-compatibility aliases: Options = PlanningOptions, OptionsLP = PlanningOptionsLP. The JSON key "options" is unchanged.

PlanningOptions Fields

All fields are std::optional – absent fields inherit built-in defaults (see PlanningOptionsLP for resolved values).

ModelOptions Fields

The model_options sub-object is the canonical location for LP-construction parameters. It enables per-level overrides in cascade solver configurations.

SolverOptions Fields

The solver_options sub-object (also embedded in monolithic_options, sddp_options.forward_solver_options, and sddp_options.backward_solver_options) configures the LP backend.

MonolithicOptions Fields

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

LpBuildOptions Fields

SddpOptions Fields

See SDDP Method for full documentation with examples.

Solver Options Precedence

Each planning method can specify per-pass solver options that override the global solver_options. The merge chain (highest priority first):

For each field in SolverOptions, the per-pass value is used if set; otherwise the global solver_options value applies.

{
  "options": {
    "solver_options": {
      "algorithm": 3,
      "threads": 4,
      "optimal_eps": 1e-8
    },
    "sddp_options": {
      "forward_solver_options": {
        "algorithm": 1
      },
      "backward_solver_options": {
        "threads": 1
      }
    }
  }
}

Variable Scales Precedence

Variable scaling factors are resolved in this order (highest priority first):

1. Per-element fields (e.g., Battery::energy_scale, Reservoir::energy_scale)
2. Global options (scale_theta for bus voltage angles)
3. variable_scales entries matching by (class_name, variable, uid)
4. variable_scales entries matching by (class_name, variable, uid=-1) (wildcard)
5. Default scale = 1.0

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

Merge Semantics

When multiple JSON files are passed to gtopt, their "options" sections are merged left to right. For each field:

• Scalars: the first file's value wins (later files fill in missing fields)
• Sub-objects: merged recursively (same rule per field)
• **variable_scales**: appended (later files add entries, earlier entries take precedence for the same key)

MainOptions (CLI-only)

MainOptions is used only by the standalone binary and is not part of the JSON interface. It carries all CLI-parsed values plus the list of planning files.

**--set key=value**: all other options are now set via --set. Examples: --set use_single_bus=true, --set output_directory=results/, --set solver_options.algorithm=barrier, --set sddp_options.max_iterations=300.

Deprecated aliases (still work, emit a warning): -b, -k, -D, -F, -d, -f, -C, --algorithm, --threads, --sddp-max-iterations, --sddp-min-iterations, --sddp-convergence-tol, --lp-debug, --log-directory, --cut-directory, --lp-compression, --lp-coeff-ratio.

Full JSON Example

{
  "options": {
    "input_directory": "system_data",
    "input_format": "parquet",
    "output_directory": "output",
    "output_format": "parquet",
    "output_compression": "zstd",
    "method": "sddp",
    "lp_debug": false,
    "model_options": {
      "demand_fail_cost": 1000,
      "use_kirchhoff": true,
      "use_single_bus": false,
      "use_line_losses": true,
      "scale_objective": 1000
    },
    "solver_options": {
      "algorithm": 3,
      "threads": 4,
      "optimal_eps": 1e-8,
      "feasible_eps": 1e-8
    },
    "sddp_options": {
      "max_iterations": 200,
      "convergence_tol": 1e-4,
      "forward_solver_options": {
        "algorithm": 1
      }
    },
    "lp_build_options": {
      "names_level": "only_cols"
    },
    "variable_scales": [
      {"class_name": "Reservoir", "variable": "energy", "uid": -1, "scale": 1000.0}
    ]
  },
  "simulation": {
    "annual_discount_rate": 0.1,
    "boundary_cuts_file": "boundary_cuts.csv",
    "boundary_cuts_valuation": "end_of_horizon"
  }
}

See Also

• Usage Guide – CLI reference and examples
• Planning Guide – Step-by-step planning guide
• SDDP Method – SDDP solver configuration
• Cascade Method – Cascade solver configuration
• Monolithic Method – Monolithic solver configuration