Scan Schedule

Scheduling model for Scan command observation-state evaluation.

This module defines the temporal model used to interpret Scan commands that include scheduling metadata such as start_time and/or duration.

The schedule is used by the observation policy to derive the current scan phase from the current time. This allows CSP.LMC to distinguish between:

  • legacy scans, where no scheduling metadata is provided;

  • scans scheduled to start at a future start_time;

  • scans with a fixed duration;

  • scans with both start_time and duration.

ScanSchedule intentionally stores only the scheduling information derived from the Scan command payload. Runtime information, such as the command invocation time, is supplied separately when evaluating the phase. This keeps payload-level metadata separated from command-context metadata.

class ska_csp_lmc_common.observation.scan.schedule.ScanSchedule(scheduled_start: datetime | None = None, duration_s: float | None = None, start_transition_grace_s: float = 1.0, end_early_tolerance_s: float = 0.5, grace_after_end_s: float = 1.0)

Bases: object

Scheduling metadata extracted from a Scan command payload.

ScanSchedule represents the optional timing information supplied with a Scan command. It does not represent the command invocation time. When a duration is provided without an explicit start_time, the effective start is resolved later from CommandContext.start_time.

Parameters:

  • scheduled_start – Optional operational scan start time extracted from the Scan command start_time field. It is None when no explicit start_time is provided; in duration-only scans, the effective start is resolved from CommandContext.start_time.

  • duration_s – Optional scan duration in seconds, extracted from the Scan command duration field.

  • start_transition_grace_s – Grace period, in seconds, allowed after the effective scan start for subsystems to transition to SCANNING.

  • grace_after_end_s – Grace period, in seconds, allowed after the effective scan end for subsystems to return to READY.

scheduled_start: datetime | None = None
duration_s: float | None = None
start_transition_grace_s: float = 1.0
end_early_tolerance_s: float = 0.5
grace_after_end_s: float = 1.0
effective_start(command_start_time: datetime) → datetime

Return the effective start time for this scan.

If the Scan command payload contains start_time, that value is used. Otherwise, the command invocation time from the command context is used. This supports the duration-only case, where the scan is treated as starting immediately when the Scan command is accepted or registered by CSP.LMC.

Parameters:

command_start_time – Command invocation time stored in the CommandContext.

Returns:

The effective scan start time.

effective_end(command_start_time: datetime) → datetime | None

Return the effective end time for this scan, if duration is set.

If no duration is provided, the scan has no scheduled end and must be ended by EndScan.

Parameters:

command_start_time – Command invocation time stored in the CommandContext. It is used as the effective start when the payload does not contain start_time.

Returns:

The effective scan end time, or None when the scan has no duration.

classmethod from_scan_command(argin: dict[str, Any]) → ScanSchedule | None

Create a scan schedule from the Scan command payload.

The method reads only payload-level scheduling metadata:

  • start_time: optional operational scan start time;

  • duration: optional scan duration in seconds.

If neither field is present, the method returns None to indicate legacy Scan behaviour.

When duration is provided without start_time, the scan is treated as starting immediately when the Scan command is registered by CSP.LMC. This method still stores scheduled_start=None in that case: the effective start time is resolved later from CommandContext.start_time when evaluating the schedule phase. This keeps explicit payload scheduling separated from runtime command-context metadata.

Parameters:

argin – Scan command input payload.

Returns:

A ScanSchedule when scheduling metadata is present, otherwise None.