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 PointingRequests 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:

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.