`atmosphere`¶

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

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

The following code block gives an overview of the steps to define, create, and extract an atmosphere model, for the specific example of exponential atmosphere drag (\(\rho_{0}=1.225\) kg/m³, \(H=7200\) m)

from tudatpy.dynamics import environment_setup

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

# Modify atmosphere model settings (base class type AtmosphereSettings)
body_settings.get( 'Earth' ).atmosphere_settings = environment_setup.atmosphere.exponential(
    scale_height = 7200.0,
    surface_density = 1.225 )

# Create bodies
bodies = environment_setup.create_system_of_bodies(body_settings)

# Extract atmosphere model (base class type AtmosphereModel) from Earth
earth_atmosphere_model = bodies.get( 'Earth' ).atmosphere_model

As a property of the atmosphere model, Tudat allows a wind model to be defined. In the absence of a wind model, the atmosphere is assumed to co-rotate with the central body. Specifically, the wind velocity in the central-body fixed frame is exactly \(\mathbf{0}\) by default. Settings for a wind model to deviate from this are added to the atmosphere settings through the wind_settings attribute (of type WindModelSettings). Several functions in this submodule allow an object of this type to be created.

The atmospheric properties of a body are used in a number of Tudat models, but the primary impact on a numerical propagation/estimation is through the impact of atmospheric density \(\rho\), which is used by the aerodynamic() acceleration model and aerodynamic() torque model.

Functions¶

`empty_wind_model`([include_corotation])	Function for creating empty wind model settings.
`constant_wind_model`(wind_velocity, 1]], ...)	Function for creating wind model settings with constant wind velocity.
`custom_wind_model`(wind_function, ...)	Function for creating wind model settings with custom wind velocity.
`coma_wind_model`(dataset_collection, ...)	Function for creating coma wind model settings.
`exponential_predefined`(body_name)	Function for creating atmospheric model settings from pre-defined exponential model.
`exponential`(scale_height, surface_density[, ...])	Function for creating atmospheric model settings from fully parametrized exponential model.
`nrlmsise00`([space_weather_file, ...])	Function for creating NRLMSISE-00 atmospheric model settings.
`tabulated`(atmosphere_data_file, ...)
`us76`()	Function for creating US76 standard atmosphere model settings.
`mars_dtm`()	Function for creating Mars DTM atmospheric settings.
`custom_constant_temperature`(...[, ...])	Function for creating atmospheric model settings from custom density profile.
`custom_four_dimensional_constant_temperature`(...)	Function for creating atmospheric model settings from custom density profile.
`scaled_by_constant`(...[, is_scaling_absolute])	Function for creating scaled atmospheric model settings.
`scaled_by_function`(...[, is_scaling_absolute])	Function for creating scaled atmospheric model settings.
`coma_model_from_poly_data`(poly_data, ...[, ...])	Function for creating coma atmosphere model settings from polynomial coefficients.
`coma_model_from_stokes_data`(stokes_data, ...)	Function for creating coma atmosphere model settings from Stokes coefficients.

empty_wind_model(include_corotation: bool = True) → tudatpy.kernel.dynamics.environment_setup.atmosphere.WindModelSettings¶

Function for creating empty wind model settings.

Function for settings object for an empty wind model (no physical wind, returns zero velocity). This is useful when you want to control atmospheric co-rotation behavior without specifying actual wind.

Parameters:: include_corotation (bool, default = True) – Boolean flag indicating whether atmospheric co-rotation should be included in aerodynamic computations.
Returns:: Instance of the WindModelSettings derived EmptyWindModelSettings class
Return type:: EmptyWindModelSettings

Examples

In this example, we create WindModelSettings, for an atmosphere without physical wind but with co-rotation disabled:

# Create empty wind model with co-rotation disabled
empty_wind = environment_setup.atmosphere.empty_wind_model(include_corotation=False)
# Apply to the atmosphere settings
body_settings.get("Earth").atmosphere_settings.wind_settings = empty_wind

constant_wind_model(wind_velocity: numpy.ndarray[numpy.float64[3, 1]], associated_reference_frame: tudatpy.kernel.dynamics.environment_setup.aerodynamic_coefficients.AerodynamicsReferenceFrames = <AerodynamicsReferenceFrames.vertical_frame: 1>, include_corotation: bool = True) → tudatpy.kernel.dynamics.environment_setup.atmosphere.WindModelSettings¶

Function for creating wind model settings with constant wind velocity.

Function for settings object, defining wind model entirely from constant wind velocity in a given reference frame.

Parameters:

wind_velocity (numpy.ndarray[numpy.float64[3, 1]]) – Constant wind velocity in the specified reference frame.
associated_reference_frame (dynamics.environment.AerodynamicsReferenceFrames, default = AerodynamicsReferenceFrames.vertical_frame) – Reference frame in which constant wind velocity is defined.
include_corotation (bool, default = True) – Boolean flag indicating whether atmospheric co-rotation should be included in aerodynamic computations.

Returns:

Instance of the WindModelSettings derived ConstantWindModelSettings class

Return type:

ConstantWindModelSettings

Examples

In this example, we create WindModelSettings, using a constant wind-velocity vector defined in a vertical aerodynamic reference frame:

