WindMar Technical Documentation

Weather-aware maritime route optimization for MR product tankers

What is WindMar?

WindMar is an end-to-end maritime route optimization platform designed for Medium Range (MR) product tankers. It models the complete chain of vessel performance physics — from calm water resistance through wind and wave added resistance, engine SFOC curves, and propulsion efficiency — to predict fuel consumption under real weather conditions. The A* pathfinding algorithm then searches for the route that minimizes total fuel consumption while respecting safety constraints and regulatory zones. All calculations are grounded in established naval architecture methods: Holtrop-Mennen for hull resistance, Blendermann for wind loads, Kwon for wave added resistance, and simplified strip theory for seakeeping motions.

The system ingests near-real-time wind data from NOAA GFS (0.25° resolution, via NOMADS), wave and current data from Copernicus Marine Service (CMEMS), with ERA5 reanalysis as a secondary wind fallback. A 5-day forecast timeline (f000–f120, 3-hourly steps) enables animated wind visualization. The system evaluates vessel motions (roll, pitch, vertical acceleration) and enforces safety criteria that block or penalize dangerous sea states. Finally, it calculates the IMO Carbon Intensity Indicator (CII) rating for the completed voyage, enabling operators to assess regulatory compliance before departure.

Architecture

Component Overview

WindMar follows a layered architecture with a clear separation between the user-facing frontend, the API backend, the physics-based optimization engine, and external data providers. Each component runs as an independent service orchestrated via Docker Compose.

Data Flow

1. Route Definition — User defines departure, arrival, and waypoints on the map interface. Vessel condition (laden/ballast) and speed preferences are selected.
2. Weather Fetch — Backend requests weather data from Copernicus for the route corridor. Wind, wave, and current fields are interpolated to the optimization grid.
3. Performance Calculation — For each grid cell, the optimization engine computes total resistance (calm water + wind + waves), brake power, SFOC, and fuel consumption at candidate speeds.
4. A* Pathfinding — The A* algorithm searches the grid using fuel consumption as the edge cost. Safety constraints block or penalize dangerous cells. Regulatory zones modify costs.
5. Speed Optimization — Each leg of the optimal path is individually speed-optimized to minimize fuel per nautical mile given local weather conditions.
6. Results — The optimized route, fuel estimate, ETA, leg-by-leg breakdown, seakeeping assessment, and CII rating are returned to the frontend for display.

Docker Services

services:
  db:
    image: postgres:16-alpine
    ports: ["${DB_PORT:-5432}:5432"]

  redis:
    image: redis:7-alpine
    ports: ["${REDIS_PORT:-6379}:6379"]

  api:
    build: .
    ports: ["${API_PORT:-8000}:8000"]
    depends_on: [db, redis]

  frontend:
    build: ./frontend
    ports: ["${FRONTEND_PORT:-3000}:3000"]
    depends_on: [api]

All ports and credentials are configured via environment variables in .env (see .env.example for defaults). Copy and customize before starting.

Installation

Prerequisites

• Python 3.10 or later
• Node.js 18 or later
• Docker & Docker Compose

Docker Compose (Recommended)

git clone https://github.com/SL-Mar/windmar.git
cd windmar
cp .env.example .env    # Edit with your settings
docker compose up -d --build

This starts all four services (PostgreSQL, Redis, API, frontend). By default the frontend is accessible at http://localhost:3000 and the backend API at http://localhost:8000. Ports are configurable via .env.

Manual Setup

Backend

pip install -r requirements.txt
python api/main.py

Frontend

cd frontend
npm install --legacy-peer-deps
npm run dev

Weather Data Sources

WindMar uses a three-tier provider chain that automatically falls back when a source is unavailable. See Weather Data Acquisition for full technical details.

Obtaining Weather Credentials

CMEMS (waves and currents): Register at marine.copernicus.eu, then set in .env:

COPERNICUSMARINE_SERVICE_USERNAME=your_username
COPERNICUSMARINE_SERVICE_PASSWORD=your_password

CDS ERA5 (wind fallback): Register at cds.climate.copernicus.eu, copy your Personal Access Token from your profile, then set:

CDSAPI_KEY=your_personal_access_token

Environment Variables

Copy .env.example to .env and configure. Key variables:

DATABASE_URL=postgresql://windmar:password@db:5432/windmar
REDIS_URL=redis://:password@redis:6379/0
API_SECRET_KEY=generate_with_openssl_rand_hex_32
COPERNICUSMARINE_SERVICE_USERNAME=your_username
COPERNICUSMARINE_SERVICE_PASSWORD=your_password
CDSAPI_KEY=your_cds_personal_access_token

Tech Stack

Backend

Frontend

Scientific Computing

Database & Cache

External APIs

Calm Water Resistance

Calm water resistance is the foundation of all fuel consumption predictions. WindMar implements the Holtrop-Mennen method, the industry-standard empirical approach for estimating hull resistance of displacement vessels. The method decomposes total resistance into frictional, wave-making, and appendage components, each derived from the vessel's principal dimensions and hull form coefficients.

Holtrop-Mennen Method

A) Frictional Resistance (R_f)

Frictional resistance arises from the viscous shear stress between the hull surface and the surrounding water. It dominates at service speeds typical of MR tankers (Froude number 0.12-0.18). The ITTC 1957 model-ship correlation line provides the friction coefficient, and the Holtrop form factor accounts for the three-dimensional shape of the hull.

At service speed of 14.5 knots (7.46 m/s) with L_pp = 176 m, the Reynolds number is approximately 1.1 × 10⁹, placing the flow firmly in the turbulent regime. The friction coefficient C_f is then approximately 0.00145.

Form Factor (1 + k_1)

The form factor corrects the flat-plate friction coefficient for the three-dimensional hull shape. Holtrop-Mennen provides a regression formula for tanker hull forms based on the principal dimension ratios and block coefficient.

B) Wave-Making Resistance (R_w)

Wave-making resistance is generated by the pressure field around the hull that creates surface waves. For MR tankers operating at low Froude numbers (Fr < 0.2), wave-making resistance is a small fraction of total resistance. However, it increases exponentially with speed, making it the dominant factor limiting maximum speed.

At the design speed of 14.5 knots, the Froude number for an MR tanker is approximately Fr = 7.46 / sqrt(9.81 × 176) ≈ 0.179. The exponential term exp(-0.4 × 0.179^-2) is very small, confirming that wave-making resistance contributes less than 5% of total resistance at service speed.

C) Appendage Resistance (R_app)

Appendage resistance accounts for the drag of the rudder, propeller shaft brackets, bilge keels, and other hull appendages. For MR tankers with standard appendage configurations, this is estimated as a fixed percentage of frictional resistance.

Default MR Tanker Specifications

Wind Resistance

Wind resistance is computed using the Blendermann method, which models the aerodynamic forces on the vessel's above-water structure as a function of relative wind speed, direction, and the vessel's projected areas. The method accounts for both longitudinal (drag) and transverse (side force) components, with the longitudinal component directly opposing forward motion and the transverse component contributing indirectly through induced drift.

Blendermann Method

Wind Projection Areas

Physical Interpretation by Wind Angle

• Head wind (0°) — Maximum longitudinal resistance. C_x reaches its peak value. This is the worst-case scenario for fuel consumption.
• Beam wind (90°) — Minimal longitudinal component but maximum transverse force. The 10% coupling factor from F_y captures the drift-induced resistance.
• Following wind (180°) — Minimal resistance. The wind partially assists forward motion. C_x is near zero or slightly negative (assisting).

Wave Resistance

Wave added resistance is the increase in hull resistance caused by the vessel's interaction with ocean waves. WindMar uses the Kwon empirical formula, which estimates added resistance as a function of significant wave height, beam, Froude number, and the encounter angle between the vessel heading and the dominant wave direction.

