CSP.LMC Observation Supervisor

class ska_csp_lmc_common.observation.observation_supervisor.CspObservationSupervisor(*, model: SubarrayObsStateModel, policy: CommandAwareObservationPolicy, store: ComponentSnapshotStore, update_attribute: Callable[[str, Any], None], get_obs_modes: Callable[[], list], logger: Logger, debounce_s: float = 0.1, max_latency: float = 0.3, reconcile_timeout_s=0.5)

Bases: ObservationSupervisor

Supervisor implementation focusing on _evaluate_and_publish logic.

The base ObservationSupervisor still provides debounce/max-latency timing and a background tick thread.

Key behavior: - On evaluation, take a snapshot from the StateStore and ask the model to

compute/store the aggregated candidate via evaluate_states(…).

  • Run the consistency policy on (candidate, obsModes, snapshot).

  • If a hard inconsistency is detected, latch FAULT via model component_fault(True) with cause=CONSISTENCY.

  • Otherwise, apply the policy final state via model.apply_final_state(…).

The ObsStateModel is the single authority responsible for de-duplication, precedence, and publication of obsState changes.

on_subsystem_event(component: ObservingComponent, obs_state: ska_control_model.ObsState | None = None, **kwargs) → None

Entry point for subsystem ObsState events from EventManager.

It handles the ingestion, debouncing, and orchestration of the state evaluation.

Parameters:

  • component – The component that generated the event.

  • obs_state – The new ObsState value.

  • kwargs – Additional arguments.

on_model_update(obs_state: ska_control_model.ObsState) → None

Handles state change notifications originating from the ObsStateModel itself (e.g., entering a transitional state like CONFIGURING).

These updates are considered high-priority and will always trigger an immediate evaluation, bypassing the debounce delay.

clear_consistency_fault() → None

Clear consistency-related fault state and diagnostic attributes.

If the model is currently latched in FAULT due to a consistency violation, that fault condition is cleared. The supervisor also resets the internal consistency flag and message and publishes the cleared diagnostic attributes.

This method only clears faults caused by consistency evaluation. It does not clear faults caused by subsystem or internal errors.

_evaluate_and_publish(*, force: bool = False, reconcile_timeout: bool = False) → EvaluationOutcome

Evaluate the CSP subarray observation state.

This method takes a snapshot of subsystem states, evaluates aggregation and consistency policies, manages hard faults, and applies the resulting ObsState to the ObsStateModel.

The evaluation follows these steps:

1. Take an atomic snapshot of all subsystem ObsState values from the StateStore and update the subarray aggregation model via evaluate_states(…). The aggregated candidate state is stored in the model but not published.

2. Apply the CSP scan consistency policy to the aggregated candidate state, the active observation modes, and the full subsystem snapshot to detect hard inconsistencies or invalid combinations.

3. Manage FAULT transitions using a single fault mechanism (component_fault):

  • If the policy reports a hard fault, the subarray is forced into

    FAULT with cause CONSISTENCY. This state is latched until an explicit recovery action.

  • If no hard fault is reported and the subarray is currently in

    FAULT due to a consistency violation, the FAULT state is cleared automatically.

Fault-related diagnostic information (consistency flag and error message) is updated as part of this step.

4. Apply the final subarray ObsState to the ObsStateModel via apply_final_state(…). The model is responsible for precedence, de-duplication, and publication to the TANGO attribute if the value changes.

This method does not clear FAULT conditions caused by subsystem or internal errors; those require an explicit recovery action (e.g. Restart).

Parameters:

  • force – Whether the evaluation was triggered as a forced supervisor cycle rather than a normal debounced update. Present for compatibility with the generic supervisor interface.

  • reconcile_timeout – Whether the reconciliation timeout has expired for the current evaluation cycle.

Returns:

The supervisor evaluation outcome indicating whether the state was applied, a wait is still required, or a fault was raised.

set_command_context(context: CommandContext) → None

Register a command context and make it the active one.

The supervisor delegates command lifecycle tracking to the internal command-context registry. The provided context becomes the active command context used during subsequent policy evaluations.

Parameters:

context – The command context associated with the command being started.

update_command_outcome(command_id: str, command_outcome: CommandOutcome, completion_time: datetime) → None

Update the outcome of a specific command context.

The matching command context is updated in the registry with the final outcome and completion time. If the context is successfully updated, an immediate observation re-evaluation is triggered.

Parameters:

  • command_id – Unique identifier of the command whose outcome is being reported.

  • command_outcome – Final aggregated outcome produced for the command.

  • completion_time – Timestamp at which the command completed.