# Define the wind in 3 directions in the vertical reference frame
wind_Xv = 3     # Meridional wind of +3 m/s (pointing to the North)
wind_Yv = 5     # Zonal wind of +5 m/s (pointing to the West)
wind_Zv = -11   # Vertical wind of +11 m/s (pointing out of the centre of the Earth)
# Create the constant wind settings
constant_wind = environment_setup.atmosphere.constant_wind_model(
  [wind_Xv, wind_Yv, wind_Zv],
  environment.AerodynamicsReferenceFrames.vertical_frame)
# Apply the constant wind settings to the Earth atmosphere settings
body_settings.get("Earth").atmosphere_settings.wind_settings = constant_wind

custom_wind_model(wind_function: Callable[[float | typing.SupportsIndex, float | typing.SupportsIndex, float | typing.SupportsIndex, float | typing.SupportsIndex], numpy.ndarray[numpy.float64[3, 1]]], associated_reference_frame: tudatpy.kernel.dynamics.environment_setup.aerodynamic_coefficients.AerodynamicsReferenceFrames = <AerodynamicsReferenceFrames.vertical_frame: 1>, include_corotation: bool = True) → tudatpy.kernel.dynamics.environment_setup.atmosphere.WindModelSettings¶

Function for creating wind model settings with custom wind velocity.

Function for settings object, defining wind model entirely from custom wind velocity function in a given reference frame. The custom wind velocity has to be given as a function of altitude, longitude, latitude and time.

Note

The longitude and latitude will be passed to the function in degree and not in radians. The altitude is in meters, and the time is a Julian date in seconds since J2000.

Parameters:

wind_velocity (callable[[float, float, float, float], numpy.ndarray[numpy.float64[3, 1]]]) – Custom wind velocity function (w.r.t. altitude, longitude, latitude and time) in the specified reference frame.
associated_reference_frame (dynamics.environment.AerodynamicsReferenceFrames, default = AerodynamicsReferenceFrames.vertical_frame) – Reference frame in which wind velocity is defined.
include_corotation (bool, default = True) – Boolean flag indicating whether atmospheric co-rotation should be included in aerodynamic computations.

Returns:

Instance of the WindModelSettings derived CustomWindModelSettings class

Return type:

CustomWindModelSettings

Examples

In this example, we create WindModelSettings, using a user-defined wind-velocity function (of altitude, longitude, latitude and time), defined in a vertical aerodynamic reference frame:

# Define the wind in 3 directions in the vertical reference frame
def wind_function(h, lon, lat, time):
    # Meridional wind (pointing North) depends on latitude [deg] and time [sec since J2000]
    wind_Xv = lat*10/time
    # Zonal wind (pointing West) only depends on the longitude [deg]
    wind_Yv = 5/lon
    # Vertical wind (pointing out of the centre of the Earth) only depends on the altitude [m]
    wind_Zv = 1000/h
    # Return the custom wind
    return [wind_Xv, wind_Yv, wind_Zv]
# Create the custom wind settings
custom_wind = environment_setup.atmosphere.custom_wind_model(
    wind_function,
    environment.AerodynamicsReferenceFrames.vertical_frame)
# Apply the custom wind settings to the Earth atmosphere settings
body_settings.get("Earth").atmosphere_settings.wind_settings = custom_wind

coma_wind_model(dataset_collection: tudatpy.kernel.data.coma_model.ComaWindDatasetCollection, requested_max_degree: int | SupportsIndex = -1, requested_max_order: int | SupportsIndex = -1, associated_reference_frame: tudatpy.kernel.dynamics.environment_setup.aerodynamic_coefficients.AerodynamicsReferenceFrames = <AerodynamicsReferenceFrames.vertical_frame: 1>, include_corotation: bool = True) → tudatpy.kernel.dynamics.environment_setup.atmosphere.WindModelSettings¶

Function for creating coma wind model settings.

Function for settings object, defining coma wind model from a dataset collection containing wind velocity components in a modified vertical frame. The wind model uses spherical harmonic expansion to compute wind velocities as a function of position.

Important

Data fitting requirement: The polynomial/Stokes coefficients for the wind model must be fitted from raw (untransformed) wind velocity values in m/s. Unlike the coma density model (which uses log2-transformed data), the wind model operates directly on the actual velocity values without any logarithmic transformation.

The wind velocity components are defined in a modified vertical frame:

X-axis: Meridional direction (in the meridian plane, pointing towards the North, aligned with central-body-fixed Z-axis direction)
Y-axis: Zonal direction (completes the right-handed frame, pointing towards the West)
Z-axis: Radial direction pointing OUTWARD from the comet nucleus center (away from origin)

Warning

The Z-axis direction is OPPOSITE to the standard Tudat vertical frame convention, where Z points inward along the gravity vector. For the coma wind model, positive Z points radially outward. This is critical for correct sign conventions when preparing input data.

Parameters:

dataset_collection (ComaWindDatasetCollection) – Collection containing wind component datasets in the modified vertical frame (either polynomial or Stokes coefficients).
requested_max_degree (int, default = -1) – Maximum spherical harmonic degree to use (-1 for automatic determination from data).
requested_max_order (int, default = -1) – Maximum spherical harmonic order to use (-1 for automatic determination from data).
associated_reference_frame (dynamics.environment.AerodynamicsReferenceFrames, default = AerodynamicsReferenceFrames.vertical_frame) – Reference frame in which the wind velocity is defined. For coma wind model, this uses a modified vertical frame with Z-axis pointing radially outward (away from nucleus), opposite to standard vertical frame.
include_corotation (bool, default = True) – Boolean flag indicating whether atmospheric co-rotation should be included in aerodynamic computations.

Returns:

