ska_oso_pdm._shared.target

The ska_oso_pdm._shared.target module models entities concerned with receptor pointing and mapping (source coordinates, survey fields, pointing patterns, etc.). The contents of the module are presented in the diagram below.

Class diagram for the target module

An example serialisation of this model to JSON is shown below. This describes two target objects: one, a five-point observation centred on Polaris Australis using 5 arcsec offsets between individual pointings, and two, a single pointing observation centred on M83. In both cases, the coordinates are defined using equatorial coordinates using an ICRS reference frame.

  "targets": [
    {
      "target_id": "Polaris Australis",
      "pointing_pattern": {
        "active": "FivePointParameters",
        "parameters": [
          {
            "kind": "FivePointParameters",
            "offset_arcsec": 5.0
          },
          {
            "kind": "RasterParameters",
            "row_length_arcsec": 1.23,
            "row_offset_arcsec": 4.56,
            "n_rows": 2,
            "pa": 7.89,
            "unidirectional": true
          },
          {
            "kind": "StarRasterParameters",
            "row_length_arcsec": 1.23,
            "n_rows": 2,
            "row_offset_angle": 4.56,
            "unidirectional": true
          }
        ]
      },
      "reference_coordinate": {
        "kind": "equatorial",
        "ra": "21:08:47.92",
        "dec": "-88:57:22.9",
        "reference_frame": "icrs",
        "unit": [
          "hourangle",
          "deg"
        ]
      },
      "radial_velocity": {
        "quantity": {
          "value": -12.345,
          "unit": "km / s"
        },
        "definition": "OPTICAL",
        "reference_frame": "LSRK",
        "redshift": 1.23
      }
    },
    {
      "target_id": "M83",
      "pointing_pattern": {
        "active": "SinglePointParameters",
        "parameters": [
          {
            "kind": "SinglePointParameters",
            "offset_x_arcsec": 0.0,
            "offset_y_arcsec": 0.0
          }
        ]
      },
      "reference_coordinate": {
        "kind": "equatorial",
        "ra": "13:37:00.919",
        "dec": "-29:51:56.74",
        "reference_frame": "icrs",
        "unit": [
          "hourangle",
          "deg"
        ]
      },
      "radial_velocity": {
        "quantity": {
          "value": 0.0,
          "unit": "km / s"
        },
        "definition": "RADIO",
        "reference_frame": "LSRK",
        "redshift": 0.0
      }
    }
  ],

Another JSON example defining two drift scan targets with position specified as azimuth and elevation is shown below.

  "targets": [
    {
      "target_id": "target #1",
      "pointing_pattern": {
        "active": "SinglePointParameters",
        "parameters": [
          {
            "kind": "SinglePointParameters",
            "offset_x_arcsec": 0.0,
            "offset_y_arcsec": 0.0
          }
        ]
      },
      "reference_coordinate": {
        "kind": "horizontal",
        "az": 180.0,
        "el": 45.0,
        "reference_frame": "altaz",
        "unit": ["deg", "deg"]
      },
      "radial_velocity": {
        "quantity": {
          "value": -12.345,
          "unit": "m / s"
        },
        "definition": "OPTICAL",
        "reference_frame": "LSRK",
        "redshift": 0.0
      }
    },
    {
      "target_id": "target #2",
      "pointing_pattern": {
        "active": "SinglePointParameters",
        "parameters": [
          {
            "kind": "SinglePointParameters",
            "offset_x_arcsec": 0.0,
            "offset_y_arcsec": 0.0
          }
        ]
      },
      "reference_coordinate": {
        "kind": "horizontal",
        "az": 180.0,
        "el": 85.0,
        "reference_frame": "altaz",
        "unit": ["deg", "deg"]
      },
      "radial_velocity": {
        "quantity": {
          "value": 0.0,
          "unit": "km / s"
        },
        "definition": "RADIO",
        "reference_frame": "LSRK",
        "redshift": 0.0
      }
    }
  ],

The ska_oso_pdm._shared.target module defines a Python representation of the target of the observation.

class CoordinateKind(value)

An enumeration.

class Coordinates(*, kind: Literal)

Coordinates is an abstract base class for pointing coordinates.

