katpoint package

Submodules

katpoint.antenna module

Antenna object containing sufficient information to point at target, correct delays.

An antenna is considered to be a steerable parabolic dish containing multiple feeds. The Antenna object wraps the antenna’s location, dish diameter and other parameters that affect pointing and delay calculations.

class katpoint.antenna.Antenna(antenna, name=<object object>, diameter=<object object>, delay_model=<object object>, pointing_model=<object object>, beamwidth=<object object>)

Bases: object

An antenna that can point at a target.

This is a wrapper around an Astropy EarthLocation that adds a dish diameter and other parameters related to pointing and delay calculations.

It has two variants: a stand-alone single dish, or an antenna that is part of an array. The first variant is initialised with the antenna location, while the second variant is initialised with the array reference location and an ENU (east-north-up) offset for the specific antenna which also doubles as the first part of a broader delay model for the antenna.

Additionally, a diameter, a pointing model and a beamwidth factor may be specified. These parameters are collected for convenience, and the pointing model is not applied by default when calculating pointing or delays.

The Antenna object is typically passed around in string form, and is fully described by its description string, which has the following format:

name, latitude (D:M:S), longitude (D:M:S), altitude (m), diameter (m),
east-north-up offset (m) / delay model, pointing model, beamwidth

A stand-alone dish has the antenna location as lat-lon-alt and the ENU offset as an empty string, while an antenna that is part of an array has the array reference location as lat-lon-alt and the ENU offset as a space-separated string of 3 numbers (followed by any additional delay model terms). The pointing model is a space-separated string of model parameters (or empty string if there is no pointing model). The beamwidth is a single floating-point number.

Any empty fields at the end of the description string may be omitted, as they will be replaced by defaults. The first four fields are required (but the name may be an empty string).

Here are some examples of description strings:

- Single dish
  'XDM, -25:53:23.0, 27:41:03.0, 1406.1086, 15.0'

- Simple array antenna
  'FF1, -30:43:17.3, 21:24:38.5, 1038.0, 12.0, 18.4 -8.7 0.0'

- Fully-specified antenna
  'FF2, -30:43:17.3, 21:24:38.5, 1038.0, 12.0, 86.2 25.5 0.0, -0:06:39.6 0, 1.16'

Parameters:

antenna (EarthLocation, str or Antenna) – A location on Earth, a full description string or existing Antenna object. The parameters in the description string or existing Antenna can still be overridden by providing additional parameters after antenna.
name (string, optional) – Name of antenna (may be empty but may not contain commas)
diameter (Quantity or string or float, optional) – Dish diameter, in metres
delay_model (DelayModel object or equivalent, optional) – Delay model for antenna, either as a direct object, a file-like object representing a parameter file, or a string or sequence of float params. The first three parameters form an East-North-Up offset from WGS84 reference position, in metres.
pointing_model (PointingModel object or equivalent, optional) – Pointing model for antenna, either as a direct object, a file-like object representing a parameter file, or a string or sequence of float parameters from which the PointingModel object can be instantiated
beamwidth (string or float, optional) – Full width at half maximum (FWHM) average beamwidth, as a multiple of lambda / D (wavelength / dish diameter). This depends on the dish illumination pattern, and ranges from 1.03 for a uniformly illuminated circular dish to 1.22 for a Gaussian-tapered circular dish (the default).

location :class:`~astropy.coordinates.EarthLocation`: Underlying object used for pointing calculations

ref_location :class:`~astropy.coordinates.EarthLocation`: Array reference location for antenna in an array (same as location for a stand-alone antenna)

Raises:: ValueError – If description string has wrong format or parameters are incorrect

array_reference_antenna(name='array')

Synthetic antenna at the delay model reference position of this antenna.

This is mainly useful as the reference antenna for Target.uvw(), in which case it will give both faster and more accurate results than other choices.

The returned antenna will have no delay or pointing model. It is intended to be used only for its position and does not correspond to a physical antenna.

baseline_toward(antenna2)

Baseline vector pointing toward second antenna, in ENU coordinates.

This calculates the baseline vector pointing from this antenna toward a second antenna, antenna2, in local East-North-Up (ENU) coordinates relative to this antenna’s geodetic location.

Parameters:: antenna2 (EarthLocation or Antenna) – Second antenna of baseline pair (baseline vector points toward it)
Returns:: enu – East, North, Up coordinates of baseline vector as Cartesian (x, y, z)
Return type:: CartesianRepresentation

property description: Complete string representation of antenna object.

classmethod from_description(description): Construct antenna object from description string.

local_sidereal_time(timestamp=None)

Calculate local apparent sidereal time at antenna for timestamp(s).

This is a vectorised function that returns the local apparent sidereal time at the antenna for the given timestamp(s).

Parameters:: timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
Returns:: last – Local apparent sidereal time(s)
Return type:: astropy.coordinates.Longitude

property position_ecef: ECEF (Earth-centred Earth-fixed) position of antenna (in metres).

property position_enu: East-North-Up offset from WGS84 reference position, in metres.

property position_wgs84

WGS84 position.

The latitude and longitude are in radians, and the altitude in metres.

property ref_position_wgs84

WGS84 reference position.

The latitude and longitude are in radians, and the altitude in metres.

katpoint.catalogue module

Target catalogue.

class katpoint.catalogue.Catalogue(targets=None, tags=None, add_specials=None, add_stars=None, antenna=None, flux_frequency: Unit('Hz') = None)

Bases: object

A searchable and filterable catalogue of targets.

Overview

A Catalogue object combines two concepts:

A list of targets, which can be filtered, sorted, pretty-printed and iterated over. The list is accessible as Catalogue.targets(), and the catalogue itself is iterable, returning the next target on each iteration. The targets are assumed to be unique, but may have the same name. An example is:
```
cat = katpoint.Catalogue()
cat.add(some_targets)
t = cat.targets[0]
for t in cat:
    # Do something with target t
```
Lookup by name, by using the catalogue as if it were a dictionary. This is simpler for the user, who does not have to remember all the target details. The named lookup supports tab completion in IPython, which further simplifies finding a target in the catalogue. The most recently added target with the specified name is returned. An example is:
```
targets = ['Sun, special', 'Moon, special', 'Jupiter, special']
cat = katpoint.Catalogue(targets)
t = cat['Sun']
```

Construction

A catalogue can be constructed in many ways. The simplest way is:

cat = katpoint.Catalogue()

which produces an empty catalogue. Additional targets may be loaded during initialisation of the catalogue by providing a list of Target objects (or a single object by itself), as in the following example:

t1 = katpoint.Target('Venus, special')
t2 = katpoint.Target('Takreem, azel, 20, 30')
cat1 = katpoint.Catalogue(t1)
cat2 = katpoint.Catalogue([t1, t2])

Alternatively, the list of targets may be replaced by a list of target description strings (or a single description string). The target objects are then constructed before being added, as in:

cat1 = katpoint.Catalogue('Takreem, azel, 20, 30')
cat2 = katpoint.Catalogue(['Venus, special', 'Takreem, azel, 20, 30'])

Taking this one step further, the list may be replaced by any iterable object that returns strings. A very useful example of such an object is the Python file object, which iterates over the lines of a text file. If the catalogue file contains one target description string per line (with comments and blank lines allowed too), it may be loaded as:

cat = katpoint.Catalogue(open('catalogue.csv'))

Once a catalogue is initialised, more targets may be added to it. The Catalogue.add() method is the most direct way. It accepts a single target object, a list of target objects, a single string, a list of strings or a string iterable. This is illustrated below:

t1 = katpoint.Target('Venus, special')
t2 = katpoint.Target('Takreem, azel, 20, 30')
cat = katpoint.Catalogue()
cat.add(t1)
cat.add([t1, t2])
cat.add('Venus, special')
cat.add(['Venus, special', 'Takreem, azel, 20, 30'])
cat.add(open('catalogue.csv'))

Some target types are typically found in files with standard formats. Notably, tle targets are found in TLE files with three lines per target, and many xephem targets are stored in EDB database files. Editing these files to make each line a valid Target description string is cumbersome, especially in the case of TLE files which are regularly updated. Two special methods simplify the loading of targets from these files:

cat = katpoint.Catalogue()
cat.add_tle(open('gps-ops.txt'))
cat.add_edb(open('hipparcos.edb'))

Whenever targets are added to the catalogue, a tag or list of tags may be specified. The tags can also be given as a single string of whitespace-delimited tags, since tags may not contain whitespace. These tags are added to the targets currently being added. This makes it easy to tag groups of related targets in the catalogue, as shown below:

cat = katpoint.Catalogue(tags='default')
cat.add_tle(open('gps-ops.txt'), tags='gps satellite')
cat.add_tle(open('glo-ops.txt'), tags=['glonass', 'satellite'])
cat.add(open('source_list.csv'), tags='calibrator')
cat.add_edb(open('hipparcos.edb'), tags='star')

Finally, targets may be removed from the catalogue. The most recently added target with the specified name is removed from the targets list as well as the lookup dict. The target may be removed via any of its names:

targets = ['Sol | Sun, special', 'Moon, special', 'Jupiter, special']
cat = katpoint.Catalogue(targets)
cat.remove('Sun')

Filtering and sorting

A Catalogue object may be filtered based on various criteria. The following filters are available:

Tag filter. Returns all targets that have a specified set of tags, and not another set of tags. Tags prepended with a tilde (~) indicate tags which targets should not have. All tags have to be present (or absent) for a target to be selected. Remember that the body type is also a tag. An example is:
```
cat = katpoint.Catalogue(tags='default')
cat1 = cat.filter(tags=['special', '~radec'])
cat1 = cat.filter(tags='special ~radec')
```

Flux filter. Returns all targets with a flux density between the specified limits, at a given frequency. If only one limit is given, it is a lower limit. To simplify filtering, a default flux frequency may be supplied to the catalogue during initialisation. This is stored in each target in the catalogue. An example is:

import astropy.units as u
cat = katpoint.Catalogue(open('source_list.csv'))
cat1 = cat.filter(flux_limit=[1, 100] * u.Jy,
                  flux_frequency=1500 * u.MHz)
cat = katpoint.Catalogue(open('source_list.csv'),
                         flux_frequency=1500 * u.MHz)
cat1 = cat.filter(flux_limit=1 * u.Jy)

Azimuth filter. Returns all targets with an azimuth angle in the given range. The range is specified in degrees as [left, right], where left is the leftmost or starting azimuth, and right is the rightmost or ending azimuth. The azimuth angle increases clockwise from left to right to form the range. If right is less than left, the azimuth angles range around +-180 degrees. Since the target azimuth is dependent on time and observer position, a timestamp and katpoint.Antenna object has to be provided. The timestamp defaults to now, and the antenna object may be associated with the catalogue during initialisation, from where it is stored in each target. An example is:
```
import astropy.units as u
ant = katpoint.Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
targets = ['Sun, special', 'Moon, special', 'Jupiter, special']
cat = katpoint.Catalogue(targets)
cat1 = cat.filter(az_limit=[0, 90] * u.deg,
                  timestamp='2009-10-10', antenna=ant)
cat = katpoint.Catalogue(antenna=ant)
cat1 = cat.filter(az_limit=[90, 0] * u.deg)
```

Elevation filter. Returns all targets with an elevation angle within the given limits, in degrees. If only one limit is given, it is assumed to be a lower limit. As with the azimuth filter, a timestamp and antenna object is required (or defaults will be used). An example is:

import astropy.units as u
ant = katpoint.Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
targets = ['Sun, special', 'Moon, special', 'Jupiter, special']
cat = katpoint.Catalogue(targets)
cat1 = cat.filter(el_limit=[10, 30] * u.deg,
                  timestamp='2009-10-10', antenna=ant)
cat = katpoint.Catalogue(antenna=ant)
cat1 = cat.filter(el_limit=10 * u.deg)

Proximity filter. Returns all targets with angular separation from a given set of targets within a specified range. The range is given as a lower and upper limit, in degrees, and a single number is taken as the lower limit. The typical use of this filter is to return all targets more than a specified number of degrees away from a known set of interfering targets. As with the azimuth filter, a timestamp and antenna object is required (or defaults will be used). An example is:

import astropy.units as u
ant = katpoint.Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
targets = ['Sun, special', 'Moon, special', 'Jupiter, special']
cat = katpoint.Catalogue(targets)
cat.add_tle(open('geo.txt'))
sun = cat['Sun']
afristar = cat['AFRISTAR']
cat1 = cat.filter(dist_limit=5 * u.deg,
                  proximity_targets=[sun, afristar],
                  timestamp='2009-10-10', antenna=ant)
cat = katpoint.Catalogue(antenna=ant)
cat1 = cat.filter(dist_limit=[0, 5] * u.deg, proximity_targets=sun)

The criteria may be divided into static criteria which are independent of time (tags and flux) and dynamic criteria which do depend on time (azimuth, elevation and proximity). There are two filtering mechanisms that both support the same criteria, but differ on their handling of dynamic criteria:

A direct filter, implemented by the Catalogue.filter() method. This returns the filtered catalogue as a new catalogue which contains the subset of targets that satisfy the criteria. All criteria are evaluated at the same time instant. A typical use-case is:
```
cat = katpoint.Catalogue(open('source_list.csv'))
strong_sources = cat.filter(flux_limit=10 * u.Jy,
                            flux_frequency=1500 * u.MHz)
```
An iterator filter, implemented by the Catalogue.iterfilter() method. This is a Python generator function, which returns a generator iterator, to be more precise. Each time the returned iterator’s .next() method is invoked, the next suitable Target object is returned. If no timestamp is provided, the criteria are re-evaluated at the time instant of the .next() call, which makes it easy to cycle through a list of targets over an extended period of time (as during observation). The iterator filter is typically used in a for-loop:
```
cat = katpoint.Catalogue(open('source_list.csv'))
ant = katpoint.Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
for t in cat.iterfilter(el_limit=10 * u.deg, antenna=ant):
    # < observe target t >
```

When a catalogue is sorted, the order of the target list is changed. The catalogue may be sorted according to name (the default), right ascension, declination, azimuth, elevation and flux. Any position-based key requires a timestamp and katpoint.Antenna object to evaluate the position of each target, and the flux key requires a frequency at which to evaluate the flux.

param targets:: Target or list of targets to add to catalogue (may also be file object)
type targets:: Target object or string, or sequence of these, optional
param tags:: Tag or list of tags to add to targets (strings will be split on whitespace)
type tags:: string or sequence of strings, optional
param add_specials:: Always False (add special bodies yourself) DEPRECATED
type add_specials:: bool, optional
param add_stars:: Always False (stars have no special support anymore) DEPRECATED
type add_stars:: bool, optional
param antenna:: Default antenna to use for position calculations for all targets
type antenna:: Antenna object, optional
param flux_frequency:: Default frequency at which to evaluate flux density of all targets
type flux_frequency:: Quantity, optional

Notes

The catalogue object has an interesting relationship with orderedness. While it is nominally an ordered list of targets, it is considered equal to another catalogue with the same targets in a different order. This is because the catalogue may be conveniently reordered in many ways (e.g. based on elevation, declination, flux, etc.) while remaining essentially the same catalogue. It also allows us to preserve the order in which the catalogue was assembled, which seems the most natural.

add(targets, tags=None)

Add targets to catalogue.

Examples of catalogue construction can be found in the Catalogue documentation.

Parameters:

targets (Target object or string, or sequence of these) – Target or list of targets to add to catalogue (may also be file object)
tags (string or sequence of strings, optional) – Tag or list of tags to add to targets (strings will be split on whitespace)

Examples

Here are some ways to add targets to a catalogue:

>>> from katpoint import Catalogue
>>> cat = Catalogue()
>>> cat.add(open('source_list.csv'), tags='cal')
>>> cat.add('Sun, special')
>>> cat2 = Catalogue()
>>> cat2.add(cat.targets)

add_edb(lines, tags=None)

Add XEphem database format (EDB) targets to catalogue.

Examples of catalogue construction can be found in the Catalogue documentation.

Parameters:

lines (sequence of strings) – List of lines containing a target per line (may also be file object)
tags (string or sequence of strings, optional) – Tag or list of tags to add to targets (strings will be split on whitespace)

Examples

Here are some ways to add EDB targets to a catalogue:

>>> from katpoint import Catalogue
>>> cat = Catalogue()
>>> cat.add_edb(open('hipparcos.edb'), tags='star')
>>> lines = ['HYP71683,f|S|G2,14:39:35.88 ,-60:50:7.4 ,-0.010,2000,\n',
             'HYP113368,f|S|A3,22:57:39.055,-29:37:20.10,1.166,2000,\n']
>>> cat2.add_edb(lines)

add_tle(lines, tags=None)

Add NORAD Two-Line Element (TLE) targets to catalogue.

Examples of catalogue construction can be found in the Catalogue documentation.

Parameters:

lines (sequence of strings) – List of lines containing one or more TLEs (may also be file object)
tags (string or sequence of strings, optional) – Tag or list of tags to add to targets (strings will be split on whitespace)

Examples

Here are some ways to add TLE targets to a catalogue:

>>> from katpoint import Catalogue
>>> cat = Catalogue()
>>> cat.add_tle(open('gps-ops.txt'), tags='gps')
>>> lines = [
    'ISS DEB [TOOL BAG]\n',
    '1 33442U 98067BL  09195.86837279  .00241454  37518-4  34022-3 0  3424\n',
    '2 33442  51.6315 144.2681 0003376 120.1747 240.0135 16.05240536 37575\n'
    ]
>>> cat2.add_tle(lines)

property antenna: Default antenna used to calculate target positions.

closest_to(target, timestamp=None, antenna=None)

Determine target in catalogue that is closest to given target.

The comparison is based on the apparent angular separation between the targets, as seen from the specified antenna and at the given time instant.

Parameters:

target (Target) – Target with which catalogue targets are compared
timestamp (Time, Timestamp or equiv, optional) – Timestamp at which to evaluate target positions (defaults to now)
antenna (Antenna, optional) – Antenna which points at targets (defaults to default antenna)

Returns:

closest_target (Target or None) – Target in catalogue that is closest to given target, or None if catalogue is empty
min_dist (Angle) – Angular separation between target and closest_target

filter(tags=None, flux_limit: Unit('Jy') = None, flux_frequency: Unit('Hz') = None, az_limit: Unit('deg') = None, el_limit: Unit('deg') = None, dist_limit: Unit('deg') = None, proximity_targets=None, timestamp=None, antenna=None)

Filter catalogue on various criteria.

This returns a new catalogue containing the subset of targets that satisfy the given criteria. All criteria are evaluated at the same time instant. For real-time continuous filtering, consider using iterfilter() instead.

Parameters:

tags (string, or sequence of strings, optional) – Tag or list of tags which targets should have. Tags prepended with a tilde (~) indicate tags which targets should not have. The string may contain multiple tags separated by whitespace. If None or an empty list, all tags are accepted. Remember that the body type is also a tag.
flux_limit (Quantity, optional) – Allowed flux density range. If this is a single number, it is the lower limit, otherwise it takes the form [lower, upper]. If None, any flux density is accepted.
flux_frequency (Quantity, optional) – Frequency at which to evaluate the flux density
az_limit (Quantity, optional) – Allowed azimuth range. It takes the form [left, right], where left is the leftmost or starting azimuth, and right is the rightmost or ending azimuth. If right is less than left, the azimuth angles range around +-180. If None, any azimuth is accepted.
el_limit (Quantity, optional) – Allowed elevation range. If this is a single number, it is the lower limit, otherwise it takes the form [lower, upper]. If None, any elevation is accepted.
dist_limit (Quantity, optional) – Allowed range of angular distance to proximity targets. If this is a single number, it is the lower limit, otherwise it takes the form [lower, upper]. If None, any distance is accepted.
proximity_targets (Target, or sequence of Target) – Target or list of targets used in proximity filter
timestamp (Time, Timestamp or equiv, optional) – Timestamp at which to evaluate target positions (defaults to now). For iterfilter() the default is the current time at each iteration.
antenna (Antenna object, optional) – Antenna which points at targets (defaults to default antenna)

Returns:

subset – Filtered catalogue

Return type:

Catalogue

Raises:

ValueError – If some required parameters are missing or limits are invalid

Examples

Here are some ways to filter a catalogue:

>>> from katpoint import Catalogue, Antenna
>>> import astropy.units as u
>>> ant = Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
>>> targets = ['Sun, special', 'Moon, special', 'Jupiter, special']
>>> cat = Catalogue(targets, antenna=ant, flux_frequency=1500 * u.MHz)
>>> cat1 = cat.filter(el_limit=10 * u.deg)
>>> cat2 = cat.filter(az_limit=[150, -150] * u.deg)
>>> cat3 = cat.filter(flux_limit=10 * u.Jy)
>>> cat4 = cat.filter(tags='special ~radec')
>>> cat5 = cat.filter(dist_limit=5 * u.deg, proximity_targets=cat['Sun'])

property flux_frequency: Default frequency at which to evaluate flux density.

iterfilter(tags=None, flux_limit: Unit('Jy') = None, flux_frequency: Unit('Hz') = None, az_limit: Unit('deg') = None, el_limit: Unit('deg') = None, dist_limit: Unit('deg') = None, proximity_targets=None, timestamp=None, antenna=None)

Yield targets satisfying various criteria (generator function).