Instance of the WindModelSettings derived ComaWindModelSettings class

Return type:

WindModelSettings

Examples

In this example, we create WindModelSettings for a coma wind model using a dataset collection:

# Create file processor from polynomial coefficient files
wind_processor = data.coma_model.coma_wind_file_processor(
    x_file_paths, y_file_paths, z_file_paths)

# Create dataset collection with Stokes coefficients
wind_datasets = wind_processor.create_coma_stokes_dataset(
    radii_m=[1000, 2000, 3000],
    sol_longitudes_deg=[0, 90, 180, 270])

# Create coma wind model settings in vertical frame
coma_wind = environment_setup.atmosphere.coma_wind_model(
    wind_datasets,
    requested_max_degree=10,
    requested_max_order=10,
    associated_reference_frame=environment.AerodynamicsReferenceFrames.vertical_frame,
    include_corotation=True)

# Apply to atmosphere settings
body_settings.get("Comet").atmosphere_settings.wind_settings = coma_wind

exponential_predefined(body_name: str) → tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings¶

Function for creating atmospheric model settings from pre-defined exponential model.

Function for settings object, defining atmosphere model from pre-defined exponential model. The pre-encoded properties are available for Earth and Mars, as can be seen on the table below. This function creates an instance of an AtmosphereSettings derived ExponentialAtmosphereSettings object.

Pre-defined exponential atmosphere model properties¶
Property	Earth	Mars	Units
Scale Height	7.2	11.1	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	–

Parameters:: body_name (str) – Body for which pre-defined model settings are to be loaded. Available bodies “Earth”, “Mars”.
Returns:: Instance of the AtmosphereSettings derived ExponentialAtmosphereSettings class
Return type:: ExponentialAtmosphereSettings

Examples

In this example, we create AtmosphereSettings for Mars, using the interface of the predefined exponential model, using pre-encoded values:

# Create atmosphere settings and add to body settings of "Mars"
body_settings.get("Mars").atmosphere_settings = environment_setup.atmosphere.exponential_predefined("Mars")

exponential(scale_height: float | SupportsIndex, surface_density: float | SupportsIndex, constant_temperature: float | SupportsIndex = 288.15, specific_gas_constant: float | SupportsIndex = 287.0, ratio_specific_heats: float | SupportsIndex = 1.4) → tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings¶

Function for creating atmospheric model settings from fully parametrized exponential model.

Function for settings object, defining exponential atmosphere model. The model is solely based on an exponentially decaying density profile with a constant temperature and composition (i.e. independent of time, latitude and longitude).

The user has access to a fully parametrized model, meaning that in addition to the required input parameters scale_height and surface_density (ground-level air density), the user can specify non-standard values for constant temperature, gas constant and specific heats ratio.

Parameters:

scale_height (float) – Scale height for density profile of atmosphere.
surface_density (float) – Atmospheric density at ground level.
constant_temperature (float, default = 288.15) – Constant atmospheric temperature.
specific_gas_constant (float, default = constants.SPECIFIC_GAS_CONSTANT_AIR) – Specific gas constant for (constant) atmospheric chemical composition.
ratio_specific_heats (float, default = 1.4) – Ratio of specific heats for (constant) atmospheric chemical composition.

Returns:

Instance of the AtmosphereSettings derived ExponentialAtmosphereSettings class

Return type:

ExponentialAtmosphereSettings

Examples

In this example, we create AtmosphereSettings for Earth, using the minimalist interface to the exponential model and taking parameters with classic values for Earth:

# define parameters of an invariant exponential atmosphere model
density_scale_height = 7.2E3
constant_temperature = 290
# create atmosphere settings and add to body settings of "Earth"
body_settings.get( "Earth" ).atmosphere_settings = environment_setup.atmosphere.exponential(
    density_scale_height, density_at_zero_altitude)

nrlmsise00(space_weather_file: str = '/home/docs/.tudat/resource/space_weather/sw19571001.txt', use_storm_conditions: bool = False, use_anomalous_oxygen: bool = True) → tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings¶

Function for creating NRLMSISE-00 atmospheric model settings.

Function for settings object, defining atmosphere model in accordance to the NRLMSISE-00 global reference model for Earth’s atmosphere. The NRLMSISE-00 model implementation uses the code from tudat-team/nrlmsise-00-cmake.

Parameters:

space_weather_file (str, default = get_space_weather_path() + ‘sw19571001.txt’) – File to be used for space weather characteristics as a function of time (e.g. F10.7, Kp, etc.). The file is typically taken from celestrak (note that the file in your resources path will not be the latest version of this file; download and replace your existing file if required). Documentation on the file is given on the celestrak website
use_storm_conditions (bool, default = false) – Boolean to define whether to use sub-daily Ap values when querying the NRLMSISE model, which is relevant under geomagnetic storm conditions (see NRLMSISE code, setting this variable to true sets switches[9] to -1, with resulting details of Ap values defined in ap_array).
use_anomalous_oxygen (bool, default = true) –
Boolean to define whether to use anomalous oxygen when querying the NRLMSISE model (if true, using gtd7d function, if false using gtd7 function in NRLMSISE code)

Returns:

Instance of the AtmosphereSettings class

Return type:

AtmosphereSettings

Examples

In this example, we create AtmosphereSettings for Earth, using the NRLMSISE-00 global reference model:

# create atmosphere settings and add to body settings of body "Earth"
body_settings.get( "Earth" ).atmosphere_settings = environment_setup.atmosphere.nrlmsise00()

