Class: wsim.wecSim¶
wsim.wecSim is a class which manages wave energy converter
simulations.
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¶
- absForceTolerance
- absMomentTolerance
- caseDirectory
- hydroSyncMinSteps
- hydroSystem
- lastAccelerations
- lastAngularAccelerations
- lastAngularPositions
- lastAngularVelocities
- lastForceAddedMass
- lastForceAddedMassUncorrected
- lastForceExcitation
- lastForceExcitationLin
- lastForceExcitationNonLin
- lastForceExcitationRamp
- lastForceHydro
- lastForceIterations
- lastForceMorrison
- lastForceRadiationDamping
- lastForceRestoring
- lastForceViscousDamping
- lastMomentAddedMass
- lastMomentAddedMassUncorrected
- lastMomentExcitation
- lastMomentExcitationLin
- lastMomentExcitationNonLin
- lastMomentExcitationRamp
- lastMomentHydro
- lastMomentMorrison
- lastMomentRadiationDamping
- lastMomentRestoring
- lastMomentViscousDamping
- lastNodeForcesUncorrected
- lastNodeMomentsUncorrected
- lastPositions
- lastTime
- lastVelocities
- logger
- loggingSettings
- mBDynInputFile
- mBDynOutputFile
- mBDynSystem
- maxForceIterations
- minForceIterations
- powerTakeOffs
- prevForceAndMomentsHydro
- prevTime
- readyToRun
- relForceTolerance
- showProgress
- simComplete
- simInfo
- simStarted
- stepCount
- wavePlotDomainSize
- wavePlotNumPointsX
- wavePlotNumPointsY
- wecController
absForceTolerance¶
absolute tolerance on the forces for convergence
absMomentTolerance¶
absolute tolerance on the moments for convergence
caseDirectory¶
hydroSyncMinSteps¶
hydroSystem¶
lastAccelerations¶
last calculated accelerations
lastAngularAccelerations¶
last calculated angular accelerations
lastAngularPositions¶
last calculated angular positions (euler angles)
lastAngularVelocities¶
last calculated angular velocities
lastForceAddedMass¶
last calculated value of hydrodynamic forces due to added mass (corrected)
lastForceAddedMassUncorrected¶
last calculated value of hydrodynamic forces due to added mass (uncorrected)
lastForceExcitation¶
last calculated value of all hydrodynamic excitation forces
lastForceExcitationLin¶
last calculated value of hydrodynamic linear excitation forces
lastForceExcitationNonLin¶
last calculated value of hydrodynamic nonlinear excitation forces
lastForceExcitationRamp¶
last calculated value of all hydrodynamic excitation forces with applied ramp
lastForceHydro¶
last calculated total of all hydrodynamic forces
lastForceIterations¶
Number of iterations in the last time step
lastForceMorrison¶
last calculated value of hydrodynamic morrison forces
lastForceRadiationDamping¶
last calculated value of hydrodynamic radiation damping forces
lastForceRestoring¶
last calculated value of hydrodynamic restoring (buoyancy) forces
lastForceViscousDamping¶
last calculated value of hydrodynamic viscous damping forces
lastMomentAddedMass¶
last calculated value of hydrodynamic moments due to added mass (corrected)
lastMomentAddedMassUncorrected¶
last calculated value of hydrodynamic moments due to added mass (uncorrected)
lastMomentExcitation¶
last calculated value of all hydrodynamic excitation moments
lastMomentExcitationLin¶
last calculated value of hydrodynamic linear excitation moments
lastMomentExcitationNonLin¶
last calculated value of hydrodynamic nonlinear excitation moments
lastMomentExcitationRamp¶
last calculated value of all hydrodynamic excitation moments with applied ramp
lastMomentHydro¶
last calculated total of all hydrodynamic moments
lastMomentMorrison¶
last calculated value of hydrodynamic morrison moments
lastMomentRadiationDamping¶
last calculated value of hydrodynamic radiation damping moments
lastMomentRestoring¶
last calculated value of hydrodynamic restoring (buoyancy) moments
lastMomentViscousDamping¶
last calculated value of hydrodynamic viscous damping moments
lastNodeForcesUncorrected¶
last calculated value ofcombined forces but with uncorrected added mass forces
lastNodeMomentsUncorrected¶
last calculated value ofcombined moments but with uncorrected added mass forces
lastPositions¶
last calculated cartesian positions
lastTime¶
lastVelocities¶
last calculated velocites
logger¶
wsim.logger object containing the logged simulation data from the current or most recent sim
loggingSettings¶
mBDynInputFile¶
mBDynOutputFile¶
mBDynSystem¶
maxForceIterations¶
maximum number of iteration allowed before convergence
minForceIterations¶
minimum number of iterations which will be performed at each time step
powerTakeOffs¶
prevForceAndMomentsHydro¶
prevTime¶
readyToRun¶
relForceTolerance¶
relative tolerance on the forces for convergence
showProgress¶
true/false flag indicating whether a progress bar will be shown
simComplete¶
true/false flag indicating whether the simulation is finished (i.e. simFinish has been called)
simInfo¶
- structure containing information about the simulation
The structure is populated when simStart is called (or the run method, which ultimately calls simStart). It will contain the following fields:
TStart : the simulation initial time
TEnd : the simulation end time
TStep : the magnitude of the time step of the simulation
- MBDynSystem : the mbdyn.pre.system object representing the
- multibody system
- HydroSystem : wsim.hydroSystem object representing the
- hydrodynamic interaction system
HydroMotionSyncSteps :
- OutputDirectory : the location of the directory where results
- will be output
- CaseDirectory : the directory containing the case information
- for the simulation
simStarted¶
true/false flag indicating whether the simulation has started (i.e. simStart had been called)
stepCount¶
wavePlotDomainSize¶
wavePlotNumPointsX¶
wavePlotNumPointsY¶
wecController¶
Methods¶
- wecSim
- addPTO
- animate
- drawStep
- prepare
- run
- simFinish
- simStart
- simStep
- simSteps
- wavePlot3D
wecSim¶
Summary¶
wsim.wecSim constructor
Syntax¶
wsobj = wsim.wecSim (hsys, mbsys)
wsobj = wsim.wecSim (..., 'Parameter', Value)
Description¶
wsim.wecSim is a class which manages wave energy converter
simulations.
Inputs¶
hsys¶
a wsim.hydroSystem object
PTOs¶
optional scalar wsim.powerTakeOff object or a cell
array of multiple wsim.powerTakeOff objects (or derived
objects). The wsim.powerTakeOff class is used to simplify
the calculation of forces and moments for the multibody
simulation and make it easier to apply them in the
multibody simulation with the correct directions etc.
Rather than using the basic wsim.powerTakeOff class,
usually a derived class such as wsim.rotaryPowerTakeOff or
wsim.linearPowerTakeOff is used. See the help for these
classes for more information.
LoggingSettings¶
optional wsim.loggingSettings object.
wsim.loggingSetting is a small class which holds the
settings determining what is logged during the simulation.
The simulation data is stored in a wsim.logger object. The
logger object for a simulation is returned by the 'run'
method. See the help for both wsim.loggingSettings and
wsim.logger for more information. If the LoggingSettings
option is not used a new loggingSettings object is created
internally with all logging turned off.
Controller¶
optional wsim.wecController or derived
object. This is a controller, usually also used in
conjuction with a PTO which also accepts a controller
object as input (e.g. wsim.linearPTOWithController). The
same controller must be given to both the PTO and the
wsim.wecSim object. The controller will be given access to
the wsim.wecSim object in which is resides, so it will
have access to the data log via the logger property of the
wsim.wecSim object.
Outputs¶
wsobj¶
wsim.wecSim
See Also¶
wsim.loggingSettings, mbdyn.pre.system
addPTO¶
Summary¶
add one or more PTO objects to a simulation
Syntax¶
addPTO (wsobj, pto)
Description¶
addPTO adds one or more wsim.powerTakeOff (or derived)
objects to a wsim.wecSim simulation. The wsim.powerTakeOff
class is used to simplify the calculation of forces and
moments for the multibody simulation and make it easier to
apply them in the multibody simulation with the correct
directions etc. Rather than using the basic wsim.powerTakeOff
class, usually a derived class such as
wsim.rotaryPowerTakeOff or wsim.linearPowerTakeOff is used.
See the help for these classes for more information.
Inputs¶
wsobj¶
wsim.wecSim object
pto¶
wsim.powerTakeOff object (or derived object), or a
cell array of wsim.powerTakeOff objects.
See Also¶
wsim.linearPowerTakeOff
animate¶
Summary¶
animate the wave energy system
Syntax¶
animate (wsobj, 'Parameter', value)
Inputs¶
PlotAxes¶
handle to plot axes in which to draw the
trajectories. If not supplied a new figure and axes are
created for the plot.
AxLims¶
(3 x 2) matrix containing limits the plot axes
should be set to, each row is the x, y and z axes limits
respectively. Uselful to focus on a particular region of
the system. If not supplied, suitable axes limits will be
determined based on the motion data.
Title¶
flag determining whether to add a title to the
system plot. Default is false.
DrawMode¶
string indicating the drawing mode. Can be one
of: 'solid', 'ghost', 'wire', 'wireghost'.
DrawLabels¶
flag indicating whether to draw node labels,
default is false.
DrawNodes¶
flag determining whether to draw nodes,
default is true
DrawBodies¶
flag determining whether to draw bodies,
default is true.
OnlyNodes¶
vector of indices of nodes to plot, only these
nodes will be plotted. By default all nodes are plotted if
'DrawNodes' is true. This setting is ignored if
'DrawNodes' is false.
Light¶
flag determining whether to light the scene to
give a more realistic look. Best used with 'solid' option.
NodeSize¶
scalar value indicating how large the nodes
should be drawn (in the same units as the plot). If not
supplied, the nodes are drawn with a size based on the
axes limits.
ExternalDrawFcn¶
function handle or string with function
which will be called after drawing the scene is complete.
Intended to be used by external programs to add their own
features to the scene. The funciton must take two
arguments, the first is the handle to the axes contining
the plot, the second is the time step index of the
simulation.
View¶
viewpoint of plot in the same format as any of the
single input styles of the 'view' function. See output of
'help view' for more information. The contents of the
'View' option is passed directly to the view function to
set the axes view.
FigPositionAndSize¶
figure position and size as a four
element vector in the same format as a figure's 'Position'
property, i.e. [ x, y, w, h ] where x and y are the
coordinates of the lower left corner of the figure and w
and h are the height and width respectively.
VideoFile¶
optional file name into which the aimation
will be saved as a video. Default is empty, in which case
no video file will be produced unless a VideoWriter object
is supplied instead through the 'VideoWriter' option (see
below).
VideoWriter¶
optional VideoWriter object which will be
used to create a video instead of creating one internally.
This option cannot be used at the same time as the
'VideoFile' option. If this option is used, the
VideoProfile option (see below) is ignored. However,
animate will still modify the FrameRate property orf the
supplied VideoWriter object internally, and the VideoSpeed
option (see below) will also be applied. Default is empty,
in which case no video file will be produced unless a
video file path is supplied instead through the
'VideoFile' option (see above).
VideoSpeed¶
optional speed multiplier for the video when
using the 'VideoFile'or 'VideoWriter' option. It must be a
scalar value greater than 0. The animation will play a
speed multiplied by this factor (by changing the video
frame rate) rather than real time. Default is 1 (no
speedup).
VideoProfile¶
optional character vector indicating what
type of video compression to use when using the
'VideoFile' option. This option coresponds to the profile
option for the VideoWrite class, soo see the help for
VideoWriter to see what the possible options are. Default
is 'Motion JPEG AVI'.
drawStep¶
Summary¶
draw the system at the given time step index
Syntax¶
plotdata = drawStep (wsobj, tind, 'Parameter', value)
Inputs¶
PlotAxes¶
handle to plot axes in which to draw the
trajectories. If not supplied a new figure and axes are
created for the plot.
AxLims¶
(3 x 2) matrix containing limits the plot axes
should be set to, each row is the x, y and z axes limits
respectively. Uselful to focus on a particular region of
the system. If not supplied, suitable axes limits will be
determined based on the motion data.
Title¶
flag determining whether to add a title to the
system plot. Default is true.
DrawMode¶
string indicating the drawing mode. Can be one
of: 'solid', 'ghost', 'wire', 'wireghost'.
DrawLabels¶
flag indicating whether to draw node labels,
default is false.
DrawNodes¶
flag determining whether to draw nodes,
default is true
DrawBodies¶
flag determining whether to draw bodies,
default is true.
OnlyNodes¶
vector of indices of nodes to plot, only these
nodes will be plotted. By default all nodes are plotted if
'DrawNodes' is true. This setting is ignored if
'DrawNodes' is false.
Light¶
flag determining whether to light the scene to
give a more realistic look. Best used with 'solid' option.
NodeSize¶
scalar value indicating how large the nodes
should be drawn (in the same units as the plot). If not
supplied, the nodes are drawn with a size based on the
axes limits.
View¶
viewpoint of plot in the same format as any of the
single input styles of the 'view' function. See output of
'help view' for more information. The contents of the
'View' option is passed directly to the view function to
set the axes view.
FigPositionAndSize¶
figure position and size as a four
element vector in the same format as a figure's 'Position'
property, i.e. [ x, y, w, h ] where x and y are the
coordinates of the lower left corner of the figure and w
and h are the height and width respectively.
Outputs¶
hfig¶
handle to figure created
hax¶
handle to plot axes created
prepare¶
Summary¶
prepare the wsim.wecSim simulation so it is ready to run
Syntax¶
prepare (wsobj)
Description¶
prepare performs various preprocessing taks to get the
simulation into a state where it is ready to be run. prepare
must be called before the run method is called.
Inputs¶
wsobj¶
wsim.wecSim object
See Also¶
run¶
Summary¶
Run entire the WEC simulation
Syntax¶
[datalog, mbdyn_postproc] = run (wsobj)
[datalog, mbdyn_postproc] = run (..., 'Parameter', Value)
Description¶
run runs the wsim.wecSim simulation to completion without
stopping.
This is a shortcut for calling simStart, then calling simStep
or simSteps until the simulation is finished and then calling
simFinish. The run method is used when no interaction is
required during the simulation, and is the most common way of
running a simulation.
Inputs¶
MBDynInputFile¶
optional character vector containing the
full path which should be used for the MBDyn input file.
If not supplied, a default file name will generated with
the extension '.mbd' and placed in the outut directory.
Verbosity¶
flag controlling how much text output is
produced at the command line during simulation, and in the
MBDyn output file during the simulation. Verbosity should
be a scalar integer. The higher the value, the more output
will be produced. Default is 0, indicating the minimum
amount of output. The value of verbosity adds that umber
of -p input arguments to the command line used to launch
MBDyn (more -p inputs means more verbose output, see the
documentation for MBDYn for more information).
AbsForceTolerance¶
positive scalar value representing the
absolute tolerance on the forces applied. The system is
solved iteratively with forces and motion being
recalculated repeatedly until convergence is achieved.
This is the smallest absolute change possible before the
force calculation is considered to be converged. Default
is 100N if not supplied.
RelForceTolerance¶
positive scalar value representing the
relative tolerance on the forces applied. The system is
solved iteratively with forces and motion being
recalculated repeatedly until convergence is achieved.
This is the smallest change possible in the force relative
to it's absolute value before the force calculation is
considered to be converged. Default is 1e-5 if not
supplied.
MinIterations¶
scalar integer indicating the minimum
number of iterations of the force/motion calculation which
should be performed. Default is 0.
TimeExecution¶
true/false flag indicating whether to time
the execution of the simulation and report it at the end
of the sim.
ForceMBDynNetCDF¶
true/false flag indicating whether to
ensure MBDyn will generate a netcdf format output file by
modifying the supplied mbdyn.pre.system object
OutputResults setting in the control data (if necessary).
Default is true.
OutputFilePrefix¶
character vector containing the output
path prefix. This
is the name of output files, but without their file
extension. e.g. /home/jbloggs/my_mbdyn_sim will create the
files:
/home/jbloggs/my_mbdyn_sim.frc
/home/jbloggs/my_mbdyn_sim.ine
/home/jbloggs/my_mbdyn_sim.out
/home/jbloggs/my_mbdyn_sim.mov
/home/jbloggs/my_mbdyn_sim.jnt
/home/jbloggs/my_mbdyn_sim.log
and/or possibly a netcdf format file:
/home/jbloggs/my_mbdyn_sim.nc
A windows example might look like
C:\Users\IEUser\Documents\my_mbdyn_sim
producing the files:
C:\Users\JBloggs\Documents\my_mbdyn_sim.frc
C:\Users\JBloggs\Documents\my_mbdyn_sim.ine
C:\Users\JBloggs\Documents\my_mbdyn_sim.out
C:\Users\JBloggs\Documents\my_mbdyn_sim.mov
C:\Users\JBloggs\Documents\my_mbdyn_sim.jnt
C:\Users\JBloggs\Documents\my_mbdyn_sim.log
and/or:
C:\Users\JBloggs\Documents\my_mbdyn_sim.nc
The netcdf format is preferred for the mbdyn.postproc
class output in the mbdy_postproc variable. By default
wsim.wecSim will force the output of a netcdf format file
(see the ForceMBDynNetCDF output above).
MaxIterations¶
optionaL scalar integer indicating the
maximum number of interations which should be performed in
any simulation step. If this number of iterations is
exceeded, the simulation will simply advance anyway using
the last set of forces calculated, regardless of meeting
tolerances etc. so this option should be used with care.
Default is Inf, so there is no limit to the number of
iterations that will be performed.
TimeExecution¶
optional true/false flag indicating
whether to time the execution of the simulation. Default
is false.
ShowProgress¶
optional true/false flag indicating
whether to show the percentage simulation complete using a
text based progress bar in the command window.
Outputs¶
datalog¶
wsim.logger object containing the logged data (if
any) from the simulation.
mbdyn_postproc¶
mbdyn.postproc object which can be used to
access the full output for all joints and elements from
MBDyn produced during the simulation. See the help for
mbdyn.postproc for more information.
See Also¶
simStart¶
Summary¶
Start a WEC simulation
Syntax¶
[datalog, mbdyn_postproc] = simStart (wsobj)
[datalog, mbdyn_postproc] = simStart (..., 'Parameter', Value)
Description¶
simStart starts wsim.wecSim simulation, performing the
initial time step.
Inputs¶
MBDynInputFile¶
optional character vector containing the
full path which should be used for the MBDyn input file.
If not supplied, a default file name will generated with
the extension '.mbd' and placed in the outut directory.
Verbosity¶
flag controlling how much text output is
produced at the command line during simulation, and in the
MBDyn output file during the simulation. Verbosity should
be a scalar integer. The higher the value, the more output
will be produced. Default is 0, indicating the minimum
amount of output. The value of verbosity adds that umber
of -p input arguments to the command line used to launch
MBDyn (more -p inputs means more verbose output, see the
documentation for MBDYn for more information).
AbsForceTolerance¶
positive scalar value representing the
absolute tolerance on the forces applied. The system is
solved iteratively with forces and motion being
recalculated repeatedly until convergence is achieved.
This is the smallest absolute change possible before the
force calculation is considered to be converged. Default
is 100N if not supplied.
RelForceTolerance¶
positive scalar value representing the
relative tolerance on the forces applied. The system is
solved iteratively with forces and motion being
recalculated repeatedly until convergence is achieved.
This is the smallest change possible in the force relative
to it's absolute value before the force calculation is
considered to be converged. Default is 1e-5 if not
supplied.
MinIterations¶
scalar integer indicating the minimum
number of iterations of the force/motion calculation which
should be performed. Default is 0.
TimeExecution¶
true/false flag indicating whether to time
the execution of the simulation and report it at the end
of the sim.
ForceMBDynNetCDF¶
true/false flag indicating whether to
ensure MBDyn will generate a netcdf format output file by
modifying the supplied mbdyn.pre.system object
OutputResults setting in the control data (if necessary).
Default is true.
OutputFilePrefix¶
character vector containing the output
path prefix. This
is the name of output files, but without their file
extension. e.g. /home/jbloggs/my_mbdyn_sim will create the
files:
/home/jbloggs/my_mbdyn_sim.frc
/home/jbloggs/my_mbdyn_sim.ine
/home/jbloggs/my_mbdyn_sim.out
/home/jbloggs/my_mbdyn_sim.mov
/home/jbloggs/my_mbdyn_sim.jnt
/home/jbloggs/my_mbdyn_sim.log
and/or possibly a netcdf format file:
/home/jbloggs/my_mbdyn_sim.nc
A windows example might look like
C:\Users\IEUser\Documents\my_mbdyn_sim
producing the files:
C:\Users\JBloggs\Documents\my_mbdyn_sim.frc
C:\Users\JBloggs\Documents\my_mbdyn_sim.ine
C:\Users\JBloggs\Documents\my_mbdyn_sim.out
C:\Users\JBloggs\Documents\my_mbdyn_sim.mov
C:\Users\JBloggs\Documents\my_mbdyn_sim.jnt
C:\Users\JBloggs\Documents\my_mbdyn_sim.log
and/or:
C:\Users\JBloggs\Documents\my_mbdyn_sim.nc
The netcdf format is preferred for the mbdyn.postproc
class output in the mbdy_postproc variable. By default
wsim.wecSim will force the output of a netcdf format file
(see the ForceMBDynNetCDF output above).
MaxIterations¶
optionaL scalar integer indicating the
maximum number of interations which should be performed in
any simulation step. If this number of iterations is
exceeded, the simulation will simply advance anyway using
the last set of forces calculated, regardless of meeting
tolerances etc. so this option should be used with care.
Default is Inf, so there is no limit to the number of
iterations that will be performed.