LCS-Mar

Liquid Cargo System Simulator — Technical Reference

Physics-based simulator for liquid cargo operations on oil and chemical tankers. Models inert gas atmosphere, cargo heating, crude oil washing, vapour generation, piping hydraulics, and intact stability in a unified real-time environment.

Designed as a digital twin prototype for cargo operations — the architecture prioritises ingestion of manual observations (sounding logs, gas readings, temperature records) to calibrate the underlying physical engines against real vessel behaviour.

Validation Status

This simulator has not been validated at sea. Physical models are based on first-principles engineering and published correlations. Sea trials and operational data are required before any use in decision support.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    React + TypeScript                    │
│  P&ID Renderer (SVG) │ Stability │ Calibration │ Tanks  │
├─────────────────────────────────────────────────────────┤
│              WebSocket (real-time frames)                │
├─────────────────────────────────────────────────────────┤
│                  FastAPI + Python 3.12                   │
│  Simulation Engine │ Flow Solver │ Calibration Solver    │
├─────────────────────────────────────────────────────────┤
│           Vessel Definition Spec (VDS / JSON)           │
├──────────────┬──────────────┬───────────────────────────┤
│  PostgreSQL  │    Redis     │  Calibration Store (JSON)  │
└──────────────┴──────────────┴───────────────────────────┘

Frontend — React 19, TypeScript, Zustand. SVG-based P&ID renderer driven by vessel definition geometry. Views: Cargo, Ballast, Inert Gas, Tank Cleaning, Bunker/ER, Tanks, Stability, Calibration.

Backend — FastAPI, Python 3.12. Eight physics subsystems run at fixed 0.5 s timesteps, accelerable to 16×. Newton-Raphson flow solver, lumped-parameter thermal model, exponential gas dilution. WebSocket pushes delta-compressed frames to the frontend.

Vessel Definition Spec — JSON schema defining hull geometry, tank calibration tables (ullage → volume → VCG → I_T), piping networks, hydrostatic tables, cross-curve data, P&ID layout coordinates, and alarm thresholds. Vessel-agnostic: any tanker can be modelled by providing a VDS file.

Calibration Loop — Operators log observations (measured vs. predicted) via the UI or Excel upload. A statistical solver computes parameter adjustment suggestions from residual analysis, which the operator reviews and applies.

Installation

# Prerequisites: Docker, Docker Compose
docker compose up -d

# Frontend: http://localhost:3002
# API:      http://localhost:8002
# DB:       localhost:5437 (PostgreSQL 16)

Development

# Backend
cd backend && python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8001

# Frontend
cd frontend && npm install && npm run dev

# Tests
cd backend && pytest                          # 494 tests
cd frontend && npm test                       # 36 tests

Tech Stack

Layer	Technology
Frontend	React 19, TypeScript, Zustand, Recharts, Vite
Backend	Python 3.12, FastAPI, NumPy, SciPy, openpyxl
Infrastructure	PostgreSQL 16, Redis 7, Docker Compose
Testing	pytest (494), vitest (36)

Inert Gas Atmosphere

Models O₂ and HC concentration decay in cargo tank ullage spaces during inerting, purging, and gas-freeing.

Dilution

Exponential decay assuming perfect mixing:

Concentration Decay

\[ C(t + \Delta t) = C_{\text{supply}} + \bigl(C(t) - C_{\text{supply}}\bigr) \times \exp\!\Bigl(-\frac{Q \cdot \Delta t}{V_{\text{ullage}}}\Bigr) \]

Where Q is the volumetric IG flow rate (m³/h) and V_ullage is the tank ullage volume. O₂ supply defaults to 3% (flue gas), HC supply to 0.1%.

Pressure

Driven by IG inflow and liquid level change:

Ullage Pressure

\[ \Delta P = \frac{\Delta V_{\text{ig}}}{V_{\text{ullage}}} \cdot P_{\text{atm}} + \frac{\Delta V_{\text{liquid}}}{V_{\text{ullage}}} \cdot P_{\text{atm}} \]

P/V Valve

Proportional relief (not binary). The valve modulates flow proportionally to pressure deviation from setpoint:

P/V Valve Flow

\[ Q_{\text{vent}} = K \cdot \max(0,\; P - P_{\text{setpoint}}) \]

