This sections provides an overview of the advanced features of the WEC-Sim code that were not covered in the WEC-Sim Tutorials section. Below is a doagram of some of the various WEC-Sim that can be used. This section provides information on how they can be turned on, and what they do.

## BEMIO¶

The Boundary Element Method Input/Output (BEMIO) functions are used to preprocess the BEM hydrodynamic data prior to running WEC-Sim, this includes:

• Read BEM results from WAMIT, NEMOH, or AQWA.
• Calculate the radiation and excitation impulse response functions (IRFs).
• Calculate state space realization coefficients for the radiation IRF.
• Save the resulting data in Hierarchical Data Format 5 (HDF5).
• Plot typical hydrodynamic data for user verification.

For more inforation, refer to the BEMIO tutorial section and the BEMIO webinar.

Note

Previously, the python based BEMIO code was used for this purpose. To avoid the inefficiencies associated with supporting two code platforms, the python BEMIO functions have been converted to MATLAB and will now be automatically downloaded with the WEC-Sim code. The python based BEMIO code will remain available but will no longer be actively supported. Also, the mesh manipulation capabilities of the python based BEMIO code have not yet been converted to MATLAB; however, it is intended that they will be in a future release.

### BEMIO Functions¶

• hydro – data structure
• filename – WAMIT output file
• ex_coeff - flag indicating the type of excitation force coefficients to read, ‘diffraction’ (default) or ‘haskind’

• hydro – data structure

• filedir – NEMOH working folder, must include:

• Nemoh.cal
• Mesh/Hydrostatics.dat (or Hydrostatiscs_0.dat, Hydrostatics_1.dat, etc. for multiple bodies)
• Mesh/KH.dat (or KH_0.dat, KH_1.dat, etc. for multiple bodies)
• Results/ExcitationForce.tec

Note

Instructions on how to download and use the open source BEM code NEMOH are provided on the NEMOH website. The NEMOH Mesh.exe code creates the Hydrostatics.dat and KH.dat files (among other files) for one input body at a time. For the Read_NEMOH function to work correctly in the case of a multiple body system, the user must manually rename Hydrostatics.dat and KH.dat files to Hydrostatics_0.dat, Hydrostatics_1.dat, …, and KH_0.dat, KH_1.dat,…, corresponding to the body order specified in the Nemoh.cal file.

• hydro – data structure
• ah1_filename – .AH1 AQWA output file
• lis_filename – .LIS AQWA output file

Normalize: Normalizes NEMOH and AQWA hydrodynamics coefficients in the same manner that WAMIT outputs are normalized. Specifically, the linear restoring stiffness is normalized as, $$C_{i,j}/\rho g$$; added mass is normalized as, $$A_{i,j}/\rho$$; radiation damping is normalized as, $$B_{i,j}/\rho \omega$$; and, exciting forces are normalized as, $$X_i/\rho g$$. Typically, this function would not be called directly by the user; it is automatically implemented within the Read_NEMOH and Read_AQWA functions.

hydro = Normalize(hydro)
• hydro – data structure

Combine_BEM: Combines multiple BEM outputs into one hydrodynamic “system”. This function requires that all BEM outputs have the same water depth, wave frequencies, and wave headings. This function would be implemented following multiple Read functions and before the IRF, Write_H5, or Plot_BEMIO functions.

hydro = Combine_BEM(hydro)
• hydro – data structure

$$\overline{K}_{i,j}(t) = {\frac{2}{\pi}}\intop_0^{\infty}{\frac{B_{i,j}(\omega)}{\rho}}\cos({\omega}t)d\omega$$

hydro = Radiation_IRF(hydro, t_end, n_t, n_w, w_min, w_max)
• hydro – data structure
• t_end – calculation range for the IRF, where the IRF is calculated from t = 0 to t_end, and the default is 100 s
• n_t – number of time steps in the IRF, the default is 1001
• n_w – number of frequency steps used in the IRF calculation (hydrodynamic coefficients are interpolated to correspond), the default is 1001
• w_min – minimum frequency to use in the IRF calculation, the default is the minimum frequency from the BEM data
• w_max – maximum frequency to use in the IRF calculation, the default is the maximum frequency from the BEM data.

Radiation_IRF_SS: Calculates the state space (SS) realization of the radiation IRF. If this function is used, it must be implemented after the Radiation_IRF function.

• hydro – data structure
• Omax – maximum order of the SS realization, the default is 10
• R2t$$R^2$$ threshold (coefficient of determination) for the SS realization, where $$R^2$$ may range from 0 to 1, and the default is 0.95

Excitation_IRF: Calculates the excitation impulse response function.

$$\overline{K}_i(t) = {\frac{1}{2\pi}}\intop_{-\infty}^{\infty}{\frac{X_i(\omega,\beta)e^{i{\omega}t}}{{\rho}g}}d\omega$$

hydro = Excitation_IRF(hydro, t_end, n_t, n_w, w_min, w_max)
• hydro – data structure
• t_end – calculation range for the IRF, where the IRF is calculated from t = -t_end to t_end, and the default is 100 s
• n_t – number of time steps in the IRF, the default is 1001
• n_w – number of frequency steps used in the IRF calculation (hydrodynamic coefficients are interpolated to correspond), the default is 1001
• w_min – minimum frequency to use in the IRF calculation, the default is the minimum frequency from the BEM data
• w_max – maximum frequency to use in the IRF calculation, the default is the maximum frequency from the BEM data.

