ch_util.ephemeris

Ephemeris routines

The precession of the Earth’s axis gives noticeable shifts in object positions over the life time of CHIME. To minimise the effects of this we need to be careful and consistent with our ephemeris calculations. Historically Right Ascension has been given with respect to the Vernal Equinox which has a significant (and unnecessary) precession in the origin of the RA axis. To avoid this we use the new Celestial Intermediate Reference System which does not suffer from this issue.

Practically this means that when calculating RA, DEC coordinates for a source position at a given time you must be careful to obtain CIRS coordinates (and not equinox based ones). Internally using ephemeris.object_coords does exactly that for you, so for any lookup of coordinates you should use that on your requested body.

Note that the actual coordinate positions of sources must be specified using RA, DEC coordinates in ICRS (which is roughly equivalent to J2000). The purpose of object_coords is to transform into new RA, DEC coordinates taking into account the precession and nutation of the Earth’s polar axis since then.

These kind of coordinate issues are tricky, confusing and hard to debug years later, so if you’re unsure you are recommended to seek some advice.

Constants

CHIMELATITUDE: CHIME’s latitude [degrees].
CHIMELONGITUDE: CHIME’s longitude [degrees].
CHIMEALTITUDE: CHIME’s altitude [metres].
SIDEREAL_S: Number of SI seconds in a sidereal second [s/sidereal s]. You probably want STELLAR_S instead.
STELLAR_S: Number of SI seconds in a stellar second [s/stellar s].
CasA: skyfield.starlib.Star representing Cassiopeia A.
CygA: skyfield.starlib.Star representing Cygnus A.
TauA: skyfield.starlib.Star representing Taurus A.
VirA: skyfield.starlib.Star representing Virgo A.

Telescope Instances

chime

Ephemeris Functions

skyfield_star_from_ra_dec()
transit_times()
solar_transit()
lunar_transit()
setting_times()
solar_setting()
lunar_setting()
rising_times()
solar_rising()
lunar_rising()
_is_skyfield_obj()
peak_RA()
get_source_dictionary()
lsa()

Time Utilities

ensure_unix()
chime_local_datetime()
unix_to_datetime()
datetime_to_unix()
datetime_to_timestr()
timestr_to_datetime()
unix_to_skyfield_time()
skyfield_time_to_unix()
time_of_day()
csd()
csd_to_unix()
unix_to_csd()
parse_date()

Module Attributes

`CasA`	`skyfield.starlib.Star` representing Cassiopeia A.
`CygA`	`skyfield.starlib.Star` representing Cygnus A.
`TauA`	`skyfield.starlib.Star` representing Taurus A.
`VirA`	`skyfield.starlib.Star` representing Virgo A.

Functions

