sora.body

The Body Class

class sora.Body(name, database='auto', **kwargs)[source]

Represent and manage information for a Solar System body.

Parameters:

  • name (str, required) – Name of the object. It can also be the spkid or designation number used to query the SBDB (Small-Body DataBase). In this case, the name is case-insensitive.

  • database (str, None, optional, default=’auto’) – Database used to query the object. It can be 'satdb' for the temporary hardcoded satellite database, 'sbdb' to query the SBDB, or 'auto' to try 'satdb' first and then 'sbdb'. If the user wants to provide the object information locally, database must be None and spkid must be given.

  • ephem (sora.EphemKernel, sora.EphemHorizons, sora.EphemJPL, sora.EphemPlanete) – Ephemeris object that contains information about the object’s ephemeris. It can also be 'horizons' to automatically define an sora.EphemHorizons object, or a list of kernels to automatically define an sora.EphemKernel object.

  • orbit_class (str) – Orbital class of the body. It can be TNO, Satellite, Centaur, comet, asteroid, trojan, neo, or planet. It is important for a better characterization of the object. If a different value is given, it will be defined as unclassified.

  • spkid (str, int, float) – If database=None, the user must give a spkid or an ephem object that has a spkid parameter.

  • shape (str, sora.body.shape.Shape3D) – Input shape of the body. It can be a sora.body.shape.Shape3D object or the path to an OBJ file.

  • albedo (float, int) – The albedo of the object.

  • H (float, int) – The absolute magnitude.

  • G (float, int) – The phase slope.

  • diameter (float, int, astropy.quantity.Quantity) – The diameter of the object, in km.

  • density (float, int, astropy.quantity.Quantity) – The density of the object, in g/cm3.

  • GM (float, int, astropy.quantity.Quantity) – The standard gravitational parameter, in km3/s2.

  • rotation (float, int, astropy.quantity.Quantity) – The rotation period of the object, in hours.

  • pole (str, astropy.coordinates.SkyCoord) – The pole coordinates of the object. It can be a SkyCoord object or a string in the format 'hh mm ss.ss +dd mm ss.ss'.

  • BV (float, int) – The B-V color.

  • UB (float, int) – The U-B color.

  • smass (str) – The spectral type in SMASS classification.

  • tholen (str) – The spectral type in Tholen classification.

Note

The following attributes are returned from the Small-Body DataBase when database='sbdb' or from our temporary hardcoded Satellite DataBase when database='satdb':

orbit_class, spkid, albedo, H, G, diameter, density, GM, rotation, pole, BV, UB, smass, and tholen.

These are physical parameters that the user can provide to the object. If a query is made and the user provides one of these parameters, the user value is used in the Body object.

__from_local(name, spkid)

Define a Body object with local input values.

Parameters:

  • name (str) – Name of the object.

  • spkid (str, int, float) – SPK-ID of the object. Required when database=None.

__from_satdb(name)

Search the object in the satellite database and define its parameters.

Parameters:

name (str) – Name of the satellite.

__from_sbdb(name)

Searches the object in the SBDB and defines its physical parameters.

Parameters:

name (str) – The name, spkid or designation number of the Small Body.

apparent_magnitude(time, observer='geocenter')[source]

Calculate the object’s apparent magnitude.

Parameters:

  • time (str, astropy.time.Time) – Reference time to calculate the object’s apparent magnitude. It can be a string in the ISO format (yyyy-mm-dd hh:mm:ss.s) or an astropy Time object.

  • observer (str, sora.Observer, sora.Spacecraft) – IAU code of the observer (must be present in given list of kernels), a SORA observer object, or one of 'geocenter' or 'barycenter'.

Returns:

ap_mag – Object apparent magnitude. A list is returned when multiple epochs are provided and the value is obtained from JPL Horizons.

Return type:

float, list of float

get_orientation(time, observer='geocenter')[source]

Return the object orientation as seen by an observer.

Parameters:

  • time (str, astropy.time.Time) – Epoch of observation to calculate the object orientation. It can be a string in the ISO format (yyyy-mm-dd hh:mm:ss.s) or an astropy Time object.

  • observer (str, sora.Observer, sora.Spacecraft) – IAU code of the observer (must be present in given list of kernels), a SORA observer object, or one of 'geocenter' or 'barycenter'.

Returns:

orientation – Dictionary with the orientation parameters. Keys may include 'sub_observer' and 'sub_solar' as decimal coordinate strings, and 'pole_position_angle' and 'pole_aperture_angle' as angles in degrees.

Return type:

dict

get_pole_position_angle(time, observer='geocenter')[source]

Return the pole position angle and aperture angle for an observer.

