Timeline & Scheduling

Scheduling algorithms and timeline generation for cruise planning.

cruiseplan.timeline package.

This package contains scheduling and timeline generation modules for cruise planning:

  • record: the timeline record (ActivityRecord) and Timeline

  • distance: Geographic distance calculations using Haversine formula

  • duration: Time duration calculations for cruise operations and activities

  • scheduler: Core scheduling logic for generating cruise timelines

These modules provide the mathematical and algorithmic foundation for determining distances, durations and scheduling sequences in oceanographic cruises.

cruiseplan.timeline.record module

The timeline record: one scheduled activity, and the timeline type.

Every stage after the scheduler works from ActivityRecord: the writers (CSV, HTML, LaTeX, KML, NetCDF, maps) and the forecast, which reads records back from the NetCDF schedule.

cruiseplan.timeline.record.ActivityKind

a point operation (station or mooring), a line, an area, a navigational transit, a port call, a contingency buffer or waiting before an operation (its positive delay_start_minutes).

Type:

What a record is

alias of Literal[‘station’, ‘mooring’, ‘line’, ‘area’, ‘transit’, ‘port’, ‘buffer’, ‘wait’]

class cruiseplan.timeline.record.ActivityRecord(*, kind: Literal['station', 'mooring', 'line', 'area', 'transit', 'port', 'buffer', 'wait'], activity: str, label: str, leg_name: str, op_type: str, operation_class: str, entry_lat: float, entry_lon: float, exit_lat: float, exit_lon: float, start_time: datetime, end_time: datetime, duration_minutes: float, planned_duration_minutes: float, dist_nm: float, vessel_speed_kt: float, action: str | None = None, operation_depth_m: float | None = None, water_depth_m: float | None = None, delay_start_minutes: float | None = None, comment: str | None = None, duration_is_fill: bool = False, transit_dist_nm: float | None = None)[source]

Bases: object

One scheduled activity of a cruise timeline.

Records are immutable: a change (for example an operation that ended early) makes a new record with replace().

Parameters:
  • kind (str) – One of KINDS.

  • activity (str) – Display type: Station, Mooring, Port, Waypoint, Line, Area, Transit or Buffer.

  • label (str) – Name shown in outputs.

  • leg_name (str) – Name of the leg the activity belongs to.

  • op_type (str) – Operation type (CTD, mooring, port, transit, …).

  • operation_class (str) – Implementation class the record was made from.

  • entry_lat (float) – Where the activity starts, in decimal degrees.

  • entry_lon (float) – Where the activity starts, in decimal degrees.

  • exit_lat (float) – Where the activity ends, in decimal degrees.

  • exit_lon (float) – Where the activity ends, in decimal degrees.

  • start_time (datetime) – Start and end (UTC, no time zone attached).

  • end_time (datetime) – Start and end (UTC, no time zone attached).

  • duration_minutes (float) – Actual duration: end_time - start_time.

  • planned_duration_minutes (float) – Duration from the planning rules, before delays of the next operation.

  • dist_nm (float) – Distance covered by the activity in nautical miles.

  • vessel_speed_kt (float) – Vessel speed in knots.

  • action (str or None) – Action (profile, deployment, mob, …).

  • operation_depth_m (float or None) – Target depth of the operation in meters.

  • water_depth_m (float or None) – Water depth at the location in meters.

  • delay_start_minutes (float or None) – The operation’s own delay in minutes as configured: positive, a wait record just before it; negative, taken off the transit into it, then the operation before. None for transits, buffers and waits.

  • comment (str or None) – Comment from the configuration.

  • duration_is_fill (bool) – True when the duration is the fill value.

  • transit_dist_nm (float or None) – Distance to the next waypoint in nautical miles, where known.

__getitem__(key: str) → object[source]

Return the attribute for a dictionary key, with a deprecation warning.

__post_init__() → None[source]

Check the kind.

property category: str

from KIND_CATEGORY, other for a waypoint.

Type:

NetCDF category

property depth_m: float | None

Operation depth if given, otherwise water depth, otherwise None.

property is_science: bool

True for scientific operations (stations, moorings, lines, areas).

property is_waypoint: bool

True for a navigational waypoint (a point record that is not work).

replace(**changes: object) → ActivityRecord[source]

Return a copy with the given fields changed.

Parameters:

**changes (object) – Field names and their new values.

Returns:

The new record.

Return type:

ActivityRecord

to_dict() → dict[str, object][source]

Return the record as a plain dictionary of its fields.

Returns:

Field name to value.

Return type:

dict

