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, windy, forecast, reanalysis, ensemble.
Environment.atmospheric_model_file (string) – Address of the file used for the atmospheric model being used. Only defined for wyoming_sounding, windy, 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. Two-element list [x1, x2] containing the latitude coordinates of the grid-cell vertices that bracket the launch site and are used in bilinear interpolation.
Environment.lon_array (array) – Defined if netCDF or OPeNDAP file is used, for Forecasts, Reanalysis and Ensembles. Two-element list [y1, y2] containing the longitude coordinates of the grid-cell vertices that bracket the launch site and are used in bilinear interpolation.
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. Two-element list with the first and last values from the dataset time variable in the dataset native units.
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.
Environment.earth_rotation_vector (list[float]) – Earth’s angular velocity vector in the Flight Coordinate System.

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 windy, forecast, reanalysis or ensemble atmospheric model will be used. 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 windy, forecast, reanalysis or ensemble atmospheric model will be used 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 windy, forecast, reanalysis or ensemble atmospheric model will be used 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.

See also

Atmospheric Models: Overview of all atmospheric-model workflows in the user guide.
Forecasts: Forecast and Windy usage details, including latest-model shortcuts.
Reanalysis: Reanalysis and MERRA-2 examples.
Soundings: Wyoming sounding workflow and RUC migration notes.
Custom Atmosphere: Defining pressure, temperature and wind profiles directly.
Ensemble: Ensemble forecasts and member-selection workflow.
Connecting to other APIs: Building custom mapping dictionaries for NetCDF/OPeNDAP APIs.

process_standard_atmosphere()[source]#

Sets pressure and temperature profiles corresponding to the International Standard Atmosphere defined by ISO 2533 and ranging from -2 km to 80 km of altitude above sea level. Note that the wind profiles are set to zero.

Return type:: None

process_custom_atmosphere(pressure=None, temperature=None, wind_u=0, wind_v=0)[source]#

Import pressure, temperature and wind profile given by user.

Parameters:

pressure (float, string, array, callable, optional) – This defines the atmospheric pressure profile. Should be given if the type parameter is custom_atmosphere. If not, than the the Standard Atmosphere pressure will be used. If a float is given, it will define a constant pressure profile. The float should be in units of Pa. If a string is given, it should point to a .CSV file containing at most one header line and two columns of data. The first column must be the geometric height above sea level in meters while the second column must be the pressure in Pa. If an array is given, it is expected to be a list or array of coordinates (height in meters, pressure in Pa). Finally, a callable or function is also accepted. The function should take one argument, the height above sea level in meters and return a corresponding pressure in Pa.
temperature (float, string, array, callable, optional) – This defines the atmospheric temperature profile. Should be given if the type parameter is custom_atmosphere. If not, than the the Standard Atmosphere temperature will be used. If a float is given, it will define a constant temperature profile. The float should be in units of K. If a string is given, it should point to a .CSV file containing at most one header line and two columns of data. The first column must be the geometric height above sea level in meters while the second column must be the temperature in K. If an array is given, it is expected to be a list or array of coordinates (height in meters, temperature in K). Finally, a callable or function is also accepted. The function should take one argument, the height above sea level in meters and return a corresponding temperature in K.
wind_u (float, string, array, callable, optional) – This defines the atmospheric wind-u profile, corresponding the the magnitude of the wind speed heading East. Should be given if the type parameter is custom_atmosphere. If not, it will be assumed constant and 0. If a float is given, it will define a constant wind-u profile. The float should be in units of m/s. If a string is given, it should point to a .CSV file containing at most one header line and two columns of data. The first column must be the geometric height above sea level in meters while the second column must be the wind-u in m/s. If an array is given, it is expected to be an array of coordinates (height in meters, wind-u in m/s). Finally, a callable or function is also accepted. The function should take one argument, the height above sea level in meters and return a corresponding wind-u in m/s.
wind_v (float, string, array, callable, optional) – This defines the atmospheric wind-v profile, corresponding the the magnitude of the wind speed heading North. Should be given if the type parameter is custom_atmosphere. If not, it will be assumed constant and 0. If a float is given, it will define a constant wind-v profile. The float should be in units of m/s. If a string is given, it should point to a .CSV file containing at most one header line and two columns of data. The first column must be the geometric height above sea level in meters while the second column must be the wind-v in m/s. If an array is given, it is expected to be an array of coordinates (height in meters, wind-v in m/s). Finally, a callable or function is also accepted. The function should take one argument, the height above sea level in meters and return a corresponding wind-v in m/s.

Return type:

None

process_windy_atmosphere(model='ECMWF')[source]#

Process data from Windy.com to retrieve atmospheric forecast data.

Parameters:: model (string, optional) – The atmospheric model to use. Default is ECMWF. Options are: ECMWF for the ECMWF-HRES model, GFS for the GFS model, ICON for the ICON-Global model or ICONEU for the ICON-EU model.
Raises:: ValueError – If model is not one of ECMWF, GFS, ICON or ICONEU.

