Environment Class#

class rocketpy.Environment[source]#

Keeps all environment information stored, such as wind and temperature conditions, as well as gravity.

Variables:

Environment.earth_radius (float) – Value of Earth’s Radius as 6.3781e6 m.
Environment.air_gas_constant (float) – Value of Air’s Gas Constant as 287.05287 J/K/Kg
Environment.gravity (Function) – Gravitational acceleration. Positive values point the acceleration down. See Environment.set_gravity_model() for more information.
Environment.latitude (float) – Launch site latitude.
Environment.longitude (float) – Launch site longitude.
Environment.datum (string) – The desired reference ellipsoid model, the following options are available: SAD69, WGS84, NAD83, and SIRGAS2000.
Environment.initial_east (float) – Launch site East UTM coordinate
Environment.initial_north (float) – Launch site North UTM coordinate
Environment.initial_utm_zone (int) – Launch site UTM zone number
Environment.initial_utm_letter (string) – Launch site UTM letter, to keep the latitude band and describe the UTM Zone
Environment.initial_hemisphere (string) – Launch site South/North hemisphere
Environment.initial_ew (string) – Launch site East/West hemisphere
Environment.elevation (float) – Launch site elevation.
Environment.datetime_date (datetime) – Date time of launch in UTC time zone using the datetime object.
Environment.local_date (datetime) – Date time of launch in the local time zone, defined by the Environment.timezone parameter.
Environment.timezone (string) –
Local time zone specification. See pytz. for time zone information.
Environment.elev_lon_array (array) – Unidimensional array containing the longitude coordinates.
Environment.elev_lat_array (array) – Unidimensional array containing the latitude coordinates.
Environment.elev_array (array) – Two-dimensional Array containing the elevation information.
Environment.topographic_profile_activated (bool) – True if the user already set a topographic profile. False otherwise.
Environment.max_expected_height (float) – Maximum altitude in meters to keep weather data. The altitude must be Above Sea Level (ASL). Especially useful for controlling plots. Can be altered as desired by running max_expected_height = number.
Environment.pressure_ISA (Function) – Air pressure in Pa as a function of altitude as defined by the International Standard Atmosphere ISO 2533.
Environment.temperature_ISA (Function) – Air temperature in K as a function of altitude as defined by the International Standard Atmosphere ISO 2533
Environment.pressure (Function) – Air pressure in Pa as a function of altitude.
Environment.barometric_height (Function) – Geometric height above sea level in m as a function of pressure.
Environment.temperature (Function) – Air temperature in K as a function of altitude.
Environment.speed_of_sound (Function) – Speed of sound in air in m/s as a function of altitude.
Environment.density (Function) – Air density in kg/m³ as a function of altitude.
Environment.dynamic_viscosity (Function) – Air dynamic viscosity in Pa*s as a function of altitude.
Environment.wind_speed (Function) – Wind speed in m/s as a function of altitude.
Environment.wind_direction (Function) – Wind direction (from which the wind blows) in degrees relative to north (positive clockwise) as a function of altitude.
Environment.wind_heading (Function) – Wind heading (direction towards which the wind blows) in degrees relative to north (positive clockwise) as a function of altitude.
Environment.wind_velocity_x (Function) – Wind U, or X (east) component of wind velocity in m/s as a function of altitude.
Environment.wind_velocity_y (Function) – Wind V, or Y (north) component of wind velocity in m/s as a function of altitude.
Environment.atmospheric_model_type (string) – Describes the atmospheric model which is being used. Can only assume the following values: standard_atmosphere, custom_atmosphere, wyoming_sounding, Forecast, Reanalysis, Ensemble.
Environment.atmospheric_model_file (string) – Address of the file used for the atmospheric model being used. Only defined for wyoming_sounding, Forecast, Reanalysis, Ensemble
Environment.atmospheric_model_dict (dictionary) – Dictionary used to properly interpret netCDF and OPeNDAP files. Only defined for Forecast, Reanalysis, Ensemble.
Environment.atmospheric_model_init_date (datetime) – Datetime object instance of first available date in netCDF and OPeNDAP files when using Forecast, Reanalysis or Ensemble.
Environment.atmospheric_model_end_date (datetime) – Datetime object instance of last available date in netCDF and OPeNDAP files when using Forecast, Reanalysis or Ensemble.
Environment.atmospheric_model_interval (int) – Hour step between weather condition used in netCDF and OPeNDAP files when using Forecast, Reanalysis or Ensemble.
Environment.atmospheric_model_init_lat (float) – Latitude of vertex just before the launch site in netCDF and OPeNDAP files when using Forecast, Reanalysis or Ensemble.
Environment.atmospheric_model_end_lat (float) – Latitude of vertex just after the launch site in netCDF and OPeNDAP files when using Forecast, Reanalysis or Ensemble.
Environment.atmospheric_model_init_lon (float) – Longitude of vertex just before the launch site in netCDF and OPeNDAP files when using Forecast, Reanalysis or Ensemble.
Environment.atmospheric_model_end_lon (float) – Longitude of vertex just after the launch site in netCDF and OPeNDAP files when using Forecast, Reanalysis or Ensemble.
Environment.lat_array (array) – Defined if netCDF or OPeNDAP file is used, for Forecasts, Reanalysis and Ensembles. 2x2 matrix for each pressure level of latitudes corresponding to the vertices of the grid cell which surrounds the launch site.
Environment.lon_array (array) – Defined if netCDF or OPeNDAP file is used, for Forecasts, Reanalysis and Ensembles. 2x2 matrix for each pressure level of longitudes corresponding to the vertices of the grid cell which surrounds the launch site.
Environment.lon_index (int) – Defined if netCDF or OPeNDAP file is used, for Forecasts, Reanalysis and Ensembles. Index to a grid longitude which is just over the launch site longitude, while lon_index - 1 points to a grid longitude which is just under the launch site longitude.
Environment.lat_index (int) – Defined if netCDF or OPeNDAP file is used, for Forecasts, Reanalysis and Ensembles. Index to a grid latitude which is just over the launch site latitude, while lat_index - 1 points to a grid latitude which is just under the launch site latitude.
Environment.geopotentials (array) – Defined if netCDF or OPeNDAP file is used, for Forecasts, Reanalysis and Ensembles. 2x2 matrix for each pressure level of geopotential heights corresponding to the vertices of the grid cell which surrounds the launch site.
Environment.wind_us (array) – Defined if netCDF or OPeNDAP file is used, for Forecasts, Reanalysis and Ensembles. 2x2 matrix for each pressure level of wind U (east) component corresponding to the vertices of the grid cell which surrounds the launch site.
Environment.wind_vs (array) – Defined if netCDF or OPeNDAP file is used, for Forecasts, Reanalysis and Ensembles. 2x2 matrix for each pressure level of wind V (north) component corresponding to the vertices of the grid cell which surrounds the launch site.
Environment.levels (array) – Defined if netCDF or OPeNDAP file is used, for Forecasts, Reanalysis and Ensembles. List of pressure levels available in the file.
Environment.temperatures (array) – Defined if netCDF or OPeNDAP file is used, for Forecasts, Reanalysis and Ensembles. 2x2 matrix for each pressure level of temperatures corresponding to the vertices of the grid cell which surrounds the launch site.
Environment.time_array (array) – Defined if netCDF or OPeNDAP file is used, for Forecasts, Reanalysis and Ensembles. Array of dates available in the file.
Environment.height (array) – Defined if netCDF or OPeNDAP file is used, for Forecasts, Reanalysis and Ensembles. List of geometric height corresponding to launch site location.
Environment.level_ensemble (array) – Only defined when using Ensembles.
Environment.height_ensemble (array) – Only defined when using Ensembles.
Environment.temperature_ensemble (array) – Only defined when using Ensembles.
Environment.wind_u_ensemble (array) – Only defined when using Ensembles.
Environment.wind_v_ensemble (array) – Only defined when using Ensembles.
Environment.wind_heading_ensemble (array) – Only defined when using Ensembles.
Environment.wind_direction_ensemble (array) – Only defined when using Ensembles.
Environment.wind_speed_ensemble (array) – Only defined when using Ensembles.
Environment.num_ensemble_members (int) – Number of ensemble members. Only defined when using Ensembles.
Environment.ensemble_member (int) – Current selected ensemble member. Only defined when using Ensembles.

