`ephemeris`¶

This module contains a set of factory functions for setting up the ephemeris models of celestial bodies in an environment.

The main interfaces with Tudat is the ephemeris_settings attribute (of type EphemerisSettings) of the body settings, which defines settings for the ephemeris of a body. The functions in this submodule are used to create these settings objects. When creating a body (typically using the create_system_of_bodies() function), an object of type Ephemeris (or a derived class) is created and added to the associated Body object based on the settings object, which can be retrieved using the ephemeris attribute.

The following code block gives an overview of the steps to define, create, and extract an ephemeris model, for the specific example of ephemeris of the Earth from Spice, with the Sun as ephemeris origin (and J2000 frame orientation).

from tudatpy.dynamics import environment_setup

# Create body settings
body_settings =  environment_setup.get_default_body_settings( ... ) # Typical way to instantiate body settings

# Modify ephemeris model settings (base class type EphemerisSettings)
body_settings.get( 'Earth' ).ephemeris_settings = environment_setup.ephemeris.direct_spice(
    frame_origin = 'Sun',
    frame_orientation = 'J2000' )

# Create bodies
bodies = environment_setup.create_system_of_bodies(body_settings)

# Extract ephemeris model (base class type Ephemeris) from Earth
earth_ephemeris_model = bodies.get( 'Earth' ).ephemeris

Below a short overview of aspects of some of the ephemeris models in order to aid in properly selecting an choosing a model.

Spice-based models For many typical applications, natural body ephemerides will be calculated from Spice kernels. In some cases, a user may find that the default Spice kernels are insufficient for their purposes, due to one of two reasons:

The body for which the state is required is in the ephemeris Spice kernel, but the time at which the state is needed lies outside of the bounds for which the Spice kernel has data
The body for which the state is required is not in the ephemeris Spice kernel

In both cases, a user should load additional Spice kernels. This can be done using the load_kernel(). Spice kernels for many bodies may be found in a number of places. The ‘goto’ place for Spice kernels for ephemerides is the NAIF website (developers of Spice), which you can find here.

Use of scaled models For a sensitivity analysis (among others) it may be useful to modify the ephemeris of a body, for instance to emulate the influence of a 1 km offset in the state provided by the nominal ephemeris. Unlike most other environment models, this cannot be achieved (at least not for most types of ephemerides) by modifying a single defining parameter of the model. Instead, we provide the functions scaled_by_vector() and scaled_by_vector_function(), which take nominal ephemeris settings, and add a user-defined variation (constant or time-varying; absolute or relative) to the inertial Cartesian state elements produced by the ephemeris.

Using the ephemeris outside the propagation In various cases, the ephemeris object is useful to use independently of the propagation. Details can be found in the API entry for Ephemeris, but we provide a short example here as well.

bodies = .... # Create system of bodies
earth_ephemeris = bodies.get('Earth').ephemeris
earth_state_at_epoch = earth_ephemeris.cartesian_state( epoch )

where the epoch input is (as always in Tudat) the time in seconds since J2000. The earth_state_at_epoch is always in a frame with inertial orientation. The specific orientation and origin can be access from the frame_orientation and frame_origin attributes.

Creating ephemeris objects from ephemeris settings Ephemeris objects can also be created directly from ephemeris settings using the create_body_ephemeris() function. This can be useful if you want to create an ephemeris object for a body that is not part of a system of bodies to perform further analysis, such as the barycenter of the Martian system:

frame_origin = "SSB"
frame_orientation = "ECLIPJ2000"
body_name_to_use =  "MARS BARYCENTER"
mars_system_ephemeris_settings = environment_setup.ephemeris.direct_spice(
   frame_origin, frame_orientation, body_name_to_use ) # Create ephemeris settings
mars_system_ephemeris = environment_setup.create_body_ephemeris(mars_system_ephemeris_settings,
   "MARS BARYCENTER") # Create ephemeris object

Functions¶

`direct_spice`([frame_origin, ...])	Function for creating ephemeris model settings entirely from Spice.
`interpolated_spice`(initial_time, final_time, ...)	Function for creating ephemeris model settings using interpolated Spice data.
`approximate_jpl_model`(body_name)	Function for creating approximate ephemeris model settings for major planets.
`constant`(constant_state[, frame_origin, ...])	Function for creating constant ephemeris model settings.
`custom_ephemeris`(custom_state_function[, ...])	Function for creating custom ephemeris model settings.
`keplerian`(initial_keplerian_state, ...[, ...])	Function for creating Keplerian ephemeris model settings.
`keplerian_from_spice`(body, ...[, ...])	Function for creating Keplerian ephemeris model settings with initial state from Spice.
`sgp4`(tle_line_1, tle_line_2[, frame_origin, ...])	Function for creating ephemeris model settings for an SGP4-propagated TLE.
`scaled_by_constant`(...[, is_scaling_absolute])	Function for creating scaled ephemeris model settings.
`scaled_by_vector`(...[, is_scaling_absolute])	Function for creating scaled ephemeris model settings.
`scaled_by_vector_function`(...[, ...])	Function for creating scaled ephemeris model settings.
`tabulated`(body_state_history[, ...])	Function for creating ephemeris model settings from tabulated data.
`tabulated_from_existing`(ephemeris_settings, ...)	Function for creating tabulated ephemeris model settings from existing ephemeris.
`horizons_wrapper.jpl_horizons`(...[, ...])	Factory function for creating ephemeris model settings from tabulated JPL Horizons vectors.
`multi_arc_ephemeris`(...[, frame_origin, ...])	Function for creating multi-arc ephemeris model settings.