This returns a (generator-)iterator which returns targets satisfying various criteria, one at a time. The standard use of this method is in a for-loop (i.e. for target in cat.iterfilter(...):). This differs from the filter() method in that all time-dependent criteria (such as elevation) may be evaluated at the time of the specific iteration, and not in advance as with filter(). This simplifies finding the next suitable target during an extended observation of several targets.

Parameters:

tags (string, or sequence of strings, optional) – Tag or list of tags which targets should have. Tags prepended with a tilde (~) indicate tags which targets should not have. The string may contain multiple tags separated by whitespace. If None or an empty list, all tags are accepted. Remember that the body type is also a tag.
flux_limit (Quantity, optional) – Allowed flux density range. If this is a single number, it is the lower limit, otherwise it takes the form [lower, upper]. If None, any flux density is accepted.
flux_frequency (Quantity, optional) – Frequency at which to evaluate the flux density
az_limit (Quantity, optional) – Allowed azimuth range. It takes the form [left, right], where left is the leftmost or starting azimuth, and right is the rightmost or ending azimuth. If right is less than left, the azimuth angles range around +-180. If None, any azimuth is accepted.
el_limit (Quantity, optional) – Allowed elevation range. If this is a single number, it is the lower limit, otherwise it takes the form [lower, upper]. If None, any elevation is accepted.
dist_limit (Quantity, optional) – Allowed range of angular distance to proximity targets. If this is a single number, it is the lower limit, otherwise it takes the form [lower, upper]. If None, any distance is accepted.
proximity_targets (Target, or sequence of Target) – Target or list of targets used in proximity filter
timestamp (Time, Timestamp or equiv, optional) – Timestamp at which to evaluate target positions (defaults to now). For iterfilter() the default is the current time at each iteration.
antenna (Antenna object, optional) – Antenna which points at targets (defaults to default antenna)

Returns:

iter – The generator-iterator object which will return filtered targets

Return type:

iterator object

Raises:

ValueError – If some required parameters are missing or limits are invalid

Examples

Here are some ways to filter a catalogue iteratively:

>>> from katpoint import Catalogue, Antenna
>>> import astropy.units as u
>>> ant = Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
>>> targets = ['Sun, special', 'Moon, special', 'Jupiter, special']
>>> cat = Catalogue(targets, antenna=ant)
>>> for t in cat.iterfilter(el_limit=10 * u.deg):
        # Observe target t
        pass

remove(name)

Remove target from catalogue.

This removes the most recently added target with the given name from the catalogue. If the target is not in the catalogue, do nothing.

Parameters:: name (string) – Name of target to remove (may also be an alternate name of target)

save(filename)

Save catalogue to file in CSV format.

Parameters:: filename (string) – Name of file to write catalogue to (overwriting existing contents)

sort(key='name', ascending=True, flux_frequency: Unit('Hz') = None, timestamp=None, antenna=None)

Sort targets in catalogue.

This returns a new catalogue with the target list sorted according to the given key.

Parameters:

key ({'name', 'ra', 'dec', 'az', 'el', 'flux'}, optional) – Sort the targets according to this field
ascending ({True, False}, optional) – True if key should be sorted in ascending order
flux_frequency (Quantity, optional) – Frequency at which to evaluate the flux density
timestamp (Time, Timestamp or equiv, optional) – Timestamp at which to evaluate target positions (defaults to now)
antenna (Antenna object, optional) – Antenna which points at targets (defaults to default antenna)

Returns:

sorted – Sorted catalogue

Return type:

Catalogue object

Raises:

ValueError – If some required parameters are missing or key is unknown

visibility_list(timestamp=None, antenna=None, flux_frequency: Unit('Hz') = None, antenna2=None)

Print out list of targets in catalogue, sorted by decreasing elevation.

This prints out the name, azimuth and elevation of each target in the catalogue, in order of decreasing elevation. The motion of the target at the given timestamp is indicated by a character code, which is ‘/’ if the target is rising, ‘' if it is setting, and ‘-’ if it is stationary (i.e. if the elevation angle changes by less than 1 arcminute during the one-minute interval surrounding the timestamp).

The method indicates the horizon itself by a line of dashes. It also displays the target flux density if a frequency is supplied, and the delay and fringe period if a second antenna is supplied. It is useful to quickly see which targets are visible (or will be soon).

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp at which to evaluate target positions (defaults to now)
antenna (Antenna, optional) – Antenna which points at targets (defaults to default antenna)
flux_frequency (Quantity, optional) – Frequency at which to evaluate flux density
antenna2 (Antenna, optional) – Second antenna of baseline pair (baseline vector points from antenna to antenna2), used to calculate delays and fringe rates per target

katpoint.conversion module

Geodetic and spherical coordinate transformations, and angle conversions.

katpoint.conversion.angle_to_string(angle, show_unit=True, **kwargs)

Convert an Angle to string(s) while maintaining precision and compatibility.

This serialises angles to strings with high precision (1 micron @ 13000 km) while maintaining some compatibility with older katpoint angle strings. The main difference is that the numerical representation (sexagesimal or decimal) has a suffix indicating the unit (‘d’ for degree or ‘h’ for hour). This allows Astropy Angles to be constructed directly from it without the need for to_angle(). This suffix can be suppressed when generating strings for display purposes.

Extra keyword arguments are passed on to to_string() to control the appearance of the string to some extent, but there are restrictions. The only supported units are degree, hour and hourangle. The sexagesimal separator is fixed to ‘:’ but ignored when a decimal representation is selected instead (unlike in Astropy >= 5.0).

Parameters:

angle (Angle) – An Angle object (may be multidimensional)
show_unit (bool, optional) – True if the unit of the angle (‘h’ or ‘d’) is appended to the string
kwargs (dict, optional) – Extra keyword arguments for to_string()

Returns:

s – String(s) representing angle

Return type:

str or array of str

Raises:

ValueError – If angle / kwargs unit is not supported, or separator is not ‘:’

katpoint.conversion.azel_to_enu(az_rad, el_rad)

Convert (az, el) spherical coordinates to unit vector in ENU coordinates.

This converts horizontal spherical coordinates (azimuth and elevation angle) to a unit vector in the corresponding local east-north-up (ENU) coordinate system.

Parameters:

az_rad (float or array) – Azimuth and elevation angle, in radians
el_rad (float or array) – Azimuth and elevation angle, in radians

Returns:

e, n, u – East, North, Up coordinates of unit vector

Return type:

float or array

katpoint.conversion.ecef_to_enu(ref_lat_rad, ref_lon_rad, ref_alt_m, x_m, y_m, z_m)

Convert ECEF coordinates to ENU coordinates relative to reference location.

This converts earth-centered, earth-fixed (ECEF) cartesian coordinates to local east-north-up (ENU) coordinates relative to a given reference position. The reference position is specified by its geodetic latitude, longitude and altitude.

Parameters:

ref_lat_rad (float or array) – Geodetic latitude and longitude of reference position, in radians
ref_lon_rad (float or array) – Geodetic latitude and longitude of reference position, in radians
ref_alt_m (float or array) – Geodetic altitude of reference position, in metres above WGS84 ellipsoid
x_m (float or array) – X, Y, Z coordinates, in metres
y_m (float or array) – X, Y, Z coordinates, in metres
z_m (float or array) – X, Y, Z coordinates, in metres

Returns:

e_m, n_m, u_m – East, North, Up coordinates, in metres

Return type:

float or array

katpoint.conversion.ecef_to_lla(x_m, y_m, z_m)

Convert ECEF cartesian coordinates to WGS84 spherical coordinates.

This converts an earth-centered, earth-fixed (ECEF) cartesian position to a position on the Earth specified in geodetic latitude, longitude and altitude. This code assumes the WGS84 earth model.

Parameters:

x_m (float or array) – X, Y, Z coordinates, in metres
y_m (float or array) – X, Y, Z coordinates, in metres
z_m (float or array) – X, Y, Z coordinates, in metres

Returns:

lat_rad (float or array) – Latitude (customary geodetic, not geocentric), in radians
lon_rad (float or array) – Longitude, in radians
alt_m (float or array) – Altitude, in metres above WGS84 ellipsoid

Notes

Based on the most accurate algorithm according to Zhu [zhu], which is summarised by Kaplan [kaplan] and described in the Wikipedia entry [geo].

[zhu]

J. Zhu, “Conversion of Earth-centered Earth-fixed coordinates to geodetic coordinates,” Aerospace and Electronic Systems, IEEE Transactions on, vol. 30, pp. 957-961, 1994.

[kaplan]

Kaplan, “Understanding GPS: principles and applications,” 1 ed., Norwood, MA 02062, USA: Artech House, Inc, 1996.

[geo]

Wikipedia entry, “Geodetic system”, 2009.

katpoint.conversion.ecef_to_lla2(x_m, y_m, z_m)

Convert ECEF cartesian coordinates to WGS84 spherical coordinates.

This converts an earth-centered, earth-fixed (ECEF) cartesian position to a position on the Earth specified in geodetic latitude, longitude and altitude. This code assumes the WGS84 earth model.

Parameters:

x_m (float or array) – X, Y, Z coordinates, in metres
y_m (float or array) – X, Y, Z coordinates, in metres
z_m (float or array) – X, Y, Z coordinates, in metres

Returns:

lat_rad (float or array) – Latitude (customary geodetic, not geocentric), in radians
lon_rad (float or array) – Longitude, in radians
alt_m (float or array) – Altitude, in metres above WGS84 ellipsoid

Notes

This is a copy of the algorithm in the CONRAD codebase (from conradmisclib). It’s nearly identical to ecef_to_lla(), but returns lon/lat in different ranges.

katpoint.conversion.enu_to_azel(east, north, up)

Convert vector in ENU coordinates to (az, el) spherical coordinates.

This converts a vector in the local east-north-up (ENU) coordinate system to the corresponding horizontal spherical coordinates (azimuth and elevation angle). The ENU coordinates can be in any unit, as the vector length will be normalised in the conversion process.

Parameters:

east (float or array) – East, North, Up coordinates (any unit)
north (float or array) – East, North, Up coordinates (any unit)
up (float or array) – East, North, Up coordinates (any unit)

Returns:

az_rad, el_rad – Azimuth and elevation angle, in radians

Return type:

float or array

katpoint.conversion.enu_to_ecef(ref_lat_rad, ref_lon_rad, ref_alt_m, e_m, n_m, u_m)

Convert ENU coordinates relative to reference location to ECEF coordinates.

This converts local east-north-up (ENU) coordinates relative to a given reference position to earth-centered, earth-fixed (ECEF) cartesian coordinates. The reference position is specified by its geodetic latitude, longitude and altitude.

Parameters:

ref_lat_rad (float or array) – Geodetic latitude and longitude of reference position, in radians
ref_lon_rad (float or array) – Geodetic latitude and longitude of reference position, in radians
ref_alt_m (float or array) – Geodetic altitude of reference position, in metres above WGS84 ellipsoid
e_m (float or array) – East, North, Up coordinates, in metres
n_m (float or array) – East, North, Up coordinates, in metres
u_m (float or array) – East, North, Up coordinates, in metres

Returns:

x_m, y_m, z_m – X, Y, Z coordinates, in metres

Return type:

float or array

katpoint.conversion.enu_to_xyz(east, north, up, lat_rad)

Convert ENU to XYZ coordinates.

This converts a vector in the local east-north-up (ENU) coordinate system to the XYZ coordinate system used in radio astronomy (see e.g. [TMS]). The X axis is the intersection of the equatorial plane and the meridian plane through the reference point of the ENU system (and therefore is similar to ‘up’). The Y axis also lies in the equatorial plane to the east of X, and coincides with ‘east’. The Z axis points toward the north pole, and therefore is similar to ‘north’. The XYZ system is therefore a local version of the Earth-centred Earth-fixed (ECEF) system.

Parameters:

east (float or array) – East, North, Up coordinates of input vector
north (float or array) – East, North, Up coordinates of input vector
up (float or array) – East, North, Up coordinates of input vector
lat_rad (float or array) – Geodetic latitude of ENU / XYZ reference point, in radians

Returns:

x, y, z – X, Y, Z coordinates of output vector

Return type:

float or array

References

[TMS]

Thompson, Moran, Swenson, “Interferometry and Synthesis in Radio Astronomy,” 2nd ed., Wiley-VCH, 2004, pp. 86-89.

katpoint.conversion.hadec_to_enu(ha_rad, dec_rad, lat_rad)

Convert (ha, dec) spherical coordinates to unit vector in ENU coordinates.

This converts equatorial spherical coordinates (hour angle and declination) to a unit vector in the corresponding local east-north-up (ENU) coordinate system. The geodetic latitude of the observer is also required.

Parameters:

ha_rad (float or array) – Hour angle, declination and geodetic latitude, in radians
dec_rad (float or array) – Hour angle, declination and geodetic latitude, in radians
lat_rad (float or array) – Hour angle, declination and geodetic latitude, in radians

Returns:

e, n, u – East, North, Up coordinates of unit vector

Return type:

float or array

katpoint.conversion.lla_to_ecef(lat_rad, lon_rad, alt_m)

Convert WGS84 spherical coordinates to ECEF cartesian coordinates.

This converts a position on the Earth specified in geodetic latitude, longitude and altitude to earth-centered, earth-fixed (ECEF) cartesian coordinates. This code assumes the WGS84 earth model, described in [NIMA2004].

Parameters:

lat_rad (float or array) – Latitude (customary geodetic, not geocentric), in radians
lon_rad (float or array) – Longitude, in radians
alt_m (float or array) – Altitude, in metres above WGS84 ellipsoid

Returns:

x_m, y_m, z_m – X, Y, Z coordinates, in metres

Return type:

float or array

References

[NIMA2004]

National Imagery and Mapping Agency, “Department of Defense World Geodetic System 1984,” NIMA TR8350.2, Page 4-4, last updated June, 2004.

katpoint.conversion.strip_zeros(str_or_array_of_str): Remove trailing zeros and unnecessary decimal points from numerical strings.

katpoint.conversion.to_angle(s, sexagesimal_unit=Unit('deg'))

Construct an Angle with default units.

This creates an Angle with the following default units:

A number is in radians.

A decimal string (‘123.4’) is in degrees.

A sexagesimal string (‘12:34:56.7’ or ‘12 34 56.7’) has sexagesimal_unit, which defaults to degrees.

Parameters:

s (Angle or equivalent, string, float) – Anything accepted by Angle and also unitless strings and numbers
sexagesimal_unit (UnitBase or str, optional) – The unit applied to sexagesimal strings

Returns:

angle – Astropy Angle

Return type:

Angle

katpoint.delay module

katpoint.ephem_extra module

katpoint.flux module

Flux density model.

class katpoint.flux.FluxDensityModel(min_frequency: Unit('Hz'), max_frequency: Unit('Hz'), coefs)

Bases: object

Spectral flux density model.

This models the spectral flux density (or spectral energy distribtion - SED) of a radio source as:

log10(S) = a + b*log10(v) + c*log10(v)**2 + d*log10(v)**3 + e*exp(f*log10(v))

where S is the flux density in janskies (Jy) and v is the frequency in MHz. The model is based on the Baars polynomial [BGP1977] (up to a third- order term) and extended with an exponential term from the 1Jy catalogue [KWP+1981]. It is considered valid for a specified frequency range only. For any frequencies outside this range a value of NaN is returned.

It also models polarisation: an optional (I, Q, U, V) vector may be given to specify fractional Stokes parameters, which scale S. If not specified, the default is unpolarised (I = 1, Q = U = V = 0). It is recommended that I is left at 1, but it can be changed to model non-physical sources e.g. negative CLEAN components.

The object can be instantiated directly with the minimum and maximum frequencies of the valid frequency range and the model coefficients, or indirectly via a description string. This string contains the minimum frequency, maximum frequency and model coefficients as space-separated values (optionally with parentheses enclosing the entire string). Some examples:

'1000.0 2000.0 0.34 -0.85 -0.02'
'(1000.0 2000.0 0.34 -0.85 0.0 0.0 2.3 -1.0)'
'1000.0 2000.0 0.34 -0.85 0.0 0.0 2.3 -1.0  1.0 0.2 -0.1 0.0'

If less than the expected number of coefficients are provided, the rest are assumed to be zero, except that I is assumed to be one. If more than the expected number are provided, the extra coefficients are ignored, but a warning is shown.

Parameters:

min_frequency (Quantity) – Minimum and maximum frequency for which model is valid
max_frequency (Quantity) – Minimum and maximum frequency for which model is valid
coefs (sequence of floats, optional) – Model coefficients (a, b, c, d, e, f, I, Q, U, V), where missing coefficients at the end of the sequence are assumed to be zero (except for I, assumed to be one), and extra coefficients are ignored.

References

[BGP1977]

J.W.M. Baars, R. Genzel, I.I.K. Pauliny-Toth, A. Witzel, “The Absolute Spectrum of Cas A; An Accurate Flux Density Scale and a Set of Secondary Calibrators,” Astron. Astrophys., 61, 99-106, 1977.

[KWP+1981]

H. Kuehr, A. Witzel, I.I.K. Pauliny-Toth, U. Nauber, “A catalogue of extragalactic radio sources having flux densities greater than 1 Jy at 5 GHz,” Astron. Astrophys. Suppl. Ser., 45, 367-430, 1981.

property description: Complete string representation of object, sufficient to reconstruct it.

flux_density(frequency: Unit('Hz'))

Calculate Stokes I flux density for given observation frequency.

Parameters:: frequency (Quantity, optional) – Frequency at which to evaluate flux density
Returns:: flux_density – Flux density, or NaN Jy if frequency is out of range. The shape matches the input.
Return type:: Quantity

flux_density_stokes(frequency: Unit('Hz'))

Calculate full-Stokes flux density for given observation frequency.

Parameters:: frequency (Quantity, optional) – Frequency at which to evaluate flux density
Returns:: flux_density – Flux density, or NaN Jy if frequency is out of range. The shape matches the input with an extra trailing dimension of size 4 containing Stokes I, Q, U, V.
Return type:: Quantity

classmethod from_description(description)

Construct flux density model object from description string.

Parameters:: description (str) – String of space-separated parameters (optionally in parentheses)
Returns:: flux_model – Constructed flux density model object
Return type:: FluxDensityModel
Raises:: FluxError – If description has the wrong format

property iquv_scale: Fractional Stokes parameters which scale the flux density.

exception katpoint.flux.FluxError

Bases: ValueError

Exception for a flux parsing error.

katpoint.model module

Model base class.

This provides a base class for pointing and delay models, handling the loading, saving and display of parameters.

exception katpoint.model.BadModelFile

Bases: Exception

Unable to load model from config file (unrecognised format).

class katpoint.model.Model(params)

Bases: object

Base class for models (e.g. pointing and delay models).

The base class handles the construction / loading, saving, display and comparison of models. A Model consists of a sequence of Parameters and an optional header dict. A number of these parameters may be active, i.e. not equal to their default values.

Models can be constructed from description strings (fromstring()), sequences of parameter values (fromlist()), configuration files (fromfile()) or other similar models. The set() method automatically picks the correct constructor based on the input.

Parameter names and values may be accessed and modified via a dict-like interface mapping names to values.

Parameters:: params (sequence of Parameter objects) – Full set of model parameters in the expected order

property description: Compact but complete string representation (‘tostring’).

fromfile(file_like)

Load model from config file (both header and parameters).

Parameters:: file_like (object) – File-like object with readline() method representing config file
Raises:: BadModelFile – If file_like could not be read or parsed

fromlist(floats): Load model from sequence of floats.

fromstring(description): Load model from description string (parameters only).

keys(): List of parameter names in the expected order.

param_strs(): Justified (name, value, units, doc) strings for active parameters.

set(model=None)

Load parameter values from the appropriate source.

Parameters:: model (file-like or model object, sequence of floats, or string, optional) – Model specification. If this is a file-like or model object, load the model from it (including header). If this is a sequence of floats, accept it directly as the model parameters. If it is a string, interpret it as a comma-separated (or whitespace- separated) sequence of parameters in their string form (i.e. a description string). The default is an empty model.
Raises:: BadModelFile – If model is of incorrect type

tofile(file_like)

Save model to config file (both header and parameters).

Parameters:: file_like (object) – File-like object with write() method representing config file

values(): List of parameter values in the expected order (‘tolist’).

class katpoint.model.Parameter(name, units, doc, from_str=<class 'float'>, to_str=<class 'str'>, value=None, default_value=0.0)

Bases: object

Generic model parameter.

This represents a single model parameter, bundling together its attributes and enabling it to be read from a string and output to a string by getting and setting the value_str property.

Parameters:

name (string) – Parameter name
units (string) – Physical unit of parameter value
doc (string) – Documentation string describing parameter
from_str (function, signature float = f(string), optional) – Conversion function to extract parameter from string
to_str (function, signature string = f(float), optional) – Conversion function to express parameter as string
value (float, optional) – Parameter value (default_value by default, of course)
default_value (float, optional) – Parameter default value

value_str

property value_str: String form of parameter value used to convert it to/from a string.

katpoint.pointing module

Pointing model.

This implements a pointing model for a non-ideal antenna mount.

class katpoint.pointing.PointingModel(model=None)

Bases: Model

Correct pointing using model of non-ideal antenna mount.