tabulated(atmosphere_data_file: str, dependent_variable_names: list[tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereDependentVariables] = [<AtmosphereDependentVariables.tabulated_density: 0>, <AtmosphereDependentVariables.tabulated_pressure: 1>, <AtmosphereDependentVariables.tabulated_temperature: 2>], specific_gas_constant: float | typing.SupportsIndex = 287.0, ratio_of_specific_heats: float | typing.SupportsIndex = 1.4) → tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings¶

us76() → tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings¶

Function for creating US76 standard atmosphere model settings.

Function for creating US76 standard atmosphere model settings. The model is defined using tabulated data for density, pressure and temperature, from an altitude of -5 km up to 1000 km. Up to 100 km, a data point is provided every 100 m. Above 100 km, a data point is provided every 1 km. The data are interpolated using a cubic spline interpolator. Note that this model is specific to Earth’s atmosphere.

Returns:: Instance of the AtmosphereSettings class
Return type:: AtmosphereSettings

Examples

In this example, we create AtmosphereSettings for Earth, using the US76 standard atmosphere model:

# create atmosphere settings and add to body settings of body "Earth"
body_settings.get( "Earth" ).atmosphere_settings = environment_setup.atmosphere.us76()

mars_dtm() → tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings¶

Function for creating Mars DTM atmospheric settings.

Creates settings for the Mars DTM semiempirical thermosphere model, which is based on the DTM algorithm originally developed for Earth’s thermosphere and adapted for Mars by Bruinsma and Lemoine (2002). The model reproduces observed densities with approximately 35% uncertainty (1-σ) outside dust storm periods, with uncertainty increasing by roughly a factor of two during dust storms.

Bruinsma, S., and F. G. Lemoine (2002), “A preliminary semiempirical thermosphere model of Mars: DTM-Mars”, Journal of Geophysical Research, 107(E10), 5085, doi:10.1029/2001JE001508.

Parameters:: space_weather_file (str, default="") – Path to file containing space weather data for Mars. If an empty string is provided (default), the model uses the standard coefficients from Bruinsma & Lemoine (2002) without additional space weather corrections. Users can provide a custom file path to use updated or mission-specific space weather data.
Returns:: Instance of the AtmosphereSettings class
Return type:: AtmosphereSettings

Examples

In this example, we create Mars DTM atmosphere settings with default coefficients:

# Create Mars DTM atmosphere using default Bruinsma & Lemoine (2002) coefficients
body_settings.get("Mars").atmosphere_settings = environment_setup.atmosphere.mars_dtm()

In this example, we create Mars DTM atmosphere settings with a custom space weather file:

# Create Mars DTM atmosphere with custom space weather data
body_settings.get("Mars").atmosphere_settings = environment_setup.atmosphere.mars_dtm(
    space_weather_file="path/to/custom_mars_space_weather.dat"
)

custom_constant_temperature(density_function: Callable[[float | SupportsIndex], float], constant_temperature: float | SupportsIndex, specific_gas_constant: float | SupportsIndex = 287.0, ratio_of_specific_heats: float | SupportsIndex = 1.4) → tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings¶

Function for creating atmospheric model settings from custom density profile.

Function for settings object, defining constant temperature atmosphere model from custom density profile. The user is specifying the density profile as a function of altitude. The value of pressure is computed by assuming hydrostatic equilibrium, temperature, gas constant and the ratio of specific heats are modelled as constants.

Parameters:

density_function (callable[[float], float]) – Function to retrieve the density at the current altitude.
constant_temperature (float) – Constant atmospheric temperature.
specific_gas_constant (float, default = 287.0) – Specific gas constant for (constant) atmospheric chemical composition.
ratio_specific_heats (float, default = 1.4) – Ratio of specific heats for (constant) atmospheric chemical composition.

Returns:

Instance of the AtmosphereSettings derived CustomConstantTemperatureAtmosphereSettings class

Return type:

CustomConstantTemperatureAtmosphereSettings

Examples

In this example, we create AtmosphereSettings for Earth, with constant temperature and composition, but a density which varies with altitude according to a user-defined model:

# Define the density as a function of altitude [in m]
def density_function(h):
    # Return the density according to a modified exponential model
    return 1.15 * np.exp(-h/7300)
# Define parameters for constant temperature and composition
constant_temperature = 250.0
specific_gas_constant = 300.0
ratio_of_specific_heats = 1.4
# Create the custom constant temperature atmosphere settings
custom_density_settings = environment_setup.atmosphere.custom_constant_temperature(
    density_function,
    constant_temperature,
    specific_gas_constant,
    ratio_of_specific_heats)
# Add the custom density to the body settings of "Earth"
body_settings.get("Earth").atmosphere_settings = custom_density_settings

custom_four_dimensional_constant_temperature(density_function: Callable[[float | SupportsIndex, float | SupportsIndex, float | SupportsIndex, float | SupportsIndex], float], constant_temperature: float | SupportsIndex, specific_gas_constant: float | SupportsIndex = 287.0, ratio_of_specific_heats: float | SupportsIndex = 1.4) → tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings¶

Function for creating atmospheric model settings from custom density profile.

Note

The longitude and latitude will be passed to the function in degree and not in radians. The altitude is in meters, and the time is a Julian date in seconds since J2000.

Parameters:

density_function (callable[[float, float, float, float], float]) – Function to retrieve the density at the current altitude, longitude, latitude and time.
constant_temperature (float) – Constant atmospheric temperature.
specific_gas_constant (float, default = 287.0) – Specific gas constant for (constant) atmospheric chemical composition.
ratio_specific_heats (float, default = 1.4) – Ratio of specific heats for (constant) atmospheric chemical composition.

Returns:

Instance of the AtmosphereSettings derived CustomConstantTemperatureAtmosphereSettings class

Return type:

CustomConstantTemperatureAtmosphereSettings

Examples

In this example, we create AtmosphereSettings for Earth, with constant temperature and composition (gas constant and ratio of specific heats), but a density which varies with altitude, longitude, latitude and time, according to a user-defined model:

# Define the density as a function of altitude [m], longitude [deg], latitude [deg], and time [sec since J2000]
def density_function(h, lon, lat, time):
    # Return the density according to an exponential model that varies with time to add noise with a sine (ignore lon/lat)
    return (1 + 0.15 * np.sin(time/10)) * np.exp(-h/7300)
# Define the parameters for constant temperature and composition
constant_temperature = 250.0
specific_gas_constant = 300.0
ratio_of_specific_heats = 1.4
# Create the atmosphere settings and add to body settings of "Earth"
body_settings.get( "Earth" ).atmosphere_settings = environment_setup.atmosphere.custom_constant_temperature(
    density_function,
    constant_temperature,
    specific_gas_constant,
    ratio_of_specific_heats )

scaled_by_constant(unscaled_atmosphere_settings: tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings, density_scaling: float | SupportsIndex, is_scaling_absolute: bool = False) → tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings¶

Function for creating scaled atmospheric model settings.

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

Parameters:

unscaled_atmosphere_settings (AtmosphereSettings) – Sets base settings of atmosphere model to be scaled.
density_scaling (float) – Constant scaling factor to be applied to the entire air density profile.
is_scaling_absolute (bool, default=false) – Boolean indicating whether density scaling is absolute. Setting this boolean to true will add the scaling value to the baseline density, instead of the default behaviour of multiplying the baseline density by the scaling value.

Returns:

Instance of the AtmosphereSettings derived ScaledAtmosphereSettings class.

Return type:

ScaledAtmosphereSettings

Notes

At present, the scaled atmosphere model only supports scaling of the density value. For cases where the density is used to compute other atmospheric quantities (such as pressure using hydrostatic equilibrium), this calculation is performed using the unscaled density!

Examples

In this example, we create AtmosphereSettings for Earth, by modifying an existing AtmosphereSettings object such that the resulting air density profile is scaled by a constant:

# define parameter for scaling
scaling_constant = 1.5
# define variable containing the existing atmosphere model settings
unscaled_atmosphere_settings = body_settings.get( "Earth" ).atmosphere_settings
# create atmosphere settings and add to body settings of "Earth"
body_settings.get( "Earth" ).atmosphere_settings =  environment_setup.atmosphere.scaled_by_constant(
    unscaled_atmosphere_settings,
    scaling_constant )

scaled_by_function(unscaled_atmosphere_settings: tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings, density_scaling_function: Callable[[float | SupportsIndex], float], is_scaling_absolute: bool = False) → tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings¶

Function for creating scaled atmospheric model settings.

Function for settings object, defining atmospheric model based on scaling an existing atmospheric settings object. The user can apply custom scaling factors (or absolute values) to the air densities of the existing model settings (for instance for an uncertainty analysis).

Parameters:

unscaled_atmosphere_settings (AtmosphereSettings) – Sets base settings of atmosphere model to be scaled.
density_scaling_function (callable[[float], float]) – Specifies air density scaling factor as a function of time.
is_scaling_absolute (bool, default=false) – Boolean indicating whether density scaling is absolute. Setting this boolean to true will add the scaling value to the baseline density, instead of the default behaviour of multiplying the baseline density by the scaling value.

Returns:

Instance of the AtmosphereSettings derived ScaledAtmosphereSettings class.

Return type:

ScaledAtmosphereSettings

Notes

Examples

In this example, we create AtmosphereSettings for Earth, by modifying an existing AtmosphereSettings object such, that the resulting air density profile is scaled with a user-defined function of time:

# Define the density scaling as a function of time [sec since J2000] (to add noise with a sine)
def scaling_function(time):
    return 1 + np.sin(time / 50) * 0.25
# Extract the existing atmosphere model settings
unscaled_atmosphere_settings = body_settings.get( "Earth" ).atmosphere_settings
# Create the atmosphere settings and add to body settings of "Earth"
body_settings.get( "Earth" ).atmosphere_settings =  environment_setup.atmosphere.scaled_by_function(
    unscaled_atmosphere_settings,
    scaling_function )

coma_model_from_poly_data(poly_data: tudatpy.kernel.data.coma_model.ComaPolyDataset, molecular_weight: float | SupportsIndex, max_degree: int | SupportsIndex = -1, max_order: int | SupportsIndex = -1, is_log2: bool = True) → tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings¶

Function for creating coma atmosphere model settings from polynomial coefficients.

Function for settings object, defining a coma atmosphere model based on spherical harmonic expansion of gas density data. The coma model is designed for modeling cometary atmospheres (comae) where gas density varies with position and time. This variant uses polynomial coefficient data that describes the spatial distribution of gas density.

The density is computed using spherical harmonic expansion, allowing efficient representation of complex 3D density distributions around the nucleus. The model supports time-dependent density variations through multiple data files covering different time periods.

Note

