"""
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
"""
import logging
from collections.abc import Mapping
from dataclasses import dataclass
from datetime import datetime, timedelta
from typing import TYPE_CHECKING, Any
from cruiseplan.config.activities import (
AreaDefinition,
LineDefinition,
PointDefinition,
)
from cruiseplan.config.cruise_config import ClusterDefinition, CruiseConfig
from cruiseplan.config.values import DEFAULT_MOORING_DURATION_MIN
from cruiseplan.runtime.operations import (
AreaOperation,
BaseOperation,
LineOperation,
NavigationalTransit,
PointOperation,
)
from cruiseplan.timeline.record import ActivityRecord, Timeline, kind_of
if TYPE_CHECKING:
from cruiseplan.runtime.cruise import CruiseInstance
from cruiseplan.runtime.organizational import Cluster, Leg
logger = logging.getLogger(__name__)
__all__ = [
"OperationFactory",
"apply_delays",
"TimelineGenerator",
"calculate_timeline_statistics",
"fill_duration_summary",
"generate_timeline",
"timeline_minutes",
]
def __getattr__(name: str) -> object:
"""Resolve deprecated names (CruiseSchedule) with a warning."""
from cruiseplan import _deprecated
return _deprecated.module_getattr(__name__, name, {"CruiseSchedule": Timeline})
# =============================================================================
# Operation Factory
# =============================================================================
[docs]
class OperationFactory:
"""Factory for creating operation objects from configuration data."""
def __init__(self, config: CruiseConfig) -> None:
self.config = config
[docs]
def create_operation(self, name: str, leg_name: str) -> BaseOperation: # noqa: ARG002 - public signature; leg_name not used yet
"""Create operation from configuration using catalog-based type detection."""
# Check each catalog to find the operation
catalog_checks = [
("points", "point"),
("ports", "point"),
("lines", "line"),
("areas", "area"),
]
for catalog_name, operation_type in catalog_checks:
catalog = getattr(self.config, catalog_name, None)
if not catalog:
continue
for item in catalog:
if item.name == name:
# Use appropriate factory based on operation type
if operation_type == "point":
# Special handling for ports which use PortDefinition instead of StationDefinition
if catalog_name == "ports":
return PointOperation.from_port(item)
return PointOperation.from_pydantic(item)
if operation_type == "line":
return LineOperation.from_pydantic(
item, self.config.default_vessel_speed_kt
)
if operation_type == "area":
return AreaOperation.from_pydantic(item)
# Fallback: Try to resolve from global ports registry
try:
from cruiseplan.config.ports import resolve_port_reference
port_def = resolve_port_reference(name)
return PointOperation.from_port(port_def)
except ValueError:
pass
raise ValueError(f"Could not resolve operation: {name}")
# =============================================================================
# Statistics Calculator
# =============================================================================
def _categorize_activities(timeline: Timeline) -> dict[str, list]:
"""Group records into the statistics categories by kind and transit direction."""
groups: dict[str, list] = {
"station_activities": [],
"mooring_activities": [],
"area_activities": [],
"scientific_transits": [],
"port_activities": [],
"port_transits_to_area": [],
"port_transits_from_area": [],
"within_area_transits": [],
}
by_kind = {
"station": "station_activities",
"mooring": "mooring_activities",
"port": "port_activities",
"line": "scientific_transits",
"area": "area_activities",
}
for i, record in enumerate(timeline):
if record.kind in by_kind:
groups[by_kind[record.kind]].append(record)
logger.info(f" Adding to {by_kind[record.kind]}: {record.label}")
elif record.kind == "transit":
is_from_port, is_to_port = _check_transit_direction(timeline, i)
if is_from_port:
groups["port_transits_to_area"].append(record)
elif is_to_port:
groups["port_transits_from_area"].append(record)
else:
groups["within_area_transits"].append(record)
# Buffers (contingency) and waits are in no group
return groups
def _check_transit_direction(timeline: Timeline, index: int) -> tuple[bool, bool]:
"""Return (from port, to port) for the transit at *index*."""
is_from_port = index > 0 and timeline[index - 1].kind == "port"
after = index + 1
# A wait before the arrival port is at the port
while after < len(timeline) and timeline[after].kind == "wait":
after += 1
is_to_port = after < len(timeline) and timeline[after].kind == "port"
return is_from_port, is_to_port
[docs]
def timeline_minutes(timeline: Timeline) -> float:
"""
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
-------
float
Minutes from the first start to the last end (0 for an empty timeline).
"""
if not timeline:
return 0.0
end = max(record.end_time for record in timeline)
return (end - timeline[0].start_time).total_seconds() / 60.0
[docs]
def fill_duration_summary(timeline: Timeline) -> str | None:
"""
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
-------
str or None
The summary line, or None when no operation uses the fill duration.
"""
from cruiseplan.utils.units import hours_to_days
filled = [r for r in timeline if r.duration_is_fill]
if not filled:
return None
fill_hours = DEFAULT_MOORING_DURATION_MIN / 60
real_minutes = sum(r.duration_minutes for r in timeline if not r.duration_is_fill)
real_days = hours_to_days(real_minutes / 60)
return (
f"{len(filled)} operation(s) at the fill duration "
f"({len(filled)} x {fill_hours:.0f} h); schedule total excluding fills: "
f"{real_days:.1f} days"
)
def _calculate_transit_stats(transits: Timeline) -> dict[str, float]:
"""Count, duration, distance and mean speed of transit records."""
from cruiseplan.utils.units import hours_to_days
if not transits:
return {
"count": 0,
"total_duration_h": 0,
"total_duration_days": 0,
"total_distance_nm": 0,
"avg_speed_kt": 0,
}
total_duration_h = sum(r.duration_minutes for r in transits) / 60.0
total_distance_nm = sum(r.dist_nm for r in transits)
avg_speed_kt = total_distance_nm / total_duration_h if total_duration_h > 0 else 0
return {
"count": len(transits),
"total_duration_h": total_duration_h,
"total_duration_days": hours_to_days(total_duration_h),
"total_distance_nm": total_distance_nm,
"avg_speed_kt": avg_speed_kt,
}
def _log_debug_counts(
categorized: dict[str, list], leg_stats: dict[str, dict[str, int]]
) -> None:
"""Log debug information about operation counts."""
station_activities = categorized["station_activities"]
mooring_activities = categorized["mooring_activities"]
scientific_transits = categorized["scientific_transits"]
area_activities = categorized["area_activities"]
port_activities = categorized["port_activities"]
within_area_transits = categorized["within_area_transits"]
total_scientific_operations = (
len(station_activities)
+ len(mooring_activities)
+ len(scientific_transits)
+ len(area_activities)
)
logger.info("Cruise-level operation counts:")
logger.info(f" Stations: {len(station_activities)}")
logger.info(f" Moorings: {len(mooring_activities)}")
logger.info(f" Scientific transits (surveys): {len(scientific_transits)}")
logger.info(f" Area operations: {len(area_activities)}")
logger.info(f" Total scientific operations: {total_scientific_operations}")
logger.info(f" Port activities: {len(port_activities)}")
logger.info(f" Within-area transits: {len(within_area_transits)}")
for leg_name, stats in leg_stats.items():
logger.info(f"Leg '{leg_name}' operation counts:")
logger.info(f" Stations: {stats['stations']}")
logger.info(f" Moorings: {stats['moorings']}")
logger.info(f" Surveys: {stats['surveys']}")
logger.info(f" Areas: {stats['areas']}")
logger.info(f" Total scientific operations: {stats['total_scientific']}")
logger.info(f" Total activities in leg: {stats['total_activities']}")
def _calculate_leg_statistics(timeline: Timeline) -> dict[str, dict[str, int]]:
"""Operation counts per leg."""
counter = {
"station": "stations",
"mooring": "moorings",
"line": "surveys",
"area": "areas",
}
leg_stats: dict[str, dict[str, int]] = {}
for record in timeline:
stats = leg_stats.setdefault(
record.leg_name,
{
"stations": 0,
"moorings": 0,
"surveys": 0,
"areas": 0,
"total_scientific": 0,
"ports": 0,
"transits": 0,
"total_activities": 0,
},
)
stats["total_activities"] += 1
if record.kind == "port":
stats["ports"] += 1
elif record.kind == "transit":
stats["transits"] += 1
elif record.is_science:
stats["total_scientific"] += 1
stats[counter[record.kind]] += 1
return leg_stats
[docs]
def calculate_timeline_statistics(timeline: Timeline) -> dict[str, Any]:
"""
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
-------
dict
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.
"""
from cruiseplan.utils.units import hours_to_days
categorized = _categorize_activities(timeline)
def calc_stats(
activities: Timeline,
include_distance: bool = False,
include_depth: bool = False,
) -> dict[str, float]:
if not activities:
stats = {
"count": 0,
"avg_duration_h": 0,
"total_duration_h": 0,
"total_duration_days": 0,
}
if include_distance:
stats.update({"avg_distance_nm": 0, "total_distance_nm": 0})
if include_depth:
stats.update({"avg_depth_m": 0})
return stats
total_duration_h = sum(r.duration_minutes for r in activities) / 60.0
stats = {
"count": len(activities),
"avg_duration_h": total_duration_h / len(activities),
"total_duration_h": total_duration_h,
"total_duration_days": hours_to_days(total_duration_h),
}
if include_distance:
total_distance_nm = sum(r.dist_nm for r in activities)
stats.update(
{
"avg_distance_nm": total_distance_nm / len(activities),
"total_distance_nm": total_distance_nm,
}
)
if include_depth:
depths = [r.depth_m for r in activities if r.depth_m is not None]
stats.update({"avg_depth_m": sum(depths) / len(depths) if depths else 0.0})
return stats
station_activities = categorized["station_activities"]
mooring_activities = categorized["mooring_activities"]
area_activities = categorized["area_activities"]
scientific_transits = categorized["scientific_transits"]
port_activities = categorized["port_activities"]
port_transits_to_area = categorized["port_transits_to_area"]
port_transits_from_area = categorized["port_transits_from_area"]
within_area_transits = categorized["within_area_transits"]
leg_stats = _calculate_leg_statistics(timeline)
_log_debug_counts(categorized, leg_stats)
return {
"stations": calc_stats(station_activities, include_depth=True),
"moorings": calc_stats(mooring_activities),
"surveys": calc_stats(scientific_transits, include_distance=True),
"areas": calc_stats(area_activities),
"within_area_transits": _calculate_transit_stats(within_area_transits),
"port_transits_to_area": _calculate_transit_stats(port_transits_to_area),
"port_transits_from_area": _calculate_transit_stats(port_transits_from_area),
"port_activities": calc_stats(port_activities),
"leg_stats": leg_stats,
"total_scientific": sum(s["total_scientific"] for s in leg_stats.values()),
"station_activities": station_activities,
"mooring_activities": mooring_activities,
"scientific_transits": scientific_transits,
"area_activities": area_activities,
"within_area_transits_activities": within_area_transits,
"port_transits_to_area_activities": port_transits_to_area,
"port_transits_from_area_activities": port_transits_from_area,
"port_activities_raw": port_activities,
}
# =============================================================================
# Timeline Generator
# =============================================================================
@dataclass(frozen=True)
class _Rules:
"""Duration rules for one operation: the cruise config and the leg's values."""
config: CruiseConfig
turnaround_time_minutes: float | None = None
_NOT_OPERATIONS = frozenset({"transit", "buffer", "wait"})
[docs]
def apply_delays(
timeline: Timeline,
leg_delays: Mapping[str, float] | None = None,
first_leg: str | None = None,
insert_waits: bool = True,
) -> Timeline:
"""
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
-------
Timeline
A new list with actual durations and times.
"""
if not timeline:
return []
actual = [r.duration_minutes for r in timeline]
first_of_leg = [
i == 0 or timeline[i].leg_name != timeline[i - 1].leg_name
for i in range(len(timeline))
]
wait_before = [0.0] * len(timeline)
# Minutes a negative delay on a leg's first record would move it earlier
undo = [0.0] * len(timeline)
leg_start = 0
for i, record in enumerate(timeline):
if first_of_leg[i]:
leg_start = i
if record.kind in _NOT_OPERATIONS:
continue
delay = record.delay_start_minutes or 0.0
if delay > 0 and not first_of_leg[i]:
wait_before[i] = delay
elif delay < 0 and first_of_leg[i]:
undo[i] = -delay
_warn_leg_start(
timeline, leg_start, record.label, -delay, leg_delays, first_leg
)
elif delay < 0:
_shorten_before(
timeline, actual, i, leg_start, -delay, leg_delays, first_leg
)
out: Timeline = []
for i, record in enumerate(timeline):
planned_start = record.start_time + timedelta(minutes=undo[i])
if i == 0:
start = planned_start
elif first_of_leg[i]:
# leg delay (and a departure-port delay) between legs is kept
gap = planned_start - timeline[i - 1].end_time
start = out[-1].end_time + max(gap, timedelta(0))
else:
start = out[-1].end_time
if wait_before[i]:
wait = _wait_record(record, start, wait_before[i])
if insert_waits:
out.append(wait)
start = wait.end_time
out.append(_with_actual(record, start, actual[i]))
return out
def _shorten_before(
timeline: Timeline,
actual: list[float],
index: int,
leg_start: int,
minutes: float,
leg_delays: Mapping[str, float] | None,
first_leg: str | None,
) -> None:
"""Take *minutes* (a negative delay) from the transit, then the operation, before *index*."""
record = timeline[index]
shortened = []
left = minutes
j = index - 1
walked_transit = False
# The transit into the operation, then the operation before that
while left > 0 and j >= leg_start:
kind = timeline[j].kind
walked_transit = walked_transit or kind == "transit"
if kind == "transit" or kind not in _NOT_OPERATIONS:
taken = min(actual[j], left)
if taken > 0:
actual[j] -= taken
left -= taken
shortened.append(f"{timeline[j].label} by {taken:.1f} min")
if kind != "transit":
break
j -= 1
logger.warning(
f"Operation {record.label}: negative delay_start_minutes "
f"{-minutes:g} is a quick fix; it shortened "
f"{', '.join(shortened) or 'nothing'}. Set transit_minutes or "
f"duration_minutes on the record that was actually shorter instead."
)
if left <= 0:
return
if j < leg_start or j == leg_start:
_warn_leg_start(timeline, leg_start, record.label, left, leg_delays, first_leg)
else:
at_zero = f"{timeline[j].label} is"
if walked_transit:
at_zero = f"the transit and {timeline[j].label} are"
logger.warning(
f"Operation {record.label}: {left:.1f} min of its negative "
f"delay_start_minutes could not be absorbed ({at_zero} at 0 min)"
)
def _wait_record(
record: ActivityRecord, start: datetime, minutes: float
) -> ActivityRecord:
"""Return a wait of *minutes* at *record*'s position before it starts."""
return ActivityRecord(
kind="wait",
activity="Waiting",
label=f"Waiting before {record.label}",
entry_lat=record.entry_lat,
entry_lon=record.entry_lon,
exit_lat=record.entry_lat,
exit_lon=record.entry_lon,
start_time=start,
end_time=start + timedelta(minutes=minutes),
duration_minutes=minutes,
planned_duration_minutes=0.0,
dist_nm=0.0,
vessel_speed_kt=0.0,
leg_name=record.leg_name,
op_type="wait",
operation_class="Waiting",
water_depth_m=record.water_depth_m,
comment=f"delay_start_minutes of {record.label}",
)
def _with_actual(
record: ActivityRecord, start: datetime, minutes: float
) -> ActivityRecord:
"""Return *record* starting at *start* with actual duration *minutes*."""
changes: dict[str, object] = {
"start_time": start,
"end_time": start + timedelta(minutes=minutes),
"duration_minutes": minutes,
}
if record.kind == "transit" and minutes != record.duration_minutes:
# The speed it was actually run at (none for 0 min)
changes["vessel_speed_kt"] = (
record.dist_nm / (minutes / 60.0) if minutes > 0 else float("nan")
)
return record.replace(**changes)
def _warn_leg_start(
timeline: Timeline,
leg_start: int,
label: str,
minutes: float,
leg_delays: Mapping[str, float] | None,
first_leg: str | None = None,
) -> None:
"""Warn that a negative delay at the start of a leg is not absorbed."""
leg = timeline[leg_start].leg_name
is_first = leg == first_leg if first_leg is not None else leg_start == 0
if is_first:
lever = (
f"start the cruise {minutes:.1f} min earlier (cruise start_date / "
f"start_time)"
)
else:
if leg_delays is not None:
leg_delay = leg_delays.get(leg, 0.0) or 0.0
elif leg_start > 0:
gap = timeline[leg_start].start_time - timeline[leg_start - 1].end_time
leg_delay = max(gap.total_seconds() / 60.0, 0.0)
else:
leg_delay = 0.0
previous = (
f"the previous leg ({timeline[leg_start - 1].leg_name})"
if leg_start > 0
else "the previous leg"
)
from_delay = min(leg_delay, minutes)
rest = minutes - from_delay
parts = []
if from_delay > 0:
parts.append(
f"reduce the delay_start_minutes of leg {leg} "
f"({leg_delay:g} min) by {from_delay:.1f} min"
)
if rest > 0:
parts.append(f"end {previous} {rest:.1f} min earlier")
lever = " and ".join(parts)
logger.warning(
f"Operation {label}: {minutes:.1f} min of its negative delay_start_minutes "
f"in leg {leg} could not be absorbed; nothing earlier in the leg is long "
f"enough. To start leg {leg} earlier, {lever}"
)
[docs]
class TimelineGenerator:
"""Generates cruise timeline from operations and legs."""
def __init__(self, config: CruiseConfig) -> None:
self.config = config
self.factory = OperationFactory(config)
self.current_time = self._parse_start_datetime()
# Operation label -> why it was scheduled with the fill duration
self._fill_reasons: dict[str, str] = {}
[docs]
def generate_timeline(self, legs: list["Leg"] | None = None) -> Timeline:
"""
Generate the cruise timeline.
Parameters
----------
legs : list of Leg, optional
Runtime legs; built from the configuration when not given.
Returns
-------
Timeline
Records in schedule order.
"""
if legs is None:
legs = self._create_runtime_legs()
timeline = []
self._fill_reasons = {}
for leg in legs:
leg_activities = self._process_leg(leg)
timeline.extend(leg_activities)
config_legs = self.config.legs or []
timeline = apply_delays(
timeline,
{leg.name: getattr(leg, "delay_start", None) or 0.0 for leg in legs},
first_leg=config_legs[0].name if config_legs else None,
)
for name, reason in self._fill_reasons.items():
logger.warning(
f"Operation {name}: {reason}; scheduled with the fill duration "
f"{DEFAULT_MOORING_DURATION_MIN / 60:.0f} h. Add 'duration_minutes:' or a "
f"depth in the YAML."
)
summary = fill_duration_summary(timeline)
if summary:
logger.warning(summary)
return timeline
def _create_runtime_legs(self) -> list["Leg"]:
"""Create runtime legs from config."""
# Import here to avoid circular imports
from cruiseplan.runtime.organizational import Leg
runtime_legs = []
for leg_def in self.config.legs or []:
try:
runtime_leg = Leg(
name=leg_def.name,
departure_port=getattr(leg_def, "departure_port", None),
arrival_port=getattr(leg_def, "arrival_port", None),
description=getattr(leg_def, "description", None),
first_activity=getattr(leg_def, "first_activity", None),
last_activity=getattr(leg_def, "last_activity", None),
)
runtime_leg.vessel_speed = leg_def.vessel_speed_kt
runtime_leg.turnaround_time = leg_def.turnaround_time_minutes
runtime_leg.distance_between_stations = (
leg_def.distance_between_stations_km
)
runtime_leg.delay_start = leg_def.delay_start_minutes
runtime_leg.buffer_time = leg_def.buffer_time_minutes
runtime_legs.append(runtime_leg)
except Exception as e: # noqa: BLE001 - skip a leg that cannot be built; others are scheduled
logger.warning(
f"Failed to create runtime leg for '{leg_def.name}': {e}"
)
return runtime_legs
def _process_leg(self, leg: "Leg") -> list[ActivityRecord]:
"""Process a single leg and generate activities."""
# Initialize current_time if not set
if self.current_time is None:
self.current_time = self._parse_start_datetime()
# Apply leg-level delay (e.g. port clearance wait before departure)
leg_delay = getattr(leg, "delay_start", None) or 0.0
if leg_delay:
self.current_time = self.current_time + timedelta(minutes=leg_delay)
activities = []
# Build scientific sequence: departure_port + leg_activities (arrival_port handled separately)
# Validation ensures departure_port and arrival_port are required fields
# Use full port objects (which may contain enriched action info) instead of just names
scientific_activities = [leg.departure_port]
# Get leg activities - check both runtime leg and config leg
leg_activities = self._extract_activities_from_leg(leg)
if not leg_activities and hasattr(self.config, "legs"):
for config_leg in self.config.legs:
if config_leg.name == leg.name and hasattr(config_leg, "activities"):
leg_activities = config_leg.activities
break
scientific_activities.extend(leg_activities or [])
previous_operation = None
# Process departure port and all scientific activities
for activity in scientific_activities:
try:
operation = self._create_operation_from_activity(activity, leg)
self._add_transit_and_operation(
operation, activities, leg, previous_operation
)
previous_operation = operation
except Exception:
activity_name = getattr(activity, "name", str(activity))
logger.exception(f"Failed to process activity '{activity_name}'")
continue
# Insert buffer time contingency block after last scientific station,
# before the return transit to arrival port
buffer_time = getattr(leg, "buffer_time", None)
if buffer_time and previous_operation is not None:
buffer_activity = self._create_buffer_activity(
leg, previous_operation, buffer_time
)
activities.append(buffer_activity)
# Process arrival port (transit computed from current_time, which includes buffer)
try:
operation = self._create_operation_from_activity(leg.arrival_port, leg)
self._add_transit_and_operation(
operation, activities, leg, previous_operation
)
except Exception:
logger.exception("Failed to process arrival port")
return activities
def _create_buffer_activity(
self, leg: "Leg", last_operation: BaseOperation, duration_minutes: float
) -> ActivityRecord:
"""Create a contingency buffer block at the position of the last operation.
Parameters
----------
leg : Leg
The current leg (provides name for labelling).
last_operation : BaseOperation
The last scientific operation; the buffer is placed at its exit position.
duration_minutes : float
Buffer duration in minutes.
Returns
-------
ActivityRecord
A stationary buffer record; advances ``self.current_time`` by duration.
"""
_, exit_pt = last_operation.get_coordinates()
buffer_start = self.current_time
buffer_end = buffer_start + timedelta(minutes=duration_minutes)
activity = ActivityRecord(
kind="buffer",
activity="Buffer",
label=f"Contingency ({duration_minutes:.0f} min)",
entry_lat=exit_pt.latitude,
entry_lon=exit_pt.longitude,
exit_lat=exit_pt.latitude,
exit_lon=exit_pt.longitude,
start_time=buffer_start,
end_time=buffer_end,
duration_minutes=duration_minutes,
planned_duration_minutes=duration_minutes,
dist_nm=0.0,
vessel_speed_kt=0.0,
leg_name=leg.name,
op_type="buffer",
operation_class="Buffer",
comment="Weather/operational contingency buffer",
)
self.current_time = buffer_end
return activity
def _create_operation_from_activity(
self,
activity: str | PointDefinition | LineDefinition | AreaDefinition,
leg: "Leg",
) -> BaseOperation:
"""Create operation object from activity definition."""
if isinstance(activity, str):
# Regular activity name - use factory
return self.factory.create_operation(activity, leg.name)
# Definition object - create directly
return self._create_operation_from_definition(activity, leg)
def _create_operation_from_definition(
self, activity: PointDefinition | LineDefinition | AreaDefinition, leg: "Leg"
) -> BaseOperation:
"""Create operation from Pydantic definition object."""
from cruiseplan.config.activities import (
AreaDefinition,
LineDefinition,
PointDefinition,
)
from cruiseplan.runtime.operations import (
AreaOperation,
LineOperation,
PointOperation,
)
if isinstance(activity, PointDefinition):
if (
hasattr(activity, "operation_type")
and activity.operation_type
and activity.operation_type.value == "port"
):
return PointOperation.from_port(activity)
return PointOperation.from_pydantic(activity)
if isinstance(activity, LineDefinition):
return LineOperation.from_pydantic(activity, leg.vessel_speed)
if isinstance(activity, AreaDefinition):
return AreaOperation.from_pydantic(activity)
raise TypeError(
f"Unknown activity type: {type(activity)}. "
f"Expected PointDefinition, LineDefinition, or AreaDefinition, got {activity}"
)
def _add_transit_and_operation(
self,
operation: BaseOperation,
activities: list[ActivityRecord],
leg: "Leg",
previous_operation: BaseOperation | None,
) -> None:
"""Add navigational transit and operation to activities list."""
# Add navigational transit between all operations
if previous_operation is not None:
transit = self._create_navigational_transit(
previous_operation, operation, leg.name, leg
)
if transit:
activities.append(transit)
# Add the operation activity
operation_activity = self._create_operation_activity(operation, leg)
activities.append(operation_activity)
def _create_navigational_transit(
self,
from_op: BaseOperation,
to_op: BaseOperation,
leg_name: str = "unknown",
leg: "Leg | None" = None,
) -> ActivityRecord | None:
"""Create navigational transit between operations."""
# Get leg-specific vessel speed if available
leg_vessel_speed = None
if leg and hasattr(leg, "vessel_speed"):
leg_vessel_speed = leg.vessel_speed
transit = NavigationalTransit(
from_op, to_op, self.config, leg_name, vessel_speed=leg_vessel_speed
)
planned_minutes = transit.calculate_duration(_Rules(self.config))
override = getattr(to_op, "transit_minutes", None)
# Skip zero-distance transits
if planned_minutes <= 0:
if override is not None:
logger.warning(
f"Operation {to_op.get_label()}: transit_minutes {override:g} is "
"ignored; there is no transit into it"
)
return None
duration_minutes = planned_minutes if override is None else float(override)
speed = transit.get_vessel_speed()
if override is not None:
# the speed the transit was actually run at (none for 0 min)
speed = (
transit.get_operation_distance_nm() / (override / 60.0)
if override > 0
else float("nan")
)
entry_pt, exit_pt = transit.get_coordinates()
activity = ActivityRecord(
kind="transit",
activity="Transit",
label=transit.get_label(),
entry_lat=entry_pt.latitude,
entry_lon=entry_pt.longitude,
exit_lat=exit_pt.latitude,
exit_lon=exit_pt.longitude,
start_time=self.current_time,
end_time=self.current_time + timedelta(minutes=duration_minutes),
duration_minutes=duration_minutes,
planned_duration_minutes=planned_minutes,
dist_nm=transit.get_operation_distance_nm(),
vessel_speed_kt=speed,
leg_name=leg_name,
op_type="transit",
operation_class=transit.__class__.__name__,
)
self.current_time = activity.end_time
return activity
def _create_operation_activity(
self, operation: BaseOperation, leg: "Leg"
) -> ActivityRecord:
"""Create activity record for a scientific operation."""
entry_pt, exit_pt = operation.get_coordinates()
leg_name = leg.name
rules = _Rules(self.config, getattr(leg, "turnaround_time", None))
duration_minutes = operation.calculate_duration(rules)
if getattr(operation, "duration_is_fill", False):
self._fill_reasons.setdefault(
operation.get_label(),
getattr(operation, "duration_fill_reason", None) or "no duration",
)
# Apply delay_start if specified
delay_start_minutes = getattr(operation, "delay_start", 0.0) or 0.0
actual_start_time = self.current_time + timedelta(minutes=delay_start_minutes)
op_type = getattr(operation, "op_type", operation.get_operation_type().lower())
action = getattr(operation, "action", None)
if action is not None:
action = action.value if hasattr(action, "value") else str(action)
activity = ActivityRecord(
kind=kind_of(operation.__class__.__name__, op_type),
activity=operation.get_operation_type(),
label=operation.get_label(),
entry_lat=entry_pt.latitude,
entry_lon=entry_pt.longitude,
exit_lat=exit_pt.latitude,
exit_lon=exit_pt.longitude,
operation_depth_m=getattr(operation, "operation_depth", None),
water_depth_m=getattr(operation, "water_depth", None),
start_time=actual_start_time,
end_time=actual_start_time + timedelta(minutes=duration_minutes),
duration_minutes=duration_minutes,
planned_duration_minutes=duration_minutes,
duration_is_fill=bool(getattr(operation, "duration_is_fill", False)),
delay_start_minutes=delay_start_minutes,
comment=getattr(operation, "comment", None),
dist_nm=getattr(operation, "get_operation_distance_nm", lambda: 0.0)(),
vessel_speed_kt=getattr(
operation,
"get_vessel_speed",
lambda: self.config.default_vessel_speed_kt,
)(),
leg_name=leg_name,
op_type=op_type,
operation_class=operation.__class__.__name__,
action=action or None,
)
self.current_time = activity.end_time
return activity
def _extract_activities_from_operations(self, leg: "Leg") -> list[str]:
"""Extract activities from leg operations."""
activities = []
if hasattr(leg, "operations") and leg.operations:
for operation in leg.operations:
if hasattr(operation, "name"):
activities.append(operation.name)
elif hasattr(operation, "station") and hasattr(
operation.station, "name"
):
activities.append(operation.station.name)
return activities
def _extract_activities_from_clusters(
self, clusters: "list[Cluster] | list[ClusterDefinition]"
) -> list[str]:
"""Extract activities from cluster definitions."""
activities = []
for cluster in clusters:
if hasattr(cluster, "activities") and cluster.activities:
for activity in cluster.activities:
if hasattr(activity, "name"):
activities.append(activity.name)
else:
activities.append(str(activity))
return activities
def _extract_activities_from_config_leg(self, leg: "Leg") -> list[str]:
"""Extract activities from matching config leg."""
activities = []
if hasattr(self.config, "legs"):
for config_leg in self.config.legs:
if config_leg.name == leg.name:
if hasattr(config_leg, "clusters") and config_leg.clusters:
activities.extend(
self._extract_activities_from_clusters(config_leg.clusters)
)
elif hasattr(config_leg, "activities") and config_leg.activities:
activities.extend(config_leg.activities)
break
return activities
def _extract_activities_from_leg(self, leg: "Leg") -> list[str]:
"""Extract activity names from leg definition."""
# Try runtime leg operations first
activities = self._extract_activities_from_operations(leg)
# Try runtime leg clusters
if not activities and hasattr(leg, "clusters") and leg.clusters:
activities = self._extract_activities_from_clusters(leg.clusters)
# Try config leg as fallback
if not activities:
activities = self._extract_activities_from_config_leg(leg)
# Final fallback: direct activities attribute
if not activities and hasattr(leg, "activities") and leg.activities:
activities.extend(leg.activities)
return activities
def _parse_start_datetime(self) -> datetime:
"""Parse start datetime from config."""
try:
start_date = getattr(self.config, "start_date", "1970-01-01T00:00:00+00:00")
if "T" in start_date:
start_date_clean = start_date.replace("Z", "").replace("+00:00", "")
return datetime.fromisoformat(start_date_clean)
start_time = getattr(self.config, "start_time", "08:00")
return datetime.strptime(f"{start_date} {start_time}", "%Y-%m-%d %H:%M")
except (ValueError, AttributeError):
logger.exception("Invalid start_date or start_time format")
# Return a default datetime instead of None
return datetime(1970, 1, 1, 8, 0, 0)
# =============================================================================
# Main API Functions (for backward compatibility)
# =============================================================================
[docs]
def generate_timeline(
cruise: "CruiseInstance", legs: list["Leg"] | None = None
) -> Timeline:
"""
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
-------
Timeline
Records in schedule order.
"""
# The CruiseInstance object already contains a validated CruiseConfig object
# This avoids the YAML serialization/deserialization that causes
# objects to become dictionaries
config = cruise.config
# Use existing timeline generation
generator = TimelineGenerator(config)
return generator.generate_timeline(legs)
def generate_cruise_schedule(
config_path: str,
output_dir: str = "data", # noqa: ARG001 - kept for backward compatibility
formats: list[str] | None = None,
validate_depths: bool = False,
selected_leg: str | None = None,
derive_netcdf: bool = False, # noqa: ARG001 - kept for backward compatibility
bathy_source: str = "gebco2025", # noqa: ARG001 - kept for backward compatibility
bathy_dir: str = "data/bathymetry", # noqa: ARG001 - kept for backward compatibility
bathy_stride: int = 10, # noqa: ARG001 - kept for backward compatibility
figsize: list[float] | None = None, # noqa: ARG001 - kept for backward compatibility
output_basename: str | None = None, # noqa: ARG001 - kept for backward compatibility
) -> dict[str, Any]:
"""
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
-------
Dict[str, Any]
Schedule data with timeline and summary information
"""
from cruiseplan.runtime.cruise import CruiseInstance
# Load cruise configuration
cruise = CruiseInstance(config_path)
# Validate depths if requested
validation_warnings = []
if validate_depths:
from cruiseplan.api.validate import (
_validate_configuration as validate_configuration,
)
is_valid, errors, warnings = validate_configuration(
config_path, check_depths=True, tolerance=10.0
)
if not is_valid:
raise RuntimeError(f"Configuration validation failed: {errors}")
validation_warnings.extend(warnings)
# Filter legs if specific leg requested
legs_to_process = cruise.runtime_legs
if selected_leg:
# Check runtime legs first, then config legs
legs_to_process = [
leg for leg in cruise.runtime_legs if leg.name == selected_leg
]
if (
not legs_to_process
and hasattr(cruise.config, "legs")
and cruise.config.legs
):
# Also check config legs for backward compatibility
config_legs = [
leg for leg in cruise.config.legs if leg.name == selected_leg
]
if config_legs:
legs_to_process = (
cruise.runtime_legs
) # Use all runtime legs if config leg found
if not legs_to_process:
raise ValueError(f"Leg '{selected_leg}' not found in configuration")
# Generate timeline
timeline = generate_timeline(cruise.config, legs_to_process)
# Calculate summary statistics
total_duration_h = timeline_minutes(timeline) / 60.0
total_transit_nm = sum(
record.dist_nm for record in timeline if record.kind == "transit"
)
return {
"success": True,
"timeline": timeline,
"total_activities": len(timeline),
"total_duration_hours": total_duration_h,
"total_distance_nm": total_transit_nm,
"formats_generated": formats or [],
"output_files": [],
"warnings": validation_warnings,
"cruise_name": cruise.config.cruise_name,
"description": getattr(cruise.config, "description", None),
"summary": {
"total_duration_hours": total_duration_h,
"total_duration_days": total_duration_h / 24.0,
"total_transit_distance_nm": total_transit_nm,
"total_activities": len(timeline),
},
"config": cruise.config,
"legs": legs_to_process,
}