katpoint package¶

Submodules¶

katpoint.antenna module¶

Antenna object containing sufficient information to point at a target and 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(name, latitude=None, longitude=None, altitude=None, diameter=0.0, delay_model=None, pointing_model=None, beamwidth=1.22)¶

Bases: object

An antenna that can point at a target.

This is a wrapper around a PyEphem ephem.Observer 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 in WGS84 (lat-long-alt) form, while the second variant is initialised with the array reference location in WGS84 form 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-long-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-long-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.

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 0 0 0 0 0:09:48.9, 1.16'

Parameters

name (string or Antenna object) – Name of antenna, or full description string or existing antenna object
latitude (string or float, optional) – Geodetic latitude, either in ‘D:M:S’ string format or float in radians
longitude (string or float, optional) – Longitude, either in ‘D:M:S’ string format or a float in radians
altitude (string or float, optional) – Altitude above WGS84 geoid, in metres
diameter (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).
position_enu (tuple of 3 floats) – East-North-Up offset from WGS84 reference position, in metres
position_wgs84 (tuple of 3 floats) – WGS84 position of antenna (latitude and longitude in radians, and altitude in metres)
position_ecef (tuple of 3 floats) – ECEF (Earth-centred Earth-fixed) position of antenna (in metres)
ref_position_wgs84 (tuple of 3 floats) – WGS84 reference position (latitude and longitude in radians, and altitude in metres)
observer (ephem.Observer object) – Underlying object used for pointing calculations
ref_observer (ephem.Observer object) – Array reference location for antenna in an array (same as observer for a stand-alone antenna)

Raises

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

Notes

The ephem.Observer objects are abused for their ability to convert latitude and longitude to and from string representations via ephem.Angle. The only reason for the existence of ref_observer is that it is a nice container for the reference latitude, longitude and altitude.

It is a bad idea to edit the coordinates of the antenna in-place, as the various position tuples will not be updated - reconstruct a new antenna object instead.

Also note that the description string of the new Antenna could differ from the original description string if the original string had higher precision in its latitude and longitude coordinates than what ephem can handle internally. Generally the latitude and longitude should be specified up to 0.1 arcsecond precision, while altitude should be in metres and East, North and Up offsets are generally specified up to millimetres.

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 (Antenna object) – Second antenna of baseline pair (baseline vector points toward it)
Returns: e_m, n_m, u_m – East, North, Up coordinates of baseline vector, in metres
Return type: float or array

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

format_katcp()¶: String representation if object is passed as parameter to KATCP command.

local_sidereal_time(timestamp=None)¶

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

This is a vectorised function that returns the local sidereal time at the antenna for a given UTC timestamp.

