wec-sim-python

The four case badges partition 63 published input identities by model family. A gated case has full-duration independent Python motion or fixed-body force paired to MATLAB using either the unchanged published input or an explicitly adopted, repository-owned corrected validation baseline. 59/63 currently meet that standard. RM3 is 21/21 and OSWEC is 13/13. Corrected baselines cover RM3 End Stops at a copied-model ode45 MaxStep=0.025 s, RM3 MoorDyn visualization at copied-input simu.dt=0.0003125 s with a fixed phase seed, both RM3 PTO Extension free decays at copied-input simu.dt=0.00078125 s, OSWEC nonlinear visualization at copied-input simu.dt=0.0125 s, OSWEC passive yaw with a zero-degree coefficient hold threshold, and OSWEC irregular variable yaw with continuous heading interpolation. The unchanged published settings for those cases remain step-sensitive or unpaired by the physical Python default. The other published cases include OWC, WaveBot, WaveStar, Morison, and nonlinear hydrodynamics; see the parity ledger for the full breakdown. The MATLAB badge counts 42 selected source workflow jobs, not additional cases. Python tests reports CI; Test coverage measures Python line and branch execution. Neither is a WEC-Sim parity fraction.

A Python library for configuring and simulating wave energy converters, with paired checks against MATLAB WEC-Sim. This project builds on Sungjun Won's original WEC-Sim-Python work; his commits remain in the repository history.

This is a pre-alpha parity effort. Supported Sphere, RM3, OSWEC, barge, and selected application cases have MATLAB checks, but the library does not yet cover all WEC-Sim models or physics. The parity ledger records which results are independently paired and what remains open.

Install

Requires Python 3.12 or newer. Install from a clone:

python3 -m venv .venv
.venv/bin/python -m pip install -e .

Or install from GitHub:

python -m pip install "git+https://github.com/cmudrc/wec-sim-python.git"

Both methods provide the wecsim Python package and command. For Excel MCR workbooks or legacy wave plots, install the optional excel or plot extra, respectively (for example, pip install -e ".[excel]").

Quick start

from wecsim import NoWave, WEC, WorldPoint

wec = WEC("Heaving float")
body = wec.body("float", "path/to/hydro.h5")
wec.coordinate("heave", body.move("heave"))
wec.pto("main", body.at(0, 0, 0), WorldPoint(0, 0, 10), damping=1_200_000)

result = wec.run(NoWave(), dt=0.1, end_time=20,
                 radiation_memory=15, initial_coordinate={"heave": 1})
heave = result.bodies["float"].position[:, 2]
pto_force = result.ptos["main"].force

from wecsim import ... is the recommended import pattern. The WEC builder, configuration, and result types can also be imported from wecsim.interface. See the runnable two-body RM3 example for body-local PTO attachments and shared coordinates.

Documentation

• User guide: WEC configuration, wave inputs, PTOs, and application examples.
• Parity ledger: pinned MATLAB reference cases, evidence, and open gaps.
• Examples: runnable cases and bundled inputs.

The source is organized by role under wecsim/: interface, environment, hydrodynamics, dynamics, components, control, analysis, and visualization.

Tests and coverage

python -m pip install -e ".[test]"
python -m pytest -q --cov=wecsim --cov-branch --cov-report=term-missing

Python CI runs the suite on each push and pull request, summarizes line and branch coverage, verifies the displayed percentage, and uploads coverage.xml and coverage.json. Many MATLAB-dependent tests skip without their reference assets. Bundled RM3, OSWEC, and Sphere fixtures run in ordinary CI. Code coverage measures executed Python paths; the parity ledger measures agreement with WEC-Sim. The pinned MATLAB sweep counts jobs, not additional case files.

License

See LICENSE.