Class: wsim.hydroBody¶
wsim.hydroBody represents one hydrodynamically interacting body in a
hydrodynamic system. It is intended to be used in conjunction with the
wsim.hydroSystem class which manages a collection of wsim.hydroBody
objects and is used to perform the time domain simulation of the bodies.
The body simulation data is contained in a case directory. This case
directory should contain two subdirectories, 'hydroData' and 'geometry'.
The hydroData subdirectory should contain either one .h5 file containing
the output of the BEMIO files which process the output of various BEM
solvers to a format understood by the hydroBody class, or, a collection
of .mat files containing hydroData structures which can be directly
loaded by the body. In this case, there will be one mat file for each
body.
The geometry subdirectory should contain a collection of STL files, one
for each body.
wsim.hydroBody Methods:
hydroBody - constructor for the hydroBody class
adjustMassMatrix - Merges diagonal term of added mass matrix to the mass matrix
advanceStep - advance to the next time step, accepting the current time
bodyGeo - Reads an STL mesh file and calculates areas and centroids
checkInputs - Checks the user inputs
forceAddedMass - Recomputes the real added mass force time history for the
getVelHist - not documented
hydroForcePre - performs pre-processing calculations to populate hydroForce structure
hydroForces - hydroForces calculates the hydrodynamic forces acting on a
hydrostaticForces - calculates the hydrostatic forces acting on the body
lagrangeInterp - not documented
linearExcitationForces - calculates linear wave excitation forces during transient
linearInterp - not documented
listInfo - Display some information about the body at the command line
loadHydroData - load hydrodynamic data from file or variable
makeMBDynComponents - creates mbdyn components for the hydroBody
morrisonElementForce - not documented
nonlinearExcitationForces - calculates the non-linear excitation forces on the body
offsetXYZ - Function to move the position vertices
plotStl - Plots the body's mesh and normal vectors
radForceODEOutputfcn - OutputFcn to be called after every completed ode time step
radForceSSDerivatives - wsim.hydroBody/radForceSSDerivatives is a function.
radiationForces - calculates the wave radiation forces
readH5File - Reads an HDF5 file containing the hydrodynamic data for the body
restoreMassMatrix - Restore the mass and added-mass matrix back to the original value
rotateXYZ - Function to rotate a point about an arbitrary axis
saveHydroData - saves the body's hydrodata structure to a .mat file
setCaseDirectory - set the case directory for the simulation the body is part of
setInitDisp - Sets the initial displacement when having initial rotation
storeForceAddedMass - Store the modified added mass and total forces history (inputs)
timeDomainSimReset - resets the body in readiness for a transient simulation
timeDomainSimSetup - sets up the body in preparation for a transient simulation
viscousDamping - not documented
waveElevation - calculate the wave elevation at centroids of triangulated surface
write_paraview_vtp - Writes vtp files for visualization with ParaView
Parent Class Properties and Methods¶
handle¶
Inheirited Properties¶
None
Inheirited Methods¶
- addlistener : ADDLISTENER Add listener for event.
- addlistener : ADDLISTENER Add listener for event.
- addlistener : ADDLISTENER Add listener for event.
- addlistener : ADDLISTENER Add listener for event.
- addlistener : ADDLISTENER Add listener for event.
- delete : DELETE Delete a handle object.
- eq : == (EQ) Test handle equality.
- findobj : FINDOBJ Find objects matching specified conditions.
- findprop : FINDPROP Find property of MATLAB handle object.
- ge : >= (GE) Greater than or equal relation for handles.
- gt : > (GT) Greater than relation for handles.
- isvalid : ISVALID Test handle validity.
- le : <= (LE) Less than or equal relation for handles.
- listener : LISTENER Add listener for event without binding the listener to the source object.
- listener : LISTENER Add listener for event without binding the listener to the source object.
- listener : LISTENER Add listener for event without binding the listener to the source object.
- listener : LISTENER Add listener for event without binding the listener to the source object.
- listener : LISTENER Add listener for event without binding the listener to the source object.
- lt : < (LT) Less than relation for handles.
- ne : ~= (NE) Not equal relation for handles.
- notify : NOTIFY Notify listeners of event.
- notify : NOTIFY Notify listeners of event.
Properties¶
- addedMassMethod
- bodyGeometry
- bodyNumber
- bodyToBodyInteraction
- bodyTotal
- caseDirectory
- cb
- cg
- disableAddedMassForce
- disableRadiationForce
- dispVol
- doAddedMass
- doLinearDamping
- doMorrisonElementViscousDrag
- doNonLinearFKExcitation
- doRadiationDamping
- doViscousDamping
- dof
- dof_end
- dof_gbm
- dof_start
- excitationMethod
- flexHydroBody
- freeSurfaceMethod
- geometryFile
- hydroData
- hydroDataBodyNum
- hydroDataFile
- hydroDataFileFullPath
- hydroForce
- hydroStiffness
- linearDamping
- mass
- massCalcMethod
- meanDriftForce
- momOfInertia
- morrisonElement
- name
- radiationMethod
- totalLenDOF
- userDefinedExcIRF
- viscDrag
- viz
addedMassMethod¶
- character vector with a description of the added mass method
Contains one of the following character vectors describing what method will be used to calculate the added mass forces:
‘extrapolate acceleration from previous steps’ ‘iterate’
bodyGeometry¶
- Structure defining body’s mesh
Should contain the fields ‘numFace’, ‘numVertex’, ‘vertex’, ‘face’, ‘norm’, ‘area’, ‘center’. Generally this is filled by reading the geometry STL file.
numFace : Number of faces
numVertex : Number of vertices
vertex : List of vertices
face : List of faces
norm : List of normal vectors
area : List of cell areas
center : List of cell centers
bodyNumber¶
- body number in the order body was added to a wsim.hydroSystem.
- Can be different from the BEM body number, this is the index of the body in the wsim.hydroSystem
bodyToBodyInteraction¶
true/false flag indicating if body-to-body interaction is included
bodyTotal¶
Total number of hydro bodies in the wsim.hydroSystem
caseDirectory¶
Simulation case directory containing the hydroData and geometry subdirectories
cb¶
- Center of buoyancy [x; y; z] in meters.
- For WEC bodies this is given in the h5 file.
cg¶
- Center of gravity [x; y; z] in meters.
- This is obtained from the h5 or mat file.
disableAddedMassForce¶
- true/false flag indicating whether to calculate added mass forces
- If this is true, the added mass force will be set to always return [ 0; 0; 0; 0; 0; 0 ]. It is generally intended for debugging purposes only
disableRadiationForce¶
- true/false flag indicating whether to calculate radiation forces
- If this is true, the radiation damping force will be set to always return [ 0; 0; 0; 0; 0; 0 ]. It is generally intended for debugging purposes only
dispVol¶
doAddedMass¶
true/false flag indicating if added mass forces are included
doLinearDamping¶
true/false flag indicating if linear damping is included
doMorrisonElementViscousDrag¶
true/false flag indicating if morrison element viscous drag is included
doNonLinearFKExcitation¶
- true/false flag indicating if FK force will be calculated
- Indicates whether the nonlinear Froude-Krylov wave excitation forces will be calculated
doRadiationDamping¶
true/false flag indicating if radiation forces are included
doViscousDamping¶
true/false flag indicating if viscous damping is included
dof¶
- Number of DOFs.
- For WEC bodies this is given in the h5 file. IF not, default is 6
dof_end¶
- Index of DOF ends.
- For WEC bodies this is given in the h5 file. IF not, default is (bodyNumber-1)*6+6
dof_gbm¶
Number of DOFs for GBM.
dof_start¶
- Index of DOF starts.
- For WEC bodies this is given in the h5 file. IF not, default is (bodyNumber-1)*6+1
excitationMethod¶
- Character vector containing the wave excitation method to be used
- can be one of: ‘noWave’, ‘noWaveCIC’, ‘regular’, ‘regularCIC’, ‘irregular’, ‘irregularImport’, ‘userDefined’
flexHydroBody¶
Flag for flexible body.
freeSurfaceMethod¶
- character vector indicating what fre surface method will be used
- Will be ‘mean’ or ‘instantaneous’
geometryFile¶
Names of geomtry stl file for this body in geometry subfolder
hydroData¶
Hydrodynamic data from BEM or user defined.
hydroDataBodyNum¶
Body number within the hdf5 file.
hydroDataFile¶
name of hdf5 or mat file containing the hydrodynamic data (without path)
hydroDataFileFullPath¶
full path to h5 or mat file containing the hydrodynamic data for the body
hydroForce¶
- Structure containing hydrodynamic forces and coefficients used during simulation
- Will be a structure containing various fields depending on what simulation settings were chosen.
hydroStiffness¶
linearDamping¶
Linear drag coefficient, vector length 6
mass¶
Mass in kg or specify ‘equilibrium’ to have mass = displacement vol * density
massCalcMethod¶
Method used to obtain mass: ‘user’, ‘fixed’, ‘equilibrium’
‘user’ means the user has specified the mass directly
- ‘fixed’ means the mass is irrelevant as the hydrobody will be
- clamped in place, so a default set of mass and inertia values will be used.
‘equilibrium’ means the mass is calculated
meanDriftForce¶
Flag for mean drift force. 0: No; 1: from control surface; 2: from momentum conservation.
momOfInertia¶
Moment of inertia [Ixx Iyy Izz] in kg*m^2 for the body
morrisonElement¶
- structure defining morrison element input
Should be a structure containing the fields ‘cd’, ‘ca’, ‘characteristicArea’, ‘VME’ and ‘rgME’
- cd : vector length 3 containing the viscous (quadratic) drag
- coefficients
- ca : Added mass coefficent for Morrison Element (format [Ca_x
- Ca_y Ca_z], default = [0 0 0])
- characteristicArea : Characteristic area for Morrison Elements
- calculations (format [Area_x Area_y Area_z], default = [0 0 0])
VME : Characteristic volume for Morrison Element (default = 0)
- rgME : Vector from center of gravity to point of application for
- Morrison Element (format [X Y Z], default = [0 0 0]).
name¶
Body name. This is obtained from the h5 or mat file.
radiationMethod¶
- character vector with a description of the radiation method
Contains one of the following character vectors describing what method will be used to calculated the radiation forces:
‘constant radiation coefficients’ ‘state space representation’ ‘state space representation using external solver’ ‘convolution integral’
totalLenDOF¶
Matrices length. 6 for no body-to-body interactions. 6*numBodies if body-to-body interactions.
userDefinedExcIRF¶
Defined Time-Series
viscDrag¶
- Structure defining the viscous (quadratic) drag
Must contain either the field ‘Drag’, or the fields ‘cd’ and ‘characteristicArea’.
- Drag : if supplied, this field should contain either a full
- (6x6) matrix defining the Viscous (quadratic) drag, or a vector of length 6 representing the diagonal of this matrix. These are the directly specified viscous drag coefficients.
- cd : should contain a vector length 6 defining the Viscous
- (quadratic) drag coefficients which will be multiplied by the corresponding values in the ‘characteristicArea’ field.
- characteristicArea : should contain a vector of length
- 6 defining the Characteristic areas for viscous drag.
viz¶
- Structure defining visualization properties for Paraview
Should contain two fields, ‘color’ and ‘opacity’.
- color : three element vector containing the rgb values defining
- the body color in Paraview
- opacity : scalar value defining the opacity of the body in
- Paraview.
Methods¶
- hydroBody
- addedMassForces
- adjustMassMatrix
- advanceStep
- bodyGeo
- checkInputs
- forceAddedMass
- getVelHist
- hydroForcePre
- hydroForces
- hydrostaticForces
- lagrangeInterp
- linearDampingForce
- linearExcitationForces
- linearInterp
- listInfo
- loadHydroData
- makeMBDynComponents
- morrisonElementForce
- nonlinearExcitationForces
- offsetXYZ
- plotStl
- radForceODEOutputfcn
- radForceSSDerivatives
- radiationDampingForces
- readH5File
- restoreMassMatrix
- rotateXYZ
- saveHydroData
- setCaseDirectory
- storeForceAddedMass
- timeDomainSimReset
- timeDomainSimSetup
- vcross
- viscousDamping
- waveElevation
- write_paraview_vtp
hydroBody¶
Summary¶
constructor for the hydroBody class
Syntax¶
hb = hydroBody (filename)
Inputs¶
filename¶
string containing the h5 or mat file containing
the hydrodynamic data for the body, without the path, e.g.
float.mat, or rm3.h5. The hydrobody searches for the file
in the <case_directory>/hydroData folder. The validity of
the file name is not checked until the setCaseDirectory
method is called (which is usually called by a parent
wism.hydroSystem object which sets the case directory for
all hydroBodies in a system).
Outputs¶
hb¶
a wsim.hydroBody object
addedMassForces¶
Summary¶
calculates the body added mass forces
Syntax¶
F_AddedMass = radiationForces (obj, t, vel, accel)
Inputs¶
accel¶
(6 x 1) translational and angular acceleration of
the body, or, if body to body interactions are being
considered, a (6 x n) vector of all the body
accelerations.
Outputs¶
F_AddedMass¶
force due to added mass
adjustMassMatrix¶
Summary¶
Merges diagonal term of added mass matrix to the mass matrix
Syntax¶
adjustMassMatrix (hb)
Description¶
adjustMassMatrix performs the following tasks in preparation
for a simulation:
* Stores the original mass and added-mass properties
* Adds diagonal added-mass inertia to moment of inertia
* Adds the maximum diagonal translational added-mass to body
mass
Inputs¶
hb¶
wsim.hydroBody object
advanceStep¶
Summary¶
advance to the next time step, accepting the current time step and data into stored solution histories
Syntax¶
advanceStep (hb, t, vel, accel)
Description¶
advanceStep must be called at the end of each integration
time step to update the history of the solution. This is
required for the radiation forces when using either the
convolution integral method, or the state-space integration
using the default internal integration provided by this class
(invoked with simu.ssCalc = 1).
Inputs¶
hb¶
hydroBody object
vel¶
vector of velocities and angular velocities, of size
(6 x 1) if there is no body to body interaction (just the
velocities of this body), or size (6*nbodies x 1) if there
is body to body interaction (the velocities of all bodies
in the system).
accel¶
vector of accelerations and angular accelerations,
of size (6 x 1) if there is no body to body interaction
(just the velocities of this body), or size (6*nbodies x
1) if there is body to body interaction (the accelerations
of all bodies in the system).
bodyGeo¶
Summary¶
Reads an STL mesh file and calculates areas and centroids
Syntax¶
bodyGeo (hb, fname)
Description¶
bodyGeo
Inputs¶
hb¶
wsim.hydroBody object
fname¶
(optional) full path to the STL file to be loaded.
If not supplied, the file specified in the body's
geometryFile property (and expected to be in the 'geometry'
folder of the simulation case directory) will be used.
forceAddedMass¶
Summary¶
Recomputes the real added mass force time history for the body
Syntax¶
fam = forceAddedMass(hb,acc,B2B)
Inputs¶
hb¶
hydroBody object
acc¶
(n x 6) time history of body accelerations for which
the added mass is to be recalculated
B2B¶
flag indicating whether body-to-body interactions are
present
Outputs¶
fam¶
added mass recalculated from time history of
accelerations and body added mass.
hydroForcePre¶
Summary¶
performs pre-processing calculations to populate hydroForce structure
Syntax¶
hydroForcePre (hb)
Description¶
hydroForcePre performs various pre-processing calulations in
prepration for a simulation. It populates the hydroForce
property of the hydroBody as a structure with the linear
hydrodynamic restoring coefficient, viscous drag, and linear
damping matrices, and also sets the wave excitation force
calculation method from the specified wave type.
Inputs¶
hb¶
wsim.hydroBody object
hydroForces¶
Summary¶
hydroForces calculates the hydrodynamic forces acting on a body
Syntax¶
[forces, breakdown] = hydroForces (hb, t, x, vel, accel, elv)
Inputs¶
hb¶
hydroBody object
pos¶
(6 x 1) displcement of this body in x,y and z and
rotatation around the x, y and z axes
vel¶
(6 x n) velocities of all bodies in system
accel¶
(6 x n) acceleration of all bodies in system
Outputs¶
forces¶
(6 x 1) forces and moments acting on the body
breakdown¶
structure containing more detailed
breakdown of the forces acting on the body. The fields
present depend on the simulation settings and can include
the following:
F_ExcitLin :
F_Excit :
F_ExcitRamp :
F_ViscousDamping :
F_AddedMass :
F_RadiationDamping :
F_Restoring :
BodyHSPressure :
F_ExcitNonLin :
WaveNonLinearPressure :
WaveLinearPressure :
F_MorrisonElement :
linearDampingForce¶
Summary¶
forces = obj.hydroForce.linearDamping * vel; linear damping is always a diagonal matrix, so just multiply the values along the diagonal
linearExcitationForces¶
Summary¶
calculates linear wave excitation forces during transient simulation
Syntax¶
forces = linearExcitationForces (obj, t)
Inputs¶
linearInterp¶
Summary¶
linearInterp simple linear interpolation with no input checking
Syntax¶
v = wsim.hydroBody.linearInterp (x1, x2, y1, y2, u)
Description¶
wsim.hydroBody.linearInterp returns a simple linear
interpolation with extrapolation without any input checking
for speed. A linear function is created from two input data
points on the line, (x1,y1) and (x2,y2).
Inputs¶
x1¶
x coordinate of first data point on line
x2¶
x coordinate of second data point on line
y1¶
y coordinate of first data point on line
y2¶
y coordinate of second data point on line
Outputs¶
See Also¶
loadHydroData¶
Summary¶
load hydrodynamic data from file or variable
Syntax¶
loadHydroData (obj)
loadHydroData (obj, filename)
loadHydroData (obj, hydroData)
Description¶
Loads hydrodynamic data from a .mat file, .h5 file or
directly from a matlab structure.
Inputs¶
hg¶
wsim.hydroBody object
filename¶
character vector containing the full path of the
file from which to load the hydrodynamic data. Can be
either a .h5 file or a .mat file. If a .mat file it must
contain all the fields expected to be in the hydroBody
hydroData property. This file can also be created using the
wsim.hydroBody.saveHydroData method.
hydroData¶
structure containing the data which is loaded
directly into the hydrBody's hydroData property
See Also¶
wsim.hydroBody.saveHydroData
makeMBDynComponents¶
Summary¶
creates mbdyn components for the hydroBody
Syntax¶
[node, body] = makeMBDynComponents (obj)
Description¶
makeMBDynComponents creates a node and body element for use
in an MBDyn multibody dynamics simulation. Requires the MBDyn
toolbox.
Inputs¶
hg¶
wsim.hydroBody object
Outputs¶
node¶
mbdyn.pre.structuralNode6dof object represetning an
inertial node located at the centre of gravity of the body.
body¶
mbdyn.pre.body object attached to the node and with
the appropriate mass and inertial proerties for the
hydroBody.
morrisonElementForce¶
Summary¶
TODO: in WEC-Sim morrison element stuff uses acceleration delay like added mass forces
radForceODEOutputfcn¶
Summary¶
OutputFcn to be called after every completed ode time step when using the state-space representation of the radiation forces
Syntax¶
radForceODEOutputfcn (hb, t, x, flag)
Inputs¶
hb¶
hydroBody oject
radForceSSDerivatives¶
Summary¶
wsim.hydroBody/radForceSSDerivatives is a function. statederivs = radForceSSDerivatives(obj, u)
radiationDampingForces¶
Summary¶
calculates the wave radiation forces
Syntax¶
F_RadiationDamping = radiationForces (obj, t, vel, accel)
Inputs¶
vel¶
(6 x 1) translational and angular velocity of the
body, or, if body to body interactions are being
considered, a (6 x n) vector of all the body
velocities.
Outputs¶
F_RadiationDamping¶
force due to wave radiation damping
readH5File¶
Summary¶
Reads an HDF5 file containing the hydrodynamic data for the body
Syntax¶
readH5File(hb)
Description¶
readH5File reads the HDF5 file containing the hydrodynamic
data for the body and stores it in the body properties. The
file location is expected to be in the case directory
provided on construction of the object.
Generating the hydrodynamic data:
The hydroBody requires frequency-domain hydrodynamic
coefficients (added mass, radiation damping, and wave
excitation). Typically, these hydrodynamic coefficients for
each body of the WEC device are generated using a boundary
element method (BEM) code (e.g., WAMIT, NEMOH or AQWA). The
HDF5 file must then be generated from the output of these
codes.
Create HDF5 file:
readH5File reads the hydrodynamic data in HDF5 format from
the (<hydrodata_file_name>.h5) file provided when the object
was constructed. A helper tool, BEMIO, is available to parse
BEM solutions (from WAMIT, NEMOH and AQWA) into the required
HDF5 data structure.
Inputs¶
hb¶
hydroBody object
rotateXYZ¶
Summary¶
Function to rotate a point about an arbitrary axis x: 3-componenet coordinates ax: axis about which to rotate (must be a normal vector) theta: rotation angle xn: new coordinates after rotation
saveHydroData¶
Summary¶
saves the body’s hydrodata structure to a .mat file
Syntax¶
saveHydroData (hb, filename)
saveHydroData (..., 'Parameter', Value)
Description¶
saveHydroData saves the body's hydroData structure to a .mat
file for later use. This avoids having to read the .h5 file.
By default saveHydroData saves the file in the hydroData
subdirectory of the case directory. The 'Directory' option
may be used to change this behaviour.
Inputs¶
hb¶
wsim.hydroBody object
filename¶
name withput path of the .mat file in which to
save the hydrobody hydroData structure contents.
Additional arguments may be supplied as parameter-value pairs:
Directory¶
optional alternative directory in which to
save the .mat file instead of the hydroData subdirectory
of the simulation case directory.
See Also¶
setCaseDirectory¶
Summary¶
set the case directory for the simulation the body is part of
Syntax¶
setCaseDirectory (hb, case_directory)
Description¶
setCaseDirectory sets the path to the case directory of the
simulation of which the hydroBody is a part. This is intended
to be called by the wsim.hydroSystem to which the body is
added, rather than called by a user directly. The case
directory should contain two subdirectories, 'hydroData' and
'geometry'. The hydroData directory should contain the .h5
file or .mat file containing the hydrodynamic data for the
body using a BEM solver and the BEMIO functions. The geometry
folder should contain any STL file describing the geometry of
the body.
Inputs¶
hb¶
a wsim.hydroBody object
case_directory¶
character vector containing the full path
to the case directory of the simulation.
See Also¶
timeDomainSimReset¶
Summary¶
resets the body in readiness for a transient simulation
Syntax¶
timeDomainSimReset (hb)
Desciription
timeDomainSimReset resets various internal storeage parameters and
settings in preparation for performing a transient simulation
based on the ODE solver routines, returning the hydroBody to
the state it is in just after calling timeDomainSimSetup. This
should be called before re-running a transient simulation
with the same parameters.
Inputs¶
hb¶
hydroBody object
timeDomainSimSetup¶
Summary¶
sets up the body in preparation for a transient simulation
Syntax¶
timeDomainSimSetup (hb, waves, simu, bodynum)
Desciription
timeDomainSimSetup initialises various parmaters and settings in
preparation for performing a transient simulation based on
the ODE solver routines.
Inputs¶
hb¶
hydroBody object
waves¶
waveClass object with the desired wave parameters
to be used in the simulation
simu¶
simulationClass Object with the desired simulation
parameters to be used in the simulation
bodynum¶
the number associated with this body. Typically
this is generated by a parent hydrosys object
vcross¶
Summary¶
Vector cross product for multiple 3 element vectors
Syntax¶
o = wsim.hydroBody.vcross (v1, v2)
Description¶
Inputs¶
v1¶
(3 x n) matrix where the rows are each 3 element
vectors
v2¶
(3 x n) matrix where the rows are each 3 element
vectors
Outputs¶
viscousDamping¶
Summary¶
wsim.hydroBody/viscousDamping is a function. forces = viscousDamping(obj, vel)