direct_spice(frame_origin: str = 'SSB', frame_orientation: str = 'ECLIPJ2000', body_name_to_use: str = '') → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating ephemeris model settings entirely from Spice.

Function for settings object, defining ephemeris model directly and entirely from Spice. Requires an appropriate Spice kernel to be loaded.

Parameters:

frame_origin (str, default="SSB") – Origin of frame in which ephemeris data is defined.
frame_orientation (str, default="ECLIPJ2000") – Orientation of frame in which ephemeris data is defined.
body_name_to_use (str, default = "") – Body from which Spice ephemeris is to be created (if empty, it uses the name of the body to which the settings are assigned, see below for example).

Returns:

Instance of the EphemerisSettings derived DirectSpiceEphemerisSettings class

Return type:

DirectSpiceEphemerisSettings

Examples

In this example, we create barycentric (origin: SSB) EphemerisSettings with axes along J2000, using data directly from spice:

frame_origin = "SSB"
frame_orientation = "J2000"
body_settings.get( "Jupiter" ).ephemeris_settings = environment_setup.ephemeris.direct_spice(
    frame_origin, frame_orientation)

Alternatively, we can assign the DirectSpiceEphemerisSettings of Jupiter (or any other body for which a direct Spice ephemeris is available) to any custom body:

frame_origin = "SSB"
frame_orientation = "J2000"
body_name_to_use =  "Jupiter"
# create ephemeris settings from "Jupiter" spice data and add to body settings of body "CustomBody"
body_settings.get( "CustomBody" ).ephemeris_settings = environment_setup.ephemeris.direct_spice(
    frame_origin, frame_orientation, body_name_to_use )

interpolated_spice(initial_time: float | SupportsIndex, final_time: float | SupportsIndex, time_step: float | SupportsIndex, frame_origin: str = 'SSB', frame_orientation: str = 'ECLIPJ2000', interpolator_settings: tudatpy.kernel.math.interpolators.InterpolatorSettings = <tudatpy.kernel.math.interpolators.LagrangeInterpolatorSettings object at 0x7fa5cc4993b0>, body_name_to_use: str = '') → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating ephemeris model settings using interpolated Spice data.

Function for settings object defining an ephemeris model from interpolated Spice data. Using this option the state of the body is retrieved from Spice at regular intervals before the environment propagation (as opposed to during the propagation). These data are then used to create an interpolator, which is put into the environment, and called during the propagation. This option has the downside of being applicable only during a limited time interval and requiring the tabulated data to be stored in RAM, but may for some special cases offer an advantage over a direct Spice ephemeris (direct_spice()).

Parameters:

initial_time (astro.time_representation.Time) – Initial time from which interpolated data from Spice should be created (Time object representing seconds since J2000 TDB).
final_time (astro.time_representation.Time) – Final time from which interpolated data from Spice should be created (Time object representing seconds since J2000 TDB).
time_step (float) – Time step with which interpolated data from Spice should be created.
frame_origin (str, default="SSB") – Origin of frame in which ephemeris data is defined.
frame_orientation (str, default="ECLIPJ2000") – Orientation of frame in which ephemeris data is defined.
interpolator_settings (std::make_shared< interpolators::InterpolatorSettings >, default=std::make_shared< interpolators::LagrangeInterpolatorSettings >( 6 )) – Settings to be used for the state interpolation.
body_name_to_use (str, default = "") – Body from which Spice ephemeris is to be created.

Returns:

Instance of the DirectSpiceEphemerisSettings derived InterpolatedSpiceEphemerisSettings class

Return type:

InterpolatedSpiceEphemerisSettings

Examples

In this example, we define EphemerisSettings for Jupiter by retrieving ephemeris data from Spice at 3600 s intervals between t=0 and t=1.0E8:

# Define the interpolation settings
initial_time = Time(0.0)
final_time = Time(1.0E8)
time_step = 3600.0
# Define the ephemeris frame
frame_origin = "SSB"
frame_orientation = "J2000"
# create ephemeris settings and add to body settings of body "Jupiter"
body_settings.get( "Jupiter" ).ephemeris_settings = environment_setup.ephemeris.interpolated_spice(
  initial_time, final_time, time_step, frame_origin, frame_orientation )

By default, a 6th order Lagrange interpolator is used (NOTE: the Lagrange interpolator is not reliable at the edges of the interpolation interval, as discussed here: lagrange_interpolation()). Settings for an alternative interpolator can be use by specifying the optional input argument. Additionally, as is the case for the direct_spice() and approximate_jpl_model() functions, an optional input argument body_name_to_use allows to use an ephemeris model from Spice for some body and assign it to a custom body.

approximate_jpl_model(body_name: str) → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating approximate ephemeris model settings for major planets.

