# thomasdkelly/aquacrop architecture

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

- Interactive diagram: https://gitdiagram.com/thomasdkelly/aquacrop
- Repository: https://github.com/thomasdkelly/aquacrop

## Overview

- Data Management:
- “aquacrop/data” folder. This includes climate, soil, CO2, and other experimental data that feed into the simulation.
- Domain Entities:
- “aquacrop/entities” layer, which encapsulates key domain objects such as Crop, Soil, Irrigation Management, GroundWater, and various parameter and structural definitions (like crop parameters, water stress coefficients, etc.).
- Initialization Module:
- “aquacrop/initialize” directory. This module reads weather inputs, field management inputs, and soil profile information, and calculates initial conditions and model parameters.
- Simulation Core:
- “aquacrop/core.py” component which likely acts as the central orchestrator.
- Simulation Solutions:
- “aquacrop/solution” folder that consists of various simulation routines (e.g., canopy cover, biomass accumulation, infiltration, drainage, etc.). This module computes state changes during simulation.
- Simulation Timestep Management:
- “aquacrop/timestep”. This layer handles the update of simulation time, checks if the model has been completed or if additional outputs are needed per timestep and whether to continue simulation.
- Utilities:
- “aquacrop/utils”. This module supports helper functions such as weather file preparation.
- Testing and Documentation:
- “tests” and “docs” directories as peripheral components demonstrating quality assurance and documentation.
- External Interfaces:
- AquaPlan web application from the README (streamlit based) as an external GUI that interacts with the core simulation and exposes model outputs to users and stakeholders.

##### Relationships and Data Flow
- Data files in the “aquacrop/data” folder are consumed by the initialization module to create initial model states.
- The initialization module prepares the domain entities by reading inputs (weather, soil parameters, crop parameters, etc.).
- Core simulation (“aquacrop/core.py”) orchestrates the simulation by integrating the domain entities, initialization data, and solution functions.
- During the simulation loop, the “timestep” module calls update functions and monitors simulation progress.
- The “solution” layer calculates detailed simulation functions such as canopy cover, transpiration, evapotranspiration, and stress effects that feed back into the simulation’s state.
- Utilities support the process by preparing and validating the weather inputs, among others.
- A set of tests in the “tests” module ensure the simulation works correctly.

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize separation into distinct modules (entities, initialization, solution, timestep, and utils). Each module handles a specific responsibility, enhancing maintainability and testability.
- Layered Architecture: Show the flow—from data ingestion (input files), to preparation/initialization, then simulation in cycles, and finally output generation.
- Extensibility: The splitting of simulation logic (solution routines) and initialization suggests that the system is designed to allow for easy updates or extension (e.g., new simulation components or external interfaces).
- Testing and CI/CD: Note the GitHub workflows and tests which indicate continuous integration practices.

##### Relevant Technologies
- Python serves as the primary programming language.
- Mention libraries/frameworks: streamlit for AquaPlan, and any data manipulation or scientific computing libraries (e.g., pandas, numpy) are likely used (based on typical patterns, though their exact names aren’t explicit in the tree).
- The project also uses configuration files (setup.py, pyproject.toml) indicating use of modern packaging and build methodologies.

##### Additional Details
- Notes like “CI/CD” or “Testing Framework” pointing to the .github/workflows and tests directories.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        A["Data Files"]:::internal
        B["Utilities"]:::internal
        C["Initialization"]:::internal
    end

    %% Domain Layer
    subgraph "Domain & Setup"
        D["Domain Entities"]:::internal
        D1["Crops"]:::internal
    end

    %% Simulation Core Layer
    subgraph "Simulation Core"
        E["Core Simulation Engine"]:::internal
        F["Simulation Solutions"]:::internal
        G["Timestep Controller"]:::internal
    end

    %% Testing & Documentation
    subgraph "Testing & Documentation"
        H["Tests"]:::internal
        I["Docs"]:::internal
        J["CI/CD Workflows"]:::internal
    end

    %% External Interface
    K["AquaPlan Web Interface"]:::external

    %% Data flow connections
    A -->|"feeds"| C
    B -->|"supports"| C
    C -->|"initializes"| D
    D1 -->|"partOf"| D
    C -->|"providesInputs"| E
    D -->|"domainModel"| E
    E -->|"executes"| F
    E -->|"controlsTime"| G
    F -->|"updatesState"| E
    G -->|"loopsSimulation"| E
    E -->|"outputs"| K

    %% Testing and Documentation connections
    H ---|"tests"| E
    I ---|"docs"| E
    J ---|"CI/CD"| E

    %% Legend (informative note; not interactive)
    L["Legend: Green = Internal Components; Yellow = External Interfaces"]:::internal

    %% Position the legend at the bottom
    E --- L

    %% Click Events
    click A "https://github.com/thomasdkelly/aquacrop/tree/master/aquacrop/data"
    click B "https://github.com/thomasdkelly/aquacrop/tree/master/aquacrop/utils"
    click C "https://github.com/thomasdkelly/aquacrop/tree/master/aquacrop/initialize"
    click D "https://github.com/thomasdkelly/aquacrop/tree/master/aquacrop/entities"
    click D1 "https://github.com/thomasdkelly/aquacrop/tree/master/aquacrop/entities/crops"
    click E "https://github.com/thomasdkelly/aquacrop/blob/master/aquacrop/core.py"
    click F "https://github.com/thomasdkelly/aquacrop/tree/master/aquacrop/solution"
    click G "https://github.com/thomasdkelly/aquacrop/tree/master/aquacrop/timestep"
    click H "https://github.com/thomasdkelly/aquacrop/tree/master/tests"
    click I "https://github.com/thomasdkelly/aquacrop/tree/master/docs"
    click J "https://github.com/thomasdkelly/aquacrop/tree/master/.github/workflows"

    %% Styles
    classDef internal fill:#A1D490,stroke:#333,stroke-width:2px;
    classDef external fill:#FDD835,stroke:#333,stroke-width:2px;
```