Parameters:

  • time (str, astropy.time.Time) – Time from which to calculate the position. It can be a string in the ISO format (yyyy-mm-dd hh:mm:ss.s) or an astropy Time object.

  • observer (str, sora.Observer, sora.Spacecraft) – IAU code of the observer (must be present in given list of kernels), a SORA observer object, or one of 'geocenter' or 'barycenter'.

Returns:

position_angle, aperture_angle – Position angle and aperture angle of the object’s pole in degrees.

Return type:

astropy.units.Quantity

get_position(time, observer='geocenter')[source]

Return the object position as seen by an observer.

Parameters:

  • time (str, astropy.time.Time) – Reference time to calculate the object position. It can be a string in the ISO format (yyyy-mm-dd hh:mm:ss.s) or an astropy Time object.

  • observer (str, sora.Observer, sora.Spacecraft) – IAU code of the observer (must be present in given list of kernels), a SORA observer object, or one of 'geocenter' or 'barycenter'.

Returns:

coord – Astropy SkyCoord object with the object coordinates at the given time.

Return type:

astropy.coordinates.SkyCoord

plot(time=None, observer='geocenter', center_f=0, center_g=0, contour=False, ax=None, plot_pole=True, **kwargs)[source]

Plot the body shape as viewed by an observer.

If the user wants to define the orientation directly, use shape.plot() instead.

Parameters:

  • time (str, astropy.time.Time) – Reference time used to calculate the object’s orientation. It can be a string in the ISO format (yyyy-mm-dd hh:mm:ss.s) or an astropy Time object. It must be only one value.

  • observer (str, sora.Observer, sora.Spacecraft) – IAU code of the observer (must be present in given list of kernels), a SORA observer object, or one of 'geocenter' or 'barycenter'.

  • center_f (int, float) – Offset of the center of the body in the East direction, in km

  • center_g (int, float) – Offset of the center of the body in the North direction, in km

  • contour (bool) – If True, it plots the limb of the projected shape. If False, it plots the 3D shape. Default: False.

  • ax (matplotlib.pyplot.Axes) – Axes where the plot is drawn. If None, the default axes are used.

  • plot_pole (bool) – If True, the direction of the pole is plotted. Ignored if contour=True.

  • **kwargs – Additional keyword arguments forwarded to the shape plotting method. These may include radial_offset, the offset of the center of the body in the direction of observation, in km.

to_log(namefile)[source]

Save the body log to a file.

Parameters:

namefile (str) – Path of the output log file.

PhysicalData Class

class sora.body.PhysicalData(name, value, uncertainty=0.0, reference='User', notes='', unit=Unit(dimensionless), raise_error=False)[source]

Represent a physical quantity with uncertainty, reference, and notes.

Note

This class inherits from astropy.units.Quantity.

Parameters:

  • name (str) – Name of the corresponding physical parameter.

  • value (int, float, str, ~numpy.ndarray, astropy.quantity.Quantity) – Numerical value of this quantity in the units given by unit. If a Quantity, or any other valid object with a unit attribute, is provided, the value is converted to unit as needed. If a string is provided, it is converted to a number or Quantity, depending on whether a unit is present.

  • uncertainty (int, float, str, ~numpy.ndarray, astropy.quantity.Quantity, default=0) – Uncertainty associated with value, in units compatible with unit. It accepts the same input types as value. A string ending in % is interpreted as a relative uncertainty, and a string with values separated by / uses the largest absolute value.

  • reference (str, default=’User’) – Reference for the parameter value.

  • notes (str, default=’’) – Additional information about the physical parameter.

  • unit (str, ~astropy.units.UnitBase instance, default=’dimensionless’) – Unit associated with the input value. It must be an ~astropy.units.UnitBase object or a string parsable by units.

  • raise_error (bool, default=False) – If True and value=None, raise an error. Otherwise, None values are converted to NaN.

Complementary functions

sora.body.utils.apparent_magnitude(H, G, dist, sundist, phase=0.0)[source]

Calculate the object’s apparent magnitude.

Parameters:

  • H (int, float) – Absolute magnitude.

  • G (int, float) – Slope parameter.

  • dist (int, float) – Observer-object distance, in AU.

  • sundist (int, float) – Sun-object distance, in AU.

  • phase (int, float, default=0) – Phase angle (Sun-target-observer), in degrees.

Returns:

ap_mag – Apparent magnitude.

Return type:

float

sora.body.utils.search_sbdb(name)[source]

Search the JPL Small-Body Database for object information.

This function searches only for small bodies. Planet and satellite information is not retrieved by this function.

Parameters:

name (str) – Name of the object to search for. It can also be the assigned spkid or designation number. The name is case-insensitive.

Returns:

sbdb – Ordered dictionary with the object information.

Return type:

dict

Important

The query is not an autocomplete search, so name='Charikl' will not find Chariklo. If more than one object is found, the user is asked to select the correct one, for example name='neowise'.