Notes

All the attributes listed as Function objects can be accessed as regular arrays, or called as a Function. See rocketpy.Function for more information.

__init__(gravity=None, date=None, latitude=0.0, longitude=0.0, elevation=0.0, datum='SIRGAS2000', timezone='UTC', max_expected_height=80000.0)[source]#

Initializes the Environment class, capturing essential parameters of the launch site, including the launch date, geographical coordinates, and elevation. This class is designed to calculate crucial variables for the Flight simulation, such as atmospheric air pressure, density, and gravitational acceleration.

Note that the default atmospheric model is the International Standard Atmosphere as defined by ISO 2533 unless specified otherwise in Environment.set_atmospheric_model().

Parameters:

gravity (int, float, callable, string, array, optional) – Surface gravitational acceleration. Positive values point the acceleration down. If None, the Somigliana formula is used. See Environment.set_gravity_model() for more information.
date (list or tuple, optional) –
List or tuple of length 4, stating (year, month, day, hour) in the time zone of the parameter timezone. Alternatively, can be a datetime object specifying launch date and time. The dates are stored as follows:
- Environment.local_date: Local time of launch in the time zone specified by the parameter timezone.
- Environment.datetime_date: UTC time of launch.
Must be given if a Forecast, Reanalysis or Ensemble, will be set as an atmospheric model. Default is None. See Environment.set_date() for more information.
latitude (float, optional) – Latitude in degrees (ranging from -90 to 90) of rocket launch location. Must be given if a Forecast, Reanalysis or Ensemble will be used as an atmospheric model or if Open-Elevation will be used to compute elevation. Positive values correspond to the North. Default value is 0, which corresponds to the equator.
longitude (float, optional) – Longitude in degrees (ranging from -180 to 180) of rocket launch location. Must be given if a Forecast, Reanalysis or Ensemble will be used as an atmospheric model or if Open-Elevation will be used to compute elevation. Positive values correspond to the East. Default value is 0, which corresponds to the Greenwich Meridian.
elevation (float, optional) – Elevation of launch site measured as height above sea level in meters. Alternatively, can be set as Open-Elevation which uses the Open-Elevation API to find elevation data. For this option, latitude and longitude must also be specified. Default value is 0.
datum (string, optional) – The desired reference ellipsoidal model, the following options are available: “SAD69”, “WGS84”, “NAD83”, and “SIRGAS2000”. The default is “SIRGAS2000”.
timezone (string, optional) – Name of the time zone. To see all time zones, import pytz and run print(pytz.all_timezones). Default time zone is “UTC”.
max_expected_height (float, optional) – Maximum altitude in meters to keep weather data. The altitude must be above sea level (ASL). Especially useful for visualization. Can be altered as desired by running max_expected_height = number. Depending on the atmospheric model, this value may be automatically modified.