Write_H5: Writes the hydro data structure to a *.h5 file.

Write_H5(hydro)
• hydro – data structure

Note

Technically, this step should not be necessary - the MATLAB data structure hydro is written to a *.h5 file by BEMIO and then read back into a new MATLAB data structure hydroData for each body by WEC-Sim. The reasons this step was retained were, first, to remain compatible with the python based BEMIO output and, second, for the simpler data visualization and verification capabilities offered by the *.h5 file viewer.

Plot_BEMIO: Plots the added mass, radiation damping, radiation IRF, excitation force magnitude, excitation force phase, and excitation IRF for each body in the heave, surge and pitch degrees of freedom.

Plot_BEMIO(hydro)
• hydro – data structure

Note

In the future, this will likely be changed to a userDefinedBEMIO.m function, similar to WEC-Sim’s userDefinedFunctions.m, such that users can interactively modify or plot any BEM hydrodynamic variable of interest.

### BEMIO hydro Data Structure¶

 Variable Format Description A [6*N,6*N,Nf] added mass Ainf [6*N,6*N] infinite frequency added mass B [6*N,6*N,Nf] radiation damping beta [1,Nh] wave headings (deg) body {1,N} body names C [6,6,N] hydrostatic restoring stiffness cb [3,N] center of buoyancy cg [3,N] center of gravity code string BEM code (WAMIT, AQWA, or NEMOH) ex_im [6*N,Nh,Nf] imaginary component of excitation ex_K [6*N,Nh,length(ex_t)] excitation IRF ex_ma [6*N,Nh,Nf] magnitude of excitation force ex_ph [6*N,Nh,Nf] phase of excitation force ex_re [6*N,Nh,Nf] real component of excitation ex_t [1,length(ex_t)] time steps in the excitation IRF ex_w [1,length(ex_w)] frequency step in the excitation IRF file string BEM output filename g [1,1] gravity h [1,1] water depth N [1,1] number of bodies Nf [1,1] number of wave frequencies Nh [1,1] number of wave headings ra_K [6*N,6*N,length(ra_t)] radiation IRF ra_t [1,length(ra_t)] time steps in the radiation IRF ra_w [1,length(ra_w)] frequency steps in the radiation IRF rho [1,1] density ss_A [6*N,6*N,ss_O,ss_O] state space A matrix ss_B [6*N,6*N,ss_O,1] state space B matrix ss_C [6*N,6*N,1,ss_O] state space C matrix ss_conv [6*N,6*N] state space convergence flag ss_D [6*N,6*N,1] state space D matrix ss_K [6*N,6*N,length(ra_t)] state space radiation IRF ss_O [6*N,6*N] state space order ss_R2 [6*N,6*N] state space R2 fit T [1,Nf] wave periods Vo [1,N] displaced volume w [1,Nf] wave frequencies

The BEMIO tutorials are included in the $Source/tutorials/BEMIO directory in the WEC-Sim source code. For more inforation, refer to the BEMIO webinar. ### Writing Your Own h5 File¶ The most common way of creating a *.h5 file is using BEMIO to post-process the outputs of a BEM code. This requires a single BEM solution that contains all hydrodynamic bodies and accounts for body interactions. Some cases in which you might want to create your own h5 file are: • Use experimentally determined coefficients or a mix of BEM and experimental coefficients. • Combine results from different BEM files and have the coefficient matrices be the correct size for the new total number of bodies. • Modify the BEM results for any other reason. MATLAB and Python have functions to read and write *.h5 files easily. WEC-Sim includes three functions to help you create your own *.h5 file. These are found under $Source/functions/writeH5/. The header comments of each function explain the inputs and outputs. An example of how to use write_hdf5 is provided in the WEC-Sim Applications repository. The first step is to have all the required coefficients and properties in Matlab in the correct format. Then the functions provided are used to create and populate the *.h5 file.

Note

The new *.h5 file will not have the impulse response function coefficients required for the convolution integral. BEMIO is currently being modified to allow for reading an existing *.h5 file. This would allow you to read in the *.h5 file you created, calculate the required impulse response functions and state space coefficients, and re-write the *.h5 file.

Note

BEMIO is currently being modified to allow for the combination of different *.h5 files into a single file. This would allow for the BEM of different bodies to be done separately, and BEMIO would take care of making the coefficient matrices the correct size.

## Body Features¶

### Body Mass and Geometry Features¶

The mass of each body must be specified in the WEC-Sim input file. The following features are available:

• Floating Body - the user may set body(i).mass = 'equilibrium' which will calculate the body mass based on displaced volume and water density. If simu.nlhydro = 0, then the mass is calculated using the dispaced volume contained in the *.h5 file. If simu.nlhydro = 1 or simu.nlhydro = 2, then the mass is calculated using the displaced volume of the provided STL geometry file.
• Fixed Body - if the mass is unknown (or not important to the dynamics), the user may specify body(i).mass = 'fixed' which will set the mass to 999 kg and moment of inertia to [999 999 999] kg-m^2.
• Import STL - to read in the geometry (stl) into Matlab use the body(i).bodyGeo method in the bodyClass. This method will import the mesh details (vertices, faces, normals, areas, centroids) into the body(i).bodyGeometry property. This method is also used for non-linear hydrodynamics and ParaView visualization files. Users can then visualize the geometry using the body(i).plotStl method.

### Non-Linear Hydrodynamics¶

WEC-Sim has the option to include the non-linear hydrostatic restoring and Froude-Krylov forces when solving the system dynamics of WECs, accounting for the weakly nonlinear effect on the body hydrodynamics. To use non-linear hydrodyanmics, the simu.nlHydro simulationClass variable must be defined in the WEC-Sim input file, for example:

simu.nlHydro = 2

For more information, refer to the non-linear hydrodynamics webinar, and the WEC-Sim Applications repository non-linear hydrodynamics example.

#### Non-Linear Settings¶

simu.nlHydro - The nonlinear hydrodynamics option can be used by setting simu.nlHydro = 2 or simu.nlHydro = 1 in your WEC-Sim input file. Typically, simu.nlHydro = 2 is recommended if nonlinear hydrodynamic effects need to be used. Note that simu.nlHydro = 1 only considers the nonlinear restoring and Froude-Krylov forces based on the body position and mean wave elevation.

simu.dtNL - An option available to reduce the nonlinear simulation time is to specify a nonlinear time step, simu.dtNL=N*simu.dt, where N is number of increment steps. The nonlinear time step specifies the interval at which the nonlinear hydrodynamic forces are calculated. As the ratio of the nonlinear to system time step increases, the computation time is reduced, again, at the expense of the simulation accuracy.

Note

WEC-Sim’s nonlinear hydrodynamic option may be used for regular or irregular waves but not with user-defined irregular waves.

#### STL File Generation¶

When the nonlinear option is turned on, the geometry file (*.stl) (previously only used for visualization purposes in linear simulations) is used as the discretized body surface on which the non-linear pressure forces are integrated. A good STL mesh resolution is required for the WEC body geometry file(s) when using the non-linear hydrodynamics in WEC-Sim. The simulation accuracy will increase with increased surface resolution (i.e. the number of discretized surface panels specified in the .stl file), but the computation time will also increase.

There are many ways to generate an STL file; however, it is important to verify the quality of the mesh before running WEC-Sim simulations with the non-linear hydro flag turned on. An STL file can be exported from from most CAD programs, but few allow adaquate mesh refinement. A good program to perform STL mesh refinement is Rhino3d. Some helpful resources explaining how to generate and refine an STL mesh in Rhino3d can be found here and here.

Note

All STL files must be saved as ASCII (not binary)

#### Non-Linear Tutorial - Heaving Ellipsoid¶

The body tested in the study is an ellipsoid with a cross- section characterized by semi-major and -minor axes of 5.0 m and 2.5 m in the wave propagation and normal directions, respectively . The ellipsoid is at its equilibrium position with its origin located at the mean water surface. The mass of the body is then set to 1.342×105 kg, and the center of gravity is located 2 m below the origin.

STL file with the discretized body surface is shown below (ellipsoid.stl)

The single-body heave only WEC model is shown below (nonLinearHydro.slx)

The WEC-Sim input file used to run the non-linear hydro WEC-Sim simulation:

%% Simulation Settings
simu = simulationClass();               %Create the Simulation Variable
simu.endTime=100;                       	% Simulation End Time [s]
simu.dt = 0.05;                              	% Simulation Delta_Time [s]
simu.simMechanicsFile = 'ellipsoid.slx';     	% Specify Simulink Model File
simu.rho=1025;
simu.mode='normal';
simu.explorer='on';                    % Turn SimMechanics Explorer on                                            % (on/off)
simu.CITime         = 30;
simu.rampT          = 50;
simu.nlHydro        = 2;		% Turns non-linear hydro on

% Wave Information
waves = waveClass('regular');           %Create the Wave Variable and Specify Type
waves.H = 4;                            % Wave Height [m]
waves.T = 6;                          	% Wave period [s]

%Body Data
body(1) = bodyClass('wamit/ellipsoid.h5');	% Initialize bodyClass for Float
body(1).mass = 'equilibrium';               	% Mass from WAMIT [kg]
body(1).momOfInertia = ...                  	% Moment of Inertia [kg-m^2]
[1.375264e6 1.375264e6 1.341721e6];
body(1).geometryFile = 'geometry/elipsoid.stl' ; 	% Discretized body geometry for nlHydro
body(1).viscDrag.cd=[1 0 1 0 1 0];
body(1).viscDrag.characteristicArea=[25 0 pi*5^2 0 pi*5^5 0];

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

pto(1) = ptoClass('PTO1');         	% Initialize ptoClass for PTO1
pto(1).k=0;                           	% PTO Stiffness Coeff [N/m]
pto(1).c=1200000;                     	% PTO Damping Coeff [Ns/m]
pto(1).loc = [0 0 -12.5];


