1.2. Available Settings for the Environment Models

Here, we will provide a full list of the available properties of the BodySettings object. Each type of environment model has one base class to define settings for the creation of the model). Often, a specific derived class is implemented for a specific environment model of a given class, in which any additional information that may be needed can be provided. For instance, when defining a gravity field model, one can simply use:

bodySettings[ "Earth" ]->gravityFieldSettings = std::make_shared< GravityFieldSettings >( central_spice );

if you want to use a central gravity field with the gravitational parameter taken from Spice: no information is needed except the type of gravity field model that is created. On the other hand, if you want to use a spherical harmonic gravity field, you need to specify additional parameters yourself, which is done by using the specific derived class:

bodySettings[ "Earth" ]->gravityFieldSettings = std::make_shared< SphericalHarmonicsGravityFieldSettings >(
   gravitationalParameter, referenceRadius, normalizedCosineCoefficients, normalizedSineCoefficients, associatedReferenceFrame );

To find out which input arguments must be provided to create a specific settings class, have a look at the documentation in the code (written above the code for the constructor of the settings class you are interested in). Below, we give examples of each type of environment model setting.

The full list of available environment model settings is described below.

1.2.1. Atmosphere model

class AtmosphereModel

Base class for all atmosphere models. This model is constructed using the settings classes described below.

class AtmosphereSettings

The base class for atmosphere settings. Models currently available through the BodySettings architecture are (with examples when defining settings for Earth):

class ExponentialAtmosphereSettings

Simple atmosphere model independent of time, latitude and longitude based on an exponentially decaying density profile with a constant temperature.

bodySettings[ "Earth" ]->atmosphereSettings = std::make_shared< ExponentialAtmosphereSettings >( 7.2E3, 290.0, 1.225, 287.06 );

for an exponential atmosphere with a scale height of 7200 m, a constant temperature of 290 K, a density at 0 m altitude of 1.225 kg/m^3 and a specific gas constant of 287.06 J/(kg K).

If you want to model the exponential atmosphere for Earth or Mars, you can also simply input aerodynamics::earth or aerodynamics::mars to load the default settings, which are defined in the table below.

Property	Earth	Mars	Units
Scale Height	7.2	1.11	km
Density at Zero Altitude	1.225	0.02	kg/m \({}^3\)
Constant Temperature	246.0	215.0	K
Specific Gas Constant	287.0	197.0	J/kg/K
Ratio of Specific Heats	1.4	1.3	–

References for the values above are:

• Earth: Lecture notes, Rocket Motion by Prof. Ir. B.A.C. Ambrosius, November 2009

• Mars: Spohn, T., Breuer, D., and Johnson, T., Eds., Encyclopedia of the Solar System, 3rd ed. Elsevier, 2014

class TabulatedAtmosphereSettings

Due to the extensive customization available for the tabulated atmosphere, you can find the settings for this class in a separate page: Tabulated Atmosphere Settings.

class CustomConstantTemperatureAtmosphereSettings

With this class, you can define your own constant temperature atmosphere, which computes the atmospheric properties based on an input function. For instance, one can link a function to the settings as such:

// Outside main
double customDensityFunction( const double altitude, const double longitude, const double latitude, const double time )
{
   // Return a linear combination of the input values
   return 0.5 * altitude + 0.25 * longitude + 0.15 * latitude + 0.1 * time;
}

int main( )
{
  // ...

  // Define atmosphere settings
  double constantTemperature = 250.0;
  double specificGasConstant = 300.0;
  double ratioOfSpecificHeats = 1.4;
  bodySettings[ "Earth" ]->atmosphereSettings = std::make_shared< CustomConstantTemperatureAtmosphereSettings >( &customDensityFunction, constantTemperature, specificGasConstant, ratioOfSpecificHeats );

  // ...
}

As shown in the example above, the user-defined function, in this case customDensityFunction, is required to have those inputs, and in that specific order. The value of pressure is computed by assuming hydrostatic equilibrium, whereas temperature, gas constant and the ratio of specific heats are assumed to be constant.

Tip

Note that, by using std::bind, you can have more inputs than the ones in customDensityFunction. However, keep in mind that std::bind only allows up to 9 inputs.

NRLMSISE-00

This can be used to select the NRLMSISE-00 atmosphere model. To use this model, the USE_NRLMSISE flag in your top-level CMakeLists must be set to true. No derived class of AtmosphereSettings base class required, the model can be created by passing nrlmsise00 as argument to base class constructor.

bodySettings[ "Earth" ]->atmosphereSettings = std::make_shared< AtmosphereSettings >( nrlmsise00 );

class CustomWindModelSettings

