Add OSWEC PTO damping optimization application

[basaucier]

Summary

This draft PR adds an OSWEC PTO damping optimization application workflow.

The application connects buoy-derived wave resource characterization to WEC-Sim batch simulations in order to estimate an optimal constant passive PTO damping value for the OSWEC case.

The workflow includes:

• Python/MHKiT generation of representative wave conditions from NDBC buoy spectral data
• PacWave-style Gaussian Mixture Model clustering of wave conditions
• MATLAB/WEC-Sim batch simulations over representative sea states and PTO damping values
• Weighted and unweighted mean absorbed power analysis
• Frequency-domain theoretical damping-bound estimation using OSWEC pitch impedance

---

File Overview

File	Description
generate_wave_conditions.ipynb	Jupyter notebook that uses MHKiT to download NDBC spectral wave data, calculate wave quantities, cluster sea states, and export .mat files for MATLAB/WEC-Sim.
config_oswec_optimization.m	Central configuration file. Detects project folders and defines damping sweep, cleanup, and theoretical-bound settings.
make_oswec_batch.m	Creates all WEC-Sim simulation cases by combining representative wave conditions with PTO damping values.
run_oswec_batch.m	Runs WEC-Sim for each batch case, extracts PTO power, computes mean absorbed power, and saves run results.
analyze_oswec_results.m	Analyzes batch results, computes weighted/unweighted mean power, identifies optimal damping, and saves plots/CSV summaries.
estimate_oswec_damping_bounds.m	Computes theoretical PTO damping estimates using single-DOF OSWEC pitch impedance.
wave_conditions/	Stores representative wave-condition .mat files generated by the Python/MHKiT workflow.
runs/	Stores timestamped WEC-Sim batch run outputs.
damping_bounds/	Stores theoretical damping-bound outputs.

---

How to Run

Set Up MATLAB Path

Start MATLAB and navigate to the application folder:

cd('path/to/WEC-Sim_Applications/OSWEC_Optimization_Damping')

Typical Run Sequence

cd('path/to/WEC-Sim_Applications/OSWEC_Optimization_Damping')

estimate_oswec_damping_bounds   % optional
make_oswec_batch
run_oswec_batch
analyze_oswec_results

If not using theoretical bounds:

make_oswec_batch
run_oswec_batch
analyze_oswec_results

---

*For more see the comments in the code.

[akeeste]

Great work @basaucier! Some preliminary review comments included here. A few on some typical minor cleanup items and some on the workflow itself.

I recommend committing the various cluster results created in MHKiT for users. They should have the ipynb so that they can recreate results, but provide the precomputed clustered conditions as .mat files here ensures that this WEC-Sim workflow can be rerun easily without MHKiT.

Otherwise on the set-up files--these seem quite capable but first instinct is to pair them down a lot. They are quite long, which is mostly an issue for future understanding and maintenance by a broader team. Let's walk through the content in each and figure out what we need to keep

[akeeste]

remove file in favor of those in the _Common_Input_Files_ directory

[akeeste]

remove file in favor of those in the _Common_Input_Files_ directory

[akeeste]

remove file in favor of those in the _Common_Input_Files_ directory

[akeeste]

remove file in favor of those in the _Common_Input_Files_ directory

[akeeste]

remove file in favor of those in the _Common_Input_Files_ directory

[akeeste]

I suggest breaking up this notebook into a few section to make it easier to review, document, and rerun. Please also add a section like the last cell of PacWave notebook. This energy comparison between each set of clustered resource and that of the real conditions is what will guide the modeler on the number of clusters to use

[akeeste]

Convert to a function to avoid requiring the clc and clear calls up front.
This workflow seems to run fine, but there are some changes we can make to increase the usability by the typical WEC-Sim user:

I suggest using WEC-Sim's built in batch capabilities ("MCR"). In this way, you can have one input file that takes in pto(1).damping value and a wave condition case file simu.mcrMatFile. Then calling wecSimMCR will run all wave conditions with that damping. That also allows you to break out the batch simulation for a single PTO damping into it's own function.

Then the top level workflow can either iterate through those batch cases using a grid search. Or use a function of the form: average_power = wec_sim_batch_run(pto_damping) with a more complex optimization method.

See one of the MHKiT WEC-Sim examples for how the wave condition file can be formatted to pull directly into WEC-Sim.

[akeeste]

Remove plots or wrap in an if statement that checks whether this is a single simulation or a batch simulation (typically whether the variable 'mcr' is present or not)

[akeeste]

will these folder allow the model to rerun more quickly? They should not affect results over batch runs to my knowledge

[akeeste]

see readmes in other applications for an example format. This information is good, there are just a few other fields that we typically add