# gschivley/battery_model architecture

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

- Interactive diagram: https://gitdiagram.com/gschivley/battery_model
- Repository: https://github.com/gschivley/battery_model

## Overview

##### Project type and purpose
- This is a research/analysis tool (not a web app or microservice) for modeling battery storage dispatch in the NYISO day‐ahead market over a historical dataset (full year 2017).
- Core goal: ingest historical Locational Based Marginal Price (LBMP) CSVs, run a day‐ahead optimization for a battery asset, then output time‐series dispatch, energy state, summary revenue/cost, and visualizations.

##### File‐structure overview
- Top‐level:
- 2017_NYISO_LBMPs/… – hourly price CSVs by month/day
- src/ – Python modules
– read_data.py (data ingestion)
– battery_model.py (optimization logic)
- Dispatch optimization.ipynb & Price exploration.ipynb – orchestration & EDA in Jupyter
- requirements.txt & environment.yml – dependency specification
- README.md, LICENSE – documentation
- full_year_optimization_results.csv – sample output

##### Key architectural components
A. Data Layer
– File System: raw CSV price data (2017_NYISO_LBMPs/)
– read_data.py: parses directory, loads CSVs into Pandas DataFrame with timestamp & zone
B. Model Layer
– battery_model.py: defines the battery asset parameters and constructs a day‐ahead dispatch optimization
– Uses a solver (e.g., PuLP or CVXPy) under the hood to maximize arbitrage revenue, subject to SOE continuity, capacity, efficiency, throughput constraints
C. Orchestration & Analysis Layer
– Dispatch optimization.ipynb:
- Calls read_data to load price series
- Instantiates the battery model with given specs
- Executes optimization for each day or full horizon
- Aggregates hourly dispatch & SOE outputs
- Computes summary metrics (annual revenue, cost, throughput)
- Exports full_year_optimization_results.csv
- Generates per‐week and per‐month plots
– Price exploration.ipynb: exploratory data analysis on LBMP patterns
D. Environment & Deployment
– environment.yml / requirements.txt: Python 3.x, Pandas, NumPy, optimization solver, Jupyter
– Binder badge: interactive cloud environment

##### Interactions and data flow
1. User launches Jupyter notebook (locally or via Binder)
2. read_data.py reads raw CSVs → DataFrame (Price Series)
3. battery_model.py consumes DataFrame + battery specs → Optimization problem
4. Solver returns hourly dispatch schedule & SOE → DataFrame of results
5. Notebook aggregates results → summary metrics + plots → CSV & notebook outputs

##### Architectural patterns and principles
- Layered design: Data ingestion → Modeling → Orchestration/Visualization
- Single‐responsibility modules: each .py file has one clear purpose
- Reproducible environment via environment.yml + Binder integration
- Notebook for orchestration and ad-hoc analysis, not production code

– Clear, descriptive labels (“Load Price Data”, “Optimize Dispatch”, “Generate Plots”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        RawData["Raw Price Data (CSV)"]:::data
        DataReader["Data Reader (read_data.py)"]:::code
    end

    %% Model Layer
    subgraph "Model Layer"
        BatteryModel["Battery Model (battery_model.py + solver)"]:::code
    end

    %% Orchestration & Visualization Layer
    subgraph "Orchestration & Visualization"
        DispatchNB["Dispatch optimization.ipynb"]:::notebook
        EDANB["Price exploration.ipynb"]:::notebook
    end

    %% Outputs
    subgraph "Outputs"
        ExportCSV["full_year_optimization_results.csv"]:::output
        Plots["Plots (PNG/HTML)"]:::output
    end

    %% Environment & Documentation
    subgraph "Environment & Documentation"
        EnvConda["environment.yml"]:::env
        EnvPip["requirements.txt"]:::env
        Readme["README.md"]:::doc
        License["LICENSE"]:::doc
    end

    %% Data Flow
    RawData -->|"CSV files"| DataReader
    DataReader -->|"Pandas DataFrame"| BatteryModel
    BatteryModel -->|"Dispatch DataFrame"| DispatchNB
    DispatchNB -->|"Exports CSV"| ExportCSV
    DispatchNB -->|"Generates Plots"| Plots
    EDANB -->|"Calls Data Reader"| DataReader
    EDANB -->|"Pandas DataFrame"| EDANB

    %% Environment links
    EnvConda -.-> DispatchNB
    EnvConda -.-> EDANB
    EnvPip -.-> DispatchNB
    EnvPip -.-> EDANB

    %% Click Events
    click RawData "https://github.com/gschivley/battery_model/tree/master/2017_NYISO_LBMPs/"
    click DataReader "https://github.com/gschivley/battery_model/blob/master/src/read_data.py"
    click BatteryModel "https://github.com/gschivley/battery_model/blob/master/src/battery_model.py"
    click DispatchNB "https://github.com/gschivley/battery_model/blob/master/Dispatch optimization.ipynb"
    click EDANB "https://github.com/gschivley/battery_model/blob/master/Price exploration.ipynb"
    click ExportCSV "https://github.com/gschivley/battery_model/blob/master/full_year_optimization_results.csv"
    click EnvConda "https://github.com/gschivley/battery_model/blob/master/environment.yml"
    click EnvPip "https://github.com/gschivley/battery_model/blob/master/requirements.txt"
    click Readme "https://github.com/gschivley/battery_model/blob/master/README.md"
    click License "https://github.com/gschivley/battery_model/tree/master/LICENSE"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef code fill:#90EE90,stroke:#333,stroke-width:1px
    classDef notebook fill:#FFA500,stroke:#333,stroke-width:1px
    classDef output fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef env fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef doc fill:#F5F5F5,stroke:#333,stroke-width:1px
```