The pointing model is the one found in the VLBI Field System and has the standard terms found in most pointing models, including the DSN and TPOINT models. These terms are numbered P1 to P22. The first 8 have a standard physical interpretation related to misalignment of the mount coordinate system and gravitational deformation, while the rest are ad hoc parameters that model remaining systematic effects in the pointing error residuals. Gravitational deformation may be considered ad hoc, too. The pointing model is specialised for an alt-az mount.

Parameters:: model (PointingModel, file-like, sequence of 22 floats, string, optional) – Model specification. If this is a model or file-like object, load the model from it. If this is a sequence of floats, accept it directly as the model parameters (defaults to sequence of zeroes). If it is a string, interpret it as a comma-separated (or whitespace-separated) sequence of parameters in their string form (i.e. a description string).

apply(az, el)

Apply pointing correction to requested (az, el) position(s).

Parameters:

az (float or sequence) – Requested azimuth angle(s), in radians
el (float or sequence) – Requested elevation angle(s), in radians

Returns:

pointed_az (float or array) – Azimuth angle(s), corrected for pointing errors, in radians
pointed_el (float or array) – Elevation angle(s), corrected for pointing errors, in radians

fit(az, el, delta_az, delta_el, sigma_daz=None, sigma_del=None, enabled_params=None, keep_disabled_params=False)

Fit pointing model parameters to observed offsets.

This fits the pointing model to a sequence of observed (az, el) offsets. A subset of the parameters can be fit, while the rest will either be kept (fixed) or zeroed. This is generally a good idea, as most of the parameters (P9 and above) are ad hoc and should only be enabled if there are sufficient evidence for them in the pointing error residuals.

While zeroing is the original behaviour, it is deprecated and will eventually be removed, since the user can always explicitly zero the model before calling fit() to get the same result. The contribution of fixed parameters will be subtracted from delta_az and delta_el before the enabled parameters are fit to the residual.

Standard errors can be specified for the input offsets, and will be reflected in the returned standard errors on the fitted parameters.

Parameters:

az (sequence of floats, length N) – Requested azimuth and elevation angles, in radians
el (sequence of floats, length N) – Requested azimuth and elevation angles, in radians
delta_az (sequence of floats, length N) – Corresponding observed azimuth and elevation offsets, in radians
delta_el (sequence of floats, length N) – Corresponding observed azimuth and elevation offsets, in radians
sigma_daz (sequence of floats, length N, optional) – Standard deviation of azimuth and elevation offsets, in radians
sigma_del (sequence of floats, length N, optional) – Standard deviation of azimuth and elevation offsets, in radians
enabled_params (sequence of ints or bools, optional) – List of model parameters that will be enabled during fitting, specified by a list of integer indices or boolean flags. The integers start at 1 and correspond to the P-number. The default is to select the 6 main parameters modelling coordinate misalignment, which are P1, P3, P4, P5, P6 and P7.
keep_disabled_params (bool, optional) – If True, disabled parameters (i.e. those that are not fitted) keep their values and are treated as fixed / frozen parameters. If False, they are zeroed. A future version of katpoint will force this to be True and remove the parameter.

Returns:

params (float array, shape (22,)) – Fitted model parameters (full model), in radians
sigma_params (float array, shape (22,)) – Standard errors on fitted parameters, in radians

Notes

Since the standard pointing model is linear in the model parameters, it is fit with linear least-squares techniques. This is done by creating a design matrix and solving the linear system via singular value decomposition (SVD), as explained in [PTV+1992].

References

[PTV+1992]

Press, Teukolsky, Vetterling, Flannery, “Numerical Recipes in C,” 2nd Ed., pp. 671-681, 1992. Section 15.4: “General Linear Least Squares”, available at http://www.nrbook.com/a/bookcpdf/c15-4.pdf

offset(az, el)

Obtain pointing offset at requested (az, el) position(s).

Parameters:

az (float or sequence) – Requested azimuth angle(s), in radians
el (float or sequence) – Requested elevation angle(s), in radians

Returns:

delta_az (float or array) – Offset(s) that has to be added to azimuth to correct it, in radians
delta_el (float or array) – Offset(s) that has to be added to elevation to correct it, in radians

Notes

The model is based on poclb/fln.c and poclb/flt.c in Field System version 9.9.0. The C implementation differs from the official description in [Him1993], introducing minor changes to the ad hoc parameters. In this implementation, the angle phi is fixed at 90 degrees, which hard-codes the model for a standard alt-az mount.

The model breaks down at the pole of the alt-az mount, which is at zenith (an elevation angle of 90 degrees). At zenith, the azimuth of the antenna is undefined, and azimuth offsets produced by the pointing model may become arbitrarily large close to zenith. To avoid this singularity, the azimuth offset is capped by adjusting the elevation away from 90 degrees specifically in its calculation. This adjustment occurs within 6 arcminutes of zenith.

References

[Him1993]

Himwich, “Pointing Model Derivation,” Mark IV Field System Reference Manual, Version 8.2, 1 September 1993.

reverse(pointed_az, pointed_el)

Remove pointing correction from (az, el) coordinate(s).

This undoes a pointing correction that resulted in the given (az, el) coordinates. It is the inverse of apply().

Parameters:

pointed_az (float or sequence) – Azimuth angle(s), corrected for pointing errors, in radians
pointed_el (float or sequence) – Elevation angle(s), corrected for pointing errors, in radians

Returns:

az (float or array) – Azimuth angle(s) before pointing correction, in radians
el (float or array) – Elevation angle(s) before pointing correction, in radians

katpoint.projection module

Spherical projections.

This module provides a basic set of routines that projects spherical coordinates onto a plane and deprojects the plane coordinates back to the sphere. It complements the astropy module, which focuses on transformations between various spherical coordinate systems instead. The routines are derived from AIPS, as documented in [Gre1993a] and [Gre1993b] and implemented in the DIRCOS and NEWPOS routines in the 31DEC08 release, with minor improvements. The projections are referred to by their AIPS (and FITS) codes, as also described in [CB2002] and implemented in Calabretta’s WCSLIB. The (x, y) coordinates in this module correspond to the (L, M) direction cosines calculated in [Gre1993a] and [Gre1993b].

Any spherical coordinate system can be used in the projections, as long as the target and reference points are expressed in the same system of longitude and latitude. The latitudinal coordinate is referred to as elevation, but could also be geodetic latitude or declination. It ranges between -pi/2 and pi/2 radians, with zero representing the equator, pi/2 the north pole and -pi/2 the south pole.

The longitudinal coordinate is referred to as azimuth, but could also be geodetic longitude or right ascension. It can be any value in radians. The fact that azimuth increases clockwise while right ascension and geodetic longitude increase anti-clockwise is not a concern, as it simply changes the direction of the x-axis on the plane (which is defined to point in the direction of increasing longitudinal coordinate).

The projection plane is tangent to the sphere at the reference point, which also coincides with the origin of the plane. All projections in this module (except the plate carree projection) are zenithal or azimuthal projections that map the sphere directly onto this plane. The y coordinate axis in the plane points along the reference meridian of longitude towards the north pole of the sphere (in the direction of increasing elevation). The x coordinate axis is perpendicular to it and points in the direction of increasing azimuth (which may be towards the right or left, depending on whether the azimuth coordinate increases clockwise or anti-clockwise).

If the reference point is at a pole, its azimuth angle is undefined and the reference meridian is therefore arbitrary. Nevertheless, the (x, y) axes are still aligned to this meridian, with the y axis pointing away from the intersection of the meridian with the equator for the north pole, and towards the intersection for the south pole. The axes at the poles can therefore be seen as a continuation of the axes obtained while moving along the reference meridian from the equator to the pole.

The following projections are implemented:

Orthographic (SIN): This is the standard projection in aperture synthesis radio astronomy, as it ties in closely with the 2-D Fourier imaging equation and the resultant (l, m) coordinate system. It is the simple orthographic projection of AIPS and [Gre1993a], not the generalised slant orthographic projection of [CB2002].
Gnomonic (TAN): This is commonly used in optical astronomy. Great circles are projected as straight lines, so that the shortest distance between two points on the sphere is represented as a straight line interval (non-uniformly divided though).
Zenithal equidistant (ARC): This is commonly used for single-dish maps, and is obtained if relative (cross-el, el) coordinates are directly plotted (cross-elevation is azimuth scaled by the cosine of elevation). It preserves angular distances from the reference point.
Stereographic (STG): This is useful to represent polar regions and large fields. It preserves angles and circles.
Plate carree (CAR): This is a very simple cylindrical projection that directly maps azimuth and elevation to a rectangular (x, y) grid, and returns offsets from the reference point on this plane. The x offset is therefore equal to the azimuth offset, while the y offset is equal to the elevation offset. It does not preserve angles, distances or circles.
Swapped orthographic (SSN): This is the standard SIN projection with the roles of reference and target points reversed. It is useful for holography and other beam pattern measurements where a dish moves relative to a fixed beacon but the beam pattern is referenced to the boresight of the moving dish.

Each projection typically has restrictions on the input domain and output range of values, which are highlighted in the docstrings of the individual functions. Out-of-range input values either raise an exception or are replaced with NaNs or the closest valid values, based on the last OutOfRange.set_treatment() call (which can also be used as a context manager).

Each function in this module is also vectorised, and will operate on single floating-point values as well as numpy arrays of floats. The standard numpy broadcasting rules apply. It is therefore possible to have an array of target points and a single reference point, or vice versa.

All coordinates in this module are in radians.

These projections are normally accessed via the katpoint.Target object by calling its katpoint.Target.sphere_to_plane() and katpoint.Target.plane_to_sphere() methods, e.g.:

tgt = katpoint.Target('Sun, special')
ant = katpoint.Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
tgt.antenna = ant
# Map from (ra, dec) coordinates to (l, m) plane with target as phase centre
l, m = tgt.sphere_to_plane(ra, dec, projection_type='SIN', coord_system='radec')
# Find (az, el) coordinates that scans dish relative to target position
az, el = tgt.plane_to_sphere(x, y, projection_type='ARC', coord_system='azel')

Alternatively they can be called directly:

x, y = katpoint.sphere_to_plane['ARC'](az0, el0, az, el)
az, el = katpoint.plane_to_sphere['ARC'](az0, el0, x, y)

[Gre1993a] (1,2,3)

Greisen, “Non-linear Coordinate Systems in AIPS,” AIPS Memo 27, 1993.

[Gre1993b] (1,2)

Greisen, “Additional Non-linear Coordinates in AIPS,” AIPS Memo 46, 1993.

[CB2002] (1,2)

Calabretta, Greisen, “Representations of celestial coordinates in FITS. II,” Astronomy & Astrophysics, vol. 395, pp. 1077-1122, 2002.

exception katpoint.projection.OutOfRangeError

Bases: ValueError

A numeric value is out of range.

katpoint.projection.get_out_of_range_treatment(): Return the current treatment of out-of-range values.

katpoint.projection.out_of_range_context(treatment)

Change the treatment of out-of-range values temporarily via context manager.

Parameters:: treatment (str) – Temporary treatment

Notes

For a description of available treatments, see set_out_of_range_treatment.

Examples

>>> with out_of_range_context(treatment='raise'):
...     plane_to_sphere_sin(0.0, 0.0, 0.0, 2.0)
Traceback (most recent call last):
File "<stdin>", line 2, in <module>
OutOfRangeError: Length of (x, y) vector bigger than 1.0

>>> with out_of_range_context(treatment='nan'):
...     plane_to_sphere_sin(0.0, 0.0, 0.0, 2.0)
(nan, nan)

>>> with out_of_range_context(treatment='clip'):
...     plane_to_sphere_sin(0.0, 0.0, 0.0, 2.0)
(0.0, np.pi / 2.0)

katpoint.projection.plane_to_sphere_arc(az0, el0, x, y)

Deproject plane to sphere using zenithal equidistant (ARC) projection.

The input (x, y) coordinates should lie within or on a circle of radius pi radians centred on the origin in the plane. The target point can be anywhere on the sphere.

Please read the module documentation for the interpretation of the input parameters and return values.

Parameters:

az0 (float or array) – Azimuth / right ascension / longitude of reference point(s), in radians
el0 (float or array) – Elevation / declination / latitude of reference point(s), in radians
x (float or array) – Azimuth-like coordinate(s) on plane, in radians
y (float or array) – Elevation-like coordinate(s) on plane, in radians

Returns:

az (float or array) – Azimuth / right ascension / longitude of target point(s), in radians
el (float or array) – Elevation / declination / latitude of target point(s), in radians

Raises:

OutOfRangeError – If elevation el0 is out of range or the radius of (x, y) > pi, and out-of-range treatment is ‘raise’

katpoint.projection.plane_to_sphere_car(az0, el0, x, y)

Deproject plane to sphere using plate carree (CAR) projection.

The input (x, y) coordinates are unrestricted. The target point can likewise be anywhere on the sphere.

Please read the module documentation for the interpretation of the input parameters and return values.

Parameters:

az0 (float or array) – Azimuth / right ascension / longitude of reference point(s), in radians
el0 (float or array) – Elevation / declination / latitude of reference point(s), in radians
x (float or array) – Azimuth-like coordinate(s) on plane, in radians
y (float or array) – Elevation-like coordinate(s) on plane, in radians

Returns:

az (float or array) – Azimuth / right ascension / longitude of target point(s), in radians
el (float or array) – Elevation / declination / latitude of target point(s), in radians

katpoint.projection.plane_to_sphere_sin(az0, el0, x, y)

Deproject plane to sphere using orthographic (SIN) projection.

The orthographic projection requires the (x, y) coordinates to lie within or on the unit circle. The target point is constrained to lie within the hemisphere centred on the reference point.

This is the standard deprojection in aperture synthesis radio astronomy as found in the 2-D Fourier imaging equation. The (x, y) coordinates are equivalent to the (l, m) coordinates found in the image plane when the reference point is treated as the phase centre and the celestial longitude and latitude are picked to be right ascension and declination, respectively.

Please read the module documentation for the interpretation of the input parameters and return values.

Parameters:

az0 (float or array) – Azimuth / right ascension / longitude of reference point(s), in radians
el0 (float or array) – Elevation / declination / latitude of reference point(s), in radians
x (float or array) – Azimuth-like coordinate(s) on plane (equivalent to l), in radians
y (float or array) – Elevation-like coordinate(s) on plane (equivalent to m), in radians

Returns:

az (float or array) – Azimuth / right ascension / longitude of target point(s), in radians
el (float or array) – Elevation / declination / latitude of target point(s), in radians

Raises:

OutOfRangeError – If elevation el0 is out of range or the radius of (x, y) > 1.0, and out-of-range treatment is ‘raise’

Notes

This implements the original SIN projection as in AIPS, not the generalised ‘slant orthographic’ projection as in WCSLIB.

katpoint.projection.plane_to_sphere_ssn(az0, el0, x, y)

Deproject plane to sphere using swapped orthographic (SSN) projection.

The swapped orthographic deprojection has more restrictions than the corresponding orthographic (SIN) deprojection:

The (x, y) coordinates should lie within or on the unit circle
The magnitude of the x coordinate should be less than cos(el0) radians
The y coordinate should satisfy
- \(y \ge -\sqrt{\cos(\text{el0})^2 - x^2}, \text{el0} \ge 0\), and
- \(y \le \sqrt{\cos(\text{el0})^2 - x^2}, \text{el0} < 0\),
to ensure that the target elevation is within pi/2 radians of reference elevation - the y domain is therefore bounded by two semicircles with radii 1 and cos(el0), respectively
The target azimuth will be within pi/2 radians of the reference azimuth

This deprojection is useful for holography and other beam measurements where a dish moves relative to a fixed beacon but the beam pattern is referenced to the boresight of the moving dish. In this scenario the fixed beacon / source would be the reference point (as observed by the tracking antenna in holography) while the scanning antenna follows the target point.

Please read the module documentation for the interpretation of the input parameters and return values.

Parameters:

az0 (float or array) – Azimuth / right ascension / longitude of reference point(s), in radians
el0 (float or array) – Elevation / declination / latitude of reference point(s), in radians
x (float or array) – Azimuth-like coordinate(s) on plane (similar to l), in radians
y (float or array) – Elevation-like coordinate(s) on plane (similar to m), in radians

Returns:

az (float or array) – Azimuth / right ascension / longitude of target point(s), in radians
el (float or array) – Elevation / declination / latitude of target point(s), in radians

Raises:

OutOfRangeError – If elevation el0 is out of range or (x, y) is outside valid domain, and out-of-range treatment is ‘raise’

Notes

This projection was originally introduced by Mattieu de Villiers for use in holography experiments.

katpoint.projection.plane_to_sphere_stg(az0, el0, x, y)

Deproject plane to sphere using stereographic (STG) projection.

The input (x, y) coordinates are unrestricted. The target point can be anywhere on the sphere.

Please read the module documentation for the interpretation of the input parameters and return values.

Parameters:

az0 (float or array) – Azimuth / right ascension / longitude of reference point(s), in radians
el0 (float or array) – Elevation / declination / latitude of reference point(s), in radians
x (float or array) – Azimuth-like coordinate(s) on plane, in radians
y (float or array) – Elevation-like coordinate(s) on plane, in radians

Returns:

az (float or array) – Azimuth / right ascension / longitude of target point(s), in radians
el (float or array) – Elevation / declination / latitude of target point(s), in radians

Raises:

OutOfRangeError – If elevation el0 is out of range and out-of-range treatment is ‘raise’

katpoint.projection.plane_to_sphere_tan(az0, el0, x, y)

Deproject plane to sphere using gnomonic (TAN) projection.

The input (x, y) coordinates are unrestricted. The returned target point is constrained to lie within the hemisphere centred on the reference point.

Please read the module documentation for the interpretation of the input parameters and return values.

Parameters:

az0 (float or array) – Azimuth / right ascension / longitude of reference point(s), in radians
el0 (float or array) – Elevation / declination / latitude of reference point(s), in radians
x (float or array) – Azimuth-like coordinate(s) on plane, in radians
y (float or array) – Elevation-like coordinate(s) on plane, in radians

Returns:

az (float or array) – Azimuth / right ascension / longitude of target point(s), in radians
el (float or array) – Elevation / declination / latitude of target point(s), in radians

Raises:

OutOfRangeError – If elevation el0 is out of range and out-of-range treatment is ‘raise’

katpoint.projection.safe_scale(x, y, new_radius)

Scale the length of the 2D (x, y) vector to a new radius in a safe way.

This handles both scalars and arrays, and maps the origin to (new_radius, 0).

Parameters:

x (float or array) – Coordinates of 2D vector(s) (unchanged by this function)
y (float or array) – Coordinates of 2D vector(s) (unchanged by this function)
new_radius (float or array) – Desired length of output vector(s)

Returns:

out_x, out_y – Coordinates of 2D vector(s) guaranteed to have length new_radius

Return type:

float or array

katpoint.projection.set_out_of_range_treatment(treatment)

Change the treatment of out-of-range values (permanently).

The supported treatments are:

‘raise’: raise OutOfRangeError (the default)
‘nan’: replace out-of-range values with NaNs
‘clip’: replace out-of-range values with nearest valid values

Parameters:: treatment ({'raise', 'nan', 'clip'}) – New treatment
Returns:: previous_treatment – An object that can be passed to set_out_of_range_treatment to restore the previous treatment
Return type:: object
Raises:: ValueError – If treatment is not a recognised option

katpoint.projection.sphere_to_ortho(az0, el0, az, el, min_cos_theta=None)

Do calculations common to all zenithal/azimuthal projections.

This does a basic orthographic (SIN) projection and also returns the angular separation / native latitude theta in cosine form, which can be used to construct many other projections. The angular separation is optionally checked against a projection-specific limit, and the (x, y) outputs are treated accordingly.

Parameters:

az0 (float or array) – Azimuth / right ascension / longitude of reference point(s), in radians
el0 (float or array) – Elevation / declination / latitude of reference point(s), in radians
az (float or array) – Azimuth / right ascension / longitude of target point(s), in radians
el (float or array) – Elevation / declination / latitude of target point(s), in radians
min_cos_theta (float, optional) – Limit on angular separation of target and reference, used to clip (x, y)

Returns:

ortho_x (float or array) – Azimuth-like coordinate(s) on plane (equivalent to l), in radians
ortho_y (float or array) – Elevation-like coordinate(s) on plane (equivalent to m), in radians
cos_theta (float or array) – Angular separation of target and reference points, expressed as cosine

katpoint.projection.sphere_to_plane_arc(az0, el0, az, el)

Project sphere to plane using zenithal equidistant (ARC) projection.

The target point can be anywhere on the sphere. The output (x, y) coordinates are constrained to lie within or on a circle of radius pi radians centred on the origin in the plane.

Please read the module documentation for the interpretation of the input parameters and return values.

Parameters:

az0 (float or array) – Azimuth / right ascension / longitude of reference point(s), in radians
el0 (float or array) – Elevation / declination / latitude of reference point(s), in radians
az (float or array) – Azimuth / right ascension / longitude of target point(s), in radians
el (float or array) – Elevation / declination / latitude of target point(s), in radians

Returns:

x (float or array) – Azimuth-like coordinate(s) on plane, in radians
y (float or array) – Elevation-like coordinate(s) on plane, in radians

Raises:

OutOfRangeError – If an elevation is out of range and out-of-range treatment is ‘raise’

katpoint.projection.sphere_to_plane_car(az0, el0, az, el)

Project sphere to plane using plate carree (CAR) projection.

