DyadShip

A Dyad port of the Modelica naval-architecture library ShipSIM by Basilio Puente and M Dolores Fernandez, built on the 3D MultibodyComponents library, plus a WaterLily.jl CFD-driven Flettner rotor propulsor.

This is a rewrite, not a translation. The Modelica components have been reimplemented in Dyad on top of MultibodyComponents, RotationalComponents, BlockComponents and the rest of the Dyad standard libraries. Per-component docstrings state what was simplified or corrected relative to upstream; PORTING_NOTES.md is the map of what exists, what changed and what was left out.

Six-degree-of-freedom ship (dyad/Ship6DOF)

The primary stack mirrors ShipSIM's architecture on Frame3D connectors:

Component	What it does
ShipBody	Rigid body (yaw-pitch-roll Euler angles) with draft-polynomial hydrostatics: displacement, centre of buoyancy and metacentric radii as functions of the instantaneous draft, heel and trim.
HydrodynamicXYY	MMG surge/sway/yaw forces with the empirical derivative estimates of Clarke, Smitt, Khattab, Lee & Shin, Kijima and Yoshimura, resistance curve, and added mass with the coupling terms. Forces act at the centre of forces, so a turn heels the hull.
HydrodynamicZRP	Heave/roll/pitch damping and added mass, with defaults from damping ratios.
Propeller1Q / Propeller4Q	Wageningen B-series open-water characteristics: the full Oosterveld & van Oossanen polynomial, or the 14 four-quadrant Fourier data sets for astern and crash-stop work. Both feed the rudder with Brix's slipstream model.
Rudder	Steering-gear angle and rate limits, NACA 0012/0015 Cl/Cd/Cm(α, Re) tables (assets/naca*.csv), flow straightening, Söding slipstream and hull-interaction factors.
ShipWind	Fujiwara superstructure wind loads at the centre of the lateral area.
WingSail	Rigid wing sail on a servo-driven mast revolute, NACA tables, forces at the quarter chord of the rotated sail.
POD4Q	Azimuthing pod: servo revolute, strut and an internal Propeller4Q that reads its own advance speed.
AntiHeeling / BallastTank / VariableMass	Clocked hysteresis pump controller with ramped flow and a latched transfer direction; the tank liquids as variable-mass points on the hull, so the righting moment, the added weight and the change of the ship's centre of gravity and roll inertia come from where the water is.
AntiHeelingCircuit / CentrifugalPump / TankLiquidMass	The same tanks as IncompressibleFlowComponents open tanks (their liquid a TankLiquidMass on the hull) joined by two antiparallel affinity-law pump and linear-valve branches: the transfer rate follows the pump characteristic against the level difference and the valve losses. A partial the ship assembly extends, because fluid ports cannot pass through a wrapper.
FuelTank	Consumable liquid on VariableMass: burn or bunker fuel and the hull's draft, trim and inertia follow.
RollTunedMassDamper	The building tuned mass damper for roll: a mass on a transverse Prismatic slide high in the ship with a SpringDamper tuned to the roll period (Den Hartog); damps roll, does not correct static heel.
Crane / Cable	Slewing and luffing revolutes on position servos, boom, tension-only cable with a clocked break latch; loads react into the hull.
ApparentSpeedXY	Frame-based apparent wind / current sensor.
WaypointAutopilot / WaypointSequencer	LimPID heading autopilot with throttle ramp, and a clocked waypoint table that advances its index on arrival (DiscreteComponents).
StandardShip	The ShipSIM sample hull (100 m, 5681 t) with propeller, rudder and hydrodynamics wired up; the manoeuvring analyses extend it.

Validation

scripts/validate_6dof.jl runs the standard manoeuvring tests and writes the figures in assets/ship6dof_*.png. Results for the sample hull (rudder rate 2.5 °/s, approach 6.69 m/s, 100 rpm unless noted):

Analysis	Result
RollDecayTransient	roll period 9.1 s (linear estimate 8.4 s; the difference is the sway added-mass coupling of a hull rolling about a CoG 5 m above its hydrodynamic centre), damping ratio 0.047 for the 0.05 setting
RollDecayTMDTransient	same release with a 100 t tuned mass damper 15 m above the roll centre: first peaks 4.6°, 1.6°, 0.7° against 8.5°, 6.2°, 4.6°, heel 0.1° at 60 s; the mass strokes 6.4 m
SpeedTrialTransient	6.05 m/s at 100 rpm, thrust 129 kN against 128 kN resistance, 1.1 MW shaft power
TurningCircleTransient (35°)	advance 3.9 L, transfer 0.7 L, tactical diameter 3.2 L; steady turn at 44 % of approach speed, 0.95 °/s, 35° drift, 0.35° outward heel
RudderReturnTransient	yaw rate halves 24 s after the rudder is centred and decays to zero
ZigZagTransient (20/20)	overshoot angles 32°, 31°, 27°
CrashStopTransient	110 rpm ahead to 80 rpm astern: stopped after 287 s, head reach 9.9 L
FullShip6DOFTransient	10 km waypoint transit in a 10 m/s wind from the north-east: arrives at 1768 s holding a 3.8° rudder offset and 0.2° heel
WingSailSweepTransient	one sail in a 10 m/s beam wind: peak forward thrust 12 kN at a 15° attack angle
FourWingSailsTransient	four sails, 15 m/s from the port beam, autopilot holding course: 7.17 m/s at 100 rpm against 6.05 m/s without sails, 29 kN sail thrust, 1.2° heel
FourWingSailsAHTransient	same with the anti-heeling system enabled at 300 s: heel back to zero by 750 s, tank levels 65 % port / 25 % starboard
FourWingSailsAHTanksTransient	same with the tanks as moving masses instead of an applied torque: heel back to zero by 700 s with 67 t / 25 t in the tanks, ship 7 cm deeper from the ballast
FourWingSailsAHCircuitTransient	same with the tanks as IncompressibleFlowComponents open tanks and a pump/valve circuit: the pump runs at 200 m³/h (57 kg/s) against a 3.0 to 4.7 m head, heel 1.15° to 0.005° by 700 s, tank fills 0.45 / 0.45 to 0.65 / 0.25
BunkeringTransient	300 t of fuel loaded forward in one hour at rest: draft +0.20 m, trim 0.52° by the bow, matching the hydrostatic estimate
MoistAir.MoistAirDewPointTransient	30 °C, 80 % air through a ventilated space on HVACComponents moist-air media: outlet dew point 26.20 °C (Magnus reference 26.17 °C)
PodTurningCircleTransient	35° pod azimuth: steady radius 1.0 L at 2.1 m/s, no cavitation
CraneOperationTransient	50 t load luffed, slewed 90° to port and lowered: ship heels to 2.1°, cable tension 490 kN
WaypointTransitTransient	three-leg route with a 45° dog-leg: the clocked sequencer switches waypoints at 851 s and 1635 s, arrival at 2400 s

The zig-zag overshoots are large because the upstream Khattab estimate of the yaw damping leaves the bare hull linearly course-unstable (HydrodynamicXYY.CourseStability < 0); the rudder's fin effect holds the course. Override N_r for a stiffer hull.

The zig-zag switch, the anti-heeling on/off controller, the cable break and the waypoint table are clocked components built on DiscreteComponents (sampled every 0.05–1 s on a PeriodicClock, with the state held between samples), not continuous relay approximations.

ManualShip6DOFTransient exposes shaft rpm and rudder angle as tunable parameters for interactive (WASM) use.

Planar stack and Flettner rotor

dyad/Ship and dyad/Propulsion hold the earlier PlanarMechanics (surge/sway/yaw) port: HullMMG, Rudder, Propeller1Q/4Q, ShipWind, HeadingAutoPilot, ManualShip, the FullShip* transits and the Flettner-rotor propulsor. The planar wing sail, pod, crane, cable and anti-heeling components were replaced by the 3D versions. Two sign errors in it were fixed in this pass (rudder inflow angle, wind lateral force and moment); its analyses still use a hull mass well below the sample ship's displacement, so prefer Ship6DOF for manoeuvring studies.

Propulsion.SimpleDieselEngine meters fuel on the brake power only: the engine torque is never negative, so a shaft driven backwards against it is a motored engine that reports negative ShaftPower and no fuel, never a fuel credit (upstream integrates the signed sensed power and goes negative). The SFOC table is a parameter pair (SFOC_P, SFOC_g) whose end values are held outside the tabulated 605–1210 kW. SFOC_valid is a table-coverage flag (0 while a held end value is in use), not a calibration statement, and Fuel_extrapolated [kg] accumulates the fuel metered outside the table, so an interval of the Fuel counter is inside the table exactly when Fuel_extrapolated did not change over it. m_dot_idle adds a no-load rate and defaults to zero as upstream. Inst_Fuel [kg/s] is nonnegative, Fuel [kg] is exactly its integral and nondecreasing, KWh stays the signed net work. The default tables are the upstream ShipSIM values, for which upstream cites no engine or test: they are reference values, not an OEM calibration (sources and manufacturer documents for context are linked in the component docstring). asserts reject unordered, non-finite or non-positive tables and a negative idle rate.

The fuel counters have been nondecreasing at every accepted solver step in every run checked. For Fuel_extrapolated, whose rate jumps to zero where the brake power enters the table, the engine ends a solver step at each table entry (Propulsion.StepAtRisingCrossing), so the steps that follow lie inside the table and leave the counter exactly constant. Interpolated values, including a saveat grid, which stores the interpolant rather than extra steps, can fall back inside a step that spans a kink of the rate (4.6e-5 kg on 0.41 kg in DieselEngineReversing without step alignment; the size follows the step length, not the solver tolerance). DieselEngineReversing declares its zero-power crossings as tstops, which makes its dense fuel counter nondecreasing too; where crossing times are not known, export counters at the accepted steps. The metering is evaluated pointwise and does not depend on automatic_discontinuity_detection, whose events miss a condition that starts exactly on its threshold (an engine starting at zero power). scripts/validate_engine_fuel.jl checks the forward ramp against the previous numbers, a reversing shaft imposed by a velocity source, a run held inside the SFOC table from start to end (DieselEngineInRange, synthetic load, rate samples reconciled with the counter), a stopped shaft with and without idle fuel, the sampling behaviour and the rejected parameter values.

How a powered ship comes together

Ship6DOF.PoweredSingleScrewShip is the sample hull with its propeller, rudder and a free propeller shaft (SingleScrewHull, which is StandardShip without its ideal speed governor) plus a distance counter. A ship is that partial with one plant subcomponent connected to shaft.spline_a.

A plant is any component that extends Ship6DOF.ShipPowerPlantPorts, which fixes what the hull needs and what the machinery reports: the propeller_flange, the orders shaft_speed_order [rpm] and hotel_power_demand [W], and the observation outputs in SI units (fuel mass rate, fuel counter, out-of-table fuel counter and coverage flag for the main engine and for the generating set; shaft, hotel, generating-set and shaft-machine power with their energy integrals; running states and running times). Dyad has no replaceable components, so the slots inside a plant are conventional subcomponent names (main_engine, gearbox, pto, genset_engine, genset_machine, hotel_load) with a partial component for the connectors of each kind: Propulsion.DieselEnginePorts for an engine, Ship6DOF.ShaftMachinePorts for an electrical machine on a shaft.

