Local-wave vessel

Heave, roll and pitch of a vessel driven by the wave elevation sampled under its hull.

Collaboration diagram for Local-wave vessel:

A time-domain seakeeping model for small vessels (fishing vessels, workboats, USVs) that responds to the free-surface elevation of the environment's wave field: regular or irregular waves, several wave trains. It needs no frequency-domain data. The horizontal position and heading come from the input ports, so a manoeuvring model (e.g. Vessels/Tanker in fhsim_base, whose Position and Rotation connect directly) or a prescribed track drives it, and the encounter frequency follows from sampling at the instantaneous position.

Equations

States q = (z, phi, theta): heave [m], positive down (NED); roll [rad], positive starboard down; pitch [rad], positive bow up. With the generalized wave load F (filtered, below):

(M + A) q'' + B q' + D(q') + C q = F

• Heave and pitch are coupled through A35, B35 and C35; roll is independent.
• M = diag(Mass, RollInertia, PitchInertia); A = diag(A33, A44, A55) plus A35.
• C33 = Rho g WaterplaneArea, C44 = Mass g GMT, C55 = Mass g GML, and C35 = -Rho g WaterplaneArea Lcf (zero when the centre of flotation is at the CG). Given RollPeriod instead of GMT, C44 = (RollInertia + A44) (2 pi / RollPeriod)^2; likewise for pitch.
• B = diag(c33, c44, c55) plus B35, with c = 2 zeta sqrt(C (M + A)) per mode.
• D = (0, RollQuadraticDamping |phi'| phi', 0): bilge-keel and viscous roll losses.

Wave excitation

N sample points with equal weights w = WaterplaneArea / N represent the waterplane, a Length x Breadth rectangle centred on the centre of flotation (Lcf forward of the CG). Each point i, at body coordinates (x_i, y_i) from the CG, samples the elevation eta_i (positive up). Only the heading rotates the points; roll and pitch are taken as small. The raw loads are the hydrostatic buoyancy of the elevation field:

Fz     = -Rho g sum(w eta_i)       (down)
Mphi   = -Rho g sum(w eta_i y_i)
Mtheta =  Rho g sum(w eta_i x_i)

They pass a first-order filter, tau F' + F = F_raw, which smooths high-frequency excitation.

The points are placed so that their mean and second moments are exactly those of the rectangle (sum w x^2 = WaterplaneArea Length^2 / 12 about the centre of flotation, likewise across): SampleLevel 2, 3 and 4 are n x n grids, n = 3, 5, 7, with spacing d = span / sqrt(n^2 - 1); level 1 is the centre and four arms at d = sqrt(5/24) span.

Short waves

The averaging over the points attenuates waves down to about twice the spacing d. Shorter waves are not resolved: at a wavelength of d, all points along that axis are in phase and the vessel feels the full buoyancy of the wave (aliasing). Along the length:

SampleLevel	Points	d / Length	Shortest resolved (2 d)	Aliased at (d)
1	5	0.456	0.91 L	0.46 L
2	9	0.354	0.71 L	0.35 L
3	25	0.204	0.41 L	0.20 L
4	49	0.144	0.29 L	0.14 L

For a 20 m vessel at level 2 waves below 14 m (deep-water period 3.0 s) are not resolved and 7 m waves (2.1 s) alias. This is a known model limitation; there is no wavelength filter. Choose the level so the sea holds little energy below 2 d, or use a wave field without components that short.

Review issues:

0354 — LocalWaveVessel aliases waves shorter than twice the sample spacing

Model notes

• The long-wave limit is quasi-static and does not depend on the level: in a uniform wave slope s along x, pitch settles at theta = s (WaterplaneArea Length^2 / 12) / (Mass GML / Rho), so the vessel follows the slope when Mass GML / Rho is the waterplane's second moment WaterplaneArea Length^2 / 12. The same holds for roll with Breadth and GMT.
• The plan's curvature corrections are left out: curvature is even in x and y and the pitch and roll moments are odd, so they would give the same moment in mirror-image seas.
• The Excitation state starts at its initial condition (default 0), not at the wave load at the start time, so the first few FilterTimeConstant show a start-up transient.
• Cost: N elevation queries per right-hand-side evaluation, N = 5, 9, 25 or 49.
• OdeJacobian is complete for the states; the input ports and the wave field are held fixed.

Visualization

The hull is drawn as a prism over the Length x Breadth waterplane (centred on the centre of flotation) with a pointed bow over the forward quarter, from the draught Mass / (Rho WaterplaneArea) below the waterline to the same height above it. It follows the Position and Rotation outputs. The drawing is indicative only; the model sees the rectangle.