The target point can be anywhere on the sphere. The output (x, y) coordinates are likewise unrestricted.

Please read the module documentation for the interpretation of the input parameters and return values.

Parameters:

az0 (float or array) – Azimuth / right ascension / longitude of reference point(s), in radians
el0 (float or array) – Elevation / declination / latitude of reference point(s), in radians
az (float or array) – Azimuth / right ascension / longitude of target point(s), in radians
el (float or array) – Elevation / declination / latitude of target point(s), in radians

Returns:

x (float or array) – Azimuth-like coordinate(s) on plane, in radians
y (float or array) – Elevation-like coordinate(s) on plane, in radians

katpoint.projection.sphere_to_plane_sin(az0, el0, az, el)

Project sphere to plane using orthographic (SIN) projection.

The orthographic projection requires the target point to be within the hemisphere centred on the reference point. The angular separation between the target and reference points should be less than or equal to pi/2 radians. The output (x, y) coordinates are constrained to lie within or on the unit circle in the plane.

This is the standard projection in aperture synthesis radio astronomy as found in the 2-D Fourier imaging equation. The (x, y) coordinates are equivalent to the (l, m) coordinates found in the image plane when the reference point is treated as the phase centre and the celestial longitude and latitude are picked to be right ascension and declination, respectively.

Please read the module documentation for the interpretation of the input parameters and return values.

Parameters:

az0 (float or array) – Azimuth / right ascension / longitude of reference point(s), in radians
el0 (float or array) – Elevation / declination / latitude of reference point(s), in radians
az (float or array) – Azimuth / right ascension / longitude of target point(s), in radians
el (float or array) – Elevation / declination / latitude of target point(s), in radians

Returns:

x (float or array) – Azimuth-like coordinate(s) on plane (equivalent to l), in radians
y (float or array) – Elevation-like coordinate(s) on plane (equivalent to m), in radians

Raises:

OutOfRangeError – If an elevation is out of range or target is too far from reference, and out-of-range treatment is ‘raise’

Notes

This implements the original SIN projection as in AIPS, not the generalised ‘slant orthographic’ projection as in WCSLIB.

katpoint.projection.sphere_to_plane_ssn(az0, el0, az, el)

Project sphere to plane using swapped orthographic (SSN) projection.

This is identical to the usual orthographic (SIN) projection, but with the roles of the reference point (az0, el0) and target point (az, el) swapped. It has the same restrictions as the orthographic projection, i.e. the angular separation between the target and reference points should be less than or equal to pi/2 radians. The output (x, y) coordinates are also constrained to lie within or on the unit circle in the plane.

This projection is useful for holography and other beam pattern measurements where a dish moves relative to a fixed beacon but the beam pattern is referenced to the boresight of the moving dish. In this scenario the fixed beacon / source would be the reference point (as observed by the tracking antenna in holography) while the scanning antenna follows the target point.

Please read the module documentation for the interpretation of the input parameters and return values.

Parameters:

az0 (float or array) – Azimuth / right ascension / longitude of reference point(s), in radians
el0 (float or array) – Elevation / declination / latitude of reference point(s), in radians
az (float or array) – Azimuth / right ascension / longitude of target point(s), in radians
el (float or array) – Elevation / declination / latitude of target point(s), in radians

Returns:

x (float or array) – Azimuth-like coordinate(s) on plane (similar to l), in radians
y (float or array) – Elevation-like coordinate(s) on plane (similar to m), in radians

Raises:

OutOfRangeError – If an elevation is out of range or target is too far from reference, and out-of-range treatment is ‘raise’

Notes

This projection was originally introduced by Mattieu de Villiers for use in holography experiments.

katpoint.projection.sphere_to_plane_stg(az0, el0, az, el)

Project sphere to plane using stereographic (STG) projection.

The target point can be anywhere on the sphere except in a small region diametrically opposite the reference point, which get mapped to infinity. The output (x, y) coordinates are unrestricted.

Please read the module documentation for the interpretation of the input parameters and return values.

Parameters:

az0 (float or array) – Azimuth / right ascension / longitude of reference point(s), in radians
el0 (float or array) – Elevation / declination / latitude of reference point(s), in radians
az (float or array) – Azimuth / right ascension / longitude of target point(s), in radians
el (float or array) – Elevation / declination / latitude of target point(s), in radians

Returns:

x (float or array) – Azimuth-like coordinate(s) on plane, in radians
y (float or array) – Elevation-like coordinate(s) on plane, in radians

Raises:

OutOfRangeError – If an elevation is out of range or target point opposite to reference, and out-of-range treatment is ‘raise’

katpoint.projection.sphere_to_plane_tan(az0, el0, az, el)

Project sphere to plane using gnomonic (TAN) projection.

The gnomonic projection requires the target point to be within the hemisphere centred on the reference point. The angular separation between the target and reference points should be less than pi/2 radians. The output (x, y) coordinates are unrestricted.

Please read the module documentation for the interpretation of the input parameters and return values.

Parameters:

az0 (float or array) – Azimuth / right ascension / longitude of reference point(s), in radians
el0 (float or array) – Elevation / declination / latitude of reference point(s), in radians
az (float or array) – Azimuth / right ascension / longitude of target point(s), in radians
el (float or array) – Elevation / declination / latitude of target point(s), in radians

Returns:

x (float or array) – Azimuth-like coordinate(s) on plane, in radians
y (float or array) – Elevation-like coordinate(s) on plane, in radians

Raises:

OutOfRangeError – If an elevation is out of range or target is too far from reference, and out-of-range treatment is ‘raise’

katpoint.projection.treat_out_of_range_values(x, err_msg, lower=None, upper=None)

Apply treatment to any out-of-range values in x.

Parameters:

x (real number or array-like of real numbers) – Input values (left untouched)
err_msg (string) – Error message passed to exception if treatment is ‘raise’
lower (real number or None, optional) – Bounds for values in x (specify at least one bound!)
upper (real number or None, optional) – Bounds for values in x (specify at least one bound!)

Returns:

treated_x – Treated values (guaranteed to be in range or NaN)

Return type:

float or array of float

Raises:

OutOfRangeError – If any values in x are out of range and treatment is ‘raise’

Notes

If a value is out of bounds by less than an absolute tolerance related to the machine precision, it is considered a rounding error. It is not treated as out-of-range to avoid false alarms, but instead silently clipped to ensure that all returned data is in the valid range.

katpoint.refraction module

Refraction correction.

This implements corrections for refractive bending and propagation delay in the atmosphere (mostly the troposphere and stratosphere).

class katpoint.refraction.GlobalMappingFunction(location)

Bases: object

Function that describes the elevation dependence of atmospheric delay.

This maps zenith delays to any elevation angle, based on the site coordinates and the day of year. It provides separate methods for the “dry” (hydrostatic) and “wet” (non-hydrostatic) components of the troposphere and stratosphere.

Parameters:: location (EarthLocation) – Location on Earth of observer (used in global weather model)

Notes

This is a direct translation of the GMF11 subroutine in the atmospheric module (catmm.f) of Calc 11, which in turn is based on Fortran code associated with [Boehm2006]. This paper describes the Global Mapping Function (GMF), a static model describing average weather conditions as a function of latitude, longitude, height and the day of year, which was fit to three years of global weather data. This is a refinement of Niell’s mapping function [Niell1996] and shares some of its formulas.

References

[Boehm2006]

J. Boehm, A. Niell, P. Tregoning, H. Schuh, “Global Mapping Function (GMF): A new empirical mapping function based on numerical weather model data,” Geophysical Research Letters, vol. 33, no. L07304, Apr 2006. DOI: 10.1029/2005GL025546

[Niell1996]

A.E. Niell, “Global mapping functions for the atmosphere delay at radio wavelengths,” Journal of Geophysical Research: Solid Earth, vol. 101, no. B2, pp. 3227–3246, Feb 1996. DOI: 10.1029/95JB03048

hydrostatic(elevation: Unit('rad'), timestamp)

Perform mapping for “dry” (hydrostatic) component of the atmosphere.

Parameters:

elevation (Quantity or) – Angle Elevation angle
timestamp (Time, Timestamp or equivalent) – Observation time (to incorporate seasonal weather patterns)

Returns:

gmf – Scale factor that turns zenith delay into delay at elevation angle

Return type:

Quantity

wet(elevation: Unit('rad'), timestamp)

Perform mapping for “wet” (non-hydrostatic) component of the atmosphere.

Parameters:

elevation (Quantity or) – Angle Elevation angle
timestamp (Time, Timestamp or equivalent) – Observation time (to incorporate seasonal weather patterns)

Returns:

gmf – Scale factor that turns zenith delay into delay at elevation angle

Return type:

Quantity

class katpoint.refraction.RefractionCorrection(model='VLBI Field System')

Bases: object

Correct pointing for refractive bending in atmosphere.

This uses the specified refraction model to calculate a correction to a given elevation angle to account for refractive bending in the atmosphere, based on surface weather measurements. The refraction correction can also be undone, usually to refer the actual antenna position to the coordinate frame before corrections were applied.

Parameters:: model (string, optional) – Name of refraction model to use
Raises:: ValueError – If the specified refraction model is unknown

apply(el, temperature_C, pressure_hPa, humidity_percent)

Apply refraction correction to elevation angle.

Each input parameter can either be a scalar value or an array of values, as long as all arrays are of the same shape.

Parameters:

el (float or array) – Requested elevation angle(s), in radians
temperature_C (float or array) – Ambient air temperature at surface, in degrees Celsius
pressure_hPa (float or array) – Total barometric pressure at surface, in hectopascal (hPa) or millibars
humidity_percent (float or array) – Relative humidity at surface, as a percentage in range [0, 100]

Returns:

refracted_el – Elevation angle(s), corrected for refraction, in radians

Return type:

float or array

reverse(refracted_el, temperature_C, pressure_hPa, humidity_percent)

Remove refraction correction from elevation angle.

This undoes a refraction correction that resulted in the given elevation angle. It is the inverse of apply().

Parameters:

refracted_el (float or array) – Elevation angle(s), corrected for refraction, in radians
temperature_C (float or array) – Ambient air temperature at surface, in degrees Celsius
pressure_hPa (float or array) – Total barometric pressure at surface, in hectopascal (hPa) or millibars
humidity_percent (float or array) – Relative humidity at surface, as a percentage in range [0, 100]

Returns:

el – Elevation angle(s) before refraction correction, in radians

Return type:

float or array

class katpoint.refraction.SaastamoinenZenithDelay(location)

Bases: object

Zenith delay due to the neutral gas in the troposphere and stratosphere.

This provides separate methods for the “dry” (hydrostatic) and “wet” (non-hydrostatic) components of the atmosphere.

Parameters:: location (EarthLocation) – Location on Earth of observer (used to correct local gravity)

Notes

This is a direct translation of the SASTD and SASTW subroutines in the atmospheric module (catmm.f) of Calc 11. It is based on the formulas of Saastamoinen [Saas1972] as implemented by Davis et al [Davis1985]. The saturation water vapour pressure is calculated by the venerable but still practical August-Roche-Magnus formula as discussed in [Murray1967].

References

[Saas1972]

J. Saastamoinen, “Atmospheric correction for the troposphere and stratosphere in radio ranging satellites,” in The Use of Artificial Satellites for Geodesy (Geophysical Monograph Series), edited by S. W. Henriksen et al, Washington, D.C., vol. 15, pp. 247-251, 1972. DOI: 10.1029/GM015p0247

[Davis1985]

J. L. Davis, T. A. Herring, I. I. Shapiro, A. E. E. Rogers, G. Elgered, “Geodesy by radio interferometry: Effects of atmospheric modeling errors on estimates of baseline length,” Radio Science, vol. 20, no. 6, pp. 1593-1607, 1985. DOI: 10.1029/rs020i006p01593

[Murray1967]

F. W. Murray, “On the computation of saturation vapor pressure,” Journal of Applied Meteorology, vol. 6, no. 1, pp. 203-204, Feb 1967. DOI: 10.1175/1520-0450(1967)006<0203:OTCOSV>2.0.CO;2

hydrostatic(pressure: Unit('hPa'))

Zenith delay due to “dry” (hydrostatic) component of the atmosphere.

Parameters:: pressure (Quantity) – Total barometric pressure at surface
Returns:: delay – Zenith delay due to hydrostatic component
Return type:: Quantity

wet(temperature: Unit('deg_C'), relative_humidity: Unit(dimensionless))

Zenith delay due to “wet” (non-hydrostatic) component of atmosphere.

Parameters:

temperature (Quantity) – Ambient air temperature at surface
relative_humidity (Quantity or float or array) – Relative humidity at surface, as a fraction in range [0, 1]

Returns:

delay – Zenith delay due to non-hydrostatic component

Return type:

Quantity

class katpoint.refraction.TroposphericDelay(location, model_id='SaastamoinenZenithDelay-GlobalMappingFunction')

Bases: object

Propagation delay due to neutral gas in the troposphere and stratosphere.

Set up a tropospheric delay model as specified by the model ID with format:

"<zenith delay>-<mapping function>[-<hydrostatic/wet>]"

This picks an appropriate zenith delay formula and mapping function, and optionally restricts the delays to hydrostatic or wet components only. The delays are calculated by calling this object like a function.

Parameters:

location (EarthLocation) – Location on Earth of observer
model_id (str, optional) – Unique identifier of tropospheric model (defaults to the only model implemented so far)

katpoint.refraction.refraction_offset_vlbi(el, temperature_C, pressure_hPa, humidity_percent)

Calculate refraction correction using model in VLBI Field System.

This uses the refraction model in the VLBI Field System to calculate a correction to a given elevation angle to account for refractive bending in the atmosphere, based on surface weather measurements. Each input parameter can either be a scalar value or an array of values, as long as all arrays are of the same shape.

Parameters:

el (float or array) – Requested elevation angle(s), in radians
temperature_C (float or array) – Ambient air temperature at surface, in degrees Celsius
pressure_hPa (float or array) – Total barometric pressure at surface, in hectopascal (hPa) or millibars
humidity_percent (float or array) – Relative humidity at surface, as a percentage in range [0, 100]

Returns:

el_offset – Refraction offset(s) in radians, which needs to be added to elevation angle(s) to correct it

Return type:

float or array

Notes

The code is based on poclb/refrwn.c in Field System version 9.9.2, which was added on 2006-11-15. This is a C version (with typos fixed) of the Fortran version in polb/refr.f. As noted in the Field System documentation [Him1993b], the refraction model originated with the Haystack pointing system. A description of the model can be found in [Clark1966], which in turn references [IH1963] as the ultimate source.

References

[Him1993b]

E. Himwich, “Station Programs,” Mark IV Field System Reference Manual, Version 8.2, 1 September 1993.

[Clark1966]

C.A. Clark, “Haystack Pointing System: Radar Coordinate Correction,” Technical Note 1966-56, Lincoln Laboratory, MIT, 1966, https://doi.org/10.21236/ad0641603

[IH1963]

W.R. Iliff, J.M. Holt, “Use of Surface Refractivity in the Empirical Prediction of Total Atmospheric Refraction,” Journal of Research of the National Bureau of Standards–D. Radio Propagation, vol. 67D, no. 1, Jan 1963, https://doi.org/10.6028/jres.067d.006

katpoint.target module

Target object used for pointing and flux density calculation.

exception katpoint.target.NonAsciiError

Bases: ValueError

Exception when non-ascii characters are found.

class katpoint.target.Target(target, name=<object object>, user_tags=<object object>, aliases=<object object>, flux_model=<object object>, antenna=<object object>, flux_frequency=<object object>)

Bases: object

A target which can be pointed at by an antenna.

This is a wrapper around a Body that adds alternate names, descriptive tags and a flux density model. For convenience, a default antenna and flux frequency can be set, to simplify the calling of pointing and flux density methods. It is also possible to construct a Target directly from an SkyCoord.

The object can be constructed from its constituent components or from a description string. The description string contains up to five comma-separated fields, with the format:

[<name list>,] <tags>, [<location 1>, [<location 2>, [<flux model>]]]

The <name list> contains a pipe-separated list of alternate names for the target, with the preferred name either indicated by a prepended asterisk or assumed to be the first name in the list. The names may contain spaces. The list may also be empty, or the entire field may be missing, to indicate an unnamed target. In this case a name will be inferred from the body.

The <tags> field contains a space-separated list of descriptive tags for the target. The first tag is mandatory and indicates the body type of the target, which should be one of (azel, radec, gal, special, tle, xephem).

For azel, radec and gal targets, the two location fields contain the relevant longitude and latitude coordinates, respectively. The following angle string formats are supported:

- Decimal, always in degrees (e.g. '12.5')
- Sexagesimal, in hours for right ascension and degrees for the rest,
  with a colon or space separator (e.g. '12:30:00' or '12 30')
- Decimal or sexagesimal with explicit unit suffix 'd' or 'h',
  e.g. '12.5h' (hours, not degrees!) or '12:30d'

The special body type has no location fields. The special target name is typically one of the major solar system objects supported by Astropy’s ephemeris routines. Alternatively, it could be “Nothing”, which indicates a dummy target with no position (useful as a placeholder but not much else).

For tle bodies, the two location fields contain the two lines of the element set. If the name list is empty, the target name is derived from the TLE instead.

The xephem body contains a string in XEphem EDB database format as the first location field, with commas replaced by tildes. If the name list is empty, the target name is taken from the XEphem string instead. Only fixed and Earth satellite objects are supported.

The <flux model> is a space-separated list of numbers used to represent the flux density of the target. The first two numbers specify the frequency range for which the flux model is valid (in MHz), and the rest of the numbers are model coefficients. The <flux model> may be enclosed in parentheses to distinguish it from the other fields. An example string is:

name1 | *name 2, radec cal, 12:34:56.7, -04:34:34.2, (1000.0 2000.0 1.0)

The default antenna and flux frequency are not stored in the description string.

In summary, description strings take the following forms based on body type:

[<name list>,] azel [<user tags>], <az>, <el> [, <flux model>]
[<name list>,] radec [<user tags>], <ra>, <dec> [, <flux model>]
[<name list>,] gal [<user tags>], <l>, <b> [, <flux model>]
<name list>, special [<user tags>] [, <flux model>]
[<name list>,] tle [<user tags>], <TLE line 1>, <TLE line 2> [, <flux model>]
[<name list>,] xephem radec [<user tags>], <EDB string (type 'f')> [, <flux>]
[<name list>,] xephem tle [<user tags>], <EDB string (type 'E')> [, <flux>]

Parameters:

target (Body, SkyCoord, str or) – Target A Body, a SkyCoord, a full description string or existing Target object. The parameters in the description string or existing Target can still be overridden by providing additional parameters after target.
name (str, optional) – Preferred name of target (use the default Body name if empty)
user_tags (sequence of str, or whitespace-delimited str, optional) – Descriptive tags associated with target (not including body type)
aliases (iterable of str, optional) – Alternate names of target
flux_model (FluxDensity, optional) – Object encapsulating spectral flux density model
antenna (EarthLocation or Antenna, optional) – Default antenna / location to use for position calculations
flux_frequency (Quantity, optional) – Default frequency at which to evaluate flux density

Raises:

ValueError – If description string has the wrong format

add_tags(tags)

Add tags to target object.

This adds tags to a target, while checking the sanity of the tags. It also prevents duplicate tags without resorting to a tag set, which would be problematic since the tag order is meaningful (tags[0] is the body type). Since tags should not contain whitespace, any string consisting of whitespace-delimited words will be split into separate tags.

Parameters:: tags (str, list of str, or None) – Tag or list of tags to add (strings will be split on whitespace)
Returns:: target – Updated target object
Return type:: Target

property aliases: Tuple of alternate names of the target.

apparent_radec(timestamp=None, antenna=None)

Calculate target’s apparent (ra, dec) as seen from antenna at time(s).

This calculates the apparent topocentric position of the target for the epoch-of-date in equatorial coordinates. Take note that this is not the “star-atlas” position of the target, but the position as is actually seen from the antenna at the given times. The difference is on the order of a few arcminutes. These are the coordinates that a telescope with an equatorial mount would use to track the target.

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna which points at target (defaults to default antenna)

Returns:

radec – Right ascension and declination in CIRS frame

Return type:

CIRS, same shape as timestamp

Raises:

ValueError – If no antenna is specified and body type requires it for (ra, dec)

astrometric_radec(timestamp=None, antenna=None)

Calculate target’s astrometric (ra, dec) as seen from antenna at time(s).

This calculates the ICRS astrometric topocentric position of the target, in equatorial coordinates. This is its star atlas position for the epoch of J2000, as seen from the antenna (also called “catalog coordinates” in SOFA).

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna which points at target (defaults to default antenna)

Returns:

radec – Right ascension and declination in ICRS frame

Return type:

ICRS, same shape as timestamp

Raises:

ValueError – If no antenna is specified and body type requires it for (ra, dec)

azel(timestamp=None, antenna=None)

Calculate target (az, el) coordinates as seen from antenna at time(s).

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna which points at target (defaults to default antenna)

Returns:

azel – Azimuth and elevation in AltAz frame

Return type:

AltAz, same shape as timestamp

Raises:

ValueError – If no antenna is specified and body type requires it for (az, el)

property body_type: Type of target body, as a string tag.

property description: Complete string representation of target object.

flux_density(frequency: Unit('Hz') = None)

Calculate flux density for given observation frequency (or frequencies).