class CrossScanParameters(*, kind: Literal[PointingKind.CROSS_SCAN] = PointingKind.CROSS_SCAN, offset_arcsec: float = 0.0)

CrossScanParameters defines the properties of an observing pattern that uses a cross scan observing pattern, typically used for pointing calibrations.

class EquatorialCoordinates(*, kind: Literal[CoordinateKind.EQUATORIAL] = CoordinateKind.EQUATORIAL, ra: float | str | None = 0.0, dec: float | str | None = 0.0, reference_frame: EquatorialCoordinatesReferenceFrame | None = EquatorialCoordinatesReferenceFrame.ICRS, unit: str | List[str] | Tuple[str] = ('hourangle', 'deg'))

SiderealTarget represents the argument for SKA scheduling block.

class EquatorialCoordinatesReferenceFrame(value)

Enumeration of reference frames supported by an EquatorialCoordinates

class FivePointParameters(*, kind: Literal[PointingKind.FIVE_POINT] = PointingKind.FIVE_POINT, offset_arcsec: float = 0.0)

FivePointParameters defines the properties of an observing pattern that uses a five-point observing pattern centred on a reference position.

class HorizontalCoordinates(*, kind: Literal[CoordinateKind.HORIZONTAL] = CoordinateKind.HORIZONTAL, az: float, el: float, unit: str | List[str] | Tuple[str] = ('deg', 'deg'), reference_frame: HorizontalCoordinatesReferenceFrame | None = HorizontalCoordinatesReferenceFrame.ALTAZ)

DriftScanTarget defines AltAz target for SKA scheduling block.

class HorizontalCoordinatesReferenceFrame(value)

Enumeration of reference frames supported by a HorizontalCoordinates.

class PointingKind(value)

An enumeration.

class PointingPattern(*, active: PointingKind = PointingKind.SINGLE_POINT, parameters: list[FivePointParameters | CrossScanParameters | SinglePointParameters | RasterParameters | StarRasterParameters] = None)

PointingPattern holds the user-configured pointing patterns and current active pattern for receptor pointing patterns associated with a target.

One of each pointing pattern type can be held in the parameters list. Only the active pattern will be used for observing; the remainder provide an easy way to recover previously edited observing parameters for the target.

class PointingPatternParameters

PointingPatternParameters is an abstract base class extended by classes that define receptor pointing patterns.

abstract class property kind: str

Discriminator field used to distinguish the subclass type of instances that extend PointingPatternParameters. This field is a requirement of the JSON representation, so that the correct class can be instantiated as the JSON is unmarshalled.

kind is an abstract class property and must be defined in any subclass.

class RadialVelocity(*, quantity: Quantity = None, definition: RadialVelocityDefinition = RadialVelocityDefinition.RADIO, reference_frame: RadialVelocityReferenceFrame = RadialVelocityReferenceFrame.LSRK, redshift: float = 0.0)

Radial velocity measures the line-of-sight velocity of an astronomical source.

In principle, the radial velocity can be converted to and from the target redshift. However, these values are persisted separately to give the user the option of inputting either value.

A velocity must also define the reference frame and definition that are applicable to the velocity. By default, these have values of:

• definition = RADIO

• reference_frame = LSRK

• redshift = 0.0

class RadialVelocityDefinition(value)

Enumeration of reference definitions supported by a RadialVelocity.

The sky frequency (ν) at which we must observe a spectral line is derived from the rest frequency of the spectral line (ν₀), the line-of-sight velocity of the source (V), and the speed of light (c). The relativistic velocity, or true line-of-sight velocity, is related to the observed and rest frequencies by

V= c * (ν₀²− ν²) / (v₀² + v²)

This equation is a bit cumbersome to use; in astronomy two different approximations are typically used:

Optical Velocity:

Voptical = c * (λ − λ₀) / λ₀ = cz

(z is the redshift of the source; λ and λ₀ are the corresponding observed and rest wavelengths, respectively)

Radio Velocity:

Vradio = c * (ν₀ − ν) / v₀ = c * (λ−λ₀) / λ

The radio and optical velocities are not identical. Particularly, Voptical and Vradio diverge for large velocities. Optical velocities are commonly used for (Helio/Barycentric) extragalactic observations; (LSRK) radio velocities are typical for Galactic observations.

