CruisePlan Developer Guide
This guide describes the internal architecture for contributors and developers integrating directly with CruisePlan internals.
Module structure
cruiseplan/
├── config/ # Pydantic models, field definitions, constants, exceptions
├── runtime/ # CruiseInstance, Leg, Cluster, operation classes
├── timeline/ # Scheduling, distance/duration calculators
├── api/ # High-level API functions (thin wrappers)
├── cli/ # Subcommand argument parsers and runners
├── data/ # Bathymetry and PANGAEA data handling
├── interactive/ # Interactive station picker
├── output/ # Output generators (LaTeX, HTML, PNG, KML, NetCDF, CSV)
└── utils/ # Coordinate conversion and shared utilities
Data flow: YAML → CruiseInstance (runtime) → scheduler (timeline) → output files.
Two-layer architecture
Config layer (cruiseplan/config/)
Pydantic models for parsing and validating YAML input:
# cruiseplan/config/cruise_config.py
class CruiseConfig(BaseModel):
cruise_name: str
description: str | None = None
default_vessel_speed_kt: float # knots
default_distance_between_stations_km: float # km
turnaround_time_minutes: float # minutes
departure_port: str | PointDefinition | None = None
arrival_port: str | PointDefinition | None = None
points: list[PointDefinition] | None = None
legs: list[LegDefinition] | None = None
# ... more fields; see cruise_config.py
class LegDefinition(BaseModel):
name: str
departure_port: str | PointDefinition # required
arrival_port: str | PointDefinition # required
activities: list[str | dict] | None = None
vessel_speed_kt: float | None = None # knots; inherits from cruise
delay_start_minutes: float | None = None # minutes
buffer_time_minutes: float | None = None # minutes
ordered: bool | None = None
clusters: list[ClusterDefinition] | None = None
# cruiseplan/config/activities.py
class PointDefinition(FlexibleLocationModel):
name: str
operation_type: OperationTypeEnum | None = None
action: ActionEnum | None = None
operation_depth_m: float | None = None # metres
water_depth_m: float | None = None # metres
duration_minutes: float | None = None # minutes
delay_start_minutes: float | None = None # minutes
equipment: str | None = None
class LineDefinition(BaseModel):
name: str
route: list[GeoPoint]
vessel_speed_kt: float | None = None
distance_between_stations_km: float | None = None # km
max_depth: float | None = None # metres
class AreaDefinition(BaseModel):
name: str
corners: list[GeoPoint]
duration_minutes: float | None = None # minutes; required for area ops
Runtime layer (cruiseplan/runtime/)
Objects used during scheduling. Built from the config layer via factory methods.
# cruiseplan/runtime/cruise.py
class CruiseInstance:
def __init__(
self, config_path: str | Path
): ... # loads YAML, validates, builds runtime leg/cluster/operation tree
# cruiseplan/runtime/organizational.py
class Leg(BaseOrganizationUnit):
@classmethod
def from_definition(cls, leg_def: LegDefinition) -> "Leg": ...
def get_vessel_speed(self, default_speed: float) -> float: ...
def get_entry_point(self) -> tuple[float, float]: ... # (lat, lon)
def get_exit_point(self) -> tuple[float, float]: ...
class Cluster(BaseOrganizationUnit):
@classmethod
def from_definition(cls, cluster_def: ClusterDefinition) -> "Cluster": ...
# cruiseplan/runtime/operations.py
class PointOperation(BaseOperation):
@classmethod
def from_pydantic(cls, obj: PointDefinition) -> "PointOperation": ...
class LineOperation(BaseOperation):
@classmethod
def from_pydantic(
cls, obj: LineDefinition, default_speed: float
) -> "LineOperation": ...
class AreaOperation(BaseOperation):
@classmethod
def from_pydantic(cls, obj: AreaDefinition) -> "AreaOperation": ...
Timeline layer (cruiseplan/timeline/)
Distance and duration calculations, schedule generation.
# cruiseplan/timeline/distance.py
def haversine_distance(start: tuple[float, float], end: tuple[float, float]) -> float:
"""Returns distance in kilometres (great circle)."""
# cruiseplan/timeline/duration.py
class DurationCalculator:
def calculate_ctd_time(self, depth: float) -> float:
"""Depth-based CTD timing: descent + ascent + turnaround."""
def calculate_transit_time(
self, distance_km: float, speed_knots: float | None = None
) -> float:
"""Route-based transit timing with unit conversion."""
# cruiseplan/timeline/scheduler.py
def generate_timeline(
cruise: CruiseInstance, legs: list[Leg] | None = None
) -> Timeline: ...
# cruiseplan/timeline/record.py
@dataclass(frozen=True, kw_only=True, slots=True)
class ActivityRecord:
kind: str # station, mooring, line, area, transit, port, buffer
label: str
start_time: datetime # UTC, no zone attached
end_time: datetime
duration_minutes: float # actual (end - start)
planned_duration_minutes: float # from the planning rules
dist_nm: float
vessel_speed_kt: float
water_depth_m: float | None = None
operation_depth_m: float | None = None
delay_start_minutes: float | None = None
# ... more fields; see record.py
Timeline = list[ActivityRecord]
Writers (CSV, HTML, LaTeX, KML, NetCDF, maps) and the forecast take records
and read attributes. record.kind replaces classification by label text.
Deprecations
Renamed YAML keys and API names live in one table each in
cruiseplan/_deprecated.py, with the release that removes them
(REMOVED_IN). The configuration loader (cruiseplan/config/loader.py)
renames old keys before validation and warns once per key per file. A test
fails once the package version reaches REMOVED_IN, and another checks the
migration page against the tables.
Entry/exit point interface
All operation types and organisational levels implement get_entry_point() and
get_exit_point(), returning (latitude, longitude) tuples. This lets the
scheduler calculate transit distances without knowing the operation type:
def calculate_transit_distance(from_entity, to_entity) -> float:
start = from_entity.get_exit_point()
end = to_entity.get_entry_point()
return haversine_distance(start, end)
PointOperation: entry == exit (same location).
LineOperation: entry = first waypoint, exit = last waypoint.
AreaOperation: entry = first corner, exit = last corner.
Leg: entry = departure port, exit = arrival port.
Adding a new operation type
Add a Pydantic definition class in
cruiseplan/config/activities.py(inheritBaseModel).Add a runtime class in
cruiseplan/runtime/operations.py(inheritBaseOperation).Implement
from_pydantic(),get_entry_point(),get_exit_point(),calculate_duration().Add duration logic to
DurationCalculatorincruiseplan/timeline/duration.py.Add the new type to
OperationTypeEnumincruiseplan/config/values.py.
Coordinate input formats
FlexibleLocationModel (in cruiseplan/config/activities.py) normalises multiple
input formats to internal decimal-degree fields:
# Decimal degrees (preferred)
latitude: 60.2440
longitude: -31.3177
# Degrees decimal minutes
latitude_decmin: "60 14.640 N"
longitude_decmin: "031 19.062 W"
Both produce the same latitude/longitude after model_validator runs.
Exceptions
# cruiseplan/config/exceptions.py
class ValidationError(Exception): ... # YAML field validation failures
class FileError(Exception): ... # File I/O problems
class BathymetryError(Exception): ... # Bathymetry data issues
# cruiseplan/config/yaml_io.py
class YAMLIOError(Exception): ... # YAML read/write errors
# cruiseplan/runtime/organizational.py
class ReferenceError(Exception): ... # Unresolved port or activity references
FlexibleLocationModel
FlexibleLocationModel stores latitude and longitude as plain float fields;
latitude_decmin / longitude_decmin are converted to them in a before
model validator. GeoPoint is used only for line routes and area corners.
A legacy position: "lat, lon" string is still accepted and is scheduled for
removal.
Code conventions
ruff check . and ruff format --check . are the CI lint job; the rule set in
pyproject.toml covers numpy docstrings, annotations, import order and Python
3.11 syntax (list[str], T | None).
Docstrings: numpy style on every public function and class, with typed
Parameters,ReturnsandRaisessections. A private helper (leading underscore) has a one-line docstring and a typed signature; a reason the code cannot show goes in a#comment at the line it explains.Logging: library modules log through
logging.getLogger(__name__)and never configure logging (nologging.basicConfig, no handlers) orprint. Thecruiseplancommand line configures logging once. An API function’sverbose=Truesets thecruiseplanlogger to DEBUG for that call only. Log messages are plain text, without emoji. Results meant for the terminal (tables, summaries) are printed by the modules incruiseplan/cli/.
Naming
Public names are spelling-neutral: never a word spelled differently in British
and American English (-ise/-ize, -isation/-ization). Say what the
function makes instead:
Pattern |
Returns |
Example |
|---|---|---|
|
the object converted to another form |
|
|
the one accepted form of a string |
|
noun |
a computed result |
|
Private names follow the same rule; where no neutral word exists the spelling is
American, as in Python and matplotlib (color and gray are never renamed).
Prefer naming the job over finding a synonym (_rename_, _fix_,
_canonical_ rather than _normalize_, _sanitize_). A private helper’s name
says what comes back, with one verb per job:
Verb |
Returns |
|---|---|
|
an object read from a file |
|
a typed value from a string in hand, no I/O |
|
the one value that applies, from several sources by precedence |
|
a display string |
|
rows, a dict or a dataset |
|
an HTML or LaTeX fragment |
|
a matplotlib Figure (public: |
|
a bool |
|
the object after one processing step |
|
the target with fields or attributes added |
noun ( |
a computed result |
Module names say what the module holds or does (scheduler.py,
bathymetry.py, kml_generator.py). Do not add modules named for a grade of
code (*_utils.py, helpers.py, misc.py); the existing *_utils.py modules
are not a pattern to copy.
Testing
Tests write only into tmp_path (or the temp_output_dir fixture): a test run
leaves the repository tree unchanged. Pass an explicit output directory to any
API call that writes files, since the default is data/.
pip install -e ".[test]" # test dependencies only (as in CI)
pytest tests/unit/ # fast unit tests
pytest tests/integration/ # end-to-end workflow tests
pytest -m "not slow" --cov=cruiseplan --cov-fail-under=70 # CI coverage gate
ruff check . && ruff format --check . # CI lint job
Coverage reporting is on by default (addopts in pyproject.toml). CI runs
the tests on Ubuntu with Python 3.11, 3.12 and 3.13, plus macOS and Windows
with Python 3.11.
Test fixtures (realistic YAML configs) live in tests/fixtures/.
Dependencies
Core: Python 3.11+, Pydantic v2, ruamel.yaml, numpy, scipy, xarray, netCDF4, pandas, requests, pangaeapy
Maps: matplotlib (PNG maps and the interactive station picker), folium, geopandas (EEZ overlays)
Testing: pytest, pytest-cov — the
testextra (pip install -e ".[test]")Development: the
testextra plus ruff, mypy, sphinx and notebook tooling — thedevextra (pip install -e ".[dev]")