Custom wind model which can be used to retrieve a wind vector. This wind vector is in the body-fixed, body-centered reference frame.

bodySettings[ "Earth" ]->atmosphereSettings = std::make_shared< CustomWindModelSettings >(  windFunction )

where windFunction is a std::function with inputs; altitude, longitude, latitude and time.

1.2.2. Ephemeris model

class Ephemeris

Base class for the ephemeris. It is constructed using one of the settings classes below.

class EphemerisSettings

Base class for the ephemeris settings. Models currently available through the BodySettings architecture and set by their respective derived classes are:

class ApproximatePlanetPositionSettings

Highly simplified model of ephemerides of major Solar system bodies (model described here). Both a three-dimensional, and circular coplanar approximation may be used.

bodySettings[ "Jupiter" ]->ephemerisSettings = std::make_shared< ApproximatePlanetPositionSettings >( ephemerides::ApproximatePlanetPositionsBase::jupiter, false );

where the first constructor argument is taken from the enum in approximatePlanetPositionsBase.h, and the second argument (false) denotes that the circular coplanar approximation is not made.

class DirectSpiceEphermerisSettings

Ephemeris retrieved directly using External Libraries: SPICE.

std::string frameOrigin = "SSB";
std::string frameOrientation = "J2000";
bodySettings[ "Jupiter" ]->ephemerisSettings = std::make_shared< DirectSpiceEphemerisSettings >( frameOrigin, frameOrientation );

creating a barycentric (SSB) ephemeris with axes along J2000, with data directly from spice.

class InterpolatedSpiceEphemerisSettings

Using this option the state of the body is retrieved at regular intervals, and used to create an interpolator, before setting up environment. This has the advantage of only requiring calls to Spice outside of the propagation inner loop, reducing computation time. However, it has the downside of begin applicable only during a limited time interval.

double initialTime = 0.0;
double finalTime = 1.0E8;
double timeStep = 3600.0;
std::string frameOrigin = "SSB";
std::string frameOrientation = "J2000";
bodySettings[ "Jupiter" ]->ephemerisSettings = std::make_shared< InterpolatedSpiceEphemerisSettings >(
    initialTime, finalTime, timeStep, frameOrigin, frameOrientation );

creating a barycentric (SSB) ephemeris with axes along J2000, with data retrieved from Spice at 3600 s intervals between t=0 and t=1.0E8, using a 6th order Lagrange interpolator. Settings for the interpolator (discussed here, can be added as a sixth argument if you wish to use a different interpolation method)

class TabulatedEphemerisSettings

Ephemeris created directly by interpolating user-specified states as a function of time.

std::map< double, Eigen::Vector6d > bodyStateHistory ...
std::string frameOrigin = "SSB";
std::string frameOrientation = "J2000";
bodySettings[ "Jupiter" ]->ephemerisSettings = std::make_shared< TabulatedEphemerisSettings >(
    bodyStateHistory, frameOrigin, frameOrientation );

creating an ephemeris interpolated (with 6th order Lagrange interpolation) from the data in bodyStateHistory, which contains the Cartesian state (w.r.t. SSB; axes along J2000) for a given number of times (map keys, valid time range between first and last time in this map).

class KeplerEphemerisSettings

Ephemeris modelled as being a perfect Kepler orbit.

Eigen::Vector6d initialStateInKeplerianElements = ...
double epochOfInitialState = ...
double centralBodyGravitationalParameter = ...
std::string frameOrigin = "SSB";
std::string frameOrientation = "J2000";
bodySettings[ "Jupiter" ]->ephemerisSettings = std::make_shared< KeplerEphemerisSettings >(
    initialStateInKeplerianElements, epochOfInitialState, centralBodyGravitationalParameter, frameOrigin, frameOrientation );

creating a Kepler orbit as ephemeris using the given kepler elements and associated initial time and gravitational parameter. See Frame/State Transformations for more details on orbital elements in Tudat.

class ConstantEphemerisSettings

Ephemeris modelled as being independent of time.

Eigen::Vector6d constantCartesianState = ...
std::string frameOrigin = "SSB";
std::string frameOrientation = "J2000";
bodySettings[ "Jupiter" ]->ephemerisSettings = std::make_shared< ConstantEphemerisSettings >(
    constantCartesianState, frameOrigin, frameOrientation );

Multi-arc ephemeris

An ephemeris model (for translational state) that allows the body’s state to be defined by distinct ephemeris models over different arcs. Class is implemented to support multi-arc propagation/estimation. No derived class of EphemerisSettings base class required, the created ephemeris can be made multi-arc by using the resetMakeMultiArcEphemeris function of the EphemerisSettings class. The resulting Ephemeris object will then be MultiArcEphemeris (with the same ephemeris model for each arc when created, according to the settings in the EphemerisSettings object)