Taken from https://science.nrao.edu/facilities/vla/docs/manuals/obsguide/modes/line

class RadialVelocityQuantity(*, value: float, unit: RadialVelocityUnits = RadialVelocityUnits.KM_PER_SEC)

Value/unit pair to describe the radial velocity measurement.

class RadialVelocityReferenceFrame(value)

Reference frame in which the radial velocity is defined.

The Earth rotates, revolves around the Sun, rotates around the Galaxy, moves within the Local Group, and shows motion against the Cosmic Microwave Background. As for the convention above, any source velocity must therefore also always be specified relative to a reference frame.

Various velocity rest frames are used in the literature. The following table lists their name, the motion that is corrected for, and the maximum amplitude of the velocity correction. Each rest frame correction is incremental to the preceding row:

Velocity Rest Frame Correct for + max correction (km/s) =========================== ====================================== ====================================== Topocentric Telescope Nothing (0) Geocentric Earth Center Earth rotation (0.5) Earth-Moon Barycentric Earth+Moon center of mass Motion around Earth+Moon center of mass (0.013) Heliocentric Center of the Sun Earth orbital motion (30) Barycentric Earth+Sun center of mass Earth+Sun center of mass (0.012) Local Standard of Rest Center of Mass of local stars Solar motion relative to nearby stars (20) Galactocentric Center of Milky Way Milky Way Rotation (230) Local Group Barycentric Local Group center of mass Milky Way Motion (100) Virgocentric Center of the Local Virgo supercluster Local Group motion (300) Cosmic Microwave Background CMB Local Supercluster Motion (600)

The velocity frame should be chosen based on the science. For most observations, however, one of the following three reference frames is commonly used:

• Topocentric is the reference frame of the observatory (defining the sky frequency of the observations). Visibilities in a measurement set are typically stored in this frame.

• Local Standard of Rest is the native output of images in CASA. Note that there are two varieties of LSR: the kinematic LSR (LSRK) and the dynamic (LSRD) definitions for the kinematic and dynamic centers, respectively. In almost all cases LSRK is being used and the less precise name LSR is usually used synonymously with the more modern LSRK definition.

• Barycentric is a commonly used frame that has virtually replaced the older Heliocentric standard. Given the small difference between the Barycentric and Heliocentric frames, they are frequently used interchangeably.

Taken from https://science.nrao.edu/facilities/vla/docs/manuals/obsguide/modes/line

class RadialVelocityUnits(value)

Units for radial velocities.

class RasterParameters(*, kind: Literal[PointingKind.RASTER] = PointingKind.RASTER, row_length_arcsec: float = 0.0, row_offset_arcsec: float = 0.0, n_rows: int = 1, pa: float = 0.0, unidirectional: bool = False)

RasterParameters defines the properties of an observing pattern that uses a raster pattern centred on a reference position.

class SinglePointParameters(*, kind: Literal[PointingKind.SINGLE_POINT] = PointingKind.SINGLE_POINT, offset_x_arcsec: float = 0.0, offset_y_arcsec: float = 0.0)

SinglePointParameters defines the properties for an observing pattern consisting of a single receptor pointing with an optional offset from the reference position.

class SolarSystemObject(*, kind: Literal[CoordinateKind.SSO] = CoordinateKind.SSO, name: SolarSystemObjectName)

Planet represents the argument for SKA scheduling block.

class SolarSystemObjectName(value)

SolarSystemObjectName represents name of the solar system object.

class StarRasterParameters(*, kind: Literal[PointingKind.STAR_RASTER] = PointingKind.STAR_RASTER, row_length_arcsec: float = 0.0, n_rows: int = 1, row_offset_angle: float = 0.0, unidirectional: bool = False)

StarRasterParameters defines the properties of an observing pattern that uses a star raster pattern centred on a reference position.

class Target(*, target_id: str = '', pointing_pattern: PointingPattern = None, reference_coordinate: EquatorialCoordinates | SolarSystemObject | HorizontalCoordinates = None, radial_velocity: RadialVelocity = None)

Target represents the receptor pointing for an SKA observation, consisting of a reference position and a pointing pattern to be used when observing the target.

Default pointing patterns and equatorial coordinates will be set if not provided.