# adam-lagoda/p10 architecture

> Architecture diagram of the GitHub repository adam-lagoda/p10, 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/adam-lagoda/p10
- Repository: https://github.com/adam-lagoda/p10

## Overview

##### Project type and purpose
- This is a research‐grade, full-stack Python project for Active Heave Compensation using Deep Reinforcement Learning (DRL). It provides:
- A custom “boat” environment modeling heave dynamics and waves
- Simulation scripts
- Training pipelines for multiple RL algorithms (DDPG, DQN, PPO, SAC, TD3)
- Validation and analysis modules
- Separate wave‐prediction models (CNN/LSTM)
- Utility scripts for R² analysis and wave visualization

##### Top-level components
- Environment & Simulation
- buoyantboat/env: core physics and wave-generation modules
- buoyantboat/simulate: simulate without control
- Training
- buoyantboat/train: five algorithm‐specific scripts
- environment.yml: reproducible Python/Micromamba environment
- Validation & Analysis
- buoyantboat/validate: per‐algorithm test scripts + CSV data
- misc/r2: R² metrics on saved states
- Policy Storage & Logging
- trained_policies/converged: model archives, TensorBoard events, loss & reward CSVs
- Wave Prediction
- wave_prediction: CNN & LSTM prediction scripts
- Utilities
- misc/wavegen.py: animated wave generator

1. “Python Execution Environment”
– Micromamba/Python (environment.yml)
2. “Boat Environment”
– boat_env.py (equations)
– dh_transform.py, wave_generator.py, winch.py
3. “Simulator”
– simulate.py (no‐control baseline)
4. “Training Pipeline”
– boat_ddpg.py, boat_dqn.py, boat_ppo.py, boat_sac.py, boat_td3.py
– Uses Stable-Baselines3 or custom RL loops
5. “Validation Pipeline”
– ddpg_test.py, dqn_test.py, ppo_test.py, sac_test.py
– Produces CSV logs, uses real/synthetic wave data
6. “Policy Storage”
– saves .zip models, TensorBoard event files, CSV metrics
7. “Analysis Utilities”
– misc/r2 scripts: R² performance plots
– misc/wavegen: animated wave for reports
8. “Wave Prediction”
– wave_prediction_cnn.py, wave_prediction_lstm.py

– Python Env → (loads) → Boat Environment
– Boat Environment → (simulates) → Simulator → (data) → Training Pipeline
– Training → (saves) → Policy Storage
– Policy Storage → (model) → Validation Pipeline → (metrics) → CSV files
– CSV / event logs → Analysis Utilities → (plots)
– Real wave data → Wave Prediction → (predicted wave) → can feed back into Environment or Validation

c. Architectural patterns
- Modular separation: env / simulate / train / validate / predict
- Data‐driven pipelines: clear input/output (CSV, .zip, TensorBoard events)
- Reproducible environment (environment.yml)

d. Key technologies
– Python 3.x, Micromamba/YAML
– NumPy/SciPy for physics
– Stable Baselines3 or custom RL loops
– TensorBoard for logging
– pandas/Matplotlib for CSV analysis
– PyTorch or TensorFlow for CNN/LSTM

