# Tutorials¶

This section provides step-by-step instructions on how to run the WEC-Sim code using the provided Tutorials (located in the WEC-Sim $Source/tutorials directory). Two WEC-Sim tutorials are provided: the Two-Body Point Absorber (RM3), and the Oscillating Surge WEC (OSWEC). For information about the implementation of the WEC-Sim code refer to the Code Structure section. For informational about additional WEC-Sim features, refer to the Advanced Features section. ## Two-Body Point Absorber (RM3)¶ This section describes the application of the WEC-Sim code to model the Reference Model 3 (RM3) two-body point absorber WEC. This example application is provided in the WEC-Sim code release in the $Source/tutorials directory.

### Device Geometry¶

The RM3 two-body point absorber WEC has been characterized both numerically and experimentally as a result of the DOE-funded Reference Model Project. The RM3 is a two-body point absorber consisting of a float and a reaction plate. Full-scale dimensions of the RM3 and its mass properties are shown below.

Float Full Scale Properties
CG (m) Mass (tonne) Moment of Inertia (kg-m^2)
0 727.01 20,907,301 0 0
0 0 21,306,091 4305
-0.72 0 4305 37,085,481
Plate Full Scale Properties
CG (m) Mass (tonne) Moment of Inertia (kg-m^2)
0 878.30 94,419,615 0 0
0 0 94,407,091 217,593
-21.29 0 217,593 28,542,225

### WEC-Sim Model Files¶

Below is an overview of the files required to run the RM3 simulation in WEC-Sim. For the RM3 WEC, there are two corresponding geometry files: float.stl and plate.stl. In addition to the required files listed below, users may supply a userDefinedFunctions.m file for post-processing results once the WEC-Sim run is complete.

 File Type File Name Directory Input File wecSimInputFile.m /tutorials/rm3/ Simulink Model rm3.slx /tutorials/rm3/ Hydrodynamic Data rm3.h5 /tutorials/rm3/hydroData/ Geometry Files float.stl & plate.stl /tutorials/rm3/geometry/

### Run Tutorial¶

Step 1: WEC-Sim Pre-Processing

Hydrodynamic data for each RM3 body must be parsed into a HDF5 file using the BEMIO hydrodynamic data format. The RM3 HDF5 file (rm3.h5) was created based on a WAMIT run of the RM3 geometry. The RM3 WAMIT rm3.out file and the BEMIO readWAMIT.py script were used to generate the HDF5 are included in the /hydroData directory.

Step 2: Build WEC-Sim model in Simulink

The WEC-Sim Simulink model is created by dragging and dropping blocks from the WEC-Sim Library into the rm3.slx file.

• Place two Rigid Body blocks from the WEC-Sim Library in the Simulink model file, one for each RM3 rigid body.
• Double click on the Rigid Body block, and rename each instance of the body. The first body must be called body(1), and the second body should be called body(2).
• Place the Global Reference Frame from the WEC-Sim Library in the Simulink model file. The global reference frame acts as the seabed.
• Place the Floating (3DOF) block to connect the plate to the seabed. This constrains the plate to move in 3DOF relative to the Global Reference Frame.
• Place the Translational PTO block to connect the float to the spar. This constrains the float to move in heave relative to the spar, and allows definition of PTO damping.

Note

When setting up a WEC-Sim model, it is very important to note the base and follower frames.

Step 3: Write WEC-Sim input file

The WEC-Sim input file defines simulation parameters, body properties, joints, and mooring for the RM3 model. The wecSimInputFile.m for the RM3 is provided in the RM3 case directory, and shown below.

wecSimInputFile for RM3

%% Simulation Data
simu = simulationClass();               % Initialize simulationClass
simu.simMechanicsFile = 'RM3.slx';      % Specify Simulink Model File
simu.startTime = 0;                     % Simulation Start Time [s]
simu.rampTime = 100;                   	% Wave Ramp Time [s]
simu.endTime=400;                       % Simulation End Time [s]
simu.dt = 0.1;                          % Simulation time-step [s]

%% Wave Information
% Regular Waves with convolution integtral calculation
waves = waveClass('regularCIC');        % Initialize waveClass and Specify Type
waves.H = 2.5;                          % Wave Height [m]
waves.T = 8;                            % Wave Period [s]