Function for settings object, defining approximate ephemeris model for major planets. In this highly simplified ephemeris model, Keplerian elements of the major solar system bodies are modelled as linear functions of time and several sinusoidal variations (described in this document). Note that this option is only available for solar system planets. For the case of the Earth the approximate ephemeris of the Earth-Moon barycenter is returned.

Parameters:: body_name (str) – String that is attempted to be matched to an identifier for the body that the ephemeris is to be created for.
Returns:: Instance of the EphemerisSettings derived ApproximateJplEphemerisSettings class
Return type:: ApproximateJplEphemerisSettings

Examples

In this example, we create EphemerisSettings for Jupiter using JPL’s approximate planet position model:

# create ephemeris settings and add to body settings of body "Jupiter"
body_settings.get( "Jupiter" ).ephemeris_settings = environment_setup.ephemeris.approximate_jpl_model( "Jupiter" )

Alternatively, we can assign the ApproximateJplEphemerisSettings of Jupiter (or any other body for which an approximate JPL ephemeris is available) to any custom body:

# create ephemeris settings (normally used for Jupiter) and add to body settings of body "CustomBody"
body_settings.get( "CustomBody" ).ephemeris_settings = environment_setup.ephemeris.approximate_jpl_model( "Jupiter" )

                            ephemerides::ApproximatePlanetPositionsBase::jupiter, false );

constant(constant_state: numpy.ndarray[numpy.float64[6, 1]], frame_origin: str = 'SSB', frame_orientation: str = 'ECLIPJ2000') → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating constant ephemeris model settings.

Function for settings object, defining ephemeris model with a constant, time-independent state.

Parameters:

constant_state (numpy.ndarray[numpy.float64[6, 1]]) – Constant state that will be provided as output of the ephemeris at all times.
frame_origin (str, default="SSB") – Origin of frame in which ephemeris data is defined.
frame_orientation (str, default="ECLIPJ2000") – Orientation of frame in which ephemeris data is defined.

Returns:

Instance of the EphemerisSettings derived ConstantEphemerisSettings class

Return type:

ConstantEphemerisSettings

Examples

In this example, we create EphemerisSettings for a time-independent, constant state of Jupiter:

# Define the constant cartesian state
constant_cartesian_state = [100.0e9, 100.0e9, 100.0e9, 10.0e3, 10.0e3, 10.0e3]
# Define the ephemeris frame
frame_origin = "SSB"
frame_orientation = "J2000"
# Make the ephemeris settings
body_settings.get( "Jupiter" ).ephemeris_settings = environment_setup.ephemeris.constant(
  constant_cartesian_state,
  frame_origin, frame_orientation)

custom_ephemeris(custom_state_function: Callable[[float | SupportsIndex], numpy.ndarray[numpy.float64[6, 1]]], frame_origin: str = 'SSB', frame_orientation: str = 'ECLIPJ2000') → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating custom ephemeris model settings.

Function for settings object, defining ephemeris model with a custom state. This allows the user to provide a custom state function as ephemeris model.

Parameters:

custom_state_function (callable[[float], numpy.ndarray[numpy.float64[6, 1]]]) – Function returning the state as a function of time.
frame_origin (str, default="SSB") – Origin of frame in which ephemeris data is defined.
frame_orientation (str, default="ECLIPJ2000") – Orientation of frame in which ephemeris data is defined.

Returns:

Instance of the EphemerisSettings derived CustomEphemerisSettings class

Return type:

CustomEphemerisSettings

Examples

In this example, we create EphemerisSettings for Earth from a custom state history function:

# Define the custom state function for Earth
def custom_state_function(time):
    # Compute what fraction of the year it is
    frac_year = (time - 2451545) % (365.25*24*3600)
    # Distance and velocity of the Earth w.r.t. the Sun
    AU, v_E = 1.496e11, 30e3
    # Compute the position and velocity of the Earth in a 2D circle
    x_pos = np.sin(frac_year*np.pi) * AU
    y_pos = np.cos(frac_year*np.pi) * AU
    x_vel = np.cos(frac_year*np.pi) * v_E
    y_vel = np.sin(frac_year*np.pi) * v_E
    return [x_pos, y_pos, 0, x_vel, y_vel, 0]
# Define the ephemeris frame
frame_origin = "SSB"
frame_orientation = "J2000"
# Make the ephemeris settings
body_settings.get("Earth").ephemeris_settings = environment_setup.ephemeris.custom(
    custom_state_function,
    frame_origin,
    frame_orientation)

keplerian(initial_keplerian_state: numpy.ndarray[numpy.float64[6, 1]], initial_state_epoch: float | SupportsIndex, central_body_gravitational_parameter: float | SupportsIndex, frame_origin: str = 'SSB', frame_orientation: str = 'ECLIPJ2000', root_finder_absolute_tolerance: float | SupportsIndex = 4.440892098500626e-14, root_finder_maximum_iterations: float | SupportsIndex = 1000.0) → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating Keplerian ephemeris model settings.

Function for settings object, defining ephemeris model which represents an ideal Kepler orbit from the given Kepler elements. These are taken as the elements at the initial_state_epoch and propagated to any other time using the provided central_body_gravitational_parameter. See Element Types and the astro module for more details on orbital elements in tudat.

