Observer and Spacecraft Classes

The Observer and Spacecraft Classes within SORA were created to deal with the observer location. The online documentation here contains the details about every step.

This Jupyter-Notebook was designed as a tutorial for how to work with the Observer and Spacecraft Classes. Any further question, please contact the core team: Altair Ramos Gomes Júnior, Bruno Eduardo Morgado, Gustavo Benedetti Rossi, and Rodrigo Carlos Boufleur.

The Observer and Spacecraft Docstring were designed to help the users. Also, each function has its Docstring containing its main purpose and the needed parameters (physical description and formats). Please, do not hesitate to use it.

0. Index

1. Instantiating an Observer or Spacecraft Object

2. Setting and/or modifing parameters

3. Apparent Sidereal Time

4. Ksi and Eta projection

5. MPC observatories

## import the Class
from sora.observer import Observer, Spacecraft
## This means the Observer Class is imported from the "observer" module of the sora package

## To facilitate, sora allows to import Observer directly from the sora package.
from sora import Observer, Spacecraft

/home/chrycho/SORA-lightcurve/sora/body/shape/core.py:2: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
  import pkg_resources

SORA version: 0.3.2

1. Instantiating an Observer or Spacecraft Object

1.1 Observer

The Observer Object Class can be instantiated in different ways. First, all observers should have a name that will distinguish it from other Observer Objects and also allows the Occultation Object to control all the steps and Objects. This is the name which the user will use to refer to this observer within the Occultation Object. The name is not needed when the site is downloaded from the MPC database in which case the name in the MPC will be used.

The Observer main objective is to deal with the observer location, convert the coordinates from ITRS and GCRS and vice-versa and calculate the Orthographic projection the coordinates in the direction of a coordinate.

Observer?

Init signature: Observer(**kwargs)
Docstring:
Defines the observer object.

Attributes
----------
name : `str`
    Name for the Observer. Observer is uniquely defined (name must be
    different for each observer).

code : `str`
    The IAU code for SORA to search for its coordinates in MPC database.

site : `astropy.coordinates.EarthLocation`
    User provides an EarthLocation object.

lon : `str`, `float`
    The Longitude of the site in degrees.
    Positive to East. Range (0 to 360) or (-180 to +180).
    User can provide in degrees (`float`) or hexadecimal (`string`).

lat : `str`, `float`
    The Latitude of the site in degrees.
    Positive North. Range (+90 to -90).
    User can provide in degrees (float) or hexadecimal (string).

height : `int`, `float`
    The height of the site in meters above see level.

ephem : `str`, `list`
    The ephemeris used to locate the observer on space.
    It can be "horizons" to use horizons or a list of kernels


Examples
--------
User can provide one of the following to define an observer:

- If user will use the MPC name for the site:

>>> Observer(code)

- If user wants to use a different name from the MPC database:

>>> Observer(name, code)

- If user wants to use an EarthLocation value:

>>> from astropy.coordinates import EarthLocation
>>> EarthLocation(lon, lat, height)
>>> Observer(name, site)

- If user wants to give site coordinates directly:

>>> Observer(name, lon, lat, height)
File:           ~/SORA-lightcurve/sora/observer/core.py
Type:           type
Subclasses:

Example of an Observer intantiated with a MPC code

opd = Observer(code='874')

/home/chrycho/SORA-lightcurve/sora/observer/utils.py:28: UserWarning: Querying code 874 in the Linea MPC Observer Database...
  warnings.warn(f'Querying code {code} in the Linea MPC Observer Database...')

## To see the name of the object "opd"
opd.name

'Observatorio do Pico dos Dias, Itajuba'

In this case, the name is a bit too long, the user can define a differente name upon instantiation.

opd = Observer(name='OPD', code='874')

/home/chrycho/SORA-lightcurve/sora/observer/utils.py:28: UserWarning: Querying code 874 in the Linea MPC Observer Database...
  warnings.warn(f'Querying code {code} in the Linea MPC Observer Database...')

Example of Observer instantiated with coordinates

This coordinates must in degrees for longitude and latitude and in meters in height.

# using string representation
obs1 = Observer(name='Ex 1', lon='-45 34 57', lat='-22 32 04', height=1864)

# using numeric representation
obs2 = Observer(name='Ex 2', lon=-69.295805, lat=-31.79877, height=2495)

Example using an Astropy EarthLocation Object

Astropy has an EarthLocation Class with observer location information. SORA uses this class as a core functionality in the Observer Class. So the user can give an object created from EarthLocation as input.

from astropy.coordinates import EarthLocation
site = EarthLocation(lon='-45 34 57', lat=' -22 32 04', height=1864)
obs3 = Observer(name='Ex 3', site=site)

