How smarsgroup/geo_epic_win works
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/.