bodySettings[ "Earth" ]->ephemerisSettings-> resetMakeMultiArcEphemeris( true );

class CustomEphemerisSettings

Allows user to provide arbitrary function as ephemeris model.

std::shared_ptr< EphemerisSettings > customEphemerisSettings =
             std::make_shared< CustomEphemerisSettings >(
                customBoostFunction, frameOrigin, frameOrientation );

1.2.3. Gravity field model

class GravityFieldModel

Base class for the gravity field model, set using the settings classes described below.

class GravityFieldSettings

Base class for the gravity field settings. Models currently available through the BodySettings architecture can be called by the following:

class CentralGravityFieldSettings

Point-mass gravity field model, with user-defined gravitational parameter.

double gravitationalParameter = ...
bodySettings[ "Earth" ]->gravityFieldSettings = std::make_shared< CentralGravityFieldSettings >( gravitationalParameter );

Point-mass gravity field model from Spice

Point-mass gravity field model, with gravitational parameter from Spice. No derived class of GravityFieldSettings base class required, created by passing central_spice as argument to base class constructor.

bodySettings[ "Earth" ]->gravityFieldSettings = std::make_shared< GravityFieldSettings >( central_spice );

class SphericalHarmonicsGravityFieldSettings

Gravity field model as a spherical harmonic expansion.

double gravitationalParameter = ...
double referenceRadius = ...
Eigen::MatrixXd normalizedCosineCoefficients =  // NOTE: entry (i,j) denotes coefficient at degree i and order j
Eigen::MatrixXd normalizedSineCoefficients =  // NOTE: entry (i,j) denotes coefficient at degree i and order j
std::string associatedReferenceFrame = ...
bodySettings[ "Earth" ]->gravityFieldSettings = std::make_shared< SphericalHarmonicsGravityFieldSettings >(
   gravitationalParameter, referenceRadius, normalizedCosineCoefficients, normalizedSineCoefficients, associatedReferenceFrame );

The associatedReferenceFrame reference frame must presently be the same frame as the target frame of the body’s rotation model (see below). It represents the frame to which the spherical harmonic field is fixed.

Warning

Spherical harmonic coefficients used for this environment model must ALWAYS be fully normalized

1.2.4. Rotational model

class RotationalEphemeris

Base class for the rotational ephemeris model, set using the settings classes described below.

class RotationModelSettings

Base class for the rotational model settings. Models currently available through the BodySettings architecture are:

class SimpleRotationModelSettings

Rotation model with constant orientation of the rotation axis, and constant rotation rate about local z-axis.

Eigen::Quaterniond initialOrientation = ...
double initialTime = ...
double rotationRate = ...
std::string originalFrame = "J2000";
std::string targetFrame = "IAU_Earth";
bodySettings[ "Earth" ]->rotationModelSettings = std::make_shared< SimpleRotationModelSettings >(
    originalFrame, targetFrame , initialOrientation, initialTime, rotationRate );

where the rotation from originalFrame to targetFrame at initialTime is given by the quaternion initialOrientation. This is mapped to other times using the rotation rate rotationRate.

Spice Rotation model

Rotation model directly obtained from Spice. No derived class of RotationModelSettings base class required, created by passing spice_rotation_model as argument to base class constructor.

std::string originalFrame = "J2000";
std::string targetFrame = "IAU_Earth";
bodySettings[ "Earth" ]->rotationModelSettings = std::make_shared< RotationModelSettings >( spice_rotation_model, originalFrame, targetFrame );

class GcrsToItrsRotationModelSettings

High-accuracy rotation model of the Earth, according to the IERS 2010 Conventions. This class has various options to deviate from the default settings, here we only show the main options (typical applications will use default):

IAUConventions precessionNutationTheory = iau_2006;
std::string originalFrame = "J2000";
bodySettings[ "Earth" ]->rotationModelSettings = boost::make_shared< GcrsToItrsRotationModelSettings >(
   precessionNutationTheory, originalFrame );

Note that for this model the original frame must be J2000, ECLIPJ2000 or GCRS. The precession-nutation theory may be iau_2000a, iau_2000b or iau_2006, as implemented in the SOFA toolbox. Alternative options to modify (not shown above) include the EOP correction file, input time scale, short period UT1 and polar motion variations. Please see the Dosygen documentation for details.

Tabulated RotationalEphemeris model

