How rithikrn/wafowt-capy-wecsim works
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: wafowt_capy_hollow.py Hollow solve · wecSimInputFile.m Run config · wafowt_capy_base.py Base solve · base.slx Base sim
Components 18
Geometry
Surface meshes and supporting geometry inputs.
- Base mesh · Solid OC4 baseline surface mesh.
geometry/base.stl - Hollow mesh · OWC-integrated platform surface mesh.
geometry/hollow.stl - OWC mesh · Supporting chamber geometry asset.
geometry/owc.stl - Lid mesh · Supporting lid geometry asset.
geometry/lid.gdf
Python / Capytaine
Frequency-domain hydrodynamic boundary-element solves.
- Solver setup · Shared Capytaine solver configuration and orchestration.
capytaine/capytaine_call.py - Base solve · Capytaine driver for the 6-DOF base model.
capytaine/wafowt_capy_base.py - Hollow solve · Capytaine driver for the coupled hollow model.
capytaine/wafowt_capy_hollow.py - base.nc · Frequency-domain hydrodynamic results for the base case.
- hollow.nc · Frequency-domain hydrodynamic results for the hollow case.
MATLAB / WEC-Sim
BEMIO conversion and time-domain simulation.
- BEMIO base · Transforms base Capytaine output into WEC-Sim-ready data.
hydroData/base/bemio_base.m - BEMIO hollow · Transforms hollow Capytaine output into WEC-Sim-ready data.
hydroData/hollow/bemio_hollow.m - base.h5 · WEC-Sim hydrodynamic dataset for the base case.
- hollow.h5 · WEC-Sim hydrodynamic dataset for the hollow case.
- Run config · Central case selector and simulation parameter script.
wecsim/wecSimInputFile.m - Base sim · Time-domain model matched to the base hydrodynamics.
wecsim/base.slx - Hollow sim · Time-domain model matched to the hollow hydrodynamics.
wecsim/hollow.slx - Post-process · Shared plotting, saving, and optional animation output.
wecsim/userDefinedFunctions.m
Docs
Theory, parameter, and case-structure references.
- Method docs · Theory, parameters, case tree, and design assumptions.
docs/METHOD_THEORY.md
Connections 20
- 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.