chandra_aca.planets

Functions for planet position relative to Chandra, Earth, or Solar System Barycenter.

Estimated accuracy of planet coordinates (RA, Dec) is as follows, where the JPL Horizons positions are used as the “truth”.

  • get_planet_chandra errors:

    • Venus: < 0.25 arcsec with a peak around 0.02

    • Mars: < 0.45 arcsec with a peak around 0.1

    • Jupiter: < 0.2 arcsec with a peak around 0.1

    • Saturn: < 0.2 arcsec with a peak around 0.1

  • get_planet_eci errors:

    • Venus: < 12 arcmin with peak around 2 arcmin

    • Mars: < 8 arcmin with peak around 1.5 arcmin

    • Jupiter: < 1 arcmin with peak around 0.5 arcmin

    • Saturn: < 0.5 arcmin with peak around 0.3 arcmin

See the validation/planet-accuracy.ipynb notebook for details.

class chandra_aca.planets.EarthBoresightAngles(times, earth_limb_angle, earth_open_angle, earth_center_angle)[source]

Earth boresight angles from Chandra

Attributes:
timesCxoTime

Times

earth_limb_anglendarray

Earth limb angle (deg)

earth_open_anglendarray

Earth opening angle (deg)

earth_center_anglendarray

Earth center angle (deg)

exception chandra_aca.planets.NoEphemerisError[source]

If there is no Chandra orbital ephemeris available

chandra_aca.planets.get_earth_blocks(start, stop=None, *, min_limb_angle=10.0)[source]

Get intervals of Earth blocks in start to stop time interval.

An “Earth block” is when the Earth limb is within min_limb_angle of the Chandra ACA boresight.

Parameters:
startCxoTime-compatible

Start time

stopCxoTime-compatible, optional

Stop time (default=NOW)

min_limb_anglefloat, optional

Minimum limb angle (deg) for block (default=10)

Returns:
Table

Table of Earth blocks with columns:

  • datestart

  • datestop

  • duration

  • tstart

  • tstop

chandra_aca.planets.get_earth_boresight_angle(start, stop)[source]

Calculate Earth boresight angle from Chandra.

The boresight angle is the angle from the ACA boresight to the Earth limb or center. This assumes that the Earth is spherical with radius 6371 km. The Earth position relative to Chandra is interpolated from cheta’s orbitephem0.

The opening angle is the angle from the Earth center to limb as viewed from Chandra.

Parameters:
startCxoTime-compatible

Start time

stopCxoTime-compatible

Stop time

Returns:
EarthBoresightAngles

Dataclass with attributes:

  • times (CxoTime)

  • earth_limb_angle (deg)

  • earth_open_angle (deg)

  • earth_center_angle (deg)

chandra_aca.planets.get_planet_angular_sep(body, ra, dec, time=None, observer_position='earth')[source]

Get angular separation between planet body and target ra, dec.

Valid values for the observer_position argument are:

  • ‘earth’ (default, approximate, fastest)

  • ‘chandra’ (reasonably accurate fast, requires fetching ephemeris)

  • ‘chandra-horizons’ (most accurate, slow, requires internet access)

Parameters:
bodystr

Body name (lower case planet name)

rafloat

RA in degrees

decfloat

Dec in degrees

timeCxoTime-compatible object

Time or times of observation

observer_positionstr

Observer position (‘earth’, ‘chandra’, or ‘chandra-horizons’)

Returns:
angular separation (deg)
chandra_aca.planets.get_planet_barycentric(body, time=None)[source]

Get barycentric position for solar system body at time.

This uses the built-in JPL ephemeris file DE432s and jplephem.

body must be one of “sun”, “mercury”, “venus”, “earth-moon-barycenter”, “earth”, “moon”, “mars”, “jupiter”, “saturn”, “uranus”, “neptune”, or “pluto”.

Parameters:
body

Body name (lower case planet name)

time

Time or times for returned position (default=NOW)

Returns:
barycentric position (km) as (x, y, z) or N x (x, y, z)
chandra_aca.planets.get_planet_chandra(body, time=None)[source]

Get position for solar system body at time relative to Chandra.

This uses the built-in JPL ephemeris file DE432s and jplephem, along with the CXC predictive Chandra orbital ephemeris (from the OFLS). The position is computed at the supplied time minus the light-travel time from Chandra to body to generate the apparent position from Chandra at time.

