# rithikrn/wafowt-capy-wecsim architecture

> Architecture diagram of the GitHub repository rithikrn/wafowt-capy-wecsim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rithikrn/wafowt-capy-wecsim
- Repository: https://github.com/rithikrn/wafowt-capy-wecsim

## Overview

1. **Repository purpose**
   - This repo is a reproducible hydrodynamics workflow for an oscillating-water-column integrated floating offshore wind turbine platform.
   - It is organized as a staged pipeline that converts geometry into frequency-domain hydrodynamic coefficients, then into time-domain simulation inputs, and finally into WEC-Sim results.

2. **Top-level architectural boundary**
   - The repository is split into four functional subsystems that map directly to the pipeline:
     - `geometry/` for surface meshes and geometry inputs
     - `capytaine/` for Python-based boundary-element hydrodynamic solves
     - `hydroData/` for MATLAB BEMIO post-processing
     - `wecsim/` for Simulink/WEC-Sim time-domain simulation
   - These folders are not interchangeable; each one consumes the artifact produced by the previous stage.

3. **Stage 1: Geometry preparation**
   - `geometry/` contains STL/GDF meshes for the platform variants:
     - `base.stl` for the solid OC4 baseline
     - `hollow.stl` for the OWC-integrated platform
     - `owc.stl` and `lid.gdf` as supporting geometry assets
   - The meshes are the primary physical boundary definition for the hydrodynamic solver, and they are expected to be centered at the bodies’ center of gravity.

4. **Stage 2: Capytaine hydrodynamic solve**
   - `capytaine/` is the Python stage that runs linear potential-flow BEM calculations with Capytaine.
   - It produces NetCDF hydrodynamic datasets (`base.nc`, `hollow.nc`) plus hydrostatics files required downstream by BEMIO.
   - The shared helper `capytaine_call.py` centralizes common solver setup, while `wafowt_capy_base.py` and `wafowt_capy_hollow.py` are case-specific drivers.

5. **Case split inside the Python stage**
   - **Base case:** one rigid body, 6 DOF, representing the OC4 semisubmersible without OWC chambers.
   - **Hollow case:** four coupled bodies, 9 DOF total, where the platform shell is coupled with three piston-like chamber bodies.
   - This is the first major model boundary: the hollow case introduces body-to-body hydrodynamic coupling that must be preserved through later stages.

6. **Stage 3: BEMIO conversion**
   - `hydroData/` contains MATLAB scripts that transform Capytaine’s frequency-domain output into the time-domain data structures WEC-Sim expects.
   - `bemio_base.m` and `bemio_hollow.m` read the corresponding `.nc` files and generate `.h5` hydrodynamic datasets.
   - BEMIO is the bridge between the frequency-domain solver and the time-domain simulator; it computes radiation/excitation impulse response functions and a state-space realisation.

7. **Stage 4: WEC-Sim time-domain simulation**
   - `wecsim/` contains the Simulink models and the main MATLAB input script that configures each run.
   - `base.slx` and `hollow.slx` are the two simulation models, matched to the body count and coupling structure of the corresponding hydrodynamic file.
   - `wecSimInputFile.m` is the control point for case selection, mass/inertia settings, mooring settings, wave definition, and PTO setup.
   - `userDefinedFunctions.m` acts as the common post-processor that saves plots and optional animation outputs after each run.

8. **Shared data flow across the repository**
   - The core artifact flow is:
     - STL/GDF geometry in `geometry/`
     - Capytaine NetCDF and hydrostatics outputs in `capytaine/` or the case-specific hydro data directories
     - BEMIO-generated HDF5 in `hydroData/<case>/`
     - WEC-Sim simulation results and figures in `wecsim/results/`
   - This is a classic file-based pipeline, not a shared-library architecture; each stage is decoupled by on-disk artifacts.

9. **External toolchain boundaries**
   - Python and Capytaine handle the hydrodynamic BEM solve.
   - MATLAB and Simulink/WEC-Sim handle the time-domain dynamics.
   - BEMIO is MATLAB code bundled through WEC-Sim, so it lives at the MATLAB boundary rather than as a separate project dependency.
   - The repo itself does not vendor WEC-Sim; it assumes a separate WEC-Sim installation on the MATLAB path.

10. **Configuration and model variability**
   - The repo supports two preconfigured system variants with a shared methodology:
     - `base`: simpler single-body model
     - `hollow`: multi-body OWC model with PTOs
   - Geometry, mass properties, mooring stiffness, and PTO locations are the main parameters that must be aligned when porting the workflow to a different platform.
   - The Simulink model choice and the hydrodynamic file must always match the same case.

11. **Documentation as architecture support**
   - The `docs/` folder is not part of runtime execution, but it explains model assumptions, case trees, theory, and parameter choices.
   - It is useful for understanding why the pipeline is structured as it is, especially the body ordering, DOF mapping, and case-specific hydrodynamic assumptions.