Kwon Empirical Formula

The Kwon formula produces a quadratic dependence on wave height: doubling H_s from 2 m to 4 m increases wave added resistance by a factor of four. The directional factor ensures that head seas produce maximum added resistance while following seas produce none, which matches the physical expectation that waves opposing the vessel's motion cause the greatest speed loss.

For a laden MR tanker in head seas with H_s = 3 m at service speed (Fr ≈ 0.179), the wave added resistance is approximately:

SFOC Curve

Specific Fuel Oil Consumption (SFOC) describes the mass of fuel consumed per unit of energy delivered by the engine. It varies with engine load: marine diesel engines have an optimal efficiency zone around 75% of Maximum Continuous Rating (MCR), with increasing specific consumption at both lower and higher loads. WindMar models this behavior with a piecewise linear correction applied to the MCR reference SFOC.

The asymmetric correction reflects the physical reality of diesel engine combustion: at low loads, incomplete combustion and thermal losses increase specific consumption more steeply (15% penalty per 0.1 load fraction below 75%) than the mild increase at high loads (5% penalty per 0.1 above 75%) caused by increased cylinder pressures and thermal stress.

SFOC Behavior by Engine Load

The engine load is clamped to the range [0.15, 1.0]. Below 15% load, the engine is considered non-operational. Above 100% MCR, the engine cannot deliver more power, so the brake power is capped at P_MCR = 8,840 kW.

Propulsion Chain

The propulsion chain converts total hull resistance into brake power demand and then into fuel consumption. It accounts for the efficiencies of the propeller, the hull-propeller interaction, and the relative rotative efficiency of the propulsion system.

Brake Power Calculation

Hull efficiency exceeds 1.0 because the wake behind the hull reduces the effective inflow velocity to the propeller relative to the ship speed. The propeller operates in a flow field that is slower than the free-stream velocity, requiring less thrust to overcome the same resistance.

Fuel Consumption

For example, at service speed in calm water with P_brake = 5,500 kW and SFOC = 172 g/kWh, a 24-hour transit consumes approximately:

Fuel = (5500 × 172 × 24) / 1,000,000 = 22.7 MT/day

Ship Motions

Ship motion prediction is essential for seakeeping assessment and safety enforcement during route optimization. WindMar implements simplified strip-theory models for roll, pitch, and vertical acceleration. These models provide physically meaningful motion estimates that capture the dominant effects of wave height, encounter frequency, and vessel loading condition.

Roll Motion — Single DOF Oscillator

Roll is modeled as a single degree-of-freedom oscillator driven by the transverse wave slope. The response amplitude operator (RAO) captures the frequency-dependent magnification, with resonance occurring when the encounter frequency matches the vessel's natural roll frequency.

The natural roll period is longer in laden condition (14 s) due to the higher metacentric height combined with greater mass moment of inertia. Ballast condition has a shorter period (10 s) because the higher GM (4.0 m) produces a stiffer restoring moment relative to the reduced inertia. The 5% critical damping ratio is conservative and accounts for hull friction, bilge keel effects, and cargo damping.

Pitch Motion

Pitch is driven primarily by head seas and bow-quarter seas. The amplitude depends on the wave slope, the encounter angle (maximum in head seas), and a pitch factor that captures the wavelength-to-ship-length tuning effect.

The pitch factor peaks near L/λ = 1 (ship length equals wavelength), where the vessel "straddles" consecutive wave crests and troughs, producing maximum pitching motion. When the wavelength is much shorter or longer than the ship, the pitch factor decreases because the vessel either averages out multiple short waves or rides on a single long wave slope.

Vertical Acceleration

Vertical acceleration at specific locations along the ship length combines the heave acceleration at the center of gravity with the pitch-induced acceleration component. Points far from midship (bridge, bow) experience amplified accelerations due to the pitch lever arm.

