Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 27 additions & 11 deletions docs/user/environment/1-atm-models/ensemble.rst
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,18 @@ is a two-column array: the first column is geometric height above sea level in
meters, and the second column uses Pa for pressure, K for temperature and m/s
for either wind component.

The pressure profiles determine a common isobaric grid. Temperature and wind
are interpolated onto that grid, then written to a GEFS-compatible NetCDF file.
Every pressure profile must overlap the others and decrease with height.
The pressure profiles determine a common isobaric grid, and temperature and
wind are interpolated onto that grid. Every pressure profile must overlap the
others and decrease with height.

The profiles are not tied to a date. The Environment does not need one, and
the ensemble stays the same if the launch date is changed later.

.. note::

Below the lowest height of a profile, its lowest value is used. Start the
profiles at or below the ground level of the launch site, so the values
near the ground are the ones you gave.

.. code-block:: python

Expand All @@ -41,15 +50,14 @@ Every pressure profile must overlap the others and decrease with height.
from rocketpy import Environment

env = Environment(
date=(2026, 9, 1, 12),
latitude=32.990254,
longitude=-106.974998,
elevation=1400,
)

pressure = np.array([85000, 70000, 50000]) # Pa
height_0 = np.array([1500, 3000, 5500]) # m ASL
height_1 = np.array([1550, 3100, 5650]) # m ASL
height_0 = np.array([1400, 3000, 5500]) # m ASL
height_1 = np.array([1400, 3100, 5650]) # m ASL

profiles = [
{
Expand All @@ -66,21 +74,29 @@ Every pressure profile must overlap the others and decrease with height.
},
]

ensemble_file = env.create_ensemble(profiles, "my_ensemble.nc")
env.create_ensemble(profiles)

The method activates member 0 after writing the file. Select another member
with the same method used for forecast ensembles:
The method activates member 0. Select another member with the same method used
for forecast ensembles:

.. code-block:: python

env.select_ensemble_member(1)

Another Environment can load the returned file with the ``GEFS`` mapping:
By default the ensemble is kept in memory and no file is written. To use it
again later, give a file name. RocketPy then also saves the ensemble as a
GEFS-compatible NetCDF file and returns its path:

.. code-block:: python

ensemble_file = env.create_ensemble(profiles, "my_ensemble.nc")

Another Environment, with any launch date or none, can load that file with the
``GEFS`` mapping:

.. code-block:: python

saved_env = Environment(
date=(2026, 9, 1, 12),
latitude=32.990254,
longitude=-106.974998,
elevation=1400,
Expand Down
164 changes: 107 additions & 57 deletions rocketpy/environment/environment.py
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,10 @@
geopotential_height_to_geometric_height,
)

# Written in the datasets of Environment.create_ensemble. It tells the loader
# that the ensemble comes from profiles given by the user, which have no date.
_USER_DEFINED_ENSEMBLE_SOURCE = "RocketPy Environment.create_ensemble"

logger = logging.getLogger(__name__)


Expand Down Expand Up @@ -859,11 +863,11 @@ def set_date(self, date, timezone="UTC"):