Data fitting: By default (is_log2=True), the model assumes that the polynomial coefficients were fitted from log2-transformed number density data (i.e., log2(n) where n is the number density in m^-3) and internally applies the inverse transformation (2^x). If your coefficients were fitted to raw (non-log2) number density data, set is_log2=False to skip the back-transformation.

Parameters:

poly_data (ComaPolyDataset) – Polynomial coefficient dataset containing spherical harmonic coefficients for gas density distribution. Create using coma_model_file_processor().
molecular_weight (float) – Molecular weight (molar mass) of the gas species [kg/mol]. For water vapor (H2O), use 0.018015 kg/mol.
max_degree (int, default = -1) – Maximum spherical harmonic degree to use in density calculations. Set to -1 to automatically use the maximum degree available in the dataset.
max_order (int, default = -1) – Maximum spherical harmonic order to use in density calculations. Set to -1 to automatically use the maximum order available in the dataset.
is_log2 (bool, default = True) – Whether the coefficients were fitted to log2-transformed number density data. If True (default), the model applies exp2 to convert back to actual number density. If False, the spherical harmonics output is used directly as number density.

Returns:

Instance of the ComaSettings class configured for coma model. The returned object can be used to add a temperature model via the add_temperature_model() method.

Return type:

ComaSettings

Examples

In this example, we create a coma atmosphere model from polynomial coefficient files:

# Define paths to polynomial coefficient files
poly_file_paths = [
    "coma_data/poly_coeffs_epoch1.txt",
    "coma_data/poly_coeffs_epoch2.txt"
]

# Create file processor from polynomial files
processor = data.coma_model.coma_model_file_processor(poly_file_paths)

# Create polynomial dataset
poly_dataset = processor.create_poly_coefficient_dataset()

# Create coma atmosphere settings
coma_settings = environment_setup.atmosphere.coma_model_from_poly_data(
    poly_data=poly_dataset,
    molecular_weight=0.018015,  # H2O molecular weight in kg/mol
    max_degree=10,
    max_order=10)

# Optionally add temperature model
# coma_settings.add_temperature_model(poly_data=temperature_poly_dataset)

# Apply to body settings
body_settings.get("67P").atmosphere_settings = coma_settings

coma_model_from_stokes_data(stokes_data: tudatpy.kernel.data.coma_model.ComaStokesDataset, molecular_weight: float | SupportsIndex, max_degree: int | SupportsIndex = -1, max_order: int | SupportsIndex = -1, is_log2: bool = True) → tudatpy.kernel.dynamics.environment_setup.atmosphere.AtmosphereSettings¶

Function for creating coma atmosphere model settings from Stokes coefficients.

Function for settings object, defining a coma atmosphere model based on spherical harmonic expansion of gas density data using precomputed Stokes coefficients. The coma model is designed for modeling cometary atmospheres (comae) where gas density varies with position and time. This variant uses precomputed Stokes coefficients (spherical harmonics) evaluated at specific radii and solar longitudes.

Stokes coefficients provide a more direct representation of the spherical harmonic expansion compared to polynomial coefficients, offering faster evaluation during simulation. The coefficients are pre-evaluated at a grid of radii and solar longitudes, with interpolation used for intermediate values.

Note

Data fitting: By default (is_log2=True), the model assumes that the Stokes coefficients (or the polynomial coefficients they are derived from) were fitted from log2-transformed number density data (i.e., log2(n) where n is the number density in m^-3) and internally applies the inverse transformation (2^x). If your coefficients were fitted to raw (non-log2) number density data, set is_log2=False to skip the back-transformation.

Parameters:

stokes_data (ComaStokesDataset) – Precomputed Stokes coefficient dataset containing spherical harmonic coefficients evaluated at specific radii and solar longitudes. Create using coma_model_file_processor() or load from pre-existing Stokes coefficient CSV files.
molecular_weight (float) – Molecular weight (molar mass) of the gas species [kg/mol]. For water vapor (H2O), use 0.018015 kg/mol.
max_degree (int, default = -1) – Maximum spherical harmonic degree to use in density calculations. Set to -1 to automatically use the maximum degree available in the dataset.
max_order (int, default = -1) – Maximum spherical harmonic order to use in density calculations. Set to -1 to automatically use the maximum order available in the dataset.
is_log2 (bool, default = True) – Whether the coefficients were fitted to log2-transformed number density data. If True (default), the model applies exp2 to convert back to actual number density. If False, the spherical harmonics output is used directly as number density.

Returns:

Instance of the ComaSettings class configured for coma model. The returned object can be used to add a temperature model via the add_temperature_model() method.

Return type:

ComaSettings

Examples

In this example, we create a coma atmosphere model by converting polynomial coefficients to Stokes coefficients:

# Create file processor from polynomial coefficient files
poly_file_paths = ["coma_data/poly_coeffs_epoch1.txt"]
processor = data.coma_model.coma_model_file_processor(poly_file_paths)

# Create Stokes dataset by evaluating at specific radii and solar longitudes
stokes_dataset = processor.create_coma_stokes_dataset(
    radii_m=[1000.0, 2000.0, 5000.0, 10000.0],
    sol_longitudes_deg=[0.0, 90.0, 180.0, 270.0],
    requested_max_degree=10,
    requested_max_order=10)

# Create coma atmosphere settings
coma_settings = environment_setup.atmosphere.coma_model_from_stokes_data(
    stokes_data=stokes_dataset,
    molecular_weight=0.018015,  # H2O molecular weight in kg/mol
    max_degree=10,
    max_order=10)

