Skip to main content
Architeuthis logo

Architeuthis: Weather Routing for Wind-powered Hybrid Vessels 🦑

Minimize fuel on a fixed schedule, with real forecasts, constraints and custom vessel model.

PyPI - Python Version PyPI Tests Downloads License: GPL v3

📚 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)

  1. Create a free account at data.marine.copernicus.eu/register.
  2. Set CMEMS_USER to your username and CMEMS_PWD to your password.
  3. Check them, which prints True if 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)

  1. Create a free account at the Climate Data Store.
  2. Copy your Personal Access Token from your profile page, and set CDS_API_KEY to it.
  3. 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:

  1. Create a free EUMETSAT account and open the API key page.
  2. Set EUMDAC_USER to your Consumer Key and EUMDAC_PWD to your Consumer Secret.
  3. Check them, which prints an expiry date, or 401 Unauthorized if 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_power and 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, optimization and modeling packages 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

GNU General Public License v3.0.

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)

Source distribution for architeuthis 0.2.0
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)

Table of built distributions (wheels) for architeuthis 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page