cruiseplan.timeline.record.KIND_CATEGORY = {'area': 'area_operation', 'buffer': 'other', 'line': 'line_operation', 'mooring': 'point_operation', 'port': 'point_operation', 'station': 'point_operation', 'transit': 'transit', 'wait': 'other'}

NetCDF category of each kind (a waypoint is other).

cruiseplan.timeline.record.KIND_OPERATION_CLASS = {'area': 'AreaOperation', 'buffer': 'Buffer', 'line': 'LineOperation', 'mooring': 'PointOperation', 'port': 'PointOperation', 'station': 'PointOperation', 'transit': 'NavigationalTransit', 'wait': 'Waiting'}

Implementation class of each kind (operation_class on records).

cruiseplan.timeline.record.SCIENCE_KINDS = frozenset({'area', 'line', 'mooring', 'station'})

Kinds that count as scientific operations.

cruiseplan.timeline.record.Timeline

records in schedule order.

Type:

A cruise timeline

alias of list[ActivityRecord]

cruiseplan.timeline.record.kind_of(operation_class: str, op_type: str | None) → str[source]

Return the record kind for an operation class and operation type.

Parameters:
  • operation_class (str) – Implementation class name: PointOperation, LineOperation, AreaOperation, NavigationalTransit, Buffer or Waiting.

  • op_type (str or None) – Operation type from the configuration (CTD, mooring, port, …).

Returns:

One of KINDS.

Return type:

str

Raises:

ValueError – If the operation class is not known.

cruiseplan.timeline.distance module

Geographic distance calculations for cruise planning.

This module provides functions for calculating distances between geographic points using the Haversine formula, which gives Great Circle distances on a spherical Earth. Includes utilities for route distance calculation and unit conversions between kilometers and nautical miles.

cruiseplan.timeline.distance.haversine_distance(start: GeoPoint | tuple[float, float], end: GeoPoint | tuple[float, float]) → float[source]

Calculate Great Circle distance between two points using Haversine formula.

Parameters:
  • start (GeoPoint or tuple of float) – Starting point coordinates.

  • end (GeoPoint or tuple of float) – Ending point coordinates.

Returns:

Distance in kilometers.

Return type:

float

cruiseplan.timeline.distance.route_distance(points: list[GeoPoint | tuple[float, float]]) → float[source]

Calculate total distance of a path connecting multiple points.

Parameters:

points (list of GeoPoint or tuple of float) – Ordered list of points defining the route.

Returns:

Total route distance in kilometers.

Return type:

float

cruiseplan.timeline.distance.to_coords(point: GeoPoint | tuple[float, float]) → tuple[float, float][source]

Extract (latitude, longitude) coordinates from various input types.

Parameters:

point (GeoPoint or tuple of float) – Input point as either a GeoPoint object or (lat, lon) tuple.

Returns:

(latitude, longitude) coordinates in decimal degrees.

Return type:

tuple of float

cruiseplan.timeline.duration module

Duration calculations for cruise operations and activities.

This module provides time duration calculations for various cruise operations including CTD profiling, vessel transit, and operational constraints based on day/night windows. Uses configuration parameters for vessel speeds and CTD rates.

class cruiseplan.timeline.duration.DurationCalculator(config: CruiseConfig, turnaround_time_minutes: float | None = None)[source]

Bases: object

Calculates time durations for cruise operations and activities.

This class provides methods to calculate operation durations based on cruise configuration parameters including vessel speeds, CTD rates, and operational time windows.

config

Cruise configuration object containing operational parameters.

Type:

CruiseConfig

turnaround_time_minutes

Turnaround added to each CTD cast: the leg value when given, else the cruise value.

Type:

float

day_start_hour

Hour when daytime operations begin (0-23).

Type:

int

day_end_hour

Hour when daytime operations end (0-23).

Type:

int

calculate_ctd_time(depth: float) → float[source]

Calculate CTD profiling duration including descent, ascent, and turnaround.

Parameters:

depth (float) – Water depth in meters.

Returns:

Total duration in minutes.

Return type:

float

Notes

Formula: (Depth / Descent) + (Depth / Ascent) + Turnaround

calculate_transit_time(distance_km: float, speed_knots: float | None = None) → float[source]

Calculate vessel transit duration based on distance and speed.

Parameters:
  • distance_km (float) – Distance to travel in kilometers.

  • speed_knots (float, optional) – Vessel speed in knots. If None, uses config default.

Returns:

Transit duration in minutes.

Return type:

float

calculate_wait_time(arrival_dt: datetime, duration_minutes: float, required_window: Literal['day', 'night'] | None = None) → float[source]

Calculate wait time to align operations with day/night windows.

