# nrel/sdom architecture

> Architecture diagram of the GitHub repository nrel/sdom, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nrel/sdom
- Repository: https://github.com/nrel/sdom

## Overview

##### Project Type and Purpose
- SDOM is primarily an optimization framework (MILP) for planning energy storage deployment.
- It is implemented in GAMS (core model) with a companion Python package for data handling and post-processing.
- Its goal is to ingest time-series and techno-economic inputs, solve a MILP, and produce summary outputs.

##### File Structure
- Root:
- SDOM_1.0.gms – the GAMS model file (defines sets, parameters, variables, equations).
- SDOM_Sol_Summary_Updated.py – Python script for summarizing or post-processing results.
- README.md, LICENSE.
- SDOM_TestCase/ – contains a complete example:
- inputs/ – all CSV and TXT files for load profiles, VRE resource profiles, storage tech, scalars.
- cplex.opt – solver options for CPLEX.
- SDOM_1.0.gms, SDOM_1.0.log, SDOM_1.0.~gm – GAMS run artifacts.
- Output/ – CSV files generated by a test run.

##### README for Technical Stack
- Core modeling: GAMS MILP with CPLEX solver.
- Python 3.10+ for open-source orchestration and post-processing (likely uses pandas/numpy).
- Input files: flat CSV/TXT files in “inputs” folder.
- Outputs: CSV summaries ready for analysis or visualization.

##### Main Components and Their Relationships
a. Input Data Store (Folder “inputs”)
- Contains time-series (8760 rows) and techno-economic parameters (scalars.csv, StorageData_2050.csv, CapSolar_2050.csv, etc.).
b. Orchestration Layer (Python Script)
- Reads inputs, may pre-process or validate.
- Optionally writes GAMS data exchange files (e.g., GDX) or directly calls GAMS.
c. Optimization Engine (GAMS Model + Solver)
- SDOM_1.0.gms: defines the MILP formulation (sets, parameters, variables, equations).
- CPLEX configured via cplex.opt.
- Processes inputs and solves the model.
d. Post-Processing Layer (Python Script)
- Parses GAMS output (.log, .lst, .gdx).
- Converts solution into CSV summaries (Output/2050_*.csv).
e. Test Harness (SDOM_TestCase)
- Provides a containerized example run: inputs → model → outputs.
f. External Dependencies
- GAMS software (model compiler).
- CPLEX solver.
- Python runtime (3.10+) and libraries (pandas, numpy).

##### Architectural Patterns and Design Principles
- Layered architecture: Data layer → Orchestration → Optimization core → Post-processing → Outputs.
- Clear separation of concerns:
- Data ingestion and validation in Python.
- Mathematical formulation and solving in GAMS.
- Reporting and summary back in Python.
- Reusability: The test case folder can be swapped out for new datasets.
- Configurability: Solver options via cplex.opt; time horizon and tech sets via input files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    Inputs["Inputs Folder"]:::inputs
    Orch["Python Orchestrator\n(SDOM_Sol_Summary_Updated.py)"]:::orchestration
    GAMS["GAMS Model\n(SDOM_1.0.gms)"]:::optimization
    CPLEX["CPLEX Solver Options\n(cplex.opt)"]:::external
    Post["Post-Processing\n(SDOM_Sol_Summary_Updated.py)"]:::postprocessing
    Outputs["Outputs Folder"]:::outputs

    %% Test Harness Subgraph
    subgraph "Test Harness"
        TH_root["Test Harness Root"]:::external
        TH_inputs["Inputs Folder\n(SDOM_TestCase/inputs/)"]:::inputs
        gpr["GAMS Project File\n(GAMS_Project_OptimalTechMix.gpr)"]:::optimization
        TH_gms["GAMS Model Copy\n(SDOM_1.0.gms)"]:::optimization
        log["GAMS Log Artifact\n(SDOM_1.0.log)"]:::external
        tmp["GAMS Temp File\n(SDOM_1.0.~gm)"]:::external
        TH_outputs["Outputs Folder\n(SDOM_TestCase/Output/)"]:::outputs
        out1["Generation Summary CSV"]:::outputs
        out2["Selected VRE CSV"]:::outputs
        out3["Storage CSV"]:::outputs
        out4["Summary CSV"]:::outputs
    end

    %% Main Flow
    Inputs -->|CSV| Orch
    Orch -->|call GAMS| GAMS
    GAMS -->|use cplex.opt| CPLEX
    GAMS -->|log/.gdx| Post
    Post -->|CSV| Outputs

    %% Test Harness Flow
    TH_root --> TH_inputs
    TH_inputs -->|CSV| TH_gms
    TH_gms -->|project| gpr
    TH_gms -->|log| log
    TH_gms -->|temp| tmp
    log --> Post
    tmp --> Post
    Post -->|CSV| TH_outputs
    TH_outputs --> out1
    TH_outputs --> out2
    TH_outputs --> out3
    TH_outputs --> out4

    %% Click Events
    click TH_root "https://github.com/nrel/sdom/tree/master/SDOM_TestCase/"
    click TH_inputs "https://github.com/nrel/sdom/tree/master/SDOM_TestCase/inputs/"
    click Orch "https://github.com/nrel/sdom/blob/master/SDOM_Sol_Summary_Updated.py"
    click GAMS "https://github.com/nrel/sdom/blob/master/SDOM_1.0.gms"
    click CPLEX "https://github.com/nrel/sdom/blob/master/SDOM_TestCase/cplex.opt"
    click gpr "https://github.com/nrel/sdom/blob/master/SDOM_TestCase/GAMS_Project_OptimalTechMix.gpr"
    click TH_gms "https://github.com/nrel/sdom/blob/master/SDOM_TestCase/SDOM_1.0.gms"
    click log "https://github.com/nrel/sdom/blob/master/SDOM_TestCase/SDOM_1.0.log"
    click tmp "https://github.com/nrel/sdom/blob/master/SDOM_TestCase/SDOM_1.0.~gm"
    click TH_outputs "https://github.com/nrel/sdom/tree/master/SDOM_TestCase/Output/"
    click out1 "https://github.com/nrel/sdom/blob/master/SDOM_TestCase/Output/2050_OutputGeneration_SDOM_SDOM_TestCase_Nuclear_1_Target_1.00NoInportExport_.csv"
    click out2 "https://github.com/nrel/sdom/blob/master/SDOM_TestCase/Output/2050_OutputSelectedVRE_SDOM_SDOM_TestCase_Nuclear_1_Target_1.00_.csv"
    click out3 "https://github.com/nrel/sdom/blob/master/SDOM_TestCase/Output/2050_OutputStorage_SDOM_SDOM_TestCase_Nuclear_1_Target_1.00NoInportExport_.csv"
    click out4 "https://github.com/nrel/sdom/blob/master/SDOM_TestCase/Output/2050_OutputSummary_SDOM_SDOM_TestCase_Nuclear_1_Target_1.00NoInportExport_.csv"

    %% Styles
    classDef inputs fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px
    classDef orchestration fill:#D5F5E3,stroke:#145A32,stroke-width:1px
    classDef optimization fill:#FAD7A0,stroke:#7D6608,stroke-width:1px
    classDef postprocessing fill:#ABEBC6,stroke:#186A3B,stroke-width:1px
    classDef outputs fill:#E5E7E9,stroke:#424949,stroke-width:1px
    classDef external fill:#EBDEF0,stroke:#6C3483,stroke-width:1px
```
