# bdvanberkel/wakewise architecture

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

- Interactive diagram: https://gitdiagram.com/bdvanberkel/wakewise
- Repository: https://github.com/bdvanberkel/wakewise

## Overview

##### Project type and purpose
- Project type: A Python‐based simulation environment implementing the Gymnasium API for reinforcement learning in wind‐farm control.
- Purpose: To simulate wake steering in wind farms using a Graph Neural Network surrogate, model fatigue degradation & maintenance costs, and sample realistic wind and electricity price conditions.

##### File structure
- Top‐level entry points:
– run.py (CLI or script to launch experiments)
– WakeWISE/main.py (defines the Gym environment class and simulation loop)
- Modules & directories:
– PropagationModels: GNN surrogate + farm simulation logic
– WindSamplers: Markov‐chain wind direction/speed sampler
– DegradationModels & MaintenanceModels: fatigue damage & cost models
– utils: config loader, logging, data handling, graph conversion, normalization
– wrappers: Gym wrappers that modify observation/action spaces or rewards
- Data/config folders:
– configs/*.yaml – environment and degradation parameters
– data/* – wind‐farm layouts, spot‐price matrices, pretrained models
- Dependencies: pyproject.toml, Gymnasium API, PyTorch (GNN models)

##### README for additional insights
- Core loop: at each 10‐minute timestep, sample wind & price, run GNN surrogate to get power & DELs, update fatigue, compute maintenance cost, and produce reward for RL agent.
- Wrappers exist to tweak observability, normalization, baseline subtraction, graph encoding, etc.

##### Final checklist
– Include all major components listed above
– Annotate where external data (layouts, price matrices, model weights) is loaded
– Show the wrapper stack around the base environment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data and Configuration Layer
    subgraph "Data & Config Stores"
        direction TB
        ConfigLoader["Configuration Loader"]:::config
        DataStores["Data Stores"]:::data
    end

    %% Sampling Layer
    subgraph "Sampling Layer"
        direction TB
        WindSampler["Wind Sampler"]:::sampling
        PriceSampler["Electricity Price Sampler"]:::sampling
    end

    %% Physics Surrogate Layer
    subgraph "Surrogate Physics Layer"
        direction TB
        GNNSurrogate["GNN Surrogate"]:::physics
        FarmSim["Farm Simulation Logic"]:::physics
    end

    %% Degradation & Maintenance Layer
    subgraph "Cost Layer"
        direction TB
        Degradation["Degradation Models"]:::cost
        Maintenance["Maintenance Models"]:::cost
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        Utils["Utilities"]:::utils
    end

    %% Environment Core & Wrappers
    subgraph "Environment & Wrappers"
        direction TB
        CoreEnv["Environment Core (Gym API)"]:::core
        subgraph "Wrapper Chain"
            direction TB
            GraphObs["GraphObservationWrapper"]:::wrapper
            NormWrap["NormalisationWrapper"]:::wrapper
            ScaleWrap["ScaleRewardsWrapper"]:::wrapper
        end
    end

    %% Connections
    CoreEnv -->|loads parameters| ConfigLoader
    CoreEnv -->|reads data| DataStores

    ConfigLoader --> WindSampler
    ConfigLoader --> PriceSampler
    ConfigLoader --> GNNSurrogate
    ConfigLoader --> Degradation
    ConfigLoader --> Maintenance

    DataStores --> WindSampler
    DataStores --> PriceSampler
    DataStores --> GNNSurrogate

    WindSampler --> GNNSurrogate
    PriceSampler --> Maintenance

    GNNSurrogate --> FarmSim
    FarmSim --> Degradation

    Degradation --> Maintenance

    CoreEnv -->|"step() loop"| WindSampler
    CoreEnv -->|"step() loop"| PriceSampler
    CoreEnv -->|"step() loop"| GNNSurrogate
    CoreEnv -->|"receives outputs"| Degradation
    CoreEnv -->|"computes cost"| Maintenance
    CoreEnv -->|"reward = revenue - cost"| CoreEnv

    CoreEnv --- GraphObs
    GraphObs --- NormWrap
    NormWrap --- ScaleWrap
    ScaleWrap --> CoreEnv

    %% Utilities connections
    Utils --> CoreEnv
    Utils --> GNNSurrogate
    Utils --> FarmSim
    Utils --> Degradation
    Utils --> Maintenance

    %% Click Events
    click CoreEnv "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/main.py"
    click ConfigLoader "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/utils/ConfigLoader.py"
    click WindSampler "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/WindSamplers/WindSampler.py"
    click PriceSampler "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/utils/RateModel.py"
    click GNNSurrogate "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/PropagationModels/Surrogates.py"
    click FarmSim "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/PropagationModels/FarmSimulation.py"
    click Degradation "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/DegradationModels/Deterministic.py"
    click Degradation "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/DegradationModels/Stochastic.py"
    click Maintenance "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/MaintenanceModels/DenseCosts.py"
    click Maintenance "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/MaintenanceModels/SparseCosts.py"
    click Maintenance "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/MaintenanceModels/MaintenanceModel.py"
    click DataStores "https://github.com/bdvanberkel/wakewise/tree/main/WakeWISE/data/WindFarmLayouts/"
    click DataStores "https://github.com/bdvanberkel/wakewise/tree/main/WakeWISE/data/SpotPrices/"
    click DataStores "https://github.com/bdvanberkel/wakewise/tree/main/WakeWISE/PropagationModels/utils/Models/"
    click GraphObs "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/wrappers/GraphObservationWrapper.py"
    click NormWrap "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/wrappers/NormalisationWrapper.py"
    click ScaleWrap "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/wrappers/ScaleRewardsWrapper.py"
    click Utils "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/utils/normalizer.py"
    click Utils "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/utils/logger.py"
    click Utils "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/utils/time.py"
    click Utils "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/utils/WindFarmUtils/CoordinatesToGraph.py"
    click Utils "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/utils/WindFarmUtils/LayoutGenerator.py"
    click Utils "https://github.com/bdvanberkel/wakewise/blob/main/WakeWISE/utils/DataLoggers.py"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef wrapper fill:#87CEFA,stroke:#000,stroke-width:1px
    classDef sampling fill:#98FB98,stroke:#000,stroke-width:1px
    classDef physics fill:#FFA500,stroke:#000,stroke-width:1px
    classDef cost fill:#FA8072,stroke:#000,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef utils fill:#D3D3D3,stroke:#000,stroke-width:1px
```