Return type:

None

set_date(date, timezone='UTC')[source]#

Set date and time of launch and update weather conditions if date dependent atmospheric model is used.

Parameters:

date (list, tuple, datetime) – List or tuple of length 4, stating (year, month, day, hour) in the time zone of the parameter timezone. See Notes for more information. Alternatively, can be a datetime object specifying launch date and time.
timezone (string, optional) – Name of the time zone. To see all time zones, import pytz and run print(pytz.all_timezones). Default time zone is “UTC”.

Return type:

None

Notes

If the date is given as a list or tuple, it should be in the same time zone as specified by the timezone parameter. This local time will be available in the attribute Environment.local_date while the UTC time will be available in the attribute Environment.datetime_date.
If the date is given as a datetime object without a time zone, it will be assumed to be in the same time zone as specified by the timezone parameter. However, if the datetime object has a time zone specified in its tzinfo attribute, the timezone parameter will be ignored.

Examples

Let’s set the launch date as an list:

>>> date = [2000, 1, 1, 13] # January 1st, 2000 at 13:00 UTC+1
>>> env = Environment()
>>> env.set_date(date, timezone="Europe/Rome")
>>> print(env.datetime_date) # Get UTC time
2000-01-01 12:00:00+00:00
>>> print(env.local_date)
2000-01-01 13:00:00+01:00

