Warning: This document is for an old version of WecOptTool.

4. API

4.1. WecOptTool

class WecOptTool.AutoFolder

Class that creates unique temporary folders, which are deleted upon object destruction.

path

path to unique folder for storage

Type:string
archive(targetPath)

Save the folder and contents

Parameters:targetPath (string) – Path to destination folder

Note

If there are no files to copy this function will not make the destination folder

recoverVar(variableName)

Recover stashed variable

Parameters:variableName (string) – variable to recover
Returns:cell array containing all stored version of given variable name
Return type:cell
stashVar(variable)

Store a variable for recovery later.

Parameters:variable – variable to store

Note

A new stash is created every time a variable is stored, so multiple values may be returned by recoverVar()

class WecOptTool.Hydrodynamics(hydroData, options)

Data type for storage of solver hydrodynamics output.

This data type defines a set of parameters that are common to the description of wave device hydrodynamics parameters, such as in WEC-Sim’s BEMIO.

The following parameters must be provided within the input struct, which map directly to class attributes (see below):

  • ex
  • g
  • rho
  • w
  • A
  • Ainf
  • B
  • C
  • Nb
  • Nh
  • Nf
  • Vo

Note

Any negative radiation damping coefficients detected for individual bodies will be set to zero, automatically.

Parameters:
  • hydroData (struct) – A struct containing the required fields
  • options – name-value pair options. See below.

The following options are supported:

solverName (string):
The name of the solver used to generate the data
runDirectory (string):
Path to the directory containing the solver’s output files
base

copy of the input struct

Type:struct
ex

complex excitation force or torque ([6*Nb,Nh,Nf])

Type:array
g

gravitational acceleration

Type:float
rho

water density

Type:float
w

simulated wave frequencies ([1,Nf])

Type:array
A

radiation added mass ([6*Nb,6*Nb,Nf])

Type:array
Ainf

infinite frequency added mass ([6*Nb,6*Nb])

Type:array
B

radiation wave damping ([6*Nb,6*Nb,Nf])

Type:array
C

hydrostatic restoring stiffness ([6,6,Nb])

Type:array
Nb

number of bodies

Type:int
Nh

number of wave headings

Type:int
Nf

number of wave frequencies

Type:int
Vo

displaced volume ([1,Nb])

Type:array
solverName

name of solver used to generate hydrodyamic parameters. Default is “Unknown”.

Type:string
runDirectory

path to folder containing output files of the hydrodynamic solver. Defaults to “”.

Type:string
class WecOptTool.SeaState(S, options)

Data type for storage of sea state information.

This data type defines a set of parameters that are common to description of sea states and is based upon the formats used by the WAFO MATLAB toolbox.