%% Body Data
% Float
body(1) = bodyClass('hydroData/rm3.h5');        % Initialize bodyClass for Float and Specify *.h5 data
body(1).geometryFile = 'geometry/float.stl';    % Geometry File
body(1).mass = 'equilibrium';                   % Displaced Water Mass [kg]
body(1).momOfInertia = [20907301 21306090.66 37085481.11];  % Moment of Inertia [kg*m^2]

% Spar/Plate
body(2) = bodyClass('hydroData/rm3.h5');        % Initialize bodyClass for Spar and Specify *.h5 data
body(2).geometryFile = 'geometry/plate.stl';    % Geometry File
body(2).mass = 'equilibrium';                   % Displaced Water Mass [kg]
body(2).momOfInertia = [94419614.57 94407091.24 28542224.82]; % Moment of Inertia [kg*m^2]

%% PTO and Constraint Parameters
% Floating (3DOF) Joint
constraint(1) = constraintClass('Constraint1'); % Initialize constraintClass for Constraint1
constraint(1).loc = [0 0 0];                    % Constraint Location [m]

% Translational PTO
pto(1) = ptoClass('PTO1');                      % Initialize ptoClass for PTO1
pto(1).k = 0;                                   % PTO Stiffness [N/m]
pto(1).c = 1200000;                             % PTO Damping [N/(m/s)]
pto(1).loc = [0 0 0];                           % PTO Location [m]


Step 4: Execute WEC-Sim

To execute the WEC-Sim code for the RM3 tutorial, type wecSim into the MATLAB Command Window. Below is a figure showing the final RM3 Simulink model and the WEC-Sim GUI during the simulation. For more information on using WEC-Sim to model the RM3 device, refer to [1].

Output and Post-processing

The RM3 example includes a userDefinedFunctions.m which plots RM3 forces and responses. This file can be modified by users for post-processing. Additionally, once the WEC-Sim run is complete, the WEC-Sim results are saved to the output variable in the MATLAB workspace.

Running Different Wave Cases

The input file for the RM3 tutorial includes several different wave cases:

• noWaveCIC - no wave with convolution integral calculation
• regularCIC - regular waves with convolution integral calculation
• irregular - irregular waves using a Pierson–Moskowitz spectrum with convolution integral calculation
• irregular - irregular waves using a Bretschneider Spectrum with state space calculation
• irregularImport - irregular waves using a user-defined spectrum
• userDefined - user-defined time-series

Note

If state space is used (simu.ssCalc=1), the user needs to make sure the state space hydrodynamic coefficients are included in the rm3.h5 file.

## Oscillating Surge WEC (OSWEC)¶

This section describes the application of the WEC-Sim code to model the Oscillating Surge WEC (OSWEC). This example application is provided in the WEC-Sim code release in the \$Source/tutorials directory.

### Device Geometry¶

The OSWEC was selected because its design is fundamentally different from the RM3. This is critical because WECs span an extensive design space, and it is important to model devices in WEC-Sim that operate under different principles. The OSWEC is fixed to the ground and has a flap that is connected through a hinge to the base that restricts the flap in order to pitch about the hinge. The full-scale dimensions of the OSWEC and the mass properties are shown in the figure and table below.

Flap Full Scale Properties
CG (m) Mass (kg) Pitch Moment of Inertia (kg-m^2)
0 127,000 1,850,000
0
-3.9

### WEC-Sim Model Files¶

Below is an overview of the files required to run the OSWEC simulation in WEC-Sim. For the OSWEC, there are two corresponding geometry files: flap.stl and base.stl. In addition to the required files listed below, users may supply a userDefinedFunctions.m file for post-processing results once the WEC-Sim run is complete.

 File Type File Name Directory Input File wecSimInputFile.m /tutorials/oswec/ Simulink Model oswec.slx /tutorials/oswec/ Hydrodynamic Data oswec.h5 /tutorials/oswec/hydroData/ Geometry Files flap.stl & base.stl /tutorials/oswec/geometry/

### Run Tutorial¶

Step 1: WEC-Sim Pre-Processing

Hydrodynamic data for each OSWEC body must be parsed into a HDF5 file using the BEMIO hydrodynamic data format. The OSWEC HDF5 file (oswec.h5) was created based on a WAMIT run of the RM3 geometry. The OSWEC WAMIT oswec.out file and the BEMIO readWAMIT.py script used to generate the HDF5 are included in the /hydroData directory.

Step 2: Build WEC-Sim model in Simulink