Example configuration excerpt

<Lib
  LibName              = "marine_elements"
  SimObject            = "Vessel/LocalWaveVessel"
  Name                 = "Boat"
  Length               = "20"
  Breadth              = "6"
  WaterplaneArea       = "96"
  Mass                 = "150000"
  RollInertia          = "6.0e5"
  PitchInertia         = "4.5e6"
  A33                  = "1.5e5"
  A44                  = "1.2e5"
  A55                  = "4.5e6"
  GMT                  = "0.8"
  GML                  = "25"
  RollQuadraticDamping = "2.0e5"
/>
<Lib
  LibName              = "environment"
  SimObject            = "Environment"
  Name                 = "Env"
  Waves.Spectrum       = "JONSWAP"
  Waves.Theory         = "Airy"
  Waves.Hs             = "1"
  Waves.NumWaves       = "30"
/>
...
<Connection
  Boat.Position = "0,0,0"
  Boat.Rotation = "0,0,0"
/>
...
<InitialCondition
  Boat.Motion     = "0,0,0"
  Boat.MotionRate = "0,0,0"
  Boat.Excitation = "0,0,0"
/>

Input Ports

Name	Width	Description
Position	3	NED position of the CG [m]. North and east place the sample points; down is not used.
Rotation	3	Only the third component is used: the heading psi [rad], from north towards east (as the Rotation output of Vessels/Tanker).

Output Ports

Name	Width	Description
Motion	3	The Motion state: heave [m, down], roll [rad, starboard down], pitch [rad, bow up].
MotionRate	3	The MotionRate state.
Excitation	3	The Excitation state: filtered heave force [N, down], roll and pitch moments [N m].
Position	3	NED position of the CG: north and east of the Position input, down = heave [m].
Rotation	3	Euler angles (roll, pitch, heading) [rad]: the roll and pitch states and the input heading.

Configuration parameters

The model needs the shared Environment (an environment Environment object); without waves it stays in calm water.

Name	Width	Description
Length	1	Waterplane length [m]. Required.
Breadth	1	Waterplane breadth [m]. Required.
WaterplaneArea	1	Waterplane area [m^2] (Default: Length * Breadth).
Lcf	1	Longitudinal position of the centre of flotation forward of the CG [m] (Default: 0).
Mass	1	Displacement [kg]. Required.
RollInertia	1	Roll moment of inertia about the CG [kg m^2]. Required.
PitchInertia	1	Pitch moment of inertia about the CG [kg m^2]. Required.
A33	1	Heave added mass [kg]. Required.
A44	1	Roll added moment of inertia [kg m^2]. Required.
A55	1	Pitch added moment of inertia [kg m^2]. Required.
A35	1	Heave-pitch added-mass coupling [kg m] (Default: 0).
B35	1	Heave-pitch damping coupling [N s] (Default: 0).
GMT	1	Transverse metacentric height [m]. Give exactly one of GMT and RollPeriod.
RollPeriod	1	Undamped roll natural period [s], sets the roll stiffness instead of GMT.
GML	1	Longitudinal metacentric height [m]. Give exactly one of GML and PitchPeriod.
PitchPeriod	1	Uncoupled undamped pitch natural period [s], sets the pitch stiffness instead of GML.
HeaveDampingRatio	1	Linear heave damping ratio (Default: 0.3).
RollDampingRatio	1	Linear roll damping ratio (Default: 0.45).
PitchDampingRatio	1	Linear pitch damping ratio (Default: 0.3).
RollQuadraticDamping	1	Quadratic roll damping d in d |phi'| phi' [N m s^2]. Required; 0 switches it off.
SampleLevel	1	Sample points: 1 = 5, 2 = 9, 3 = 25, 4 = 49 (Default: 2). See Short waves.
FilterTimeConstant	1	Time constant tau of the excitation filter [s] (Default: 0.1). Must be positive.
Rho	1	Water density [kg/m^3] (Default: 1025).

Initial conditions

Name	Width	Description
Motion	3	Heave, roll, pitch (Default: 0,0,0).
MotionRate	3	Their rates (Default: 0,0,0).
Excitation	3	Filtered wave loads (Default: 0,0,0).

Full example file

Three hulls of 12, 20 and 40 m in head, beam and bow-quartering irregular seas, drawn in the ocean of the environment.

