Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Using Newtonian PINNs

A physics-informed Seq2Seq model that penalizes unrealistic velocity and acceleration in predicted vessel tracks, so forecasts stay kinematically plausible even when AIS data is sparse or noisy.

Purely statistical Seq2Seq models can forecast vessel tracks that look plausible yet turn or accelerate in ways no real ship can. This tutorial builds NPINN, an attention-based Seq2Seq LSTM trained under a combined data-fidelity and kinematic-smoothness loss, so predicted trajectories respect how vessels actually move. You walk away with a complete pipeline, from AISdb query and cleaning through training to an evaluation that reports errors in real meters on a held-out time window.

What you will learn

  • Cleaning, linking, and interpolating AIS tracks into fixed-interval UTM features with AISdb

  • Building sliding-window Seq2Seq datasets that predict future position residuals

  • Training an attention LSTM with a physics-inspired penalty on velocity and acceleration

  • Evaluating forecasts in meters with haversine errors and trajectory-length checks

Prerequisites

pip install aisdb torch scikit-learn pyproj joblib pandas cartopy matplotlib

The run shown on this page trained on a private regional database built from AISdb's Meridian receiver network, covering the Gulf of St. Lawrence and Cabot Strait over a few days in August 2018, with a test window that starts after training ends so the model must extrapolate to traffic it never saw. If you lack a comparable database, the open NOAA day file works as a drop-in. Download AIS_2020_01_01.zip from coast.noaa.gov, decode the extracted CSV with aisdb.decode_msgs(filepaths=[...], dbconn=dbconn, source="NOAA") into a SQLite database, point DB_CONNECTION at it, set the bounding box to -98, 24, -80, 31, and set the dates to 2020-01-01 through 2020-01-02. One day cannot supply a genuinely unseen test window, so treat a NOAA run as a pipeline check. The numbers and figures below come from the private multi-day dataset.

Step 1. Imports and configuration

Everything the pipeline needs lands in one place, including the training window, the later held-out test window, the bounding box, and the UTM projection that converts lat/lon into meters for the physics loss.

import json
import random
from collections import defaultdict
from datetime import datetime, timedelta

import joblib
import numpy as np
import pandas as pd
import pyproj
import torch
import torch.nn as nn
import torch.nn.functional as F
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import RobustScaler
from torch.utils.data import DataLoader, TensorDataset

import aisdb
from aisdb import SQLiteDBConn, TrackGen
from aisdb.database.sqlfcn_callbacks import in_bbox_time

DB_CONNECTION = "/home/sqlite_database_file.db"  # replace with your data path
START_DATE = datetime(2018, 8, 1, hour=0)
END_DATE = datetime(2018, 8, 4, hour=2)
TEST_START_DATE = datetime(2018, 8, 5, hour=0)
TEST_END_DATE = datetime(2018, 8, 6, hour=8)
XMIN, YMIN, XMAX, YMAX = -64.828126, 46.113933, -58.500001, 49.619290

dbconn = SQLiteDBConn(dbpath=DB_CONNECTION)
# Cartesian projection used to convert lat/lon into meters for the physics loss
proj = pyproj.Proj(proj='utm', zone=20, ellps='WGS84')

Step 2. Preprocess tracks into model-ready features

Raw AIS is noisy and irregularly sampled, so AISdb first drops near-stationary pings, links segments by great-circle score, and interpolates to fixed 5-minute steps. The function then keeps vessels whose tracks all have at least 100 pings, projects positions to UTM meters, encodes course as sine and cosine to avoid the 359-to-0 degree jump, computes per-step deltas, and scales everything with outlier-resistant RobustScalers.

Step 3. Query, build sequences, and checkpoint

The training query fits fresh scalers while the test query reuses them, keeping both windows on the same scale. A window of 80 past steps predicts the next 2 residual movements, vessels are split between training and validation by MMSI so no vessel leaks across the split, and everything is serialized once so later sessions skip the query and preprocessing.

