# smarsgroup/geo_epic_win architecture

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

- Interactive diagram: https://gitdiagram.com/smarsgroup/geo_epic_win
- Repository: https://github.com/smarsgroup/geo_epic_win

## Overview

##### Project Type and Purpose
- Geo-EPIC is an open-source Python toolkit (not a full-stack web app) for large-scale, geospatial crop simulations using the EPIC model.
- It orchestrates data ingestion (soil, weather, remote sensing), calibration, and EPIC model execution across spatial workspaces.

##### High-Level Architectural Overview
- This is a modular CLI-driven engine, broken into:
a. Dispatcher/CLI (entry point)
b. Initialization & Workspace Management
c. Data Ingestion (soil, weather, GEE)
d. Core Logic (calibration, model setup, run orchestration)
e. OPC Generation (crop parameter templates)
f. EPIC Binary Execution
g. Data Logging & Outputs
h. Assets & Configuration Files

##### Main Components and Their Roles
1. **CLI / Dispatcher** (`src/geoEpic/dispatcher.py`)
- Parses user commands and configuration.
- Routes to sub-modules: initialize workspace, run simulation, calibrate.
2. **Initialization & Workspace** (`src/geoEpic/initialize.py`, `geoEpic/workspace/`)
- Creates directory structure, copies model binaries & templates.
- Manages parallel copying and workspace run scripts.
3. **Data Ingestion**
- **Soil** (`geoEpic/soil/`): fetch_usda, ssurgo, utilities.
- **Weather** (`geoEpic/weather/`): daymet API, GEE remote scripting, local daily files.
- **GEE** (`geoEpic/gee/`): Earth Engine initialization & data fetch.
- **IO Subsystem** (`geoEpic/io/`):
- Config parsing (YAML/INI)
- Input readers (dly, opc, sit, sol)
- Output writers (CSV, Redis, SQL)
4. **Calibration Module** (`geoEpic/core/calibration.py`)
- Fine-tunes EPIC parameters based on observed data.
- Uses built-in defaults and sensitivity files in assets.
5. **Core Model Logic** (`geoEpic/core/model.py`, `site.py`, `workspace.py`)
- Assembles inputs, parameterizes EPIC runs, orchestrates parallel runs through the EPIC executable.
6. **OPC Generation** (`geoEpic/opc/generate_opc.py`)
- Produces OPC files (crop templates) used by EPIC for specific scenarios.
7. **EPIC Binary** (packaged in `assets/workspace_win/model/EPIC1102.exe`)
- The compiled crop simulation engine.
8. **Data Logging & Output** (`geoEpic/io/data_logger/`)
- Captures EPIC run outputs to CSV, Redis, or SQL for downstream analysis.

##### Relationships & Data Flow
- User invokes CLI → Dispatcher
- Dispatcher calls Initialize → Workspace Manager → copies assets & binaries
- Dispatcher calls Data Ingestion modules → fetch soil, weather, GEE layers → local workspace
- Dispatcher calls Calibration (optional) → adjust parameter files in workspace
- OPC Generator creates crop templates (OPC files) in workspace
- Core Model Logic spins up EPIC runs in parallel, invoking the EPIC binary with prepared inputs
- EPIC binary produces output files → Data Logger reads them → writes to chosen sinks (CSV/Redis/SQL)
- End user retrieves summarized results

