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
- note
Parameters: - S (struct) – A struct containing the required fields, validated by the
WecOptTool.SeaState.checkSpectrum()
method. - options – name-value pair options. See below.
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:
- trimmed to include all frequencies containing 99% of the max spectral density
- resampled to 5% maximum error in max spectral density
- 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
-
note
¶ a description of the spectrum
Type: string
-
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:
- The struct has fields S and w
- Fields S and w are the same length
- Fields S and w are column vectors
- Field w is positive
- Field w is monotonic
- Field w is regular
- 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: - S (struct) – struct array that satisfies the
WecOptTool.SeaState.checkSpectrum()
method - nRepeats (int) – Number of repetitions of max frequency
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
- S (struct) – struct array that satisfies the
-
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: - trueS (struct) – struct array representing the true value and satisfies
WecOptTool.SeaState.checkSpectrum()
- approxS (struct) – struct array representing the approximate value and
satisfies
WecOptTool.SeaState.checkSpectrum()
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
- trueS (struct) – struct array representing the true value and satisfies
-
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: - trueS (struct) – struct array representing the true value and satisfies
WecOptTool.SeaState.checkSpectrum()
- approxS (struct) – struct array representing the approximate value and
satisfies
WecOptTool.SeaState.checkSpectrum()
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
- trueS (struct) – struct array representing the true value and satisfies
-
static
getSpecificEnergy
(S, options)¶ Calculates the specific energy of the given spectra struct array
Parameters: - S (struct) – struct array that satisfies the
WecOptTool.SeaState.checkSpectrum()
method - options – name-value pair options. See below.
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
- S (struct) – struct array that satisfies the
-
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: 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: - S (struct): Sea state struct which conforms to
WecOptTool.SeaState.checkSpectrum()
- dw (array): Frequency spacings per spectrum
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
- S (struct) – struct array that satisfies the
-
static
resampleByStep
(S, dw)¶ Resample the given sea state struct using a given frequency step
Parameters: - S (struct) – struct array that satisfies the
WecOptTool.SeaState.checkSpectrum()
method - dw (float) – Angular frequency step size
Returns: - S (struct): Sea state struct which conforms to
WecOptTool.SeaState.checkSpectrum()
- errors (array): error in spectral density (normalized by the maximum) per spectrum
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
- S (struct) – struct array that satisfies the
-
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: - S (struct) – struct array that satisfies the
WecOptTool.SeaState.checkSpectrum()
method - densityTolerence (float) – Percentage of maximum spectral density
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);
- S (struct) – struct array that satisfies the
-
WecOptTool.
mesh
(meshName, folder, varargin)¶ Make a mesh using shortcuts to the
makeMesh
method of the defined Mesher concrete classes in theWecOptTool.mesh
package.Parameters: - meshName (string) –
Meshing routine to use. Current options are:
- AxiMesh (
WecOptTool.mesh.AxiMesh
)
- AxiMesh (
- 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 - meshName (string) –
-
WecOptTool.
solver
(solverName, folder, varargin)¶ Solve a mesh using shortcuts to the
getHydro
method of the defined Solver concrete classes in theWecOptTool.solver
package.Parameters: - solverName (string) –
Solver routine to use. Current options are:
- NEMOH (
WecOptTool.solver.NEMOH
)
- NEMOH (
- 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
- solverName (string) –
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: “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.
- meshes (struct) – The meshes to be solved. Each object in the array
represents a different body with body number given by
the
-
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
-
static
-
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
-