SDOM

User Guide

  • Introduction to SDOM
    • Overview
    • How SDOM Works
      • Input Data
      • Outputs
    • Simplified Mathematical Formulation
    • Model Components
    • Key Features
      • Temporal Resolution
      • Storage Representation
      • Spatial Resolution
      • Flexibility
    • Computational Considerations
    • Next Steps
  • SDOM Input Data
    • Input Data Structure
    • Zonal Mode Inputs
    • Required Files
      • 1. Formulations Configuration
      • 2. Load Data
      • 3. VRE (Variable Renewable Energy) Data
      • 4. Fixed Generation Sources
      • 5. Storage Technology Data
      • 6. Thermal Generation Data
      • 7. System Scalars
      • 8. Import/Export Data (Optional)
    • Data Validation
    • Example Data Loading
    • Tips for Data Preparation
    • Next Steps
  • Zonal Inputs
    • Zonal Conventions
    • Network Selector
      • formulations.csv
    • New Zonal Files
      • areas.csv
      • interconnections.csv
      • LineCap_FT.csv
      • LineCap_TF.csv
    • Modified Existing Files in Zonal Mode
      • Row-oriented files with area column
      • Wide files with tagged headers
      • Capacity-factor files
    • CopperPlate Aggregation Fallback
    • Validation Summary
  • Running SDOM and Understanding Outputs
    • Running an Optimization
      • Basic Workflow
      • Shorter Time Horizons
    • Solver Configuration
      • CBC Solver (Open-Source)
      • HiGHS Solver (Open-Source)
      • Xpress Solver (Commercial)
      • Solver Option Reference
    • Outputs/Results
    • Zonal Results Access
    • Troubleshooting
      • Solver Performance
      • Infeasible Solutions
    • Visualising Results
      • Generated figures
      • Basic usage
      • Controlling the output directory
      • Full workflow example
    • Running Parametric & Sensitivity Studies
    • Next Steps
  • Zonal Model Guide
    • When to Use Zonal Mode
    • Minimal Setup
    • Run Example
    • Pyomo Object Access
    • Results and Outputs
    • Known Limits (Current Scope)
  • Parametric & Sensitivity Analysis
    • When to use parametric analysis
    • Quick-start example
    • Sample results of this example
      • Cross-case sensitivity plots
      • Per-case plots
    • Sweep types
      • Scalar sweep — add_scalar_sweep(data_key, param_name, values)
      • Storage factor sweep — add_storage_factor_sweep(param_name, factors)
      • Time-series sweep — add_ts_sweep(ts_key, factors)
    • Cartesian product and case naming
    • Output structure
    • Performance guidance
    • Visualising parametric results
      • Grouping strategy
      • Additional options
  • Resiliency Evaluation
    • Two Optimization Problems
      • Problem (B) - Baseline annual dispatch
      • Problem (O) - Per-hour outage dispatch
    • Inputs
      • 1. Snapshot directory (snapshot_dir)
      • 2. Previous-stage inputs directory (inputs_dir)
    • Outage Specification
    • Quickstart
      • 1. End-to-end with evaluate_resiliency
      • 2. Step-by-step (more control, advanced)
      • 3. Constant critical load during the outage window
      • 4. Optional profiling
    • Results
      • Per-hour DataFrame
      • Aggregate metrics
      • Persistence
    • Plotting
    • Logging
  • Resiliency Mathematical Formulation
    • 1. Sets
    • 2. Parameters
      • 2.1 Designed capacities (fixed)
      • 2.2 Time series
      • 2.3 Costs
      • 2.4 Outage / operational
    • 3. Variables
    • 4. Objective Functions
      • 4.1 Problem (B): Baseline annual dispatch
      • 4.2 Problem (O): Per-hour outage dispatch starting at \(h\)
    • 5. Constraints
      • 5.1 Power balance
      • 5.2 Capacity bounds with de-rating
      • 5.3 Storage dynamics, charge / discharge bounds
      • 5.4 Demand-charge linking (Problem (B))
      • 5.5 Outage problem coupling (Problem (O), starting at \(h\))
    • 6. Outage Modeling Formalism
      • 6.1 Capacity-bounded assets
      • 6.2 Must-run time-series sources
      • 6.3 Recovery window semantics
    • 7. Resiliency Metrics
      • 7.1 Per-scenario (anchored at \(h\))
      • 7.2 Aggregate
      • 7.3 Probability-weighted expected metrics
  • Exploring the Pyomo Model
    • Model Architecture
    • Zonal Model Structure (AreaTransportationModelNetwork)
    • Model Components
      • Sets
      • Parameters
      • Variables
      • Expressions
      • Constraints
    • Inspecting the Model
      • Print Model Summary
      • Examine Specific Constraints
      • Display Variable Bounds
    • Model Modifications
      • Changing Parameters Between Runs
      • Adding Custom Constraints
    • Debugging Model Issues
      • Check for Infeasibility
      • Validate Model Construction
    • Advanced: Direct Pyomo Operations
    • Model Formulation Files
    • Next Steps
  • SDOM Formulation
    • Sets
    • Parameters
      • Derived quantities
      • System
      • Fixed generation profiles
      • Renewable investment
      • Balancing units
      • Hydro
      • Trade
      • Storage
    • Variables
      • Renewable (investment and dispatch)
      • Balancing units (investment and dispatch)
      • Storage (investment and operations)
      • Hydro
      • Trade
    • Objective Function
      • PV cost
      • Wind cost
      • Balancing unit cost
      • Storage cost
      • Trade cost
    • Constraints
      • System constraints
      • VRE balance constraints
      • Balancing unit constraints
      • Storage constraints
      • Hydro budget constraints
      • Import and export constraints
  • Zonal Math Formulation
    • Sets
    • Parameters
    • Variables
    • Network Constraints
    • Per-Area Supply Balance
    • System-Wide Clean Share Constraint
    • Objective