Estimated accuracy of planet coordinates (RA, Dec) from Chandra is as follows, where the JPL Horizons positions are used as the “truth”.

  • Venus: < 0.25 arcsec with a peak around 0.02

  • Mars: < 0.45 arcsec with a peak around 0.1

  • Jupiter: < 0.2 arcsec with a peak around 0.1

  • Saturn: < 0.2 arcsec with a peak around 0.1

Parameters:
bodystr

Body name

timeCxoTimeLike

Time or times for returned position (default=NOW)

Returns:
ndarray (float)

Position relative to Chandra (km) as (x, y, z) or N x (x, y, z)

chandra_aca.planets.get_planet_chandra_horizons(body, timestart, timestop, n_times=10, timeout=10)[source]

Get body position and other info as seen from Chandra using JPL Horizons.

In addition to the planet names, the body argument can be any identifier that Horizon supports, e.g. sun or geo (Earth geocenter).

This function queries the JPL Horizons site using the web API interface (See https://ssd-api.jpl.nasa.gov/doc/horizons.html for docs).

The return value is an astropy Table with columns: time, ra, dec, rate_ra, rate_dec, mag, surf_brt, ang_diam. The units are included in the table columns. The time column is a CxoTime object.

The returned Table has a meta key value response_text with the full text of the Horizons response and a response_json key with the parsed JSON.

Example:

>>> from chandra_aca.planets import get_planet_chandra_horizons
>>> dat = get_planet_chandra_horizons('jupiter', '2020:001', '2020:002', n_times=4)
>>> dat
<Table length=5>
         time             ra       dec     rate_ra    rate_dec    mag      surf_brt   ang_diam
                         deg       deg    arcsec / h arcsec / h   mag   mag / arcsec2  arcsec
        object         float64   float64   float64    float64   float64    float64    float64
--------------------- --------- --------- ---------- ---------- ------- ------------- --------
2020:001:00:00:00.000 276.96494 -23.20087      34.22       0.98  -1.839         5.408    31.75
2020:001:06:00:00.000 277.02707 -23.19897      34.30       1.30  -1.839         5.408    31.76
2020:001:12:00:00.000 277.08934 -23.19652      34.39       1.64  -1.839         5.408    31.76
2020:001:18:00:00.000 277.15181 -23.19347      34.51       2.03  -1.839         5.408    31.76
2020:002:00:00:00.000 277.21454 -23.18970      34.69       2.51  -1.839         5.408    31.76
Parameters:
bodystr

One of ‘mercury’, ‘venus’, ‘mars’, ‘jupiter’, ‘saturn’, ‘uranus’, ‘neptune’, or any other body that Horizons supports.

timestart

start time (any CxoTime-compatible time)

timestop

stop time (any CxoTime-compatible time)

n_times

number of time samples (inclusive, default=10)

timeout

timeout for query to Horizons (secs)

Returns:
Table of information
chandra_aca.planets.get_planet_eci(body, time=None, pos_observer=None)[source]

Get ECI apparent position for solar system body at time.

This uses the built-in JPL ephemeris file DE432s and jplephem. The position is computed at the supplied time minus the light-travel time from the observer to body to generate the apparent position on Earth at time.

body and pos_observer must be one of “sun”, “mercury”, “venus”, “earth-moon-barycenter”, “earth”, “moon”, “mars”, “jupiter”, “saturn”, “uranus”, “neptune”, or “pluto”.

Estimated accuracy of planet coordinates (RA, Dec) is as follows, where the JPL Horizons positions are used as the “truth”. This assumes the observer position is Earth (default).

  • Venus: < 12 arcmin with peak around 2 arcmin

  • Mars: < 8 arcmin with peak around 1.5 arcmin

  • Jupiter: < 1 arcmin with peak around 0.5 arcmin

  • Saturn: < 0.5 arcmin with peak around 0.3 arcmin

Parameters:
bodystr

Body name (lower case planet name)

timeCxoTimeLike, optional

Time or times for returned position (default=NOW)

pos_observerstr, optional

Observer position (default=Earth)

Returns:
ndarray (float)

Earth-Centered Inertial (ECI) position (km) as (x, y, z) or N x (x, y, z)