The advanced features documentation provides an overview of WEC-Sim features that were not covered in the WEC-Sim Tutorials. The diagram below highlights some of WEC-Sim’s advanced features, details of which will be described in the following sections.

## BEMIO¶

The Boundary Element Method Input/Output (BEMIO) functions are used to pre-process the BEM hydrodynamic data prior to running WEC-Sim. For more information about the WEC-Sim pre-processing workflow, refer to Step 1: WEC-Sim Pre-Processing. BEMIO functions perform the following tasks:

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

The BEMIO tutorials are included in the $Source/tutorials/BEMIO directory in the WEC-Sim source code. For more information, refer to the BEMIO webinar. Note Previously the python based BEMIO code was used for this purpose. The python BEMIO functions have been converted to MATLAB and are included in the WEC-Sim source code. The python based BEMIO code will remain available but will no longer be supported. ### BEMIO Functions¶ Read_WAMIT: Reads data from a WAMIT output file hydro = Read_WAMIT(hydro, filename, ex_coeff) • hydro – data structure • filename – WAMIT output file • ex_coeff - flag indicating the type of excitation force coefficients to read, ‘diffraction’ (default) or ‘haskind’ Read_NEMOH: Reads data from a NEMOH working folder hydro = Read_NEMOH(hydro, filedir) • 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/RadiationCoefficients.tec • 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. Read_AQWA: Reads data from AQWA output files hydro = Read_AQWA(hydro, ah1_filename, lis_filename) • 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 hydrostatic restoring stiffness is normalized as, $$C_{i,j}/\rho g$$; the radiation added mass is normalized as, $$A_{i,j}/\rho$$; radiation wave damping is normalized as, $$B_{i,j}/\rho \omega$$; and the wave-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 Radiation_IRF: Calculates the normalized radiation impulse response function. $$\overline{K}_{r,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 = Radiation_IRF_SS(hydro, Omax, R2t) • 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}_{e,i,\beta}(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 radiation added mass, radiation wave 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*Nb,6*Nb,Nf] radiation added mass Ainf [6*Nb,6*Nb] infinite frequency added mass B [6*Nb,6*Nb,Nf] radiation wave damping beta [1,Nh] wave headings (deg) body {1,Nb} body names C [6,6,Nb] hydrostatic restoring stiffness cb [3,Nb] center of buoyancy cg [3,Nb] center of gravity code string BEM code (WAMIT, AQWA, or NEMOH) dof [6 + GBM, Nb] Degrees of freedom (DOF) for each body. Default DOF for each body is 6 plus number of possible generalized body modes (GBM). ex_im [6*Nb,Nh,Nf] imaginary component of excitation force or torque ex_K [6*Nb,Nh,length(ex_t)] excitation IRF ex_ma [6*Nb,Nh,Nf] magnitude of excitation force or torque ex_ph [6*Nb,Nh,Nf] phase of excitation force or torque ex_re [6*Nb,Nh,Nf] real component of excitation force or torque 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 fk_im [6*Nb,Nh,Nf] imaginary component of Froude-Krylov contribution to the excitation force or torque fk_ma [6*Nb,Nh,Nf] magnitude of Froude-Krylov excitation component fk_ph [6*Nb,Nh,Nf] phase of Froude-Krylov excitation component fk_re [6*Nb,Nh,Nf] real component of Froude-Krylov contribution to the excitation force or torque g [1,1] gravity h [1,1] water depth Nb [1,1] number of bodies Nf [1,1] number of wave frequencies Nh [1,1] number of wave headings ra_K [6*Nb,6*Nb,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 sc_im [6*Nb,Nh,Nf] imaginary component of scattering contribution to the excitation force or torque sc_ma [6*Nb,Nh,Nf] magnitude of scattering excitation component sc_ph [6*Nb,Nh,Nf] phase of scattering excitation component sc_re [6*Nb,Nh,Nf] real component of scattering contribution to the excitation force or torque ss_A [6*Nb,6*Nb,ss_O,ss_O] state space A matrix ss_B [6*Nb,6*Nb,ss_O,1] state space B matrix ss_C [6*Nb,6*Nb,1,ss_O] state space C matrix ss_conv [6*Nb,6*Nb] state space convergence flag ss_D [6*Nb,6*Nb,1] state space D matrix ss_K [6*Nb,6*Nb,length(ra_t)] state space radiation IRF ss_O [6*Nb,6*Nb] state space order ss_R2 [6*Nb,6*Nb] state space R2 fit T [1,Nf] wave periods Vo [1,Nb] displaced volume w [1,Nf] wave frequencies ### 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-to-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

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.

## Simulation Features¶

This section provides an overview of WEC-Sim’s simulation class features; for more information about the simulation class code structure, refer to Simulation Class.