This uses the stored flux density model to calculate the flux density at a given frequency (or frequencies). See the documentation of FluxDensityModel for more details of this model. If the flux frequency is unspecified, the default value supplied to the target object during construction is used. If no flux density model is available or a frequency is out of range, a flux value of NaN is returned for that frequency.

This returns only Stokes I. Use flux_density_stokes() to get polarisation information.

Parameters:: frequency (Quantity, optional) – Frequency at which to evaluate flux density
Returns:: flux_density – Flux density in Jy, or np.nan if frequency is out of range or target does not have flux model. The shape matches the input.
Return type:: Quantity
Raises:: ValueError – If no frequency is specified, and no default frequency was set either

flux_density_stokes(frequency: Unit('Hz') = None)

Calculate flux density for given observation frequency(-ies), full-Stokes.

See flux_density() This uses the stored flux density model to calculate the flux density at a given frequency (or frequencies). See the documentation of FluxDensityModel for more details of this model. If the flux frequency is unspecified, the default value supplied to the target object during construction is used. If no flux density model is available or a frequency is out of range, a flux value of NaN is returned for that frequency.

Parameters:: frequency (Quantity, optional) – Frequency at which to evaluate flux density
Returns:: flux_density – Flux density in Jy, or np.nan if frequency is out of range or target does not have flux model. The shape matches the input with an extra trailing dimension of size 4 containing Stokes I, Q, U, V.
Return type:: Quantity
Raises:: ValueError – If no frequency is specified, and no default frequency was set either

property flux_frequency: Default frequency at which to evaluate flux density.

classmethod from_azel(az, el)

Create unnamed stationary target (azel body type).

Parameters:

az (Angle or equivalent, string or float) –
el (Angle or equivalent, string or float) –
elevation (Azimuth and) –
Angle (as anything accepted by) –
or (a sexagesimal) –
degrees (decimal string in) –
radians (or as a float in) –

Returns:

target – Constructed target object

Return type:

Target

classmethod from_description(description)

Construct Target object from description string.

For more information on the description string format, see the help string for Target.

Parameters:: description (str) – String containing target name(s), tags, location and flux model
Returns:: target – Constructed target object
Return type:: Target
Raises:: ValueError – If description has the wrong format

classmethod from_radec(ra, dec)

Create unnamed fixed target (radec body type, ICRS frame).

Parameters:

ra (Angle or equivalent, string or float) – Right ascension, as anything accepted by Angle, a sexagesimal string in hours, a decimal string in degrees, or as a float in radians
dec (Angle or equivalent, string or float) – Declination, as anything accepted by Angle, a sexagesimal or decimal string in degrees, or as a float in radians

Returns:

target – Constructed target object

Return type:

Target

galactic(timestamp=None, antenna=None)

Calculate target’s galactic (l, b) as seen from antenna at time(s).

This calculates the galactic coordinates of the target, based on the ICRS astrometric topocentric coordinates. This is its position relative to the Galactic frame for the epoch of J2000 as seen from the antenna.

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna which points at target (defaults to default antenna)

Returns:

lb – Galactic longitude, l, and latitude, b, in Galactic frame

Return type:

Galactic, same shape as timestamp

Raises:

ValueError – If no antenna is specified and body type requires it for (l, b)

geometric_delay(antenna2, timestamp=None, antenna=None)

Calculate geometric delay between two antennas pointing at target.

An incoming plane wavefront travelling along the direction from the target to the reference antenna antenna arrives at this antenna at the given timestamp(s), and delay seconds later (or earlier, if delay is negative) at the second antenna, antenna2. This delay is known as the geometric delay, also represented by the symbol \(\tau_g\), and is associated with the baseline vector from the reference antenna to the second antenna. Additionally, the rate of change of the delay at the given timestamp(s) is estimated from the change in delay during a short interval spanning the timestamp(s).

Parameters:

antenna2 (EarthLocation or Antenna) – Second antenna of baseline pair (baseline vector points toward it)
timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional First (reference) antenna of baseline pair, which also serves as pointing reference (defaults to default antenna)

Returns:

delay (Quantity of same shape as timestamp) – Geometric delay
delay_rate (Quantity of same shape as timestamp) – Rate of change of geometric delay, in seconds per second

Raises:

ValueError – If no reference antenna is specified and no default antenna was set

Notes

This is a straightforward dot product between the unit vector pointing from the reference antenna to the target, and the baseline vector pointing from the reference antenna to the second antenna, all in local ENU coordinates relative to the reference antenna.

lmn(ra, dec, timestamp=None, antenna=None)

Calculate (l, m, n) coordinates for another target relative to self.

Calculate (l, m, n) coordinates for another target, while pointing at this target.

Refer to uvw() for a description of the coordinate system. This function is vectorised, allowing for multiple targets and multiple timestamps.

Parameters:

ra (float or array) – Right ascension of the other target, in radians
dec (float or array) – Declination of the other target, in radians
timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Pointing reference (defaults to default antenna)

Returns:

l,m,n – (l, m, n) coordinates of target(s).

Return type:

float, or array of same length as ra, dec, timestamps

property name: Preferred name of the target.

property names: Tuple of all names (both preferred and alternate) of the target.

parallactic_angle(timestamp=None, antenna=None)

Calculate parallactic angle on target as seen from antenna at time(s).

This calculates the parallactic angle, which is the position angle of the observer’s vertical on the sky, measured from north toward east. This is the angle between the great-circle arc connecting the celestial North pole to the target position, and the great-circle arc connecting the zenith above the antenna to the target, or the angle between the hour circle and vertical circle through the target, at the given timestamp(s).

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna which points at target (defaults to default antenna)

Returns:

parangle – Parallactic angle

Return type:

Angle, same shape as timestamp

Raises:

ValueError – If no antenna is specified, and no default antenna was set either

Notes

The formula can be found in the AIPS++ glossary or in the SLALIB source code (file pa.f, function sla_PA) which is part of the now defunct Starlink project.

plane_to_sphere(x, y, timestamp=None, antenna=None, projection_type='ARC', coord_system='azel')

Deproject plane coordinates to sphere with target position as reference.

This is a convenience function that deprojects plane coordinates to a sphere with the target position as the origin of the plane. The function is vectorised and can operate on single or multiple timestamps, as well as single or multiple coordinate vectors. The spherical coordinates may be (az, el) or (ra, dec), and the projection type can also be specified.

Parameters:

x (float or array) – Azimuth-like coordinate(s) on plane, in radians
y (float or array) – Elevation-like coordinate(s) on plane, in radians
timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna pointing at target (defaults to default antenna)
projection_type ({'ARC', 'SIN', 'TAN', 'STG', 'CAR', 'SSN'}, optional) – Type of spherical projection
coord_system ({'azel', 'radec'}, optional) – Spherical coordinate system

Returns:

az (float or array) – Azimuth or right ascension, in radians
el (float or array) – Elevation or declination, in radians

radec(timestamp=None, antenna=None)

Calculate target’s astrometric (ra, dec) as seen from antenna at time(s).

This calculates the ICRS astrometric topocentric position of the target, in equatorial coordinates. This is its star atlas position for the epoch of J2000, as seen from the antenna (also called “catalog coordinates” in SOFA).

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna which points at target (defaults to default antenna)

Returns:

radec – Right ascension and declination in ICRS frame

Return type:

ICRS, same shape as timestamp

Raises:

ValueError – If no antenna is specified and body type requires it for (ra, dec)

separation(other_target, timestamp=None, antenna=None)

Angular separation between this target and another as viewed from antenna.

Parameters:

other_target (Target) – The other target
timestamp (Time, Timestamp or equiv, optional) – Timestamp(s) when separation is measured (defaults to now)
antenna (EarthLocation or) – Antenna, optional Antenna that observes both targets, from where separation is measured (defaults to default antenna of this target)

Returns:

separation – Angular separation between the targets, as viewed from antenna

Return type:

Angle

Notes

This calculates the azimuth and elevation of both targets at the given time and finds the angular distance between the two sets of coordinates.

sphere_to_plane(az, el, timestamp=None, antenna=None, projection_type='ARC', coord_system='azel')

Project spherical coordinates to plane with target position as reference.

This is a convenience function that projects spherical coordinates to a plane with the target position as the origin of the plane. The function is vectorised and can operate on single or multiple timestamps, as well as single or multiple coordinate vectors. The spherical coordinates may be (az, el) or (ra, dec), and the projection type can also be specified.

Parameters:

az (float or array) – Azimuth or right ascension, in radians
el (float or array) – Elevation or declination, in radians
timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna pointing at target (defaults to default antenna)
projection_type ({'ARC', 'SIN', 'TAN', 'STG', 'CAR', 'SSN'}, optional) – Type of spherical projection
coord_system ({'azel', 'radec'}, optional) – Spherical coordinate system

Returns:

x (float or array) – Azimuth-like coordinate(s) on plane, in radians
y (float or array) – Elevation-like coordinate(s) on plane, in radians

property tags: List of descriptive tags associated with target, body type first.

uvw(antenna2, timestamp=None, antenna=None)

Calculate (u,v,w) coordinates of baseline while pointing at target.

Calculate the (u,v,w) coordinates of the baseline vector from antenna toward antenna2. The w axis points from the first antenna toward the target. The v axis is perpendicular to it and lies in the plane passing through the w axis and the poles of the earth, on the northern side of w. The u axis is perpendicular to the v and w axes, and points to the east of w.

Parameters:

antenna2 (EarthLocation or) – Antenna or sequence Second antenna of baseline pair (baseline vector points toward it), shape A
timestamp (Time, Timestamp or equiv, optional) – Timestamp(s) of shape T, defaults to now
antenna (EarthLocation or) – Antenna, optional First (reference) antenna of baseline pair, which also serves as pointing reference (defaults to default antenna)

Returns:

uvw – (u, v, w) coordinates of baseline as Cartesian (x, y, z), in units of length. The shape is a concatenation of the timestamp and antenna2 shapes.

Return type:

CartesianRepresentation, shape T + A

Notes

All calculations are done in the local ENU coordinate system centered on the first antenna, as opposed to the traditional XYZ coordinate system. This avoids having to convert (az, el) angles to (ha, dec) angles and uses linear algebra throughout instead.

uvw_basis(timestamp=None, antenna=None)

Calculate ENU -> (u,v,w) transform while pointing at the target.

Calculate the coordinate transformation from local ENU coordinates to (u,v,w) coordinates while pointing at the target.

In most cases you should use uvw() directly.

Refer to uvw() for details about how the (u,v,w) coordinate system is defined.

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s) of shape T, defaults to now
antenna (EarthLocation or) – Antenna, optional Reference antenna of baseline pairs, which also serves as pointing reference (defaults to default antenna)

Returns:

uvw_basis – Orthogonal basis vectors for the transformation. If timestamp is scalar, the return value is a matrix to multiply by ENU column vectors to produce UVW vectors. If timestamp is an array of shape T, the first two dimensions correspond to the matrix and the remaining dimension(s) to the timestamp.

Return type:

array of float, shape (3, 3) + T

katpoint.target.construct_azel_target(az, el): Create unnamed stationary target (azel body type) DEPRECATED.

katpoint.target.construct_radec_target(ra, dec): Create unnamed fixed target (radec body type) DEPRECATED.

katpoint.timestamp module

A Timestamp object.

class katpoint.timestamp.Timestamp(timestamp=None)

Bases: object

Basic representation of time(s), in UTC seconds since Unix epoch.

This is loosely based on PyEphem’s Date object, but uses an Astropy Time object as internal representation. Like Time it can contain a multi-dimensional array of timestamps.

The following input formats are accepted for a timestamp:

A floating-point number, directly representing the number of UTC seconds since the Unix epoch. Fractional seconds are allowed.
A string or bytes with format ‘YYYY-MM-DD HH:MM:SS.SSS’ (Astropy ‘iso’ format) or ‘YYYY/MM/DD HH:MM:SS.SSS’ (XEphem format), where the hours and minutes, seconds, and fractional seconds are optional. It is always in UTC. Examples are:

‘1999-12-31 12:34:56.789’ ‘1999/12/31 12:34:56’ ‘1999-12-31 12:34’ b’1999-12-31’
A Time object (NOT TimeDelta).
Another Timestamp object, which will result in a copy.
A sequence or NumPy array of one of the above types.
None, which uses the current time (the default).

Parameters:: timestamp (Time, Timestamp, float, string,) – bytes, sequence or array of any of the former, or None, optional Timestamp, in various formats (if None, defaults to now)
Raises:: ValueError – If timestamp is not in a supported format

time

Underlying Time object

Type:: Time

secs

Timestamp as UTC seconds since Unix epoch

Type:: float or array of float

Notes

This differs from Time in the following respects:

Numbers are interpreted as Unix timestamps during initialisation; Timestamp(1234567890) is equivalent to Time(1234567890, format=’unix’) (while Time(1234567890) is not allowed because it lacks a format).
Arithmetic is done in seconds instead of days (in the absence of units).
Date strings may contain slashes (a leftover from PyEphem / XEphem).
Empty initialisation results in the current time, so Timestamp() is equivalent to Time.now() (while Time() is not allowed).

local(): Local time string representation (str or array of str).

property secs: Timestamp as UTC seconds since Unix epoch.

to_mjd(): Convert timestamp to Modified Julian Day (MJD).

to_string(): UTC string representation (str or array of str).

katpoint.timestamp.delta_seconds(x): Construct a TimeDelta in TAI seconds.

Module contents

Coordinate library for the SKA and MeerKAT radio telescopes.

This provides astronomical coordinate transformations, antenna pointing models, correlator delay models, source flux models and basic source catalogues, using an existing coordinate library (Astropy) to do the low-level calculations.

class katpoint.Antenna(antenna, name=<object object>, diameter=<object object>, delay_model=<object object>, pointing_model=<object object>, beamwidth=<object object>)

Bases: object

An antenna that can point at a target.

This is a wrapper around an Astropy EarthLocation that adds a dish diameter and other parameters related to pointing and delay calculations.

It has two variants: a stand-alone single dish, or an antenna that is part of an array. The first variant is initialised with the antenna location, while the second variant is initialised with the array reference location and an ENU (east-north-up) offset for the specific antenna which also doubles as the first part of a broader delay model for the antenna.

Additionally, a diameter, a pointing model and a beamwidth factor may be specified. These parameters are collected for convenience, and the pointing model is not applied by default when calculating pointing or delays.

The Antenna object is typically passed around in string form, and is fully described by its description string, which has the following format:

name, latitude (D:M:S), longitude (D:M:S), altitude (m), diameter (m),
east-north-up offset (m) / delay model, pointing model, beamwidth

A stand-alone dish has the antenna location as lat-lon-alt and the ENU offset as an empty string, while an antenna that is part of an array has the array reference location as lat-lon-alt and the ENU offset as a space-separated string of 3 numbers (followed by any additional delay model terms). The pointing model is a space-separated string of model parameters (or empty string if there is no pointing model). The beamwidth is a single floating-point number.

Any empty fields at the end of the description string may be omitted, as they will be replaced by defaults. The first four fields are required (but the name may be an empty string).

Here are some examples of description strings:

- Single dish
  'XDM, -25:53:23.0, 27:41:03.0, 1406.1086, 15.0'

- Simple array antenna
  'FF1, -30:43:17.3, 21:24:38.5, 1038.0, 12.0, 18.4 -8.7 0.0'

- Fully-specified antenna
  'FF2, -30:43:17.3, 21:24:38.5, 1038.0, 12.0, 86.2 25.5 0.0, -0:06:39.6 0, 1.16'

Parameters:

antenna (EarthLocation, str or Antenna) – A location on Earth, a full description string or existing Antenna object. The parameters in the description string or existing Antenna can still be overridden by providing additional parameters after antenna.
name (string, optional) – Name of antenna (may be empty but may not contain commas)
diameter (Quantity or string or float, optional) – Dish diameter, in metres
delay_model (DelayModel object or equivalent, optional) – Delay model for antenna, either as a direct object, a file-like object representing a parameter file, or a string or sequence of float params. The first three parameters form an East-North-Up offset from WGS84 reference position, in metres.
pointing_model (PointingModel object or equivalent, optional) – Pointing model for antenna, either as a direct object, a file-like object representing a parameter file, or a string or sequence of float parameters from which the PointingModel object can be instantiated
beamwidth (string or float, optional) – Full width at half maximum (FWHM) average beamwidth, as a multiple of lambda / D (wavelength / dish diameter). This depends on the dish illumination pattern, and ranges from 1.03 for a uniformly illuminated circular dish to 1.22 for a Gaussian-tapered circular dish (the default).

location :class:`~astropy.coordinates.EarthLocation`: Underlying object used for pointing calculations

ref_location :class:`~astropy.coordinates.EarthLocation`: Array reference location for antenna in an array (same as location for a stand-alone antenna)

Raises:: ValueError – If description string has wrong format or parameters are incorrect

array_reference_antenna(name='array')

Synthetic antenna at the delay model reference position of this antenna.

This is mainly useful as the reference antenna for Target.uvw(), in which case it will give both faster and more accurate results than other choices.

The returned antenna will have no delay or pointing model. It is intended to be used only for its position and does not correspond to a physical antenna.

baseline_toward(antenna2)

Baseline vector pointing toward second antenna, in ENU coordinates.

This calculates the baseline vector pointing from this antenna toward a second antenna, antenna2, in local East-North-Up (ENU) coordinates relative to this antenna’s geodetic location.

Parameters:: antenna2 (EarthLocation or Antenna) – Second antenna of baseline pair (baseline vector points toward it)
Returns:: enu – East, North, Up coordinates of baseline vector as Cartesian (x, y, z)
Return type:: CartesianRepresentation

property description: Complete string representation of antenna object.

classmethod from_description(description): Construct antenna object from description string.

local_sidereal_time(timestamp=None)

Calculate local apparent sidereal time at antenna for timestamp(s).

This is a vectorised function that returns the local apparent sidereal time at the antenna for the given timestamp(s).

Parameters:: timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
Returns:: last – Local apparent sidereal time(s)
Return type:: astropy.coordinates.Longitude

property position_ecef: ECEF (Earth-centred Earth-fixed) position of antenna (in metres).

property position_enu: East-North-Up offset from WGS84 reference position, in metres.

property position_wgs84

WGS84 position.

The latitude and longitude are in radians, and the altitude in metres.

property ref_position_wgs84

WGS84 reference position.

The latitude and longitude are in radians, and the altitude in metres.

exception katpoint.BadModelFile

Bases: Exception

Unable to load model from config file (unrecognised format).

class katpoint.Catalogue(targets=None, tags=None, add_specials=None, add_stars=None, antenna=None, flux_frequency: Unit('Hz') = None)

Bases: object

A searchable and filterable catalogue of targets.

Overview

A Catalogue object combines two concepts:

A list of targets, which can be filtered, sorted, pretty-printed and iterated over. The list is accessible as Catalogue.targets(), and the catalogue itself is iterable, returning the next target on each iteration. The targets are assumed to be unique, but may have the same name. An example is:
```
cat = katpoint.Catalogue()
cat.add(some_targets)
t = cat.targets[0]
for t in cat:
    # Do something with target t
```
Lookup by name, by using the catalogue as if it were a dictionary. This is simpler for the user, who does not have to remember all the target details. The named lookup supports tab completion in IPython, which further simplifies finding a target in the catalogue. The most recently added target with the specified name is returned. An example is:
```
targets = ['Sun, special', 'Moon, special', 'Jupiter, special']
cat = katpoint.Catalogue(targets)
t = cat['Sun']
```

Construction

A catalogue can be constructed in many ways. The simplest way is:

cat = katpoint.Catalogue()

which produces an empty catalogue. Additional targets may be loaded during initialisation of the catalogue by providing a list of Target objects (or a single object by itself), as in the following example:

t1 = katpoint.Target('Venus, special')
t2 = katpoint.Target('Takreem, azel, 20, 30')
cat1 = katpoint.Catalogue(t1)
cat2 = katpoint.Catalogue([t1, t2])

Alternatively, the list of targets may be replaced by a list of target description strings (or a single description string). The target objects are then constructed before being added, as in:

cat1 = katpoint.Catalogue('Takreem, azel, 20, 30')
cat2 = katpoint.Catalogue(['Venus, special', 'Takreem, azel, 20, 30'])

Taking this one step further, the list may be replaced by any iterable object that returns strings. A very useful example of such an object is the Python file object, which iterates over the lines of a text file. If the catalogue file contains one target description string per line (with comments and blank lines allowed too), it may be loaded as:

cat = katpoint.Catalogue(open('catalogue.csv'))

Once a catalogue is initialised, more targets may be added to it. The Catalogue.add() method is the most direct way. It accepts a single target object, a list of target objects, a single string, a list of strings or a string iterable. This is illustrated below:

t1 = katpoint.Target('Venus, special')
t2 = katpoint.Target('Takreem, azel, 20, 30')
cat = katpoint.Catalogue()
cat.add(t1)
cat.add([t1, t2])
cat.add('Venus, special')
cat.add(['Venus, special', 'Takreem, azel, 20, 30'])
cat.add(open('catalogue.csv'))

Some target types are typically found in files with standard formats. Notably, tle targets are found in TLE files with three lines per target, and many xephem targets are stored in EDB database files. Editing these files to make each line a valid Target description string is cumbersome, especially in the case of TLE files which are regularly updated. Two special methods simplify the loading of targets from these files:

cat = katpoint.Catalogue()
cat.add_tle(open('gps-ops.txt'))
cat.add_edb(open('hipparcos.edb'))

Whenever targets are added to the catalogue, a tag or list of tags may be specified. The tags can also be given as a single string of whitespace-delimited tags, since tags may not contain whitespace. These tags are added to the targets currently being added. This makes it easy to tag groups of related targets in the catalogue, as shown below:

cat = katpoint.Catalogue(tags='default')
cat.add_tle(open('gps-ops.txt'), tags='gps satellite')
cat.add_tle(open('glo-ops.txt'), tags=['glonass', 'satellite'])
cat.add(open('source_list.csv'), tags='calibrator')
cat.add_edb(open('hipparcos.edb'), tags='star')

Finally, targets may be removed from the catalogue. The most recently added target with the specified name is removed from the targets list as well as the lookup dict. The target may be removed via any of its names:

targets = ['Sol | Sun, special', 'Moon, special', 'Jupiter, special']
cat = katpoint.Catalogue(targets)
cat.remove('Sun')

Filtering and sorting

A Catalogue object may be filtered based on various criteria. The following filters are available:

Tag filter. Returns all targets that have a specified set of tags, and not another set of tags. Tags prepended with a tilde (~) indicate tags which targets should not have. All tags have to be present (or absent) for a target to be selected. Remember that the body type is also a tag. An example is:
```
cat = katpoint.Catalogue(tags='default')
cat1 = cat.filter(tags=['special', '~radec'])
cat1 = cat.filter(tags='special ~radec')
```

Flux filter. Returns all targets with a flux density between the specified limits, at a given frequency. If only one limit is given, it is a lower limit. To simplify filtering, a default flux frequency may be supplied to the catalogue during initialisation. This is stored in each target in the catalogue. An example is:

import astropy.units as u
cat = katpoint.Catalogue(open('source_list.csv'))
cat1 = cat.filter(flux_limit=[1, 100] * u.Jy,
                  flux_frequency=1500 * u.MHz)
cat = katpoint.Catalogue(open('source_list.csv'),
                         flux_frequency=1500 * u.MHz)
cat1 = cat.filter(flux_limit=1 * u.Jy)

Azimuth filter. Returns all targets with an azimuth angle in the given range. The range is specified in degrees as [left, right], where left is the leftmost or starting azimuth, and right is the rightmost or ending azimuth. The azimuth angle increases clockwise from left to right to form the range. If right is less than left, the azimuth angles range around +-180 degrees. Since the target azimuth is dependent on time and observer position, a timestamp and katpoint.Antenna object has to be provided. The timestamp defaults to now, and the antenna object may be associated with the catalogue during initialisation, from where it is stored in each target. An example is:
```
import astropy.units as u
ant = katpoint.Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
targets = ['Sun, special', 'Moon, special', 'Jupiter, special']
cat = katpoint.Catalogue(targets)
cat1 = cat.filter(az_limit=[0, 90] * u.deg,
                  timestamp='2009-10-10', antenna=ant)
cat = katpoint.Catalogue(antenna=ant)
cat1 = cat.filter(az_limit=[90, 0] * u.deg)
```

Elevation filter. Returns all targets with an elevation angle within the given limits, in degrees. If only one limit is given, it is assumed to be a lower limit. As with the azimuth filter, a timestamp and antenna object is required (or defaults will be used). An example is:

import astropy.units as u
ant = katpoint.Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
targets = ['Sun, special', 'Moon, special', 'Jupiter, special']
cat = katpoint.Catalogue(targets)
cat1 = cat.filter(el_limit=[10, 30] * u.deg,
                  timestamp='2009-10-10', antenna=ant)
cat = katpoint.Catalogue(antenna=ant)
cat1 = cat.filter(el_limit=10 * u.deg)

Proximity filter. Returns all targets with angular separation from a given set of targets within a specified range. The range is given as a lower and upper limit, in degrees, and a single number is taken as the lower limit. The typical use of this filter is to return all targets more than a specified number of degrees away from a known set of interfering targets. As with the azimuth filter, a timestamp and antenna object is required (or defaults will be used). An example is:

import astropy.units as u
ant = katpoint.Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
targets = ['Sun, special', 'Moon, special', 'Jupiter, special']
cat = katpoint.Catalogue(targets)
cat.add_tle(open('geo.txt'))
sun = cat['Sun']
afristar = cat['AFRISTAR']
cat1 = cat.filter(dist_limit=5 * u.deg,
                  proximity_targets=[sun, afristar],
                  timestamp='2009-10-10', antenna=ant)
cat = katpoint.Catalogue(antenna=ant)
cat1 = cat.filter(dist_limit=[0, 5] * u.deg, proximity_targets=sun)

The criteria may be divided into static criteria which are independent of time (tags and flux) and dynamic criteria which do depend on time (azimuth, elevation and proximity). There are two filtering mechanisms that both support the same criteria, but differ on their handling of dynamic criteria:

A direct filter, implemented by the Catalogue.filter() method. This returns the filtered catalogue as a new catalogue which contains the subset of targets that satisfy the criteria. All criteria are evaluated at the same time instant. A typical use-case is:
```
cat = katpoint.Catalogue(open('source_list.csv'))
strong_sources = cat.filter(flux_limit=10 * u.Jy,
                            flux_frequency=1500 * u.MHz)
```
An iterator filter, implemented by the Catalogue.iterfilter() method. This is a Python generator function, which returns a generator iterator, to be more precise. Each time the returned iterator’s .next() method is invoked, the next suitable Target object is returned. If no timestamp is provided, the criteria are re-evaluated at the time instant of the .next() call, which makes it easy to cycle through a list of targets over an extended period of time (as during observation). The iterator filter is typically used in a for-loop:
```
cat = katpoint.Catalogue(open('source_list.csv'))
ant = katpoint.Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
for t in cat.iterfilter(el_limit=10 * u.deg, antenna=ant):
    # < observe target t >
```

When a catalogue is sorted, the order of the target list is changed. The catalogue may be sorted according to name (the default), right ascension, declination, azimuth, elevation and flux. Any position-based key requires a timestamp and katpoint.Antenna object to evaluate the position of each target, and the flux key requires a frequency at which to evaluate the flux.

param targets:: Target or list of targets to add to catalogue (may also be file object)
type targets:: Target object or string, or sequence of these, optional
param tags:: Tag or list of tags to add to targets (strings will be split on whitespace)
type tags:: string or sequence of strings, optional
param add_specials:: Always False (add special bodies yourself) DEPRECATED
type add_specials:: bool, optional
param add_stars:: Always False (stars have no special support anymore) DEPRECATED
type add_stars:: bool, optional
param antenna:: Default antenna to use for position calculations for all targets
type antenna:: Antenna object, optional
param flux_frequency:: Default frequency at which to evaluate flux density of all targets
type flux_frequency:: Quantity, optional

Notes

The catalogue object has an interesting relationship with orderedness. While it is nominally an ordered list of targets, it is considered equal to another catalogue with the same targets in a different order. This is because the catalogue may be conveniently reordered in many ways (e.g. based on elevation, declination, flux, etc.) while remaining essentially the same catalogue. It also allows us to preserve the order in which the catalogue was assembled, which seems the most natural.

add(targets, tags=None)

Add targets to catalogue.

Examples of catalogue construction can be found in the Catalogue documentation.

Parameters:

targets (Target object or string, or sequence of these) – Target or list of targets to add to catalogue (may also be file object)
tags (string or sequence of strings, optional) – Tag or list of tags to add to targets (strings will be split on whitespace)

Examples

Here are some ways to add targets to a catalogue:

>>> from katpoint import Catalogue
>>> cat = Catalogue()
>>> cat.add(open('source_list.csv'), tags='cal')
>>> cat.add('Sun, special')
>>> cat2 = Catalogue()
>>> cat2.add(cat.targets)

add_edb(lines, tags=None)

Add XEphem database format (EDB) targets to catalogue.

Examples of catalogue construction can be found in the Catalogue documentation.

Parameters:

lines (sequence of strings) – List of lines containing a target per line (may also be file object)
tags (string or sequence of strings, optional) – Tag or list of tags to add to targets (strings will be split on whitespace)

Examples

Here are some ways to add EDB targets to a catalogue:

>>> from katpoint import Catalogue
>>> cat = Catalogue()
>>> cat.add_edb(open('hipparcos.edb'), tags='star')
>>> lines = ['HYP71683,f|S|G2,14:39:35.88 ,-60:50:7.4 ,-0.010,2000,\n',
             'HYP113368,f|S|A3,22:57:39.055,-29:37:20.10,1.166,2000,\n']
>>> cat2.add_edb(lines)

add_tle(lines, tags=None)

Add NORAD Two-Line Element (TLE) targets to catalogue.

Examples of catalogue construction can be found in the Catalogue documentation.

Parameters:

lines (sequence of strings) – List of lines containing one or more TLEs (may also be file object)
tags (string or sequence of strings, optional) – Tag or list of tags to add to targets (strings will be split on whitespace)

Examples

Here are some ways to add TLE targets to a catalogue:

>>> from katpoint import Catalogue
>>> cat = Catalogue()
>>> cat.add_tle(open('gps-ops.txt'), tags='gps')
>>> lines = [
    'ISS DEB [TOOL BAG]\n',
    '1 33442U 98067BL  09195.86837279  .00241454  37518-4  34022-3 0  3424\n',
    '2 33442  51.6315 144.2681 0003376 120.1747 240.0135 16.05240536 37575\n'
    ]
>>> cat2.add_tle(lines)

property antenna: Default antenna used to calculate target positions.

closest_to(target, timestamp=None, antenna=None)

Determine target in catalogue that is closest to given target.

The comparison is based on the apparent angular separation between the targets, as seen from the specified antenna and at the given time instant.

Parameters:

target (Target) – Target with which catalogue targets are compared
timestamp (Time, Timestamp or equiv, optional) – Timestamp at which to evaluate target positions (defaults to now)
antenna (Antenna, optional) – Antenna which points at targets (defaults to default antenna)

Returns:

closest_target (Target or None) – Target in catalogue that is closest to given target, or None if catalogue is empty
min_dist (Angle) – Angular separation between target and closest_target

filter(tags=None, flux_limit: Unit('Jy') = None, flux_frequency: Unit('Hz') = None, az_limit: Unit('deg') = None, el_limit: Unit('deg') = None, dist_limit: Unit('deg') = None, proximity_targets=None, timestamp=None, antenna=None)

Filter catalogue on various criteria.

This returns a new catalogue containing the subset of targets that satisfy the given criteria. All criteria are evaluated at the same time instant. For real-time continuous filtering, consider using iterfilter() instead.

Parameters:

tags (string, or sequence of strings, optional) – Tag or list of tags which targets should have. Tags prepended with a tilde (~) indicate tags which targets should not have. The string may contain multiple tags separated by whitespace. If None or an empty list, all tags are accepted. Remember that the body type is also a tag.
flux_limit (Quantity, optional) – Allowed flux density range. If this is a single number, it is the lower limit, otherwise it takes the form [lower, upper]. If None, any flux density is accepted.
flux_frequency (Quantity, optional) – Frequency at which to evaluate the flux density
az_limit (Quantity, optional) – Allowed azimuth range. It takes the form [left, right], where left is the leftmost or starting azimuth, and right is the rightmost or ending azimuth. If right is less than left, the azimuth angles range around +-180. If None, any azimuth is accepted.
el_limit (Quantity, optional) – Allowed elevation range. If this is a single number, it is the lower limit, otherwise it takes the form [lower, upper]. If None, any elevation is accepted.
dist_limit (Quantity, optional) – Allowed range of angular distance to proximity targets. If this is a single number, it is the lower limit, otherwise it takes the form [lower, upper]. If None, any distance is accepted.
proximity_targets (Target, or sequence of Target) – Target or list of targets used in proximity filter
timestamp (Time, Timestamp or equiv, optional) – Timestamp at which to evaluate target positions (defaults to now). For iterfilter() the default is the current time at each iteration.
antenna (Antenna object, optional) – Antenna which points at targets (defaults to default antenna)

Returns:

subset – Filtered catalogue

Return type:

Catalogue

Raises:

ValueError – If some required parameters are missing or limits are invalid

Examples

Here are some ways to filter a catalogue:

>>> from katpoint import Catalogue, Antenna
>>> import astropy.units as u
>>> ant = Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
>>> targets = ['Sun, special', 'Moon, special', 'Jupiter, special']
>>> cat = Catalogue(targets, antenna=ant, flux_frequency=1500 * u.MHz)
>>> cat1 = cat.filter(el_limit=10 * u.deg)
>>> cat2 = cat.filter(az_limit=[150, -150] * u.deg)
>>> cat3 = cat.filter(flux_limit=10 * u.Jy)
>>> cat4 = cat.filter(tags='special ~radec')
>>> cat5 = cat.filter(dist_limit=5 * u.deg, proximity_targets=cat['Sun'])

property flux_frequency: Default frequency at which to evaluate flux density.

iterfilter(tags=None, flux_limit: Unit('Jy') = None, flux_frequency: Unit('Hz') = None, az_limit: Unit('deg') = None, el_limit: Unit('deg') = None, dist_limit: Unit('deg') = None, proximity_targets=None, timestamp=None, antenna=None)

Yield targets satisfying various criteria (generator function).

This returns a (generator-)iterator which returns targets satisfying various criteria, one at a time. The standard use of this method is in a for-loop (i.e. for target in cat.iterfilter(...):). This differs from the filter() method in that all time-dependent criteria (such as elevation) may be evaluated at the time of the specific iteration, and not in advance as with filter(). This simplifies finding the next suitable target during an extended observation of several targets.

Parameters:

tags (string, or sequence of strings, optional) – Tag or list of tags which targets should have. Tags prepended with a tilde (~) indicate tags which targets should not have. The string may contain multiple tags separated by whitespace. If None or an empty list, all tags are accepted. Remember that the body type is also a tag.
flux_limit (Quantity, optional) – Allowed flux density range. If this is a single number, it is the lower limit, otherwise it takes the form [lower, upper]. If None, any flux density is accepted.
flux_frequency (Quantity, optional) – Frequency at which to evaluate the flux density
az_limit (Quantity, optional) – Allowed azimuth range. It takes the form [left, right], where left is the leftmost or starting azimuth, and right is the rightmost or ending azimuth. If right is less than left, the azimuth angles range around +-180. If None, any azimuth is accepted.
el_limit (Quantity, optional) – Allowed elevation range. If this is a single number, it is the lower limit, otherwise it takes the form [lower, upper]. If None, any elevation is accepted.
dist_limit (Quantity, optional) – Allowed range of angular distance to proximity targets. If this is a single number, it is the lower limit, otherwise it takes the form [lower, upper]. If None, any distance is accepted.
proximity_targets (Target, or sequence of Target) – Target or list of targets used in proximity filter
timestamp (Time, Timestamp or equiv, optional) – Timestamp at which to evaluate target positions (defaults to now). For iterfilter() the default is the current time at each iteration.
antenna (Antenna object, optional) – Antenna which points at targets (defaults to default antenna)

Returns:

iter – The generator-iterator object which will return filtered targets

Return type:

iterator object

Raises:

ValueError – If some required parameters are missing or limits are invalid

Examples

Here are some ways to filter a catalogue iteratively:

>>> from katpoint import Catalogue, Antenna
>>> import astropy.units as u
>>> ant = Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
>>> targets = ['Sun, special', 'Moon, special', 'Jupiter, special']
>>> cat = Catalogue(targets, antenna=ant)
>>> for t in cat.iterfilter(el_limit=10 * u.deg):
        # Observe target t
        pass

remove(name)

Remove target from catalogue.

This removes the most recently added target with the given name from the catalogue. If the target is not in the catalogue, do nothing.

Parameters:: name (string) – Name of target to remove (may also be an alternate name of target)

save(filename)

Save catalogue to file in CSV format.

Parameters:: filename (string) – Name of file to write catalogue to (overwriting existing contents)

sort(key='name', ascending=True, flux_frequency: Unit('Hz') = None, timestamp=None, antenna=None)

Sort targets in catalogue.

This returns a new catalogue with the target list sorted according to the given key.

Parameters:

key ({'name', 'ra', 'dec', 'az', 'el', 'flux'}, optional) – Sort the targets according to this field
ascending ({True, False}, optional) – True if key should be sorted in ascending order
flux_frequency (Quantity, optional) – Frequency at which to evaluate the flux density
timestamp (Time, Timestamp or equiv, optional) – Timestamp at which to evaluate target positions (defaults to now)
antenna (Antenna object, optional) – Antenna which points at targets (defaults to default antenna)

Returns:

sorted – Sorted catalogue

Return type:

Catalogue object

Raises:

ValueError – If some required parameters are missing or key is unknown

visibility_list(timestamp=None, antenna=None, flux_frequency: Unit('Hz') = None, antenna2=None)

Print out list of targets in catalogue, sorted by decreasing elevation.

This prints out the name, azimuth and elevation of each target in the catalogue, in order of decreasing elevation. The motion of the target at the given timestamp is indicated by a character code, which is ‘/’ if the target is rising, ‘' if it is setting, and ‘-’ if it is stationary (i.e. if the elevation angle changes by less than 1 arcminute during the one-minute interval surrounding the timestamp).

The method indicates the horizon itself by a line of dashes. It also displays the target flux density if a frequency is supplied, and the delay and fringe period if a second antenna is supplied. It is useful to quickly see which targets are visible (or will be soon).

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp at which to evaluate target positions (defaults to now)
antenna (Antenna, optional) – Antenna which points at targets (defaults to default antenna)
flux_frequency (Quantity, optional) – Frequency at which to evaluate flux density
antenna2 (Antenna, optional) – Second antenna of baseline pair (baseline vector points from antenna to antenna2), used to calculate delays and fringe rates per target

class katpoint.DelayCorrection(ants, ref_ant=None, sky_centre_freq: Unit("Hz") = <Quantity 0. Hz>, extra_correction: Unit("s") = None, tropospheric_model='None')

Bases: object

Calculate delay corrections for a set of correlator inputs / antennas.

This uses delay models from multiple antennas connected to a correlator to produce delay and phase corrections for a given target and timestamp, for all correlator inputs at once. The delay corrections are guaranteed to be strictly positive. Each antenna is assumed to have two polarisations (H and V), resulting in two correlator inputs per antenna.

Parameters:

ants (sequence of A Antenna objects or str) – Sequence of antennas forming an array and connected to correlator; alternatively, a description string representing the entire object
ref_ant (Antenna, optional) – Reference antenna for the array (defaults to first antenna in ants)
sky_centre_freq (Quantity, optional) – RF centre frequency that serves as reference for fringe phase
extra_correction (Quantity, optional) – Additional correction added to all inputs to ensure strictly positive corrections (automatically calculated by default)
tropospheric_model (str, optional) – Unique identifier of tropospheric model, or ‘None’ if no tropospheric correction will be done

ant_models

Dict mapping antenna name to corresponding delay model

Type:: dict mapping str to DelayModel

inputs

List of correlator input labels corresponding to output of delays()

Type:: list of str, length 2A

ant_locations

Locations of A antennas, in the same order as inputs

Type:: EarthLocation, shape (A,)

ref_location

Location of reference antenna

Type:: EarthLocation

Raises:: ValueError – If description string is invalid

property ant_locations: Locations of A antennas, in the same order as inputs.

corrections(target, timestamp=None, offset=None, pressure: Unit("hPa") = <Quantity 0. hPa>, temperature: Unit("deg_C") = <Quantity -300. deg_C>, relative_humidity: Unit(dimensionless) = 0)

Delay and phase corrections for a given target and timestamp(s).

Calculate delay and phase corrections for the direction towards target at timestamp. Both delay (aka phase slope across frequency) and phase (aka phase offset or fringe phase) corrections are provided, and their derivatives with respect to time (delay rate and fringe rate, respectively). The derivatives allow linear interpolation of delay and phase if a sequence of timestamps is provided.

Parameters:

target (Target) – Target providing direction for geometric delays
timestamp (Time, Timestamp or equivalent) – Timestamp(s) when wavefront from target passes reference position, shape T
offset (dict, optional) – Keyword arguments for Target.plane_to_sphere() to offset delay centre relative to target (see method for details)
pressure (Quantity, optional) – Total barometric pressure at surface, broadcastable to shape (A, prod(T))
temperature (Quantity, optional) – Ambient air temperature at surface, broadcastable to shape (A, prod(T)). If the relative humidity is positive, the temperature has to be set.
relative_humidity (Quantity or array-like, optional) – Relative humidity at surface, as a fraction in range [0, 1], broadcastable to shape (A, prod(T))

Returns:

delays (dict mapping str to Quantity, shape T) – Delay correction per correlator input name and timestamp
phases (dict mapping str to Angle, shape T) – Phase correction per correlator input name and timestamp
delay_rates (dict mapping str to Quantity) – Delay rate correction per correlator input name and timestamp. The quantity shape is like T, except the first dimension is 1 smaller. The quantity will be an empty array if there are fewer than 2 times.
fringe_rates (dict mapping str to Quantity) – Fringe rate correction per correlator input name and timestamp. The quantity shape is like T, except the first dimension is 1 smaller. The quantity will be an empty array if there are fewer than 2 times.

Raises:

ValueError – If the relative humidity is positive but temperature is unspecified

delays(target, timestamp, offset=None, pressure: Unit("hPa") = <Quantity 0. hPa>, temperature: Unit("deg_C") = <Quantity -300. deg_C>, relative_humidity: Unit(dimensionless) = 0) -> Unit("s")

Calculate delays for all timestamps and inputs for a given target.

These delays include all geometric effects (also non-intersecting axis offsets) and known fixed/cable delays, but not the extra_correction needed to make delay corrections strictly positive.

Parameters:

target (Target) – Target providing direction for geometric delays
timestamp (Time, Timestamp or equivalent) – Timestamp(s) when wavefront from target passes reference position, shape T
offset (dict, optional) – Keyword arguments for Target.plane_to_sphere() to offset delay centre relative to target (see method for details)
pressure (Quantity, optional) – Total barometric pressure at surface, broadcastable to shape (A, prod(T))
temperature (Quantity, optional) – Ambient air temperature at surface, broadcastable to shape (A, prod(T)). If the relative humidity is positive, the temperature has to be set.
relative_humidity (Quantity or array-like, optional) – Relative humidity at surface, as a fraction in range [0, 1], broadcastable to shape (A, prod(T))

Returns:

delays – Delays for 2A correlator inputs and timestamps with shape T, with ordering on the first axis matching the labels in inputs

Return type:

Quantity, shape (2 * A,) + T

Raises:

ValueError – If the relative humidity is positive but temperature is unspecified

property description: Complete string representation of object that allows reconstruction.

property max_delay: Unit("s"): The maximum (absolute) delay achievable in the array.

property ref_location: Location of reference antenna.

property tropospheric_model: Unique identifier of tropospheric model, or ‘None’ for no correction.

class katpoint.DelayModel(model=None)

Bases: Model

Model of the delay contribution from a single antenna.

This object is purely used as a repository for model parameters, allowing easy construction, inspection and saving of the delay model. The actual calculations happen in DelayCorrection, which is more efficient as it handles multiple antenna delays simultaneously.

Parameters:: model (file-like or model object, sequence of floats, or string, optional) – Model specification. If this is a file-like or model object, load the model from it. If this is a sequence of floats, accept it directly as the model parameters (defaults to sequence of zeroes). If it is a string, interpret it as a comma-separated (or whitespace-separated) sequence of parameters in their string form (i.e. a description string). The default is an empty model.

property delay_params: The model parameters converted to delays in seconds.

fromdelays(delays)

Update model from a sequence of delay parameters.

Parameters:: delays (sequence of floats) – Model parameters in delay form (i.e. in seconds)

class katpoint.FluxDensityModel(min_frequency: Unit('Hz'), max_frequency: Unit('Hz'), coefs)

Bases: object

Spectral flux density model.

This models the spectral flux density (or spectral energy distribtion - SED) of a radio source as:

log10(S) = a + b*log10(v) + c*log10(v)**2 + d*log10(v)**3 + e*exp(f*log10(v))

where S is the flux density in janskies (Jy) and v is the frequency in MHz. The model is based on the Baars polynomial [BGP1977] (up to a third- order term) and extended with an exponential term from the 1Jy catalogue [KWP+1981]. It is considered valid for a specified frequency range only. For any frequencies outside this range a value of NaN is returned.

It also models polarisation: an optional (I, Q, U, V) vector may be given to specify fractional Stokes parameters, which scale S. If not specified, the default is unpolarised (I = 1, Q = U = V = 0). It is recommended that I is left at 1, but it can be changed to model non-physical sources e.g. negative CLEAN components.

The object can be instantiated directly with the minimum and maximum frequencies of the valid frequency range and the model coefficients, or indirectly via a description string. This string contains the minimum frequency, maximum frequency and model coefficients as space-separated values (optionally with parentheses enclosing the entire string). Some examples:

'1000.0 2000.0 0.34 -0.85 -0.02'
'(1000.0 2000.0 0.34 -0.85 0.0 0.0 2.3 -1.0)'
'1000.0 2000.0 0.34 -0.85 0.0 0.0 2.3 -1.0  1.0 0.2 -0.1 0.0'

If less than the expected number of coefficients are provided, the rest are assumed to be zero, except that I is assumed to be one. If more than the expected number are provided, the extra coefficients are ignored, but a warning is shown.

Parameters:

min_frequency (Quantity) – Minimum and maximum frequency for which model is valid
max_frequency (Quantity) – Minimum and maximum frequency for which model is valid
coefs (sequence of floats, optional) – Model coefficients (a, b, c, d, e, f, I, Q, U, V), where missing coefficients at the end of the sequence are assumed to be zero (except for I, assumed to be one), and extra coefficients are ignored.

References

[BGP1977]

J.W.M. Baars, R. Genzel, I.I.K. Pauliny-Toth, A. Witzel, “The Absolute Spectrum of Cas A; An Accurate Flux Density Scale and a Set of Secondary Calibrators,” Astron. Astrophys., 61, 99-106, 1977.

[KWP+1981]

H. Kuehr, A. Witzel, I.I.K. Pauliny-Toth, U. Nauber, “A catalogue of extragalactic radio sources having flux densities greater than 1 Jy at 5 GHz,” Astron. Astrophys. Suppl. Ser., 45, 367-430, 1981.

property description: Complete string representation of object, sufficient to reconstruct it.

flux_density(frequency: Unit('Hz'))

Calculate Stokes I flux density for given observation frequency.

Parameters:: frequency (Quantity, optional) – Frequency at which to evaluate flux density
Returns:: flux_density – Flux density, or NaN Jy if frequency is out of range. The shape matches the input.
Return type:: Quantity

flux_density_stokes(frequency: Unit('Hz'))

Calculate full-Stokes flux density for given observation frequency.

Parameters:: frequency (Quantity, optional) – Frequency at which to evaluate flux density
Returns:: flux_density – Flux density, or NaN Jy if frequency is out of range. The shape matches the input with an extra trailing dimension of size 4 containing Stokes I, Q, U, V.
Return type:: Quantity

classmethod from_description(description)

Construct flux density model object from description string.

Parameters:: description (str) – String of space-separated parameters (optionally in parentheses)
Returns:: flux_model – Constructed flux density model object
Return type:: FluxDensityModel
Raises:: FluxError – If description has the wrong format

property iquv_scale: Fractional Stokes parameters which scale the flux density.

exception katpoint.FluxError

Bases: ValueError

Exception for a flux parsing error.

class katpoint.Model(params)

Bases: object

Base class for models (e.g. pointing and delay models).

The base class handles the construction / loading, saving, display and comparison of models. A Model consists of a sequence of Parameters and an optional header dict. A number of these parameters may be active, i.e. not equal to their default values.

Models can be constructed from description strings (fromstring()), sequences of parameter values (fromlist()), configuration files (fromfile()) or other similar models. The set() method automatically picks the correct constructor based on the input.

Parameter names and values may be accessed and modified via a dict-like interface mapping names to values.

Parameters:: params (sequence of Parameter objects) – Full set of model parameters in the expected order

property description: Compact but complete string representation (‘tostring’).

fromfile(file_like)

Load model from config file (both header and parameters).

Parameters:: file_like (object) – File-like object with readline() method representing config file
Raises:: BadModelFile – If file_like could not be read or parsed

fromlist(floats): Load model from sequence of floats.

fromstring(description): Load model from description string (parameters only).

keys(): List of parameter names in the expected order.

param_strs(): Justified (name, value, units, doc) strings for active parameters.

set(model=None)

Load parameter values from the appropriate source.

Parameters:: model (file-like or model object, sequence of floats, or string, optional) – Model specification. If this is a file-like or model object, load the model from it (including header). If this is a sequence of floats, accept it directly as the model parameters. If it is a string, interpret it as a comma-separated (or whitespace- separated) sequence of parameters in their string form (i.e. a description string). The default is an empty model.
Raises:: BadModelFile – If model is of incorrect type

tofile(file_like)

Save model to config file (both header and parameters).

Parameters:: file_like (object) – File-like object with write() method representing config file

values(): List of parameter values in the expected order (‘tolist’).

exception katpoint.NonAsciiError

Bases: ValueError

Exception when non-ascii characters are found.

class katpoint.Parameter(name, units, doc, from_str=<class 'float'>, to_str=<class 'str'>, value=None, default_value=0.0)

Bases: object

Generic model parameter.

This represents a single model parameter, bundling together its attributes and enabling it to be read from a string and output to a string by getting and setting the value_str property.

Parameters:

name (string) – Parameter name
units (string) – Physical unit of parameter value
doc (string) – Documentation string describing parameter
from_str (function, signature float = f(string), optional) – Conversion function to extract parameter from string
to_str (function, signature string = f(float), optional) – Conversion function to express parameter as string
value (float, optional) – Parameter value (default_value by default, of course)
default_value (float, optional) – Parameter default value

value_str

property value_str: String form of parameter value used to convert it to/from a string.

class katpoint.PointingModel(model=None)

Bases: Model

Correct pointing using model of non-ideal antenna mount.

The pointing model is the one found in the VLBI Field System and has the standard terms found in most pointing models, including the DSN and TPOINT models. These terms are numbered P1 to P22. The first 8 have a standard physical interpretation related to misalignment of the mount coordinate system and gravitational deformation, while the rest are ad hoc parameters that model remaining systematic effects in the pointing error residuals. Gravitational deformation may be considered ad hoc, too. The pointing model is specialised for an alt-az mount.

Parameters:: model (PointingModel, file-like, sequence of 22 floats, string, optional) – Model specification. If this is a model or file-like object, load the model from it. If this is a sequence of floats, accept it directly as the model parameters (defaults to sequence of zeroes). If it is a string, interpret it as a comma-separated (or whitespace-separated) sequence of parameters in their string form (i.e. a description string).

apply(az, el)

Apply pointing correction to requested (az, el) position(s).

Parameters:

az (float or sequence) – Requested azimuth angle(s), in radians
el (float or sequence) – Requested elevation angle(s), in radians

Returns:

pointed_az (float or array) – Azimuth angle(s), corrected for pointing errors, in radians
pointed_el (float or array) – Elevation angle(s), corrected for pointing errors, in radians

fit(az, el, delta_az, delta_el, sigma_daz=None, sigma_del=None, enabled_params=None, keep_disabled_params=False)

Fit pointing model parameters to observed offsets.

This fits the pointing model to a sequence of observed (az, el) offsets. A subset of the parameters can be fit, while the rest will either be kept (fixed) or zeroed. This is generally a good idea, as most of the parameters (P9 and above) are ad hoc and should only be enabled if there are sufficient evidence for them in the pointing error residuals.

While zeroing is the original behaviour, it is deprecated and will eventually be removed, since the user can always explicitly zero the model before calling fit() to get the same result. The contribution of fixed parameters will be subtracted from delta_az and delta_el before the enabled parameters are fit to the residual.

Standard errors can be specified for the input offsets, and will be reflected in the returned standard errors on the fitted parameters.

Parameters:

az (sequence of floats, length N) – Requested azimuth and elevation angles, in radians
el (sequence of floats, length N) – Requested azimuth and elevation angles, in radians
delta_az (sequence of floats, length N) – Corresponding observed azimuth and elevation offsets, in radians
delta_el (sequence of floats, length N) – Corresponding observed azimuth and elevation offsets, in radians
sigma_daz (sequence of floats, length N, optional) – Standard deviation of azimuth and elevation offsets, in radians
sigma_del (sequence of floats, length N, optional) – Standard deviation of azimuth and elevation offsets, in radians
enabled_params (sequence of ints or bools, optional) – List of model parameters that will be enabled during fitting, specified by a list of integer indices or boolean flags. The integers start at 1 and correspond to the P-number. The default is to select the 6 main parameters modelling coordinate misalignment, which are P1, P3, P4, P5, P6 and P7.
keep_disabled_params (bool, optional) – If True, disabled parameters (i.e. those that are not fitted) keep their values and are treated as fixed / frozen parameters. If False, they are zeroed. A future version of katpoint will force this to be True and remove the parameter.

Returns:

params (float array, shape (22,)) – Fitted model parameters (full model), in radians
sigma_params (float array, shape (22,)) – Standard errors on fitted parameters, in radians

Notes

Since the standard pointing model is linear in the model parameters, it is fit with linear least-squares techniques. This is done by creating a design matrix and solving the linear system via singular value decomposition (SVD), as explained in [PTV+1992].

References

[PTV+1992]

Press, Teukolsky, Vetterling, Flannery, “Numerical Recipes in C,” 2nd Ed., pp. 671-681, 1992. Section 15.4: “General Linear Least Squares”, available at http://www.nrbook.com/a/bookcpdf/c15-4.pdf

offset(az, el)

Obtain pointing offset at requested (az, el) position(s).

Parameters:

az (float or sequence) – Requested azimuth angle(s), in radians
el (float or sequence) – Requested elevation angle(s), in radians

Returns:

delta_az (float or array) – Offset(s) that has to be added to azimuth to correct it, in radians
delta_el (float or array) – Offset(s) that has to be added to elevation to correct it, in radians

Notes

The model is based on poclb/fln.c and poclb/flt.c in Field System version 9.9.0. The C implementation differs from the official description in [Him1993], introducing minor changes to the ad hoc parameters. In this implementation, the angle phi is fixed at 90 degrees, which hard-codes the model for a standard alt-az mount.

The model breaks down at the pole of the alt-az mount, which is at zenith (an elevation angle of 90 degrees). At zenith, the azimuth of the antenna is undefined, and azimuth offsets produced by the pointing model may become arbitrarily large close to zenith. To avoid this singularity, the azimuth offset is capped by adjusting the elevation away from 90 degrees specifically in its calculation. This adjustment occurs within 6 arcminutes of zenith.

References

[Him1993]

Himwich, “Pointing Model Derivation,” Mark IV Field System Reference Manual, Version 8.2, 1 September 1993.

reverse(pointed_az, pointed_el)

Remove pointing correction from (az, el) coordinate(s).

This undoes a pointing correction that resulted in the given (az, el) coordinates. It is the inverse of apply().

Parameters:

pointed_az (float or sequence) – Azimuth angle(s), corrected for pointing errors, in radians
pointed_el (float or sequence) – Elevation angle(s), corrected for pointing errors, in radians

Returns:

az (float or array) – Azimuth angle(s) before pointing correction, in radians
el (float or array) – Elevation angle(s) before pointing correction, in radians

class katpoint.RefractionCorrection(model='VLBI Field System')

Bases: object

Correct pointing for refractive bending in atmosphere.

This uses the specified refraction model to calculate a correction to a given elevation angle to account for refractive bending in the atmosphere, based on surface weather measurements. The refraction correction can also be undone, usually to refer the actual antenna position to the coordinate frame before corrections were applied.

Parameters:: model (string, optional) – Name of refraction model to use
Raises:: ValueError – If the specified refraction model is unknown

apply(el, temperature_C, pressure_hPa, humidity_percent)

Apply refraction correction to elevation angle.

Each input parameter can either be a scalar value or an array of values, as long as all arrays are of the same shape.

Parameters:

el (float or array) – Requested elevation angle(s), in radians
temperature_C (float or array) – Ambient air temperature at surface, in degrees Celsius
pressure_hPa (float or array) – Total barometric pressure at surface, in hectopascal (hPa) or millibars
humidity_percent (float or array) – Relative humidity at surface, as a percentage in range [0, 100]

Returns:

refracted_el – Elevation angle(s), corrected for refraction, in radians

Return type:

float or array

reverse(refracted_el, temperature_C, pressure_hPa, humidity_percent)

Remove refraction correction from elevation angle.

This undoes a refraction correction that resulted in the given elevation angle. It is the inverse of apply().

Parameters:

refracted_el (float or array) – Elevation angle(s), corrected for refraction, in radians
temperature_C (float or array) – Ambient air temperature at surface, in degrees Celsius
pressure_hPa (float or array) – Total barometric pressure at surface, in hectopascal (hPa) or millibars
humidity_percent (float or array) – Relative humidity at surface, as a percentage in range [0, 100]

Returns:

el – Elevation angle(s) before refraction correction, in radians

Return type:

float or array

class katpoint.Target(target, name=<object object>, user_tags=<object object>, aliases=<object object>, flux_model=<object object>, antenna=<object object>, flux_frequency=<object object>)

Bases: object

A target which can be pointed at by an antenna.

This is a wrapper around a Body that adds alternate names, descriptive tags and a flux density model. For convenience, a default antenna and flux frequency can be set, to simplify the calling of pointing and flux density methods. It is also possible to construct a Target directly from an SkyCoord.

The object can be constructed from its constituent components or from a description string. The description string contains up to five comma-separated fields, with the format:

[<name list>,] <tags>, [<location 1>, [<location 2>, [<flux model>]]]

The <name list> contains a pipe-separated list of alternate names for the target, with the preferred name either indicated by a prepended asterisk or assumed to be the first name in the list. The names may contain spaces. The list may also be empty, or the entire field may be missing, to indicate an unnamed target. In this case a name will be inferred from the body.

The <tags> field contains a space-separated list of descriptive tags for the target. The first tag is mandatory and indicates the body type of the target, which should be one of (azel, radec, gal, special, tle, xephem).

For azel, radec and gal targets, the two location fields contain the relevant longitude and latitude coordinates, respectively. The following angle string formats are supported:

- Decimal, always in degrees (e.g. '12.5')
- Sexagesimal, in hours for right ascension and degrees for the rest,
  with a colon or space separator (e.g. '12:30:00' or '12 30')
- Decimal or sexagesimal with explicit unit suffix 'd' or 'h',
  e.g. '12.5h' (hours, not degrees!) or '12:30d'

The special body type has no location fields. The special target name is typically one of the major solar system objects supported by Astropy’s ephemeris routines. Alternatively, it could be “Nothing”, which indicates a dummy target with no position (useful as a placeholder but not much else).

For tle bodies, the two location fields contain the two lines of the element set. If the name list is empty, the target name is derived from the TLE instead.

The xephem body contains a string in XEphem EDB database format as the first location field, with commas replaced by tildes. If the name list is empty, the target name is taken from the XEphem string instead. Only fixed and Earth satellite objects are supported.

The <flux model> is a space-separated list of numbers used to represent the flux density of the target. The first two numbers specify the frequency range for which the flux model is valid (in MHz), and the rest of the numbers are model coefficients. The <flux model> may be enclosed in parentheses to distinguish it from the other fields. An example string is:

name1 | *name 2, radec cal, 12:34:56.7, -04:34:34.2, (1000.0 2000.0 1.0)

The default antenna and flux frequency are not stored in the description string.

In summary, description strings take the following forms based on body type:

[<name list>,] azel [<user tags>], <az>, <el> [, <flux model>]
[<name list>,] radec [<user tags>], <ra>, <dec> [, <flux model>]
[<name list>,] gal [<user tags>], <l>, <b> [, <flux model>]
<name list>, special [<user tags>] [, <flux model>]
[<name list>,] tle [<user tags>], <TLE line 1>, <TLE line 2> [, <flux model>]
[<name list>,] xephem radec [<user tags>], <EDB string (type 'f')> [, <flux>]
[<name list>,] xephem tle [<user tags>], <EDB string (type 'E')> [, <flux>]

Parameters:

target (Body, SkyCoord, str or) – Target A Body, a SkyCoord, a full description string or existing Target object. The parameters in the description string or existing Target can still be overridden by providing additional parameters after target.
name (str, optional) – Preferred name of target (use the default Body name if empty)
user_tags (sequence of str, or whitespace-delimited str, optional) – Descriptive tags associated with target (not including body type)
aliases (iterable of str, optional) – Alternate names of target
flux_model (FluxDensity, optional) – Object encapsulating spectral flux density model
antenna (EarthLocation or Antenna, optional) – Default antenna / location to use for position calculations
flux_frequency (Quantity, optional) – Default frequency at which to evaluate flux density

Raises:

ValueError – If description string has the wrong format

add_tags(tags)

Add tags to target object.

This adds tags to a target, while checking the sanity of the tags. It also prevents duplicate tags without resorting to a tag set, which would be problematic since the tag order is meaningful (tags[0] is the body type). Since tags should not contain whitespace, any string consisting of whitespace-delimited words will be split into separate tags.

Parameters:: tags (str, list of str, or None) – Tag or list of tags to add (strings will be split on whitespace)
Returns:: target – Updated target object
Return type:: Target

property aliases: Tuple of alternate names of the target.

apparent_radec(timestamp=None, antenna=None)

Calculate target’s apparent (ra, dec) as seen from antenna at time(s).

This calculates the apparent topocentric position of the target for the epoch-of-date in equatorial coordinates. Take note that this is not the “star-atlas” position of the target, but the position as is actually seen from the antenna at the given times. The difference is on the order of a few arcminutes. These are the coordinates that a telescope with an equatorial mount would use to track the target.

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna which points at target (defaults to default antenna)

Returns:

radec – Right ascension and declination in CIRS frame

Return type:

CIRS, same shape as timestamp

Raises:

ValueError – If no antenna is specified and body type requires it for (ra, dec)

astrometric_radec(timestamp=None, antenna=None)

Calculate target’s astrometric (ra, dec) as seen from antenna at time(s).

This calculates the ICRS astrometric topocentric position of the target, in equatorial coordinates. This is its star atlas position for the epoch of J2000, as seen from the antenna (also called “catalog coordinates” in SOFA).

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna which points at target (defaults to default antenna)