The bow experiences the highest vertical accelerations because it is the farthest point forward from the pitch axis. At the bridge (70 m aft of midship), accelerations are also amplified but less than at the bow. Vertical acceleration is the primary crew comfort criterion and drives speed reduction decisions in heavy weather.

Safety Criteria

WindMar enforces a three-tier safety classification (Safe, Marginal, Dangerous) based on vessel motion amplitudes and derived seakeeping parameters. These criteria are applied during route optimization to block unsafe routes and penalize marginally safe routes.

Safety Limits

The overall safety classification for a cell is determined by the worst-case criterion: if any single parameter falls in the Dangerous range, the cell is classified as Dangerous regardless of the other parameters.

Slamming & Parametric Roll

Slamming (Ochi Criteria)

Slamming occurs when the bow emerges from the water and re-enters with high velocity, generating impulsive loads on the hull structure. The Ochi criteria estimate the probability of slamming based on bow emergence and re-entry velocity. Slamming risk is highest in ballast condition (lower forward draft) and head seas.

Despite the higher freeboard in ballast, the reduced forward draft means the keel rises above the still water surface more frequently, particularly in head seas. The combination of high emergence amplitude and significant re-entry velocity produces the impulsive slamming loads that can cause structural damage to the forward hull plating.

Parametric Roll Risk

Parametric rolling is a dangerous phenomenon where roll amplitudes build up rapidly due to periodic variation in the vessel's waterplane area (and thus stability) as waves pass along the hull. It occurs primarily in head or following seas when the wave encounter period is approximately twice the natural roll period.

Parametric roll can develop in just a few wave cycles, reaching amplitudes of 30–40 degrees or more. It is particularly dangerous because it can occur in moderate sea states where other motion criteria appear safe. Detection and avoidance through route optimization is a key safety feature.

A* Algorithm

Route optimization uses the A* pathfinding algorithm to find the minimum-cost path through a weather-dependent grid. Each grid cell has a traversal cost determined by the fuel consumption required to cross it at the locally optimal speed, considering all resistance components and safety constraints.

Grid Construction

• Resolution: Configurable, default 0.5 degrees (~30 nm at the equator)
• Land masking: Land cells are removed using the global-land-mask library, which provides a 1-km resolution land/ocean classification
• Corridor: The search grid extends ±5 degrees latitude and longitude around the direct great-circle route to limit search space while allowing sufficient deviation for weather routing
• Connectivity: 8-connected grid (cardinal + diagonal neighbors)

A* Search

Search Procedure

1. Initialize priority queue (min-heap ordered by f-score) with start node
2. Pop node with lowest f-score
3. If goal reached, reconstruct path and return
4. For each of 8 neighbors:
   • Skip if land cell or already visited with lower cost
   • Compute weather at neighbor location (interpolated from grid)
   • Compute fuel cost to traverse cell at optimal speed
   • Apply safety and regulatory zone multipliers
   • Update neighbor's g-score if new path is cheaper
   • Add to priority queue
5. Terminate if cells explored exceeds 50,000 (safety limit)

Cost Calculation Code

def compute_cell_cost(self, from_cell, to_cell, weather):
    """Compute fuel cost to traverse a grid cell."""
    distance_nm = haversine(from_cell.lat, from_cell.lon,
                            to_cell.lat, to_cell.lon)

    # Find optimal speed for this cell
    best_fuel = float('inf')
    best_speed = self.vessel.service_speed

    for speed_kts in np.linspace(6.0, 18.0, 7):
        speed_ms = speed_kts * 0.5144

        # Total resistance
        r_calm = self.vessel.calm_water_resistance(speed_ms)
        r_wind = self.vessel.wind_resistance(
            speed_ms, weather.wind_speed, weather.wind_dir,
            self.heading)
        r_wave = self.vessel.wave_resistance(
            speed_ms, weather.wave_height, weather.wave_dir,
            self.heading)
        r_total = r_calm + r_wind + r_wave

        # Brake power and fuel
        p_tow = r_total * speed_ms / 1000
        p_brake = min(p_tow / self.vessel.eta_total,
                      self.vessel.mcr)
        sfoc = self.vessel.sfoc(p_brake / self.vessel.mcr)
        time_h = distance_nm / speed_kts
        fuel_mt = p_brake * sfoc * time_h / 1e6

        if fuel_mt < best_fuel:
            best_fuel = fuel_mt
            best_speed = speed_kts

    # Apply safety multiplier
    safety = self.assess_safety(weather, best_speed)
    if safety == 'dangerous':
        return float('inf')
    elif safety == 'marginal':
        best_fuel *= 1.5

    return best_fuel