##### Emphasize
- Every directory as a distinct component
- Dependency on environment.yml at the top

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top-level Environment
    subgraph "Python Execution Environment"
        ENV["environment.yml"]:::env
    end

    %% Environment & Simulation
    subgraph "Boat Environment & Simulation" 
        direction TB
        BE["boat_env.py"]:::env
        DT["dh_transform.py"]:::env
        WG["wave_generator.py"]:::env
        WI["winch.py"]:::env
        SIM["simulate.py"]:::env
    end

    %% Training Pipeline
    subgraph "Training Pipeline" 
        direction TB
        DDPG["boat_ddpg.py"]:::train
        DQN["boat_dqn.py"]:::train
        PPO["boat_ppo.py"]:::train
        SAC["boat_sac.py"]:::train
        TD3["boat_td3.py"]:::train
        Trainer["Trainer"]:::train
    end

    %% Policy Storage
    POL["Policy Storage (.zip, events, CSV)"]:::storage

    %% Validation Pipeline
    subgraph "Validation Pipeline" 
        direction TB
        VT1["ddpg_test.py"]:::val
        VT2["dqn_test.py"]:::val
        VT2b["dqn_test_real_data.py"]:::val
        VT3["ppo_test.py"]:::val
        VT4["sac_test.py"]:::val
        VT4b["sac_test_real_data.py"]:::val
        VCSV["CSV Outputs"]:::data
    end

    %% Analysis Utilities
    subgraph "Analysis Utilities" 
        direction TB
        R2A["r2test.py"]:::analysis
        R2B["r2test_ue_data.py"]:::analysis
        WAVEVIS["wavegen.py"]:::analysis
        R2CSV["R² CSVs"]:::data
    end

    %% Wave Prediction
    subgraph "Wave Prediction" 
        direction TB
        CNN["wave_prediction_cnn.py"]:::pred
        LSTM["wave_prediction_lstm.py"]:::pred
    end

    %% Data Nodes
    RealData[(Real Wave Data)]:::data
    PredWave[(Predicted Wave)]:::data

    %% Connections
    ENV -->|"loads"| BE
    BE -->|"simulates"| SIM
    SIM -->|"data"| Trainer
    Trainer -->|".zip, events"| POL
    POL -->|"model"| VT1
    POL -->|"model"| VT2
    POL -->|"model"| VT2b
    POL -->|"model"| VT3
    POL -->|"model"| VT4
    POL -->|"model"| VT4b
    VT1 -->|"metrics"| VCSV
    VT2 -->|"metrics"| VCSV
    VT2b -->|"metrics"| VCSV
    VT3 -->|"metrics"| VCSV
    VT4 -->|"metrics"| VCSV
    VT4b -->|"metrics"| VCSV
    VCSV -->|"used by"| R2A
    VCSV -->|"used by"| R2B
    R2A -->|"plots"| R2CSV
    R2B -->|"plots"| R2CSV
    WAVEVIS -->|"animation"| R2CSV
    RealData -->|"input"| CNN
    RealData -->|"input"| LSTM
    CNN -->|"predicted wave"| PredWave
    LSTM -->|"predicted wave"| PredWave
    PredWave -->|"feeds"| BE
    PredWave -->|"feeds"| VT2b
    PredWave -->|"feeds"| VT4b

    %% Click Events
    click ENV "https://github.com/adam-lagoda/p10/blob/main/environment.yml"
    click BE "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/env/boat_env.py"
    click DT "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/env/dh_transform.py"
    click WG "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/env/wave_generator.py"
    click WI "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/env/winch.py"
    click SIM "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/simulate/simulate.py"
    click DDPG "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/train/boat_ddpg.py"
    click DQN "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/train/boat_dqn.py"
    click PPO "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/train/boat_ppo.py"
    click SAC "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/train/boat_sac.py"
    click TD3 "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/train/boat_td3.py"
    click VT1 "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/validate/ddpg_test.py"
    click VT2 "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/validate/dqn_test.py"
    click VT2b "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/validate/dqn_test_real_data.py"
    click VT3 "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/validate/ppo_test.py"
    click VT4 "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/validate/sac_test.py"
    click VT4b "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/validate/sac_test_real_data.py"
    click VCSV "https://github.com/adam-lagoda/p10/blob/main/buoyantboat/validate/*.csv"
    click POL "https://github.com/adam-lagoda/p10/tree/main/trained_policies/converged"
    click R2A "https://github.com/adam-lagoda/p10/blob/main/misc/r2/r2test.py"
    click R2B "https://github.com/adam-lagoda/p10/blob/main/misc/r2/r2test_ue_data.py"
    click WAVEVIS "https://github.com/adam-lagoda/p10/blob/main/misc/wavegen.py"
    click R2CSV "https://github.com/adam-lagoda/p10/blob/main/misc/r2/*.csv"
    click CNN "https://github.com/adam-lagoda/p10/blob/main/wave_prediction/wave_prediction_cnn.py"
    click LSTM "https://github.com/adam-lagoda/p10/blob/main/wave_prediction/wave_prediction_lstm.py"

    %% Styles
    classDef env fill:#D0E7FF,stroke:#1E70BF,color:#000
    classDef train fill:#D6F5D6,stroke:#28A828,color:#000
    classDef val fill:#FFE7C0,stroke:#E08E00,color:#000
    classDef analysis fill:#FFE7C0,stroke:#E08E00,color:#000
    classDef pred fill:#EAD1F7,stroke:#9E2EC8,color:#000
    classDef storage fill:#CCCCCC,stroke:#888888,color:#000
    classDef data fill:#FFFFFF,stroke:#444444,color:#000
```
