necst.procedures.observations.pointing_reference_beam

Pointing reference-beam support for file-based observations.

This module implements the observation-control side of pointing_reference_beam_id. The coordinate convention is intentionally explicit:

• x_arcsec = dAz * cos(El) is positive toward increasing Az.

• y_arcsec = dEl is positive toward increasing El.

• A beam center is reconstructed as beam = boresight + offset.

• To put a selected beam on a requested target, the antenna boresight command is boresight = target - offset.

The implementation is deliberately dependency-light and does not import the converter/sunscan implementation. It accepts the same beam-model fields needed by the observation program and fails closed for unsupported cases instead of silently applying a geometrically ambiguous correction.

exception PointingReferenceBeamError

Bases: ValueError

Raised when pointing-reference beam correction cannot be applied safely.

class BeamModelDocument(beams: 'Dict[str, Dict[str, Any]]', source_path: 'Optional[Path]' = None, input_file_sha256: 'Optional[str]' = None, beam_model_version: 'Optional[str]' = None)

Bases: object

Parameters:

• beams (Dict[str, Dict[str, Any]]) –

• source_path (Optional[Path]) –

• input_file_sha256 (Optional[str]) –

• beam_model_version (Optional[str]) –

beams: Dict[str, Dict[str, Any]]

source_path: Optional[Path] = None

input_file_sha256: Optional[str] = None

beam_model_version: Optional[str] = None

class PointingReferenceBeamContext(pointing_reference_beam_id: 'str', pointing_reference_beam_policy: 'str' = 'exact', beam_model: 'Optional[BeamModelDocument]' = None)

Bases: object

Parameters:

• pointing_reference_beam_id (str) –

• pointing_reference_beam_policy (str) –

• beam_model (Optional[BeamModelDocument]) –

pointing_reference_beam_id: str

pointing_reference_beam_policy: str = 'exact'

beam_model: Optional[BeamModelDocument] = None

property active: bool

normalize_beam_model(raw, *, source_path=None, input_file_sha256=None)

Parameters:

• raw (Mapping[str, Any]) –

• source_path (Optional[Path]) –

• input_file_sha256 (Optional[str]) –

Return type:

BeamModelDocument

load_beam_model(path)

Parameters:

path (Path) –

Return type:

BeamModelDocument

build_pointing_reference_context(params, *, obs_file)

Build pointing-reference context from .obs parameters.

point_reference_beam_id is rejected intentionally; the supported observation-control name is pointing_reference_beam_id.

Parameters:

• params (Mapping[str, Any]) –

• obs_file (Any) –

Return type:

Optional[PointingReferenceBeamContext]

evaluate_beam_offset_arcsec(beam_model, beam_id, az_deg, el_deg)

Evaluate beam offset in the tangent-plane convention.

Parameters:

• beam_model (Union[BeamModelDocument, Mapping[str, Any]]) – Normalized document or raw mapping containing beams.

• beam_id (str) – Beam to evaluate.

• az_deg (float) – Target Az/El in degrees. The current implemented models depend on El; Az is accepted to keep the API explicit and future-proof.

• el_deg (float) – Target Az/El in degrees. The current implemented models depend on El; Az is accepted to keep the API explicit and future-proof.

Returns:

(x_arcsec, y_arcsec) where x = dAz*cos(El) and y = dEl.

Return type:

tuple

apply_pointing_reference_beam(target_az_deg, target_el_deg, context, policy=None)

Convert requested target Az/El into boresight Az/El.

The sign convention is always beam = boresight + offset and therefore boresight = target - offset. The policy controls which elevation is used to evaluate the offset:

• target_el evaluates the offset at the requested target elevation.

• boresight_el_iter1 evaluates once at the target elevation and once at the resulting boresight elevation.

• exact solves C_el + y(C_el)/3600 = T_el and then evaluates x(C_el). This is the recommended policy for science observations because it is exactly consistent with converter/sunscan reconstruction.

Parameters:

• target_az_deg (float) –

• target_el_deg (float) –

• context (Optional[PointingReferenceBeamContext]) –

• policy (Optional[str]) –

Return type:

Tuple[float, float]

apply_pointing_reference_to_point_kwargs(kwargs, context)

Apply reference-beam correction to a Commander.antenna(‘point’) kwargs dict.

Parameters:

• kwargs (Mapping[str, Any]) –

• context (Optional[PointingReferenceBeamContext]) –

Return type:

Dict[str, Any]

apply_pointing_reference_to_scan_kwargs(kwargs, context)

Apply reference-beam correction to a Commander.antenna(‘scan’) kwargs dict.

Parameters:

• kwargs (Mapping[str, Any]) –

• context (Optional[PointingReferenceBeamContext]) –

Return type:

Dict[str, Any]

apply_pointing_reference_to_scan_block_kwargs(kwargs, context)

Apply reference-beam correction to a Commander.scan_block kwargs dict.

Parameters:

• kwargs (Mapping[str, Any]) –

• context (Optional[PointingReferenceBeamContext]) –

Return type:

Dict[str, Any]

pointing_reference_snapshot_record(context)

Parameters:

context (Optional[PointingReferenceBeamContext]) –

Return type:

Dict[str, Any]

attach_pointing_reference_to_snapshot(snapshot, context, *, dumps_toml_func, sha256_text_func)

Attach pointing-reference provenance and recompute the canonical hash.

Parameters:

• snapshot (Mapping[str, Any]) –

• context (Optional[PointingReferenceBeamContext]) –

• dumps_toml_func (Any) –

• sha256_text_func (Any) –

Return type:

Dict[str, Any]

previous

necst.procedures.observations.optical_pointing

next

necst.procedures.observations.position_switching