12. **What an architecture diagram should emphasize**
   - Show a left-to-right, four-stage pipeline with two branches for `base` and `hollow`.
   - Highlight the three critical file interfaces: STL/GDF meshes, Capytaine `.nc` outputs, and WEC-Sim `.h5` inputs.
   - Mark the MATLAB/Python boundary explicitly, because the workflow crosses languages and runtimes.
   - Show that `wecsim/wecSimInputFile.m` is the central runtime selector for simulation behavior, while the case-specific Python and MATLAB scripts are the stage entry points.

Main entry points: [`capytaine/wafowt_capy_hollow.py`](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/capytaine/wafowt_capy_hollow.py) (Hollow solve), [`wecsim/wecSimInputFile.m`](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/wecsim/wecSimInputFile.m) (Run config), [`capytaine/wafowt_capy_base.py`](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/capytaine/wafowt_capy_base.py) (Base solve), [`wecsim/base.slx`](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/wecsim/base.slx) (Base sim)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_geometry["Geometry"]
  node_geom_base["Base mesh<br/>STL mesh<br/>[base.stl]"]
  node_geom_hollow["Hollow mesh<br/>STL mesh<br/>[hollow.stl]"]
  node_geom_owc["OWC mesh<br/>STL mesh<br/>[owc.stl]"]
  node_geom_lid["Lid mesh<br/>GDF mesh<br/>[lid.gdf]"]
end

subgraph group_python["Python / Capytaine"]
  node_capy_call["Solver setup<br/>Python helper<br/>[capytaine_call.py]"]
  node_capy_base["Base solve<br/>Python driver"]
  node_capy_hollow["Hollow solve<br/>Python driver"]
  node_nc_base["base.nc<br/>NetCDF output"]
  node_nc_hollow["hollow.nc<br/>NetCDF output"]
end

subgraph group_matlab["MATLAB / WEC-Sim"]
  node_bemio_base["BEMIO base<br/>MATLAB converter<br/>[bemio_base.m]"]
  node_bemio_hollow["BEMIO hollow<br/>MATLAB converter<br/>[bemio_hollow.m]"]
  node_h5_base["base.h5<br/>Hydro file"]
  node_h5_hollow["hollow.h5<br/>Hydro file"]
  node_input["Run config<br/>MATLAB input<br/>[wecSimInputFile.m]"]
  node_sim_base["Base sim<br/>Simulink model<br/>[base.slx]"]
  node_sim_hollow["Hollow sim<br/>Simulink model<br/>[hollow.slx]"]
  node_post["Post-process<br/>MATLAB helper"]
end

subgraph group_docs["Docs"]
  node_docs_main["Method docs<br/>Documentation<br/>[METHOD_THEORY.md]"]
end

node_geom_base -->|"mesh input"| node_capy_base
node_geom_hollow -->|"mesh input"| node_capy_hollow
node_geom_owc -->|"supporting geometry"| node_capy_hollow
node_geom_lid -->|"supporting geometry"| node_capy_hollow
node_capy_call -->|"shared setup"| node_capy_base
node_capy_call -->|"shared setup"| node_capy_hollow
node_capy_base -->|"solve"| node_nc_base
node_capy_hollow -->|"solve"| node_nc_hollow
node_nc_base -->|"BEMIO input"| node_bemio_base
node_nc_hollow -->|"BEMIO input"| node_bemio_hollow
node_bemio_base -->|"convert"| node_h5_base
node_bemio_hollow -->|"convert"| node_h5_hollow
node_h5_base -->|"hydro input"| node_sim_base
node_h5_hollow -->|"hydro input"| node_sim_hollow
node_input -->|"select case"| node_sim_base
node_input -->|"select case"| node_sim_hollow
node_sim_base -->|"results"| node_post
node_sim_hollow -->|"results"| node_post
node_docs_main -.->|"reference"| node_input
node_docs_main -.->|"reference"| node_capy_hollow

