pint.observatory.topo_obs.TopoObs

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

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	List of aliases for the observatory.
name	Short name of the observatory.
timescale	Returns the timescale that TOAs from this observatory will be in, once any clock corrections have been applied.
tempo_code	One-character TEMPO code.
itoa_code	Two-character ITOA code.
location	Location of the observatory.
clock_files	List of files to read for clock corrections.
clock_fmt	Format of the clock files.
bogus_last_correction	Clock correction files include a bogus last correction.
clock_dir	Where to look for the clock files.
origin	Documentation of the origin/author/date for the information.
fullname	Full human-readable name of the observatory.
include_gps	Whether to include GPS clock corrections.
include_bipm	Whether to include BIPM clock corrections.
bipm_version	Version of the BIPM clock file to use.

location: EarthLocation

Location of the observatory.

clock_files: List[str]

List of files to read for clock corrections. If empty, no clock corrections are applied.

clock_fmt: str

Format of the clock files.

See pint.observatory.clock_file.ClockFile for allowed values.

clock_dir: str | Path | None

Where to look for the clock files.

include_gps: bool

Whether to include GPS clock corrections.

include_bipm: bool

Whether to include BIPM clock corrections.

bipm_version: str

Version of the BIPM clock file to use.

bogus_last_correction: bool

Clock correction files include a bogus last correction.

This is common with TEMPO/TEMPO2 clock files since neither program does a good job with times past the end ot the table. It makes detecting values past the end of real calibration difficult if it’s not marked as bogus.

property aliases: List[str]

List of aliases for the observatory.

These are short names also used to specify this observatory. Includes ITOA and TEMPO codes, and any other common names.

static bipm_correction(t: Time, bipm_version: str = 'BIPM2021', limits: str = 'warn') → Quantity

Compute the GPS clock corrections for times t.

classmethod clear_registry() → None

Clear registry for ground-based observatories.

classmethod get(name: str) → Observatory

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: Time, method: str | Callable = 'default', ephem: str | None = None, options: dict | None = 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: Time, limits: str = 'warn') → Quantity

Compute the GPS clock corrections for times t.

property name: str

Short name of the observatory.

This is the name used in TOA files and in the observatory registry.

classmethod names()

List all observatories known to PINT.

classmethod names_and_aliases() → Dict[str, List[str]]

List all observatories and their aliases

tempo_code: str | None

One-character TEMPO code.

fullname: str

Full human-readable name of the observatory.

itoa_code: str | None

Two-character ITOA code.

origin: str | None

Documentation of the origin/author/date for the information.

property timescale: str

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() → Dict[str, Dict[str, Any]]

Return as a dict with limited/changed info

get_json() → str

Return as a JSON string.

separation(other: TopoObs, method: str = 'cartesian') → Quantity

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) → EarthLocation

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: Time, limits: str = 'warn') → Quantity

Compute the total clock corrections,

Parameters:

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

last_clock_correction_mjd() → float

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: Time, ephem: str | None = None)

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: Time, ephem: str | None, group=None) → PosVel

Return observatory position and velocity for the given times.

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