Path Smoothing

After A* finds the optimal grid path, a smoothing pass removes unnecessary waypoints to produce a more natural route. The algorithm iteratively removes intermediate waypoints and checks:

• The straight-line segment does not cross land
• The fuel consumption difference is within 1% of the unsmoothed path
• All intermediate points maintain safe seakeeping conditions

Variable Speed Optimization

Rather than maintaining a constant speed throughout the voyage, WindMar optimizes speed independently for each leg of the route. This allows the vessel to slow down in adverse weather (reducing resistance cubically) and speed up in calm conditions, minimizing total fuel consumption for the voyage.

Per-Leg Speed Optimization

• Speed range: 6 to 18 knots, tested at 7 discrete values (6, 8, 10, 12, 14, 16, 18 kts)
• Objective: Minimize fuel consumption per nautical mile for each leg
• Weather-dependent: The optimal speed varies with local wind, wave, and current conditions
• Power constraint: Speed is limited by MCR — if the required brake power exceeds MCR at a given speed, that speed is not achievable

The cubic relationship between speed and resistance means that a small speed reduction produces a large fuel saving. For example, reducing speed from 14 to 12 knots (14% reduction) can reduce fuel consumption by approximately 35% per hour, although the voyage takes longer. The optimizer balances this trade-off based on the fuel-per-mile metric.

Safety Constraints

Safety constraints are integrated directly into the A* search, ensuring that the optimizer never produces a route that violates safety criteria or regulatory requirements. Constraints are applied at two levels: seakeeping safety and regulatory zone enforcement.

Seakeeping Constraints in A* Search

• Dangerous conditions: Cell cost = infinity. The A* algorithm will not expand through this cell, forcing the route around the hazardous area. This applies when any motion parameter exceeds the Dangerous threshold.
• Marginal conditions: Cell cost × 1.5. The optimizer can still route through the cell, but at a 50% cost penalty. This encourages deviation when alternative routes are available but permits marginal conditions when no safe alternative exists.
• Safe conditions: Nominal fuel-based cost with no penalty.

Regulatory Zone Enforcement

Regulatory zones modify the A* cost function based on the zone type. Three enforcement modes are supported:

Exclusion zones and penalty zones are applied per-cell during the A* expansion. Mandatory zones are enforced as waypoint constraints: the route must pass through at least one cell in each mandatory zone.

IMO CII Rating

The Carbon Intensity Indicator (CII) is a mandatory IMO measure under MEPC.339(76) that rates a ship's operational carbon efficiency on an A-to-E scale. WindMar calculates the attained CII for a voyage and compares it against the required CII to determine the rating. This enables operators to assess whether a planned voyage will contribute positively or negatively to their annual CII rating.

Attained CII

Required CII

Rating Boundaries

Annual Reduction Factors

CO2 Emission Factors

Regulatory Zones

WindMar supports the definition and enforcement of regulatory zones that constrain route optimization. Zones are defined as GeoJSON polygons and classified by type, each with a specific effect on the A* cost function.

Zone Types

GeoJSON Import/Export