Parameters:

initial_state_in_keplerian_elements (numpy.ndarray[numpy.float64[6, 1]]) – Kepler elements at epoch given by initial_state_epoch.
initial_state_epoch (astro.time_representation.Time) – Epoch at which initial_state_epoch represents the Keplerian state (Time object representing seconds since J2000 TDB).
central_body_gravitational_parameter (float) – Effective gravitational parameter of the central body that is used in the computations. Note that when the Keplerian orbit is to represent the relative state of two massive bodies, with one of these bodies as the origin this values should be the sum of the two bodies’ gravitational parameters
frame_origin (str, default="SSB") – Origin of frame in which ephemeris data is defined.
frame_orientation (str, default="ECLIPJ2000") – Orientation of frame in which ephemeris data is defined.
root_finder_absolute_tolerance (float) – Convergence tolerance on iterative conversion from mean to eccentric anomaly; applies every time a cartesian state is requested from the kepler ephemeris, such as during propagation.
root_finder_maximum_number_of_iterations (float) – Maximum iteration on iterative conversion from mean to eccentric anomaly; applies every time a cartesian state is requested from the kepler ephemeris, such as during propagation.

Returns:

Instance of the EphemerisSettings derived KeplerEphemerisSettings class

Return type:

KeplerEphemerisSettings

Examples

In this example, we create EphemerisSettings for a simple, barycentric (SSB) Kepler orbit of Jupiter:

# Define the computation of the Kepler orbit ephemeris
initial_state_in_keplerian_elements = [100e9, 0.7, 1.0, 2.0, 2.0, 2.0]
initial_state_epoch = Time(12345)
central_body_gravitational_parameter = 1.3284e20 # (sum of Sun and Jupiter)
# Define the ephemeris frame
frame_origin = "SSB"
frame_orientation = "J2000"
# Create ephemeris settings and add to body settings of "Jupiter"
body_settings.get( "Jupiter" ).ephemeris_settings = environment_setup.ephemeris.keplerian(
    initial_state_in_keplerian_elements,
    initial_state_epoch,
    central_body_gravitational_parameter,
    frame_origin, frame_orientation )

keplerian_from_spice(body: str, initial_state_epoch: float | SupportsIndex, central_body_gravitational_parameter: float | SupportsIndex, frame_origin: str = 'SSB', frame_orientation: str = 'ECLIPJ2000', root_finder_absolute_tolerance: float | SupportsIndex = 4.440892098500626e-14, root_finder_maximum_iterations: float | SupportsIndex = 1000.0) → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating Keplerian ephemeris model settings with initial state from Spice.

Function for settings object, defining ephemeris model which represents an ideal Kepler orbit from an initial state from Spice. The Kepler elements inferred from the initial state are propagated to any other time using the provided central_body_gravitational_parameter. See Element Types and the astro module for more details on orbital elements in tudat.

Parameters:

body (str) – Name of body for which to create ephemeris settings and infer initial state from Spice.
initial_state_epoch (astro.time_representation.Time) – Epoch at which initial_state_epoch represents the Keplerian state (Time object representing seconds since J2000 TDB).
central_body_gravitational_parameter (float) – Gravitational parameter of the central body that is used in the computations.
frame_origin (str, default="SSB") – Origin of frame in which ephemeris data is defined.
frame_orientation (str, default="ECLIPJ2000") – Orientation of frame in which ephemeris data is defined.
root_finder_absolute_tolerance (float) – Convergence tolerance on iterative conversion from mean to eccentric anomaly; applies every time a cartesian state is requested from the kepler ephemeris, such as during propagation.
root_finder_maximum_number_of_iterations (float) – Maximum iteration on iterative conversion from mean to eccentric anomaly; applies every time a cartesian state is requested from the kepler ephemeris, such as during propagation.

Returns:

Instance of the EphemerisSettings derived KeplerEphemerisSettings class

Return type:

KeplerEphemerisSettings

Examples

In this example, we create EphemerisSettings for a simple, barycentric (SSB) Kepler orbit of Jupiter. The initial keplerian state is extracted from Spice as the state of body_name w.r.t. frame_origin

# Define the parameters for retrieval of the initial Kepler orbit elements from spice
body_name = "Jupiter"
initial_state_epoch = Time(12345)
central_body_gravitational_parameter = 1.3284e20 # (sum of Sun and Jupiter)
# Define the ephemeris frame
frame_origin = "SSB"
frame_orientation = 'J2000'
# Make ephemeris the settings and add to body settings of "Jupiter"
body_settings.get( "Jupiter" ).ephemeris_settings = environment_setup.ephemeris.keplerian_from_spice(
    body_name,
    initial_state_epoch,
    central_body_gravitational_parameter,
    frame_origin,
    frame_orientation )

Additionally, as is the case for the direct_spice(), approximate_jpl_model() and interpolated_spice() functions, the ephemeris model from Spice can be retrieved for some body and assigned to a custom body.

sgp4(tle_line_1: str, tle_line_2: str, frame_origin: str = 'Earth', frame_orientation: str = 'J2000') → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating ephemeris model settings for an SGP4-propagated TLE.

