Architeuthis: Weather Routing for Wind-powered Hybrid Vessels 🦑
Minimize fuel on a fixed schedule, with real forecasts, real constraints and your own vessel model.
📚 User Guide | 🧪 Examples | ❔ 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.
No graph, no grid search: the waypoints are continuous variables of a single nonlinear program. Weather, bathymetry and your vessel are differentiable models queried at those waypoints, CasADi differentiates through all of it and IPOPT finds the route.
- ⛽ Fuel-optimal routes on a fixed departure and arrival time
- 🧩 Any vessel model: a polar table, or your own semi-empirical functions with their fitted parameters
- 🌊 Wind, waves, currents and more: IFS, GFS, ensembles, Mercator, ERA5, and any other field your model needs
- 🧊 Real-world constraints: land, shallow water, exclusion zones, the iceberg limit, maximum power, your own rules
- 🎲 Forecast uncertainty: optimize each ensemble member, test a plan against other models, members or vessels
- 📊 Ready-to-use outputs: A4 reports, maps, tables, GPX tracks and an interactive viewer
Architeuthis provides the onshore weather routing support of Neoliner Origin 🌬️⛵⚓
Keywords: weather routing, voyage optimization, fuel saving, wind-assisted ship propulsion, hybrid vessel, passage planning, nonlinear optimization, CasADi, IPOPT, GRIB2, xarray, python
🚀 Quick Start
pip install architeuthis # add [app] for the interactive viewer
Or from source: git clone https://github.com/julesricheux/Architeuthis.git, then conda env create -f environment.yaml and run everything from the repository root (Python 3.11 or later).
A North Atlantic crossing on yesterday's ECMWF forecast, with no account and no credentials:
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.)
today = pd.Timestamp("now").floor("1d")
date = today - pd.Timedelta(days=1) # yesterday's 00 UTC run
steps = list(range(0, 145, 3)) + list(range(150, 241, 6)) # lead times, in hours
atmosphere = DeterministicHerbieForecast("wind", model="ifs", product="oper", regex=r":10[u|v]:", fxx=steps, date=date, **domain)
atmosphere.load_data()
for key in ("u10", "v10"):
atmosphere.add_interpolator(key, "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_wave_components() # direction through its components
for key in ("swh", "uw", "vw"):
wave.add_interpolator(key, "valid_time", "latitude", "longitude")
calm = xr.zeros_like(atmosphere.data["u10"]) # calm water; see CopernicusForecast for currents
current = Forecast("calm_current", date=None, fxx=None, **domain)
current.data = xr.Dataset({"uo": calm, "vo": calm})
for key in ("uo", "vo"):
current.add_interpolator(key, "valid_time", "latitude", "longitude")
topography = Topography("topography", **domain)
topography.load_data()
topography.add_interpolator("distance_to_iso0", "lat", "lon", var_key="z")
vessel = Vessel("vessel", filepath="my_vessel_polar.nc", sfc=220., hotel_load=194., max_power=4100.) # g/kWh, kW, kW
vessel.load_data()
for key in ("bhp", "max_bhp", "sails_contribution"):
vessel.add_interpolator(key, "stw", "tws", "twa", "hs", "wa", method="linear")
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)
report = RoutingAnalysis("crossing", vessel, voyage, atmosphere, wave, current, topography).run()
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
🚢 Your Vessel
Architeuthis ships no vessel model: bring yours, as a table or as functions. Both are models of the same object, queried the same way, and the routing does not care which one it gets.
📋 A polar table, from a VPP, sea trials or anything else: a NetCDF file with bhp, max_bhp and sails_contribution (kW, kW, %) on the axes stw, tws, twa, hs, wa (kt, kt, deg, m, deg). That is the Quick Start.
🧮 Or your own functions, with their fitted parameters, and no file at all:
import architeuthis.numpy as np
def my_polar(x, p):
tws = (x["tws"] + x["tws100"]) / 2. # wind between 10 m and 100 m
sails = p["c_sail"] * tws**2 * x["stw"] * np.sind(x["twa100"])**2
calm = p["c_calm"] * x["stw"]**3 * (1. + p["k_t"] * (x["water_temperature"] - 15.))
return calm - sails, {"calm": calm, "sails": sails}
inputs = ["stw", "tws", "tws100", "twa100", "water_temperature"]
vessel = Vessel("my_ship", sfc=220., max_power=4100.)
vessel.add_function("bhp", my_polar, inputs, args={"p": fitted})
vessel.add_function("max_bhp", my_polar, inputs, args={"p": fitted})
vessel.add_function("sails_contribution", my_polar, inputs, args={"p": fitted}, output="sails")
✨ The routing finds what your model needs
Name an input, and the routing provides it. No wiring, no plumbing:
| Your model asks for | The routing |
|---|---|
stw, sog, tws, twd, twa, aws, awa, hs/swh, wa/mwa |
computes them along the route, relative to the vessel |
tws100, twa100, aws100, awa100... at any height |
computes them the same way from the forecast's u100 and v100 |
anything else: water_temperature, mwp, air_temperature... |
samples the forecast that has a model of that name |
So the forecasts above only need a few more lines, and the routing is unchanged:
atmosphere = DeterministicHerbieForecast("wind", model="ifs", product="oper", regex=r":(?:10[uv]|100[uv]):", ...) # one download, several levels
atmosphere.add_interpolator("u100", "valid_time", "latitude", "longitude")
atmosphere.add_interpolator("v100", "valid_time", "latitude", "longitude")
current.add_interpolator("thetao", "valid_time", "latitude", "longitude", var_key="water_temperature")
A forecast can hold functions too, to convert a unit or combine fields: atmosphere.add_function("air_temperature", lambda x: atmosphere("t2m", x) - 273.15, inputs=["valid_time", "latitude", "longitude"]).
Quantities your model does not use can be computed all the same, to constrain them or see them in the reports: RoutingAnalysis(..., variables=["tws_gust", "wave.slope"]) puts the gusts and a wave slope in ctx and in every report.
💡 Good practice
- Stay differentiable: write with
architeuthis.numpy, and usenp.where,np.softmaxornp.sigmoidrather thanifon values. - Mind the units: routing quantities are in kt and degrees, angles in absolute value. Forecast fields arrive as stored (m/s, K): convert them with
fac=or a function. - Return components:
(value, {"sails": ...}), then pick one withoutput=. - Set a realistic
max_powerandsfc: a huge power limit unsettles the solver, and the objective is zero withoutsfc.
The complete script is examples/function_polar_routing.py, and the User Guide has the details.
🔑 Credentials and Settings
> What You Need to Set
Mostly nothing: IFS, GFS, HRDPS, ETOPO and the iceberg limit need no account. Each credential is needed only by its provider.
| What | For | How |
|---|---|---|
CMEMS_USER, CMEMS_PWD |
Currents, forecast.CopernicusForecast |
Save them once, get them |
CDS_API_KEY |
Reanalysis, forecast.CDSForecast |
Save it once, get it |
EUMDAC_KEY, EUMDAC_SECRET |
Satellite data, satellite.ASCATData, satellite.PoseidonData |
Save them once, get them |
ARCHITEUTHIS_HOME |
Optional: keep downloads elsewhere than ~/data/ |
An environment variable |
> Saving Your Credentials Once
In the environment where Architeuthis lives, run set with the names you need. It asks for each value, hidden:
python -m architeuthis.credentials set CMEMS_USER CMEMS_PWD
Then check what Architeuthis finds, without showing any value:
python -m architeuthis.credentials status
CDS_API_KEY missing
CMEMS_USER credential store
CMEMS_PWD credential store
EUMDAC_KEY missing
EUMDAC_SECRET missing
Done: every session finds them, in Spyder, a notebook or a script. They stay encrypted by your operating system (Windows Credential Manager, macOS Keychain, Secret Service), through keyring. Run set again to change one, and remove one with:
python -m architeuthis.credentials delete CMEMS_PWD
From Python: save_credential("CMEMS_PWD") and credential_sources(), in architeuthis.credentials. A missing credential stops the download before it starts, with a ⚠️ message and the command that fixes it.
> Where Architeuthis Looks
Only when a download needs them, never at import, taking the first value found:
- An environment variable of the same name, or one of the providers' own:
CDSAPI_KEY,COPERNICUSMARINE_SERVICE_USERNAME,COPERNICUSMARINE_SERVICE_PASSWORD, andEUMDAC_USERandEUMDAC_PWD, the former names ofEUMDAC_KEYandEUMDAC_SECRET. - The credential store, where
setsaves them. - The provider's own file:
copernicusmarine login, or~/.cdsapirc.
Environment variables suit servers, CI jobs and containers, where there is no credential store, and override the store for a while. Saving a credential removes its variables from the current session, with a ⚠️ message naming them: delete them where they are defined too, or new sessions keep reading the old value. Give them as secrets of the platform; saved in a profile (setx, ~/.bashrc, conda env config vars) they sit in plain text.
> The Data Folder
Everything goes to ~/data/:
| Folder | Holds |
|---|---|
topo/, cmems/, cds/, eumetsat/, iip/ |
Downloads: relief, currents, reanalysis, satellite data, iceberg limit |
route_library/, route_sets/, passage_plans/, exclusion_zones/ |
Your saved routes, plans and zones |
routes/ |
Reports saved by ReportCollection.save, read by the viewer |
Set ARCHITEUTHIS_HOME to move it, then open a new terminal: setx ARCHITEUTHIS_HOME "D:\architeuthis-data" on Windows, export ARCHITEUTHIS_HOME="$HOME/architeuthis-data" in ~/.bashrc elsewhere. Herbie keeps the GRIB files in its own save_dir (~/.config/herbie/config.toml).
> Keeping Credentials Safe
- 🔒 Never write a credential in code, a notebook or a comment: a repository's history keeps it forever.
- If one leaks, change it at the provider, then
setit again. - Coming from 0.2.0 or earlier? Your environment variables still work. Move them to the store with
set, check withstatus, then delete them and the~/.cdsapircArchiteuthis wrote.
Copernicus Marine (currents)
Create a free account at data.marine.copernicus.eu/register, then save your username as CMEMS_USER and your password as CMEMS_PWD. To check them (prints True):
import copernicusmarine
from architeuthis.credentials import get_credential
print(copernicusmarine.login(get_credential("CMEMS_USER"), get_credential("CMEMS_PWD"), check_credentials_valid=True))
Climate Data Store (ERA5)
Create a free account at the Climate Data Store, save the Personal Access Token of your profile as CDS_API_KEY, and accept the Terms of Use of each dataset you need, such as ERA5 single levels. Architeuthis hands the token to the client and writes no file; without one, the client falls back to your own ~/.cdsapirc:
url: https://cds.climate.copernicus.eu/api
key: your-personal-access-token
EUMETSAT (satellite observations)
Not your login: on the API key page of a free EUMETSAT account, save your Consumer Key as EUMDAC_KEY and your Consumer Secret as EUMDAC_SECRET. To check them (prints an expiry date):
import eumdac
from architeuthis.credentials import get_credential
print(eumdac.AccessToken((get_credential("EUMDAC_KEY"), get_credential("EUMDAC_SECRET"))).expiration)
🗺️ The Routing Problem
- Objective: total fuel,
sum((bhp + hotel_load) * dt * sfc) / 1e6, in tonnes. - Fixed: departure, arrival, ETD and ETA. The schedule is a requirement, the speed an outcome.
- Variables: the positions along the route, and optionally a factor blending the reference route towards two alternatives.
- Constraints: brake power below
max_powerand every position at sea, or your own, on any quantity of the route or any additional variable (variables=).
🙏 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 this one.
- CasADi (LGPL) and IPOPT (EPL) differentiate and solve the routing problem.
- Copernicus Marine Toolbox, xarray, Cartopy, Dash and the other dependencies of
pyproject.toml. - The forecast, ocean, relief and ice data of their providers.
Contributing
Report bugs or suggest features in the issues, and star this repository! ⭐
⚖️ License
Metadata
Release files for architeuthis 0.3.1
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.3.1.tar.gz | 2.5 MB | With provenance | Details for architeuthis-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| architeuthis-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for architeuthis-0.3.1-py3-none-any.whl |
Total release size: 4.9 MB
Release files / architeuthis-0.3.1.tar.gz
| Download URL | architeuthis-0.3.1.tar.gz |
|---|---|
| Size | 2.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5a90f4ea8c9bb90b47feb25a947f089af3ccdcb4d5f549c64f252719d2400277
|
|
BLAKE2b-256 checksum How to use checksums |
83be945e05a2feee9cc2887c1a3c34ca3ad0dc8c2b7b6e014f79128e9774bf22
|
| 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 18, 2026.
Transparency logRelease files / architeuthis-0.3.1-py3-none-any.whl
| Download URL | architeuthis-0.3.1-py3-none-any.whl |
|---|---|
| Size | 2.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1f7c55b7443989cf83b16c55e08ec6c8f5a33dbb8945f4e2b219aaf71ef5a7b5
|
|
BLAKE2b-256 checksum How to use checksums |
3a9dc27a86e3133753a7f41eae2133cc471c4d2b74c620b4e40e2cd4132212db
|
| 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 18, 2026.
Transparency logSecurity for architeuthis 0.3.1
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.3.1.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 18, 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.