Zones are stored as GeoJSON Feature Collections. Each feature includes a properties object specifying the zone type, name, and any associated parameters (e.g., penalty factor).

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "North Sea ECA",
        "zone_type": "PENALTY",
        "penalty_factor": 1.3
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[...], [...], ...]]
      }
    }
  ]
}

Point-in-Polygon Detection

During A* expansion, each candidate cell is tested against all active regulatory zones using the ray casting algorithm. For a point (lat, lon), the algorithm casts a horizontal ray and counts the number of intersections with the polygon boundary. An odd count means the point is inside the polygon; an even count means outside.

Weather API

The Weather API provides access to weather fields for the route optimization grid and map visualization. Wind data is sourced from NOAA GFS (primary) with ERA5 fallback. Wave and current data comes from Copernicus CMEMS. Weather fields are cached in-memory for repeated queries. See Weather Data Acquisition for full details.

Grid Endpoints

Forecast Endpoints

Route API

The Route API handles route optimization requests, waypoint-based route calculation, RTZ file parsing, and voyage planning with ETA computation.

{
  "departure": {
    "lat": 51.95,
    "lon": 1.33,
    "name": "Rotterdam"
  },
  "arrival": {
    "lat": 29.75,
    "lon": -93.85,
    "name": "Houston"
  },
  "departure_time": "2026-02-10T08:00:00Z",
  "vessel_condition": "laden",
  "optimization_objective": "fuel",
  "grid_resolution": 0.5,
  "speed_range": [6.0, 18.0],
  "enable_safety_constraints": true,
  "regulatory_zones": ["eca_north_sea", "tss_dover"]
}

{
  "route": {
    "waypoints": [
      {"lat": 51.95, "lon": 1.33, "speed_kts": 14.0, "fuel_mt": 0.0},
      {"lat": 50.50, "lon": -2.10, "speed_kts": 13.5, "fuel_mt": 12.4},
      ...
    ],
    "total_distance_nm": 5120,
    "total_fuel_mt": 285.3,
    "total_time_hours": 372.5,
    "eta": "2026-02-25T20:30:00Z"
  },
  "cii": {
    "attained": 4.82,
    "required": 5.31,
    "rating": "B"
  },
  "safety_summary": {
    "max_roll_deg": 12.3,
    "max_pitch_deg": 4.1,
    "max_acceleration_g": 0.18,
    "dangerous_cells_avoided": 14,
    "marginal_cells_traversed": 7
  },
  "legs": [
    {
      "from": {"lat": 51.95, "lon": 1.33},
      "to": {"lat": 50.50, "lon": -2.10},
      "distance_nm": 156,
      "speed_kts": 13.5,
      "fuel_mt": 12.4,
      "time_hours": 11.6,
      "weather": {
        "wind_speed_ms": 8.2,
        "wind_dir": 245,
        "wave_height_m": 2.1,
        "wave_dir": 260
      }
    }
  ]
}

{
  "waypoints": [
    {"lat": 51.95, "lon": 1.33},
    {"lat": 48.50, "lon": -5.10},
    {"lat": 29.75, "lon": -93.85}
  ],
  "departure_time": "2026-02-10T08:00:00Z",
  "vessel_condition": "laden",
  "speed_kts": 14.5
}

Vessel API

The Vessel API manages vessel specifications, calibration, and compliance calculations.

{
  "loa": 183.0,
  "lpp": 176.0,
  "beam": 32.0,
  "draft_laden": 11.8,
  "draft_ballast": 6.5,
  "displacement_laden": 65000,
  "displacement_ballast": 20000,
  "dwt": 49000,
  "mcr_kw": 8840,
  "sfoc_mcr": 171,
  "service_speed_laden": 14.5,
  "service_speed_ballast": 15.0
}

{
  "calibration_factors": {
    "calm_water": 1.12,
    "wind": 0.95,
    "waves": 1.08
  },
  "rmse_before": 3.45,
  "rmse_after": 1.23,
  "improvement_pct": 64.3,
  "data_points": 42
}