Returns:

radec – Right ascension and declination in ICRS frame

Return type:

ICRS, same shape as timestamp

Raises:

ValueError – If no antenna is specified and body type requires it for (ra, dec)

azel(timestamp=None, antenna=None)

Calculate target (az, el) coordinates as seen from antenna at time(s).

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna which points at target (defaults to default antenna)

Returns:

azel – Azimuth and elevation in AltAz frame

Return type:

AltAz, same shape as timestamp

Raises:

ValueError – If no antenna is specified and body type requires it for (az, el)

property body_type: Type of target body, as a string tag.

property description: Complete string representation of target object.

flux_density(frequency: Unit('Hz') = None)

Calculate flux density for given observation frequency (or frequencies).

This uses the stored flux density model to calculate the flux density at a given frequency (or frequencies). See the documentation of FluxDensityModel for more details of this model. If the flux frequency is unspecified, the default value supplied to the target object during construction is used. If no flux density model is available or a frequency is out of range, a flux value of NaN is returned for that frequency.

This returns only Stokes I. Use flux_density_stokes() to get polarisation information.

Parameters:: frequency (Quantity, optional) – Frequency at which to evaluate flux density
Returns:: flux_density – Flux density in Jy, or np.nan if frequency is out of range or target does not have flux model. The shape matches the input.
Return type:: Quantity
Raises:: ValueError – If no frequency is specified, and no default frequency was set either

flux_density_stokes(frequency: Unit('Hz') = None)

Calculate flux density for given observation frequency(-ies), full-Stokes.

See flux_density() This uses the stored flux density model to calculate the flux density at a given frequency (or frequencies). See the documentation of FluxDensityModel for more details of this model. If the flux frequency is unspecified, the default value supplied to the target object during construction is used. If no flux density model is available or a frequency is out of range, a flux value of NaN is returned for that frequency.

Parameters:: frequency (Quantity, optional) – Frequency at which to evaluate flux density
Returns:: flux_density – Flux density in Jy, or np.nan if frequency is out of range or target does not have flux model. The shape matches the input with an extra trailing dimension of size 4 containing Stokes I, Q, U, V.
Return type:: Quantity
Raises:: ValueError – If no frequency is specified, and no default frequency was set either

property flux_frequency: Default frequency at which to evaluate flux density.

classmethod from_azel(az, el)

Create unnamed stationary target (azel body type).

Parameters:

az (Angle or equivalent, string or float) –
el (Angle or equivalent, string or float) –
elevation (Azimuth and) –
Angle (as anything accepted by) –
or (a sexagesimal) –
degrees (decimal string in) –
radians (or as a float in) –

Returns:

target – Constructed target object

Return type:

Target

classmethod from_description(description)

Construct Target object from description string.

For more information on the description string format, see the help string for Target.

Parameters:: description (str) – String containing target name(s), tags, location and flux model
Returns:: target – Constructed target object
Return type:: Target
Raises:: ValueError – If description has the wrong format

classmethod from_radec(ra, dec)

Create unnamed fixed target (radec body type, ICRS frame).

Parameters:

ra (Angle or equivalent, string or float) – Right ascension, as anything accepted by Angle, a sexagesimal string in hours, a decimal string in degrees, or as a float in radians
dec (Angle or equivalent, string or float) – Declination, as anything accepted by Angle, a sexagesimal or decimal string in degrees, or as a float in radians

Returns:

target – Constructed target object

Return type:

Target

galactic(timestamp=None, antenna=None)

Calculate target’s galactic (l, b) as seen from antenna at time(s).

This calculates the galactic coordinates of the target, based on the ICRS astrometric topocentric coordinates. This is its position relative to the Galactic frame for the epoch of J2000 as seen from the antenna.

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna which points at target (defaults to default antenna)

Returns:

lb – Galactic longitude, l, and latitude, b, in Galactic frame

Return type:

Galactic, same shape as timestamp

Raises:

ValueError – If no antenna is specified and body type requires it for (l, b)

geometric_delay(antenna2, timestamp=None, antenna=None)

Calculate geometric delay between two antennas pointing at target.

An incoming plane wavefront travelling along the direction from the target to the reference antenna antenna arrives at this antenna at the given timestamp(s), and delay seconds later (or earlier, if delay is negative) at the second antenna, antenna2. This delay is known as the geometric delay, also represented by the symbol \(\tau_g\), and is associated with the baseline vector from the reference antenna to the second antenna. Additionally, the rate of change of the delay at the given timestamp(s) is estimated from the change in delay during a short interval spanning the timestamp(s).

Parameters:

antenna2 (EarthLocation or Antenna) – Second antenna of baseline pair (baseline vector points toward it)
timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional First (reference) antenna of baseline pair, which also serves as pointing reference (defaults to default antenna)

Returns:

delay (Quantity of same shape as timestamp) – Geometric delay
delay_rate (Quantity of same shape as timestamp) – Rate of change of geometric delay, in seconds per second

Raises:

ValueError – If no reference antenna is specified and no default antenna was set

Notes

This is a straightforward dot product between the unit vector pointing from the reference antenna to the target, and the baseline vector pointing from the reference antenna to the second antenna, all in local ENU coordinates relative to the reference antenna.

lmn(ra, dec, timestamp=None, antenna=None)

Calculate (l, m, n) coordinates for another target relative to self.

Calculate (l, m, n) coordinates for another target, while pointing at this target.

Refer to uvw() for a description of the coordinate system. This function is vectorised, allowing for multiple targets and multiple timestamps.

Parameters:

ra (float or array) – Right ascension of the other target, in radians
dec (float or array) – Declination of the other target, in radians
timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Pointing reference (defaults to default antenna)

Returns:

l,m,n – (l, m, n) coordinates of target(s).

Return type:

float, or array of same length as ra, dec, timestamps

property name: Preferred name of the target.

property names: Tuple of all names (both preferred and alternate) of the target.

parallactic_angle(timestamp=None, antenna=None)

Calculate parallactic angle on target as seen from antenna at time(s).

This calculates the parallactic angle, which is the position angle of the observer’s vertical on the sky, measured from north toward east. This is the angle between the great-circle arc connecting the celestial North pole to the target position, and the great-circle arc connecting the zenith above the antenna to the target, or the angle between the hour circle and vertical circle through the target, at the given timestamp(s).

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna which points at target (defaults to default antenna)

Returns:

parangle – Parallactic angle

Return type:

Angle, same shape as timestamp

Raises:

ValueError – If no antenna is specified, and no default antenna was set either

Notes

The formula can be found in the AIPS++ glossary or in the SLALIB source code (file pa.f, function sla_PA) which is part of the now defunct Starlink project.

plane_to_sphere(x, y, timestamp=None, antenna=None, projection_type='ARC', coord_system='azel')

Deproject plane coordinates to sphere with target position as reference.

This is a convenience function that deprojects plane coordinates to a sphere with the target position as the origin of the plane. The function is vectorised and can operate on single or multiple timestamps, as well as single or multiple coordinate vectors. The spherical coordinates may be (az, el) or (ra, dec), and the projection type can also be specified.

Parameters:

x (float or array) – Azimuth-like coordinate(s) on plane, in radians
y (float or array) – Elevation-like coordinate(s) on plane, in radians
timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna pointing at target (defaults to default antenna)
projection_type ({'ARC', 'SIN', 'TAN', 'STG', 'CAR', 'SSN'}, optional) – Type of spherical projection
coord_system ({'azel', 'radec'}, optional) – Spherical coordinate system

Returns:

az (float or array) – Azimuth or right ascension, in radians
el (float or array) – Elevation or declination, in radians

radec(timestamp=None, antenna=None)

Calculate target’s astrometric (ra, dec) as seen from antenna at time(s).

This calculates the ICRS astrometric topocentric position of the target, in equatorial coordinates. This is its star atlas position for the epoch of J2000, as seen from the antenna (also called “catalog coordinates” in SOFA).

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna which points at target (defaults to default antenna)

Returns:

radec – Right ascension and declination in ICRS frame

Return type:

ICRS, same shape as timestamp

Raises:

ValueError – If no antenna is specified and body type requires it for (ra, dec)

separation(other_target, timestamp=None, antenna=None)

Angular separation between this target and another as viewed from antenna.

Parameters:

other_target (Target) – The other target
timestamp (Time, Timestamp or equiv, optional) – Timestamp(s) when separation is measured (defaults to now)
antenna (EarthLocation or) – Antenna, optional Antenna that observes both targets, from where separation is measured (defaults to default antenna of this target)

Returns:

separation – Angular separation between the targets, as viewed from antenna

Return type:

Angle

Notes

This calculates the azimuth and elevation of both targets at the given time and finds the angular distance between the two sets of coordinates.

sphere_to_plane(az, el, timestamp=None, antenna=None, projection_type='ARC', coord_system='azel')

Project spherical coordinates to plane with target position as reference.

This is a convenience function that projects spherical coordinates to a plane with the target position as the origin of the plane. The function is vectorised and can operate on single or multiple timestamps, as well as single or multiple coordinate vectors. The spherical coordinates may be (az, el) or (ra, dec), and the projection type can also be specified.

Parameters:

az (float or array) – Azimuth or right ascension, in radians
el (float or array) – Elevation or declination, in radians
timestamp (Time, Timestamp or equiv, optional) – Timestamp(s), defaults to now
antenna (EarthLocation or) – Antenna, optional Antenna pointing at target (defaults to default antenna)
projection_type ({'ARC', 'SIN', 'TAN', 'STG', 'CAR', 'SSN'}, optional) – Type of spherical projection
coord_system ({'azel', 'radec'}, optional) – Spherical coordinate system

Returns:

x (float or array) – Azimuth-like coordinate(s) on plane, in radians
y (float or array) – Elevation-like coordinate(s) on plane, in radians

property tags: List of descriptive tags associated with target, body type first.

uvw(antenna2, timestamp=None, antenna=None)

Calculate (u,v,w) coordinates of baseline while pointing at target.

Calculate the (u,v,w) coordinates of the baseline vector from antenna toward antenna2. The w axis points from the first antenna toward the target. The v axis is perpendicular to it and lies in the plane passing through the w axis and the poles of the earth, on the northern side of w. The u axis is perpendicular to the v and w axes, and points to the east of w.

Parameters:

antenna2 (EarthLocation or) – Antenna or sequence Second antenna of baseline pair (baseline vector points toward it), shape A
timestamp (Time, Timestamp or equiv, optional) – Timestamp(s) of shape T, defaults to now
antenna (EarthLocation or) – Antenna, optional First (reference) antenna of baseline pair, which also serves as pointing reference (defaults to default antenna)

Returns:

uvw – (u, v, w) coordinates of baseline as Cartesian (x, y, z), in units of length. The shape is a concatenation of the timestamp and antenna2 shapes.

Return type:

CartesianRepresentation, shape T + A

Notes

All calculations are done in the local ENU coordinate system centered on the first antenna, as opposed to the traditional XYZ coordinate system. This avoids having to convert (az, el) angles to (ha, dec) angles and uses linear algebra throughout instead.

uvw_basis(timestamp=None, antenna=None)

Calculate ENU -> (u,v,w) transform while pointing at the target.

Calculate the coordinate transformation from local ENU coordinates to (u,v,w) coordinates while pointing at the target.

In most cases you should use uvw() directly.

Refer to uvw() for details about how the (u,v,w) coordinate system is defined.

Parameters:

timestamp (Time, Timestamp or equiv, optional) – Timestamp(s) of shape T, defaults to now
antenna (EarthLocation or) – Antenna, optional Reference antenna of baseline pairs, which also serves as pointing reference (defaults to default antenna)

Returns:

uvw_basis – Orthogonal basis vectors for the transformation. If timestamp is scalar, the return value is a matrix to multiply by ENU column vectors to produce UVW vectors. If timestamp is an array of shape T, the first two dimensions correspond to the matrix and the remaining dimension(s) to the timestamp.

Return type:

array of float, shape (3, 3) + T

class katpoint.Timestamp(timestamp=None)

Bases: object

Basic representation of time(s), in UTC seconds since Unix epoch.

This is loosely based on PyEphem’s Date object, but uses an Astropy Time object as internal representation. Like Time it can contain a multi-dimensional array of timestamps.

The following input formats are accepted for a timestamp:

A floating-point number, directly representing the number of UTC seconds since the Unix epoch. Fractional seconds are allowed.
A string or bytes with format ‘YYYY-MM-DD HH:MM:SS.SSS’ (Astropy ‘iso’ format) or ‘YYYY/MM/DD HH:MM:SS.SSS’ (XEphem format), where the hours and minutes, seconds, and fractional seconds are optional. It is always in UTC. Examples are:

‘1999-12-31 12:34:56.789’ ‘1999/12/31 12:34:56’ ‘1999-12-31 12:34’ b’1999-12-31’
A Time object (NOT TimeDelta).
Another Timestamp object, which will result in a copy.
A sequence or NumPy array of one of the above types.
None, which uses the current time (the default).

Parameters:: timestamp (Time, Timestamp, float, string,) – bytes, sequence or array of any of the former, or None, optional Timestamp, in various formats (if None, defaults to now)
Raises:: ValueError – If timestamp is not in a supported format

time

Underlying Time object

Type:: Time

secs

Timestamp as UTC seconds since Unix epoch

Type:: float or array of float

Notes

This differs from Time in the following respects:

Numbers are interpreted as Unix timestamps during initialisation; Timestamp(1234567890) is equivalent to Time(1234567890, format=’unix’) (while Time(1234567890) is not allowed because it lacks a format).
Arithmetic is done in seconds instead of days (in the absence of units).
Date strings may contain slashes (a leftover from PyEphem / XEphem).
Empty initialisation results in the current time, so Timestamp() is equivalent to Time.now() (while Time() is not allowed).

local(): Local time string representation (str or array of str).

property secs: Timestamp as UTC seconds since Unix epoch.

to_mjd(): Convert timestamp to Modified Julian Day (MJD).

to_string(): UTC string representation (str or array of str).

katpoint.azel_to_enu(az_rad, el_rad)

Convert (az, el) spherical coordinates to unit vector in ENU coordinates.

This converts horizontal spherical coordinates (azimuth and elevation angle) to a unit vector in the corresponding local east-north-up (ENU) coordinate system.

Parameters:

az_rad (float or array) – Azimuth and elevation angle, in radians
el_rad (float or array) – Azimuth and elevation angle, in radians

Returns:

e, n, u – East, North, Up coordinates of unit vector

Return type:

float or array

katpoint.construct_azel_target(az, el): Create unnamed stationary target (azel body type) DEPRECATED.

katpoint.construct_radec_target(ra, dec): Create unnamed fixed target (radec body type) DEPRECATED.

katpoint.ecef_to_enu(ref_lat_rad, ref_lon_rad, ref_alt_m, x_m, y_m, z_m)

Convert ECEF coordinates to ENU coordinates relative to reference location.

This converts earth-centered, earth-fixed (ECEF) cartesian coordinates to local east-north-up (ENU) coordinates relative to a given reference position. The reference position is specified by its geodetic latitude, longitude and altitude.

Parameters:

ref_lat_rad (float or array) – Geodetic latitude and longitude of reference position, in radians
ref_lon_rad (float or array) – Geodetic latitude and longitude of reference position, in radians
ref_alt_m (float or array) – Geodetic altitude of reference position, in metres above WGS84 ellipsoid
x_m (float or array) – X, Y, Z coordinates, in metres
y_m (float or array) – X, Y, Z coordinates, in metres
z_m (float or array) – X, Y, Z coordinates, in metres

Returns:

e_m, n_m, u_m – East, North, Up coordinates, in metres

Return type:

float or array

katpoint.ecef_to_lla(x_m, y_m, z_m)

Convert ECEF cartesian coordinates to WGS84 spherical coordinates.

This converts an earth-centered, earth-fixed (ECEF) cartesian position to a position on the Earth specified in geodetic latitude, longitude and altitude. This code assumes the WGS84 earth model.

Parameters:

x_m (float or array) – X, Y, Z coordinates, in metres
y_m (float or array) – X, Y, Z coordinates, in metres
z_m (float or array) – X, Y, Z coordinates, in metres

Returns:

lat_rad (float or array) – Latitude (customary geodetic, not geocentric), in radians
lon_rad (float or array) – Longitude, in radians
alt_m (float or array) – Altitude, in metres above WGS84 ellipsoid

Notes

Based on the most accurate algorithm according to Zhu [zhu], which is summarised by Kaplan [kaplan] and described in the Wikipedia entry [geo].

[zhu]

J. Zhu, “Conversion of Earth-centered Earth-fixed coordinates to geodetic coordinates,” Aerospace and Electronic Systems, IEEE Transactions on, vol. 30, pp. 957-961, 1994.

[kaplan]

Kaplan, “Understanding GPS: principles and applications,” 1 ed., Norwood, MA 02062, USA: Artech House, Inc, 1996.

[geo]

Wikipedia entry, “Geodetic system”, 2009.

katpoint.enu_to_azel(east, north, up)

Convert vector in ENU coordinates to (az, el) spherical coordinates.

This converts a vector in the local east-north-up (ENU) coordinate system to the corresponding horizontal spherical coordinates (azimuth and elevation angle). The ENU coordinates can be in any unit, as the vector length will be normalised in the conversion process.

Parameters:

east (float or array) – East, North, Up coordinates (any unit)
north (float or array) – East, North, Up coordinates (any unit)
up (float or array) – East, North, Up coordinates (any unit)

Returns:

az_rad, el_rad – Azimuth and elevation angle, in radians

Return type:

float or array

katpoint.enu_to_ecef(ref_lat_rad, ref_lon_rad, ref_alt_m, e_m, n_m, u_m)

Convert ENU coordinates relative to reference location to ECEF coordinates.

This converts local east-north-up (ENU) coordinates relative to a given reference position to earth-centered, earth-fixed (ECEF) cartesian coordinates. The reference position is specified by its geodetic latitude, longitude and altitude.

Parameters:

ref_lat_rad (float or array) – Geodetic latitude and longitude of reference position, in radians
ref_lon_rad (float or array) – Geodetic latitude and longitude of reference position, in radians
ref_alt_m (float or array) – Geodetic altitude of reference position, in metres above WGS84 ellipsoid
e_m (float or array) – East, North, Up coordinates, in metres
n_m (float or array) – East, North, Up coordinates, in metres
u_m (float or array) – East, North, Up coordinates, in metres

Returns:

x_m, y_m, z_m – X, Y, Z coordinates, in metres

Return type:

float or array

katpoint.enu_to_xyz(east, north, up, lat_rad)

Convert ENU to XYZ coordinates.

This converts a vector in the local east-north-up (ENU) coordinate system to the XYZ coordinate system used in radio astronomy (see e.g. [TMS]). The X axis is the intersection of the equatorial plane and the meridian plane through the reference point of the ENU system (and therefore is similar to ‘up’). The Y axis also lies in the equatorial plane to the east of X, and coincides with ‘east’. The Z axis points toward the north pole, and therefore is similar to ‘north’. The XYZ system is therefore a local version of the Earth-centred Earth-fixed (ECEF) system.

Parameters:

east (float or array) – East, North, Up coordinates of input vector
north (float or array) – East, North, Up coordinates of input vector
up (float or array) – East, North, Up coordinates of input vector
lat_rad (float or array) – Geodetic latitude of ENU / XYZ reference point, in radians

Returns:

x, y, z – X, Y, Z coordinates of output vector

Return type:

float or array

References

[TMS]

Thompson, Moran, Swenson, “Interferometry and Synthesis in Radio Astronomy,” 2nd ed., Wiley-VCH, 2004, pp. 86-89.

katpoint.hadec_to_enu(ha_rad, dec_rad, lat_rad)

Convert (ha, dec) spherical coordinates to unit vector in ENU coordinates.

This converts equatorial spherical coordinates (hour angle and declination) to a unit vector in the corresponding local east-north-up (ENU) coordinate system. The geodetic latitude of the observer is also required.

Parameters:

ha_rad (float or array) – Hour angle, declination and geodetic latitude, in radians
dec_rad (float or array) – Hour angle, declination and geodetic latitude, in radians
lat_rad (float or array) – Hour angle, declination and geodetic latitude, in radians

Returns:

e, n, u – East, North, Up coordinates of unit vector

Return type:

float or array

katpoint.lla_to_ecef(lat_rad, lon_rad, alt_m)

Convert WGS84 spherical coordinates to ECEF cartesian coordinates.

This converts a position on the Earth specified in geodetic latitude, longitude and altitude to earth-centered, earth-fixed (ECEF) cartesian coordinates. This code assumes the WGS84 earth model, described in [NIMA2004].

Parameters:

lat_rad (float or array) – Latitude (customary geodetic, not geocentric), in radians
lon_rad (float or array) – Longitude, in radians
alt_m (float or array) – Altitude, in metres above WGS84 ellipsoid

Returns:

x_m, y_m, z_m – X, Y, Z coordinates, in metres

Return type:

float or array

References

[NIMA2004]

National Imagery and Mapping Agency, “Department of Defense World Geodetic System 1984,” NIMA TR8350.2, Page 4-4, last updated June, 2004.

katpoint.wrap_angle(angle, period=6.283185307179586)

Wrap angle into interval centred on zero.

This wraps the angle into the interval -period / 2 … period / 2.