Function for creating ephemeris model settings for an SGP4-propagated two-line element (TLE). Our implementation uses the evsgp4_c function of the SPICE library to perform the SGP4 propagation, and the teme_to_j2000() function to rotate the resulting state from the TEME frame to the J2000 frame (and, if required for this ephemeris model, a subsequent different inertial frame).

Parameters:

tle_line_1 (str) – First line of the two-line element set
tle_line_2 (str) – second line of the two-line element set
frame_origin (str, default="Earth") – Origin of frame in which ephemeris data is defined. At present, only “Earth” is supported.
frame_orientation (str, default="J2000") – Orientation of frame in which ephemeris data is defined.

Returns:

Instance of the EphemerisSettings derived DirectTleEphemerisSettings class

Return type:

DirectTleEphemerisSettings

Examples

In this example, we create ephemeris settings for Delfi-C3, using the two lines of the TLE formatted as strings:

 # Create ephemeris settings for Delfi C-3 spacecraft using launch TLE
  body_settings.get( "Delfi-C3" ).ephemeris_settings =  environment_setup.ephemeris.sgp4(
       '1 32789U 07021G   08119.60740078 -.00000054  00000-0  00000+0 0  9999',
       '2 32789 098.0082 179.6267 0015321 307.2977 051.0656 14.81417433    68' )
)

scaled_by_constant(unscaled_ephemeris_settings: tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings, scaling_constant: float | SupportsIndex, is_scaling_absolute: bool = False) → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating scaled ephemeris model settings.

Function for settings object, defining ephemeris model based on an scaling of an existing ephemeris settings object. The user can apply a scaling factor (or an absolute value) to the resulting Cartesian states (for instance for an uncertainty analysis).

Parameters:

unscaled_ephemeris_settings (EphemerisSettings) – Sets base settings of ephemeris to be scaled.
scaling_constant (float) – Constant scaling factor to be applied to all elements of the Cartesian state.
is_scaling_absolute (bool, default=false) – Boolean indicating whether ephemeris scaling is absolute. Setting this boolean to true will add the scaling value to the state, instead of the default behaviour of multiplying the state by the scaling value.

Returns:

Instance of the EphemerisSettings derived ScaledEphemerisSettings class

Return type:

ScaledEphemerisSettings

Examples

In this example, we create ephemeris settings for Jupiter, by scaling an existing EphemerisSettingsObject with a constant factor:

# define variable for scaling factor
scaling_constant = 1.001
# define variables containing the existing ephemeris settings
unscaled_ephemeris_settings = body_settings.get( "Jupiter" ).ephemeris_settings
# make new ephemeris settings
body_settings.get( "Jupiter" ).ephemeris_settings =  environment_setup.ephemeris.scaled_by_constant(
       unscaled_ephemeris_settings, scaling_constant )

In the above case, the original Jupiter ephemeris setting is taken and each state element (x,y,z position and velocity) from the original ephemeris is multiplied by a factor 1.001.

scaled_by_vector(unscaled_ephemeris_settings: tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings, scaling_vector: numpy.ndarray[numpy.float64[6, 1]], is_scaling_absolute: bool = False) → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating scaled ephemeris model settings.

Parameters:

unscaled_ephemeris_settings (EphemerisSettings) – Sets base settings of ephemeris to be scaled.
scaling_vector (numpy.ndarray[numpy.float64[6, 1]]) – Vector containing scaling factors to be applied to each element of the Cartesian state.
is_scaling_absolute (bool, default=false) – Boolean indicating whether ephemeris scaling is absolute. Setting this boolean to true will add the scaling value to the state, instead of the default behaviour of multiplying the state by the scaling value.

Returns:

Instance of the EphemerisSettings derived ScaledEphemerisSettings class

Return type:

ScaledEphemerisSettings

Examples

In this example, we create ephemeris settings for Jupiter, by scaling an existing EphemerisSettingsObject with the constant elements of a vector:

# Define the scaling vector
scaling_vector = [1.01, 0.99, 1, 1, 1, 0]
# Extract the unscaled ephemeris settings from Jupiter
unscaled_ephemeris_settings = body_settings.get( "Jupiter" ).ephemeris_settings
# Create the scaled ephemeris settings and apply to the body "Jupiter"
body_settings.get( "Jupiter" ).ephemeris_settings =  environment_setup.ephemeris.scaled_by_vector(
    unscaled_ephemeris_settings,
    scaling_vector)

In the above case, the original Jupiter ephemeris setting is taken and each state element (x,y,z position and velocity) from the original ephemeris is multiplied by the corresponding scaling factor in scaling_vector.

scaled_by_vector_function(unscaled_ephemeris_settings: tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings, scaling_vector_function: Callable[[float | SupportsIndex], numpy.ndarray[numpy.float64[6, 1]]], is_scaling_absolute: bool = False) → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating scaled ephemeris model settings.

Parameters:

unscaled_ephemeris_settings (EphemerisSettings) – Sets base settings of ephemeris to be scaled.
scaling_vector_function (callable[[float], numpy.ndarray[numpy.float64[6, 1]]]) – Function returning a vector with the scaling factors to be applied to each element of the Cartesian state.
is_scaling_absolute (bool, default=false) – Boolean indicating whether ephemeris scaling is absolute. Setting this boolean to true will add the scaling value to the state, instead of the default behaviour of multiplying the state by the scaling value.

Returns:

Instance of the EphemerisSettings derived ScaledEphemerisSettings class

Return type:

ScaledEphemerisSettings

Examples

In this example, we create ephemeris settings for Jupiter, by scaling an existing EphemerisSettings object with factors from a custom function:

# Define the scaling vector function
def scaling_vector_function(time):
    # Add a wobble in the x and y coordinates
    wobble = 1 + 0.1 * np.cos(time/50)
    return [wobble, wobble, 1, 1, 1, 1]
# Extract the existing unscaled ephemeris settings
unscaled_ephemeris_settings = body_settings.get( "Jupiter" ).ephemeris_settings
# Create the scaled ephemeris settings and apply to the body "Jupiter"
body_settings.get( "Jupiter" ).ephemeris_settings =  environment_setup.ephemeris.scaled_by_vector_function(
    unscaled_ephemeris_settings,
    scaling_vector_function )

tabulated(body_state_history: dict[float | SupportsIndex, numpy.ndarray[numpy.float64[6, 1]]], frame_origin: str = 'SSB', frame_orientation: str = 'ECLIPJ2000') → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating ephemeris model settings from tabulated data.

Function for settings object, defining ephemeris model to be created from tabulated data. Currently the data that is provided gets interpolated by a 6th order Lagrange interpolator (hardcoded). At the edges of the interpolation interval a cubic spline interpolator is used to suppress the influence of Runge’s phenomenon.

Parameters:

body_state_history (dict) – Dictionary of the discrete state history data from which ephemeris is to be created. Keys representing the time (float) and values representing Cartesian states (numpy.ndarray).
frame_origin (str, default="SSB") – Origin of frame in which ephemeris data is defined.
frame_orientation (str, default="ECLIPJ2000") – Orientation of frame in which ephemeris data is defined.

Returns:

Instance of the EphemerisSettings derived TabulatedEphemerisSettings class

Return type:

TabulatedEphemerisSettings

Examples

In this example, we create EphemerisSettings for Jupiter from tabulated state history data:

# Define the Dict containing Jupiter's tabulated state history
body_state_history = {
    0: [7.4713e11, 0, 0, 13.5e3, 0, 0],
    1000: [7.4711e11, 5e9, 0, 13.4998e3, 75, 0],
    2150: [7.4671e11, 2.5e10, 0, 13.498e3, 200, 0],
    # ... truncated
    15650: [7.3899e11, 1.1e11, 0, 13.416e3, 1.5e3, 0]
}
# Define the ephemeris frame
frame_origin = "SSB"
frame_orientation = "J2000"
# Create the tabulated ephemeris settings and add them to the body "Jupiter"
body_settings.get( "Jupiter" ).ephemeris_settings = environment_setup.ephemeris.tabulated( body_state_history,
    frame_origin,
    frame_orientation )

tabulated_from_existing(ephemeris_settings: tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings, start_time: float | SupportsIndex, end_time: float | SupportsIndex, time_step: float | SupportsIndex, interpolator_settings: tudatpy.kernel.math.interpolators.InterpolatorSettings = <tudatpy.kernel.math.interpolators.LagrangeInterpolatorSettings object at 0x7fa5cc44d170>) → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating tabulated ephemeris model settings from existing ephemeris.

Function for creating tabulated ephemeris model settings from existing ephemeris. The ephemeris that is provided gets tabulated in a given time frame, for a given time step. When called, this tabulated ephemeris will use interpolation, when needed, from the specified interpolator.

Note

Creating tabulated ephemeris from existing ephemeris can for instance be used when combined with estimation. This is because estimation needs the ephemeris to be tabulated to work.

Parameters:

ephemeris_settings (tudatpy.dynamics.environment_setup.ephemeris.EphemerisSettings) – Existing ephemeris settings that have to be tabulated.
start_time (astro.time_representation.Time) – Initial time for which to create the tabulated ephemeris (Time object representing seconds since J2000 TDB).
end_time (astro.time_representation.Time) – Final time for which to create the tabulated ephemeris (Time object representing seconds since J2000 TDB).
time_step (float) – Time step to use to tabulate the existing ephemeris.
interpolator_settings (tudatpy.math.interpolators.InterpolatorSettings, default=tudatpy.math.interpolators.lagrange_interpolation(8)) – Interpolator settings to use when interpolating between two tabulated ephemeris.

Returns:

Instance of the EphemerisSettings derived TabulatedEphemerisSettings class

Return type:

TabulatedEphemerisSettings

Examples

In this example, we create EphemerisSettings for Io. First, we extract the existing ephemeris. Then, we define new tabulated ephemeris settings, from the original settings.

# Get the original ephemeris settings
original_io_ephemeris_settings = body_settings.get( "Io" ).ephemeris_settings
# Apply new tabulated ephemeris settings
body_settings.get( "Io" ).ephemeris_settings =  environment_setup.ephemeris.tabulated_from_existing(
  original_io_ephemeris_settings,
  initial_time,
  final_time,
  time_step )

