Norrbin Tanker

A 3DOF vessel.

Collaboration diagram for Norrbin Tanker:

Review issues:

0048 — CNorrbinTanker applies ScaleX/Y/Z to a loaded scene's root node and again to each of its child nodes

0049 — CNorrbinTanker does not report an unknown `ModelType` and silently uses the `bernica` data

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.

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. Any other value is not reported and selects the bernica data.
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.
ScaleX	1	Visualization scale along x (Default: 1.0). Multiplies the fitted scale of the default hull; a Scene is scaled by it on its root node and again on each child node (BASE-0048). 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