process_wyoming_sounding(file)[source]#

Import and process the upper air sounding data from Wyoming Upper Air Soundings database given by the url in file. Sets pressure, temperature, wind-u, wind-v profiles and surface elevation.

Parameters:

file (string) –

URL of an upper air sounding data output from Wyoming Upper Air Soundings database.

Example:

http://weather.uwyo.edu/cgi-bin/sounding?region=samer&TYPE=TEXT%3ALIST&YEAR=2019&MONTH=02&FROM=0200&TO=0200&STNM=82599

Notes

More can be found at: http://weather.uwyo.edu/upperair/sounding.html.

Return type:: None

process_forecast_reanalysis(file, dictionary)[source]#

Import and process atmospheric data from weather forecasts and reanalysis given as netCDF or OPeNDAP files. Sets pressure, temperature, wind-u and wind-v profiles and surface elevation obtained from a weather file in netCDF format or from an OPeNDAP URL, both given through the file parameter. The date and location of the launch should already have been set through the date and location parameters when initializing the Environment. The netCDF and OPeNDAP datasets must contain at least geopotential height or geopotential, temperature, wind-u and wind-v profiles as a function of pressure levels. If surface geopotential or geopotential height is given, elevation is also set. Otherwise, elevation is not changed. Profiles are interpolated bi-linearly using supplied latitude and longitude. The date used is the nearest one to the date supplied. Furthermore, a dictionary must be supplied through the dictionary parameter in order for the dataset to be accurately read. Lastly, the dataset must use a rectangular grid sorted in either ascending or descending order of latitude and longitude.

Parameters:

file (string) – String containing path to local netCDF file or URL of an OPeNDAP file, such as NOAA’s NOMAD or UCAR TRHEDDS server.
dictionary (dictionary) –
Specifies the dictionary to be used when reading netCDF and OPeNDAP files, allowing for the correct retrieval of data. The dictionary structure should specify the short names used for time, latitude, longitude, pressure levels, temperature profile, geopotential or geopotential height profile, wind-u and wind-v profiles in the dataset given in the file parameter. An example is the following dictionary, generally used to read OPeNDAP files from NOAA’s NOMAD server:
```
dictionary = {
    "time": "time",
    "latitude": "lat",
    "longitude": "lon",
    "level": "lev",
    "temperature": "tmpprs",
    "surface_geopotential_height": "hgtsfc",
    "geopotential_height": "hgtprs",
    "geopotential": None,
    "u_wind": "ugrdprs",
    "v_wind": "vgrdprs",
}
```

Return type:

None

Raises:

ValueError – If launch date/time was not set before loading date-dependent data, or if required geopotential/geopotential-height, temperature, wind-u, or wind-v variables cannot be read from the dataset.

process_ensemble(file, dictionary)[source]#

Import and process atmospheric data from weather ensembles given as netCDF or OPeNDAP files. Sets pressure, temperature, wind-u and wind-v profiles and surface elevation obtained from a weather ensemble file in netCDF format or from an OPeNDAP URL, both given through the file parameter. The date and location of the launch should already have been set through the date and location parameters when initializing the Environment. The netCDF and OPeNDAP datasets must contain at least geopotential height or geopotential, temperature, wind-u and wind-v profiles as a function of pressure levels. If surface geopotential or geopotential height is given, elevation is also set. Otherwise, elevation is not changed. Profiles are interpolated bi-linearly using supplied latitude and longitude. The date used is the nearest one to the date supplied. Furthermore, a dictionary must be supplied through the dictionary parameter in order for the dataset to be accurately read. Lastly, the dataset must use a rectangular grid sorted in either ascending or descending order of latitude and longitude. By default the first ensemble forecast is activated. To activate other ensemble forecasts see Environment.select_ensemble_member().

Parameters:

file (string) – String containing path to local .nc file or URL of an OPeNDAP file, such as NOAA’s NOMAD or UCAR TRHEDDS server.
dictionary (dictionary) –
Specifies the dictionary to be used when reading netCDF and OPeNDAP files, allowing for the correct retrieval of data. The dictionary structure should specify the short names used for time, latitude, longitude, pressure levels, temperature profile, geopotential or geopotential height profile, wind-u and wind-v profiles in the dataset given in the file parameter. An example is the following dictionary, generally used to read OPeNDAP files from NOAA’s NOMAD server:
```
dictionary = {
    "time": "time",
    "latitude": "lat",
    "longitude": "lon",
    "level": "lev",
    "ensemble": "ens",
    "surface_geopotential_height": "hgtsfc",
    "geopotential_height": "hgtprs",
    "geopotential": None,
    "u_wind": "ugrdprs",
    "v_wind": "vgrdprs",
}
```