Creation of celestial body settings

The usual workflow to create celestial body settings is composed of two subsequent steps, described separately:

Creating body settings
Customization of body settings

Warning

Body settings are not used in the propagation: they are only used to define the settings of the body objects, and are used to create Body objects, which are used during the propagation and contain the actual objects/functions performing the relevant calculations. This procedure is described in the separate page Creating and modifying the bodies.

Creating body settings

In most cases, the starting point for the creation of body settings will be the extraction of default settings. This prevents a user from having to manually define a variety of ‘typical’ models for solar-system bodies. The full list of default body settings is given at Default environment models, and can be retrieved as follows, using the get_default_body_settings() function:

Required Show/Hide

# import statements required
from tudatpy.kernel.numerical_simulation import environment_setup
from tudatpy.kernel.interface import spice

# load spice kernels
spice_interface.load_standard_kernels()

# define bodies in simulation
bodies_to_create = ["Sun", "Earth", "Moon", "Mars", "Jupiter"]

# create body settings dictionary
global_frame_origin = "SSB"
global_frame_orientation = "J2000"
body_settings = environment_setup.get_default_body_settings(
        bodies_to_create, global_frame_origin, global_frame_orientation)

where the global_frame_origin and global_frame_orientation define the reference frame in which state vectors stored in the environment during propagation are represented. In general, it is recommended to choose this as the most ‘intuitive’ frame origin for your propagation (e.g. SSB or Sun for solar system scale propagations, Earth for an Earth orbiter, Mars for a Martian mission, etc.). The frame_orientation may be omitted altogether, in which case the default ECLIPJ2000 is used. The above function creates an object of type BodyListSettings, which stores the settings for all bodies (as a list of tudatpy.numerical_simulation.environment_setup.BodySettings objects)

Note that the frame origin definitions is distinct from the center of propagation that you can define for the propagation of translational dynamics (see translational() function, and the Translational Dynamics page). For more information about this distinction, and the use of these reference frames in general, see Frames in the Environment.

In addition to the above method of creating default bodies, we offer an alternative which is more computationally efficient, at the expense of higher RAM usage and a more limited time interval in which the environment is valid. Such an approach is typically only used when computational speed is very important, and is described in more detail here.

Finally, in case you want to initialize body settings without any default settings, the body_settings in the above script can also be created manually as:

Required Show/Hide

# import statements required
from tudatpy.kernel.numerical_simulation import environment_setup
from tudatpy.kernel.interface import spice

# load spice kernels
spice_interface.load_standard_kernels()

# Manually create (empty) settings for a list of bodies, with origin/orientation Earth/J2000
body_settings = environment_setup.BodyListSettings( frame_origin = "Earth", frame_orientation = "J2000" )

where the frame origin and orientation have been defined manually as “Earth” and “J2000”, respectively.

Customization of body settings

Although the default body settings are often very useful, there are various cases where a user will want to override these default settings, or where these default settings cannot be use. The manner in which to overrride the default settings can be divided into three categories:

Modifying the type of the default model that is used. Example: using a spherical harmonic gravity field instead of a point-mass gravity field
Modifying the specific parameters inside a given default model setting. Example: modifying the value of the gravitational parameter used for the given default model
Created body settings from scratch, without any use of the default settings.

Below we show each manner to modify the settings with a representative example.

Overriding existing settings objects

Default settings may be overridden as follows:

Required Show/Hide

# import statements required
from tudatpy.kernel.numerical_simulation import environment_setup
from tudatpy.kernel.interface import spice

# load spice kernels
spice_interface.load_standard_kernels()

# define bodies in simulation
bodies_to_create = ["Sun", "Earth", "Moon", "Mars", "Jupiter"]

# create body settings dictionary
global_frame_origin = "SSB"
global_frame_orientation = "J2000"
body_settings = environment_setup.get_default_body_settings(
        bodies_to_create, global_frame_origin, global_frame_orientation)

# Modify the gravity field of the Sun
body_settings.get( "Sun" ).gravity_field_settings = 
    environment_setup.gravity_field.point_mass( 1.32712440042E20 )

// required include statements
#include <tudat/simulation/simulation.h>

// required using-declarations
using tudat::simulation_setup;
using tudat;

The above works equally well if the existing environment model settings are empty. Where the above example creates a new gravity field settings object, and overrides the default setting for the Sun’s gravity field with this new object. The new settings define a point-mass gravity field with a gravitational parameter of 1.32712440042 \(\cdot\) 10 ²⁰ m ³ / s ².

Modifying parameters in existing settings objects

Default settings may be overridden as follows:

Required Show/Hide

# import statements required
from tudatpy.kernel.numerical_simulation import environment_setup
from tudatpy.kernel.interface import spice

# load spice kernels
spice_interface.load_standard_kernels()

# define bodies in simulation
bodies_to_create = ["Sun", "Earth", "Moon", "Mars", "Jupiter"]

# create body settings dictionary
global_frame_origin = "SSB"
global_frame_orientation = "J2000"
body_settings = environment_setup.get_default_body_settings(
        bodies_to_create, global_frame_origin, global_frame_orientation)

# Modify the gravity field of the Sun
body_settings.get( "Sun" ).gravity_field_settings.gravitational_parameter = 1.32712440042E20

// required include statements
#include <tudat/simulation/simulation.h>

// required using-declarations
using tudat::simulation_setup;
using tudat;