API Reference

  • API Reference
    • Core Modules
      • Core Optimization Functions
      • Results Module
      • Model Formulations
      • Data I/O Manager
      • Utility Functions
      • sdom.parametric — Parametric Analysis
      • Resiliency Module
    • Quick Links
    • Main Functions
      • sdom.load_data
      • sdom.initialize_model
      • sdom.run_solver
      • sdom.export_results
      • sdom.get_default_solver_config_dict
      • sdom.configure_logging
    • Package Structure
  • Core Optimization Functions
    • Model Initialization
      • initialize_model()
    • Solver Configuration
      • get_default_solver_config_dict()
      • configure_solver()
    • Running Optimization
      • run_solver()
    • Configuration
      • configure_logging()
      • ColorFormatter
    • Example Usage
    • See Also
  • Results Module
    • OptimizationResults Class
      • OptimizationResults
    • Result Collection Function
      • collect_results_from_model()
    • Example Usage
      • Basic Result Access
      • Accessing Capacities
      • Accessing DataFrames
      • Accessing Cost Breakdown
      • Accessing Problem Information
    • OptimizationResults Attributes
      • Solver Information
      • Core Results
      • Capacity Results
      • Generation Results
      • Cost Breakdown
      • DataFrames
      • Zonal Fields
  • Model Formulations
    • System Formulations
      • objective_rule()
      • net_load_rule()
      • add_system_expressions()
      • create_supply_balance_rule()
      • genmix_share_rule()
      • add_system_constraints()
    • VRE Formulations
      • add_vre_parameters()
      • add_vre_variables()
      • add_vre_expressions()
      • add_vre_fixed_costs()
      • vre_balance_rule()
      • add_vre_balance_constraints()
    • Storage Formulations
      • initialize_storage_sets()
      • add_storage_parameters()
      • add_storage_variables()
      • storage_power_capex_cost_expr_rule()
      • storage_energy_capex_cost_expr_rule()
      • storage_fixed_om_cost_expr_rule()
      • add_storage_expressions()
      • add_storage_fixed_costs()
      • add_storage_variable_costs()
      • soc_balance_rule()
      • max_cycle_year_rule()
      • add_storage_constraints()
    • Thermal Formulations
      • initialize_thermal_sets()
      • add_thermal_parameters()
      • add_thermal_variables()
      • total_thermal_expr_rule()
      • add_thermal_expressions()
      • add_thermal_constraints()
      • add_thermal_fixed_costs()
      • add_thermal_variable_costs()
    • Hydropower Formulations
      • add_large_hydro_parameters()
      • add_large_hydro_bound_parameters()
      • add_hydro_variables()
      • add_hydro_run_of_river_constraints()
      • add_hydro_budget_constraints()
    • Import/Export Formulations
      • add_import_export_ts_parameters()
      • add_imports_parameters()
      • add_exports_parameters()
      • add_imports_variables()
      • add_exports_variables()
      • add_imports_exports_cost_expressions()
      • add_import_export_binary_variable()
      • add_imports_constraints()
      • add_exports_constraints()
      • add_imports_constraints_without_net_load()
      • add_exports_constraints_without_net_load()
      • add_imports_exports_cost()
    • Network (Zonal) Formulations
      • add_network_sets()
      • add_network_parameters()
      • add_network_variables()
      • add_network_constraints()
      • add_network_expressions()
      • network_transmission_cost_rule()
    • Host Pattern in Formulation Builders
    • Model Utilities
      • compute_annualization_factor()
      • build_annualization_factor_map()
      • get_filtered_ts_parameter_dict()
      • add_alpha_parameter()
      • add_alpha_and_ts_parameters()
      • add_budget_parameter()
      • add_upper_bound_paramenters()
      • add_lower_bound_paramenters()
      • add_generation_variables()
      • sum_installed_capacity_by_plants_set_expr_rule()
      • generic_fixed_om_cost_expr_rule()
      • generic_capex_cost_expr_rule()
      • different_fcr_capex_cost_expr_rule()
      • generic_budget_rule()
      • add_generic_fixed_costs()
    • Initialization Functions
      • initialize_vre_sets()
      • check_n_hours()
      • create_budget_set()
      • initialize_sets()
      • initialize_params()
  • Data I/O Manager
    • Data Loading
      • load_data()
    • Formulation Management
      • get_formulation()
      • get_network_formulation()
      • check_formulation()
    • Results Export
      • export_results()
    • Example: Loading Data
    • Example: Exporting Results
    • Data Dictionary Structure
  • Utility Functions
    • Pyomo Utilities
      • safe_pyomo_value()
    • File Utilities
      • check_file_exists()
      • get_complete_path()
      • normalize_string()
    • Data Utilities
      • compare_lists()
      • concatenate_dataframes()
      • get_dict_string_void_list_from_keys_in_list()
    • Constants
      • Unit Conversion
      • Input File Names
      • Hydro Formulations
      • Import/Export Formulations
    • Example Usage
  • Resiliency Module
    • Top-Level Convenience
      • evaluate_resiliency()
    • Data Loading
      • load_designed_system()
      • DesignedSystem
      • BaselineState
    • Outage Specification
      • OutageSpec
      • VALID_COMPONENTS
      • MUST_RUN_COMPONENTS
    • Baseline Dispatch (Problem B)
      • build_baseline_dispatch()
      • run_baseline_dispatch()
      • BaselineDispatchResults
    • Outage Dispatch (Problem O)
      • build_outage_dispatch()
    • Imports Formulation with Demand Charges
      • add_imports_with_demand_charges()
    • Parallel Runner
      • run_resiliency_evaluation()
    • Results Container
      • ResiliencyResults
    • Plotting
      • plot_metric_distribution()

