# yl1127/ml-adcirc architecture

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

- Interactive diagram: https://gitdiagram.com/yl1127/ml-adcirc
- Repository: https://github.com/yl1127/ml-adcirc

## Overview

##### Main Components
- Environment Setup and Dependency Management: Represent the use of Conda environments (with files like environment.yml and variants) for ensuring a reproducible Python setup.
- Preprocessing & Data Preparation Module: Indicate processing steps (data downloading, conversion, and cleaning) as performed in the notebooks in the “example” directory.
- ML Model Training & Evaluation Pipeline: Illustrate the “example/01-Introduction” directory containing Jupyter notebooks, configuration files, run logs, and checkpoints. In this module, training routines produce model artifacts and logs (with events logs and saved model checkpoints).
- ADCIRC Integration/Usage Module: Identify the instructions provided in the README for running ADCIRC either via Docker or SMS. This module represents the traditional computational model used to generate coastal ocean simulation outputs that may complement or be compared with ML predictions.
- Documentation & Meetings: While not part of the runtime architecture, include a “Docs” or “Meetings” component to show that research discussions and presentations (PPTs, PDFs) support iterative development and refinement of the project.

##### Relationships and Data Flow
- Directional data flows starting from raw input data (from the “data” directory) being processed by the notebooks (in “example/00-Data-Prerequisites” and “example/01-Introduction”).
- From preprocessing, the clean datasets are fed into the ML model training module. Mark interactions such as configuration files (e.g., config.yml, basin.yml) that drive experiments.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly divide the roles—data handling, model training, and ADCIRC simulation are distinct modules.
- Extensibility: Since notebooks and modular scripts indicate a research-driven prototype, note that additional modules (benchmarking, new model types) can be interwoven later.

##### Relevant Technologies, Frameworks, and Libraries
- Python and Jupyter Notebooks for experimentations.
- Conda package management through environment files.
- NeuralHydrology (cited in the README) as an underlying ML framework.
- ADCIRC (accessed via Docker/SMS) for coastal ocean modeling.
- Data formats such as NetCDF for storing time series data.

##### Elements
- Clear Labels: Name each component (e.g., “Environment Setup”, “Data Ingestion”, “Preprocessing & Feature Engineering”, “ML Training Pipeline”, “ADCIRC Simulation Module”, “Documentation & Meeting Artifacts”).

##### Detailed Architectural Representation
- To represent “external resources” such as online datasets (CORA, ERA5) and ADCIRC Docker containers in an “External Systems” section.
- Environment configuration as a foundational element since every component depends on the correct Python runtime and package versions.

Happy Diagramming!

## Diagram (Mermaid)

```mermaid
graph TD
    %% Environment Setup
    ENV["Environment Setup & Dependency Management"]:::environment

    %% Data Management
    DATA["Data Ingestion & Storage"]:::data
    EXTD["External Datasets (CORA & ERA5)"]:::external

    %% Data Processing
    PRE["Preprocessing & Data Preparation Module"]:::preprocessing

    %% ML Training Pipeline
    ML["ML Model Training & Evaluation Pipeline"]:::ml

    %% ADCIRC Module
    ADCIRC["ADCIRC Simulation Module"]:::adcirc

    %% Supporting Documentation
    DOCS["Documentation & Meetings"]:::docs

    %% Data Flow Relationships
    ENV -->|"setsUp"| DATA
    EXTD -->|"providesData"| DATA
    DATA -->|"rawData"| PRE
    PRE -->|"processedData"| ML
    ML -->|"modelOutputs"| ADCIRC
    ADCIRC -->|"simOutputs"| ML
    ML -->|"evaluationLogs"| DOCS
    ADCIRC -->|"simulationRecords"| DOCS
    ML -->|"feedback"| PRE

    %% Click Events
    click ENV "https://github.com/yl1127/ml-adcirc/blob/main/environments/environment.yml"
    click DATA "https://github.com/yl1127/ml-adcirc/tree/main/data/time_series"
    click PRE "https://github.com/yl1127/ml-adcirc/tree/main/example/00-Data-Prerequisites"
    click ML "https://github.com/yl1127/ml-adcirc/tree/main/example/01-Introduction"
    click ADCIRC "https://github.com/yl1127/ml-adcirc/blob/main/README.md"
    click DOCS "https://github.com/yl1127/ml-adcirc/tree/main/docs"

    %% Styles
    classDef environment fill:#a29bfe,stroke:#6c5ce7,stroke-width:2px;
    classDef data fill:#55efc4,stroke:#00b894,stroke-width:2px;
    classDef external fill:#81ecec,stroke:#00cec9,stroke-width:2px;
    classDef preprocessing fill:#74b9ff,stroke:#0984e3,stroke-width:2px;
    classDef ml fill:#ffeaa7,stroke:#fdcb6e,stroke-width:2px;
    classDef adcirc fill:#fab1a0,stroke:#e17055,stroke-width:2px;
    classDef docs fill:#fd79a8,stroke:#d63031,stroke-width:2px;
```