`Star_cirs`(ra, dec, epoch)	Wrapper for skyfield.api.star that creates a position given CIRS coordinates observed from CHIME
`bmxy_to_hadec`(bmx, bmy)	Convert CHIME/FRB beam-model XY coordinates to CIRS hour angle and declination.
`chime_local_datetime`(*args)	Create a `datetime.datetime` object in Canada/Pacific timezone.
`cirs_radec`(body[, date, deg, obs])	Converts a Skyfield body in CIRS coordinates at a given epoch to ICRS coordinates observed from CHIME
`galt_pointing_model_dec`(ha_in, dec_in[, b])	Calculate pointing correction in declination for the Galt Telescope See description of the pointing model by Lewis Knee CHIME document library 754 https://bao.chimenet.ca/doc/documents/754
`galt_pointing_model_ha`(ha_in, dec_in[, a])	Calculate pointing correction in hour angle for the Galt Telescope See description of the pointing model by Lewis Knee CHIME document library 754 https://bao.chimenet.ca/doc/documents/754
`get_doppler_shifted_freq`(source, date[, ...])	Calculate Doppler shifted frequency of spectral feature with rest frequency freq_rest, seen towards source source at time date, due to Earth's motion and rotation, following the relativistic Doppler effect.
`get_range_rate`(source, date[, obs])	Calculate rate at which distance between observer and source changes.
`get_source_dictionary`(*args)	Returns a dictionary containing `skyfield.starlib.Star` objects for common radio point sources.
`hadec_to_bmxy`(ha_cirs, dec_cirs)	Convert CIRS hour angle and declination to CHIME/FRB beam-model XY coordinates.
`lunar_rising`(start_time[, end_time, obs])	Find the Lunar risings between two times for CHIME.
`lunar_setting`(start_time[, end_time, obs])	Find the Lunar settings between two times for CHIME.
`lunar_transit`(start_time[, end_time, obs])	Find the Lunar transits between two times for CHIME.
`object_coords`(body[, date, deg, obs])	Calculates the RA and DEC of the source.
`parse_date`(datestring)	Convert date string to a datetime object.
`peak_RA`(body[, date, deg])	Calculates the RA where a source is expected to peak in the beam.
`solar_rising`(start_time[, end_time, obs])	Find the Solar risings between two times for CHIME.
`solar_setting`(start_time[, end_time, obs])	Find the Solar settings between two times for CHIME.
`solar_transit`(start_time[, end_time, obs])	Find the Solar transits between two times for CHIME.
`sphdist`(long1, lat1, long2, lat2)	Return the angular distance between two coordinates.
`transit_RA`(time)	No longer supported.
`utc_lst_to_mjd`(datestring, lst[, obs])	Convert datetime string and LST to corresponding modified Julian Day

ch_util.ephemeris.CasA = Star(ra=350.86642, dec=58.81178, names='CAS_A', epoch=2451545.0): skyfield.starlib.Star representing Cassiopeia A.

ch_util.ephemeris.CygA = Star(ra=299.86815, dec=40.73392, names='CYG_A', epoch=2451545.0): skyfield.starlib.Star representing Cygnus A.

ch_util.ephemeris.Star_cirs(ra, dec, epoch)[source]

Wrapper for skyfield.api.star that creates a position given CIRS coordinates observed from CHIME

Parameters:

ra (skyfield.api.Angle) – RA and dec of the source in CIRS coordinates
dec (skyfield.api.Angle) – RA and dec of the source in CIRS coordinates
epoch (skyfield.api.Time) – Time of the observation

Returns:

body – Star object in ICRS coordinates

Return type:

skyfield.api.Star

ch_util.ephemeris.TauA = Star(ra=83.63321, dec=22.01446, names='TAU_A', epoch=2451545.0): skyfield.starlib.Star representing Taurus A.

ch_util.ephemeris.VirA = Star(ra=187.70593, dec=12.39112, names='VIR_A', epoch=2451545.0): skyfield.starlib.Star representing Virgo A.

ch_util.ephemeris.bmxy_to_hadec(bmx, bmy)[source]

Convert CHIME/FRB beam-model XY coordinates to CIRS hour angle and declination.

Parameters:

bmx (array_like) – The CHIME/FRB beam model X and Y coordinates in degrees as defined in the beam-model coordinate conventions: https://chime-frb-open-data.github.io/beam-model/#coordinate-conventions X is degrees west from the meridian Y is degrees north from zenith
bmy (array_like) – The CHIME/FRB beam model X and Y coordinates in degrees as defined in the beam-model coordinate conventions: https://chime-frb-open-data.github.io/beam-model/#coordinate-conventions X is degrees west from the meridian Y is degrees north from zenith

Returns:

ha_cirs (array_like) – The CIRS Hour Angle in degrees.
dec_cirs (array_like) – The CIRS Declination in degrees.

ch_util.ephemeris.chime_local_datetime(*args)[source]

Create a datetime.datetime object in Canada/Pacific timezone.

Parameters:: *args – Any valid arguments to the constructor of datetime.datetime except tzinfo. Local date and time at CHIME.
Returns:: dt – Timezone naive date and time but converted to UTC.
Return type:: datetime.datetime