Development

  • GUIDELINES FOR DEVELOPING SDOM
    • General Guidelines
    • Table of Contents
  • clone/fork SDOM repo
  • Setting up your enviroment
    • Install uv
    • Install your local SDOM python module and pytest
  • Running tests locally
  • Build the documentation locally
  • General Source code structure
  • Developer Guide: sdom.parametric Implementation
    • Sub-package layout
    • Data flow
    • Key design decisions
      • 1. Lazy deep-copy (memory efficiency)
      • 2. Collision-safe case naming
      • 3. Result ordering via case_index (not name lookup)
      • 4. Module-level worker function (pickling)
      • 5. Graceful failure
    • mutations.py — TS_KEY_TO_COLUMN mapping
    • Case naming format
    • Summary CSV columns
    • How to extend
      • Adding a new sweep type
      • Adding a new time-series key
    • Testing strategy
    • Known limitations & deferred items
  • PUBLICATIONS AND USE CASES OF SDOM
  • GitHub Repository
SDOM
  • Python Module Index

Python Module Index

s
 
s
- sdom
    sdom.initializations
    sdom.models.formulations_hydro
    sdom.models.formulations_imports_exports
    sdom.models.formulations_network
    sdom.models.formulations_storage
    sdom.models.formulations_system
    sdom.models.formulations_thermal
    sdom.models.formulations_vre
    sdom.models.models_utils

© Copyright 2026, NLR SDOM Team.

Built with Sphinx using a theme provided by Read the Docs.