# Update atmospheric conditions if atmosphere type is Forecast,
# Reanalysis or Ensemble
if hasattr(self, "atmospheric_model_type") and self.atmospheric_model_type in [
"Forecast",
"Reanalysis",
"Ensemble",
]:
if (
hasattr(self, "atmospheric_model_type")
and self.atmospheric_model_type in ["Forecast", "Reanalysis", "Ensemble"]
and not getattr(self, "_ensemble_from_profiles", False)
):
self.set_atmospheric_model(
type=self.atmospheric_model_type,
file=self.atmospheric_model_file,
Expand Down Expand Up @@ -898,11 +902,11 @@ def set_location(self, latitude, longitude):

# Update atmospheric conditions if atmosphere type is Forecast,
# Reanalysis or Ensemble
if hasattr(self, "atmospheric_model_type") and self.atmospheric_model_type in [
"Forecast",
"Reanalysis",
"Ensemble",
]:
if (
hasattr(self, "atmospheric_model_type")
and self.atmospheric_model_type in ["Forecast", "Reanalysis", "Ensemble"]
and not getattr(self, "_ensemble_from_profiles", False)
):
self.set_atmospheric_model(
type=self.atmospheric_model_type,
file=self.atmospheric_model_file,
Expand Down Expand Up @@ -1410,6 +1414,7 @@ def set_atmospheric_model( # pylint: disable=too-many-statements
"""
# Save atmospheric model type
self.atmospheric_model_type = type
self._ensemble_from_profiles = False
type = type.lower()

match type:
Expand Down Expand Up @@ -3277,9 +3282,10 @@ def _create_ensemble_time_coordinate(self, dataset):
time = dataset.createVariable("time", "f8", ("time",))
time.long_name = "profile valid time"
time.standard_name = "time"
time.units = (
f"hours since {self.datetime_date.strftime('%Y-%m-%d %H:%M:%S')} UTC"
)
# The profiles have no date of their own and the loader does not check
# this one. The launch date is used when the Environment has one.
reference = self.datetime_date or datetime(1970, 1, 1)
time.units = f"hours since {reference.strftime('%Y-%m-%d %H:%M:%S')} UTC"
time.calendar = "gregorian"
time.axis = "T"
time[:] = [0]
Expand Down Expand Up @@ -3398,43 +3404,43 @@ def _create_ensemble_data_variables(
variable.coordinates = "time ens lev lat lon"
variable[:] = np.broadcast_to(values[None, :, :, None, None], data_shape)

def _write_ensemble_file(
self, file_path, pressure_levels, geopotential_heights, member_values
def _fill_ensemble_dataset(
self, dataset, pressure_levels, geopotential_heights, member_values
):
"""Write prepared ensemble data to a GEFS-compatible NetCDF file."""
with netCDF4.Dataset(file_path, "w", format="NETCDF4") as dataset:
dataset.Conventions = "CF-1.8"
dataset.title = "RocketPy user-defined atmospheric ensemble"
dataset.source = "RocketPy Environment.create_ensemble"
dataset.history = (
f"Created {datetime.now(tz=pytz.UTC).isoformat()} by RocketPy"
)
dataset.comment = (
"Profiles are spatially constant across the 2 x 2 grid "
"surrounding the launch coordinates."
)
dataset.launch_latitude = self.latitude
dataset.launch_longitude = self.longitude
"""Write prepared ensemble data to an open GEFS-compatible dataset."""
dataset.Conventions = "CF-1.8"
dataset.title = "RocketPy user-defined atmospheric ensemble"
dataset.source = _USER_DEFINED_ENSEMBLE_SOURCE
dataset.history = f"Created {datetime.now(tz=pytz.UTC).isoformat()} by RocketPy"
dataset.comment = (
"Profiles are spatially constant across the 2 x 2 grid "
"surrounding the launch coordinates."
)
dataset.launch_latitude = self.latitude
dataset.launch_longitude = self.longitude

data_shape = self._create_ensemble_coordinates(
dataset, len(geopotential_heights), pressure_levels
)
self._create_ensemble_data_variables(
dataset, data_shape, geopotential_heights, member_values
)
data_shape = self._create_ensemble_coordinates(
dataset, len(geopotential_heights), pressure_levels
)
self._create_ensemble_data_variables(
dataset, data_shape, geopotential_heights, member_values
)

def create_ensemble(
self,
profiles,
file_name="custom_ensemble.nc",
file_name=None,
pressure_levels=None,
overwrite=False,
):
"""Create and activate an ensemble from user-defined profiles.

RocketPy writes the profiles with GEFS-compatible variable names.
Another Environment can load the returned file by passing
``type="Ensemble"`` and ``dictionary="GEFS"`` to
The profiles are not tied to a date, so the Environment does not need
one and the ensemble stays the same when the launch date changes. By
default nothing is written to disk. Pass ``file_name`` to also save
the ensemble: RocketPy writes the profiles with GEFS-compatible
variable names, and any other Environment, whatever its date, can load
the file by passing ``type="Ensemble"`` and ``dictionary="GEFS"`` to
:meth:`Environment.set_atmospheric_model`.

Parameters
Expand All @@ -3447,19 +3453,24 @@ def create_ensemble(
Pa for pressure, K for temperature and m/s for either wind
component. Array-backed :class:`rocketpy.Function` objects are also
accepted. Pressure must decrease strictly with increasing height.
Below the lowest height of a profile its lowest value is used, so
start the profiles at or below the ground level of the launch site.
file_name : str or os.PathLike, optional
Path of the NetCDF file to create. The ``.nc`` suffix is appended
when omitted. Default is ``"custom_ensemble.nc"``.
Path of a NetCDF file to save the ensemble in. The ``.nc`` suffix
is appended when omitted. Default is ``None``, which keeps the
ensemble in memory and writes no file.
pressure_levels : array-like, optional
Common pressure levels in Pa. By default, the union of sampled
pressure levels inside the range shared by every member is used.
overwrite : bool, optional
Whether an existing file may be replaced. Default is ``False``.
Whether an existing file may be replaced. Only used when
``file_name`` is given. Default is ``False``.

Returns
-------
str
Absolute path of the created NetCDF file.
str or None
Absolute path of the created NetCDF file, or None when no file was
asked for.

Raises
------
Expand All @@ -3470,26 +3481,46 @@ def create_ensemble(
missing, profiles are invalid, or the members have no usable common
pressure range.
FileExistsError
If the output exists and ``overwrite`` is ``False``.
If ``file_name`` exists and ``overwrite`` is ``False``.

Notes
-----
The first member is activated after the file is created. Use
The first member is activated. Use
:meth:`Environment.select_ensemble_member` to activate another member.
"""
self.__validate_datetime()
members = self._prepare_ensemble_profiles(profiles)
pressure_levels = self._prepare_ensemble_pressure_levels(
members, pressure_levels
)
geopotential_heights, member_values = self._interpolate_ensemble_profiles(
members, pressure_levels
)
file_path = self._prepare_ensemble_file_path(file_name, overwrite)
self._write_ensemble_file(
file_path, pressure_levels, geopotential_heights, member_values
)
ensemble = (pressure_levels, geopotential_heights, member_values)

if file_name is None:
# A dataset that only exists in memory: nothing is written to disk
dataset = netCDF4.Dataset(
"rocketpy_ensemble_in_memory.nc",
"w",
format="NETCDF4",
diskless=True,
persist=False,
)
try:
self._fill_ensemble_dataset(dataset, *ensemble)
self.set_atmospheric_model(
type="Ensemble", file=dataset, dictionary="GEFS"
)
finally:
if dataset.isopen():
dataset.close()
# There is no file to load the ensemble from again
self.atmospheric_model_file = str()
return None

file_path = self._prepare_ensemble_file_path(file_name, overwrite)
with netCDF4.Dataset(file_path, "w", format="NETCDF4") as dataset:
self._fill_ensemble_dataset(dataset, *ensemble)
self.set_atmospheric_model(type="Ensemble", file=file_path, dictionary="GEFS")
logger.info("Atmospheric ensemble saved at '%s'.", file_path)
return file_path
Expand Down Expand Up @@ -3562,14 +3593,19 @@ class for some dictionary examples.
wind-u, or wind-v variables cannot be read from the dataset.
"""
# Check if date, lat and lon are known
self.__validate_datetime()

# Read weather file
if isinstance(file, str):
data = netCDF4.Dataset(file)
else:
data = file

# Profiles given by the user have no date, so the Environment does not
# need one and the time written in their dataset is not checked.
from_profiles = getattr(data, "source", None) == _USER_DEFINED_ENSEMBLE_SOURCE
self._ensemble_from_profiles = from_profiles
if not from_profiles:
self.__validate_datetime()

dictionary = self.__resolve_dictionary_for_dataset(dictionary, data)

# Get time, latitude and longitude data from file
Expand Down Expand Up @@ -3599,7 +3635,10 @@ class for some dictionary examples.
target_lat = self.latitude

# Find time, latitude and longitude indexes
time_index = find_time_index(self.datetime_date, time_array)
if from_profiles:
time_index = 0
else:
time_index = find_time_index(self.datetime_date, time_array)
lon, lon_index = find_longitude_index(target_lon, lon_array)
_, lat_index = find_latitude_index(target_lat, lat_array)

Expand Down Expand Up @@ -3771,9 +3810,18 @@ class for some dictionary examples.
)

# Compute info data
self.atmospheric_model_init_date = get_initial_date_from_time_array(time_array)
self.atmospheric_model_end_date = get_final_date_from_time_array(time_array)
self.atmospheric_model_interval = get_interval_date_from_time_array(time_array)
if from_profiles:
self.atmospheric_model_init_date = None
self.atmospheric_model_end_date = None
self.atmospheric_model_interval = 0
else:
self.atmospheric_model_init_date = get_initial_date_from_time_array(
time_array
)
self.atmospheric_model_end_date = get_final_date_from_time_array(time_array)
self.atmospheric_model_interval = get_interval_date_from_time_array(
time_array
)
self.atmospheric_model_init_lat = float(lat_array[0])
self.atmospheric_model_end_lat = float(lat_array[len(lat_array) - 1])
self.atmospheric_model_init_lon = float(lon_array[0])
Expand Down Expand Up @@ -4325,6 +4373,7 @@ def to_dict(self, **kwargs):
"wind_speed_ensemble": getattr(self, "wind_speed_ensemble", None),
"num_ensemble_members": getattr(self, "num_ensemble_members", None),
"ensemble_member": getattr(self, "ensemble_member", None),
"ensemble_from_profiles": getattr(self, "_ensemble_from_profiles", False),
}

if kwargs.get("include_outputs", False):
Expand Down Expand Up @@ -4403,6 +4452,7 @@ def from_dict(cls, data): # pylint: disable=too-many-statements
env.wind_speed_ensemble = data["wind_speed_ensemble"]
env.num_ensemble_members = data["num_ensemble_members"]
env.ensemble_member = data.get("ensemble_member", 0) or 0
env._ensemble_from_profiles = data.get("ensemble_from_profiles", False)

env.__reset_barometric_height_function()
env.calculate_density_profile()
Expand Down
6 changes: 4 additions & 2 deletions rocketpy/prints/environment_prints.py
Original file line number Diff line number Diff line change
Expand Up @@ -117,8 +117,10 @@ def atmospheric_model_details(self):
init_date = self.environment.atmospheric_model_init_date
end_date = self.environment.atmospheric_model_end_date
interval = self.environment.atmospheric_model_interval
print(f"{model_type} Time Period: from {init_date} to {end_date} utc")
print(f"{model_type} Hour Interval: {interval} hrs")
# An ensemble created from profiles has no time period
if init_date is not None:
print(f"{model_type} Time Period: from {init_date} to {end_date} utc")
print(f"{model_type} Hour Interval: {interval} hrs")
# Determine latitude and longitude range
init_lat = self.environment.atmospheric_model_init_lat
end_lat = self.environment.atmospheric_model_end_lat
Expand Down
Loading
Loading