@jjlmoya/utils-nautical 1.22.0 → 1.24.0

package/src/tool/hullSpeed/logic.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import {
+  bandFromRatio,
+  clampLwlMetres,
+  clampObservedKnots,
+  computeHullSpeed,
+  displayLength,
+  feetToMetres,
+  froudeNumber,
+  HULL_SPEED_FACTOR,
+  hullSpeedKnotsFromLwl,
+  knotsToKmh,
+  knotsToMph,
+  LWL_MAX_M,
+  LWL_MIN_M,
+  metresToFeet,
+  speedLengthRatio,
+  storeLength,
+} from './logic';
+
+describe('hull speed geometry', () => {
+  it('converts metres and feet without drift on a round trip', () => {
+    const metres = 10;
+    expect(feetToMetres(metresToFeet(metres))).toBeCloseTo(metres, 10);
+  });
+
+  it('uses 1.34 times sqrt of waterline in feet', () => {
+    const lwlM = 10;
+    const expected = HULL_SPEED_FACTOR * Math.sqrt(metresToFeet(lwlM));
+    expect(hullSpeedKnotsFromLwl(lwlM)).toBeCloseTo(expected, 8);
+    expect(hullSpeedKnotsFromLwl(lwlM)).toBeCloseTo(7.676, 2);
+  });
+
+  it('keeps speed-length ratio equal to the factor at hull speed', () => {
+    const lwlM = 12;
+    const hs = hullSpeedKnotsFromLwl(lwlM);
+    expect(speedLengthRatio(hs, lwlM)).toBeCloseTo(HULL_SPEED_FACTOR, 8);
+  });
+
+  it('returns a Froude number near 0.40 at hull speed', () => {
+    const lwlM = 10;
+    const hs = hullSpeedKnotsFromLwl(lwlM);
+    expect(froudeNumber(hs, lwlM)).toBeGreaterThan(0.39);
+    expect(froudeNumber(hs, lwlM)).toBeLessThan(0.41);
+  });
+});
+
+describe('units and clamps', () => {
+  it('displays feet in imperial and metres in metric', () => {
+    expect(displayLength(10, 'metric')).toBe(10);
+    expect(displayLength(10, 'imperial')).toBeCloseTo(metresToFeet(10), 8);
+    expect(storeLength(32.80839895013123, 'imperial')).toBeCloseTo(10, 6);
+    expect(storeLength(10, 'metric')).toBe(10);
+  });
+
+  it('clamps waterline and observed speed', () => {
+    expect(clampLwlMetres(Number.NaN)).toBe(LWL_MIN_M);
+    expect(clampLwlMetres(0)).toBe(LWL_MIN_M);
+    expect(clampLwlMetres(99)).toBe(LWL_MAX_M);
+    expect(clampObservedKnots(-4)).toBe(0);
+    expect(clampObservedKnots(Number.NaN)).toBe(0);
+    expect(clampObservedKnots(80)).toBe(40);
+  });
+
+  it('converts knots to km/h and mph', () => {
+    expect(knotsToKmh(10)).toBeCloseTo(18.52, 6);
+    expect(knotsToMph(10)).toBeCloseTo(11.5078, 3);
+  });
+});
+
+describe('bands', () => {
+  it('marks below, near, at and above the wave barrier', () => {
+    expect(bandFromRatio(0.9)).toBe('below');
+    expect(bandFromRatio(1.2)).toBe('near');
+    expect(bandFromRatio(1.34)).toBe('at');
+    expect(bandFromRatio(1.8)).toBe('above');
+  });
+});
+
+describe('computeHullSpeed', () => {
+  it('uses hull speed as the compared speed when observed is zero', () => {
+    const result = computeHullSpeed({
+      lwlMetres: 10,
+      hullKind: 'displacement',
+      observedKnots: 0,
+    });
+    expect(result.band).toBe('at');
+    expect(result.hullSpeedKnots).toBeCloseTo(7.676, 2);
+    expect(result.observedKnots).toBe(0);
+  });
+
+  it('classifies an observed speed above hull speed', () => {
+    const result = computeHullSpeed({
+      lwlMetres: 10,
+      hullKind: 'planing',
+      observedKnots: 18,
+    });
+    expect(result.band).toBe('above');
+    expect(result.speedLengthRatio).toBeGreaterThan(HULL_SPEED_FACTOR);
+  });
+
+  it('treats a ratio within 0.02 of 1.34 as at hull speed', () => {
+    expect(bandFromRatio(1.33)).toBe('at');
+  });
+});

package/src/tool/hullSpeed/logic.ts