Two plants are built from this library and the standard component libraries only: DieselMechanicalPlant (synthetic engine preset A through an ideal gear to the propeller, synthetic preset B driving a DC machine that feeds a conductance hotel load) and DieselShaftMachinePlant, the same with a DCShaftMachine on the engine shaft and the bus. That machine is an ideal EMF behind a resistance with no control, so it takes power from the bus below its matching engine speed and feeds the bus above it. Everything in them is synthetic or ideal; they show the structure, not an installation. scripts/validate_ship_power_plant.jl checks signs, the power balance from engines to propeller and hotel load, and the counters.

A plant written in another package extends these partials directly. The generated code of the extending package names the libraries that the inherited hull composes, so its module must import them as well: MultibodyComponents, RotationalComponents, BlockComponents and ElectricalComponents, not only the libraries its own components name.

Hotel load by consumer group

Machinery.ElectricalLoadList is an electrical load list. It holds consumer groups, each with an installed power and a demand factor (power drawn divided by installed power) for each of four operating modes. Its output is the sum for the mode on its mode input, which feeds a plant's hotel_power_demand. Its default is one aggregate group that reproduces the fleet-average row behind the hotel-load presets: a 60,000 to 99,999 dwt bulk carrier at 410, 1100, 240 and 400 kW at sea, manoeuvring, at berth and at anchor (Fourth IMO GHG Study 2020, Table 17, page 68).

Presets.LoadAnalysisExampleShip applies a consumer-group list from assets/presets/LoadList/load_analysis_example_ship.toml. Its source is the worked example in Annex B (pages 91 and 92) of A. C. R. C. Sarrico, Assessment of Ship Electric Power Consumption (MSc thesis, Instituto Superior Técnico, 2020). The example has 82 items in 12 groups, including reefer containers, cargo cranes, bow thrusters, HVAC and galley, with load and simultaneity factors for four conditions. It is a model estimate printed in the thesis, not a measured load balance. Each group is reduced to its installed power and one factor per condition, so the totals are the printed ones: 1202, 1487, 577 and 217 kW. The thesis has no anchored condition, so its "at port" condition is the fourth mode.

DieselShipModesFleetAverageTransient and DieselShipModesLoadListTransient run the diesel-plant ship through the four modes: at sea, manoeuvring, berth and anchor, 300 to 600 s each. The shaft order steps down with the mode and the hotel demand steps with it. The library's synthetic generating set is limited to 5500 N·m at 1800 rpm, about 1.04 MW. It carries the fleet-average load except the 1100 kW of manoeuvring, and the consumer-group list in none of the first two modes: the list shows that this ship needs a larger plant at sea and when manoeuvring. After a long overload the set overspeeds when the load drops, because the speed governor of SimpleDieselEngine has no anti-windup, so the bus voltage rises and the port modes of the consumer-group run receive more than their demand. The demand itself, loads.y, is exact in every mode. scripts/validate_load_list.jl checks the file against the printed group and condition totals, the demand in each mode and at each step, and what the plant delivers.

A tanker skeleton

Ship6DOF.TankerSkeleton puts the pieces of a ship in one assembly: the powered hull above with its body reduced to a lightship mass, three cargo tanks and two peak ballast tanks (FuelTank, used as a liquid mass with no flow), two wing ballast tanks joined by the pump-and-valve circuit AntiHeelingCircuit, a bunker tank drained by the fuel rates of the plant's engines, and DieselMechanicalPlant. TankerLaden and TankerBallast are two load conditions; the analyses are a speed trial in each and a ballast transfer under way. All numbers are synthetic round values on the library's 100 m sample hull, which is not a tanker hull.

Each tank is a point mass at half the liquid height on the multibody hull, so draft, trim and heel follow the loading. The tank models have no free surface of their own (see FreeSurfaceMoment below), no sloshing, no cargo piping and no flooding; the docstring lists what each piece can and cannot represent. scripts/validate_tanker_skeleton.jl checks the mass bookkeeping (the bunker tank loses exactly what the engines meter; a ballast transfer conserves water), the hydrostatic response and the power bookkeeping.

Tank tables

A ship's tanks are data. Ship6DOF.TankTable holds one row per tank: name, position of the tank bottom in the ship frame, capacity, height, liquid density and, optionally, the initial fill. Each assembly loads its file with an apply clause, and every tank component takes its values from its row. The files are in assets/presets/Tanks/, each with a provenance sidecar:

File	Ship	Rows
tanker_skeleton.toml	TankerSkeleton	three cargo tanks, two peak tanks, bunker
anti_heeling_pair.toml	the four-wing-sail ship (FourWingSailsAH, …AHTanks, …AHCircuit), and the tanker's wing tanks through AntiHeelingCircuit	port and starboard wing tanks
bunkering.toml	Bunkering	one forward fuel tank

All values are the synthetic round numbers that were in the model text before. They were moved, not changed. scripts/validate_tank_tables.jl prints every tank analysis at full precision, with its number of solver steps. Before and after the move, its output for the bunkering ship and the three four-wing-sail variants is identical, digit for digit. In the three tanker analyses the loaded values are the same, but the tanker's wing tanks now come from a table inside the anti-heeling circuit, which changes the arrangement of the compiled tanker model. That changes floating-point round-off. The results agree to 1e-10 (relative) in the two speed trials, and to 8e-8 in the ballast transfer's final heel, where the adaptive solver takes 325 steps instead of 326. All checks of scripts/validate_tanker_skeleton.jl still pass. The tanker's fills stay with its two loading conditions (TankerLaden, TankerBallast). The anti-heeling circuit is a partial that a ship extends, and Dyad 3.4 cannot hand a partial a member of the extending component, so the circuit loads its own file.

Free-surface correction

Ship6DOF.FreeSurfaceMoment adds the free-surface effect of a partly filled tank as a heeling moment ρ_t g i sin φ on the hull. Here i = l b³ / 12 is the transverse second moment of the liquid surface. This is the correction GM − (γ_t/γ_s) i/∇ of MIT OpenCourseWare 2.700, Principles of Naval Architecture (Fall 2014), Project 4, page 1, after Gillmer and Johnson, chapter 6. The tank models do not include it, so it is added beside a tank and no existing result changes. HeelSolidTransient and HeelFreeSurfaceTransient heel the sample hull under the same steady moment, without and with a 20 m × 10 m free surface of sea water. scripts/validate_free_surface.jl checks that the loss of metacentric height between the two equals ρ_t i / Δ. It leaves out the longitudinal free surface, the change of i with the fill, and sloshing.

A published tanker hull: KVLCC2

Ship6DOF.KVLCC2Ship is the KVLCC2 research tanker at full scale (320 m, 312 600 m³). Its hull forces come from the file assets/presets/Hull/kvlcc2_full_scale.toml: the principal particulars, resistance coefficient, added masses and sixteen hull derivatives of Yasukawa and Yoshimura, "Introduction of MMG standard method for ship maneuvering predictions", J. Mar. Sci. Technol. 20 (2015) 37–52 (open access). The sidecar next to the file gives the table and page of every value and the arithmetic of the converted ones. Ship6DOF.Propeller1Q takes the published open-water thrust polynomial through its new optional polynomial parameters.

The source's model has three degrees of freedom and its own rudder and wake models. This one has six degrees of freedom, the library's Rudder and a constant wake fraction; the vertical hydrostatics, the height of the centre of gravity and the positions of propeller and rudder are stated assumptions. With nothing tuned, the 35° turning circles from 15.5 kn come out with an advance of 4.16 (port) and 4.04 (starboard) ship lengths and a tactical diameter of 3.98 and 3.75, against 3.56 / 3.62 and 3.59 / 3.71 in the source's own full-scale simulation: the advance is 12–17 % larger and the tactical diameter 1–11 % larger. The source's port turn is the tighter one; here the starboard turn is. Against the source's free-running test of a 7 m model, which has no full-scale counterpart, they are 24–34 % and 12–29 % larger. scripts/validate_kvlcc2.jl prints the comparison. Those advances are of the ship frame's origin at the aft perpendicular. At the midship point, where the source and the IMO standards measure it, the advance is 0.5 L less: 3.66 (port) and 3.54 (starboard), within 3 % of the source's full-scale simulation (see "IMO manoeuvring standards" below). The tactical diameter is the same at either point.

Ship6DOF.PoweredKVLCC2Ship is the same hull with a free propeller shaft for a power plant (the pattern of PoweredSingleScrewShip), the open-water torque of the propeller, and a full-scale resistance estimate. The torque curve is a quadratic fit of the open-water test of the model propeller published with the SIMMAN 2008 workshop data; the same fit of its thrust column returns the thrust polynomial above. The resistance coefficient of the manoeuvring set is that of the 2.9 m captive model: it suits the model-scale manoeuvring balance, but at full scale it asks for 79 MW at 15.5 kn and 107 rev/min. The source computed its full-scale resistance by a three-dimensional extrapolation on Schoenherr's friction line without printing the result; the powered ship repeats that method with the published wetted surface and the wave-making part taken as zero, which is an estimate and the low end of the range, not a published powering prediction. With it, and IdealGovernorPlant in the plant slot, the ship runs at:

Speed [kn]	Shaft speed [rev/min]	Thrust [kN]	Torque [kN·m]	Shaft power [MW]
9.97	47.6	916	1145	5.70
12.46	59.5	1432	1789	11.14
13.95	66.6	1796	2245	15.65
15.45	73.7	2202	2752	21.24

The run keeps its course with a simple rudder law: with the published derivatives the hull is directionally unstable and does not hold a straight course with the rudder amidships.

The turning-circle comparison above was made with the model resistance coefficient, and so with the propeller at 107 rev/min. With the full-scale estimate and 73.7 rev/min the turns are wider still: advance 4.49 (port) and 4.38 (starboard) ship lengths at the aft perpendicular (0.5 L less at midship), tactical diameter 4.08 and 3.87, that is 21–26 % and 4–14 % above the source's full-scale simulation. The slower propeller gives the rudder less slipstream.

Ship6DOF.KVLCC2Vessel is the powered KVLCC2 as an ordinary component, with the propeller shaft and the rudder order as connectors, for a model that wants to hold the ship as a subcomponent instead of extending a partial.

IMO manoeuvring standards: the KVLCC2

scripts/validate_imo_manoeuvring.jl runs the KVLCC2 manoeuvring model (KVLCC2Ship) through the standard manoeuvres of the IMO Standards for Ship Manoeuvrability (resolution MSC.137(76), 2002, with the explanatory notes MSC/Circ.1053). It extracts the measures they define for the midship point and checks them against the criteria of paragraph 5.3.

The runs:

• Model: the same as KVLCC2TurningCircle: 106.7 rpm and a steady 15.5 kn approach, L/V = 40.1 s.
• Turning circles: 35° rudder, port and starboard.
• Zig-zags: KVLCC2ZigZag with the clocked zig-zag controller of the sample ship, 10°/10° and 20°/20°, each with the first execute to port and to starboard.
• References: Yasukawa and Yoshimura, J. Mar. Sci. Technol. 20 (2015) 37-52 (CC BY 4.0). Its Tables 4 and 5 are the free-running test of the 7 m model in MARIN's tank; Tables 6 and 7 are the source's full-scale simulation.

The source's rudder angle is positive to starboard, so its "10/10Z" is the starboard-first zig-zag here.

Measure	Port first	Starboard first	Test (7 m model) port / stbd	Source full-scale port / stbd	IMO criterion
Advance, 35°	3.66 L	3.54 L	3.11 / 3.25	3.56 / 3.62	≤ 4.5 L
Tactical diameter, 35°	3.98 L	3.75 L	3.08 / 3.34	3.59 / 3.71	≤ 5 L
Distance to 10° heading, 10° rudder	1.27 L	1.32 L	–	–	≤ 2.5 L
10°/10° first overshoot	7.9°	6.3°	9.5 / 8.2	8.8 / 5.8	≤ 20° (L/V ≥ 30 s)
10°/10° second overshoot	10.8°	13.8°	15.0 / 21.9	12.6 / 20.5	≤ 40°
20°/20° first overshoot	23.1°	21.2°	15.1 / 13.7	16.1 / 11.8	≤ 25°

• All criteria are met. The 20°/20° overshoots are close to the limit and 7-8° above the test.
• 10°/10°: the overshoots are within a few degrees of the test, though the second overshoot of the starboard-first test (21.9°) is under-predicted.

Stopping. KVLCC2CrashStop is the same hull and rudder with the four-quadrant Wageningen Propeller4Q (B4_70_8, the four-quadrant table closest in pitch). The KVLCC2's own propeller is modelled for the first quadrant only and cannot run astern.

• Engine assumption: MSC/Circ.1053 Appendix 3 gives, for diesel machinery, an astern power of about 85 % of the ahead power and 60 s to develop astern thrust. The astern shaft speed is set so that the astern power at the stop is 85 % of the approach power, and the shaft is reversed over 60 s.
• Track reach: the distance sailed by the midship point until the ship stops in the water.

Resistance	Approach power	Track reach	Time	Appendix 3 formula, this ship	IMO criterion
KVLCC2Ship (captive-model coefficient)	78 MW	6.74 L	586 s	6.57 L (A 7.2)	≤ 15 L
Full-scale estimate of PoweredKVLCC2Ship	20 MW	16.24 L	1465 s	15.74 L (A 20.0)	≤ 15 L, at most 20 L for large ships

Notes on the stopping results:

• Straight track: the track is straight, because the model has no transverse propeller force. That is the longest case in Appendix 3, which notes that a real ship veers off and stops sooner.
• Appendix 3 formula: S = A ln(1 + B) + C, with this ship's mass, resistance and astern thrust, gives the simulated reaches within 4 %.
• Typical VLCC: for a diesel VLCC, Appendix 3 has A = 14-16 and so about 8-12 L.
• Full-scale case: the full-scale resistance estimate is the low, friction-only one, so A is 20 and the reach exceeds the 15 L criterion. It stays within the 20 L an Administration may accept for ships of large displacement.

A model-tested propeller against the B-series: KP458

How far is the Wageningen B-series regression of Propeller1Q from a real propeller of the same main dimensions? scripts/compare_kp458_bseries.jl evaluates it at the geometry of KP458, the propeller designed for KVLCC2 (4 blades, P/D 0.7212 at 0.7R, Ae/A0 0.431), and compares it with that propeller's open-water test: NMRI, 0.0896 m model, Rn 3.65·10⁵, published with the SIMMAN 2008 workshop data. The measured points are in assets/data/OpenWater/kvlcc2_kp458_nmri.toml, transcribed unchanged, with the source in the sidecar. The script uses no new propeller model.

KP458 is inside the published range of the regression: 2 to 7 blades, Ae/A0 0.30 to 1.05 (0.40 to 1.00 for four blades) and P/D 0.6 to 1.4 (Carlton 2019, reproduced in Čalić et al., Trans. Marit. Sci. 2025, doi:10.7225/toms.v14.n02.s05, Tables 1 and 3, pages 2 and 4). The regression is stated for Rn = 2·10⁶. The test is at a sixth of that, and the source warns that its KQ is only a guide for so small a propeller.

J	KT	KT B-series	10KQ	10KQ B-series	η₀	η₀ B-series
0.000	0.2891	0.2923 (+1.1 %)	0.3054	0.3116 (+2.0 %)	0	0
0.100	0.2654	0.2687 (+1.2 %)	0.2876	0.2920 (+1.5 %)	0.147	0.146
0.200	0.2347	0.2410 (+2.7 %)	0.2644	0.2701 (+2.1 %)	0.283	0.284
0.299	0.1994	0.2100 (+5.3 %)	0.2335	0.2454 (+5.1 %)	0.406	0.407
0.399	0.1612	0.1752 (+8.7 %)	0.1994	0.2171 (+8.9 %)	0.513	0.513
0.499	0.1173	0.1373 (+17 %)	0.1614	0.1845 (+14 %)	0.577	0.591
0.599	0.0756	0.0966 (+28 %)	0.1252	0.1472 (+18 %)	0.576	0.626
0.699	0.0341	0.0535 (+57 %)	0.0780	0.1044 (+34 %)	0.486	0.569
0.798	−0.0132	0.0086	0.0266	0.0562	–	–

The script prints all 19 points. The B-series gives more thrust and more torque at every point:

• J ≤ 0.25 (bollard pull to heavy loading): within 5 % in KT and KQ. The B-series is a fair substitute.
• J 0.3 to 0.45: KT and KQ are 5 to 12 % high, but together, so the efficiency stays within 0.005. A fair substitute for power, not for thrust at a given shaft speed.
• J ≥ 0.5 (light loading): about +0.02 in KT and 10KQ throughout. The B-series reaches zero thrust at J 0.817 instead of 0.772, and its best efficiency is 0.626 at J 0.60 against 0.593 at J 0.55. Not a fair substitute: it overstates the efficiency by 0.013 to 0.21.

The powered KVLCC2 above runs at J = 0.426 in every row of its table. At that propeller loading (the same thrust at the same speed of advance), the B-series propeller turns 3 % slower, at J 0.440, with the same torque within 1 %. It would ask for 2.4 % less shaft power. The comparison does not separate the causes: section shape, radial pitch distribution, skew (21° here) and Reynolds number all differ from the series.

Empirical resistance: Holtrop-Mennen

Ship6DOF.HoltropMennenResistance predicts the calm-water resistance of a hull from its main dimensions, for a ship that has no model-test curve. It acts as a surge force on the hull frame, like HullRoughness, so the hull's own HydrodynamicXYY resistance is set to zero. The wake fraction, thrust deduction and relative rotative efficiency of the method are outputs.

Sources: the method follows two papers. Neither numbers its equations, so definitions.jl cites each formula by paper, page and quantity.

• J. Holtrop and G.G.J. Mennen, "An approximate power prediction method", International Shipbuilding Progress 29(335), 1982, pp. 166-170.
• J. Holtrop, "A statistical re-analysis of resistance and propulsion data", International Shipbuilding Progress 31(363), 1984, pp. 272-276.

Where the 1984 paper revises a formula, its version is used. That covers the form factor, the wave resistance (its m4, its high-speed formula above Fn 0.55 and the interpolation from Fn 0.40), the single-screw wake fraction and the thrust deduction. Where it refers back to 1982, the 1982 formula is used: the bulb, transom, appendages, correlation allowance and the relative rotative efficiency.

The total is RF (1 + k1) + RAPP + RW + RB + RTR + RA, with ITTC-1957 friction. CA_factor = 0 removes the correlation allowance RA, for example for a model.

Validity: the papers bound the method only in words: "hull forms resembling the average ship described by the main dimensions and form coefficients used in the method". In_validity uses the numbers of the SARC PIAS manual (chapter Resist, "Holtrop and Mennen"):

• Lwl/B 3.5-9.5;
• CP 0.40-0.93;
• CM 0.5-1.0;
• LCB within ±5 %;
• half angle of entrance at most 70°;
• bulb section below 20 % of the midship section.

Outside these ranges In_validity is 0 and there is one warning; the result is extrapolated.

Check against the 1982 paper: scripts/validate_holtrop_mennen.jl reproduces the paper's own numerical example (p. 170) to its printed digits, for every quantity the 1984 paper left unchanged. There are two exceptions, both explained by the example evidently using the wetted surface of hull and appendages together: its c9 (14.50 against 14.40) and R_A (221.98 against 220.57 kN). The 1984 changes are checked against a second transcription of their formulas.

Example: the KVLCC2. The existing KVLCC2 resistance comes from the captive-model test of Yasukawa and Yoshimura (2015): R'0 = 0.022 for a 2.91 m model, that is C_T = 5.385e-3 on the wetted surface. PoweredKVLCC2Ship extrapolates it to full scale as 26 909 U² N.

The method's inputs are the SIMMAN 2008 particulars. Four inputs are assumed, as stated in KVLCC2HoltropPowering:

• the LCB on the waterline length (2.58 %);
• the waterplane coefficient (0.9);
• a 60 m² bulb (without it, +0.7 % at 15.5 kn);
• the rudder form factor (1.4).

The results:

• Model scale: at the test's 0.760 m/s (Fn 0.141), with no correlation allowance, the method gives C_T = 5.415e-3, +0.6 % above the measured value. Its form factor is 1.304.
• Full scale: the method is 9 to 18 % above the existing curve. Without the correlation allowance, which the existing smooth-hull extrapolation also leaves out, it is −2.7 to +6.7 % of it.

Speed [kn]	Fn	Existing [kN]	Method [kN]	Error	Method without C_A [kN]	Error
6	0.055	256	304	+18.5 %	274	+6.7 %
8	0.073	456	523	+14.7 %	469	+2.9 %
10	0.091	712	798	+12.0 %	714	+0.2 %
12	0.109	1026	1128	+10.0 %	1007	−1.8 %
14	0.128	1396	1523	+9.1 %	1358	−2.7 %
15.5	0.141	1711	1879	+9.8 %	1677	−2.0 %
16	0.146	1823	2014	+10.5 %	1799	−1.3 %

The existing curve is quadratic, so its coefficient is the same at every speed. The method's friction coefficient falls with speed and its wave resistance rises, which shapes the error across the range.

• Propulsion factors at 15.5 kn: wake fraction 0.418 and thrust deduction 0.216, against the model's 0.35 and 0.220. Relative rotative efficiency 1.022.
• Powering run: KVLCC2HoltropPowering is PoweredKVLCC2Ship with the method's resistance in place of the quadratic one. It keeps the model's wake fraction and thrust deduction. At the design 73.7 rpm it runs at 15.00 kn (resistance 1752 kN, shaft power 21.7 MW), against 15.45 kn with the existing resistance.