jpl_horizons(horizons_query: str, horizons_location: str, frame_origin: str, frame_orientation: str = 'ECLIPJ2000', query_type: str = 'default', epoch_start: datetime | float | None = None, epoch_end: datetime | float | None = None, epoch_step: str | None = None, epoch_list: list | None = None, extended_query: bool = False, aberations: str = 'geometric')[source]¶

Factory function for creating ephemeris model settings from tabulated JPL Horizons vectors.

JPL Horizons provides access to highly accurate ephemerides for many solar system objects, including asteroids, comets, planets, moons and select spacecraft.

This function is a wrapper for the tudatpy.data.horizons functionality. That api is not available on the api documentation yet. For now, visit the HorizonsQuery source code for extensive documentation: https://github.com/tudat-team/tudatpy/blob/master/tudatpy/data/horizons.py

For more information on the Horizons System, visit: https://ssd.jpl.nasa.gov/horizons/manual.html

Examples

Add Ephemerides of JUICE to the body_settings

>>> juice_eph_settings = jpl_horizons(
        horizons_query="-121", #-121 is the query code for JUICE
        horizons_location="500@399", # Geocentre@Earth
        frame_origin="Earth", #tudat frame origin and orientation
        frame_orientation="ECLIPJ2000",
        epoch_start=datetime.datetime(2018, 10, 21),
        epoch_end=datetime.datetime(2023, 9, 1),
        epoch_step="1d",
        extended_query=True,
    )

>>> body_settings.add_empty_settings("JUICE")
>>> body_settings.get("JUICE").ephemeris_settings = juice_eph_settings

multi_arc_ephemeris(single_arc_ephemeris_settings: dict[float | SupportsIndex, tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings], frame_origin: str = 'SSB', frame_orientation: str = 'ECLIPJ2000', default_ephemeris_settings: tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings = None) → tudatpy.kernel.dynamics.environment_setup.ephemeris.EphemerisSettings¶

Function for creating multi-arc ephemeris model settings.

Function for creating multi-arc ephemeris model settings, in which different ephemerides are used over different time intervals to compute the state of a given object. This object is typically used in conjunction with a multi-arc propagation (settings for which are defined using multi_arc()) and/or estimation. Then, the propagation results of the different arcs can be used to reset the ephemeris of the body, using this multi-arc ephemeris model

The single_arc_ephemeris_settings input is a dictionary to define the arc ephemeris settings, with key the arc initial epoch \(t_{i,0}\) of arc \(i\), and with value the ephemeris settings defining the state function \(\mathbf{x}_{i}(t)\) of the associated arc \(i\). The time interval during which the arc is ‘valid’ (e.g during which the state function \(\mathbf{x}_{i}(t)\) can be queried) depends on the underlying ephemeris model. If \(\mathbf{x}_{i}(t)\) is an ephemeris model that does not have any specific boundaries of validity (such as a Keplerian ephemeris or a constant ephemeris), then arc \(i\) is defined to be the time interval \([t_{i}, t_{i+1})\) for all but the first and last arc. For the first arc, the boundary is then \([-\infty, t_{i+1})\) final arc, the boundary in this case becomes \([t_{i}, \infty)\). As a result, if the underlying arc-wise ephemerides are defined everywhere, the multi-arc ephemeris is defined everywhere.