Rotation model obtained from an interpolator, with dependent variable a Eigen::VectorXd of size 7: the four entries (w,x,y,z) of the quaternion from the target frame to the base frame, and body’s angular velocity vector, expressed in its body-fixed frame . Currently the settings interface is not yet implemented but the functionality is implemented in TabulatedRotationalEphemeris. The tabulated rotational ephemeris can be implemented as follows:

// Create tabulated rotational model
std::shared_ptr< TabulatedRotationalEphemeris< double, double > > tabulatedEphemeris =
        std::make_shared< TabulatedRotationalEphemeris<  double, double > >( rotationInterpolator );

Constant Rotation Model

Rotation model with a constant value for the rotation. Currently the settings interface is not yet implemented.

1.2.5. Body shape model

class BodyShapeModel

Base class for body shape models. It is constructed using the settings described below.

class BodyShapeSettings

Base class for the body shape settings. Models currently available through the BodySettings architecture are:

class SphericalBodyShapeSettings

Model defining a body shape as a perfect sphere, with the sphere radius provided by the user.

double bodyRadius = 6378.0E3;
bodySettings[ "Earth" ]->shapeModelSettings = std::make_shared< SphericalBodyShapeSettings >( bodyRadius );

Spherical shape from Spice

Model defining a body shape as a perfect sphere, with the sphere radius retrieved from Spice. No derived class of BodyShapeSettings base class required, created by passing spherical_spice as argument to base class constructor.

bodySettings[ "Earth" ]->shapeModelSettings = std::make_shared< BodyShapeSettings >( spherical_spice );

class OblateSphericalBodyShapeSettings

Model defining a body shape as a flattened sphere, with the equatorial radius and flattening provided by the user.

double bodyRadius = 6378.0E3;
double bodyFlattening = 1.0 / 300.0;
bodySettings[ "Earth" ]->shapeModelSettings = std::make_shared< OblateSphericalBodyShapeSettings >( bodyRadius, bodyFlattening );

1.2.6. Radiation pressure interface

class RadiationPressureInterface

Class containing the properties of a solar radiation pressure acceleration model. It is constructed using the settings classes below.

class RadiationPressureInterfaceSettings

Base class for the radiation pressure interface settings. A separate model can be used for different bodies emitting radiation (key values of radiationPressureSettings) Models currently available through the BodySettings architecture are:

class CannonBallRadiationPressureInterfaceSettings

Properties for a cannonball radiation pressure model, i.e. effective force colinear with vector from source to target.

std::string sourceBody = "Sun";
double area = 20.0;
const double radiationPressureCoefficient = 1.2;
std::vector< std::string > occultingBodies;
occultingBodies.push_back( "Earth" );
bodySettings[ "TestVehicle" ]->radiationPressureSettings[ sourceBody ] = std::make_shared< CannonBallRadiationPressureInterfaceSettings >(
    sourceBody, area, radiationPressureCoefficient, occultingBodies );

Creating cannonball radiation pressure settings for radiation due to the Sun, acting on the “TestVehicle” body, where the occultations due to the Earth are taken into account.

Note

Occultations by multiple bodies are not yet supported. Please contact the Tudat suppport team if you wish to use multiple occultations.

class PanelledRadiationPressureInterfaceSettings

Properties for a panelled radiation pressure model, i.e. solar radiation pressure force derived from a so-called boxes-and-wings model.

 std::string sourceBody = "Sun";
 std::vector< double > emissivities = { 0.1, 0.0, 0.1, 0.1 };
 std::vector< double > areas = { 4.0, 6.0, 2.3, 2.3 };
 std::vector< double > diffusionCoefficients = { 0.46, 0.06, 0.46, 0.46 };
 std::vector< std::string > occultingBodies;
 occultingBodies.push_back( "Earth" );

 std::vector< std::function< Eigen::Vector3d( const double ) > > panelSurfaceNormals;
panelSurfaceNormals.push_back( [ = ]( const double ){ return Eigen::Vector3d::UnitZ( ); } );
panelSurfaceNormals.push_back( [ = ]( const double ){ return - Eigen::Vector3d::UnitZ( ); } );
panelSurfaceNormals.push_back( [ = ]( const double ){ return Eigen::Vector3d::UnitX( ); } );
panelSurfaceNormals.push_back( [ = ]( const double ){ return - Eigen::Vector3d::UnitX( ); } );

 bodySettings[ "Vehicle" ]->radiationPressureSettings[ sourceBody ] = std::make_shared< PanelledRadiationPressureInterfaceSettings >(
     sourceBody, emissivities, areas, diffusionCoefficients, surfaceNormalsInBodyFixedFrameFunctions, occultingBodies );

