Timeline & Scheduling

Scheduling algorithms and timeline generation for cruise planning.

cruiseplan.timeline package.

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

  • distance: Geographic distance calculations using Haversine formula

  • duration: Time duration calculations for cruise operations and activities

  • routing: Route optimization and spatial planning algorithms

  • scheduler: Core scheduling logic for generating cruise timelines

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

cruiseplan.timeline.generate_timeline(cruise, legs: list[Any] | None = None) → list[dict[str, Any]][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.core.cruise.CruiseInstance) – CruiseInstance object with enhanced data

  • legs (Optional[List[Any]]) – Runtime legs (if None, will be created from config)

Returns:

Timeline activities as dictionaries

Return type:

List[Dict[str, Any]]

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

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.routing module

Route optimization and spatial planning algorithms.

This module provides algorithms for optimizing cruise routes and spatial planning. Currently implements placeholder functions for composite route optimization that will eventually solve constrained Traveling Salesman Problems (TSP).

cruiseplan.timeline.routing.calculate_route_distance(start_point, end_point) → float[source]

Placeholder for Haversine/geodesic distance calculation.

Parameters:

  • start_point (Any) – Starting point coordinates.

  • end_point (Any) – Ending point coordinates.

Returns:

Distance between points (currently returns 0.0).

Return type:

float

cruiseplan.timeline.routing.optimize_composite_route(children: list[BaseOperation], rules: Any) → float[source]

Calculate total duration for operations within a Cluster.

This function should eventually solve a Constrained Traveling Salesman Problem (TSP) to optimize the order and routing of operations. For now, it returns the simple sum of the children’s durations.

Parameters:

  • children (list of BaseOperation) – List of child operations to optimize.

  • rules (Any) – Operational rules and constraints for optimization.

Returns:

Total duration in minutes for all operations.

Return type:

float

Notes

Phase 1 implementation: Simple sum of durations, ignoring routing complexity. Actual TSP/routing logic will be added in a later phase.

cruiseplan.timeline.scheduler module

Clean scheduler implementation with unified operations model.

This module implements the new scheduler architecture from CLAUDE-v0.3.1-scheduler-fix.md with a focus on: - Everything as operations with entry/exit coordinates - Clear separation between operations (science) and navigational transits (connections) - Consistent coordinate system for accurate distance calculations - Simplified, maintainable code (~500 lines vs 2000+ lines)

class cruiseplan.timeline.scheduler.ActivityRecord(data: dict[str, Any])[source]

Bases: object

Standardized activity record for timeline output.

__init__(data: dict[str, Any])[source]

Initialize from dictionary for compatibility with old system.

action: str | None = None
activity: str
dist_nm: float
duration_minutes: float
end_time: datetime
entry_lat: float
entry_lon: float
exit_lat: float
exit_lon: float
label: str
leg_name: str
op_type: str
operation_class: str
operation_depth: float | None = None
start_time: datetime
to_dict() → dict[str, Any][source]

Convert to dictionary for output compatibility.

Maps ActivityRecord fields to legacy dictionary format expected by output generators.

vessel_speed_kt: float
water_depth: float | None = None
class cruiseplan.timeline.scheduler.NavigationalTransit(from_op: BaseOperation, to_op: BaseOperation, config: CruiseConfig, leg_name: str, vessel_speed: float | None = None)[source]

Bases: BaseOperation

Pure navigational connection between operations.

calculate_duration(rules: Any) → float[source]

Calculate based on transit distance and vessel speed.

get_entry_point() → tuple[float, float][source]

Transit starts where previous operation ended.

get_exit_point() → tuple[float, float][source]

Transit ends where next operation begins.

get_operation_distance_nm() → float[source]

Calculate straight-line distance between operations.

get_operation_type() → str[source]

Override default to return specific transit type.

get_vessel_speed() → float[source]

Get vessel speed (leg-specific or default).

class cruiseplan.timeline.scheduler.OperationCoordinates(entry: GeoPoint, exit: GeoPoint)[source]

Bases: object

Unified coordinate representation for all operations.

__post_init__()[source]

Validate coordinates.

entry: GeoPoint
exit: GeoPoint
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[Any] | None = None) → list[dict[str, Any]][source]

Generate complete cruise timeline.

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

Calculate summary statistics for cruise timeline activities.

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

Parameters:

timeline (List[Dict[str, Any]]) – List of activity records from the scheduler.

Returns:

Dictionary containing statistics for each activity type with keys: ‘stations’, ‘surveys’, ‘areas’, ‘moorings’, ‘within_area_transits’, ‘port_transits’, and raw activity lists.

Return type:

Dict[str, Any]

cruiseplan.timeline.scheduler.generate_cruise_schedule(config_path: str, output_dir: str = 'data', formats: list[str] | None = None, validate_depths: bool = False, selected_leg: str | None = None, derive_netcdf: bool = False, bathy_source: str = 'etopo2022', bathy_dir: str = 'data', bathy_stride: int = 10, figsize: list[float] | None = None, output_basename: str | None = None) → dict[str, Any][source]

Generate cruise schedule (backward compatibility function).

Parameters:

  • config_path (str) – Path to configuration file

  • output_dir (str) – Output directory for generated files

  • formats (Optional[List[str]]) – Output formats to generate

  • validate_depths (bool) – Whether to validate depths

  • selected_leg (Optional[str]) – Specific leg to process (if None, process all legs)

  • derive_netcdf (bool) – Whether to generate NetCDF output

  • bathy_source (str) – Bathymetry data source

  • bathy_dir (str) – Bathymetry data directory

  • bathy_stride (int) – Bathymetry stride for maps

  • figsize (Optional[List[float]]) – Figure size for maps

  • output_basename (Optional[str]) – Base name for output files

Returns:

Schedule data with timeline and summary information

Return type:

Dict[str, Any]

cruiseplan.timeline.scheduler.generate_timeline(cruise, legs: list[Any] | None = None) → list[dict[str, Any]][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.core.cruise.CruiseInstance) – CruiseInstance object with enhanced data

  • legs (Optional[List[Any]]) – Runtime legs (if None, will be created from config)

Returns:

Timeline activities as dictionaries

Return type:

List[Dict[str, Any]]