Now let’s set the launch date as a datetime object:

>>> from datetime import datetime
>>> date = datetime(2000, 1, 1, 13, 0, 0)
>>> env = Environment()
>>> env.set_date(date, timezone="Europe/Rome")
>>> print(env.datetime_date) # Get UTC time
2000-01-01 12:00:00+00:00
>>> print(env.local_date)
2000-01-01 13:00:00+01:00

set_location(latitude, longitude)[source]#

Set latitude and longitude of launch and update atmospheric conditions if location dependent model is being used.

Parameters:

latitude (float) – Latitude of launch site. May range from -90 to 90 degrees.
longitude (float) – Longitude of launch site. Either from 0 to 360 degrees or from -180 to 180 degrees.

Return type:

None

set_gravity_model(gravity=None)[source]#

Defines the gravity model based on the given user input to the gravity parameter. The gravity model is responsible for computing the gravity acceleration at a given height above sea level in meters.

Parameters:

gravity (int, float, callable, string, list, optional) –

The gravitational acceleration in m/s² to be used in the simulation, this value is positive when pointing downwards. The input type can be one of the following:

int or float: The gravity acceleration is set as a constant function with respect to height;
callable: This callable should receive the height above sea level in meters and return the gravity acceleration;
list: The datapoints should be structured as [(h_i,g_i), ...] where h_i is the height above sea level in meters and g_i is the gravity acceleration in m/s²;
string: The string should correspond to a path to a CSV file containing the gravity acceleration data;
None: The Somigliana formula is used to compute the gravity acceleration.

This parameter is used as a Function object source, check out the available input types for a more detailed explanation.

Returns:

Function object representing the gravity model.

Return type:

Function

Notes

This method does not set the gravity acceleration, it only returns a Function object representing the gravity model.

Examples

Let’s prepare a Environment object with a constant gravity acceleration:

>>> g_0 = 9.80665
>>> env_cte_g = Environment(gravity=g_0)
>>> env_cte_g.gravity([0, 100, 1000])
[np.float64(9.80665), np.float64(9.80665), np.float64(9.80665)]

It’s also possible to variate the gravity acceleration by defining its function of height:

>>> R_t = 6371000
>>> g_func = lambda h : g_0 * (R_t / (R_t + h))**2
>>> env_var_g = Environment(gravity=g_func)
>>> g = env_var_g.gravity(1000)
>>> print(f"{g:.6f}")
9.803572

somigliana_gravity#

Computes the gravity acceleration with the Somigliana formula [1]. An height correction is applied to the normal gravity that is accurate for heights used in aviation. The formula is based on the WGS84 ellipsoid, but is accurate for other reference ellipsoids.

Parameters:: height (float) – Height above the reference ellipsoid in meters.
Returns:: Function object representing the gravity model.
Return type:: Function

References

set_elevation(elevation='Open-Elevation')[source]#

Set elevation of launch site given user input or using the Open-Elevation API.

Parameters:

elevation (float, string, optional) –

Elevation of launch site measured as height above sea level in meters. Alternatively, can be set as Open-Elevation which uses the Open-Elevation API to find elevation data. For this option, latitude and longitude must have already been specified.