### 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: waves.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 Multiple Condition Runs, the *.h5 hydrodynamic data is only loaded once. To reload the *.h5 data between runs, set simu.reloadH5Data =1 in the WEC-Sim input file.

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

### 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 a 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 NonlinearHydro example for a comparisons between ‘ode4’ to ‘ode45’. 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=N*simu.dt
• Nonlinear Buoyancy and Froude-Krylov Excitation time-step: simu.dtNL=N*simu.dt
• Convolution integral time-step: simu.dtCITime=N*simu.dt
• Morison force time-step: simu.dtME = N*N*simu.dt

#### 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 period). 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 buoyancy and Froude-Krylov excitation 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.

#### 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

## Wave Features¶

This section provides an overview of WEC-Sim’s wave class features. For more information about the wave class code structure, refer to Wave Class.

### Irregular Wave Binning¶

WEC-Sim’s default spectral binning method divides the wave spectrum into 499 bins with equal energy content, defined by 500 wave frequencies. As a result, the wave forces on the WEC using the equal energy method are only computed at each of the 500 wave frequencies. The equal energy formulation speeds up the irregular wave simulation time by reducing the number of frequencies the wave train is defined by, and thus the number of frequencies for which the wave forces are calculated. The equal energy method is specified by defining the following wave class variable in the WEC-Sim input file:

waves.freqDisc = 'EqualEnergy';

By comparison, the traditional method divides the wave spectrum into a sufficiently large number of equally spaced bins to define the wave spectrum. WEC-Sim’s traditional formulation uses 999 bins, defined by 1000 wave frequencies of equal frequency distribution. To override WEC-Sim’s default equal energy method, and instead use the traditional binning method, the following wave class variable must be defined in the WEC-Sim input file:

waves.freqDisc = 'Traditional';

Users may override the default number of wave frequencies by defining waves.numFreq. However, it is on the user to ensure that the wave spectrum is adequately defined by the number of wave frequencies, and that the wave forces are not impacted by this change.

### Wave Directionality¶

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

waves.waveDir = <user defined wave direction>; %[deg]

The incident wave direction has a default heading of 0 Degrees (Default = 0). For more information about the wave formulation, refer to Wave Theory.

WEC-Sim has the ability to model waves with directional spreading, $$D\left( \beta \right)$$. To define wave directional spreading in WEC-Sim, the following wave class variable must be defined in the WEC-Sim input file:

waves.waveSpread = <user defined directional spreading>;

The wave directional spreading has a default probability of 1 (Default = 1). For more information about the spectral formulation, refer to Wave Theory.

### Irregular Waves with Seeded Phase¶

By default, the phase for all irregular wave cases are generated randomly. In order to reproduce the same time-series every time an irregular wave simulation is run, the following wave class variable may be defined in the WEC-Sim input file:

waves.phaseSeed = <user defined seed>;

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

### Wave Gauge Placement¶

By default, the wave surface elevation is calculated at the origin. Users are allowed up to 3 other x-locations to calculate the wave surface elevation offset from the origin in the global x-direction by defining the wave class variable, waves.wavegauge<i>loc, in the WEC-Sim input file:

waves.wavegauge<i>loc = <user defined wave gauge i x-location>; %(y-position assumed to be 0 m)

where i = 1, 2, or 3

The WEC-Sim numerical wave gauges output the undisturbed linear incident wave elevation at the wave gauge locations defined above. The numerical wave gauges do not handle the incident wave interaction with the radiated or diffracted waves that are generated because of the presence and motion of the WEC hydrodynamic bodies. This option provides the following wave elevation time series:

waves.waveAmpTime<i> = incident wave elevation time series at wave gauge i

Note

This feature only works with planar waves propagating along the positive x-direction when waves.waveDir = 0.

## Body Features¶

This section provides an overview of WEC-Sim’s body class features; for more information about the body class code structure, refer to Body Class.

### 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 displaced 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 buoyancy and Froude-Krylov excitation and ParaView visualization files. Users can then visualize the geometry using the body(i).plotStl method.

### Non-Linear Buoyancy and Froude-Krylov Excitation¶

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 nonlinear buoyancy and Froude-Krylov excitation, 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 NonlinearHydro 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 buoyancy and Froude-Krylov effects need to be used. Note that simu.nlHydro = 1 only considers the nonlinear hydrostatic and Froude-Krylov wave excitations 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 buoyancy and Froude-Krylov wave excitation 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 buoyancy and Froude-Krylov wave excitation 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 most CAD programs, but few allow adequate mesh refinement. A good program to perform STL mesh refinement is Rhino. Some helpful resources explaining how to generate and refine an STL mesh in Rhino can be found on Rhino’s website and on Youtube.