Simulation and post-processing is the same process as described in Tutorials section.

### Non-Hydrodynamic Bodies¶

For some simulations, it might be important to model bodies that do not have hydrodynamic forces acting on them. This could be bodies that are completely outside of the water but are still connected through a joint to the WEC bodies, or it could be bodies deeply submerged to the point where the hydrodynamics may be neglected. WEC-Sim allows for bodies which have no hydrodynamic forces acting on them and for which no BEM data is provided.

To do this, use a Body Block from the WEC-Sim Library and initialize it in the WEC-Sim input file as any other body but leave the name of the h5 file as an empty string. Specify body(i).nhBody = 1; and specify body name, mass, moments of inertia, cg, geometry file, location, and displaced volume. You can also specify visualization options and initial displacement.

To use non-hydrodynamic bodies, the following bodyClass variable must be defined in the WEC-Sim input file, for example:

body(i).nhBody = 1

For more information, refer to the non-hydro bodies webinar, and the WEC-Sim Applications repository non-hydro body example.

### Body-To-Body Interactions¶

WEC-Sim allows for body-to-body interactions in the radiation force calculation, thus allowing the motion of one body to impart a force on all other bodies. The radiation matrices for each body (radiation damping and added mass) required by WEC-Sim and contained in the *.h5 file. For body-to-body interactions with N total hydrodynamic bodies, the *h5 data structure is [(6*N), 6].

When body-to-body interactions are used, the augmented [(6*N), 6] matrices are multiplied by concatenated velocity and acceleration vectors of all hydrodynamic bodies. For example, the radiation damping force for body(2) in a 3-body system with body-to-body interactions would be calculated as the product of a [1,18] velocity vector and a [18,6] radiation damping coefficients matrix.

To use body-to-body interactions, the following simulationClass variable must be defined in the WEC-Sim input file, for example:

simu.b2b = 1

For more information, refer to the B2B webinar, and the WEC-Sim Applications repository B2B example.

Note

By default, body-to-body interactions are off (simu.b2b = 0), and only the [1+6*(i-1):6*i, 1:6] sub-matrices are used for each body (where i is the body number).

## Wave Features¶

This section provides an overview of some features included in WEC-Sim’s wave implementation. For more information, refer to Wave Class.

### Irregular Wave Binning¶

The default frequency discretization for WEC-Sim is to use 1001 wave frequencies. This ensures that there are a sufficient number of bins to accurately generate teh desired sea state. However, this means that the hydrodynamic forces are calculated at every time-step for each of the 1001 frequency bins. In order to speed up the irregular wave simulation time, irregular sea states may now be generated using EqualEnergy bins.

To use equal energy bins, the following waveClass variable must be defined in the WEC-Sim input file:

waves.freqDisc = 'EqualEnergy';

### Wave Directionality¶

WEC-Sim has the ability to model waves with various angles of incidence. To define wave directionality in WEC-Sim, the following waveClass variable must be defined in the WEC-Sim input file:

waves.waveDir = 0;

The default incident wave direction has a heading of 0 (Default = 0), to change the heading waves.waveDir must be defined in [deg].

### Irregular Waves with Seeded Phase¶

In order to reproduce the same time-series every time an irregular wave simualtion is run, the following waveClass variable must be defined in the WEC-Sim input file:

waves.randPreDefined = 0;

By setting waves.randPreDefined equal to 1,2,3,...,etc, the random wave phase used by WEC-Sim is seeded, thus producing the same random value for each simulation.

## Simulation Features¶

### Multiple Condition Runs (MCR)¶

WEC-Sim allows users to perform batch runs by typing wecSimMCR into the MATLAB Command Window. This command executes the Multiple Condition Run (MCR) option, which can be initiated three different ways:

Option 1. Specify a range of sea states and PTO damping coefficients in the WEC-Sim input file, example: waves.H = 1:0.5:5; waves.T = 5:1:15; pto(1).k=1000:1000:10000; pto(1).c=1200000:1200000:3600000;

Option 2. Specify the excel filename that contains a set of wave statistic data in the WEC-Sim input file. This option is generally useful for power matrix generation, example: statisticsDataLoad = "<Excel file name>.xls"

Option 3. Provide a MCR case .mat file, and specify the filename in the WEC-Sim input file, example: simu.mcrCaseFile = "<File name>.mat"

For more information, refer to the MCR webinar, and the WEC-Sim Applications repository MCR example.

Note

For Multiple Condition Runs, the .h5 hydrodynamic data is only loaded once. To override this default (and reload the .h5 hydrodynamic data between runs), set simu.reloadH5Data =1 in the WEC-Sim input file.

### State-Space Representation¶

The convolution integral term in the equation of motion can be linearized using the state-space representation as described in the Theory Section. To use state-space representation, the simu.ssCalc simulationClass variable must be defined in the WEC-Sim input file, for example:

simu.ssCalc = 1

### Time-Step Features¶

The default WEC-Sim solver is ‘ode4’. Refer to the WEC-Sim Applications repository non-linear hydro example for a comparisons between ‘ode4’ to ‘ode45’.

#### Fixed Time-Step (ode4)¶