For the case where the underlying ephemeris is not defined everywhere (for instance a tabulated ephemeris), the minimum and maximum epoch of the underlying ephemeris \(t_{\min,i},t_{\max,i}\) are extracted, and the valid time interval of arc \(i\) becomes \([\max(t_{0,i},t_{\min,i}),\min(t_{0,i+1},t_{\max,i})\). Note that, for a Lagrange interpolator underlying the tabulated ephemeris (as is the default for a numerical propagation result stored in an ephemeris), the interpolator can use a cubic spline interpolator at the boundaries of the domain to avoid Runge’s phenomenon (see lagrange_interpolation()). In this case, the interpolator is defined to be valid over the full propagation domain (even if the cubic spine interpolator will be much less accurate than the Lagrange interpolator).

For cases where there are ‘gaps’ in the coverage of the multi-arc ephemeris, we provide the option to set a default ephemeris that gets queried if a state is requested at an epoch that is not a valid epoch for any of the arcs (using the default_ephemeris_settings input). If the state is queried at an epoch where not arc is valid, and no default ephemeris is provided, an exception is thrown.

Note that, when resetting the arc-wise ephemerides (for instance as a result of a repropagation and resetting of the dynamics), both the number of arcs and the initial/final epochs of the arc may change.

Parameters:

single_arc_ephemeris_settings (dict[float, EphemerisSettings]) – Dictionary of underlying single-arc ephemeris, with the key providing \(t_{i,0}\) and the value the settings for the ephemeris settings from which the state function \(\mathbf{x}(t_{i})\) is created
frame_origin (str, default="SSB") – Origin of frame in which ephemeris data is defined.
frame_orientation (str, default="ECLIPJ2000") – Orientation of frame in which ephemeris data is defined.
default_ephemeris_settings (EphemerisSettings, default = None) – Settings to create a default ephemeris model that is use when the multi-arc ephemeris is queried at an epoch at which none of the arcs are valid

Returns:

Instance of the EphemerisSettings class with the required settings

Return type:

EphemerisSettings

Classes¶

`EphemerisSettings`	Base class for providing settings for ephemeris model.
`ScaledEphemerisSettings`	Class for defining settings from scaling existing ephemeris settings.
`DirectSpiceEphemerisSettings`	Class for defining settings of an ephemeris linked directly to Spice.
`InterpolatedSpiceEphemerisSettings`	Class for defining settings of an ephemeris interpolated from Spice data.
`ApproximateJplEphemerisSettings`	Class for creating settings of approximate ephemeris for major planets.
`ConstantEphemerisSettings`	Class for defining settings of constant ephemerides.
`CustomEphemerisSettings`	Class for defining settings of a custom ephemeris.
`KeplerEphemerisSettings`	No documentation found.
`TabulatedEphemerisSettings`	Class for defining settings of ephemeris to be created from tabulated data.

class EphemerisSettings¶

Bases: pybind11_object

Base class for providing settings for ephemeris model.

Functional (base) class for settings of ephemeris models that require no information in addition to their type (and frame origin and orientation). Ephemeris model classes requiring additional information must be created using an object derived from this class.

property ephemeris_type¶

read-only

Type of ephemeris that is to be created.

Type:: EphemerisType

property frame_orientation¶

Orientation of frame in which ephemeris data is to be defined.

Type:: str

property frame_origin¶

Origin of frame in which ephemeris data is to be defined.

Type:: str

property make_multi_arc_ephemeris¶

Boolean denoting whether the ephemeris that is to be created is a multi-arc ephemeris. If this is set to true (default is false), the ephemeris settings object will be processed as though it were a multi_arc_ephemeris() object initialized with a single arc (with that single arc defined using this object). This is required when doing a multi-arc propagation/estimation (multi_arc()) in which the ephemeris of this body is to be reset.

Type:: bool

class ScaledEphemerisSettings¶

Bases: EphemerisSettings

Class for defining settings from scaling existing ephemeris settings.

EphemerisSettings derived class for a new ephemeris created from scaling an existing ephemeris settings object. It allows the user to apply a scaling factor to the resulting Cartesian states (for instance for an uncertainty analysis).

class DirectSpiceEphemerisSettings¶

Bases: EphemerisSettings

Class for defining settings of an ephemeris linked directly to Spice.

EphemerisSettings derived class for ephemeris which are directly linked to Spice.

property converge_light_time_aberration¶

read-only

Boolean defining whether to use single iteration or max. 3 iterations for calculating light time correction.

Type:: bool

property correct_for_light_time_aberration¶

read-only

Boolean defining whether to correct for light time in retrieved values (of observed state).

Type:: bool

property correct_for_stellar_aberration¶

read-only

Boolean defining whether to correct for stellar aberrations in retrieved values (of observed state).

Type:: bool

class InterpolatedSpiceEphemerisSettings¶

Bases: DirectSpiceEphemerisSettings

Class for defining settings of an ephemeris interpolated from Spice data.

DirectSpiceEphemerisSettings derived class for setting ephemerides to be created from interpolated Spice ephemeris data.

property final_time¶

read-only

Final time from which interpolated data from Spice should be created.

Type:: float

property initial_time¶

read-only

Initial time from which interpolated data from Spice should be created.

Type:: float

property time_step¶

read-only

Time step setting to be used for the state interpolation.

Type:: float

class ApproximateJplEphemerisSettings¶

Bases: EphemerisSettings

Class for creating settings of approximate ephemeris for major planets.

EphemerisSettings derived class for approximate ephemeris for major planets as implemented in ApproximateJplEphemerisSettings class and derived class (described in this document).

property body_name¶: No documentation found.

class ConstantEphemerisSettings¶

Bases: EphemerisSettings

Class for defining settings of constant ephemerides.

EphemerisSettings derived class for ephemerides producing a constant (time-independent) state.

class CustomEphemerisSettings¶

Bases: EphemerisSettings

Class for defining settings of a custom ephemeris.

EphemerisSettings derived class for ephemerides which represent an ideal Kepler orbit.

property get_custom_state_function¶: No documentation found.

class KeplerEphemerisSettings¶

Bases: EphemerisSettings

No documentation found.

property central_body_gravitational_parameter¶: No documentation found.

property epoch_of_initial_state¶: No documentation found.

property initial_state_in_keplerian_elements¶: No documentation found.

property root_finder_absolute_tolerance¶: No documentation found.

property root_finder_maximum_number_of_iterations¶: No documentation found.

class TabulatedEphemerisSettings¶

Bases: EphemerisSettings

Class for defining settings of ephemeris to be created from tabulated data.

EphemerisSettings derived class for ephemeris created from tabulated data. The provided data is interpolated into ephemerides.

property body_state_history¶

read-only

Dictionary of the discrete state history data from which ephemeris is to be created.

Type:: Dict[[float], numpy.ndarray[numpy.float64[6, 1]]]