The following parameters must be provided within the input struct (any additional parameters given will also be stored within the created object:

  • S
  • w

The values of S and w will be validated by the checkSpectrum method of this class. The following parameters are optional, and if not given will be given a default upon instantiation of the object:

  • mu
Parameters:

The following options are supported:

resampleByError (float):
Resample the given spectra such that the error with respect to the original spectral density is less than the given percentage of the maximum spectral density (per spectrum).
resampleByStep (float):
Resample the spectra with the given angular frequency step.
trimFrequencies (float):
Remove frequencies with spectral density less than the given percentage of the maximum (per spectrum).
extendFrequencies (int):
Add addition frequencies such that the largest value is extendFrequencies times the maximum (i.e. max(w)).

Note

The order of operations (if required) is to trim the frequencies first, then resample then, finally, extend the frequencies.

Example

Create an array of SeaState objects, with spectra:

  1. trimmed to include all frequencies containing 99% of the max spectral density
  2. resampled to 5% maximum error in max spectral density
  3. extended so that the maximum frequency is 4 times the trimmed maximum
>>> S = WecOptTool.SeaState.example8Spectra("resampleByError", 0.05, ...
...                                         "trimFrequencies", 0.01, ...
...                                         "extendFrequencies", 4);
S

spectral density [m2 s/rad]

Type:array of float
w

angular frequency [rad / s]

Type:array of float
baseS

unmodified spectral density [m2 s/rad]

Type:array of float
basew

unmodified angular frequency [rad / s]

Type:array of float
dw

angular frequency step [rad / s]

Type:float
sampleError

maximum sampling error as percentage of max(S)

Type:float
trimLoss

error due to range trimming as percentage of max(S)

Type:float
specificEnergy

the specific energy of the spectra [J / m2]

Type:float
mu

spectrum weighting, for arrays only (defaults to 1)

Type:float
static checkSpectrum(S)

Checks whether the input S is a valid spectrum structure (following WAFO).

Parameters:S (struct) –

struct array with the fields:

  • w - column vector of frequencies [rad/s]
  • S - column vector of spectral density [m2 s/rad]

Note

This method makes the following checks:

  1. The struct has fields S and w
  2. Fields S and w are the same length
  3. Fields S and w are column vectors
  4. Field w is positive
  5. Field w is monotonic
  6. Field w is regular
  7. The first entry of field w is an integer multiple of the frequency step

Example

Use WAFO to create a Bretschneider spectrum

>>> Hm0 = 5;
>>> Tp = 8;
>>> S = bretschneider([],[Hm0,Tp]);
>>> WecOptTool.utils.checkSpectrum(S)
static example8Spectra(varargin)

Example Bretschneider spectrum with varying HHm0s, Tps, Nbins, and range

static exampleSpectrum(varargin)

Example Bretschneider spectrum with Hm0=8 and Tp=10

static extendFrequencies(S, nRepeats)

Adds multiples of the maximum frequency to a spectra struct array

Parameters:
Returns:

Sea state struct which conforms to WecOptTool.SeaState.checkSpectrum()
Return type:

struct

Example

Double the frequency range of the given spectrum

>>> import WecOptTool.SeaState
>>> S = WecOptTool.tests.data.exampleSpectrum();
>>> disp(max(S.w))
    3.2000
<BLANKLINE>
>>> Snew = SeaState.extendFrequencies(S, 2);
>>> disp(max(Snew.w))
    6.4000
getAllFrequencies()

Returns all unique frequencies over all sea states

Returns:sorted unique angular frequencies [rad / s]
Return type:array
getAmplitudeSpectrum()

Get wave amplitude per angular frequency

Returns:wave amplitudes [m]
Return type:array
static getMaxAbsoluteDensityError(trueS, approxS)

Returns the maximum absolute error in spectral density between two spectra struct arrays.

Parameters:
Returns:

absolute error per spectrum [m2 s/rad]
Return type:

array

Example

Find the maximum absolute error in spectral density in a spectrum after resampling

>>> import WecOptTool.SeaState
>>> S = WecOptTool.tests.data.exampleSpectrum();
>>> newS = SeaState.resampleByStep(S, 0.2);
>>> error = SeaState.getMaxAbsoluteDensityError(S, newS);
>>> disp(error)
    0.9136
getRegularFrequencies(dw)

Returns regularly spaced frequencies covering all sea states at the given step size

Parameters:dw (float) – angular frequency step
Returns:regular angular frequencies [rad / s]
Return type:array
static getRelativeEnergyError(trueS, approxS)

Returns the relative error in specific energy between two spectra struct arrays

Parameters:
Returns:

relative error per spectrum
Return type:

array

Example

Find the relative error in specific energy of a spectrum after resampling

>>> import WecOptTool.SeaState
>>> S = WecOptTool.tests.data.exampleSpectrum();
>>> newS = SeaState.resampleByStep(S, 0.2);
>>> error = SeaState.getRelativeEnergyError(S, newS);
>>> disp(error)
    0.0010
static getSpecificEnergy(S, options)

Calculates the specific energy of the given spectra struct array

Parameters:

The following options are supported:

g (optional, float):
Acceleration due to gravity, default = 9.81 m/s2.
rho (optional, float):
Water density, default 1028 kg/m3.
Returns:specify energy per spectra [J / m2]
Return type:array

Example

>>> import WecOptTool.SeaState
>>> S = WecOptTool.tests.data.exampleSpectrum();
>>> e = SeaState.getSpecificEnergy(S);
>>> disp(e)
   4.0264e+04
plot()

Plot spectra and comparison to base spectra, if different.

One plot is created per spectrum in the array.

static regularWave(w, sdata, varargin)

Returns a regular wave using a WAFO-like struct

Parameters:
  • w (array) – frequency vector
  • sdata (array) – [A, T], where A is the amplitude and T is the period
Returns:

SeaState object
Return type:

WecOptTool.SeaState

See also jonswap

static resampleByError(S, targetError, min_dw)

Resample the given sea state struct based on the error in spectral density normalized by the maximum per spectrum. a maximum error of the maximum spectral density for a spectra struct array.

Parameters:
  • S (struct) – struct array that satisfies the WecOptTool.SeaState.checkSpectrum() method
  • targetError (float) – Target maximum error in normalized spectral density
  • min_dw (optional, float) – Smallest frequency step to test, default = 1e-4
Returns:

Example

Resample such that the maximum absolute error in spectral density is less that 5% of it’s original maximum

>>> import WecOptTool.SeaState
>>> S = WecOptTool.tests.data.exampleSpectrum();
>>> newS = SeaState.resampleByError(S, 0.05);
>>> error = SeaState.getMaxAbsoluteDensityError(S, newS);
>>> disp(error / max(S.S))
    0.0500
static resampleByStep(S, dw)

Resample the given sea state struct using a given frequency step

Parameters:
Returns:

Example

Resample using a fixed angular frequency step of 0.2

>>> import WecOptTool.SeaState
>>> S = WecOptTool.tests.data.exampleSpectrum();
>>> newS = SeaState.resampleByStep(S, 0.2);
>>> dw = uniquetol(diff(newS.w), eps('single'));
>>> disp(dw)
    0.2000
static trimFrequencies(S, densityTolerence)

Removes frequencies below a threshold of the maximum spectral density from the tails, per spectra, of a spectra struct array.

Parameters:
Returns:

Sea state struct which conforms to WecOptTool.SeaState.checkSpectrum()
Return type:

struct

Example

Remove frequencies containing less than 1% of the maximum spectral density

>>> import WecOptTool.SeaState
>>> S = WecOptTool.tests.data.example8Spectra();
>>> newS = SeaState.trimFrequencies(S, 0.01);
WecOptTool.mesh(meshName, folder, varargin)

Make a mesh using shortcuts to the makeMesh method of the defined Mesher concrete classes in the WecOptTool.mesh package.

Parameters:
  • meshName (string) –

    Meshing routine to use. Current options are:

  • folder (string) – Path to the folder to store output files
  • varargin – Arguments to pass to the meshing routine. See the makeMesh method of the chosen mesher class for details.
Returns:

A mesh description with fields as described below
Return type:

struct
Variable Format Description
bodyNum int body number
name char array name of the mesh
nodes Nx4 table table of N node positions with columns ID, x, y, z
panels Mx4 int32 array array of M panels where each row contains the 4 connected node IDs
xzSymmetric bool body is symmetric in xz plane (half mesh)
zG float z-coordinate of the bodies centre of gravity
WecOptTool.solver(solverName, folder, varargin)

Solve a mesh using shortcuts to the getHydro method of the defined Solver concrete classes in the WecOptTool.solver package.

Parameters:
  • solverName (string) –

    Solver routine to use. Current options are:

  • folder (string) – Path to the folder to store output files
  • varargin – Arguments to pass to the solver routine. See the getHydro method of the chosen solver class for details.
Returns:

Output struct from chosen solver
Return type:

struct

4.2. WecOptTool.geometry

The geometry package provides predefined geometry generation functions.

WecOptTool.geometry.existingNEMOH(nemohFolder)

A predefined geometry callback for reading an existing NEMOH solution.

Parameters:nemohFolder (string) – Path to the folder containing existing NEMOH output files
Returns:Hydrodynamics object
Return type:WecOptTool.Hydrodynamics

4.3. WecOptTool.plot

WecOptTool.plot.plotMesh(meshses, newFig)

Plot the given meshes on a single 3D axis.

Parameters:
  • meshses (struct) – Struct array containing mesh description with fields as described below
  • newFig (bool) – If true a new figure is created

The meshes struct must contain the following fields:

Variable Format Description
bodyNum int body number
name char array name of the mesh
nodes Nx4 table table of N node positions with columns ID, x, y, z
panels Mx4 int32 array array of M panels where each row contains the 4 connected node IDs
xzSymmetric bool body is symmetric in xz plane (half mesh)
zG float z-coordinate of the bodies centre of gravity
WecOptTool.plot.powerPerFreq(input)

Plots power per frequency for a simulated device.

Parameters:input (struct) – A struct array with fields defined in the table below
Variable Format Description
w Nx1 float array N sea-state frequencie
powPerFreq Nx1 float array Power production per frequency

4.4. WecOptTool.math

WecOptTool.math.bisection(f, a, b, options)

Bisection method

Parameters:
  • f (float) – real valued function
  • a (float) – search space lower boundary
  • b (float) – search space upper boundary
  • tol (optional, float) – solution tolerance, default = 1e-10
  • nmax (optional, int) – maximum number of operations, default = 1e4
Returns:

root of f
Return type:

float

Note

The given interval boundaries must satisfy f(a) * f(b) <= 0

WecOptTool.math.isClose(a, b, varargin)

Determine if two values are numerically close (but perhaps not exactly equal).

Parameters:
  • a (float) – first value to compare
  • b (float) – second value to compare
  • rtol (float, optional) – relative tolerence, default = 1e-05
  • atol (float, optional) – absolute tolerance, default = 1e-08
Returns:

true if a is within given tolerances of b
Return type:

bool

Note

Derived from the similar named numpy routine

4.5. WecOptTool.mesh

The mesh subpackage provides mesh generation classes, that provide the standard method makeMesh.

class WecOptTool.mesh.AxiMesh

Class for making meshes using the NEMOH aximesh routine

Parameters:base (string, optional) – Parent for folder which stores NEMOH input and output files, default is tempdir
path

path to file storage folder

Type:string
verb

use verbose console outputs (default false)

Type:bool
rho

water density (default = 1025 kg/m3)

Type:float
g

gravitational acceleration (default = 9.81 m/s2)

Type:float
makeMesh(r, z, ntheta, nfobj, zG, bodyNum)

Mesh generation of an axisymmetric body.

All coordinates are measured from the undisturbed sea surface and only the body description below the sea surface should be given, thus all z-coordinates should be negative.

The produced mesh represents half of the body and is symmetric in the xz plane.

Parameters:
  • r (array of float) – radial coordinates
  • z (array of float) – vertical coordinates
  • ntheta (int) – number of points for discretization in angular direction (over pi radians)
  • nfobj (int) – number of nodes within the resulting half body mesh
  • zG (float) – z-coordinate of the bodies centre of gravity
  • bodyNum (int) – the number of the body (starting from one)
Returns:

A mesh description with fields as described below
Return type:

struct
Variable Format Description
bodyNum int body number
name char array name of the mesh
nodes Nx4 table table of N node positions with columns ID, x, y, z
panels Mx4 int32 array array of M panels where each row contains the 4 connected node IDs
xzSymmetric bool body is symmetric in xz plane (half mesh)
zG float z-coordinate of the bodies centre of gravity

Warning

z(i) must be greater than or equal to z(i+1)

Note

The original aximesh function was written by A. Babarit, LHEEA Lab, and licensed under the Apache License, Version 2.0.

4.6. WecOptTool.solver

The solver subpackage provides hydrodynamic solver classes, that provide the standard method getHydro.

class WecOptTool.solver.NEMOH(basePath)

Class for solving meshes using the NEMOH suite.

Parameters:base (string, optional) – Parent for folder which stores NEMOH input and output files, default is tempdir
path

path to file storage folder

Type:string
verb

use verbose console outputs (default false)

Type:bool
rho

water density (default = 1025 kg/m3)

Type:float
g

gravitational acceleration (default = 9.81 m/s2)

Type:float
getHydro(meshes, w)

Calculate floating body hydrodynamic coefficients using NEMOH

Parameters:
  • meshes (struct) – The meshes to be solved. Each object in the array represents a different body with body number given by the bodyNum property. See table below for field definitions.
  • w (array of float) – The angular wave frequencies to be calculated.
Returns:

Hydrodynamics object
Return type:

WecOptTool.Hydrodynamics

“meshes” Struct Fields

Variable Format Description
bodyNum int body number
name char array name of the mesh
nodes Nx4 table table of N node positions with columns ID, x, y, z
panels Mx4 int32 array array of M panels where each row contains the 4 connected node IDs
zG float z-coordinate of the bodies centre of gravity

Note

The original aximesh function was written by A. Babarit, LHEEA Lab, and licensed under the Apache License, Version 2.0.

4.7. WecOptTool.base

The base subpackage provides base classes used in other classes.

class WecOptTool.base.Mesher

Abstract class for creating new mesher classes

A single method should be implemented, called makeMesh that creates a mesh using any particular external tool

class WecOptTool.base.NEMOH

Base class containing NEMOH helpers

static isNemohInPath()

Determine if the NEMOH executables can be found.

Returns:true if executables found, otherwise false.
Return type:bool
class WecOptTool.base.Solver

Abstract class for creating new solver classes

A single method should be implemented, called getHydro that solves the hydrodynamics for a given mesh using any particular external tool

class WecOptTool.base.TempFolder(base)

Superclass for classes requiring temporary storage

Parameters:base (string, optional) – Parent for temporary folder, default is tempdir
path

path to temporary folder

Type:string