Step 4. Define the Seq2Seq model

An encoder LSTM summarizes the 80 past steps, and a decoder LSTMCell emits one residual at a time while an attention head picks which parts of the history matter for each step. Predicted residuals accumulate onto the last observed position to rebuild absolute coordinates, with teacher forcing on half the steps during training.

Step 5. Define the NPINN loss and training loop

The physics enters through the loss (the idea traces back to physics-informed neural networks, Raissi et al., 2019). First differences of the predicted path approximate velocity and second differences approximate acceleration, so penalizing both keeps trajectories kinematically smooth, while a smooth L1 term keeps them close to the observed positions. The smoothness weight decays over the first 30 epochs, letting the constraint guide early training without capping final accuracy.

Step 6. Train

Fixed seeds and deterministic CuDNN make the run reproducible, and the global min and max of the training coordinates normalize the smoothness penalty so its magnitude does not depend on where the region sits in UTM space.

Step 7. Reload the best model and define evaluation helpers

A fresh session rebuilds everything from disk, the tensors, the scalers, the projection, and the best weights. The helpers invert the scaled residuals and positions back to meters, and haversine distances turn predicted lon/lat into errors a navigator can read.

Step 8. Evaluate on the held-out window

For each test batch the model predicts scaled residuals, which are inverted to meters, accumulated onto the last observed position, and projected back to lon/lat. Per-timestep haversine errors and trajectory-length differences summarize accuracy, and each true versus predicted pair is drawn on a map.

Results

Calling evaluate_with_errors on the held-out August 2018 window walks the test set trajectory by trajectory, printing the true and predicted length in meters for each one and rendering a map of the two paths.

Trajectory 2 covers 521.39 m in the ground truth and 508.66 m in the prediction, a difference of 12.73 m. In the figure below, the predicted path tracks the true path closely and stays roughly parallel to it, offset by a small, consistent margin rather than drifting away over time. The model underestimates the total path length by about 2.4%, a small error, and the smoothness of the predicted line is exactly what the kinematic penalty in the loss is meant to produce.

Predicted (red) vs. true (green) vessel trajectory 2, Gulf of St. Lawrence test window, August 2018.

Trajectory 5 runs the other way. The true length is 188.76 m against a predicted 206.01 m, overestimating the distance by about 9%. The path is still smooth and follows the right general direction, but the larger relative error on a shorter trajectory shows the model has more trouble scaling step lengths correctly when there is less distance for it to work with.

Predicted (red) vs. true (green) vessel trajectory 5, Gulf of St. Lawrence test window, August 2018.

Aggregated across the full test set, the mean per-timestep error is 45.03 m at the first predicted step and climbs to 80.80 m at the second, the usual compounding pattern for a residual model. Over the full two-step horizon the mean error is 62.92 m and the median is 61.72 m, close enough that a handful of outlier trajectories is not dragging the distribution around. Trajectory length holds up better than pointwise position, with a mean length difference of 11.82 m and a median of 12.73 m, under 3% relative error for most trajectories. Errors grow smoothly with the horizon rather than in erratic jumps, which is the signature the NPINN penalty is supposed to leave behind, though the two-step horizon tested here is short enough that longer horizons and a larger test population deserve their own validation.

Takeaway

  • The kinematic penalty is cheap to add and leaves a visible signature. Errors grow smoothly with the horizon, 45.03 m at the first step and 80.80 m at the second, instead of jumping erratically.

  • Fit scalers on the training window only, reuse them on the test window, and invert them before reporting, so every error reads in meters rather than scaled units.

  • The pipeline assumes one UTM zone (zone 20 here) and dense reporters (a 100-ping minimum), so swap the projection and revalidate before trusting it on wide regions, sparse vessels, or horizons past two steps.

  • Every vessel is forecast from its own history alone, so converging traffic is invisible to the model.

Next, TGNs with TorchGeometric models traffic as a temporal graph, so the model learns from the relational structure of traffic rather than one ship at a time.

Last updated