When running WEC-Sim with a fixed time-step, 100-200 time-steps per wave period is recommended to provide accurate hydrodynamic force calculations (ex: simu.dt = T/100, where T is wave periods). However, a smaller time-step may be required (such as when coupling WEC-Sim with MoorDyn or PTO-Sim). To reduce the required WEC-Sim simulation time, a different time-step may be specified for nonlinear hydrodynamics and for convolution integral calculations. For all simulations, the time-step should be chosen based on numerical stability and a convergence study should be performed.

The following variables may be changed in the simulationClass (where N is number of increment steps, default: N=1):

• Fixed time-step: simu.dt
• Output time-step: simu.dtOut
• Nonlinear hydrodynamics time-step: simu.dtFeNonlin=N*simu.dt
• Convolution integral time-step: simu.dtCITime=N*simu.dt

#### Variable Time-Step (ode45)¶

To run WEC-Sim with a variable time-step, the following variables must be defined in the simulationClass:

• Numerical solver: simu.solver='ode45'
• Max time-step: simu.dt

## Constraint and PTO Features¶

The default linear and rotational constraints and PTOs are allow for heave and pitch motions of the follower relative to the base. To obtain a linear or rotational constraint in a different direction you must modify the constraint’s or PTO’s coordinate orientation. The important thing to remember is that a linear constraint or PTO will always allow motion along the joint’s Z-axis, and a rotational constraint or PTO will allow rotation about the joint’s Y-axis. To obtain translation along or rotation about a different direction relative to the global frame, you must modify the orientation of the joint’s coordinate frame. This is done by setting the constraint’s or PTO’s orientation.z and orientation.y properties which specify the new direction of the Z- and Y- joint coordinates. The Z- and Y- directions must be perpendicular to each other.

As an example, if you want to constrain body 2 to surge motion relative to body 1 using a linear constraint, you would need the constraint’s Z-axis to point in the direction of the global surge (X) direction. This would be done by setting constraint(i).orientation.z=[1,0,0] and the Y-direction to any perpendicular direction (can be left as the default y=[0 1 0]). In this example, the Y-direction would only have an effect on the coordinate on which the constraint forces are reported but not on the dynamics of the system. Similarly if you want to obtain a yaw constraint you would use a rotational constraint and align the constraint’s Y-axis with the global Z-axis. This would be done by setting constraint(i).orientation.y=[0,0,1] and the z-direction to a perpendicular direction (say [0,-1,0]).

Additionally, by combining constraints and PTOs in series you can obtain different motion constraints. For example, a massless rigid rod between two bodies, hinged at each body, can be obtained by using a two rotational constraints in series, both rotating in pitch, but with different locations. A roll-pitch constraint can also be obtained with two rotational constraints in series; one rotating in pitch, and the other in roll, and both at the same location.

### Power Take-Off/PTO-Sim¶

PTO-Sim is the WEC-Sim module responsible for accurately modeling a WEC’s conversion of mechanical power to electrical power. While the PTO blocks native to WEC-Sim are modeled as a simple linear spring-damper systems, PTO-Sim is capable of modeling many power conversion chains (PCC) such as mechanical drivetrain and hydraulic drivetrain. PTO-Sim is made of native Simulink blocks coupled with WEC-Sim, using WEC-Sim’s user-defined PTO blocks, where the WEC-Sim response (relative displacement and velocity for linear motion and angular position and velocity for rotary motion) is the PTO-Sim input. Similarly, the PTO force or torque is the WEC-Sim input. For more information on how PTO-Sim works, refer to [So et al., 2015], and the PTO and Control webinar.

The files for the PTO-Sim tutorials described in this section can be found in the WEC-Sim Applications repository.

#### Tutorial: RM3 with PTO-Sim¶

This section describes how to use RM3 with PTO-Sim. Two tutorials will be given in this section: one for the RM3 with a hydraulic PTO (non-compressible and compressible) and another for the RM3 with a direct drive PTO.

##### RM3 with Hydraulic PTO¶

The hydraulic PTO example used in this section consists of a piston, a rectifying valve, a high pressure accumulator, a hydraulic motor coupled to a rotary generator, and a low pressure accumulator.

There are two ways of modeling the hydraulic PTO: with a compressible fluid hydraulic, and with a non-compressible fluid hydraulic. The compressible fluid model uses the properties of fluid such as an effective bulk modulus and density while the non-compressible fluid does not.

In this section, a step by step tutorial on how to set up and run the RM3 simulation with PTO-Sim is provided. All the files used in WEC-Sim will remain the same. An additional file that is needed is the PTO-Sim input file (ptoSimInputFile.m). If the rotary generator lookup table is used, a datasheet that contains generator efficiency, torque, and angular velocity is needed and should be named as table in Workspace (table.eff, table.Tpu,and table.omegapu). More details, refer to Step 8. In summary, the files need to run RM3 with PTO-Sim case are the following:

• WEC-Sim input file: wecSimInputFile.m (make sure to set the PTO linear damping to zero)
• Simulink model: RM3.slx
• Geometry file for each body: float.stl and plate.stl
• Hydrodynamic data file(s): rm3.h5
• Optional user defined postprocessing file: userDefinedFunction.m
• PTO-Sim input file: ptoSimInputFile.m
• Datasheet for the rotary generator: table (table.eff, table.Tpu,and table.omegapu)
• For the hydraulic PTOs: variableMotorVolume.m