click node_geom_base "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/geometry/base.stl"
click node_geom_hollow "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/geometry/hollow.stl"
click node_geom_owc "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/geometry/owc.stl"
click node_geom_lid "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/geometry/lid.gdf"
click node_capy_call "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/capytaine/capytaine_call.py"
click node_capy_base "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/capytaine/wafowt_capy_base.py"
click node_capy_hollow "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/capytaine/wafowt_capy_hollow.py"
click node_bemio_base "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/hydroData/base/bemio_base.m"
click node_bemio_hollow "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/hydroData/hollow/bemio_hollow.m"
click node_input "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/wecsim/wecSimInputFile.m"
click node_sim_base "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/wecsim/base.slx"
click node_sim_hollow "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/wecsim/hollow.slx"
click node_post "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/wecsim/userDefinedFunctions.m"
click node_docs_main "https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/docs/METHOD_THEORY.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_geom_base,node_geom_hollow,node_geom_owc,node_geom_lid toneBlue
class node_capy_call,node_capy_base,node_capy_hollow,node_nc_base,node_nc_hollow toneAmber
class node_bemio_base,node_bemio_hollow,node_h5_base,node_h5_hollow,node_input,node_sim_base,node_sim_hollow,node_post toneMint
class node_docs_main toneRose
```

## Components

### Geometry

Surface meshes and supporting geometry inputs.

- [Base mesh](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/geometry/base.stl): STL mesh · Solid OC4 baseline surface mesh. · `geometry/base.stl`
- [Hollow mesh](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/geometry/hollow.stl): STL mesh · OWC-integrated platform surface mesh. · `geometry/hollow.stl`
- [OWC mesh](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/geometry/owc.stl): STL mesh · Supporting chamber geometry asset. · `geometry/owc.stl`
- [Lid mesh](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/geometry/lid.gdf): GDF mesh · Supporting lid geometry asset. · `geometry/lid.gdf`

### Python / Capytaine

Frequency-domain hydrodynamic boundary-element solves.

- [Solver setup](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/capytaine/capytaine_call.py): Python helper · Shared Capytaine solver configuration and orchestration. · `capytaine/capytaine_call.py`
- [Base solve](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/capytaine/wafowt_capy_base.py): Python driver · Capytaine driver for the 6-DOF base model. · `capytaine/wafowt_capy_base.py`
- [Hollow solve](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/capytaine/wafowt_capy_hollow.py): Python driver · Capytaine driver for the coupled hollow model. · `capytaine/wafowt_capy_hollow.py`
- **base.nc**: NetCDF output · Frequency-domain hydrodynamic results for the base case.
- **hollow.nc**: NetCDF output · Frequency-domain hydrodynamic results for the hollow case.

### MATLAB / WEC-Sim

BEMIO conversion and time-domain simulation.

- [BEMIO base](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/hydroData/base/bemio_base.m): MATLAB converter · Transforms base Capytaine output into WEC-Sim-ready data. · `hydroData/base/bemio_base.m`
- [BEMIO hollow](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/hydroData/hollow/bemio_hollow.m): MATLAB converter · Transforms hollow Capytaine output into WEC-Sim-ready data. · `hydroData/hollow/bemio_hollow.m`
- **base.h5**: Hydro file · WEC-Sim hydrodynamic dataset for the base case.
- **hollow.h5**: Hydro file · WEC-Sim hydrodynamic dataset for the hollow case.
- [Run config](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/wecsim/wecSimInputFile.m): MATLAB input · Central case selector and simulation parameter script. · `wecsim/wecSimInputFile.m`
- [Base sim](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/wecsim/base.slx): Simulink model · Time-domain model matched to the base hydrodynamics. · `wecsim/base.slx`
- [Hollow sim](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/wecsim/hollow.slx): Simulink model · Time-domain model matched to the hollow hydrodynamics. · `wecsim/hollow.slx`
- [Post-process](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/wecsim/userDefinedFunctions.m): MATLAB helper · Shared plotting, saving, and optional animation output. · `wecsim/userDefinedFunctions.m`

### Docs

Theory, parameter, and case-structure references.

- [Method docs](https://github.com/rithikrn/wafowt-capy-wecsim/blob/main/docs/METHOD_THEORY.md): Documentation · Theory, parameters, case tree, and design assumptions. · `docs/METHOD_THEORY.md`

## Connections

- Base mesh → Base solve: mesh input · Base geometry defines the boundary for the base solver run.
- Hollow mesh → Hollow solve: mesh input · Hollow geometry defines the coupled shell and chamber bodies.
- OWC mesh → Hollow solve: supporting geometry · Auxiliary OWC geometry used by the hollow case.
- Lid mesh → Hollow solve: supporting geometry · Auxiliary lid geometry used by the hollow case.
- Solver setup → Base solve: shared setup · Common solver configuration used by the base driver.
- Solver setup → Hollow solve: shared setup · Common solver configuration used by the hollow driver.
- Base solve → base.nc: solve · Base case frequency-domain hydrodynamic output.
- Hollow solve → hollow.nc: solve · Hollow case frequency-domain hydrodynamic output.
- base.nc → BEMIO base: BEMIO input · Capytaine NetCDF output consumed by the base converter.
- hollow.nc → BEMIO hollow: BEMIO input · Capytaine NetCDF output consumed by the hollow converter.
- BEMIO base → base.h5: convert · Generates the WEC-Sim hydrodynamic file for the base case.
- BEMIO hollow → hollow.h5: convert · Generates the WEC-Sim hydrodynamic file for the hollow case.
- base.h5 → Base sim: hydro input · Base Simulink model must match the base hydrodynamic dataset.
- hollow.h5 → Hollow sim: hydro input · Hollow Simulink model must match the hollow hydrodynamic dataset.
- Run config → Base sim: select case · Runtime settings configure the base simulation.
- Run config → Hollow sim: select case · Runtime settings configure the hollow simulation.
- Base sim → Post-process: results · Base run outputs are handled by the shared post-processor.
- Hollow sim → Post-process: results · Hollow run outputs are handled by the shared post-processor.
- Method docs → Run config: reference · Documentation explains parameter choices and case structure.
- Method docs → Hollow solve: reference · Docs capture the coupled-body assumptions for the hollow case.
