Architeuthis: Weather Routing for Wind-powered Hybrid Vessels 🦑
Minimize fuel on a fixed schedule, with real forecasts, constraints and custom vessel model.
📚 User Guide | ❔ Issues
What is Architeuthis?
An open-source marine weather and decision-making framework for hybrid sailing ships. It couples mesh-free, fully differentiable methods in a unified optimization environment to compute optimal routes under real-world constraints.
"Mesh-free" means that routes are not searched on a graph. The waypoints are continuous variables of a single nonlinear program, and weather, bathymetry and vessel performance are differentiable tables queried at those waypoints. CasADi differentiates through everything and IPOPT solves the problem.
Key Features:
- ⛽ Fuel-optimal routes - Minimize the fuel of a voyage with a fixed departure and arrival time
- 🚢 Motor and hybrid vessels - Bring your vessel as a performance table, with or without sails
- 🌊 Wind, waves and currents - Ready-made IFS, GFS, ensemble and Mercator sources
- 🧊 Real-world constraints - Land, shallow water, exclusion zones, the iceberg limit, maximum power and your own constraints
- 🎲 Forecast uncertainty - Optimize each ensemble member, and test a plan against other models, members or vessels
- 📊 Ready-to-use outputs - A4 reports, maps, tables, GPX tracks and an interactive viewer
Keywords: weather routing, voyage optimization, fuel saving, wind-assisted ship propulsion, hybrid vessel, passage planning, nonlinear optimization, CasADi, IPOPT, GRIB2, xarray, python
Architeuthis is the tool used for the onshore weather routing support for Neoliner Origin 🌬️⛵⚓
🚀 Quick Start
⚙️ Installation
Architeuthis needs Python 3.11 or later.
With pip:
pip install architeuthis
Add the interactive viewer with:
pip install "architeuthis[app]"
From source, with conda:
git clone https://github.com/julesricheux/Architeuthis.git
cd Architeuthis
conda env create -f environment.yaml
The environment is named py313-architeuthis. The package then needs no installation: run everything from the repository root.
💡 Simple Example
This example routes a vessel across the North Atlantic with recent ECMWF forecasts. It needs no credentials, only a polar file for your vessel (see Your Vessel).
import pandas as pd
import xarray as xr
from architeuthis.core import RoutingAnalysis
from architeuthis.forecast import DeterministicHerbieForecast, Forecast, Topography
from architeuthis.report import ReportCollection
from architeuthis.route import Route, Waypoint
from architeuthis.toolbox.plot_utils import plot_report
from architeuthis.vessel import Vessel
from architeuthis.voyage import Voyage
domain = dict(min_lon=-60., max_lon=0., min_lat=38., max_lat=56.)
# Yesterday's 00 UTC forecast, with its lead times in hours
today = pd.Timestamp("now").floor("1d")
date = today - pd.Timedelta(days=1)
steps = list(range(0, 145, 3)) + list(range(150, 241, 6))
atmosphere = DeterministicHerbieForecast("wind", model="ifs", product="oper", regex=r":10[u|v]:", fxx=steps, date=date, **domain)
atmosphere.load_data()
atmosphere.add_interpolator("u10", "valid_time", "latitude", "longitude")
atmosphere.add_interpolator("v10", "valid_time", "latitude", "longitude")
wave = DeterministicHerbieForecast("wave", model="ifs", product="wave", regex=r":swh:|:mwd:", fxx=steps, date=date, **domain)
wave.load_data()
wave.add_interpolator("swh", "valid_time", "latitude", "longitude")
wave.add_interpolator("mwd", "valid_time", "latitude", "longitude")
# Calm water on the grid of the wind. For real currents, see CopernicusForecast in examples/post_leg_rewind.py
calm = xr.zeros_like(atmosphere.data["u10"])
current = Forecast("calm_current", date=None, fxx=None, **domain)
current.data = xr.Dataset({"uo": calm, "vo": calm})
current.add_interpolator("uo", "valid_time", "latitude", "longitude")
current.add_interpolator("vo", "valid_time", "latitude", "longitude")
topography = Topography("topography", **domain)
topography.load_data()
topography.add_interpolator("distance_to_iso0", "lat", "lon", var_key="z")
# Specific fuel consumption in g/kWh, loads and power in kW
vessel = Vessel("vessel", filepath="my_vessel_polar.nc", sfc=220., hotel_load=194., max_power=4100.)
vessel.load_data()
for key in ("bhp", "max_bhp", "sails_contribution"):
vessel.add_interpolator(key, "stw", "tws", "twa", "hs", "wa", method="linear")
# The reference route and the schedule, in UTC
route = Route("crossing", [Waypoint(47.725, -4.380, "Penmarch"), Waypoint(46.551, -53.321, "Cape Race")])
voyage = Voyage("crossing", etd=today, eta=today + pd.Timedelta(days=8), route=route)
# Optimize
analysis = RoutingAnalysis("crossing", vessel, voyage, atmosphere, wave, current, topography)
report = analysis.run()
# Results
reports = ReportCollection([report])
print(reports.summary())
reports.to_gpx() # a track for your navigation system
reports.save() # for the viewer
plot_report(report) # one A4 page: speed, sails, power, waves and wind against time
🚢 Your Vessel
Architeuthis does not include a vessel model. You provide a NetCDF performance table, which can come from a velocity prediction program, sea trials or a simpler model. A motor vessel and a hybrid vessel only differ by the content of this table: for a motor vessel, sails_contribution is zero.
| Variable | Meaning | Unit |
|---|---|---|
bhp |
Average brake power | kW |
max_bhp |
Brake power with load fluctuations, checked against max_power |
kW |
sails_contribution |
Share of the propulsion from sails, for the reports | % |
Each variable has the five dimensions below, in this order:
| Dimension | Meaning | Unit |
|---|---|---|
stw |
Speed through water | kt |
tws |
True wind speed | kt |
twa |
True wind angle, 0 to 180 | deg |
hs |
Significant wave height | m |
wa |
Wave angle, 0 to 180 | deg |
sfc and hotel_load are given to Vessel as constants or as functions of the power, and sfc must be set because the objective is zero without it. A polar named ..._eff45.nc gets the label eff45 in reports, or you can give any label.
🔑 Credentials
IFS, GFS, HRDPS, ETOPO and the iceberg limit need no account. The other providers are free but need one, and only when you use them:
| You want | Provider | Environment variables |
|---|---|---|
Currents, forecast.CopernicusForecast |
Copernicus Marine | CMEMS_USER, CMEMS_PWD |
Reanalysis, forecast.CDSForecast |
Climate Data Store | CDS_API_KEY |
Satellite observations, satellite.ASCATData, satellite.PoseidonData |
EUMETSAT | EUMDAC_USER, EUMDAC_PWD |
> Setting an Environment Variable
Architeuthis reads these variables when it is imported, so set them first, then open a new terminal or restart Spyder. The examples below use CMEMS_USER: do the same for each variable.
Windows: search for Edit environment variables for your account in the Start menu, then choose New. Or, in PowerShell:
setx CMEMS_USER "your-username"
Linux and macOS: add this line to ~/.bashrc or ~/.zshrc:
export CMEMS_USER="your-username"
In a conda environment, so that the values only apply there, then activate the environment again:
conda env config vars set CMEMS_USER="your-username" -n py313-architeuthis
For one session only, before any Architeuthis import:
import os
from getpass import getpass
os.environ["CMEMS_USER"] = "your-username"
os.environ["CMEMS_PWD"] = getpass("Copernicus Marine password: ")
from architeuthis.forecast import CopernicusForecast
To check which variables Python can see, without showing their values:
import os
for name in ("CMEMS_USER", "CMEMS_PWD", "CDS_API_KEY", "EUMDAC_USER", "EUMDAC_PWD"):
print(name, "is set" if os.environ.get(name) else "is missing")
🔒 Keep credentials out of your code. Anything committed to a repository stays in its history, even after it is removed from the files, and a public repository exposes it to everyone. These methods store values in plain text in your user profile, so keep them out of shared machines and shared folders. If a credential leaks, change it at the provider right away. A value typed in a command also stays in the shell history.
Copernicus Marine (currents)
- Create a free account at data.marine.copernicus.eu/register.
- Set
CMEMS_USERto your username andCMEMS_PWDto your password. - Check them, which prints
Trueif they are valid:
import os
import copernicusmarine
print(copernicusmarine.login(os.environ["CMEMS_USER"], os.environ["CMEMS_PWD"], check_credentials_valid=True))
If you prefer, leave the variables unset and store your credentials once with copernicusmarine login. The toolbox then finds them in ~/.copernicusmarine/. The startup log still says that they are incomplete, which you can ignore.
Climate Data Store (ERA5)
- Create a free account at the Climate Data Store.
- Copy your Personal Access Token from your profile page, and set
CDS_API_KEYto it. - Open the page of each dataset you need, such as ERA5 single levels, and accept its Terms of Use. Downloads are refused until you do.
At its first download, Architeuthis writes the token to ~/.cdsapirc and uses this file from then on. If you change your token, update or delete this file, because a new CDS_API_KEY does not replace it. You can also write the file yourself and leave the variable unset:
url: https://cds.climate.copernicus.eu/api
key: your-personal-access-token
EUMETSAT (satellite observations)
Despite their names, these two variables do not take your login and password:
- Create a free EUMETSAT account and open the API key page.
- Set
EUMDAC_USERto your Consumer Key andEUMDAC_PWDto your Consumer Secret. - Check them, which prints an expiry date, or
401 Unauthorizedif they are wrong:
import os
import eumdac
print(eumdac.AccessToken((os.environ["EUMDAC_USER"], os.environ["EUMDAC_PWD"])).expiration)
eumdac set-credentials configures the eumdac command only, so Architeuthis still needs the variables.
🗺️ The Routing Problem
- Objective: total fuel,
sum((bhp + hotel_load) * dt * sfc) / 1e6, in tonnes. - Fixed: departure and arrival, ETD and ETA. The schedule is a requirement and the speed is an outcome.
- Variables: the positions along the route, and optionally a factor that blends the reference route towards two alternatives.
- Constraints: by default, brake power below
max_powerand every position in navigable water. Your own constraints can replace them.
🙏 Credits
Architeuthis stands on the work of others, with our thanks:
- AeroSandbox by Peter D. Sharpe (MIT). The
numpy,optimizationandmodelingpackages are adapted from version 4.2.9 (license). - Herbie by Brian K. Blaylock (MIT) downloads the forecasts, and its README inspired the structure of this one.
- CasADi (LGPL) and IPOPT (EPL) differentiate and solve the routing problem.
- Copernicus Marine Toolbox, xarray, Cartopy, Dash and the other dependencies listed in
pyproject.toml. - The forecast, ocean, relief and ice data of their providers.
Contributing
Please report bugs or suggest features via issues and star this repository! ⭐
⚖️ License
Metadata
Release files for architeuthis 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| architeuthis-0.2.0.tar.gz | 2.4 MB | With provenance | Details for architeuthis-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| architeuthis-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for architeuthis-0.2.0-py3-none-any.whl |
Total release size: 4.8 MB
Release files / architeuthis-0.2.0.tar.gz
| Download URL | architeuthis-0.2.0.tar.gz |
|---|---|
| Size | 2.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d547aa0b7b7222ea3d7ad1db3d1509ae858e9d8c9daf4ba57f7f6339493cc774
|
|
BLAKE2b-256 checksum How to use checksums |
cef57cc2d9ef93705ea17415313fb4a26fcb84db2e06709e57c7ba5253772e76
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / architeuthis-0.2.0-py3-none-any.whl
| Download URL | architeuthis-0.2.0-py3-none-any.whl |
|---|---|
| Size | 2.4 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
315984abda4eae418fa3ecaca9d5ece9e2f80d6179851f485751ed47b243c6a0
|
|
BLAKE2b-256 checksum How to use checksums |
19cbe4b993618555c6fa4379cf0838fa14b3f58a0425580dce5cc60798cca4e2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logSecurity for architeuthis 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for architeuthis-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.