Scan policy

CSP.LMC-specific scan consistency policy implementation.

This module contains the CSP.LMC scan consistency rules used by the observation supervisor to validate subsystem ObsState alignment during scan execution.

The policy handles two related but distinct cases:

  • legacy or observed scans, where no retained schedule metadata is available and scan consistency is inferred from the aggregated ObsState and subsystem snapshots;

  • scheduled scans, where retained Scan metadata is available through a retained command context and the snapshot is evaluated with scheduled-scan start and exit gates.

For scheduled scans, the policy keeps the CSP Subarray READY until all valid successful planned devices have reached SCANNING, then keeps the CSP Subarray SCANNING until all valid successful planned devices have returned READY.

Command lifecycle information is intentionally not interpreted in this policy. Command execution, completion, failure, rejection, and abortion semantics are handled by the command-aware observation policy. This policy only evaluates whether the current observation snapshot is consistent with either the observed scan state or the retained scan lifecycle.

class ska_csp_lmc_common.observation.scan.scan_policy.CspScanConsistencyPolicy(*, logger: Logger | None = None, apply_inconsistency_policy: bool = True, required_subsystems: Set[str] | None = None)

Bases: ScanConsistencyPolicy

Evaluate CSP subsystem consistency during scan-related states.

The policy validates whether CSP subsystems are in observation states compatible with the current scan situation.

When a retained Scan command context with schedule metadata is available, the policy evaluates the snapshot using scheduled-scan gates. Before scan entry, the CSP Subarray remains READY until all valid successful planned devices are SCANNING. After the CSP Subarray has entered SCANNING, it remains SCANNING until all valid successful planned devices have returned READY.

When no active scan schedule is available, the policy falls back to the legacy observed-state behaviour. In that mode, scan consistency checks are run when the aggregated state is SCANNING or when the system appears to collapse unexpectedly from SCANNING to EMPTY or IDLE.

This class does not interpret command lifecycle state. In particular, it does not decide whether a Scan, EndScan, or Abort command is in progress or completed. Those decisions are handled by the command-aware policy and the observation supervisor.

Parameters:

  • logger – Logger used to report consistency warnings.

  • apply_inconsistency_policy – Whether detected hard inconsistencies should force a FAULT decision.

  • required_subsystems – Default subsystem families required for a valid scan. The set is refined at runtime according to the active observing modes.

evaluate(aggregated: ska_control_model.ObsState, obs_modes: List[ska_control_model.ObsMode], subsystems: Dict[str, ComponentSnapshot], previous_state: ska_control_model.ObsState | None = None, command_context: CommandContext | None = None, retained_scan_context: CommandContext | None = None, reconcile_timeout: bool | None = False, refreshed_after_reconcile: bool | None = False) → Decision

Evaluate CSP scan consistency for the current observation snapshot.

If a Scan lifecycle context with schedule metadata is available, the snapshot is evaluated with the scheduled-scan start and exit gates. Otherwise, the policy uses the legacy observed-state scan consistency rules.

Parameters:

  • aggregated – Current aggregated observation state.

  • obs_modes – Active observation modes reported for the subarray.

  • subsystems – Snapshot of subsystem states used for consistency evaluation.

  • previous_state – Previously published stable observation state.

  • command_context – Current command context, if a command is being reconciled.

  • retained_scan_context – Retained Scan context from the active or most recent scan lifecycle.

  • reconcile_timeout – Whether command reconciliation has timed out.

  • refreshed_after_reconcile – Whether subsystem snapshots have already been refreshed after reconciliation.

Returns:

Policy decision to apply, wait, or fault.

should_override_in_progress_command(context: CommandContext) → bool

Return whether scan lifecycle policy should override command progress.

Scheduled Scan commands are handled by this policy because their immediate observable state may legitimately differ from the Scan command target during the retained scan lifecycle. For example, the CSP Subarray may remain READY before scan entry, and may remain SCANNING while waiting for selected devices to return READY after scan execution.

Generic command progress reconciliation must therefore defer to the scan lifecycle policy whenever the current command is a Scan with retained schedule metadata.