# Optionally add temperature model
# coma_settings.add_temperature_model(stokes_data=temperature_stokes_dataset)

# Apply to body settings
body_settings.get("67P").atmosphere_settings = coma_settings

Alternatively, load from pre-existing Stokes coefficient CSV files:

# Create file processor from existing Stokes CSV files
processor = data.coma_model.coma_model_file_processor(
    input_dir="coma_data/stokes_files",
    prefix="stokes")

# Create Stokes dataset (radii and longitudes are read from files)
stokes_dataset = processor.create_coma_stokes_dataset(
    radii_m=[],  # Ignored when loading from files
    sol_longitudes_deg=[])

# Create coma atmosphere settings
coma_settings = environment_setup.atmosphere.coma_model_from_stokes_data(
    stokes_data=stokes_dataset,
    molecular_weight=0.018015)

# Optionally add temperature model
# coma_settings.add_temperature_model(stokes_data=temperature_stokes_dataset)

# Apply to body settings
body_settings.get("67P").atmosphere_settings = coma_settings

Classes¶

`WindModelSettings`	Class for providing settings for wind model.
`EmptyWindModelSettings`	Settings for empty wind model (no physical wind, only co-rotation control).
`ConstantWindModelSettings`	No documentation found.
`CustomWindModelSettings`	No documentation found.
`AtmosphereSettings`	Base class for providing settings for atmosphere model.
`ComaSettings`	Settings class for coma atmosphere models.
`ExponentialAtmosphereSettings`	Class for providing settings for exponential atmosphere model.
`CustomConstantTemperatureAtmosphereSettings`	No documentation found.
`ScaledAtmosphereSettings`	No documentation found.
`NRLMSISE00Input`	Input for computation of NRLMSISE00 atmospheric conditions at current time and position.
`NRLMSISE00Atmosphere`	NRLMSISE00 atmosphere model.

Wind Model Settings¶

class WindModelSettings¶

Bases: pybind11_object

Class for providing settings for wind model.

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

property include_corotation¶

Boolean flag indicating whether atmospheric co-rotation should be included in aerodynamic computations.

Type:: bool

class EmptyWindModelSettings¶

Bases: WindModelSettings

Settings for empty wind model (no physical wind, only co-rotation control).

class ConstantWindModelSettings¶

Bases: WindModelSettings

No documentation found.

class CustomWindModelSettings¶

Bases: WindModelSettings

No documentation found.

Atmosphere Settings¶

class AtmosphereSettings¶

Bases: pybind11_object

Base class for providing settings for atmosphere model.

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

property wind_settings¶

read-only

Wind model settings for the atmosphere model settings object.

Type:: WindModelSettings

class ComaSettings¶

Bases: AtmosphereSettings

Settings class for coma atmosphere models.

This class extends AtmosphereSettings to provide configuration for cometary coma atmosphere models. It supports both polynomial and Stokes coefficient datasets for density modeling, and allows optional temperature modeling via the add_temperature_model() method.

Note

This class is typically created using the factory functions coma_model() rather than being instantiated directly.

Examples

Create coma settings and add temperature model:

# Create coma atmosphere settings from polynomial data
coma_settings = environment_setup.atmosphere.coma_model_from_poly_data(
    poly_data=density_poly_dataset,
    molecular_weight=0.018015)  # H2O in kg/mol

# Add temperature model using polynomial data
coma_settings.add_temperature_model(
    poly_data=temperature_poly_dataset,
    max_degree=10,
    max_order=10,
    gamma=1.33)

# Apply to body
body_settings.get("67P").atmosphere_settings = coma_settings

add_temperature_model(*args, **kwargs)¶

Overloaded function.

Overload 1: add_temperature_model(self: tudatpy.kernel.dynamics.environment_setup.atmosphere.ComaSettings, poly_data: tudatpy.kernel.data.coma_model.ComaPolyDataset, max_degree: typing.SupportsInt | typing.SupportsIndex = -1, max_order: typing.SupportsInt | typing.SupportsIndex = -1, gamma: typing.SupportsFloat | typing.SupportsIndex = 1.33) -> None

Add temperature model from polynomial coefficient data.

This method adds a temperature model to the coma atmosphere settings using polynomial coefficient data. The temperature model uses spherical harmonic expansion to compute temperature as a function of position and time.

Note

The temperature data type (polynomial or Stokes) must match the density data type.

Parameters:

poly_data (ComaPolyDataset) – Polynomial coefficient dataset for temperature distribution.
max_degree (int, default = -1) – Maximum spherical harmonic degree for temperature calculations. Set to -1 to use the maximum degree available in the dataset.
max_order (int, default = -1) – Maximum spherical harmonic order for temperature calculations. Set to -1 to use the maximum order available in the dataset.
gamma (float, default = 1.33) – Heat capacity ratio (gamma = Cp/Cv) for the gas species. Default value 1.33 is appropriate for water vapor.

Examples

# Create coma settings with polynomial density data
coma_settings = environment_setup.atmosphere.coma_model_from_poly_data(
    poly_data=density_poly_data,
    molecular_weight=0.018015)

# Add temperature model with polynomial data
coma_settings.add_temperature_model(
    poly_data=temperature_poly_data,
    max_degree=10,
    max_order=10,
    gamma=1.33)