{
  "total_fuel_mt": 285.3,
  "fuel_type": "VLSFO",
  "distance_nm": 5120,
  "dwt": 49000,
  "year": 2026
}

{
  "attained_cii": 4.82,
  "reference_cii": 5.97,
  "required_cii": 5.31,
  "reduction_factor": 11,
  "rating": "B",
  "boundaries": {
    "A_upper": 4.57,
    "B_upper": 4.99,
    "C_upper": 5.63,
    "D_upper": 6.27
  }
}

Weather Database Architecture

Starting with v0.0.5, WindMar pre-fetches weather grids on a 6-hourly schedule and stores them as compressed blobs in PostgreSQL. This eliminates the 30–60 second CMEMS/GFS download latency during route calculations, reducing optimization time from minutes to seconds.

Database Schema

Two tables manage the weather grid lifecycle:

Compression

Each grid is stored as a zlib-compressed float32 numpy array. A global 0.5° grid (341 × 721 = ~246K points) compresses to ~200–400 KB per parameter per forecast hour. Total storage per ingestion cycle: 7 parameters × 41 hours × ~300 KB ≈ 86 MB.

Provider Fallback Chain

Weather data is resolved through a multi-tier fallback chain. Each tier is tried in order; the first successful response is used:

1. Redis shared cache — cross-worker, 15-minute TTL
2. PostgreSQL pre-ingested grids — latest complete forecast run
3. Live CMEMS/GFS download — direct API call (30–60s)
4. Synthetic data — deterministic test/demo fallback

Ingestion Service

The WeatherIngestionService runs as a FastAPI background task on a 6-hour loop. It downloads global grids from CMEMS (waves, currents) and GFS (wind) and stores them compressed in PostgreSQL. Runs older than 24 hours are automatically marked as superseded.

DbWeatherProvider

The DbWeatherProvider class reads compressed grids from PostgreSQL, decompresses them into numpy arrays, crops to the requested bounding box, and returns WeatherData objects. It selects the best available forecast hour for time-specific queries using nearest-neighbour matching against available forecast hours.

Performance

Monte Carlo Simulation

WindMar includes a parametric Monte Carlo simulator that produces P10/P50/P90 confidence intervals for ETA, fuel consumption, and voyage time. The simulator accounts for weather forecast uncertainty by applying temporally correlated perturbations to base weather conditions along the route.

Architecture

The simulation proceeds in four stages:

1. Route timeline — The voyage is divided into up to 100 evenly-spaced time slices (~1 slice per 1.2 hours). Each slice has a timestamp and interpolated (lat, lon) position along the rhumb-line route.
2. Weather pre-fetch — Base weather (wind, wave, current) is loaded for all slices. Wave data comes from multi-timestep DB grids (forecast hours 0–120h), currents from a single DB snapshot, and wind from the pre-built GridWeatherProvider.
3. Correlated perturbation — For each of N simulations, temporally correlated random factors are generated via Cholesky decomposition of an exponential correlation matrix. These factors perturb wind speed, wave height, current speed, and directions.
4. Voyage calculation — Each simulation runs a full voyage calculation with the perturbed weather provider. Results are collected and percentiles computed.

Perturbation Model

Temporal Correlation

The exponential kernel ensures that weather perturbations at nearby time slices are strongly correlated (a storm at hour 12 implies bad weather at hour 15), while distant slices are nearly independent. The correlation length τ = 0.3 corresponds to ~1.5 days for a 5-day voyage.

Wind–Wave Coupling

Wave height perturbations are 70% correlated with wind perturbations, reflecting the physical relationship between wind forcing and sea state:

API Usage

POST /api/voyage/monte-carlo
{
  "waypoints": [
    {"lat": 51.95, "lon": 4.05, "name": "Rotterdam"},
    {"lat": 37.23, "lon": 15.22, "name": "Augusta"}
  ],
  "calm_speed_kts": 14.5,
  "is_laden": true,
  "departure_time": "2026-02-10T06:00:00Z",
  "n_simulations": 100
}

