# dement-model/dementpy architecture

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

- Interactive diagram: https://gitdiagram.com/dement-model/dementpy
- Repository: https://github.com/dement-model/dementpy

## Overview

##### Main components
a. Core Simulation Engine (src/)
- dementpy.py (entry point / CLI)
- initialization.py (loads parameters & grid setup)
- grid.py (spatial grid management)
- microbe.py, enzyme.py, monomer.py, substrate.py (domain models)
- output.py, utility.py (I/O and helper functions)
b. Data Inputs (input/, grassland/)
- CSV files driving climate, enzyme traits, substrates, parameters, runtime settings, substrate-monitor inputs
c. Data Outputs (output/ or grassland/... runtime.txt / .pickle)
- Pickled simulation results, runtime logs
d. Post-processing & Analysis (SPA/)
- Shell scripts for batch submission (SGE/slurm)
- Python scripts for extracting / plotting results (data_extraction.py, output.py, drought_trait.py, etc.)
e. Infrastructure & Deployment
- pyproject.toml + uv for dependency management
- HPC integration: SGE job scripts and Slurm .sub files

##### Architectural patterns & design principles
- Modular layering: clear separation of domain models (microbe, enzyme, substrate), simulation orchestration (dementpy.py + initialization), and I/O utilities
- Pipeline pattern: data flows sequentially from input → simulation engine → output → post-processing
- Plug-in style extensibility: domain modules can be swapped or extended (e.g., add new microbial processes)
- HPC compatibility: batch job abstraction via shell scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    Input[(Input Data Store)]:::data
    Grassland[(Grassland Data Store)]:::data

    %% CLI Entry
    CLI[/CLI / Shell/]:::infra

    %% Core Simulation Engine
    subgraph "Core Simulation Engine"
        direction TB
        DP["dementpy.py"]:::engine
        Init["initialization.py"]:::engine
        Grid["grid.py"]:::engine
        Microbe["microbe.py"]:::engine
        Enzyme["enzyme.py"]:::engine
        Monomer["monomer.py"]:::engine
        Substrate["substrate.py"]:::engine
        OutputMod["output.py"]:::engine
        Utility["utility.py"]:::engine
    end

    %% Output Store
    OutputStore[(Output Data Store)]:::data

    %% Post-processing & Analysis
    subgraph "Post-processing & Analysis (SPA)"
        direction TB
        subgraph "Batch Submission Scripts"
            direction TB
            Batch2[/batchjob2.sh/]:::analysis
            BatchTest[/batchjob_test.sh/]:::analysis
            Array[/dementpy_array.sh/]:::analysis
            Jupyter[/jupyternb.sh/]:::analysis
            MVOutputs[/mvoutputs.sh/]:::analysis
            Replicate[/replicate.sh/]:::analysis
            ReplicateTest[/replicate_test.sh/]:::analysis
            Scenario[/scenario_name.sh/]:::analysis
        end
        subgraph "Python Analysis Scripts"
            direction TB
            DataExt["data_extraction.py"]:::analysis
            Drought["drought_trait.py"]:::analysis
            EnzTrait["enzyme_trait.py"]:::analysis
            MicComm["mic_community.py"]:::analysis
            OutAnalysis["output.py"]:::analysis
            Tradeoff["tradeoff.py"]:::analysis
        end
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        direction TB
        PyProj["pyproject.toml"]:::infra
        subgraph "HPC Scheduler Interface"
            direction TB
            SGE[/sge_job.sh/]:::infra
            Slurm[/slurm_job.sub/]:::infra
            GroupSub[/group_submit.sh/]:::infra
        end
    end

    %% Connections - Data to Engine
    Input -->|read CSV| Init
    Grassland -->|read CSV| Init
    CLI -->|run simulation| DP
    DP -->|load params| Init
    Init -->|setup grid| Grid
    Init -->|instantiate models| Microbe
    Init -->|instantiate models| Enzyme
    Init -->|instantiate models| Monomer
    Init -->|instantiate models| Substrate

    %% Simulation Loop
    Microbe -->|"timestep update"| Enzyme
    Enzyme -->|"timestep update"| Monomer
    Monomer -->|"timestep update"| Substrate
    Substrate -->|"timestep update"| Microbe

    %% Output
    Enzyme -->|write data| OutputMod
    Microbe -->|write data| OutputMod
    OutputMod -->|write pickle/CSV| OutputStore

    %% Analysis Flow
    OutputStore -->|input data| DataExt
    DataExt --> Drought --> EnzTrait --> MicComm --> OutAnalysis --> Tradeoff

    %% HPC Control Flow
    Batch2 -.submit job.-> CLI
    BatchTest -.submit job.-> CLI
    Array -.submit job.-> CLI
    GroupSub -.submit job.-> CLI

    %% Dependency Management to Engine
    PyProj --> DP

    %% Click Events
    click DP "https://github.com/dement-model/dementpy/blob/main/src/dementpy.py"
    click Init "https://github.com/dement-model/dementpy/blob/main/src/initialization.py"
    click Grid "https://github.com/dement-model/dementpy/blob/main/src/grid.py"
    click Microbe "https://github.com/dement-model/dementpy/blob/main/src/microbe.py"
    click Enzyme "https://github.com/dement-model/dementpy/blob/main/src/enzyme.py"
    click Monomer "https://github.com/dement-model/dementpy/blob/main/src/monomer.py"
    click Substrate "https://github.com/dement-model/dementpy/blob/main/src/substrate.py"
    click OutputMod "https://github.com/dement-model/dementpy/blob/main/src/output.py"
    click Utility "https://github.com/dement-model/dementpy/blob/main/src/utility.py"
    click Input "https://github.com/dement-model/dementpy/tree/main/input/"
    click Grassland "https://github.com/dement-model/dementpy/tree/main/grassland/"
    click Batch2 "https://github.com/dement-model/dementpy/blob/main/SPA/batchjob2.sh"
    click BatchTest "https://github.com/dement-model/dementpy/blob/main/SPA/batchjob_test.sh"
    click Array "https://github.com/dement-model/dementpy/blob/main/SPA/dementpy_array.sh"
    click Jupyter "https://github.com/dement-model/dementpy/blob/main/SPA/jupyternb.sh"
    click MVOutputs "https://github.com/dement-model/dementpy/blob/main/SPA/mvoutputs.sh"
    click Replicate "https://github.com/dement-model/dementpy/blob/main/SPA/replicate.sh"
    click ReplicateTest "https://github.com/dement-model/dementpy/blob/main/SPA/replicate_test.sh"
    click Scenario "https://github.com/dement-model/dementpy/blob/main/SPA/scenario_name.sh"
    click DataExt "https://github.com/dement-model/dementpy/blob/main/SPA/scripts/data_extraction.py"
    click Drought "https://github.com/dement-model/dementpy/blob/main/SPA/scripts/drought_trait.py"
    click EnzTrait "https://github.com/dement-model/dementpy/blob/main/SPA/scripts/enzyme_trait.py"
    click MicComm "https://github.com/dement-model/dementpy/blob/main/SPA/scripts/mic_community.py"
    click OutAnalysis "https://github.com/dement-model/dementpy/blob/main/SPA/scripts/output.py"
    click Tradeoff "https://github.com/dement-model/dementpy/blob/main/SPA/scripts/tradeoff.py"
    click SGE "https://github.com/dement-model/dementpy/blob/main/SPA/scripts/sge_job.sh"
    click Slurm "https://github.com/dement-model/dementpy/blob/main/SPA/scripts/slurm_job.sub"
    click GroupSub "https://github.com/dement-model/dementpy/blob/main/SPA/scripts/group_submit.sh"
    click PyProj "https://github.com/dement-model/dementpy/blob/main/pyproject.toml"

    %% Styles
    classDef data fill:#a2d2ff,stroke:#1d3557,color:#1d3557
    classDef engine fill:#b7e4c7,stroke:#2f9e44,color:#1b4332
    classDef analysis fill:#ffe066,stroke:#b4690e,color:#78350f
    classDef infra fill:#adb5bd,stroke:#495057,color:#212529
```