Overload 2: add_temperature_model(self: tudatpy.kernel.dynamics.environment_setup.atmosphere.ComaSettings, stokes_data: tudatpy.kernel.data.coma_model.ComaStokesDataset, max_degree: typing.SupportsInt | typing.SupportsIndex = -1, max_order: typing.SupportsInt | typing.SupportsIndex = -1, gamma: typing.SupportsFloat | typing.SupportsIndex = 1.33) -> None

Add temperature model from Stokes coefficient data.

This method adds a temperature model to the coma atmosphere settings using precomputed Stokes (spherical harmonic) coefficient data. The temperature model uses interpolation of the Stokes coefficients to compute temperature as a function of position and time.

Note

The temperature data type (polynomial or Stokes) must match the density data type.

Parameters:

stokes_data (ComaStokesDataset) – Stokes coefficient dataset for temperature distribution.
max_degree (int, default = -1) – Maximum spherical harmonic degree for temperature calculations. Set to -1 to use the maximum degree available in the dataset.
max_order (int, default = -1) – Maximum spherical harmonic order for temperature calculations. Set to -1 to use the maximum order available in the dataset.
gamma (float, default = 1.33) – Heat capacity ratio (gamma = Cp/Cv) for the gas species. Default value 1.33 is appropriate for water vapor.

Examples

# Create coma settings with Stokes density data
coma_settings = environment_setup.atmosphere.coma_model_from_stokes_data(
    stokes_data=density_stokes_data,
    molecular_weight=0.018015)

# Add temperature model with Stokes data
coma_settings.add_temperature_model(
    stokes_data=temperature_stokes_data,
    max_degree=10,
    max_order=10,
    gamma=1.33)

class ExponentialAtmosphereSettings¶

Bases: AtmosphereSettings

Class for providing settings for exponential atmosphere model.

AtmosphereSettings derived class for a defining the settings of an exponential atmosphere model.

class CustomConstantTemperatureAtmosphereSettings¶

Bases: AtmosphereSettings

No documentation found.

class ScaledAtmosphereSettings¶

Bases: AtmosphereSettings

No documentation found.

Atmosphere Model Classes¶

class NRLMSISE00Input¶

Bases: pybind11_object

Input for computation of NRLMSISE00 atmospheric conditions at current time and position.

The values in this class may be recomputed every time step to reflect changing atmospheric conditions.

__init__(self: tudatpy.kernel.dynamics.environment_setup.atmosphere.NRLMSISE00Input, year: int | SupportsIndex = 0, day_of_year: int | SupportsIndex = 0, seconds_of_day: float | SupportsIndex = 0.0, local_solar_time: float | SupportsIndex = 0.0, f107: float | SupportsIndex = 0.0, f107a: float | SupportsIndex = 0.0, ap_daily: float | SupportsIndex = 0.0, ap_vector: list[float | SupportsIndex] = [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], switches: list[int | SupportsIndex] = []) → None¶

class NRLMSISE00Atmosphere¶

Bases: pybind11_object

NRLMSISE00 atmosphere model.

This class uses the NRLMSISE00 model to compute the atmospheric density and temperature. The GTD7 function is used: Neutral Atmosphere Empirical Model from the surface to the lower exosphere.

Currently, the ideal gas law is used to compute the speed of sound and the specific heat ratio is assumed to be constant and equal to 1.4.

Parameters:: solar_activity_data – Solar activity data for a range of epochs as produced by tudatpy.data.read_solar_activity_data.

__init__(self: tudatpy.kernel.dynamics.environment_setup.atmosphere.NRLMSISE00Atmosphere, solar_activity_data: dict[float | SupportsIndex, tudatpy.kernel.data.SolarActivityData], use_ideal_gas_law: bool = True, use_storm_conditions: bool = False, use_anomalous_oxygen: bool = True) → None¶

get_density(self: tudatpy.kernel.dynamics.environment_setup.atmosphere.NRLMSISE00Atmosphere, altitude: float | SupportsIndex, longitude: float | SupportsIndex, latitude: float | SupportsIndex, time: float | SupportsIndex) → float¶

Get local density

Returns the local density at the given altitude, longitude, latitude and time.

param altitude:

Altitude at which to get the density. [m]

param longitude:

Longitude at which to get the density [rad].

param latitude:

Latitude at which to get the density [rad].

param time:

Time at which density is to be computed [seconds since J2000].

return:

Local density. [kg/m^3]

get_use_geodetic_latitude(self: tudatpy.kernel.dynamics.environment_setup.atmosphere.NRLMSISE00Atmosphere) → bool¶

get_use_utc(self: tudatpy.kernel.dynamics.environment_setup.atmosphere.NRLMSISE00Atmosphere) → bool¶

set_use_geodetic_latitude(self: tudatpy.kernel.dynamics.environment_setup.atmosphere.NRLMSISE00Atmosphere, arg0: bool) → None¶

set_use_utc(self: tudatpy.kernel.dynamics.environment_setup.atmosphere.NRLMSISE00Atmosphere, arg0: bool) → None¶

Enumerations¶

AtmosphereDependentVariables

Members:

class AtmosphereDependentVariables¶

Bases: pybind11_object

Members:

tabulated_density

tabulated_pressure

tabulated_temperature

tabulated_gas_constant

tabulated_specific_heat_ratio

tabulated_molar_mass

AtmosphereDependentVariables.name -> str

atmosphere¶

Functions¶

Classes¶

Wind Model Settings¶

Atmosphere Settings¶

Atmosphere Model Classes¶

Enumerations¶

`atmosphere`¶