ch_util.ephemeris.cirs_radec(body, date=None, deg=False, obs=<caput.time.Observer object>)[source]

Converts a Skyfield body in CIRS coordinates at a given epoch to ICRS coordinates observed from CHIME

Parameters:: body (skyfield.api.Star) – Skyfield Star object with positions in CIRS coordinates.
Returns:: new_body – Skyfield Star object with positions in ICRS coordinates
Return type:: skyfield.api.Star

ch_util.ephemeris.galt_pointing_model_dec(ha_in, dec_in, b=[1.081, 0.707, -0.076, 0.0, 0.0, 0.0, 0.0])[source]

Calculate pointing correction in declination for the Galt Telescope See description of the pointing model by Lewis Knee CHIME document library 754 https://bao.chimenet.ca/doc/documents/754

Parameters:

ha (Skyfield Angle objects) – Target hour angle and declination
dec (Skyfield Angle objects) – Target hour angle and declination
b (list of floats) – List of coefficients (in arcmin) for the pointing model (NOTE: it is very unlikely that a user will want to change these from the defaults, which are taken from the pointing model as of 2019-2-15)

Returns:

Angular offset in hour angle

Return type:

Skyfield Angle object

ch_util.ephemeris.galt_pointing_model_ha(ha_in, dec_in, a=[-5.872, -0.5292, 5.458, -0.076, -0.707, 0.0, 0.0])[source]

Calculate pointing correction in hour angle for the Galt Telescope See description of the pointing model by Lewis Knee CHIME document library 754 https://bao.chimenet.ca/doc/documents/754

Parameters:

ha (Skyfield Angle objects) – Target hour angle and declination
dec (Skyfield Angle objects) – Target hour angle and declination
a (list of floats) – List of coefficients (in arcmin) for the pointing model (NOTE: it is very unlikely that a user will want to change these from the defaults, which are taken from the pointing model as of 2019-2-15)

Returns:

Angular offset in hour angle

Return type:

Skyfield Angle object

ch_util.ephemeris.get_doppler_shifted_freq(source: ~skyfield.starlib.Star | str, date: float | list, freq_rest: float | list = None, obs: ~caput.time.Observer = <caput.time.Observer object>) → array[source]

Calculate Doppler shifted frequency of spectral feature with rest frequency freq_rest, seen towards source source at time date, due to Earth’s motion and rotation, following the relativistic Doppler effect.

Parameters:

source – Position(s) on the sky. If the input is a str, attempt to resolve this from ch_util.hfbcat.HFBCatalog.
date – Unix time(s) for which to calculate Doppler shift.
freq_rest – Rest frequency(ies) in MHz. If None, attempt to obtain rest frequency of absorption feature from ch_util.hfbcat.HFBCatalog.freq_abs.
obs – An Observer instance to use. If not supplied use chime. For many calculations changing from this default will make little difference.

Returns:

Doppler shifted frequencies in MHz. Array where rows correspond to the different input rest frequencies and columns correspond either to input times or to input sky positions (whichever contains multiple entries).

Return type:

freq_obs

Notes

Only one of source and date can contain multiple entries.

Example

To get the Doppler shifted frequencies of a feature with a rest frequency of 600 MHz for two positions on the sky at a single point in time (Unix time 1717809534 = 2024-06-07T21:18:54+00:00), run:

>>> from skyfield.starlib import Star
>>> from skyfield.positionlib import Angle
>>> from ch_util.tools import get_doppler_shifted_freq
>>> coord = Star(ra=Angle(degrees=[100, 110]), dec=Angle(degrees=[45, 50]))
>>> get_doppler_shifted_freq(coord, 1717809534, 600)

ch_util.ephemeris.get_range_rate(source: ~skyfield.starlib.Star, date: float | list, obs: ~caput.time.Observer = <caput.time.Observer object>) → float | array[source]

Calculate rate at which distance between observer and source changes.

Parameters:

source – Position(s) on the sky.
date – Unix time(s) for which to calculate range rate.
obs – An Observer instance to use. If not supplied use chime. For many calculations changing from this default will make little difference.

Returns:

Rate (in m/s) at which the distance between the observer and source changes (i.e., the velocity of observer in direction of source, but positive for observer and source moving appart). If either source or date contains multiple entries, range_rate will be an array. Otherwise, range_rate will be a float.

Return type:

range_rate

Notes

Only one of source and date can contain multiple entries.

This routine uses an skyfield.positionlib.Apparent object (rather than an skyfield.positionlib.Astrometric object) to find the velocity of the observatory and the position of the source. This accounts for the gravitational deflection and the aberration of light. It is unclear if the latter should be taken into account for this Doppler shift calculation, but its effects are negligible.

ch_util.ephemeris.get_source_dictionary(*args)[source]

Returns a dictionary containing skyfield.starlib.Star objects for common radio point sources. This is useful for obtaining the skyfield representation of a source from a string containing its name.

Parameters:: catalog_name (str) – Name of the catalog. This must be the basename of the json file in the ch_util/catalogs directory. Can take multiple catalogs, with the first catalog favoured for any overlapping sources.
Returns:: src_dict – Format is {‘SOURCE_NAME’: skyfield.starlib.Star, …}
Return type:: dictionary

ch_util.ephemeris.hadec_to_bmxy(ha_cirs, dec_cirs)[source]

Convert CIRS hour angle and declination to CHIME/FRB beam-model XY coordinates.

Parameters:

ha_cirs (array_like) – The CIRS Hour Angle in degrees.
dec_cirs (array_like) – The CIRS Declination in degrees.

Returns:

bmx, bmy – The CHIME/FRB beam model X and Y coordinates in degrees as defined in the beam-model coordinate conventions: https://chime-frb-open-data.github.io/beam-model/#coordinate-conventions

Return type:

array_like

ch_util.ephemeris.lunar_rising(start_time, end_time=None, obs=<caput.time.Observer object>)[source]

Find the Lunar risings between two times for CHIME.

Parameters:

start_time (float (UNIX time) or datetime) – Start time to find risings.
end_time (float (UNIX time) or datetime, optional) – End time for finding risings. If None default, search for 24 hours after start time.

Returns:

rising_times – Array of rising times (in UNIX time).

Return type:

array_like

ch_util.ephemeris.lunar_setting(start_time, end_time=None, obs=<caput.time.Observer object>)[source]

Find the Lunar settings between two times for CHIME.

Parameters:

start_time (float (UNIX time) or datetime) – Start time to find settings.
end_time (float (UNIX time) or datetime, optional) – End time for finding settings. If None default, search for 24 hours after start time.

Returns:

setting_times – Array of setting times (in UNIX time).

Return type:

array_like

ch_util.ephemeris.lunar_transit(start_time, end_time=None, obs=<caput.time.Observer object>)[source]

Find the Lunar transits between two times for CHIME.

Parameters:

start_time (float (UNIX time) or datetime) – Start time to find transits.
end_time (float (UNIX time) or datetime, optional) – End time for finding transits. If None default, search for 24 hours after start time.

Returns:

transit_times – Array of transit times (in UNIX time).

Return type:

array_like

ch_util.ephemeris.object_coords(body, date=None, deg=False, obs=<caput.time.Observer object>)[source]

Calculates the RA and DEC of the source.

Gives the ICRS coordinates if no date is given (=J2000), or if a date is specified gives the CIRS coordinates at that epoch.

This also returns the apparent position, including abberation and deflection by gravitational lensing. This shifts the positions by up to 20 arcseconds.

Parameters:

body (skyfield source) – skyfield.starlib.Star or skyfield.vectorlib.VectorSum or skyfield.jpllib.ChebyshevPosition body representing the source.
date (float) – Unix time at which to determine ra of source If None, use Jan 01 2000.
deg (bool) – Return RA ascension in degrees if True, radians if false (default).
obs (caput.time.Observer) – An observer instance to use. If not supplied use chime. For many calculations changing from this default will make little difference.