The existing KVLCC2 model is unchanged.

Hull roughness and fouling

Ship6DOF.HullRoughness adds the frictional resistance of a rough or fouled hull to a ship: a surge force ½ ρ S ΔC_F u|u| on the hull frame, on top of the resistance curve of HydrodynamicXYY, which it leaves unchanged. With its defaults the increment is zero, and no existing model holds one.

• Roughness of a coated hull: the roughness allowance of the ITTC Recommended Procedure 7.5-02-03-01.4, 1978 ITTC Performance Prediction Method, revision 04 (2017), page 5: ΔC_F = 0.044[(k_s/L_WL)^(1/3) − 10 Re^(−1/3)] + 0.000125, with k_s = 150 µm as the procedure's standard value.
• Fouling: an increase of the friction coefficient over a smooth hull, as a fraction of the ITTC-1957 value, for the coating and fouling conditions of Schultz (2007). The file assets/data/Fouling/schultz_2007_categories.toml gives the seven conditions with their roughness heights and the friction coefficient each gives a 230 m plate at Re 2.29·10⁹. The values are as reproduced and computed by Demirel, Turan and Incecik, Applied Ocean Research 62 (2017), Tables 1 and 10 (open access). Schultz's own paper is not open access and was not read.

Both are frictional increments only. The wave resistance, the wake and the propeller do not change with the hull condition here.

KVLCC2CleanTransient, KVLCC2CoatedTransient, KVLCC2LightSlimeTransient and KVLCC2HeavySlimeTransient run the powered KVLCC2 with its smooth-hull full-scale resistance estimate at a constant 73.7 rpm, its 15.45 kn design speed when clean:

Hull	ΔC_F ×10³	Speed [kn]	Added resistance [kN]	Delivered power [MW]
clean	0	15.44	0	21.23
new coating (ITTC, 150 µm)	0.123	15.14	104	21.56
light slime	0.374	14.57	293	22.17
heavy slime	0.674	13.98	486	22.80

At constant shaft speed the fouled ship is slower, and its more heavily loaded propeller absorbs more power. scripts/validate_hull_roughness.jl solves the same resistance and propeller curves for the other two views and checks them against the simulated speed loss:

Hull	At 15.5 kn: added resistance	Delivered power	At the clean ship's 21.18 MW: speed	Speed lost
new coating	+6.5 %	+8.0 %	15.11 kn	0.39 kn
light slime	+19.2 %	+24.2 %	14.41 kn	1.09 kn
heavy slime	+34.5 %	+44.4 %	13.69 kn	1.81 kn

The fouling ratios come from a 230 m plate at a Reynolds number 5 % above the KVLCC2's at 15.5 kn (2.19·10⁹ on its waterline length), so they are approximate for this 325 m waterline.

Added resistance in waves

Ship6DOF.AddedResistanceWaves adds the mean resistance of a ship in head to bow waves: a surge force on the hull frame, on top of the resistance curve of HydrodynamicXYY (the pattern of HullRoughness). Its default significant wave height is zero, so the force is zero, and no existing model holds one.

The method is from the ITTC Recommended Procedure 7.5-04-01-01.1, Preparation, Conduct and Analysis of Speed/Power Trials, effective 2021, revision 06, Annex G (pages 53 and 54).

• STAWAVE-2 (the default): the parametric transfer function of wave reflection and motion-induced resistance (equations G-2 to G-11). It is integrated over the ITTC 1978 spectrum of the significant wave height and the mean period T01 (equation G-12; spectrum on page 24). The procedure limits it to:
  • 50 to 400 m length, Lpp/B 4 to 9, B/T 2.2 to 9;
  • Froude number 0.10 to 0.30, block coefficient 0.39 to 0.90;
  • waves within ±45° of the bow.
• STAWAVE-1: the reflection-only formula ρ g Hs² B √(B/L_BWL) / 16 (equation G-1), for ships with small heave and pitch. It needs the length of the bow on the waterline, L_BWL, which is not published for the KVLCC2.
• Wave-height limit: the procedure allows a speed trial up to Hs ≤ 2.25 √(Lpp/100), 4.0 m for the KVLCC2 (section 6.3, page 10). The output In_validity reports these limits.

The force is a mean value. It does not model the ship's motions in waves or any effect of the waves on the propeller.

KVLCC2CalmTransient and KVLCC2WavesHs1Transient to KVLCC2WavesHs3Transient run the powered KVLCC2 at a constant 73.7 rpm in calm water and in head seas of Hs 1, 2 and 3 m, with a mean period of 6 s. Two inputs are not from the KVLCC2 data:

• The period is an evaluation point, not a sea-state statistic.
• The pitch radius of gyration of 0.25 Lpp is an assumption. The SIMMAN 2008 data give only the yaw and roll radii.

Hs [m]	Speed at 73.7 rpm [kn]	Added resistance [kN]	Delivered power [MW]
0	15.44	0	21.23
1	15.34	33	21.33
2	15.06	131	21.65
3	14.58	291	22.17

scripts/validate_added_resistance_waves.jl solves the same resistance and propeller curves at the design speed of 15.5 kn, where the calm-water hull resistance is 1.71 MN and the delivered power 21.18 MW. The sea margin is the extra delivered power at that speed:

Hs [m]	T01 4 s	T01 6 s	T01 8 s	T01 10 s	T01 12 s
1	2.2 %	2.4 %	3.0 %	3.9 %	3.8 %
2	9.0 %	9.6 %	12.3 %	15.7 %	15.4 %
3	20.7 %	21.9 %	28.2 %	36.3 %	35.5 %

A sea margin of 15 % is the customary figure. MAN Energy Solutions' Basic principles of ship propulsion (5510-0004-05ppr, April 2023, page 35) puts the range at "10 to 30%" and says "Historically, 15% has been applied, and can be used as a first estimate". For this ship in head seas by STAWAVE-2:

• 15 % covers Hs 2 m at any of these periods except the longest. At T01 10 and 12 s it is just exceeded.
• 15 % is not enough for Hs 3 m at any period. There the ship holding the calm-water power loses 1.0 to 1.8 kn.
• The added resistance grows with Hs² and is largest at T01 of about 10 s. There the waves are long enough to pitch a 320 m hull.

The table covers head waves only. The wind's own resistance and the hull's fouling (above) come on top.

Wind resistance of hull and superstructure

Ship6DOF.WindResistance adds the wind force on the ship above the water: a surge force on the hull frame, on top of the resistance curve of HydrodynamicXYY (the pattern of HullRoughness and AddedResistanceWaves). Its inputs are the true wind velocity at 10 m, the same Wind_x, Wind_y the rotor and wing sails take. The sails keep their own forces on their own areas, which are not part of this component's area.

The force is the relative-wind resistance of the ITTC Recommended Procedure 7.5-04-01-01.1 (effective 2021, revision 06), section 10.3.1, equation 7: ½ ρ_A C_X(ψ) A_XV V_WR².

• Coefficient: by default the procedure's data set for a 280 kDWT tanker with a conventional bow, laden (Annex F.3, Table F-1 and page 41, wind-tunnel data). It is interpolated in the relative wind angle ψ.
• Still air: the procedure's equation also subtracts the still-air term, because a trial's reference from model tests already contains it. The component adds the full force, for hull resistances without air resistance, such as the KVLCC2 estimate here.
• Not represented: the side force and the yawing moment of the wind.
• Default: the frontal area A_XV is 0, so the force is zero.

For the KVLCC2 no above-water areas are published. The example uses A_XV = 1,133.6 m²:

• the hull's 533.6 m², derived as beam × (depth − draught) = 58 × (30.0 − 20.8) m from the SIMMAN 2008 particulars;
• 600 m² for the accommodation block (40 m wide, 15 m high), an assumption.

KVLCC2Wind runs the powered KVLCC2 at a constant 73.7 rpm in five conditions. Beaufort 6 is the representative sea condition of IMO MEPC.1/Circ.796, Table 2.1: head wind 12.6 m/s and head waves of Hs 3.0 m, T 6.7 s. Its waves use AddedResistanceWaves (STAWAVE-2).

Condition	Speed at 73.7 rpm [kn]	Wind [kN]	Waves [kN]	Delivered power [MW]
no air resistance (A_XV 0)	15.44	0	0	21.23
still air	15.32	41	0	21.36
head wind 10 m/s	14.83	207	0	21.90
head wind 20 m/s	13.96	493	0	22.83
Beaufort 6	13.74	258	304	23.05

scripts/validate_wind_resistance.jl solves the same curves at the design speed of 15.5 kn, against 21.18 MW without air resistance:

Condition	Extra resistance at 15.5 kn	Delivered power	Speed at 21.18 MW
still air	42 kN (2.5 %)	+3.0 %	15.35 kn
head wind 10 m/s	216 kN (12.6 %)	+15.7 %	14.72 kn
head wind 20 m/s	522 kN (30.5 %)	+39.1 %	13.61 kn
Beaufort 6	599 kN (35.0 %)	+45.2 %	13.33 kn

What the tables show:

• A 10 m/s head wind alone uses up the customary 15 % sea margin (see the section above).
• Beaufort 6 from ahead needs three times it.
• These are head-on conditions, the worst case. Wind from the side or from behind costs less, and from astern it pushes.

Shallow water: resistance increase and squat

Ship6DOF.ShallowWater adds the resistance increase of a ship in water of finite depth h as a surge force on the hull frame, like HullRoughness and AddedResistanceWaves. It takes the hull's own deep-water resistance as an input (R_deep, connected to -HydrodynamicXYY.Resistance). Its default depth is 0, meaning deep water, so the force is zero and every existing result is unchanged.

Resistance: the Raven correction of the ITTC Recommended Procedure 7.5-04-01-01.1, Preparation, Conduct and Analysis of Speed/Power Trials, effective 2021, revision 06, Appendix K.1 (pages 72 to 74). It has two parts:

• Viscous part: the deep-water viscous resistance (equations K-1 to K-6), increased by 0.57 (T/h)^1.79 (K-7). It is limited to the whole deep-water resistance (K-12).
• Sinkage part: the additional dynamic sinkage (K-8) gives a displacement increase of at most 5 % (K-9). The resistance grows with its 2/3 power (K-10).

The procedure states K-11 as a correction from a trial in shallow water to deep water. Read the other way at the same propulsive efficiency, the shallow-water resistance is (1 + δ∇)^(2/3) (R_deep + ΔR_V).

The procedure limits the method to h ≥ 2.5 T and h ≥ 2.4 V²/g (section 6.4). The output In_validity reports this, and shallower depths are extrapolated with one warning. The 2017 edition (revision 07) adds a note that its shallow-water corrections are not "adequately validated for large seagoing vessels". The Lackenby (1963) speed loss of that edition (Appendix K.1, K-1) is an output for comparison.

