.. _station_pointing_manager:

###################################
Station Beam Pointing Management
###################################

.. note::
   This page documents the new runtime pointing management classes introduced
   in THORN-141 (``PointingRequest`` and ``StationPointingManager``) and
   how they integrate with ``StationComponentManager``. They supersede the
   earlier ad-hoc per-thread tracking implementation that lived inside
   ``StationComponentManager``.

Overview
========

Stations may have multiple simultaneously active station beams that must all
be pointed (and, for sidereal / special targets, tracked) in a *time-coherent*
way. Previously, each tracking request spawned (or conceptually behaved like)
its own loop, which made it difficult to guarantee that all beams stepped to
new delay solutions on the same time boundary. It also increased CPU load due
to duplicated delay calculations and introduced race conditions when applying
new pointing delays to hardware.

The new design introduces two small coordinating classes:

* ``PointingRequest`` - An immutable-ish (after construction) record of a
  single beam's tracking parameters plus mutable runtime state (``next_update``
  and completion flag). It encapsulates per-beam temporal cadence logic such
  as computing the next time-step boundary and marking scan completion.
* ``StationPointingManager`` - Owns all active ``PointingRequest``\ s for
  a station. It runs a single lightweight scheduler thread that:

  1. Monitors all requests for an upcoming time-step boundary.
  2. When any beam approaches its boundary (within a configurable delay
     calculation window), triggers a synchronous recalculation of *all* active
     beams' delays so they share a common application timestamp.
  3. Loads and (optionally time-arms) the pointing delays via the
     ``SpsStation`` proxy.
  4. Advances each request's ``next_update`` (optionally forcing a jump to
     the *next* boundary if calculations completed too quickly).
  5. Cleans up completed (expired) requests automatically.


Boundary Computation Strategy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The boundary is computed by flooring the current UNIX timestamp to the next
multiple of ``time_step`` (or the one after that when ``force=True`` was
requested). This means all beams *tend* toward alignment even if added at
slightly different instants:

.. code-block:: text

    next_boundary = now + time_step - now % time_step

When forced (immediately after applying a set of delays) the manager can
advance by two steps if the calculated boundary would be too close in the
past when considering the cost of delay computation. This avoids "busy loop"
behaviour where the next scheduled boundary is effectively already due.

StationPointingManager
--------------------------

Internal responsibilities:

* Maintain dictionaries of active requests and last-calculated per-beam
  delays / delay rates.
* Decide when a *global* update is required (``_pointing_needs_updating``).
* Batch-calculate delays for every beam (``_calculate_delays_for_all_beams``).
* Stage (``_load_delays_for_all_beams``) and atomically apply
  (``_apply_delays_to_all_beams``) the new delays.
* Prune completed requests.

Integration with StationComponentManager
========================================

``StationComponentManager`` now delegates all live tracking lifecycle
operations to the pointing manager:

* Creating a tracking session (``track_object`` command path) produces a
  ``PointingRequest`` instance, which is passed to
  ``StationPointingManager.add_pointing_request``.
* Stopping tracking (``stop_tracking`` / ``stop_tracking_all``) invokes the
  corresponding manager methods.


State & Event Flow
^^^^^^^^^^^^^^^^^^

1. User issues ``TrackObject`` command to ``MccsStation`` (schema documented
   under ``schemas/MccsStation/MccsStation_TrackObject_3_0.rst``).
2. Command arguments are validated (``verify_values``).
3. A ``PointingRequest`` is created and registered.
4. Manager scheduler loop notices an upcoming boundary and triggers a batch
   delay recomputation.
5. Delays are loaded then (optionally at a specified ``load_time``) applied
   via the SPS proxy.
6. All requests' ``next_update`` values are advanced and, if their
   ``_end_time`` is passed, they are marked complete and later removed.

Concurrency & Timing Considerations
-----------------------------------

* A re-entrant lock protects the request map during add/remove and update.
* The cadence auto-adjustment prevents missing boundaries for short
  ``time_step`` values (e.g. 1 s) while keeping CPU load low for long
  intervals.
* Forced advancement after application prevents immediate fast repeats when
  computation was faster than expected.

Cross-reference
===============

For historical prototype command-line pointing utilities see the
``pointing`` reference page. Beam weight and phase centre interactions are
covered in the ``beam_weight_store`` reference page.