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) andTimelinedistance: Geographic distance calculations using Haversine formuladuration: Time duration calculations for cruise operations and activitiesscheduler: 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:
objectOne 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,TransitorBuffer.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.
- property category: str
from
KIND_CATEGORY,otherfor 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:
- 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
categoryof each kind (a waypoint isother).
- 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_classon 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,BufferorWaiting.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:
objectCalculates 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:
objectFactory 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:
objectGenerates cruise timeline from operations and legs.
- 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
waitrecord 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_minutesorduration_minuteson the record that was actually shorter states what happened.planned_duration_minuteskeeps the plan;duration_minutesis 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_minutesby 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
waitrecord 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:
- 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:
cruise (cruiseplan.runtime.cruise.CruiseInstance) – CruiseInstance object with enhanced data
legs (Optional[List[Any]]) – Runtime legs (if None, will be created from config)
- Returns:
Records in schedule order.
- Return type:
- 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_minuteslies 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