Squat, the maximum sinkage, comes from two empirical formulas in the PIANC Working Group 30 set, as reproduced with their ranges by Serban and Panaitescu (2016), Comparison between formulas of maximum ship squat, Mircea cel Batran Naval Academy Scientific Bulletin XIX(1), 105-111 (open access), equations 1 to 3 and Table 1:

• ICORELS: S_b = 2.4 (∇/L²) Fr_h² / √(1 − Fr_h²). Its ranges are an unrestricted channel, C_B 0.6-0.8, B/T 2.19-3.5, h/T 1.1-2.0, L/B 5.5-8.5 and L/T 16.1-20.2.
• Barrass: S_max = K C_B V_kn² / 100 m. K is 1 in open water. Its ranges are C_B 0.5-0.85 and h/T 1.1-1.4.

The under-keel clearance UKC is h − T − the larger squat. The outputs ICORELS_in_range and Barrass_in_range report the ranges. The KVLCC2 (C_B 0.81, L/T 15.4) is just outside the ICORELS ranges, and inside Barrass's only at h/T 1.2.

Not modelled: shallow-water effects on the propeller and wake, trim and manoeuvring; banks and channel blockage (apart from the Barrass blockage factor).

Example. KVLCC2Shallow is the powered KVLCC2 with a ShallowWater component. Its water plane area is assumed from the hull's C_W of 0.9, because the SIMMAN data do not give it. scripts/validate_shallow_water.jl runs it at h/T = 1.2, 1.5, 2 and 3 and in deep water, at the design 73.7 rpm and at 47.6 rpm (10 kn in deep water):

h/T	Speed at 73.7 rpm [kn]	Added resistance [kN]	Delivered power [MW]	Squat ICORELS / Barrass [m]	UKC [m]
deep	15.44	0	21.23	–	–
3	15.03	139	21.67	0.75 / 1.83	39.8
2	14.62	276	22.12	1.10 / 1.73	19.1
1.5	14.15	431	22.63	1.40 / 1.62	8.8
1.2	13.64	595	23.16	1.65 / 1.51	2.5

With the same resistance and propeller curves, at constant speed:

h/T	15.5 kn: added resistance	15.5 kn: delivered power	15.5 kn: UKC [m]	10 kn: added resistance	10 kn: delivered power	10 kn: UKC [m]
deep	0	21.18 MW	–	0	5.69 MW	–
3	+8.7 %	+10.7 %	39.6	+8.2 %	+10.2 %	40.8
2	+18.3 %	+23.0 %	18.9	+17.2 %	+21.6 %	20.0
1.5	+30.9 %	+39.6 %	8.5	+28.8 %	+36.9 %	9.6
1.2	+45.8 %	+60.0 %	1.9	+43.0 %	+56.2 %	3.3

Notes on these results:

• Depth limit: only h/T = 3 is inside the ITTC limit. The shallower rows extrapolate the correction.
• Viscous resistance: the KVLCC2's deep-water resistance here is a friction-only estimate, below the Raven viscous resistance, so K-12 limits the viscous part to it.
• Lackenby: its speed loss at h/T 1.2 is 23 % (at constant power). The simulation loses 12 % at constant shaft speed.

A speed/power trial analysis on synthetic trial data

KVLCC2Trial is the powered KVLCC2 with all four added-resistance components at once: hull roughness, wind, waves (STAWAVE-2) and shallow water. scripts/validate_speed_power_trial.jl uses it to generate synthetic trial data. These data are not a real trial. They come from the model itself, in stated conditions:

• Ship condition: hull roughness k_s 150 µm.
• Wind: true wind 12 m/s from 30° off the starboard bow on the first run of each pair.
• Waves: head seas Hs 2 m, T01 6.7 s on the first run. They come from astern on the return run, outside the ±45° sector that the procedure corrects, so the model gives them no resistance there.
• Water depth: 3 T = 62.4 m, inside the procedure's depth limit.
• Other: no current, and the reference water density.
• Runs: double runs at 55, 65 and 73.7 rpm.

The data are then analysed by ITTC 7.5-04-01-01.1 (effective 2021, revision 06), in the order of its section 11. Every step uses the merged components' own equations:

1. True wind: averaged over the double run, and each run's relative wind recomputed from the average (Appendix E).
2. Wind resistance increase: equation 7, the relative-wind force less the still-air term, with the table of WindResistance.
3. Wave resistance increase: STAWAVE-2 (Appendix G.2), with stawave2_mean.
4. Direct Power Method: equation 5 / D-5. The ideal-condition propulsive efficiency and the overload factor ξ_P (D-3) come from a load variation on the model's own resistance and propeller curves; the model stands in for the tank tests. At 13.8 kn, ξ_P = −0.21 and η_D = 0.63.
5. Shallow water: Appendix K.1, K-11 with the K-12 limit, with raven_viscous_coefficient.

The water density, displacement and current corrections are not exercised.

The corrected powers are compared with the model's own calm deep-water curve: the same ship in the ideal condition (no wind, waves or shallow water; still air; the same roughness), run at seven shaft speeds. Mean of each double run:

Water depth	Shaft speed [rpm]	Mean speed [kn]	Measured P_D [MW]	Corrected P_D [MW]	Ideal curve [MW]	Measured above ideal	Corrected above ideal
3 T	55	10.56	9.40	7.59	7.34	+28.0 %	+3.3 %
3 T	65	12.55	15.46	12.87	12.49	+23.8 %	+3.0 %
3 T	73.7	14.28	22.49	19.09	18.54	+21.3 %	+3.0 %
deep	55	10.83	9.24	8.01	7.93	+16.6 %	+1.0 %
deep	65	12.88	15.19	13.61	13.51	+12.4 %	+0.7 %
deep	73.7	14.65	22.08	20.20	20.09	+9.9 %	+0.5 %

Size of the corrections, at the design shaft speed on the head-sea run in 3 T:

Item	Value
Wind resistance increase	170 kN
Wave resistance increase	135 kN
Power removed by the Direct Power Method	4.30 MW
Power removed by the shallow-water step	1.42 MW
Remaining power	17.27 MW, against 16.71 MW on the ideal curve at 13.8 kn

Where the residual comes from:

• Wind and waves in deep water: each run comes within 0.6 % of the ideal curve at its own speed.
• Double-run means: they carry up to 1 % more. The two runs differ by up to ±5 % in speed, and the power curve is convex.
• Shallow water: K-11 does not correct the loss of propulsive efficiency from the shallow-water load, about ξ_P R_shallow / R_id ≈ 1.7 %. Section 10.2.3 says this "could be ignored". The return runs match that figure.
• Head-sea runs in shallow water: they come out a further 1.6-1.9 % high. There the wind-and-wave load and the shallow-water load act on the propeller together, while the procedure removes them in turn as if they were independent.

Engine-propeller matching: the load diagram

Ship6DOF.EngineLoadDiagram places a two-stroke main engine's operating point on the engine maker's load diagram. It reads shaft speed and power, in percent of the SMCR (the specified maximum continuous rating), and only reports; it does not limit the engine.

The lines and their definitions come from the Everllence (formerly MAN Energy Solutions) G60ME-C10.5 Project Guide, section 2.03 "Engine layout and load diagram" (marked "All engines", 2025-06-16), Fig. 2.03.02. The same lines appear in Basic principles of ship propulsion (5510-0004-05ppr, 2023), pages 34-41.

• Line 1, the engine layout curve (= line 2, the heavy propeller curve): the propeller law P = 100 (n/100)³ through SMCR.
• Line 4, the torque/speed limit: the guide gives no equation for it. It is digitised from the figure's raster: P = 103.3 (n/100)^2.00 between 40 and 95 % speed, with 0.22 % of SMCR power largest deviation over 52 points, and a straight line from the origin below 40 %.
• Line 5, the maximum mean effective pressure: "corresponding to 100 % torque", P = n. Line 4 is the stricter limit below 96.8 % speed.
• Line 7: the maximum continuous power, 100 %.
• Line 3: 105 % speed.
• Line 8, the overload limit (1 hour in 12): "110 % of the power at MCR" (section 1.04). Below full speed the guide draws it without an equation. Here it is 110 % of the continuous limit at each speed, an interpretation that is exact at 100 % speed.

Outputs:

• the continuous limit (the lowest of lines 4, 5 and 7) and the margin to it;
• the running margin to line 1, (n − n₁)/n₁ as in the light running margin of EQ 35, negative when heavier than line 1;
• the region: 1 recommended, 2 heavy, 3 overload, 4 beyond, the last with one warning.

Example: the KVLCC2. The SMCR is derived from the ship's own clean, calm-water propeller curve (the light propeller curve), with the margins of Basic principles (EQ 33 and 34):

• Propeller design point: 73.72 rpm and 21.18 MW at 15.5 kn.
• SMCR power: a sea margin of 15 % and an engine margin of 10 % give 27.07 MW.
• SMCR speed: a light running margin of 5 % (the guide recommends 4-7 %) gives 76.0 rpm.
• Light curve at SMCR power: the light propeller curve reaches 100 % power at 105.3 % speed (EQ 35: 5.26 %).
• Not modelled: brake and delivered power are taken equal.
• Engine: no particular engine rating was checked. The load diagram depends on the SMCR alone.

The propeller curves of the model are then placed on the diagram. They come from the merged components:

• the resistance and propeller curves of PoweredKVLCC2Ship;
• the Schultz (2007) fouling categories of HullRoughness;
• STAWAVE-2 head seas with T01 6 s from AddedResistanceWaves.

Condition	Power at SMCR speed	Light running margin needed	Meets the continuous limit at	Overload limit (line 8) at	Ship speed at the limit
Clean, calm (light curve)	85.7 %	–	not below 105 %	–	–
Head seas Hs 2 m	87.4 %	0.6 %	104.7 % speed (line 7)	–	16.36 kn
Head seas Hs 3 m	89.4 %	1.4 %	103.9 % (line 7)	–	15.77 kn
Heavy slime	92.2 %	2.5 %	102.8 % (line 7)	–	14.87 kn
Heavy slime + Hs 3 m	95.2 %	3.6 %	101.7 % (line 7)	–	13.99 kn
Medium calcareous fouling	98.2 %	4.7 %	100.6 % (line 7)	103.8 %	13.05 kn
Medium calcareous + Hs 3 m	100.7 %	5.5 %	99.7 % (line 5)	103.0 %	12.30 kn
Heavy calcareous + Hs 3 m	103.9 %	6.5 %	98.1 % (line 5)	102.0 %	11.26 kn

What the table shows:

• Up to heavy slime in Hs 3 m: the 5 % light running margin covers the condition. The curve reaches the continuous limit only above 100 % speed, on line 7.
• Medium calcareous fouling with Hs 3 m: this needs 5.5 %. At the SMCR speed it puts the engine in the overload region, at 100.8 % power in the simulation (KVLCC2LoadDiagramHeavyTransient). The engine must slow below 99.7 % speed to stay continuous, and the ship then makes 12.3 kn.
• Line 4: none of these curves reaches it. A propeller-law curve meets line 4 below 96.8 % speed only if it is 7.5 % heavier than the light curve here.

scripts/validate_engine_load_diagram.jl checks:

• the lines and the regions;
• the SMCR derivation;
• each curve, with the statements above;
• the component in two simulations at the SMCR speed (clean, and medium calcareous with Hs 3 m), within 1 % of the arithmetic (which has no rudder drag).

IMO energy efficiency: EEXI and CII

definitions.jl holds the index formulas of MARPOL Annex VI chapter 4 as plain functions. Ship6DOF.CarbonIntensityMeter counts fuel, CO2 and distance on any simulated ship. scripts/validate_energy_efficiency.jl applies both to the KVLCC2, using its own speed-power curve. No ship physics is added.

Sources:

Item	Source
Attained EEXI	resolution MEPC.350(78), the 2022 EEXI calculation guidelines, which revoked MEPC.333(76): formula 2.1; P_ME = 75 % MCR, or with an engine power limitation the lower of 83 % MCR_lim and 75 % MCR (2.2.1); SFC 190 / 215 g/kWh and C_F 3.114 where no NOx Technical File value exists (2.2.4, 2.2.5)
Auxiliary power	MEPC.364(79) 2.2.5.6.1: 0.025 MCR + 250 kW
Required EEXI	MEPC.328(76), MARPOL Annex VI regulation 25 Table 3 (tanker ≥ 200 000 DWT: Y = 15 %) on the EEDI reference line of regulation 24 Table 2 (tanker: a = 1218.80, c = 0.488)
CII	MEPC.352(78) G1, AER = CO2 / (DWT × distance); MEPC.353(78) G2 Table 1, tanker reference a = 5247, c = 0.610; MEPC.338(76) G3 Table 1, Z = 11 % for 2026; MEPC.354(78) G4 Table 1, tanker boundaries exp(d) = 0.82 / 0.93 / 1.08 / 1.28

Stated inputs that are not KVLCC2 data:

• Capacity: 300 000 DWT, the "300 K tanker" of the SIMMAN 2008 description.
• MCR: 27 068 kW, derived in the load-diagram example.
• Power: brake power is taken equal to delivered power.
• Resistance: the full-scale estimate of PoweredKVLCC2Ship, which is smooth-hull and friction-only, the low end.

EEXI. The model's speed-power curve (seven settled runs from 50 to 78 rpm) gives V_ref = 15.21 kn at 75 % MCR (20 301 kW). With P_AE = 927 kW:

	g CO2 / (t nm)
Attained EEXI	2.768
Required EEXI (300 000 DWT)	2.200

The ship does not meet the requirement. An engine power limitation would bring it in:

EPL result	Value
Limited MCR	16 763 kW, 61.9 % of MCR
P_ME = 0.83 MCR_lim	13 913 kW
V_ref	13.41 kn
EEXI	2.200

CII, a SYNTHETIC operating year 2026. The profile is stated, not data:

• 250 days at sea, all laden, at 59.5 rpm (12.46 kn, 11.2 MW);
• 115 days in port or at anchor, with the 927 kW auxiliary load only;
• no cargo-pump, boiler or ballast-passage fuel.

KVLCC2CarbonIntensityTransient runs the service point with the meter.

	g CO2 / (t nm)
Attained AER	2.010
CII_R (300 000 DWT)	2.393
Required for 2026 (Z = 11 %)	2.129

The ratio is 0.944, so the rating is C, near the B boundary at 0.93. The same year at other sea speeds rates:

Sea speed [kn]	10.5	11.5	12.6	13.6	14.7	15.7	16.3
Rating	A	B	C	D	D	E	E

Below 13 kn the ship stays at C or better. The EPL limit, 13.4 kn at 0.83 MCR_lim, is above the service speed, so it does not constrain this year's operation.

Active fin stabilisers

Ship6DOF.FinStabilisers is a pair of horizontal fins at the bilges. Each fin is the library's Rudder, mounted with its stock across the ship, so its lift is vertical. It keeps everything the rudder model has:

• the steering gear's angle and rate limits;
• the NACA 0015 lift and drag tables with their aspect-ratio correction;
• the inflow measured at the fin, which includes the fin's own vertical velocity from roll, so a fin held at zero angle already damps roll.

The rudder's slipstream, wake, hull-interaction and flow-straightening terms are switched off.

• Controller: the fin angle is δ = K_roll·φ + K_rate·p, from heel and roll rate in degrees, with user gains.
• Drag: the fins add the induced drag of their lift, C_Di = C_L²/(π AR e) with e = 0.7 (NASA Glenn, Induced Drag Coefficient), to the rudder model's section drag.
• Default fin: the largest of the Kongsberg Aquarius retractable stabiliser, model 100: 5.78 m² and 3.99 m outreach (datasheet 04.Stab, 2022). That gives a derived mean chord of 1.45 m.
• Assumptions: the datasheet prints no lift, so lift comes from the tables. The ±20° angle limit and 20°/s rate limit are assumptions.

Ship6DOF.BeamSeaRollMoment is the roll moment of a regular beam sea in the long-wave approximation: ρ g ∇ GM k ζ_a sin ωt, the roll stiffness times the wave slope (TU Delft OE4630, after Journée and Massie). It has an effective-slope factor to adjust. It is crude when the waves are only a few beams long.

The example puts the sample hull (StandardShip, 100 rpm, 6.03 m/s) in a beam sea of 0.25 m amplitude at its nominal roll period, 8.38 s, with the fins in three states. The last 100 s of 600 s give:

Fins	Roll amplitude	Speed	Fin drag (of which induced)	Shaft power
retracted	3.87°	6.034 m/s	—	1,113.7 kW
deployed, held at 0°	3.54°	6.032 m/s	1.6 kN (0.8)	1,114.1 kW
active, K_roll 1, K_rate 10	2.25° (−42 %)	5.899 m/s	14.9 kN (13.3)	1,136.0 kW
active, calm water	0.03°	6.044 m/s	0.8 kN (0.0)	1,112.0 kW

• Drag cost: active in this sea, the fins' mean drag is 12 % of the hull's 127 kN resistance. Most of it is induced drag, which costs 2.2 % of the speed at constant shaft speed. In calm water, deployed, their drag is 0.6 % of the hull resistance.
• More gain is not better: at K_rate 15 to 30 the fins sit at their 20° limit, roll more (2.5° to 3.1°) and drag twice as much.
• Not represented: fin stall dynamics, the hull's influence on the fins' inflow, and the sway and diffraction of a real beam sea.

At anchor: chain catenary and holding

Ship6DOF.AnchorChain is a bow anchor and its chain cable, attached at the hawse pipe. The chain is a static, inextensible catenary in the vertical plane through the hawse and the anchor. It is recomputed from the present geometry at every instant (quasi-static: no chain dynamics or drag). anchor_chain_state covers the three cases:

• Slack: the chain hangs straight down and the rest lies on the seabed.
• Touchdown: the suspended length is s = √(h² + 2 h a) with a = H/w, and the span is L − s + a asinh(s/a) (NAVFAC DM-26.5 Fleet Moorings, 1985, equations 5-83 ff.).
• Lifted: the whole chain is suspended and pulls the anchor up.

The chain cannot stretch, so a span beyond the taut length √(L² − h²) is clamped just short of it. The chain's force on the hull is the horizontal H towards the anchor and its suspended weight downwards.

• Chain: stud link of grade 1 to 3, 0.02191 d² kg/m in air and 0.87 of that in water (DM-26.5 equations 5-81 and 5-82). Breaking load from IACS UR A1 Rev.7 Table 4.
• Seabed friction: the chain on the seabed takes μ w L_seabed of the load by friction, μ = 0.70 sliding (ABS Guidance Notes on Design and Installation of Drag Anchors and Plate Anchors, 2017, Appendix 7 Table 2 and equations A7.2-A7.3). The rest reaches the anchor.
• Holding capacity: efficiency × anchor weight, with efficiency 4, the "safe" value in sand for the stabilized Navy stockless anchor (DM-26.5 Table 18). Mud gives 2.75, hard soil 3, and an ordinary ship's stockless anchor may hold less.
• Holds: the output Holds is 1 while the anchor load is within the capacity and the anchor is not lifted. Otherwise it is 0, with one warning. The anchor does not move in the model: dragging is reported, not simulated.

The hull family has new parameters current_x and current_y, a uniform current seen by hull, propeller and rudder. They default to 0, so earlier results are unchanged.

Example. KVLCC2AtAnchor is the powered KVLCC2 at 0 rpm on one bow anchor, with wind, head waves and current all from ahead. Its equipment comes from UR A1 Table 1:

• Equipment Number: 7 724, from A1.2.1. The deckhouse (14 m high, 40 m long) is assumed, because the SIMMAN data do not give the superstructure.
• Table 1 row (7 400-7 900): anchors of 23 000 kg and grade 3 chain of 117 mm (breaking load 9 300 kN).
• Hawse pipe: assumed 5 m aft of the forward perpendicular and 8.2 m above the waterline.
• Scope: 6 times the depth, the minimum UR A1 assumes (A1.1.4).

The environmental force is the sum of three components, each with the formula of the merged component:

• Wind: WindResistance with the KVLCC2's A_XV.
• Current: the hull's quadratic resistance at the current speed.
• Waves: STAWAVE-2 with T01 = 6 s, an assumption.

The holding capacity is 902 kN. scripts/validate_anchor_chain.jl computes the following for UR A1's two design environments (A1.1.4):

Environment	Wind + current + waves	Depth	Chain	Offset	On seabed	Anchor load	Chain safety factor
Alternative, L > 135 m: 1.54 m/s, 11 m/s, Hs 2 m	81 + 64 + 84 = 228 kN	30 m	180 m	27.1 m	89 m	69 kN	28.5
		45 m	270 m	35.3 m	159 m	0	25.5
		60 m	360 m	42.8 m	230 m	0	23.1
Basic: 2.5 m/s, 25 m/s, no waves	417 + 168 = 585 kN	30 m	180 m	31.0 m	42 m	509 kN	13.6
		45 m	270 m	41.5 m	105 m	397 kN	12.9
		60 m	360 m	51.4 m	171 m	279 kN	12.2

The anchor holds in every case.

• Offset: measured from the position where the chain hangs straight down to the anchor.
• Restoring force at 45 m: 8, 25, 61, 146 and 428 kN at offsets of 8, 16, 24, 32 and 40 m, then steeply up towards the taut chain (48 m).
• Check against the simulation: started at these equilibria, the simulated ship stays within 0.02 m. Its chain force and environmental forces agree with the static ones within 2 %.

Not modelled: chain elasticity and dynamics, yawing at anchor (the forces here are all from ahead), and the anchor dragging.

A ducted propeller: Ka 4-70 in nozzle 19A

Ship6DOF.DuctedPropeller1Q is the Wageningen Ka 4-70 propeller in the accelerating nozzle 19A. It is Propeller1QBase with ducted = 1: the open-water lookup of the shared base takes Oosterveld's (1970) regression polynomials for this propeller and nozzle instead of the B-series regression. The connectors, wake, thrust deduction, torque reaction and slipstream are the base's.

