pint.observatory.topo_obs.TopoObs

class pint.observatory.topo_obs.TopoObs(name, *, fullname=None, tempo_code=None, itoa_code=None, aliases=None, location=None, itrf_xyz=None, lat=None, lon=None, height=None, clock_file='', clock_fmt='tempo', clock_dir=None, include_gps=True, include_bipm=True, bipm_version='BIPM2021', origin=None, overwrite=False, bogus_last_correction=False)[source]

Bases: Observatory

Observatories that are at a fixed location on the surface of the Earth.

This behaves very similarly to “standard” site definitions in tempo/tempo2. Clock correction files are read and computed, observatory coordinates are specified in ITRF XYZ, etc.

PINT can look for clock files in one of several ways, depending on how the clock_dir variable is set:

  • clock_dir="PINT" - clock files are looked for in $PINT_CLOCK_OVERRIDE, or failing that, in a global clock correction repository

  • clock_dir="TEMPO" or clock_dir="TEMPO2" - clock files are looked for under $TEMPO or $TEMPO2

  • clock_dir is a specific directory

If PINT cannot find a clock file, you will (by default) get a warning and no clock corrections. Calling code can request that missing clock corrections raise an exception.

Additional information can be accessed through the location attribute

Parameters:

  • name (str) – The name of the observatory

  • fullname (str) – A fuller name of the observatory

  • location (EarthLocation, optional) –

  • itrf_xyz (Quantity or array-like, optional) – IRTF site coordinates (len-3 array). Can include astropy units. If no units are given, meters are assumed.

  • lat (Quantity or float, optional) – Earth East longitude. Can be anything that initialises an Angle object (if float, in degrees).

  • lon (Quantity or float, optional) – Earth latitude. Can be anything that initialises an Angle object (if float, in degrees).

  • height (Quantity ['length'] or float, optional) – Height above reference ellipsoid (if float, in meters; default: 0).

  • tempo_code (str, optional) – 1-character tempo code for the site. Will be automatically added to aliases. Note, this is REQUIRED only if using TEMPO time.dat clock file.

  • itoa_code (str, optional) – 2-character ITOA code. Will be added to aliases.

  • aliases (list of str, optional) – List of other aliases for the observatory name.

  • clock_file (str or list of str or list of dict or None) – Name of the clock correction file. Can be a list of strings, for multiple clock files, or a list of dictionaries if it is desired to specify additional keyword arguments to the ClockFile objects.

  • clock_fmt (str, optional) – Format of clock file (see ClockFile class for allowed values).

  • clock_dir (str or pathlib.Path, optional) – Where to look for the clock files. “PINT”, the default, means to use PINT’s usual seach approach; “TEMPO” or “TEMPO2” mean to look in those programs’ usual location (pointed to by their environment variables), while a path means to look in that specific directory.

  • include_gps (bool, optional) – Set False to disable UTC(GPS)->UTC clock correction.

  • include_bipm (bool, optional) – Set False to disable TAI-> TT BIPM clock correction. If False, it only apply TAI->TT correction TT = TAI+32.184s, the same as TEMPO2 TT(TAI) in the parfile. If True, it will apply the correction from BIPM TT=TT(BIPMYYYY). See the link: http://www.bipm.org/en/bipm-services/timescales/time-ftp/ttbipm.html

  • bipm_version (str, optional) – Set the version of TT BIPM clock correction file to use, the default is the most recent available. It should be a string like ‘BIPM2015’ to select the file ‘tai2tt_bipm2015.clk’.

  • origin (str, optional) – Documentation of the origin/author/date for the information

  • overwrite (bool, optional) – set True to force overwriting of previous observatory definition

  • bogus_last_correction (bool, optional) – Clock correction files include a bogus last correction

Note

One of location, itrf_xyz, or (lat, lon, height) must be specified

Methods

bipm_correction(t[, bipm_version, limits])

Compute the GPS clock corrections for times t.

clear_registry()

Clear registry for ground-based observatories.

clock_corrections(t[, limits])

Compute the total clock corrections,

earth_location_itrf([time])

Returns observatory geocentric position as an astropy EarthLocation object.