<Contents>
   <!--
   Three LocalWaveVessel hulls of 12, 20 and 40 m in a 1.5 m irregular sea, drawn in the ocean
   of the environment.
 
   The sea is a JONSWAP spectrum, mean period 6 s, travelling south (MainDirectionDeg 180).
   The hulls lie still, 40 m north of the origin, with headings that give head seas (12 m,
   heading north), beam seas (20 m, heading east) and bow-quartering seas (40 m, heading
   north-east).
 
   The 12 and 40 m hulls are the 20 m workboat Froude-scaled by 0.6 and 2: lengths and GM
   scale by s, areas by s^2, mass by s^3, inertias and RollQuadraticDamping by s^5.
   SampleLevel grows with the length so the sample spacing stays below the shortest waves
   with energy (about 6 m; see "Short waves" in the model's documentation).
 
   The live view needs a visualization build and the <Visualization> observer below;
   simulationSpeed="1" runs it in real time. The
   camera starts at NED (-30, 0, 0) looking north towards the hulls.
   -->
   <OBJECTS>
      <Lib
         LibName              = "marine_elements"
         SimObject            = "Vessel/LocalWaveVessel"
         Name                 = "Small"
         Length               = "12"
         Breadth              = "3.6"
         Mass                 = "32400"
         RollInertia          = "46656"
         PitchInertia         = "349920"
         A33                  = "32400"
         A44                  = "9331"
         A55                  = "349920"
         GMT                  = "0.48"
         GML                  = "15"
         RollQuadraticDamping = "15552"
         SampleLevel          = "2"
      />
      <Lib
         LibName              = "marine_elements"
         SimObject            = "Vessel/LocalWaveVessel"
         Name                 = "Medium"
         Length               = "20"
         Breadth              = "6"
         Mass                 = "150000"
         RollInertia          = "6.0e5"
         PitchInertia         = "4.5e6"
         A33                  = "1.5e5"
         A44                  = "1.2e5"
         A55                  = "4.5e6"
         GMT                  = "0.8"
         GML                  = "25"
         RollQuadraticDamping = "2.0e5"
         SampleLevel          = "3"
      />
      <Lib
         LibName              = "marine_elements"
         SimObject            = "Vessel/LocalWaveVessel"
         Name                 = "Large"
         Length               = "40"
         Breadth              = "12"
         Mass                 = "1.2e6"
         RollInertia          = "1.92e7"
         PitchInertia         = "1.44e8"
         A33                  = "1.2e6"
         A44                  = "3.84e6"
         A55                  = "1.44e8"
         GMT                  = "1.6"
         GML                  = "50"
         RollQuadraticDamping = "6.4e6"
         SampleLevel          = "4"
      />
      <Lib
         LibName                    = "environment"
         SimObject                  = "Environment"
         Name                       = "Environment"
         Waves.Spectrum             = "JONSWAP"
         Waves.Theory               = "Airy"
         Waves.Hs                   = "1.5"
         Waves.MeanPeriod           = "6"
         Waves.MainDirectionDeg     = "180"
         Waves.DirectionCosinePower = "10"
         Waves.NumWaves             = "40"
         Bathymetry.Depth           = "1000"
         Visual.WorldRadius         = "500"
      />
   </OBJECTS>
 
   <INTERCONNECTIONS>
      <Connection
         Small.Position  = "40,-35,0"
         Small.Rotation  = "0,0,0"
         Medium.Position = "40,0,0"
         Medium.Rotation = "0,0,1.5707963"
         Large.Position  = "40,45,0"
         Large.Rotation  = "0,0,0.7853982"
      />
   </INTERCONNECTIONS>
 
   <INITIALIZATION>
      <InitialCondition
         Small.Motion      = "0,0,0"
         Small.MotionRate  = "0,0,0"
         Small.Excitation  = "0,0,0"
         Medium.Motion     = "0,0,0"
         Medium.MotionRate = "0,0,0"
         Medium.Excitation = "0,0,0"
         Large.Motion      = "0,0,0"
         Large.MotionRate  = "0,0,0"
         Large.Excitation  = "0,0,0"
      />
   </INITIALIZATION>
 
   <SIMULATION simulationSpeed="1">
      <Timing TStart="0" TEnd="600"/>
      <Integrator Method="RK45_i">
         <StepControl StepMax="0.05" StepMin="1e-10" AbsTol="1e-3" RelTol="1e-3"/>
      </Integrator>
   </SIMULATION>
 
   <OBSERVERS>
      <FileOutput TOutput="0, 0:0.5:600, 600" Select="objects:all"/>
      <Visualization frameRate="25"/>
   </OBSERVERS>
</Contents>

This SimObject is referred to as Vessel/LocalWaveVessel