• Kt is the total thrust coefficient, propeller plus nozzle. Kt_nozzle reports the nozzle's share of it.
• The coefficients come from a secondary reproduction: A. Saari, MSc thesis, Aalto University, 2014, Appendix C, Table C.2. That thesis uses them for the propellers tested in nozzle 19A. Oosterveld's Wake Adapted Ducted Propellers (NSMB Publication 345) itself was not read.
• Validity in this library: P/D 0.5 to 1.2. The PIAS manual gives the original polynomials as valid for P/D 0.5 to 1.6 (after Oosterveld, RINA 1973). With the reproduced tables, however, above P/D of about 1.3 the torque rises with J and the zero-thrust J falls with pitch, which is unphysical. The cause is probably a transcription error in the (P/D)⁶ terms, which no second reproduction was available to check (a recorded data gap). In_validity flags P/D outside 0.5 to 1.2, and the first use there emits a warning.
• At P/D 1.0 the thrust is zero at J = 0.68.

BollardRigOpen and BollardRigDucted hold an open B4-70 and the Ka 4-70 / 19A in open water. Both have the same 3.0 m diameter and P/D 1.0, and their shafts are driven at the same 2.0 MW. These are illustrative tug values, not data of a vessel. scripts/validate_ducted_propeller.jl checks the four rig runs (bollard and 3 m/s) against the steady balance and prints the comparison at equal power:

Speed of advance	Open B4-70	Ka 4-70 / 19A	Ducted / open
0 (bollard pull)	268 kN	411 kN	1.53
2 m/s	248 kN	313 kN	1.26
3 m/s	236 kN	263 kN	1.12
4 m/s	223 kN	209 kN	0.94
6 m/s	196 kN	81 kN	0.41

• Bollard pull: the nozzle gives 53 % more at the same power and diameter. That is why tugs and offshore vessels use it.
• Cross-over: above 3.68 m/s (7.2 kn) the open propeller gives more thrust, and so more efficiency, for the same power. At the cross-over both work near J = 0.4 at an efficiency of 0.42.
• High speed: at 7 m/s the ducted propeller's thrust is nearly gone. Its zero-thrust J is close.

Azimuth thrusters

Ship6DOF.AzimuthThruster is a propeller on a strut that slews through 360°. It is open (B-series) or ducted (Ka 4-70 / 19A, the default), and it is the library's Propeller1Q with the ducted switch of Propeller1QBase. No propeller equation is repeated. The unit is mounted on the hull like the tunnel thruster and the pod, and the steering is the arrangement of POD4Q:

• Slewing: a revolute joint driven to the azimuth order, limited in rate and smoothed by a 1 Hz filter.
• Thrust vector: the propeller reads its own inflow along the unit's axis, so the thrust vector, the force and the yaw moment on the hull at the unit's position come from the joints.
• Slewing drive: it reports its torque and power on the unit's slewing inertia. The steering moment of a propeller in oblique flow is not represented, so the drive power is a lower bound.
• Reversed flow: facing the flow, the advance ratio is held at zero rather than extrapolating the first-quadrant regressions.
• When to use which: use POD4Q where a propeller must run astern on its shaft, and this component where the thrust is reversed by slewing.

Defaults:

• Unit: the SCHOTTEL RudderPropeller SRP 490 (Product Guide 11/25: 2050–2550 kW, 2.8 m propeller).
• Shaft speed: the example's 224 rpm is derived as the speed at which the ducted propeller absorbs 2550 kW at bollard pull. The guide prints no propeller speed.
• Assumptions: the guide prints no slew rate, bollard pull or inertia. The 12 °/s slew rate, the slewing inertia and the nozzle and P/D 1.0 are assumptions.

The example fits two units to the 100 m sample hull in place of its propeller and rudder.

• Crash stop: from its steady 6.28 m/s, both units slew round to face astern, one through port and one through starboard, at constant shaft speed. The ship stops in 48.5 s and 184 m, ending 6 m off its line: nothing keeps its course, and its heading had drifted 4.7° in the approach. CrashStop, the conventional propeller and rudder of the same hull reversing its shaft over 60 s, needs 266.8 s and 848 m from 6.83 m/s. The installed powers differ: about 2 × 1.9 MW against 1.4 MW at the approach.
• Turn on the spot: from rest, one unit pushes ahead and the other astern. The ship turns at 0.69 °/s to starboard and has turned 154° after 240 s. It moves about 64 m while the second unit slews round, so it is not a pure rotation. A single propeller with a rudder cannot do this at zero speed.
• Slewing drive: it peaks at a few kW for the inertia alone.

Propeller cavitation check

Propeller1QBase reports a cavitation check of the blades. It applies to every propeller that extends it: Propeller1Q, DuctedPropeller1Q, the controllable-pitch propeller and the azimuth thruster's propeller. The check is switched on by the depth of the shaft centreline below the free surface, ShaftImmersion. Its default of 0 leaves it off, so every existing result is unchanged.

Formulas:

• Cavitation number at 0.7R: σ = (p_0 − p_v) / (½ ρ V_R²), where p_0 is atmospheric plus hydrostatic pressure at the shaft, p_v is the vapour pressure (1700 Pa) and V_R² = V_A² + (0.7 π n D)².
• Burrill thrust loading: τ_c = T / (A_P ½ ρ V_R²), with the projected area A_P = A_E (1.067 − 0.229 P/D).
• Keller's minimum area ratio: (1.3 + 0.3 Z) T / ((p_0 − p_v) D²) + K, where K is 0.2 for a single screw, 0.1 for a slow twin-screw ship and 0 for a fast twin-screw ship.
• Thrust: T is the thrust of the blades. For the ducted propeller that is the total less the nozzle's part.

Burrill limit: the limit on τ_c is the Burrill line for Burrill_C % back cavitation (default 5 %). It is taken from the Carmichael correlation τ_c = C (0.0305 σ^0.2 − 0.0174) + 0.523 σ^0.2 − 0.3064, an analytic fit of Burrill's diagram (quoted for C up to about 25 %), so nothing is digitised. Burrill_cavitation solves the same fit for the propeller's own back cavitation.

Sources:

• MIT OpenCourseWare 2.611 Marine Power and Propulsion, Fall 2006, notes Cavitation. They give σ, τ_c, the projected area and the Carmichael correlation with a worked example (σ 0.4 and τ_c 0.2 give 8.88 %), which the validation reproduces.
• Ship Hydrodynamics Lecture Notes, Part 6: Cavitation, p. 20, on Korea OpenCourseWare. They give Keller and the K values.
• The original papers (Burrill 1943, Keller 1966) were not read.

Outputs:

• Sigma_07R and Tau_c: the cavitation number and the Burrill thrust loading above.
• Burrill_tau_limit and Burrill_margin: the Burrill limit on τ_c and how far below it the propeller is.
• Burrill_cavitation: the estimated back cavitation in %.
• Keller_Ae_Ao_min and Keller_margin: Keller's minimum area ratio and the actual ratio's margin over it.
• Cavitation_OK: 0, with one warning, when either margin is negative.

Both criteria are design rules for conventional open propellers. For the ducted propeller they are indicative only.

KVLCC2 at its design 73.7 rpm (15.44 kn). The SIMMAN 2008 propeller has 4 blades, P/D 0.721 and Ae/A0 0.431; KVLCC2Hull now passes these to its propeller. The blade thrust is 2.20 MN.