• Step 1: Navigate to the RM3 tutorial $Source/tutorals/RM3. • Step 2: Open RM3.slx file and replace Translational PTO (local Z) with Translational PTO UD Force (Local Z). • Step 3: Use a subsystem and rename it to PTO-Sim where input is response and output is force. • Step 4: Go inside PTO-Sim block and add one bus selector and two selector blocks. Since PTO-Sim block is connected to the WEC-Sim translational joint block, you can select position and velocity and therefore “signal1” and “signal2” will change to “position” and “velocity”. Because the heave motion is driving the piston, selection index of each selector needs to be changed to 3. • Step 5: Go to Simulink Library Browser to access PTO-Sim Library. • Step 6: By looking at the physical hydraulic PTO model as shown above, user can simply drag and drop PTO-Sim library blocks. Piston, valves, accummulator blocks are located under Hydraulic block. Rotary generator lookup table is under Generator block. • Step 7: Since two accumulators are needed for the high pressure accumulator and low pressure accumulator, user need to douple-click on each block and give a number to each accumulator. For example, ptosim.accumulator(1) is called high pressure accumulator and ptosim.accumulator(2) is called low pressure accumulator. • Step 8: If a rotary generator lookup table is used, this block assumes user will provide the datasheet. After the datasheet is loaded into Workspace, it needs to be named as table because the word table is used inside Simulink lookup table block. The datasheet in tutorials is taken from ABB datasheet part number M3BJ315SMC. The lookup table takes three inputs: efficiency (table.eff), anglular velocity (table.Tpu), and generator torque (table.omegapu), respectively. • Step 9: After the high pressure and low pressure accumulators have been identified, and the rotary generator lookup table datasheet has been setup, all the blocks can be connected together. Position and velocity from selectors are used as inputs of compressible fluid piston. This block also needs to know top and bottom volumetric flows which come from the rectifying check valve. The piston then outputs PTO force that will be used by WEC-Sim. Two other outputs are the piston pressures. The rectifying check valve takes both the pressures from the piston and accumulators. Both high and low pressure accumulators takes the volumetric flows from the rectifying check valve and hydraulic motor. The hydraulic motor uses the knowledge of the pressures from both accumulator and generator torque from the rotary generator. The rotary generator needs angular velocity from the hydraulic motor. The figure below shows how to connect all the blocks together. Input File In this section, PTO-Sim input file (ptoSimInputFile.m) is defined and categorized into sections such as piston, rectifying check valve, high pressure accumulator, hydraulic motor, low pressure accumulator, and rotary generator. Simulation and Postprocessing Simulation and postprocessing are the same process as described in WEC-Sim Simulation example above. ##### RM3 with Direct Drive PTO¶ A mechanical PTO is used in this example and is modeled as a direct drive linear generator. The main components of this example consist of magnets and a coil where the magnet assembly is attached to the heaving float and the coil is locacted inside the spar. As the float moves up and down, the magnet assembly creates a change in the magnetic field surrounding the spar that contains the coil: therefore, current is induced in the coil and electricity is generated. Simulink Model Step 1 through 3 are the same as in RM3 with hydraulic PTO. • Step 4: Go inside PTO-Sim block and add one bus selector and one selector blocks. Only velocity is needed for this example. • Step 5: Go to PTO-Sim library. • Step 6: By looking at the physical mechanical PTO model as shown above, the user can simply drag and drop PTO-Sim library blocks. In this case, only the direct drive linear generator is needed, and it is located under generator box. • Step 7: Simply connect velocity from the selector to the input of the direct drive linear generator. The ouput PTO force is fed back to WEC-Sim. Input File, Simulation, and Postprocessing The same as RM3 with hydraulic PTO. #### Tutorial: OSWEC with PTO-Sim¶ This section describes how to use OSWEC with PTO-Sim. The same process as described in RM3 with PTO-Sim ; however, since OSWEC is a rotary device, it takes torque as an input and a rotary to linear motion conversion block is needed. The tutorials can be found on the WEC-Sim Applications repository (both for a crank and for a rod). ##### OSWEC with Hydraulic PTO¶ A hydraulic PTO or mechanical PTO can be used with OSWEC but for simplicity a hydraulic PTO will be used as an example. Modeling of OSWEC with Hydraulic PTO The same as RM3 with hydraulic PTO. Simulink Model The Simulink model can be built as following: • Step 1: Copy OSWEC tutorial folder to get started $Source\tutorials\OSWEC.
• Step 2: Open OSWEC.slx file and replace Rotary PTO (Local RY) with Rotational PTO UD Torque (Local RY).
• Step 3: Use a subsystem and rename it to PTO-Sim where input is response and output is torque.
• Step 4: Go inside PTO-Sim block and drag and drop one bus selector and two selector blocks. Since pitch is driving the piston, selection index of each selector needs to be changed to 5. Next, go to PTO-Sim library and drag and drop all the blocks for the hydraulic PTO. The rotary to linear adjustable rod block can be found under rotary to linear conversion box.
• Step 5: The rotary to linear adjustable rod block takes angular position and velocity from index selector blocks and PTO force from compressible fluid piston block. The outputs of the rotary to linear adjustable rod block are linear position, velocity, and torque. Linear position and velocity are used as inputs for compressible fluid piston and torque is fed back to WEC-Sim. The rest of the connects are the same as in RM3 with hydraulic PTO. The user is encouraged to go up one level to check the connections between PTO-Sim and WEC-Sim.