The user can access some information from the object as attribute

obs3.name

'Ex 3'

obs3.lon

$-45^\circ34{}^\prime57{}^{\prime\prime}$

obs3.lat

$-22^\circ32{}^\prime04{}^{\prime\prime}$

obs3.height

$1864 \; \mathrm{m}$

If the user wants to see the informations in the object, just prints the object directly.

print(obs3)

Site: Ex 3
Geodetic coordinates: Lon: -45d34m57s, Lat: -22d32m04s, height: 1.864 km

1.2 Spacecraft

In SORA, it is possible to inform an spacecraft observation. The Spacecraft Class provides functionality to identify the observer in space. This way, the Occultation object can calculate the geometry for the combination of different Sacecraft and Observer objects.

For this, to instantiate a Spacecraft object, it is required an ephemeris. The options available are: the string “horizons” to use ephemeris from the Horizons web service; a list of spice kernels where Spice can identify the spacecraft relative to the barycenter of the Solar System. A “spkid” is also required. Please do not use an Ephem object in this case.

cassini = Spacecraft(name='Cassini', spkid='-82', ephem='horizons')

# Using kernels. For example, downloading the New Horizons kernel from
# https://naif.jpl.nasa.gov/pub/naif/pds/data/nh-j_p_ss-spice-6-v1.0/nhsp_1000/data/spk/

# new_horizons = Spacecraft(name='New Horizons', spkid='-98', ephem=['nh_recon_pluto_od122_v01.bsp'])

2. Setting and/or modifing parameters

If any parameter given to Observer is not correct, the user does not need to delete or overwrite the previous object. It can be given the new values directly to the object attributes. Only the name attribute cannot be replaced.

print(obs3.lon)

-45d34m57s

obs3.lon = '-35 40 26'
print(obs3.lon)

-35d40m26s

obs3.lon = 67.3514
print(obs3.lon)

67d21m05.04s

try:
    obs3.name = 'Teste'
except AttributeError as err:
    print(err)

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[1], line 3
      1 try:
      2     obs3.name = 'Teste'
----> 3 except AttributeError as err:
      4     print(err)

NameError: name 'obs3' is not defined

3. Apparent Sidereal Time

If the user, for some reason, wants to know the apparent sidereal time at a certain location for a given time, there exists a function that calculates it. This function is only available for the Observer object.

obs3.sidereal_time?

obs3.sidereal_time(time='2020-05-10 00:00:00')

The input time can also be an Astropy Time Object

from astropy.time import Time

t = Time('2020-05-10 00:00:00')

obs3.sidereal_time(t)

If the user wants to calculate the Greenwich Apparent Sidereal Time, it can be done as:

obs3.sidereal_time('2020-05-10 00:00:00', mode='greenwich')

Also, with the Observer the user can calculate the altitude and azimuth of a given target.

obs3.altaz?

altitude, azimuth = obs3.altaz(time='2020-05-10 00:00:00', coord='20 12 19.3 +25 30 00.5')

print('Altitude {:.2f} degrees'.format(altitude))
print('Azimuth  {:.2f} degrees'.format(azimuth))

4. Ksi and Eta projection

Observer object calculates the orthographic projection (ksi and eta) of a site in the direction of a star given the following function. Ksi is in the East direction and Eta in the North direction.

The coordinates of the star given must be in the Geocentric Celestial Reference System (GCRS).

This is calculated automaticaly in Occultation.

obs3.get_ksi_eta?

ksi, eta = obs3.get_ksi_eta(time='2020-05-10 00:00:00', star='19 21 18.63201 -21 44 25.3924')
print(ksi, eta)

A list of times can be given to the time param, as shown below.

times = ['2020-05-10 00:00:00', '2020-05-10 01:00:00', '2020-05-10 02:00:00', '2020-05-10 03:00:00']
ksi, eta = obs3.get_ksi_eta(time=times, star='19 21 18.63201 -21 44 25.3924')
print(ksi)
print(eta)

5. MPC observatories

The user can query an observatory from the MPC database by giving its MPC code. These are ground-based observatories. The spacecraft observatories are ignored. The function returns the observatory name together with its EarthLocation.

from sora.observer import search_code_mpc
search_code_mpc('874')

search_code_mpc('511')

name, site = search_code_mpc('874')
name

site

This Jupyter-Notebook was designed as a tutorial for how to work with the Observer Class. More information about the other classes, please refer to their specif Jupyter-Notebook. Any further question, please contact the core team: Altair Ramos Gomes Júnior, Bruno Eduardo Morgado, Gustavo Benedetti Rossi, and Rodrigo Carlos Boufleur.

The End