The WEC-Sim Simulink model is created by dragging and dropping blocks from the WEC-Sim Library into the oswec.slx file.

• Place two Rigid Body blocks from the WEC-Sim Library in the Simulink model file, one for each OSWEC rigid body.
• Double click on the Rigid Body block, and rename each instance of the body. The first body must be called body(1), and the second body should be called body(2).
• Place the Global Reference Frame from the WEC-Sim Library in the Simulink model file. The global reference frame acts as the seabed.
• Place the Fixed block to connect the base to the seabed. This constrains the base to be fixed relative to the Global Reference Frame.
• Place a Rotational PTO block to connect the base to the flap. This constrains the flap to move in pitch relative to the base, and allows definition of PTO damping.

Note

When setting up a WEC-Sim model, it is very important to note the base and follower frames.

Step 3: Write WEC-Sim input file

The WEC-Sim input file defines simulation parameters, body properties, joints, and mooring for the OSWEC model. The wecSimInputFile.m for the OSWEC is provided in the OSWEC case directory, and shown below.

wecSimInputFile.m for OSWEC

%% Simulation Data
simu = simulationClass();               % Initialize simulationClass
simu.simMechanicsFile = 'OSWEC.slx';    % Specify Simulink Model File
simu.startTime = 0;                     % Simulation Start Time [s]
simu.rampTime = 100;                    % Wave Ramp Time [s]
simu.endTime=400;                       % Simulation End Time [s]
simu.dt = 0.01;                         % Simulation Time-Step [s]
simu.CITime = 30;                       % Specify CI Time [s]

%% Wave Information
% Regular Waves
waves = waveClass('regular');           % Initialize waveClass and Specify Type
waves.H = 2.5;                          % Wave Height [m]
waves.T = 8;                            % Wave Period [s]

%% Body Data
% Flap
body(1) = bodyClass('hydroData/oswec.h5');      % Initialize bodyClass for Flap and Specify *.h5 data
body(1).geometryFile = 'geometry/flap.stl';     % Geometry File
body(1).mass = 127000;                          % User-Defined mass [kg]
body(1).momOfInertia = [1.85e6 1.85e6 1.85e6];  % Moment of Inertia [kg-m^2]

% Base
body(2) = bodyClass('hydroData/oswec.h5');      % Initialize bodyClass for Base
body(2).geometryFile = 'geometry/base.stl';     % Geometry File
body(2).mass = 'fixed';                         % Creates Fixed Body

%% PTO and Constraint Parameters
% Fixed
constraint(1)= constraintClass('Constraint1');  % Initialize constraintClass for Constraint1
constraint(1).loc = [0 0 -10];                  % Constraint Location [m]

% Rotational PTO
pto(1) = ptoClass('PTO1');                      % Initialize ptoClass for PTO1
pto(1).k = 0;                                   % PTO Stiffness [Nm/rad]
pto(1).c = 0;                                   % PTO Damping [Nsm/rad]
pto(1).loc = [0 0 -8.9];                        % PTO Location [m]


Step 4: Execute WEC-Sim

To execute the WEC-Sim code for the OSWEC tutorial, type wecSim into the MATLAB Command Window. Below is a figure showing the final OSWEC Simulink model and the WEC-Sim GUI during the simulation. For more information on using WEC-Sim to model the OSWEC device, refer to [2][3].

## Applications Repository¶

The WEC-Sim Applications repository contains applications of the WEC-Sim code, including tutorials by the WEC-Sim team as well as user-shared examples. The WEC-Sim Applications respository is included as a submodule of the WEC-Sim respository.

## References¶

 [1] K. Ruehl, C. Michelen, S. Kanner, M. Lawson, and Y. Yu. Preliminary Verification and Validation of WEC-Sim, an Open-Source Wave Energy Converter Design Tool. In Proceedings of OMAE 2014. San Francisco, CA, 2014.
 [2] Y. Yu, M. Lawson, K. Ruehl, and C. Michelen. Development and Demonstration of the WEC-Sim Wave Energy Converter Simulation Tool. In Proceedings of the 2nd Marine Energy Technology Symposium. Seattle, WA, USA, 2014.
 [3] Y. Yu, Y. Li, K. Hallett, and C. Hotimsky. Design and Analysis for a Floating Oscillating Surge Wave Energy Converter. In Proceedings of OMAE 2014. San Francisco, CA, 2014.