• Laden draught: the shaft is 15.3 m deep (draught 20.8 m less the shaft's 5.5 m above the keel).
• Ballast immersion: a stated condition. 33 CFR 157.10 (the US text of MARPOL Annex I regulation 18.2) requires a mean draught of at least 2.0 + 0.02 L = 8.4 m, a trim by the stern of at most 0.015 L and a fully immersed propeller. At the largest trim that gives a draught aft of 10.8 m and a shaft 5.3 m deep. The thrust is held at the design value, so this case shows the effect of immersion alone.

Case	σ (0.7R)	τ_c	Burrill limit at 5 %	Back cavitation	Keller minimum Ae/A0	Actual Ae/A0	Check
KVLCC2, laden (shaft 15.3 m)	0.672	0.197	0.230	1.9 %	0.423	0.431	passes
KVLCC2, ballast immersion (5.3 m)	0.405	0.197	0.171	8.2 %	0.570	0.431	fails both
Ducted Ka 4-70 / 19A, bollard (shaft 3.0 m)	0.618	0.231	0.220	6.0 %	0.630	0.70	fails Burrill
Open B4-70, bollard (shaft 3.0 m)	0.819	0.408	0.256	17.8 %	0.774	0.70	fails both

• KVLCC2: the propeller is just adequate laden, with a Keller margin of 0.008. At the ballast immersion it is not.
• Bollard rigs: 2 MW and a 3.0 m propeller. The 3.0 m shaft immersion is an assumption for a harbour tug. In the ducted unit the nozzle carries 51 % of the 411 kN, so its blades are much less loaded than the open propeller's, which carries all of its 268 kN.

scripts/validate_propeller_cavitation.jl checks each output against the formulas written out again at the simulated operating point. It also checks that the B-series speed trial, the KVLCC2 powering run and both bollard rigs are unchanged.

A controllable pitch propeller

Ship6DOF.ControllablePitchPropeller gives thrust and torque from the shaft speed, the speed of advance and a pitch order. It shares everything with the fixed-pitch Propeller1Q through the partial Propeller1QBase (connectors, parameters, open-water lookup, thrust, torque reaction, slipstream) and differs in one line: the pitch ratio follows Pitch_order, held to the range of the regression (0.5 to 1.4), with a first-order lag. The open-water data are the Wageningen B-screw series polynomials of Oosterveld and van Oossanen (1975), which the library already carries, read at the pitch in use. The series propellers are fixed-pitch designs, so this treats the propeller as the series propeller of the same pitch at each setting: there is no zero or reverse pitch and no off-design loss.

CPPShipPitchStepsTransient runs the sample ship at a constant 100 rpm and steps the pitch:

P/D	Speed [m/s]	J	Thrust [kN]	Torque [kN·m]	Shaft power [kW]
1.0	6.054	0.604	129.1	106.0	1110
0.8	5.300	0.528	92.5	65.6	687
0.6	4.330	0.432	60.4	37.9	397

A tunnel (bow) thruster

Ship6DOF.TunnelThruster is a fixed-pitch propeller in a transverse tunnel. It takes a shaft on flange and pushes the hull along +y of its frame (to port). Static thrust and torque are KT0 ρ n|n| D⁴ and KQ0 ρ n|n| D⁵, the same in both directions. The defaults are derived from the public Kongsberg TT-PM 2000 datasheet (leaflet 06.Tunnel, 20.04.21, page 2): a 2.0 m propeller, about 243 kN, 1600 kW and 280 rpm, on the assumption that these figures go together. Its static merit coefficient (Beveridge 1971, below) is 1.32, inside the 0.55 to 1.50 his Table 1 gives for model thrusters.

Ahead speed reduces the side force and yaw moment. The jet bends aft along the hull and draws suction behind it. The thruster multiplies its static thrust by the body force and moment coefficients K_F and N' of J. L. Beveridge, Design and Performance of Bow Thrusters (NSRDC Report 3611, 1971, public release; Fig. 2b on page 28, after Chislett and Björheden 1966). Both coefficients are plotted against the ratio of ship speed to jet speed U/Uj, with Uj = sqrt(T/(ρA)). The points are read by eye from the scanned figure and are ordinary parameters; the curve belongs to one ship and one thruster. No astern data were found, so the ahead curve is applied to |u|. The side force acts at the tunnel. A pure torque makes the moment about the centre of gravity N' T x_T (lever_arm).

BowThrusterShip adds the thruster to the standard hull, 90 m forward of the aft perpendicular. In BowThrusterTurnOnSpotTransient the stopped ship turns bow to port under full thruster speed; reversed, in BowThrusterTurnOnSpotReverseTransient, it turns bow to starboard at the mirrored rate. In BowThrusterUnderWayTransient the same thruster runs at 6 m/s. scripts/validate_tunnel_thruster.jl checks the thrust, torque and power against the coefficients, and the yaw rate sign. It checks the cut force and torque at the mount against the lever arm, and the forward-speed factors. It also checks that the speed trial without a thruster is unchanged. The MMG hull model is meant for forward speed, so the yaw rate the stopped ship settles at is indicative only. A flat-plate cross-flow drag estimate (Beveridge, page 20) gives the same order.

Case	U/Uj	K_F	N'	Side force [kN]	Yaw moment about G [kN·m]	Result
Stopped, end of the 10 s ramp	< 0.1	≈ 1	≈ 1	≈ 242.9	≈ 9 630 (T x_T)
Spinning, t = 200 s	0.17	0.90	1.02	218.7	9 820	1.60 °/s bow to port after 300 s (flat plate 2.23 °/s)
5.8 m/s, 280 rpm	0.67	0.31	0.64	74.6	6 150

Static thrust 242.9 kN, torque 54.6 kN·m and shaft power 1600 kW at 280 rpm; lever arm 39.6 m.

A rotor sail

Ship6DOF.RotorSail is a Flettner rotor on a 3D frame: a vertical cylinder spun by an electric motor at the ordered Spin_Order [rpm], positive counter-clockwise seen from above. It uses the same interface as WingSail: it takes the world wind on Wind_x / Wind_y, measures the apparent wind with ApparentSpeedXY at mid-height, and applies drag along the wind and Magnus lift across it at that point. Lift and drag coefficients depend on the spin ratio k (peripheral speed over apparent wind speed). They are the printed values of E. G. Reid, Tests of Rotating Cylinders, NACA TN 209 (1924), Table I, pages 10–11. Those are two-dimensional, model-scale coefficients and overstate a ship rotor's thrust; replace them when better data exist. The electrical load ElectricalPower is the spin power C_f ρ U_t³/2 · π D H (Bordogna 2020, TU Delft PhD thesis, eq. 4.3, page 57) over a drive efficiency. The default C_f is derived so that the default rotor (4 m × 24 m, up to 225 rpm, the Norsepower 24 m × 4 m size from the 2023 brochure, page 3) draws the 80 kW motor rating at 225 rpm. That is an assumption, not a measurement. No public drive efficiency was found, so it defaults to 1. The spin torque reacts on the hull.

RotorSailSweepTransient spins a rotor on a fixed mount in a 10 m/s wind up to 225 rpm. BeamWindShipTransient runs the standard ship at 100 rpm, heading east under the autopilot, in a 10 m/s wind from port. RotorSailBeamWindTransient runs the same case with one rotor, 75 m forward of the aft perpendicular, held at spin ratio 3. scripts/validate_rotor_sail.jl checks the table, force directions, spin power and mount loads. It also compares the two ship runs and the brochure's polar diagram (19 kn, read as more than 500 kW propulsion-power equivalent at 10 m/s true wind abeam, efficiency 0.7, i.e. more than 35.8 kN).

Case (steady, last 100 s of 900 s)	Speed [m/s]	Propeller thrust [kN]	Shaft power [kW]	Heel [°]
BeamWindShip, no rotor	5.983	130.8	1122	0.29
RotorSailBeamWind	6.540	117.0	1028	0.61

At the same shaft speed the rotor gives 0.557 m/s (9.3 %) more speed and 94 kW (8.4 %) less shaft power. It runs at −168 rpm, spin ratio 3.00, with 48.8 kN ahead and 43.3 kN to starboard, and draws 33.3 kW. For the brochure condition the table gives 57.2 kN at k = 3, against the brochure's more than 35.8 kN.

Propulsion.SyntheticDieselEngineA and SyntheticDieselEngineB are parameter presets of the one SimpleDieselEngine: a wrapper without equations holds the engine as core and loads assets/presets/Synthetic/diesel_engine_{a,b}.toml with an apply clause, which is the path Dyad 3.4 supports for a table whose length differs from the default (six and three knots here; the file sets the structural n_sfoc together with the arrays). Both files are synthetic: round numbers invented to exercise the mechanism, not measurements, manufacturer data or a calibration, as their *.provenance.toml sidecars record. scripts/validate_engine_presets.jl solves both and checks the metered fuel against the files; test/invalid_engine_presets holds files that must be refused and shows where each kind is caught (compiler diagnostic with exit status 0, construction, or the engine's assertions). A table whose length disagrees with n_sfoc is refused when the engine is constructed.

The FlettnerRotor component reads Cl(ξ), Cd(ξ) from assets/flettner_coeffs.csv, produced offline by scripts/run_waterlily_flettner.jl from WaterLily.jl simulations of a rotating cylinder in cross-flow (G. D. Weymouth's SpinCyl pattern). Three rendered transits compare diesel-only, rotor with bow-quarter wind and rotor with beam wind:

Analysis	Rotor	Mean wind from	Time to target
ShipRenderTransient	none	NE (45°)	not reached by 2200 s
ShipFlettnerRenderTransient	yes	NE (45°), bow quarter	not reached by 1500 s
ShipFlettnerFavorableRenderTransient	yes	N (0°), beam	reaches at t ≈ 1200 s

FlettnerRotorOnline and scripts/run_flettner_cosim_verification.jl run the same transit with WaterLily stepped live in a PeriodicCallback (package extension FlettnerCFDLiveExt, GPU-capable through CUDA) to verify the table approach; assets/flettner_cosim_* hold the comparison plots and animations. Table and live CFD agree on shape, sign and trajectory, with live magnitudes 20–30 % lower during the ramp-up.

Getting started

Dyad models live in dyad/; the Dyad compiler emits Julia into generated/ (never edit those files). The wrappers ../julia-dyad.sh and ../dyad.sh select the dyad-3.4.0 JuliaUp channel and dyad-cli@3.4.0; run heavy commands through ~/dyad-fleet/heavy on this machine.

# Compile Dyad -> Julia
../dyad.sh compile

# Run an analysis from Julia
../julia-dyad.sh -e 'using DyadShip; res = DyadShip.Ship6DOF.TurningCircleTransient(); println(res.sol.retcode)'

# Manoeuvring validation report + figures
../julia-dyad.sh scripts/validate_6dof.jl

# Convection factors, external wall, ship compartment and the weather boundary
../julia-dyad.sh scripts/validate_heattransfer.jl

# Electrical load analysis and rainflow counting
../julia-dyad.sh scripts/validate_machinery.jl

# Planar transit animations
../julia-dyad.sh scripts/render_all.jl

# Re-characterise the Flettner rotor with WaterLily (scripts/Project.toml)
../julia-dyad.sh --project=scripts scripts/run_waterlily_flettner.jl

Two dependencies are not open source. HVACComponents (moist air, used by dyad/MoistAir) and IncompressibleFlowComponents (tanks, pumps and valves, used by Ship6DOF.AntiHeelingCircuit) are © JuliaHub, all rights reserved, and are provided under the JuliaHub end user license agreement (https://juliahub.com/company/eula) from the private DyadHVACRegistry and DyadThermoFluidRegistry registries; see PORTING_NOTES.md for how they are installed. They are not redistributed here, and using the models that depend on them requires access to those registries under that agreement.

Accessing results follows the Dyad convention:

using DyadShip
using DyadInterface: symbolic_container
res = DyadShip.Ship6DOF.ZigZagTransient()
m = symbolic_container(res)
heading_deg = rad2deg.(res.sol[m.ship.Yaw])

Layout

• dyad/Ship6DOF/ — 6-DOF ship stack, analyses, definitions.jl (Wageningen polynomials, four-quadrant Fourier sets, draft polynomials).
• dyad/Ship/, dyad/Propulsion/ — planar stack, Flettner rotor, transits.
• dyad/Machinery/ — on-off consumer, the seeded clocked RandomStart scheduler and the ElectricalLoad bank that make up a ship's electrical power load analysis, plus the continuous peak sampler and the event-driven EventPeakSampler built on DiscreteComponents clocks.
• dyad/Thermal/ — solar irradiation, sun screen, plate and cylinder transients, temperature dataset, air exchanger, the four convection factors (horizontal cylinder, forced flat plate, internal and external wall surfaces) on ThermalComponents.Interfaces.ConvectiveElement1D, and ConvRadSunWall, an external wall composing those with two view-factor-split ThermalComponents.BodyRadiation paths, IrradiationOnPlane and SunScreen. dyad/Thermal/ShipCompartment.dyad is a moist-air compartment behind weather-exposed bulkheads whose film coefficients are those convection factors rather than fixed U values, so its heat loss follows the ship's apparent wind.
• dyad/MoistAir/ — SourceMoistAir and DewTemperature on the HVACComponents moist-air medium (MoistAirFluidPort).
• dyad/Environment.dyad, VariableEnvironment.dyad, ApparentSpeedXY.dyad — signal-level environment helpers.
• assets/ — wing-profile and Flettner coefficient tables, temperature CSV, validation figures, animations.
• scripts/ — validation, rendering and WaterLily characterisation scripts (scripts/Project.toml carries the WaterLily/CUDA dependencies).
• src/DyadShip.jl, src/Rainflow.jl, ext/FlettnerCFDLiveExt.jl — Julia module wrapper, rainflow cycle counting and Miner damage over the turning points EventPeakSampler emits, and the live-CFD extension.
• PORTING_NOTES.md — port status, conventions, corrections relative to upstream.
• AGENTS.md — toolchain notes and Dyad/MTK learnings for agents.

License

The Dyad rewrite in this repository is © 2025 JuliaHub and contributors, Panagiotis Georgakopoulos. The upstream Modelica ShipSIM library is © Basilio Puente and M Dolores Fernandez, distributed under the 3-clause BSD license.

The HVACComponents and IncompressibleFlowComponents libraries this repository depends on are © JuliaHub, all rights reserved, and are subject to the JuliaHub end user license agreement rather than the licenses above; the MoistAir module and the AntiHeelingCircuit models are unusable without them. The Dyad toolchain itself is provided by JuliaHub for educational and personal use, with commercial use requiring a license.