@@ -0,0 +1,116 @@
+export type UnitSystem = 'metric' | 'imperial';
+export type HullKind = 'displacement' | 'semi' | 'planing';
+export type SpeedBand = 'below' | 'near' | 'at' | 'above';
+
+export interface HullSpeedInput {
+  lwlMetres: number;
+  hullKind: HullKind;
+  observedKnots: number;
+}
+
+export interface HullSpeedResult {
+  lwlMetres: number;
+  lwlFeet: number;
+  hullKind: HullKind;
+  hullSpeedKnots: number;
+  hullSpeedKmh: number;
+  hullSpeedMph: number;
+  speedLengthRatio: number;
+  froudeNumber: number;
+  band: SpeedBand;
+  observedKnots: number;
+}
+
+export const METRES_PER_FOOT = 0.3048;
+export const HULL_SPEED_FACTOR = 1.34;
+export const GRAVITY_MS2 = 9.80665;
+export const METRES_PER_NAUTICAL_MILE = 1852;
+export const LWL_MIN_M = 2.5;
+export const LWL_MAX_M = 40;
+export const OBSERVED_MAX_KN = 40;
+export const NEAR_RATIO = 1.1;
+
+export function metresToFeet(metres: number): number {
+  return metres / METRES_PER_FOOT;
+}
+
+export function feetToMetres(feet: number): number {
+  return feet * METRES_PER_FOOT;
+}
+
+export function knotsToMetresPerSecond(knots: number): number {
+  return (knots * METRES_PER_NAUTICAL_MILE) / 3600;
+}
+
+export function knotsToKmh(knots: number): number {
+  return knots * 1.852;
+}
+
+export function knotsToMph(knots: number): number {
+  return knotsToKmh(knots) / 1.609344;
+}
+
+export function clampLwlMetres(metres: number): number {
+  if (Number.isNaN(metres)) return LWL_MIN_M;
+  return Math.min(LWL_MAX_M, Math.max(LWL_MIN_M, metres));
+}
+
+export function clampObservedKnots(knots: number): number {
+  if (Number.isNaN(knots) || knots < 0) return 0;
+  return Math.min(OBSERVED_MAX_KN, knots);
+}
+
+export function displayLength(metres: number, unit: UnitSystem): number {
+  if (unit === 'imperial') return metresToFeet(metres);
+  return metres;
+}
+
+export function storeLength(displayed: number, unit: UnitSystem): number {
+  if (unit === 'imperial') return feetToMetres(displayed);
+  return displayed;
+}
+
+export function hullSpeedKnotsFromLwl(lwlMetres: number): number {
+  const feet = metresToFeet(clampLwlMetres(lwlMetres));
+  return HULL_SPEED_FACTOR * Math.sqrt(feet);
+}
+
+export function speedLengthRatio(speedKnots: number, lwlMetres: number): number {
+  const feet = metresToFeet(clampLwlMetres(lwlMetres));
+  const root = Math.sqrt(feet);
+  if (root === 0) return 0;
+  return speedKnots / root;
+}
+
+export function froudeNumber(speedKnots: number, lwlMetres: number): number {
+  const length = clampLwlMetres(lwlMetres);
+  const denom = Math.sqrt(GRAVITY_MS2 * length);
+  if (denom === 0) return 0;
+  return knotsToMetresPerSecond(speedKnots) / denom;
+}
+
+export function bandFromRatio(ratio: number): SpeedBand {
+  if (Math.abs(ratio - HULL_SPEED_FACTOR) < 0.02) return 'at';
+  if (ratio < NEAR_RATIO) return 'below';
+  if (ratio < HULL_SPEED_FACTOR) return 'near';
+  return 'above';
+}
+
+export function computeHullSpeed(input: HullSpeedInput): HullSpeedResult {
+  const lwlMetres = clampLwlMetres(input.lwlMetres);
+  const observedKnots = clampObservedKnots(input.observedKnots);
+  const hullSpeedKnots = hullSpeedKnotsFromLwl(lwlMetres);
+  const compareKnots = observedKnots > 0 ? observedKnots : hullSpeedKnots;
+  return {
+    lwlMetres,
+    lwlFeet: metresToFeet(lwlMetres),
+    hullKind: input.hullKind,
+    hullSpeedKnots,
+    hullSpeedKmh: knotsToKmh(hullSpeedKnots),
+    hullSpeedMph: knotsToMph(hullSpeedKnots),
+    speedLengthRatio: speedLengthRatio(compareKnots, lwlMetres),
+    froudeNumber: froudeNumber(compareKnots, lwlMetres),
+    band: bandFromRatio(speedLengthRatio(compareKnots, lwlMetres)),
+    observedKnots,
+  };
+}

package/src/tool/hullSpeed/presets.ts

@@ -0,0 +1,17 @@
+export interface BoatPreset {
+  id: string;
+  lwlMetres: number;
+}
+
+export const BOAT_PRESETS: BoatPreset[] = [
+  { id: 'dinghy', lwlMetres: 4.2 },
+  { id: 'daysailer', lwlMetres: 6.5 },
+  { id: 'cruiser', lwlMetres: 10 },
+  { id: 'bluewater', lwlMetres: 13.5 },
+  { id: 'workboat', lwlMetres: 18 },
+];
+
+export function presetIdForLwl(lwlMetres: number): string | null {
+  const found = BOAT_PRESETS.find((item) => Math.abs(item.lwlMetres - lwlMetres) < 0.05);
+  return found ? found.id : null;
+}