K = 200 m³/h per mmWG, pressure setpoint 1400 mmWG (vent), −350 mmWG (vacuum admit). Hard backstops at +1800 / −500 mmWG simulate P/V breaker behaviour.

Flow Distribution

Total IG supply from running blowers splits equally among open tank isolation valves, after mast riser diversion (85% when open). Deck isolating valve gates all flow.

Piping Hydraulics

Steady-state Newton-Raphson network solver for multi-system piping (cargo, ballast, IG, tank cleaning run simultaneously with shared tank states).

Pipe Friction

Darcy-Weisbach with Churchill correlation (all Reynolds regimes):

Darcy-Weisbach

\[ \Delta P_{\text{pipe}} = f \cdot \frac{L}{D} \cdot \frac{v^2}{2g} \]

Valve Loss

Cv method with equal-percentage characteristic:

Valve Pressure Drop

\[ \Delta P_{\text{valve}} = \left(\frac{Q}{C_{v,\text{eff}}}\right)^2 \cdot SG, \quad C_{v,\text{eff}} = C_{v,\text{full}} \cdot \left(\frac{\text{opening}}{100}\right)^2 \]

Pump Head

Parabolic H-Q curve with affinity law speed scaling:

Pump Characteristic

\[ H = H_{\text{shutoff}} - (H_{\text{shutoff}} - H_{\text{rated}}) \cdot \left(\frac{Q}{Q_{\text{rated}}}\right)^2 \]

Convergence

Damped Newton updates (α = 100/max(dx)), regularisation near zero flow, max 50 iterations, tolerance 1×10⁻⁶ m³/h. Check valves enforced via iterative re-solve blocking reverse flow.

Stability & Hydrostatics

Intact stability calculation from weight/moment summation and hydrostatic table interpolation.

Displacement: Δ = m_lightship + Σ(V_tank × ρ_cargo)
Centre of gravity: KG = Σ(m_i × KG_i) / Δ, LCG and TCG likewise
Draft: reverse-interpolated from hydrostatic table (draft → displacement)
GM: GM_solid = KM_T − KG; free surface correction FSE = Σ(ρ × I_T / Δ) for slack tanks (2–98% fill); GM_fluid = GM_solid − FSE
Trim: trim = Δ × (LCG − LCB) / MCTC
List: tan(θ) = TCG / GM_fluid
GZ curve: GZ(θ) = KN(θ) − KG × sin(θ), interpolated from cross-curve tables

IMO Criteria

IMO intact stability criteria (A.749) checked automatically: area under GZ curve to 30°/40°, maximum GZ, angle of maximum GZ, initial GM.

Thermal Model

Lumped-parameter heat balance per tank:

Tank Temperature

\[ \Delta T = \frac{(Q_{\text{coil}} - Q_{\text{loss}}) \cdot \Delta t}{m \cdot C_p} \]

\( Q_{\text{coil}} = U_{\text{coil}} \cdot A_{\text{coil}} \cdot (T_{\text{steam}} - T_{\text{cargo}}) \) — heating only

\( Q_{\text{loss}} = U_{\text{hull}} \cdot A_{\text{hull}} \cdot (T_{\text{cargo}} - T_{\text{ambient}}) \) — always active

Defaults: U_coil = 50 W/(m²·K), U_hull = 5 W/(m²·K), steam at 170 °C, C_p = 2000 J/(kg·K). Coil and hull areas scale with tank volume. Alarms on flash point and pour point approach.

Crude Oil Washing

Surface coverage model:

COW Progress

\[ \frac{d\,\text{Progress}}{dt} = \frac{Q_{\text{wash}} \cdot k \cdot A_{\text{surface\_factor}}}{A_{\text{surface}}} \]

Where A_surface = 6 × V^2/3. Requires IG pressure ≥ 100 mmWG (safety interlock). One full cycle calibrated to ~60 min at 80 m³/h.

Vapour Generation

VOC generation from cargo surface, proportional to Reid Vapour Pressure:

VOC Rate

\[ \frac{d\,\text{HC}}{dt} = k_{\text{base}} \cdot \text{RVP} \cdot A_{\text{surface}} \cdot \frac{\text{loading\_factor}}{V_{\text{ullage}}} \]

Loading factor 3× during active cargo transfer (turbulence-driven evaporation). Dissipation when O₂ > 5%. Alarms at 30% and 50% LEL.