Returns:

ra, dec – Position of the source.

Return type:

float

ch_util.ephemeris.parse_date(datestring)[source]

Convert date string to a datetime object.

Parameters:: datestring (string) – Date as YYYYMMDD-AAA, where AAA is one of [UTC, PST, PDT]
Returns:: date – A python datetime object in UTC.
Return type:: datetime

ch_util.ephemeris.peak_RA(body, date=None, deg=False)[source]

Calculates the RA where a source is expected to peak in the beam. Note that this is not the same as the RA where the source is at transit, since the pathfinder is rotated with respect to north.

Parameters:

body (ephem.FixedBody) – skyfield.starlib.Star or skyfield.vectorlib.VectorSum or skyfield.jpllib.ChebyshevPosition or Ephemeris body representing the source.
date (float) – Unix time at which to determine ra of source If None, use Jan 01 2000. Ignored if body is not a skyfield object
deg (bool) – Return RA ascension in degrees if True, radians if false (default).

Returns:

peak_ra – RA when the transiting source peaks.

Return type:

float

ch_util.ephemeris.solar_rising(start_time, end_time=None, obs=<caput.time.Observer object>)[source]

Find the Solar risings between two times for CHIME.

Parameters:

start_time (float (UNIX time) or datetime) – Start time to find risings.
end_time (float (UNIX time) or datetime, optional) – End time for finding risings. If None default, search for 24 hours after start time.

Returns:

rising_times – Array of rising times (in UNIX time).

Return type:

array_like

ch_util.ephemeris.solar_setting(start_time, end_time=None, obs=<caput.time.Observer object>)[source]

Find the Solar settings between two times for CHIME.

Parameters:

start_time (float (UNIX time) or datetime) – Start time to find settings.
end_time (float (UNIX time) or datetime, optional) – End time for finding settings. If None default, search for 24 hours after start time.

Returns:

setting_times – Array of setting times (in UNIX time).

Return type:

array_like

ch_util.ephemeris.solar_transit(start_time, end_time=None, obs=<caput.time.Observer object>)[source]

Find the Solar transits between two times for CHIME.

Parameters:

start_time (float (UNIX time) or datetime) – Start time to find transits.
end_time (float (UNIX time) or datetime, optional) – End time for finding transits. If None default, search for 24 hours after start time.

Returns:

transit_times – Array of transit times (in UNIX time).

Return type:

array_like

ch_util.ephemeris.sphdist(long1, lat1, long2, lat2)[source]

Return the angular distance between two coordinates.

Parameters:

long1 (Skyfield Angle objects) – longitude and latitude of the first coordinate. Each should be the same length; can be one or longer.
lat1 (Skyfield Angle objects) – longitude and latitude of the first coordinate. Each should be the same length; can be one or longer.
long2 (Skyfield Angle objects) – longitude and latitude of the second coordinate. Each should be the same length. If long1, lat1 have length longer than 1, long2 and lat2 should either have the same length as coordinate 1 or length 1.
lat2 (Skyfield Angle objects) – longitude and latitude of the second coordinate. Each should be the same length. If long1, lat1 have length longer than 1, long2 and lat2 should either have the same length as coordinate 1 or length 1.

Returns:

dist – angle between the two coordinates

Return type:

Skyfield Angle object

ch_util.ephemeris.transit_RA(time)[source]: No longer supported. Use lsa instead.

ch_util.ephemeris.utc_lst_to_mjd(datestring, lst, obs=<caput.time.Observer object>)[source]

Convert datetime string and LST to corresponding modified Julian Day

Parameters:

datestring (string) – Date as YYYYMMDD-AAA, where AAA is one of [UTC, PST, PDT]
lst (float) – Local sidereal time at DRAO (CHIME) in decimal hours
obs (caput.Observer object)

Returns:

mjd – Modified Julian Date corresponding to the given time.

Return type:

float