Note

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

Refining STL File - The script refine_stl in the BEMIO directory performs a simple mesh refinement on an *.stl file by subdividing each panel with an area above the specified threshold into four smaller panels with new vertices at the mid-points of the original panel edges. This procedure is iterated for each panel until all panels have an area below the specified threshold, as in the example rectangle.

In this way, the each new panel retains the aspect ratio of the original panel. Note that the linear discretization of curved edges is not refined via this algorithm. The header comments of the function explain the inputs and outputs. This function calls import_stl_fast, included with the WEC-Sim distribution, to import the .*stl file.

#### Non-Linear Buoyancy and Froude-Krylov Wave Excitation 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 body class 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 OSWEC_nhBody 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 wave 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 simulation class variable must be defined in the WEC-Sim input file:

simu.b2b = 1

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

Note

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

### Viscous Damping and Morison Elements¶

WEC-Sim allows for the definition of additional damping and added-mass terms; for more information about the numerical formulation of viscous damping and Morison Elements, refer to the Viscous Damping and Morison Elements section.

#### Viscous Damping¶

A viscous damping force in the form of a linear damping coefficient $$C_{v}$$ can be applied to each body by defining the following body class parameter in the WEC-Sim input file (which has a default value of zero):

body(i).linearDamping


A quadratic drag force, proportional to the square of the body’s velocity, can be applied to each body by defining the quadratic drag coefficient $$C_{d}$$, and the characteristic area $$A_{d}$$ for drag calculation. This is achieved by defining the following body class parameters in the WEC-Sim input file (each of which have a default value of zero):

body(i).viscDrag.cd
body(i).viscDrag.characteristicArea


Alternatively, one can define $$C_{D}$$ directly:

body(i).viscDrag.Drag


#### Morison Elements¶

To use Morison Elements, the following simulation class variable must be defined in the WEC-Sim input file:

simu.morrisonElement  = 1

Morison Elements must then be defined for each body using the body(#).morrisonElement property of the body class. This property requires definition of the following body class parameters in the WEC-Sim input file (each of which have a default value of zero):

body(i).morrisonElement.cd
body(i).morrisonElement.ca
body(i).morrisonElement.characteristicArea
body(i).morrisonElement.VME
body(i).morrisonElement.rgME


The Morison Element time-step may also be defined as simu.dtME = N*simu.dt, where N is number of increment steps. For an example application of using Morison Elements in WEC-Sim, refer to the WEC-Sim Applications repository IEA_OES_Task10_freeDecay example.

Note

Morison Elements cannot but used with etaImport.

## Constraint and PTO Features¶

This section provides an overview of WEC-Sim’s constraint and pto classes; for more information about the constraint and pto classes’ code structure, refer to Constraint Class and PTO Class.

The default linear and rotational constraints and PTOs 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]).

Note

When using the Actuation Force/Torque PTO or Actuation Motion PTO blocks, the loads and displacements are specified in the local (not global) coordinate system. This is true for both the sensed (measured) and actuated (commanded) loads and displacements.

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 PTO-Sim example.

#### 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 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 post-processing 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/tutorials/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, accumulator blocks are located under the Hydraulic block. Rotary generator lookup table is under the Generator block. • Step 7: Since two accumulators are needed for the high pressure accumulator and low pressure accumulator, the user needs to double-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 the 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), angular 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 to the 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 take 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 Post-processing Simulation and post-processing 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 located 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 the generator box. • Step 7: Simply connect velocity from the selector to the input of the direct drive linear generator. The output PTO force is fed back to WEC-Sim. Input File, Simulation, and Post-processing The same as RM3 with hydraulic PTO. #### Tutorial: OSWEC with PTO-Sim¶ This section describes how to use the OSWEC model with PTO-Sim. The same process as described in RM3 with PTO-Sim ; however, since the 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 connections 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 Post-processing 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¶

This section provides an overview of WEC-Sim’s mooring class features; for more information about the mooring class code structure, refer to Mooring Class.

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 to the MoorDyn Tutorial section, and the Mooring Webinar for more information.

MoorDyn is hosted on a separate MoorDyn repository. It must be download separately, 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 needs 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] in [N/m]

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

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

### 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 the number of mooring lines that are 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 the 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 needs 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 are described in the MoorDyn User Guide [1].
• Simulation and Post-processing: Simulation and post-processing 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 Viz example.

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 nonlinear buoyancy and Froude-Krylov wave excitation)
• Allow data manipulation and more visualization options

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

• 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 visualization 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 specified 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 output 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 free surface
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 visualization 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 Buoyancy and Froude-Krylov Wave Excitation¶

When using non-linear buoyancy and Froude-Krylov Wave Excitation 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 (hydrostatic 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 tutorials. 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.