Response:
{
  "n_simulations": 100,
  "eta_p10": "2026-02-14T13:22:00Z",
  "eta_p50": "2026-02-14T14:55:00Z",
  "eta_p90": "2026-02-14T16:28:00Z",
  "fuel_p10": 285.4,
  "fuel_p50": 302.1,
  "fuel_p90": 321.8,
  "time_p10": 103.4,
  "time_p50": 104.9,
  "time_p90": 106.5,
  "computation_time_ms": 399.2
}

References

• Dickson, T., Farr, H., Sear, D., and Blake, J. (2019). “Uncertainty in marine weather routing.” arXiv:1901.03840
• Aijjou, A.E. et al. (2021). “A Comprehensive Approach to Account for Weather Uncertainties in Ship Route Optimization.” J. Mar. Sci. Eng. 9(12):1434

Model Validation

WindMar includes a comprehensive test suite that validates physical models against expected behaviors, empirical relationships, and boundary conditions. Tests are structured to verify both individual model components and the integrated optimization pipeline.

Unit Tests

The following physical constraints are validated:

• Resistance increases with speed — Total calm water resistance at 16 kts exceeds resistance at 12 kts for both laden and ballast conditions
• Laden uses more fuel than ballast — At the same speed, the laden condition produces higher calm water resistance due to greater displacement and wetted surface
• Weather increases fuel consumption — Total fuel with wind and waves always exceeds calm water fuel for the same speed and distance
• SFOC optimal at 75-85% load — SFOC at 80% load is lower than SFOC at 50% load and lower than SFOC at 100% load
• Head wind worse than following wind — Wind resistance at 0 degrees (head wind) exceeds wind resistance at 180 degrees (following wind)
• A* finds path avoiding land — No waypoint in the optimized path falls on a land cell as classified by global-land-mask
• Safety constraints block dangerous routes — When dangerous conditions exist on the direct path, the optimizer produces a detour that avoids them
• Zone exclusions force detours — An exclusion zone on the direct path forces the optimizer to route around it, increasing total distance

Integration Tests

• Full optimization flow — End-to-end test from route request through weather fetch, A* search, speed optimization, and CII calculation
• API endpoint validation — All REST endpoints return correct HTTP status codes, response schemas, and handle invalid input gracefully
• Weather provider fallback — Synthetic weather provider produces consistent results when Copernicus credentials are not available

Physical Constants

Calibration

Calibration adjusts the physics model parameters to match observed vessel performance from noon report data. This accounts for hull fouling, propeller degradation, and other vessel-specific factors that cause the default model to deviate from actual fuel consumption.

Noon Report Data Format

Calibration accepts an Excel file (.xlsx) with the following columns. Each row represents one noon-to-noon reporting period (approximately 24 hours).

Optimization Method

Calibration uses scipy.optimize.minimize with the Nelder-Mead simplex algorithm to find the calibration factors that minimize the root mean square error (RMSE) between predicted and actual fuel consumption across all noon report entries.

Interpretation of Calibration Factors

• k_calm > 1.0 — Hull roughness or fouling increasing skin friction beyond the clean-hull model prediction
• k_calm < 1.0 — Hull is cleaner than the model assumes (e.g., recent dry-docking)
• k_wind > 1.0 — Above-water structure presents more windage than the default areas suggest
• k_wave > 1.0 — Vessel is more sensitive to waves than the Kwon formula predicts (e.g., bluff bow form)

Factors are bounded to [0.5, 2.0] to prevent physically unreasonable corrections. A factor outside this range indicates either bad input data or a fundamental mismatch between the vessel and the default model parameters, requiring manual review of the vessel specifications.

Technical Articles

The following peer-reviewed-style articles provide in-depth coverage of WindMar's core subsystems. Each article presents the mathematical foundations, implementation details, and relevant references for a specific domain of the weather routing pipeline.