Creating panelled radiation pressure settings for radiation due to the Sun, acting on the “Vehicle” body, from the following input variables:

• Name of the source body of the radiation pressure.

• Vector containing the emissivities of the different panels.

• Vector containing the areas of the panels.

• Vector containing the diffusion coefficient of each panel.

• Vector containing the functions that return the normals of the panels surfaces, in body-fixed reference frame.

• Vector with the names of the occulting bodies.

class SolarSailRadiationInterfaceSettings

Properties for a solar sail radiation pressure model, i.e. solar radiation pressure force derived from a solar sail characteristics and orientation.

std::string sourceBody = "Sun";
double area = 2.0;
std::function< double( const double ) > coneAngle = [ = ]( const double ){ return 0.25; };
std::function< double( const double ) > clockAngle = [ =  ]( const double ){ return 0.2; };
double frontEmissivityCoefficient = 0.4;
double backEmissivityCoefficient = 0.4;
double frontLambertianCoefficient = 0.4;
double backLambertianCoefficient = 0.4;
double reflectivityCoefficient = 0.3;
double specularReflectionCoefficient = 1.0;
std::vector< std::string > occultingBodies; occultingBodies.push_back( "Earth" );
std::string& centralBody = "Earth";

bodySettings[ "Vehicle" ]->radiationPressureSettings[ sourceBody ] = std::make_shared< SolarSailRadiationInterfaceSettings >(
    sourceBody, area, coneAngle, clockAngle, frontEmissivityCoefficient, backEmissivityCoefficient,
    frontLambertianCoefficient, backLambertianCoefficient, reflectivityCoefficient, specularReflectionCoefficient, occultingBodies, centralBody );

Creating solar sail radiation pressure settings for radiation due to the Sun, acting on the “Vehicle” body, where the occultations due to the Earth are taken into account. The input variables for the solar sail radiation pressure settings are:

• Name of the radiation pressure source body.

• Area of the solar sail.

• Function returning the cone angle of the solar sail as a function of time (in the above example, the cone angle function is constant).

• Function returning the clock angle of the solar sail as a function of time (in the above example, the clock angle function is constant).

• Emissivity coefficient of the front face of the solar sail.

• Emissivity coefficient of the back face of the solar sail.

• Lambertian coefficient of the front face of the solar sail.

• Lambertian coefficient of the back face of the solar sail.

• Reflectvity coefficient of the solar sail.

• Specular reflection coefficient of the solar sail.

• Vector with the names of the occulting bodies.

1.2.7. Aerodynamic coefficient interface

class AerodynamicCoefficientInterface

Base class containing the aerodynamic coefficient interface set by the settings classes below.

class AerodynamicCoefficientSettings

Base class for the aerodynamic coefficient settings. Models currently available through the BodySettings architecture are:

class ConstantAerodynamicCoefficientSettings

Settings for constant (not a function of any independent variables) aerodynamic coefficients.

double referenceArea = 20.0;
Eigen::Vector3d constantCoefficients;
constantCoefficients( 0 ) = 1.5;
constantCoefficients( 2 ) = 0.3;
bodySettings[ "TestVehicle" ]->aerodynamicCoefficientSettings = std::make_shared< ConstantAerodynamicCoefficientSettings >(
    referenceArea, constantCoefficients, true, true );

For constant drag coefficient of 1.5 and lift coefficient of 0.3.

class TabulatedAerodynamicCoefficientSettings

Settings for tabulated aerodynamic coefficients as a function of given independent variables. These tables can be defined either manually or loaded from a file, as discussed in more detail here. Coefficients can be defined as a function of angle of sideslip, angle of attack, Mach number or altitude. If you simulation requires any other dependencies for the coefficients, please open an issue on Github requesting feature.

Local Inclination methods

Settings for aerodynamic coefficients computed internally using a shape model of the vehicle, valid for hypersonic Mach numbers. Currently, this type of aerodynamic coefficients can only be set manually in the Body object directly.

1.2.8. Time-variations of the gravity field

class GravityFieldVariations

Virtual base class for spherical harmonic gravity field variations. Constructed using the settings classes below.

class GravityFieldVariationSettings

Base class for the gravity field variation settings. Any number of gravity field variations may be used (hence the use of a vector). NOTE: You can only use gravity field variations for bodies where you have defined a spherical harmonic gravity field (through the use of SphericalHarmonicsGravityFieldSettings). Models currently available through the BodySettings architecture are:

class BasicSolidBodyGravityFieldVariationSettings

Tidal variation of the gravity field using first-order tidal theory.

class TabulatedGravityFieldVariationSettings

Variations in spherical harmonic coefficients tabulated as a function of time.