get(name)

Returns the Observatory instance for the specified name/alias.

get_TDBs(t[, method, ephem, options])

This is a high level function for converting TOAs to TDB time scale.

get_dict()

Return as a dict with limited/changed info

get_gcrs(t[, ephem])

Return position vector of TopoObs in GCRS

get_json()

Return as a JSON string

gps_correction(t[, limits])

Compute the GPS clock corrections for times t.

last_clock_correction_mjd()

Return the MJD of the last clock correction.

names()

List all observatories known to PINT.

names_and_aliases()

List all observatories and their aliases

posvel(t, ephem[, group])

Return observatory position and velocity for the given times.

separation(other[, method])

Return separation between two TopoObs objects

Attributes

aliases

name

timescale

Returns the timescale that TOAs from this observatory will be in, once any clock corrections have been applied.
property timescale

Returns the timescale that TOAs from this observatory will be in, once any clock corrections have been applied. This should be a string suitable to be passed directly to the scale argument of astropy.time.Time().

get_dict()[source]

Return as a dict with limited/changed info

get_json()[source]

Return as a JSON string

separation(other, method='cartesian')[source]

Return separation between two TopoObs objects

Parameters:

  • other (TopoObs) –

  • method (str, optional) – Method to compute separation. Either “cartesian” or “geodesic”

Return type:

astropy.quantity.Quantity

Note

“geodesic” method assumes a spherical Earth and ignores altitudes

earth_location_itrf(time=None)[source]

Returns observatory geocentric position as an astropy EarthLocation object. For observatories where this is not relevant, None can be returned.

The location is in the International Terrestrial Reference Frame (ITRF). The realization of the ITRF is determined by astropy, which uses ERFA (IAU SOFA).

The time argument is ignored for observatories with static positions. For moving observatories (e.g. spacecraft), it should be specified (as an astropy Time) and the position at that time will be returned.

clock_corrections(t, limits='warn')[source]

Compute the total clock corrections,

Parameters:

t (astropy.time.Time) – The time when the clock correcions are applied.

last_clock_correction_mjd()[source]

Return the MJD of the last clock correction.

Combines constraints based on Earth orientation parameters and on the available clock corrections specific to the telescope.

get_gcrs(t, ephem=None)[source]

Return position vector of TopoObs in GCRS

Parameters:

t (astropy.time.Time or array of astropy.time.Time) –

Returns:

a 3-vector of Quantities representing the position in GCRS coordinates.

Return type:

np.array

posvel(t, ephem, group=None)[source]

Return observatory position and velocity for the given times.

Position is relative to solar system barycenter; times are (astropy array-valued Time objects).

static bipm_correction(t, bipm_version='BIPM2021', limits='warn')

Compute the GPS clock corrections for times t.

classmethod clear_registry()

Clear registry for ground-based observatories.

classmethod get(name)

Returns the Observatory instance for the specified name/alias.

If the name has not been defined, an error will be raised. Aside from the initial observatory definitions, this is in general the only way Observatory objects should be accessed. Name-matching is case-insensitive.

get_TDBs(t, method='default', ephem=None, options=None)

This is a high level function for converting TOAs to TDB time scale.

Different method can be applied to obtain the result. Current supported methods are [‘default’, ‘ephemeris’]

Parameters:

  • t (astropy.time.Time object) – The time need for converting toas

  • method (str or callable, optional) –

    Method of computing TDB

    ”default”

    Astropy time.Time object built-in converter, uses FB90. SpacecraftObs will include a topocentric correction term.

    ”ephemeris”

    JPL ephemeris included TDB-TT correction. Not currently implemented.

    callable

    This callable is called with the parameter t as its first parameter; additional keyword arguments can be supplied in the options argument

  • ephem (str, optional) – The ephemeris to get he TDB-TT correction. Required for the ‘ephemeris’ method.

  • options (dict or None) – Options to pass to a custom callable.

static gps_correction(t, limits='warn')

Compute the GPS clock corrections for times t.

classmethod names()

List all observatories known to PINT.

classmethod names_and_aliases()

List all observatories and their aliases