Input File, Simulation, and Postprocessing The same as RM3 with hydraulic PTO.

#### Other PTO-Sim Tutorials¶

Other PTO-Sim tutorials that were not discussed above can be found on the WEC-Sim Applications repository.

 PTO-Sim Application Description RM3_Hydraulic_PTO RM3 with hydraulic PTO RM3_cHydraulic_PTO RM3 with compressible hydraulic PTO RM3_DD_PTO RM3 with direct drive linear generator OSWEC_Hydraulic_PTO OSWEC with hydraulic PTO (adjustable rod) OSWEC_Hydraulic_Crank_PTO OSWEC with hydraulic PTO (crank)

## Mooring Features¶

Floating WEC systems are often connected to mooring lines to keep the device in position. WEC-Sim allows the user to model the mooring dynamics in the simulation by specifying the mooring matrix or coupling with MoorDyn. To include mooring connections, the user can use the mooring block (i.e., Mooring Matrix block or MoorDyn block) given in the WEC-Sim library under Moorings lib and connect it between the body and the Global reference frame. Refer the MoorDyn Tutorial section, and the Mooring Webinar for more information.

MoorDyn is hosted on a seperate MoorDyn repository. It must be download seperately, and all files and folders should be placed in the \$Source/functions/moorDyn directory.

### Mooring Matrix¶

When the mooring matrix block is used, the user first needs to initiate the mooring class by setting mooring(i) = mooringClass('mooring name') in the WEC-Sim input file (wecSimInputFile.m). Typically, the mooring connection location also need to be specified, mooring(i).ref = [1x3] (the default connection location is [0 0 0]). The user can also define the mooring matrix properties in the WEC-Sim input file using:

• Mooring stiffness matrix - mooring(i).matrix.k = [6x6]

• Mooring damping matrix - mooring(i).matrix.c = [6x6]

• Mooring pretension - mooring(i).matrix.preTension = [1x6]

### MoorDyn¶

When the MoorDyn block is used, the user needs to initiate the mooring class by setting mooring = mooringClass('mooring name') in the WEC-Sim input file (wecSimInputFile.m), followed by number of mooring lines is defined in MoorDyn (mooring(1).moorDynLines = <Number of mooring lines>)

A mooring folder that includes a moorDyn input file (lines.txt) is required in the simulation folder.

#### Tutorial: RM3 with MoorDyn¶

This section describes how to simulate a mooring connected WEC system in WEC-Sim using MoorDyn. The RM3 two-body floating point absorber is connected to a three-point catenary mooring system with an angle of 120 between the lines in this example case. The RM3 with MoorDyn folder is located under WEC-Sim Applications repository.

• WEC-Sim Simulink Model: Start out by following the instructions on how to model the RM3 Two-Body Point Absorber. To couple WEC-Sim with MoorDyn, the MoorDyn Block is added in parallel to the constraint block
• WEC-Sim Input File: In the wecSimInputFile.m file, the user need to initiate the mooring class and define the number of mooring lines.
%% Simulation Data
simu = simulationClass();               %Create the Simulation Variable
simu.simMechanicsFile = 'RM3MoorDyn.slx';      %Location of Simulink Model File
simu.endTime=400;                       %Simulation End Time [s]
simu.dt = 0.01;                          %Simulation Time-Step [s]
simu.rampT = 40;                        %Wave Ramp Time Length [s]
simu.mode='accelerator';
simu.explorer = 'off';
simu.dtCITime = 0.05;
%simu.paraview = 1;

%% Wave Information
%% User-Defined Time-Series
waves = waveClass('userDefined');   %Create the Wave Variable and Specify Type
waves.etaDataFile = 'umpqua46229_6_2008.mat';  % Name of User-Defined Time-Series File [:,2] = [time, wave_elev]

%% Body Data
body(1) = bodyClass('hydroData/rm3.h5');
body(1).mass = 'equilibrium';
body(1).momOfInertia = [20907301 21306090.66 37085481.11];
body(1).geometryFile = 'geometry/float.stl';    %Location of Geomtry File

body(2) = bodyClass('hydroData/rm3.h5');
body(2).mass = 'equilibrium';
body(2).momOfInertia = [94419614.57 94407091.24 28542224.82];
body(2).geometryFile = 'geometry/plate.stl';
body(2).initDisp.initLinDisp = [0 0 -0.21];

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

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

mooring(1) = mooringClass('mooring');
mooring(1).moorDynLines = 6;
mooring(1).moorDynNodes(1:3) = 16;
mooring(1).moorDynNodes(4:6) = 6;
mooring(1).initDisp.initLinDisp = [0 0 -0.21];