Calibration System

The calibration architecture accepts manual observations — the kind of data already recorded in tanker logbooks — and uses them to tune physics parameters.

Observation Types

IG O₂ decay rate, IG tank pressure, thermal rate, flow rate, COW duration.

Solver

Groups observations by type (minimum 3), computes mean bias and standard deviation of residuals, derives confidence metric (1 − σ/(|bias| + σ)), suggests parameter corrections via ratio or inverse-ratio adjustment. Only suggestions with >50% confidence and >1% bias are surfaced.

Workflow

Observe → Log → Suggest → Review → Apply. No automatic parameter changes — the operator always decides.

A downloadable Excel template is provided for bulk observation entry.

Physics Parameters

All 20 parameters have sensible defaults and can be overridden per vessel:

Parameter	Default	Unit	Controls
`ig_supply_o2`	0.03	fraction	O₂ in flue gas supply
`ig_hc_supply`	0.001	fraction	HC in clean IG
`ig_blower_rated_flow`	5000	m³/h	Blower capacity at 100%
`pv_valve_press`	1400	mmWG	P/V valve vent setpoint
`pv_valve_vac`	−350	mmWG	P/V valve vacuum setpoint
`pv_valve_gain`	200	m³/h per mmWG	P/V proportional gain
`mast_vent_fraction`	0.85	fraction	Mast riser diversion ratio
`u_coil`	50	W/(m²·K)	Heating coil U-value
`u_hull`	5	W/(m²·K)	Hull heat transfer
`steam_temp_c`	170	°C	Steam supply temperature
`cp_cargo`	2000	J/(kg·K)	Cargo specific heat
`coil_area_per_m3`	0.1	m²/m³	Coil surface per tank volume
`hull_area_per_m3`	0.15	m²/m³	Wetted surface per tank volume
`cow_effectiveness`	0.3	—	COW washing rate factor
`cow_ig_pressure_min`	100	mmWG	Minimum IG for safe COW
`voc_base_rate`	0.001	frac/s/m²	Base VOC generation rate
`surface_area_per_vol`	0.05	m²/m³	Tank surface estimate
`loading_factor`	3.0	multiplier	VOC multiplier during loading
`default_cargo_density`	850	kg/m³	Fallback cargo density
`default_ballast_density`	1025	kg/m³	Seawater density

Vessel Definition Spec

Any tanker can be modelled by providing a VDS JSON file defining:

Hull & Tanks

Hull geometry (LBP, beam, depth)
Tank calibration tables (ullage → volume → VCG → I_T)
Lightship parameters (weight, KG, LCG)

Piping Networks

Pipe segments (length, diameter, material)
Valves (Cv, type, position)
Pumps (H-Q curves, speed control)

Hydrostatics

Hydrostatic tables (draft → displacement, KM_T, LCB, MCTC)
Cross-curve data (KN values at heel angles)

P&ID Layout

Equipment coordinates and symbols
Pipe routing for SVG rendering
Alarm thresholds per system

Dev Log

v0.0.1 — 7 March 2026

Public announcement. Baseline version.

Initial prototype. Core simulation engine with 8 physics subsystems, multi-system piping, real-time P&ID visualisation, and calibration framework.

What works

Real-time cargo loading/discharge with simultaneous ballast operations
Inert gas system with dual blowers, deck main, mast riser, P/V valves
Crude oil washing with IG pressure interlocks
Thermal model (steam heating coils + ambient heat loss)
VOC generation with LEL alarms
Intact stability (hydrostatics, GZ curves, IMO A.749 criteria)
Multi-system piping (cargo + ballast + IG + COW solve simultaneously)
Per-vessel calibration with observation logging and statistical suggestions
VDS-driven rendering (any tanker from a JSON definition file)

What needs validation

All physical models need comparison against sea trial data
P/V valve proportional model needs tuning against actual valve characteristics
COW effectiveness factor is empirically estimated
Thermal U-values are literature defaults, not measured
Flow solver assumes steady-state (no water hammer, no transients)
Free surface effect uses simplified I_T interpolation

Planned

Engine room equipment modelling (pumps, boilers, purifiers)
Import of operational logs from existing fleet management systems
Fleet-wide parameter learning across sister vessels