Parameters:
  • arrival_dt (datetime) – Arrival time at the operation location.

  • duration_minutes (float) – Duration of the operation in minutes.

  • required_window ({"day", "night"}, optional) – Required time window for the operation.

Returns:

Wait time in minutes before operation can begin.

Return type:

float

cruiseplan.timeline.scheduler module

Clean scheduler implementation with unified operations model.

The scheduler treats every activity as an operation with entry and exit coordinates: - Operations (science) are kept separate from navigational transits (connections) - All distances are computed in one coordinate system

class cruiseplan.timeline.scheduler.OperationFactory(config: CruiseConfig)[source]

Bases: object

Factory for creating operation objects from configuration data.

create_operation(name: str, leg_name: str) → BaseOperation[source]

Create operation from configuration using catalog-based type detection.

class cruiseplan.timeline.scheduler.TimelineGenerator(config: CruiseConfig)[source]

Bases: object

Generates cruise timeline from operations and legs.

generate_timeline(legs: list[Leg] | None = None) → list[ActivityRecord][source]

Generate the cruise timeline.

Parameters:

legs (list of Leg, optional) – Runtime legs; built from the configuration when not given.

Returns:

Records in schedule order.

Return type:

Timeline

cruiseplan.timeline.scheduler.apply_delays(timeline: list[ActivityRecord], leg_delays: Mapping[str, float] | None = None, first_leg: str | None = None, insert_waits: bool = True) → list[ActivityRecord][source]

Apply each operation’s delay_start_minutes.

A positive delay is waiting before the operation starts (for weather, a daylight start, …). It becomes its own wait record at the operation’s position, just before it, so no other record gets longer.

A negative delay means the operation started earlier than planned. The time comes out of the transit into the operation first (it was faster), then, if the delay is longer than that transit, out of the operation before it (it ended early). An actual duration never goes below zero; the part that cannot be absorbed is dropped, with a warning that says how to start the leg earlier when the leg start is reached. A negative delay is a quick fix and always warns: setting transit_minutes or duration_minutes on the record that was actually shorter states what happened.

planned_duration_minutes keeps the plan; duration_minutes is the actual duration. Within a leg every record starts where the one before it ends; between legs the leg delay is kept.

Parameters:
  • timeline (Timeline) – Records in schedule order, before delays are applied.

  • leg_delays (Mapping of str to float, optional) – Leg-level delay_start_minutes by leg name, used in the warning. When not given, it is taken from the gap before the leg.

  • first_leg (str, optional) – Name of the cruise’s first leg, used in the warning. When not given, the leg of the first record is taken as the first leg.

  • insert_waits (bool, optional) – Add a wait record for each positive delay (default). With False the wait is left as a gap before the operation, which keeps the record count (used for schedules read from older files).

Returns:

A new list with actual durations and times.

Return type:

Timeline

cruiseplan.timeline.scheduler.calculate_timeline_statistics(timeline: list[ActivityRecord]) → dict[str, Any][source]

Calculate summary statistics for cruise timeline activities.

Groups records into scientific operations (stations, surveys, areas) and supporting operations (transits, ports) for summary reporting.

Parameters:

timeline (Timeline) – Records from the scheduler.

Returns:

Statistics for each activity type with keys ‘stations’, ‘surveys’, ‘areas’, ‘moorings’, ‘within_area_transits’, ‘port_transits’, the per-leg counts, and the grouped record lists.

Return type:

dict

cruiseplan.timeline.scheduler.fill_duration_summary(timeline: list[ActivityRecord]) → str | None[source]

Return a one-line summary of operations scheduled at the fill duration.

Names how many operations use the fill duration and the schedule total with those operations excluded, so the inflated fill hours do not hide the real total.

Parameters:

timeline (Timeline) – Records making up the schedule.

Returns:

The summary line, or None when no operation uses the fill duration.

Return type:

str or None

cruiseplan.timeline.scheduler.generate_timeline(cruise: CruiseInstance, legs: list[Leg] | None = None) → list[ActivityRecord][source]

Generate cruise timeline directly from CruiseInstance object.

This function eliminates the need for YAML serialization/deserialization by working directly with the CruiseInstance object’s validated configuration.

Parameters:
Returns:

Records in schedule order.

Return type:

Timeline

cruiseplan.timeline.scheduler.timeline_minutes(timeline: list[ActivityRecord]) → float[source]

Return the elapsed time of a timeline: last end minus first start.

Waiting from a positive delay_start_minutes lies between records, so this total includes it where a sum of durations would not.

Parameters:

timeline (Timeline) – Records in schedule order.

Returns:

Minutes from the first start to the last end (0 for an empty timeline).

Return type:

float