• MoorDyn Input File: A mooring folder that includes a moorDyn input file (lines.txt) is created. The moorDyn input file (lines.txt) is shown in the figure below. More details on how to setup the MooDyn input file were described in the MoorDyn User Guide [1].
• Simulation and Postprocessing: Simulation and postprocessing are the same process as described in Tutorial Section.

Note

You may need to install the MinGW-w64 compiler to run this simulation.

## Visualization/Paraview¶

This section describes how to setup, output, and use Paraview files for visualizing a WEC-Sim simulation. For more information about using Paraview for visualization, refer to the visualization webinar, and the WEC-Sim Applications repository.

Using Paraview visualization improves on SimMechanics’s explorer by:

• Visualization of the wave field
• Visualization of the cell-by-cell non-linear hydrodynamic forces (when using non-linear hydro)
• Allow data manipulation and more visualization options

On the other hand the SimMechanics explorer shows the following information not shown in Paraview vizualition:

• Location of the center of gravity
• Location of the different frames including PTO and Constraint frames

Visualization with paraview requires many files to be written, which makes the WEC-Sim simulation take significantly more time, and makes the directory significantly larger. It should only be turned on when vizualisation is desired. The user also needs to have some familiarity with using Paraview.

### Getting Started - Installation¶

You will need to install Paraview and install and setup Python. Next you will need to add some WEC-Sim specific macros,as follows:

• Open Paraview
• Click on Macros => Add new macro
• Navigate to the WEC-Sim source/functions/paraview_macros directory
• Select the first file and click OK
• Repeat this for all files in the paraview_macros directory.

### Setting Up Paraview Output¶

The following table shows the variables that can be specfied in the wecSimInputFile to control the Paraview visualization. The body.viz properties are also used in the SimMechanics explorer visualization.
WEC-Sim Visualization using Paraview
Variable Description
simu.paraview 0 to not ouput Paraview files [default] 1 to output Paraview files
simu.nlHydro 0 for no non-linear hydro [default] 1 for non-linear hydro with mean free surface 2 for non-linear hydro with instantaneous fs
simu.domainSize size of ground and water planes in meters [default 200]
simu.dtOut simulation output sampling time step [default dt]
body(i).viz.color [RGB] body color [default [1 1 0]]
body(i).viz.opacity body opacity [default 1]
waves.viz.numPointsX wave plane discretization: number of X points [default 50]
waves.viz.numPointsY wave plane discretization: number of Y points [default 50]

### Outputs and Opening in Paraview¶

When simu.paraview is set to 1, a directory called vtk is created. All files necessary for Paraview vizualisation are located there. To view in Paraview:

• Open the vtk/filename.pvd file in Paraview
• Click Apply
• With the model selected in the pipeline, run the WEC-Sim macro
• Move the camera to desired view
• Click the green arrow (play) button

The WEC-Sim macro:

• Extracts each body, sets the color and opacity, and renames them
• Extracts the waves, sets color and opacity, and renames
• Creates the ground plane
• Sets the camera to parallel view

### Basic Visualization Manipulation¶

After opening the .pvd file and running the WEC-Sim macro you can do a number of things to visualize the simulation in different ways. You can color waves and bodies by any of the available properties and apply any of the Paraview filters.

The video below shows three different views of the OSWEC model described in the tutorials. On the bottom right view the wave elevation is used to color the free surface. The top right view uses the slice filter.

### Visualizing Non-Linear Hydro Forces¶

When using non-linear hydro the paraview files also contain cell data for the bodies. The cell data are:

• Cell areas
• Hydrostatic pressures
• Linear Froude-Krylov pressures
• Non-linear Froude-Krylov pressures

The pressureGlyphs macro calculates cell normals, and cell centers. It then creates the following glyphs:

• Hydrostatic Pressure
• Linear Froude-Krylov pressure
• Non-linear Froude-Krylov pressure
• Total pressure (hydostatic plus non-linear Foude-Krylov)
• Froude-Krylov delta (non-linear minus linear)

The video below shows three different views of the RM3 model described in the turoeials. The top right shows glyphs of the non-linear Froude-Krylov pressure acting on the float. The bottom right shows the float colored by hydrostatic pressure.

## Decay Tests¶

When performing simulations of decay tests, you must use one of the no-wave cases and setup the initial (time = 0) location of each body, constraint, PTO, and mooring block. The initial location of a body or mooring block is set by specifying the CG or location at the stability position (as with any WEC-Sim simulation) and then specifying an initial displacement. To specify an initial displacement, the body and mooring blocks have a .initDisp property with which you can specify a translation and angular rotation about an arbitrary axis. For the constraint and PTO blocks, the .loc property must be set to the location at time = 0.

There are methods available to help setup this initial displacement for all bodies, constraints, PTOs, and moorings. To do this, you would use the body(i).setInitDisp(...);, constraint(i).setInitDisp(...), pto(i).setInitDisp(...), and mooring(i).setInitDisp(...) method in the WEC-Sim input file. A description of the required input can be found in the method’s header comments. Note that body(i).cg, constraint(i).loc, pto(i).loc, and mooring.ref must be defined prior to using the object’s .setInitDisp method.