Where the value of the gravitational parameter in the Sun’s gravity field is changed to 1.32712440042 \(\cdot\) 10 ²⁰ m ³ / s ². Functionally, this example is identical to the previous one, but it permits different kinds of modifications to be made. It allows only a single property of the environment model to be modified, while in the previous example, it is required that all properties are redefined by the user (for the point-mass gravity field, which has only one property in the settings, this point is moot). The present example therefor allows for more ‘fine-grained’ control of the settings, but limits the user to a modifying the properties of the settings, without providing the flexibility to modify the type of settings (which is allowed in the previous example).

To understand how to know the syntax of the above example, but for different types of environment models:

The type of the gravity_field_settings attribute of the BodySettings is tudatpy.numerical_simulation.environment_setup.gravity_field.GravityFieldSettings, as shown in the API documentation.
The gravitational_parameter attribute of the GravityFieldSettings is a float, and can be modified by a user, as shown in the API documentation.
So: provided that the body settings for the Sun has any gravity field settings, the above will work. If it does not, you should first create such settings (see Overriding existing settings objects)

Below is a slightly more involved example, which does not use a property of the GravityFieldSettings base class, but rather the SphericalHarmonicsGravityFieldSettings derived class. Therefore, the example below will only work if the current gravity field settings for the Earth already define a spherical harmonic gravity field:

Required Show/Hide

# import statements required
from tudatpy.kernel.numerical_simulation import environment_setup
from tudatpy.kernel.interface import spice

# load spice kernels
spice_interface.load_standard_kernels()

# define bodies in simulation
bodies_to_create = ["Sun", "Earth", "Moon", "Mars", "Jupiter"]

# create body settings dictionary
global_frame_origin = "SSB"
global_frame_orientation = "J2000"
body_settings = environment_setup.get_default_body_settings(
        bodies_to_create, global_frame_origin, global_frame_orientation)

# Get the current cosine coefficients of the Earth
cosine_coefficients = body_settings.get('Earth').gravity_field_settings.normalized_cosine_coefficients

# Modify the C_{2,0} coefficient of the Earth
cosine_coefficients[ 2, 0 ] = cosine_coefficients[ 2, 0 ] + 1.0E-12

# Reset the coefficients of the Earth
body_settings.get('Earth').gravity_field_settings.normalized_cosine_coefficients = cosine_coefficients

// required include statements
#include <tudat/simulation/simulation.h>

// required using-declarations
using tudat::simulation_setup;
using tudat;

Here, we extracted, modified, and then reset the normalized_cosine_coefficients property of the SphericalHarmonicsGravityFieldSettings.

Creating a new settings object

Some bodies do not have any default settings, and in some cases all default settings may be different from what a user desired. In such cases, manually creating the settings can also be done.

Required Show/Hide

# import statements required
from tudatpy.kernel.numerical_simulation import environment_setup
from tudatpy.kernel.interface import spice

# load spice kernels
spice_interface.load_standard_kernels()

# define bodies in simulation
bodies_to_create = ["Sun", "Earth", "Moon", "Mars", "Jupiter"]

# create body settings dictionary
global_frame_origin = "SSB"
global_frame_orientation = "J2000"
body_settings = environment_setup.get_default_body_settings(
        bodies_to_create, global_frame_origin, global_frame_orientation)

# Add empty body settings for body Oumuamua, and add to existing list of settings 
body_settings.add_empty_settings( "Oumuamua" )

# Manually create and assign environment model settings to new body settings
body_settings.get( "Oumuamua" ).ephemeris_settings = ...	
body_settings.get( "Oumuamua" ).gravity_field_settings = ...
body_settings.get( "Oumuamua" ).rotation_model_settings = ...

// required include statements
#include <tudat/simulation/simulation.h>

// required using-declarations
using tudat::simulation_setup;
using tudat;

In this example, empty body settings for a body ‘Oumuamua’ are first added. When adding such settings, no properties whatsoever are assigned to the body, the only thing that it assigned to it is its existence, but it has no ephemeris, gravity field, etc. Each environment model setting has to be manually added.

The above setup is also one that is typically used for artificial bodies, for which no default settings are currently implemented. Even though the type and settings of a vehicle’s constituent environment (and system) models are typically very different from a natural body, the manner in which such a body is set up is not fundamentally different in Tudat. See below for a representative example:

Required Show/Hide

# import statements required
from tudatpy.kernel.numerical_simulation import environment_setup
from tudatpy.kernel.interface import spice

# load spice kernels
spice_interface.load_standard_kernels()

# define bodies in simulation
bodies_to_create = ["Sun", "Earth", "Moon", "Mars", "Jupiter"]

# create body settings dictionary
global_frame_origin = "SSB"
global_frame_orientation = "J2000"
body_settings = environment_setup.get_default_body_settings(
        bodies_to_create, global_frame_origin, global_frame_orientation)

# Add empty body settings for body Oumuamua, and add to existing list of settings 
body_settings.add_empty_settings( "Spacecraft" )

# Manually create and assign environment model settings to new body settings
body_settings.get( "Spacecraft" ).radiation_pressure_settings[ "Sun" ] = ...
body_settings.get( "Spacecraft" ).aerodynamic_coefficient_settings = ...
body_settings.get( "Spacecraft" ).constant_mass = 500.0;	

// required include statements
#include <tudat/simulation/simulation.h>

// required using-declarations
using tudat::simulation_setup;
using tudat;

In the above code snippet, you may notice two seemingly different aspects from the other environment models:

The settings for the radiation pressure interface, which has Sun as key, unlike any of the other environment models. This is due to the fact that a body may have radiation pressure settings for any number of source bodies
The body mass, which is set directly as a value (here 500 kg). This is due to the fact that the mass is stored in the Body object directly as a value (or a function, if it is time-variable) rather than as a dedicated environment model class