Norrbin Tanker

A 3DOF vessel.

Collaboration diagram for Norrbin Tanker:

Author

Karl Gunnar Aarsæther

Reference model

The manoeuvring model of Van Berlekom and Goddard (1972), "Maneuvering of large tankers", SNAME Transactions 80, with its data for nine tankers. The bernica data set is the Esso Bernicia 190,000 dwt tanker (L = 304.8 m) of its Appendix A, which Fossen's MSS toolbox implements in CRAFT/SHIP/models/tanker.m (github.com/cybergalactic/MSS). The hull and shallow-water terms, the rudder and propeller forces and every bernica coefficient were checked against that file on 2026-09-24. In particular, Xvr and Yur hold its combined coefficients d11 = 1 + Xvr = 2.02 and d22 = Yur - 1 = -0.752, and tanker.m's Yuvz term, Yuvz (1 - 0.8/z) u v z, is zero below z = 0.8. tanker.m's states are body-frame (u, v, r); this class's are NED velocities, so it adds the frame's rotation. The differences:

• The shaft speed follows a torque balance (Qmu, Qn, ...), not tanker.m's first-order lag to a commanded rpm.
• The rudder follows its command through a 60 s first-order lag, not tanker.m's rate limit of 2.33 deg/s.

Model notes

• Sign conventions: NED, with the yaw angle psi measured from north towards east. The rudder's yaw moment is Nccd |c| c delta with Nccd < 0 in every data set, so a positive rudder angle gives a negative yaw rate: the tanker turns to port. The propeller's own yaw moment, L Nt gT with Nt < 0, also turns it to port.
• The surge and sway equations are written in the body frame, which turns at the yaw rate, and rotated to NED. The drift angle beta = v/u in the rudder forces is replaced by u v / (u^2 + 0.1^2), which equals v/u above about 1 m/s and goes smoothly to zero at u = 0.
• Units of the shaft: the EngineRPM state is the shaft speed n in revolutions per second, despite its name; the thrust and rudder-inflow coefficients are tanker.m's, which converts rpm to rev/s before using them. The Engine input is the dimensionless engine torque in the shaft's torque balance, with 1 the service condition: in deep water, rudder amidships, Engine = 1 holds n = RPM0 / 60 (115 rpm, 1.92 rev/s, for 20000dwt and 100000dwt; 80 rpm, 1.33 rev/s, for the others) within 1 %, and 15 to 16 kn ahead.
• The sign of the shaft friction, n/|n|, is smoothed as tanh(n / 0.1).
• The shallow-water ratio z = draft / (depth - draft) enters the hull and rudder forces and the surge, sway and yaw added mass (Xduz, Ydvz, Ndrz). With the default sea depth (no Environment), z is close to zero.
• OdeJacobian is complete: it has the hull, rudder (through the inflow speed c(u, n) and beta), propeller and shaft partials. The current, the sea depth and the input ports are held fixed.

Wake

With an Environment the tanker reads its hull inflow, the current without the waves (owner ruling O6a), through an environment::wake::BodyFlowInteraction: the current with every other object's wake and jet, never its own (D3). The other objects' wakes are held for the step at the hull with the default ExternalWakeUpdate Step and composed live with Evaluation. Without an Environment there is no current, no wake and deep water, as before; CastWake is then a parameter error.