Parameters: timestamp (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch (defaults to now)
Returns: lst – Local sidereal time(s), in radians
Return type: ephem.Angle object, or sequence of objects

katpoint.catalogue module¶

Target catalogue.

class katpoint.catalogue.Catalogue(targets=None, tags=None, add_specials=False, add_stars=False, antenna=None, flux_freq_MHz=None)¶

Bases: object

A searchable and filterable catalogue of targets.

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:
```
cat = katpoint.Catalogue(add_specials=True)
t = cat['Sun']
```

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

cat = katpoint.Catalogue()

which produces an empty catalogue. The standard special targets, which are the Sun, Moon, planets and Zenith, can be added as follows:

cat = katpoint.Catalogue(add_specials=True)

Another built-in set of targets is the small star catalogue included with PyEphem. These star targets are added as follows:

cat = katpoint.Catalogue(add_stars=True)

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('Ganymede, 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(['Ganymede, 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(file('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('Ganymede, special')
t2 = katpoint.Target('Takreem, azel, 20, 30')
cat = katpoint.Catalogue()
cat.add(t1)
cat.add([t1, t2])
cat.add('Ganymede, special')
cat.add(['Ganymede, special', 'Takreem, azel, 20, 30'])
cat.add(file('catalogue.csv'))

The only functionality that Catalogue.add() lacks is the ability to add all special and star targets in one go. They may still be added individually, although this is less convenient (and the reason for the existence of add_specials and add_stars in the Catalogue initialiser in the first place).

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(file('gps-ops.txt'))
cat.add_edb(file('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(file('gps-ops.txt'), tags='gps satellite')
cat.add_tle(file('glo-ops.txt'), tags=['glonass', 'satellite'])
cat.add(file('source_list.csv'), tags='calibrator')
cat.add_edb(file('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:

cat = katpoint.Catalogue(add_specials=True)
cat.remove('Sun')

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:
```
cat = katpoint.Catalogue(file('source_list.csv'))
cat1 = cat.filter(flux_limit_Jy=[1, 100], flux_freq_MHz=1500)
cat = katpoint.Catalogue(file('source_list.csv'), flux_freq_MHz=1500)
cat1 = cat.filter(flux_limit_Jy=1)
```
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:
```
ant = katpoint.Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
cat = katpoint.Catalogue(add_specials=True)
cat1 = cat.filter(az_limit_deg=[0, 90], timestamp='2009-10-10', antenna=ant)
cat = katpoint.Catalogue(antenna=ant)
cat1 = cat.filter(az_limit_deg=[90, 0])
```

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:

ant = katpoint.Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
cat = katpoint.Catalogue(add_specials=True)
cat1 = cat.filter(el_limit_deg=[10, 30], timestamp='2009-10-10', antenna=ant)
cat = katpoint.Catalogue(antenna=ant)
cat1 = cat.filter(el_limit_deg=10)

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:
```
ant = katpoint.Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
cat = katpoint.Catalogue(add_specials=True)
cat.add_tle(file('geo.txt'))
sun = cat['Sun']
afristar = cat['AFRISTAR']
cat1 = cat.filter(dist_limit_deg=5, proximity_targets=[sun, afristar],
                  timestamp='2009-10-10', antenna=ant)
cat = katpoint.Catalogue(antenna=ant)
cat1 = cat.filter(dist_limit_deg=[0, 5], 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(file('source_list.csv'))
strong_sources = cat.filter(flux_limit_Jy=10.0, flux_freq_MHz=1500)
```
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(file('source_list.csv'))
ant = katpoint.Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
for t in cat.iterfilter(el_limit_deg=10, 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.

Parameters

targets (Target object or string, or sequence of these, optional) – 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)
add_specials (bool, optional) – True if special bodies specified in specials (and ‘Zenith’) should be added
add_stars (bool, optional) – True if star bodies from PyEphem star catalogue should be added
antenna (Antenna object, optional) – Default antenna to use for position calculations for all targets
flux_freq_MHz (float, optional) – Default frequency at which to evaluate flux density of all targets (MHz)

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(file('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(file('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(file('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 object) – Target with which catalogue targets are compared
timestamp (Timestamp object or equivalent, optional) – Timestamp at which to evaluate target positions, in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, optional) – Antenna which points at targets (defaults to default antenna)

Returns

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

filter(tags=None, flux_limit_Jy=None, flux_freq_MHz=None, az_limit_deg=None, el_limit_deg=None, dist_limit_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_Jy (float or sequence of 2 floats, optional) – Allowed flux density range, in Jy. 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_freq_MHz (float, optional) – Frequency at which to evaluate the flux density, in MHz
az_limit_deg (sequence of 2 floats, optional) – Allowed azimuth range, in degrees. 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_deg (float or sequence of 2 floats, optional) – Allowed elevation range, in degrees. 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_deg (float or sequence of 2 floats, optional) – Allowed range of angular distance to proximity targets, in degrees. 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 object, or sequence of objects) – Target or list of targets used in proximity filter
timestamp (Timestamp object or equivalent, optional) – Timestamp at which to evaluate target positions, in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, optional) – Antenna which points at targets (defaults to default antenna)

Returns

subset – Filtered catalogue

Return type

Catalogue object

Raises

ValueError – If some required parameters are missing

Examples

Here are some ways to filter a catalogue:

>>> from katpoint import Catalogue, Antenna
>>> ant = Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
>>> cat = Catalogue(antenna=ant, flux_freq_MHz=1500)
>>> cat1 = cat.filter(el_limit_deg=10)
>>> cat2 = cat.filter(az_limit_deg=[150, -150])
>>> cat3 = cat.filter(flux_limit_Jy=10)
>>> cat4 = cat.filter(tags='special ~radec')
>>> cat5 = cat.filter(dist_limit_deg=5, proximity_targets=cat['Sun'])

property flux_freq_MHz¶: Default frequency at which to evaluate flux density, in MHz.

iterfilter(tags=None, flux_limit_Jy=None, flux_freq_MHz=None, az_limit_deg=None, el_limit_deg=None, dist_limit_deg=None, proximity_targets=None, timestamp=None, antenna=None)¶

Generator function which returns targets satisfying various criteria.

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_Jy (float or sequence of 2 floats, optional) – Allowed flux density range, in Jy. 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_freq_MHz (float, optional) – Frequency at which to evaluate the flux density, in MHz
az_limit_deg (sequence of 2 floats, optional) – Allowed azimuth range, in degrees. 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_deg (float or sequence of 2 floats, optional) – Allowed elevation range, in degrees. 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_deg (float or sequence of 2 floats, optional) – Allowed range of angular distance to proximity targets, in degrees. 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 object, or sequence of objects) – Target or list of targets used in proximity filter
timestamp (Timestamp object or equivalent, optional) – Timestamp at which to evaluate target positions, in UTC seconds since Unix epoch. If None, the current time at each iteration is used.
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

Examples

Here are some ways to filter a catalogue iteratively:

>>> from katpoint import Catalogue, Antenna
>>> ant = Antenna('XDM, -25:53:23, 27:41:03, 1406, 15.0')
>>> cat = Catalogue(antenna=ant)
>>> for t in cat.iterfilter(el_limit_deg=10):
        # 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_freq_MHz=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_freq_MHz (float, optional) – Frequency at which to evaluate the flux density, in MHz
timestamp (Timestamp object or equivalent, optional) – Timestamp at which to evaluate target positions, in UTC seconds since Unix epoch (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_freq_MHz=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 (Timestamp object or equivalent, optional) – Timestamp at which to evaluate target positions, in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, optional) – Antenna which points at targets (defaults to default antenna)
flux_freq_MHz (float, optional) – Frequency at which to evaluate flux density, in MHz
antenna2 (Antenna object, 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¶

Coordinate conversions not found in PyEphem.

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_long_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_long_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
long_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
long_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 long/lat in different ranges.

katpoint.conversion.enu_to_azel(e, n, u)¶

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

e (float or array) – East, North, Up coordinates (any unit)
n (float or array) – East, North, Up coordinates (any unit)
u (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_long_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_long_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(e, n, u, 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

e (float or array) – East, North, Up coordinates of input vector
n (float or array) – East, North, Up coordinates of input vector
u (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, long_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
long_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.delay module¶

Delay model and correction.

This implements the basic delay model used to calculate the delay contribution from each antenna, as well as a class that performs delay correction for a correlator.

class katpoint.delay.DelayCorrection(ants, ref_ant=None, sky_centre_freq=0.0, extra_delay=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.

For now, the reference antenna position must match the reference positions of each antenna in the array, so that the ENU offset in each antenna’s delay model directly represent the baseline between that antenna and the reference antenna. This should be fine as this is the standard case, but may cause problems for e.g. VLBI with a geocentric reference antenna.

Parameters

ants (sequence of M Antenna objects or string) – Sequence of antennas forming an array and connected to correlator; alternatively, a description string representing the entire object
ref_ant (Antenna object or None, optional) – Reference antenna for the array (only optional if ants is a string)
sky_centre_freq (float, optional) – RF centre frequency that serves as reference for fringe phase
extra_delay (None or float, optional) – Additional delay, in seconds, added to all inputs to ensure strictly positive delay corrections (automatically calculated if None)

ant_models¶

Dict mapping antenna name to corresponding delay model

Type: dict mapping string to DelayModel object

Raises: ValueError – If all antennas do not share the same reference position as ref_ant or ref_ant was not specified, or description string is invalid

CACHE_SIZE = 1000¶

corrections(target, timestamp=None, next_timestamp=None, offset=None)¶

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

Calculate delay and phase corrections for the direction towards target at timestamp. If the timestamp of the next delay calculation is provided, it is used to calculate a delay rate that can be used for linear interpolation in the period up to the next update. This process is repeated if a sequence of timestamps is given. Both delay (aka phase slope) and phase (aka phase offset or fringe phase) corrections are provided, and optionally their derivatives with respect to time (delay rate and fringe rate, respectively).

Parameters

target (Target object) – Target providing direction for geometric delays
timestamp (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch when delays are evaluated (default is now). If more than one timestamp is given, the corrections will include slopes to be used for linear interpolation between the times
next_timestamp (Timestamp object or equivalent, optional) – Timestamp when next delay will be evaluated, used to determine a slope for linear interpolation (default is no slope). This is ignored if timestamp is a sequence.
offset (dict or None, optional) – Keyword arguments for Target.plane_to_sphere() to offset delay centre relative to target (see method for details)

Returns

delays (dict mapping string to float or array of floats) – Dict mapping correlator input name to delay correction, which consists of a delay value (in seconds) and optionally a delay rate value (in seconds per second). If a sequence of T timestamps are provided, each input maps to an array of shape (T, 2).
phases (dict mapping string to float or array of floats) – Dict mapping correlator input name to phase correction, which consists of a fringe phase value (in radians) and optionally a fringe rate value (in radians per second). If a sequence of T timestamps are provided, each input maps to an array of shape (T, 2).

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

property max_delay¶: The maximum (absolute) delay achievable in the array, in seconds.

class katpoint.delay.DelayModel(model=None)¶

Bases: katpoint.model.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)

katpoint.ephem_extra module¶

Enhancements to PyEphem.

class katpoint.ephem_extra.NullBody¶

Bases: object

Body with no position, used as a placeholder.

This body has the expected methods of Body, but always returns NaNs for all coordinates. It is intended for use as a placeholder when no proper target object is available, i.e. as a dummy target.

compute(observer)¶

class katpoint.ephem_extra.StationaryBody(az, el, name=None)¶

Bases: object

Stationary body with fixed (az, el) coordinates.

This is a simplified ephem.Body that is useful to specify targets such as zenith and geostationary satellites.

Parameters

az (string or float) – Azimuth and elevation, either in ‘D:M:S’ string format, or float in rads
el (string or float) – Azimuth and elevation, either in ‘D:M:S’ string format, or float in rads
name (string, optional) – Name of body

compute(observer)¶

Update target coordinates for given observer.

This updates the (ra, dec) coordinates of the target, as seen from the given observer, while its (az, el) coordinates remain unchanged.

katpoint.ephem_extra.angle_from_degrees(s)¶: Creates angle object from sexagesimal string in degrees or number in radians.

katpoint.ephem_extra.angle_from_hours(s)¶: Creates angle object from sexagesimal string in hours or number in radians.

katpoint.ephem_extra.deg2rad(x)¶: Converts degrees to radians (also works for arrays).

katpoint.ephem_extra.is_iterable(x)¶: Checks if object is iterable (but not a string or 0-dimensional array).

katpoint.ephem_extra.rad2deg(x)¶: Converts radians to degrees (also works for arrays).

katpoint.ephem_extra.wrap_angle(angle, period=6.283185307179586)¶

Wrap angle into interval centred on zero.

This wraps the angle into the interval -period / 2 … period / 2.

katpoint.flux module¶

Flux density model.

class katpoint.flux.FluxDensityModel(min_freq_MHz, max_freq_MHz=None, coefs=None)¶

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_freq_MHz (float or string) – Minimum frequency for which model is valid, in MHz. Alternatively, this is a description string containing the minimum frequency, maximum frequency and model coefficients as space-separated values (optionally with parentheses enclosing the entire string).
max_freq_MHz (float, optional) – Maximum frequency for which model is valid, in MHz
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, assumes to be one), and extra coefficients are ignored.

Raises

ValueError – If description string has the wrong format or is mixed with normal parameters

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.

flux_density(freq_MHz)¶

Calculate Stokes I flux density for given observation frequency.

Parameters: freq_MHz (float, or sequence of floats) – Frequency at which to evaluate flux density, in MHz
Returns: flux_density – Flux density in Jy, or np.nan if the frequency is out of range
Return type: float, or array of floats of same shape as freq_MHz

flux_density_stokes(freq_MHz)¶

Calculate full-Stokes flux density for given observation frequency.

Parameters: freq_MHz (float, or sequence of floats) – Frequency at which to evaluate flux density, in MHz
Returns: flux_density – Flux density in Jy, or np.nan if the frequency is out of range. The array has an extra final axis of length 4, corresponding to the I, Q, U, V components.
Return type: array of floats

property iquv_scale¶

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

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.

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: katpoint.model.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 ephem 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()¶: 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 correction for refractive bending in the atmosphere.

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

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(body, tags=None, aliases=None, flux_model=None, antenna=None, flux_freq_MHz=None)¶

Bases: object

A target which can be pointed at by an antenna.

This is a wrapper around a PyEphem ephem.Body that adds flux density, alternate names and descriptive tags. For convenience, a default antenna and flux frequency can be set, to simplify the calling of pointing and flux density methods. These are not stored as part of the target object, however.

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>, <longitudinal>, <latitudinal>, <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, and the list may be empty. 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, tle, special, star, xephem).

The longitudinal and latitudinal fields are only relevant to azel, radec and gal targets, in which case they contain the relevant coordinates. 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 <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)

For special and star body types, only the target name is required. The special body name is assumed to be a PyEphem class name, and is typically one of the major solar system objects. Alternatively, it could be “Nothing”, which indicates a dummy target with no position (useful as a placeholder but not much else). The star name is looked up in the PyEphem star database, which contains a modest list of bright stars.

For tle bodies, the final field in the description string should contain the three lines of the TLE. If the name list is empty, the target name is taken from the TLE instead. The xephem body contains a string in XEphem EDB database format as the final field, with commas replaced by tildes. If the name list is empty, the target name is taken from the XEphem string instead.

When specifying a description string, the rest of the target parameters are ignored, except for the default antenna and flux frequency (which do not form part of the description string).

Parameters

body (ephem.Body object or Target object or string) – Pre-constructed PyEphem Body object to embed in target object, or existing target object or description string
tags (list of strings, or whitespace-delimited string, optional) – Descriptive tags associated with target, starting with its body type
aliases (list of strings, optional) – Alternate names of target
flux_model (FluxDensity object, optional) – Object encapsulating spectral flux density model
antenna (Antenna object, optional) – Default antenna to use for position calculations
flux_freq_MHz (float, optional) – Default frequency at which to evaluate flux density, in MHz
name (string) – Name of target

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 (string, list of strings, or None) – Tag or list of tags to add (strings will be split on whitespace)
Returns: target – Updated target object
Return type: Target object

apparent_radec(timestamp=None, antenna=None)¶

Calculate target’s apparent (ra, dec) coordinates 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. Some targets are unable to provide this (due to a limitation of pyephem), notably stationary (azel) targets, and provide the astrometric geocentric position instead.

Parameters

timestamp (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, optional) – Antenna which points at target (defaults to default antenna)

Returns

ra (ephem.Angle object, or array of same shape as timestamp) – Right ascension, in radians
dec (ephem.Angle object, or array of same shape as timestamp) – Declination, in radians

Raises

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

astrometric_radec(timestamp=None, antenna=None)¶

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

This calculates the J2000 astrometric geocentric position of the target, in equatorial coordinates. This is its star atlas position for the epoch of J2000.

Parameters

timestamp (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, optional) – Antenna which points at target (defaults to default antenna)

Returns

ra (ephem.Angle object, or array of same shape as timestamp) – Right ascension, in radians
dec (ephem.Angle object, or array of same shape as timestamp) – Declination, in radians

Raises

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

azel(timestamp=None, antenna=None)¶

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

Parameters

timestamp (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, optional) – Antenna which points at target (defaults to default antenna)

Returns

az (ephem.Angle object, or array of same shape as timestamp) – Azimuth angle(s), in radians
el (ephem.Angle object, or array of same shape as timestamp) – Elevation angle(s), in radians

Raises

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

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

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

flux_density(flux_freq_MHz=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: freq_MHz (float or sequence, optional) – Frequency at which to evaluate flux density, in MHz
Returns: flux_density – Flux density in Jy, or np.nan if frequency is out of range or target does not have flux model
Return type: float, or array of same shape as freq_MHz
Raises: ValueError – If no frequency is specified, and no default frequency was set either

flux_density_stokes(flux_freq_MHz=None)¶

Calculate flux density for given observation frequency (or frequencies), 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: freq_MHz (float or sequence, optional) – Frequency at which to evaluate flux density, in MHz
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: array of float
Raises: ValueError – If no frequency is specified, and no default frequency was set either

format_katcp()¶: String representation if object is passed as parameter to KATCP command.

galactic(timestamp=None, antenna=None)¶

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

This calculates the galactic coordinates of the target, based on the J2000 astrometric equatorial coordinates. This is its position relative to the Galactic reference frame for the epoch of J2000.

Parameters

timestamp (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, optional) – Antenna which points at target (defaults to default antenna)

Returns

l (ephem.Angle object, or array of same shape as timestamp) – Galactic longitude, in radians
b (ephem.Angle object, or array of same shape as timestamp) – Galactic latitude, in radians

Raises

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

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 :math:` au_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 (Antenna object) – Second antenna of baseline pair (baseline vector points toward it)
timestamp (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, optional) – First (reference) antenna of baseline pair, which also serves as pointing reference (defaults to default antenna)

Returns

delay (float, or array of same shape as *timestamp*) – Geometric delay, in seconds
delay_rate (float, or array 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, 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 (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, 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

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 (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, optional) – Antenna which points at target (defaults to default antenna)

Returns

parangle – Parallactic angle, in radians

Return type

float, or array of 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 (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, 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) coordinates as seen from antenna at time(s).

This calculates the J2000 astrometric geocentric position of the target, in equatorial coordinates. This is its star atlas position for the epoch of J2000.

Parameters

timestamp (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, optional) – Antenna which points at target (defaults to default antenna)

Returns

ra (ephem.Angle object, or array of same shape as timestamp) – Right ascension, in radians
dec (ephem.Angle object, or array of same shape as timestamp) – Declination, in radians

Raises

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

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

Angular separation between this target and another one.

Parameters

other_target (Target object) – The other target
timestamp (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) when separation is measured, in UTC seconds since Unix epoch (defaults to now)
antenna (class:Antenna object, 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, in radians

Return type

ephem.Angle object, or array of shape of timestamp

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 (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, 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

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 (Antenna object or sequence) – Second antenna of baseline pair (baseline vector points toward it)
timestamp (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, optional) – First (reference) antenna of baseline pair, which also serves as pointing reference (defaults to default antenna)

Returns

u, v, w – (u, v, w) coordinates of baseline, in metres. If timestamp and/or antenna2 is a sequence, returns an array, with axes in that order.

Return type

float or array

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 the coordinate transformation from local ENU coordinates to (u,v,w) coordinates while pointing at target.

For simple cases, use uvw() directly. This method is useful for computing (u,v,w) coordinates for all antennas in an array more efficiently than calling uvw() for each antenna in turn.

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

Parameters

timestamp (Timestamp object or equivalent, or sequence, optional) – Timestamp(s) in UTC seconds since Unix epoch (defaults to now)
antenna (Antenna object, optional) – Reference antenna of baseline pairs, which also serves as pointing reference (defaults to default antenna)

Returns

uvw – 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 a vector, the first two dimensions correspond to the matrix and the final dimension to the timestamp.

Return type

2D or 3D array

katpoint.target.construct_azel_target(az, el)¶

Convenience function to create unnamed stationary target (azel body type).

The input parameters will also accept ephem.Angle objects, as these are floats in radians internally.

Parameters

az (string or float) – Azimuth / elevation, either as a sexagesimal or decimal string in degrees, or such a string with an explicit unit suffix (‘d’ for degrees / ‘h’ for hours), or as a float in radians
el (string or float) – Azimuth / elevation, either as a sexagesimal or decimal string in degrees, or such a string with an explicit unit suffix (‘d’ for degrees / ‘h’ for hours), or as a float in radians

Returns

target – Constructed target object

Return type

Target object

katpoint.target.construct_radec_target(ra, dec)¶

Convenience function to create unnamed fixed target (radec body type).

The input parameters will also accept ephem.Angle objects, as these are floats in radians internally. The epoch is assumed to be J2000.

Parameters

ra (string or float) – Right ascension, either as a sexagesimal string in hours, a decimal string in degrees, or a sexagesimal or decimal string with an explicit unit suffix (‘d’ for degrees / ‘h’ for hours), or as a float in radians
dec (string or float) – Declination, either as a sexagesimal or decimal string in degrees, or such a string with an explicit unit suffix (‘d’ for degrees / ‘h’ for hours), or as a float in radians

Returns

target – Constructed target object

Return type

Target object

katpoint.target.construct_target_params(description)¶

Construct parameters of Target object from description string.

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

Parameters

description (string) – String containing target name(s), tags, location and flux model

Returns

body (ephem.Body object) – PyEphem Body object that will be used for position calculations
tags (list of strings) – Descriptive tags associated with target, starting with its body type
aliases (list of strings) – Alternate names of target
flux_model (FluxDensity object) – Object encapsulating spectral flux density model

Raises

ValueError – If description has the wrong format

katpoint.timestamp module¶

A Timestamp object.

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

Bases: object

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

This is loosely based on ephem.Date. Its base representation of time is UTC seconds since the Unix epoch, i.e. the standard Posix timestamp (ephem.Date uses UTC days since noon on 1899/12/31, or the Dublin Julian Day). Fractional seconds are allowed, as the basic data type is a Python (double-precision) float.

The following input formats are accepted for a timestamp:

None, which uses the current time (the default).
A floating-point number, directly representing the number of UTC seconds since the Unix epoch. Fractional seconds are allowed.
A string with format ‘YYYY-MM-DD HH:MM:SS.SSS’ or ‘YYYY/MM/DD HH:MM:SS.SSS’, or any prefix thereof. Examples are ‘1999-12-31 12:34:56.789’, ‘1999-12-31’, ‘1999-12-31 12:34:56’ and even ‘1999’. The input string is always in UTC.
A ephem.Date object, which is the standard time representation in PyEphem.

Parameters

timestamp (float, string, ephem.Date object or None) – Timestamp, in various formats (if None, defaults to now)
secs (float) – Timestamp as UTC seconds since Unix epoch

local()¶: Convert timestamp to local time string representation (for display only).

secs¶

to_ephem_date()¶: Convert timestamp to ephem.Date object.

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

to_string()¶: Convert timestamp to UTC string representation.

Module contents¶

Module that abstracts pointing and related coordinate transformations.

This module provides a simplified interface to the underlying coordinate library, and provides functionality lacking in it. It defines a Target and Antenna class, analogous to the Body and Observer classes in PyEphem, and provides spherical coordinate transformations and spherical projections.

Currently it only caters for PyEphem, but it could be extended to include ACSM and CASA.