Overview

This section provides an overview of the WEC-Sim work flow. First, the WEC-Sim file structure is described; then, steps for setting up and running the WEC-Sim code are described. The WEC-Sim workflow diagram is shown below. A description of this workflow is provided in the following sections. For information about the implementation and structure of the WEC-Sim source code, refer to the Code Structure section.

_images/WEC-Sim_flowChart.png
WEC-Sim Workflow Diagram

WEC-Sim Model Files

All files required for a WEC-Sim simulation must be contained within a case directory referred to as $CASE. This directory can be located anywhere on your computer. The table below list the WEC-Sim case directory structure and required files.

File Type File Name Directory
Hydrodynamic Data *.h5 $CASE/hydroData
Geometry File *.stl $CASE/geometry
Simulink Model *.slx $CASE
Input File wecSimInputFile.m $CASE

Hydrodynamic Data

  • The Hydrodynamic coefficients for each body may be generated using a boundary element method (BEM) code (e.g., WAMIT, NEMOH or AQWA).
  • The WEC-Sim code also requires hydrodynamic data from the BEM solution in the form of HDF5 format (*.h5 file).
  • This *.h5 hydrodynamic data file can be generated using the BEMIO pre-processor.
  • BEMIO (Boundary Element Method Input/Output) is a code developed by the WEC-Sim team to process BEM output files from WAMIT, NEMOH, and AQWA into a data structure than can be read by WEC-Sim.
  • For more information about the BEMIO pre-processor, refer to the BEMIO section.

Geometry File

  • The WEC-Sim code also requires a geometry file in the form of a *.stl file.
  • This *.stl file is used by the WEC-Sim code to generate the Simscape Explorer visualization, and by the nonlinear buoyancy and Froude-Krylov forces option to determine the instantaneous wetted surface at each time step.
  • When running WEC-Sim with linear hydrodynamics, the *.stl is only used for visualization.
  • When running WEC-Sim with nonlinear buoyancy and Froude-Krylov forces, the quality of the *.stl mesh is critical, refer to the Nonlinear Buoyancy and Froude-Krylov Forces section for more information.

Input File

  • A WEC-Sim input file (wecSimInputFile.m) is required for each run. The input file MUST be named wecSimInputFile.m and placed within the case directory.
  • The main structure of the input file consists of initializing all the objects necessary to run WEC-Sim simulations, and defining any user specified properties for each object.
  • The input file for each WEC-Sim simulation requires initialization and definition of the simulation and wave classes, at least one instance of the body class, and at least one instance of the constraint or PTO classes.
  • For details about WEC-Sim’s objects and available properties for each object, refer to the WEC-Sim Objects section.

An example WEC-Sim input file is shown below for the OSWEC Tutorial. Additional examples are provided in the Tutorials section. WEC-Sim is an object oriented code and the input file reflects this. The WEC-Sim input file (wecSimInputFile.m) for the OSWEC initializes and specifies properties for simulation, body, constraint and pto classes.

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

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

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

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

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

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

Running WEC-Sim

This section provides a description of the steps to run the WEC-Sim code, refer to the WEC-Sim workflow diagram while following the steps to run WEC-Sim.

Step 1: WEC-Sim Pre-Processing

In the pre-processing step, users need to create the WEC geometry, run a BEM code to calculate the hydrodynamic coefficients, and convert the hydrodynamic coefficients into the *.h5 format for WEC-Sim to read:

  • Create WEC Geometry:

    • Create CAD models of the WEC geometry and export it to a *.stl format.
    • The *.stl files are used to visualize the WEC response in Simscape Explorer
    • They are also used for Nonlinear Buoyancy and Froude-Krylov Forces if the option is applied.
  • Compute Hydrodynamic Coefficients: WEC-Sim requires frequency-domain hydrodynamic coefficients (e.g. added mass, radiation damping, and wave excitation).

    • The coefficients for each body may be generated using a boundary element method (BEM) code (e.g., WAMIT, NEMOH or AQWA).
    • WEC-Sim requires that all hydrodynamic coefficients must be specified at the center of gravity for each body.

Note

  • If WAMIT is used:
    • The origin of the body coordinate system (XBODY, defined in *.pot) as well as the mesh for each body must be at the center of gravity.
    • The WAMIT mesh (*.gdf) can be generated using Rhino or MultiSurf.
    • More details on WAMIT setup are given in the WAMIT User Manual.
  • If NEMOH is used:
    • The origin of the mesh for each body (*.dat) is located at the mean water surface, which follows the same coordinate used in WEC-Sim.
    • The location to output the hydrodynamic coefficients for each degree of freedom is defined in the Nemoh.cal file.
    • Please refer to NEMOH-Mesh webpage for more mesh generation details.
    • 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.
    • More details on NEMOH setup are given in the Nemoh Homepage.
  • If AQWA is used:
    • The origin of the global coordinate system is at the mean water surface, and the origin of the body coordinate system for each body must be at the center of gravity (defined using the AQWA GUI or in the *.dat input file).
    • In order to run BEMIO, AQWA users must output both the default *.LIS file and output the *.AH1 hydrodynamic database file. Both of these files are reacquired to run BEMIO.
    • More details on AQWA setup are given in the AQWA Reference Manual.
  • Parse Hydrodynamic Coefficients into WEC-Sim Required Format:
    • The hydrodynamic coefficients for each body generated from the BEM code can be parsed into a *.h5 data structure using BEMIO, which was developed by the WEC-Sim team.
    • BEMIO currently supports WAMIT, NEMOH and AQWA.

Note

Users are also able to specify their own hydrodynamic coefficients by creating their own *.h5 file with customized hydrodynamic coefficients following the *.h5 format created by BEMIO.

Step 3: Write the WEC-Sim Input File

The WEC-Sim input file must be located in the $CASE directory, and named wecSimInputFile.m. The figure below shows an example of a WEC-Sim input file. The input file specifies the simulation settings, body mass properties, wave conditions, joints, and mooring. Additionally, the WEC-Sim input file must specify the location of the WEC-Sim Simulink model (*.slx) file, the geometry file(s) *.stl, and the hydrodynamic data file (*.h5) .

_images/runWECSim_mod.png

Step 4: Execute WEC-Sim

Lastly, execute the WEC-Sim code by typing wecSim into the MATLAB Command Window. The WEC-Sim source code is located in the $Source directory, but wecSim must be executed from the $CASE directory.

Note

WEC-Sim simulations should always be executed from the MATLAB Command Window, not from the Simulink/SimMechanics model.