##### Architectural Patterns & Design Principles
- **Modular Layering**: clear separation between ingestion, core logic, I/O.
- **Plugin-style I/O**: different writers (CSV, Redis, SQL) conform to a common interface.
- **Parallel Execution**: uses Python parallel utilities to run multiple EPIC instances simultaneously.
- **CLI-Driven Workflow**: single entry point orchestrates end-to-end process.
- **Asset-Backed Templates**: shipping calibration defaults, OPC and model binaries in `assets/`.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and CLI
    User["End User"]:::external
    Config["Configuration (YAML/INI)"]:::assets
    Dispatcher["Dispatcher / CLI"]:::module
    User -->|"invokes CLI"| Dispatcher
    Config -->|"parsed by"| Dispatcher

    %% Initialization & Workspace
    subgraph "Initialization & Workspace" 
        Init["Initialization Module"]:::module
        WS_Create["create_ws.py"]:::module
        WS_Copy["parallel_copy.py"]:::module
        WS_Run["run.py"]:::module
    end
    Dispatcher -->|"initialize"| Init
    Init --> WS_Create
    Init --> WS_Copy
    Init --> WS_Run

    %% Data Ingestion
    subgraph "Data Ingestion"
        subgraph Soil
            Soil_USDA["fetch_usda.py"]:::module
            Soil_SSURGO["ssurgo_gdb.py"]:::module
            Soil_SDA["sda.py"]:::module
            Soil_Utils["utils.py"]:::module
        end
        subgraph Weather
            Weather_Daymet["daymet.py"]:::module
            Weather_Download["download_daily.py"]:::module
            Weather_Formule["formule.py"]:::module
            Weather_GEE["gee.py"]:::module
        end
        subgraph GEE
            GEE_Core["core.py"]:::module
            GEE_Fetch["fetch.py"]:::module
            GEE_Init["initialize.py"]:::module
        end
        subgraph IO_Subsystem
            ConfigParser["config_parser.py"]:::module
            CropCom["cropcom.py"]:::module
            Parm["parm.py"]:::module
            subgraph Inputs
                Input_DLY["dly.py"]:::module
                Input_OPC["opc.py"]:::module
                Input_SIT["sit.py"]:::module
                Input_SOL["sol.py"]:::module
            end
            Outputs["outputs.py"]:::module
            subgraph Plugin_Outputs
                Out_All["all.py"]:::module
                Out_SW["sw.py"]:::module
            end
        end
    end
    Dispatcher -->|"fetch soil"| Soil_USDA
    Dispatcher -->|"fetch weather"| Weather_Daymet
    Dispatcher -->|"init GEE"| GEE_Init
    Dispatcher -->|"IO operations"| ConfigParser

    %% Calibration
    Calibration["Calibration Module"]:::module
    Dispatcher -->|"calibrate"| Calibration

    %% OPC Generation
    OPC["OPC Generation"]:::module
    Dispatcher -->|"generate opc"| OPC

    %% Core Model Logic
    subgraph "Core Model Logic"
        Model["model.py"]:::module
        Site["site.py"]:::module
        Workspace_Run["workspace.py"]:::module
    end
    Dispatcher -->|"run model"| Model
    Model --> Site
    Model --> Workspace_Run

    %% EPIC Binary Execution
    EPIC_Bin["EPIC1102.exe"]:::assets
    Model -->|"invoke binary"| EPIC_Bin

    %% Data Logging & Outputs
    subgraph "Data Logging & Outputs"
        DataLogger["main.py"]:::module
        CSV_Writer["csv_writer.py"]:::module
        Redis_Writer["redis_writer.py"]:::module
        SQL_Writer["sql_writer.py"]:::module
    end
    EPIC_Bin -->|"produces outputs"| DataLogger
    DataLogger --> CSV_Writer
    DataLogger --> Redis_Writer
    DataLogger --> SQL_Writer

    %% Assets & Templates
    subgraph "Workspace Assets"
        Assets_General["assets/"]:::assets
        Templates["workspace_win/config.yml"]:::assets
        Templates2["workspace_win/opc/crop_templates/"]:::assets
    end
    Init --> Assets_General
    OPC --> Templates2

    %% Click Events
    click Dispatcher "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/dispatcher.py"
    click Init "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/initialize.py"
    click WS_Create "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/workspace/create_ws.py"
    click WS_Copy "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/workspace/parallel_copy.py"
    click WS_Run "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/workspace/run.py"
    click Soil_USDA "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/soil/fetch_usda.py"
    click Soil_SSURGO "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/soil/ssurgo_gdb.py"
    click Soil_SDA "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/soil/sda.py"
    click Soil_Utils "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/soil/utils.py"
    click Weather_Daymet "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/weather/daymet.py"
    click Weather_Download "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/weather/download_daily.py"
    click Weather_Formule "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/weather/formule.py"
    click Weather_GEE "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/weather/gee.py"
    click GEE_Core "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/gee/core.py"
    click GEE_Fetch "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/gee/fetch.py"
    click GEE_Init "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/gee/initialize.py"
    click ConfigParser "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/config_parser.py"
    click CropCom "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/cropcom.py"
    click Parm "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/parm.py"
    click Input_DLY "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/inputs/dly.py"
    click Input_OPC "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/inputs/opc.py"
    click Input_SIT "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/inputs/sit.py"
    click Input_SOL "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/inputs/sol.py"
    click Outputs "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/outputs.py"
    click Out_All "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/outputs/all.py"
    click Out_SW "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/outputs/sw.py"
    click DataLogger "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/data_logger/main.py"
    click CSV_Writer "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/data_logger/csv_writer.py"
    click Redis_Writer "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/data_logger/redis_writer.py"
    click SQL_Writer "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/io/data_logger/sql_writer.py"
    click Calibration "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/core/calibration.py"
    click Model "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/core/model.py"
    click Site "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/core/site.py"
    click Workspace_Run "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/core/workspace.py"
    click OPC "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/opc/generate_opc.py"
    click EPIC_Bin "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/assets/workspace_win/model/EPIC1102.exe"
    click Assets_General "https://github.com/smarsgroup/geo_epic_win/tree/main/src/geoEpic/assets/"
    click Templates "https://github.com/smarsgroup/geo_epic_win/blob/main/src/geoEpic/assets/workspace_win/config.yml"
    click Templates2 "https://github.com/smarsgroup/geo_epic_win/tree/main/src/geoEpic/assets/workspace_win/opc/crop_templates/"

    %% Styles
    classDef module fill:#E0F7FA,stroke:#006064,stroke-width:1px
    classDef external fill:#E8F5E9,stroke:#1B5E20,stroke-width:1px
    classDef assets fill:#ECEFF1,stroke:#37474F,stroke-width:1px
```