With CastWake the tanker is a self-propelled body (environment::wake::PropelledObject, feature propeller-jet, owner rulings O12a, O13a and "Balance") and casts two fields, both on the common wake parameters (Wake*, fhsim_environment's doc/user/wake-parameters.md):

• the hull wake, a lumped wake of the bare-hull resistance at the free stream, ρ DISPL (nlin_X, nlin_Y) rotated to NED, with ρ = Rho: the hull terms only, without the thrust, the stopped propeller's Tuu term, the rudder or the external force. The (Xuu + Xuuz z) u² term takes u|u| (owner ruling 2026-10-13), so a following current faster than the ship (u < 0) casts the hull wake along the relative flow, ahead of the bow; OdeFcn keeps u². Its frontal area is B TT and its rear centre the downstream end, the stern, Position − Lpp/2 (cos ψ, sin ψ, 0) + (0, 0, TT/2), or the bow when the water overtakes the hull. The free stream is sampled at Position. The force is ρ DISPL times the hull acceleration, not ρ g DISPL times it as the Force input's scaling has it;
• the propeller jet <Name>/jet of the effective thrust T_eff = ρ DISPL gT (1 − t), t the thrust deduction (0.22 for bernica), at the advance speed u_a, the surge speed through the water at the hull, issuing astern along the body x axis from PropellerPos with the diameter PropellerDiameter (marenv doc/wake.md § 4.2).

In steady self-propulsion the two balance: at the bernica service point (16 kn, 80 rpm) T_eff and the bare-hull resistance R differ by 0.2 %, and the far field carries about no net momentum (test NorrbinTanker_steadyFarFieldIsNearlyMomentumless). Measured there in 5 km deep still water: the jet's excess on its axis is 1.78 m/s (the efflux) at 1 D_p behind the propeller, 1.21 at 5, 0.83 at 10 and 0.55 m/s at 20 D_p; the hull deficit on its axis, TT/2 deep, is 0.031 (0.26 m/s) Lpp/2 behind the stern, 0.016 at 1 Lpp and 0.004 at 5 Lpp. The tanker's own motion is unchanged by CastWake; other objects feel the fields.

Example configuration excerpt

<Lib
  LibName     = "fhsim_base"
  SimObject   = "Vessels/Tanker"
  Name        = "A"
  ModelType   = "lb-series"
  DataSet     = "20000dwt"
  RudderType  = "small"
/>
...
<Connection
  A.Force     = "0,0,0"
  A.Torque    = "0,0,0"
  A.Engine    = "0"
  A.Rudder    = "0"
/>
...
<InitialCondition
  A.Position    = "0,0,-500"
  A.Velocity    = "0,0,0"
  A.Rotation    = "1,0,0"
  A.Omega       = "0,0,0"
  A.EngineRPM   = "0"
  A.RudderAngle = "0"
/>

Input Ports

Name	Width	Description
Force	3	External force on the vessel, NED components. Only the north and east components enter the dynamics.
Torque	3	External torque on the vessel. Only the third (yaw) component enters the dynamics.
Engine	1	Engine torque command, dimensionless: 1 holds the service shaft speed and 15 to 16 kn ahead (see Model notes).
Rudder	1	Commanded rudder angle [rad]. Limited to +/-60 degrees and tracked by the RudderAngle state through a first-order lag with a 60 s time constant.

Output Ports

Name	Width	Description
Position	3	The Position state (NED).
Velocity	3	The Velocity state (NED). The down component has zero derivative.
Rotation	3	The Rotation state. Only the third component (yaw angle psi) enters the dynamics.
Omega	3	The Omega state. Only the third component (yaw rate) has a non-zero derivative.

Configuration parameters

Name	Width	Description
ModelType	1	Hydrodynamic data series, case-insensitive: lb-series, geosim-series or bernica. Required; other values are reported as errors.
Rho	1	Water density [kg/m^3] (Default: 1025). The Force and Torque inputs are divided by the displaced mass DISPL * Rho (and Lpp).
DataSet	1	Vessel within the series, case-insensitive. Required for lb-series (20000dwt, 100000dwt, 200000dwt, 500000dwt) and for geosim-series (240m, 274m, 304m, 332m); other values are reported as errors. Not read for bernica.
RudderType	1	small, medium or large, case-insensitive. Required; other values are reported as errors.
Scene	1	Ogre .scene resource for the vessel. Default: none, and the hull mesh vessels/skrog01/skrog01.mesh from fhsim_base.zip is drawn, fitted to the data set's Lpp along x and B along y, with the vertical scale equal to the breadth scale, centred on the position and with its keel at the draught. Visualization builds only.
CastWake	1	Cast the hull wake and the propeller jet (see Wake); needs an Environment. The other wake parameters (Wake*, ExternalWakeUpdate) are listed in fhsim_environment's doc/user/wake-parameters.md. (Default: false)
PropellerDiameter	1	Propeller diameter D_p [m], > 0. Read only with CastWake. (Default: 0.65 TT)
PropellerPos	3	Propeller centre in the body frame (x forward, y starboard, z down from Position) [m]. Read only with CastWake. (Default: -Lpp/2, 0, 0.6 TT)
ScaleX	1	Visualization scale along x (Default: 1.0). Multiplies the fitted scale of the default hull; a Scene is scaled by it once, on its root node; the scene's own node scales are kept. Visualization builds only.
ScaleY	1	Visualization scale along y (Default: 1.0), as ScaleX. Visualization builds only.
ScaleZ	1	Visualization scale along z (Default: 1.0), as ScaleX. Visualization builds only.

Initial conditions

None of the states has a registered default\, so all six must be given in the model.

Name	Width	Description
Position	3	Initial NED position.
Velocity	3	Initial NED velocity.
Rotation	3	Initial rotation vector; the third component is the yaw angle psi [rad].
Omega	3	Initial angular rate; the third component is the yaw rate [rad/s].
EngineRPM	1	Initial shaft speed [rev/s, not rpm].
RudderAngle	1	Initial rudder angle [rad].

Full example file

<Contents>
  <!-- The tanker starts ahead at 4 m/s with the engine on; the rudder is commanded to
       +0.35 rad and reaches it through its 60 s lag (BASE-0032). -->
  <OBJECTS>
    <Lib
        LibName="base" 
        SimObject="Vessels/Tanker"  
        Name="A" 
        Scale="1.0"
        Mass="1.0"
        Material="Simple/Red"
        InertiaRadi="1,1,1"
        ModelType="lb-series"
        DataSet="20000dwt" 
        RudderType="small"
    />
  </OBJECTS>
  
  <INTERCONNECTIONS>
    <Connection
        A.Force="0,0,0"
        A.Torque="0,0,0"
        A.Engine="1"
        A.Rudder="0.35"
    />
  </INTERCONNECTIONS>
 
  <INITIALIZATION>
    <InitialCondition
        A.Position="0,0,0"
        A.Velocity="4,0,0"
        A.Rotation="0,0,0"
        A.Omega="0,0,0"
        A.EngineRPM="1.87"
        A.RudderAngle="0"
    />
  </INITIALIZATION>
 
  <SIMULATION>
    <Timing TStart="0" TEnd="600.0"/>
    <Integrator Method="RK45_i" NumCores="1" LogStates="1" UseRSSNorm="0">
      <StepControl StepMax="0.002" StepMin="0.00000001" AbsTol="1e-3" RelTol="1e-3"/>
    </Integrator>
    
  </SIMULATION>
 
<OBSERVERS>
    <FileOutput TOutput="0:60:600" Select="objects:all"/>
  </OBSERVERS>
</Contents>

This SimObject is referred to as Vessels/Tanker