`atmosphere`#

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

Functions#

`constant_wind_model`(wind_velocity, 1]], ...)	Factory function for creating wind model settings with constant wind velocity.
`custom_wind_model`(wind_function, float, ...)	Factory function for creating wind model settings with custom wind velocity.
`exponential_predefined`(body_name)	Factory function for creating atmospheric model settings from pre-defined exponential model.
`exponential`(scale_height, surface_density[, ...])	Factory function for creating atmospheric model settings from fully parametrized exponential model.
`nrlmsise00`([space_weather_file])	Factory function for creating NRLMSISE-00 atmospheric model settings.
`us76`()
`custom_constant_temperature`(...[, ...])	Factory function for creating atmospheric model settings from custom density profile.
`custom_four_dimensional_constant_temperature`(...)	Factory function for creating atmospheric model settings from custom density profile.
`scaled_by_constant`(...[, is_scaling_absolute])	Factory function for creating scaled atmospheric model settings.
`scaled_by_function`(...[, is_scaling_absolute])	Factory function for creating scaled atmospheric model settings.

constant_wind_model(wind_velocity: numpy.ndarray[numpy.float64[3, 1]], associated_reference_frame: tudatpy.kernel.numerical_simulation.environment.AerodynamicsReferenceFrames = <AerodynamicsReferenceFrames.vertical_frame: 1>) → tudatpy.kernel.numerical_simulation.environment_setup.atmosphere.WindModelSettings#

Factory function for creating wind model settings with constant wind velocity.

Factory 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 (numerical_simulation.environment.AerodynamicsReferenceFrames, default = AerodynamicsReferenceFrames.vertical_frame) – Reference frame in which constant wind velocity is defined.

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, float, float, float], numpy.ndarray[numpy.float64[3, 1]]], associated_reference_frame: tudatpy.kernel.numerical_simulation.environment.AerodynamicsReferenceFrames = <AerodynamicsReferenceFrames.vertical_frame: 1>) → tudatpy.kernel.numerical_simulation.environment_setup.atmosphere.WindModelSettings#

Factory function for creating wind model settings with custom wind velocity.

Factory 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 (numerical_simulation.environment.AerodynamicsReferenceFrames, default = AerodynamicsReferenceFrames.vertical_frame) – Reference frame in which wind velocity is defined.

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

exponential_predefined(body_name: str) → tudatpy.kernel.numerical_simulation.environment_setup.atmosphere.AtmosphereSettings#

Factory function for creating atmospheric model settings from pre-defined exponential model.

Factory 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, surface_density: float, constant_temperature: float = 288.15, specific_gas_constant: float = 287.0, ratio_specific_heats: float = 1.4) → tudatpy.kernel.numerical_simulation.environment_setup.atmosphere.AtmosphereSettings#

Factory function for creating atmospheric model settings from fully parametrized exponential model.

Factory 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') → tudatpy.kernel.numerical_simulation.environment_setup.atmosphere.AtmosphereSettings#

Factory function for creating NRLMSISE-00 atmospheric model settings.

Factory function for settings object, defining atmosphere model in accordance to the NRLMSISE-00 global reference model for Earth’s atmosphere.

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 here 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 here
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()

us76() → tudatpy.kernel.numerical_simulation.environment_setup.atmosphere.AtmosphereSettings#

custom_constant_temperature(density_function: Callable[[float], float], constant_temperature: float, specific_gas_constant: float = 287.0, ratio_of_specific_heats: float = 1.4) → tudatpy.kernel.numerical_simulation.environment_setup.atmosphere.AtmosphereSettings#

Factory function for creating atmospheric model settings from custom density profile.

Factory 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, float, float, float], float], constant_temperature: float, specific_gas_constant: float = 287.0, ratio_of_specific_heats: float = 1.4) → tudatpy.kernel.numerical_simulation.environment_setup.atmosphere.AtmosphereSettings#

Factory 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.numerical_simulation.environment_setup.atmosphere.AtmosphereSettings, density_scaling: float, is_scaling_absolute: bool = False) → tudatpy.kernel.numerical_simulation.environment_setup.atmosphere.AtmosphereSettings#

Factory function for creating scaled atmospheric model settings.

Factory 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.numerical_simulation.environment_setup.atmosphere.AtmosphereSettings, density_scaling_function: Callable[[float], float], is_scaling_absolute: bool = False) → tudatpy.kernel.numerical_simulation.environment_setup.atmosphere.AtmosphereSettings#

Factory function for creating scaled atmospheric model settings.

Factory 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 )

Classes#

`WindModelSettings`	Class for providing settings for wind model.
`AtmosphereSettings`	Base class for providing settings for atmosphere model.
`ExponentialAtmosphereSettings`	Class for providing settings for exponential atmosphere model.

class WindModelSettings#

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.

class AtmosphereSettings#

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 ExponentialAtmosphereSettings#

Class for providing settings for exponential atmosphere model.

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

atmosphere#

Functions#

Classes#

`atmosphere`#