pycontrails 0.40.0__cp310-cp310-macosx_10_9_x86_64.whl → 0.40.1__cp310-cp310-macosx_10_9_x86_64.whl

pycontrails/_version.py

@@ -1,4 +1,4 @@
 # file generated by setuptools_scm
 # don't change, don't track in version control
-__version__ = version = '0.40.0'
-__version_tuple__ = version_tuple = (0, 40, 0)
+__version__ = version = '0.40.1'
+__version_tuple__ = version_tuple = (0, 40, 1)

pycontrails/core/met.py

@@ -94,7 +94,14 @@ class MetBase(ABC, Generic[XArrayType]):
         """
         for dim in self.dim_order:
             if dim not in self.data.dims:
-                raise ValueError(f"Meteorology data must contain dimension '{dim}'")
+                if dim == "level":
+                    raise ValueError(
+                        f"Meteorology data must contain dimension '{dim}'. "
+                        "For single level data, set 'level' coordinate to constant -1 "
+                        "using `ds = ds.expand_dims({'level': [-1]})`"
+                    )
+                else:
+                    raise ValueError(f"Meteorology data must contain dimension '{dim}'.")
 
     def _validate_longitude(self) -> None:
         """Check longitude bounds.
@@ -220,11 +227,12 @@ class MetBase(ABC, Generic[XArrayType]):
     def _preprocess_dims(self, wrap_longitude: bool) -> None:
         """Confirm DataArray or Dataset include required dimension in a consistent format.
 
-        Expects DataArray or Dataset to contain dimensions "latitude", "longitude", "time",
-        and "level" (in hPa/mbar). Adds additional coordinate variables ``air_pressure``
-        and ``altitude`` coordinates mapped to "level" dimension if "level" > 0.
+        Expects DataArray or Dataset to contain dimensions ``latitude`, ``longitude``, ``time``,
+        and ``level`` (in hPa/mbar).
+        Adds additional coordinate variables ``air_pressure`` and ``altitude`` coordinates
+        mapped to "level" dimension if "level" > 0.
 
-        Set "level" to -1 to signify surface level.
+        Set ``level`` to -1 to signify single level.
 
         .. versionchanged:: 0.40.0
 
@@ -280,7 +288,7 @@ class MetBase(ABC, Generic[XArrayType]):
         dim_order = self.dim_order + [d for d in self.data.dims if d not in self.dim_order]
         self.data = self.data.transpose(*dim_order)
 
-        # surface level data
+        # single level data
         if self.is_single_level:
             # add level attributes to reflect surface level
             self.data["level"].attrs.update(units="", long_name="Single Level")

pycontrails/core/models.py

@@ -147,12 +147,13 @@ class Model(ABC):
     #: Require meteorology is not None on __init__()
     met_required: bool = False
 
-    #: Required meteorology variables
-    #: Each element in the list is a MetVariable or a list[MetVariable].
-    #: If a list[MetVariable], only one variable in the list is required by input :attr:`met`.
+    #: Required meteorology pressure level variables.
+    #: Each element in the list is a :class:`MetVariable` or a ``tuple[MetVariable]``.
+    #: If element is a ``tuple[MetVariable]``, the variable depends on the data source.
+    #: Only one variable in the tuple is required.
     met_variables: tuple[MetVariable | tuple[MetVariable, ...], ...]
 
-    #: Minimal set of required parameters if processing already complete on met input.
+    #: Set of required parameters if processing already complete on ``met`` input.
     processed_met_variables: tuple[MetVariable, ...]
 
     #: Optional meteorology variables

pycontrails/datalib/ecmwf/era5.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import hashlib
 import logging
+import os
 import pathlib
 import warnings
 from contextlib import ExitStack
@@ -40,13 +41,16 @@ class ERA5(ECMWFAPI):
     `Copernicus Data Portal <https://cds.climate.copernicus.eu/cdsapp#!/home>`_
     and local credentials.
 
-    Local credentials can be specified in a ``~/.cdsapirc`` file
+    API credentials can be stored in a ``~/.cdsapirc`` file
     or as ``CDSAPI_URL`` and ``CDSAPI_KEY`` environment variables.
 
-
         export CDSAPI_URL=...
         export CDSAPI_KEY=...
 
+    Credentials can also be provided directly ``url`` and ``key`` keyword args.
+
+    See `cdsapi <https://github.com/ecmwf/cdsapi>`_ documentation
+    for more information.
 
     Parameters
     ----------
@@ -80,6 +84,10 @@ class ERA5(ECMWFAPI):
         Cache data store for staging ECMWF ERA5 files.
         Defaults to :class:`cache.DiskCacheStore`.
         If None, cache is turned off.
+    url : str
+        Override `cdsapi <https://github.com/ecmwf/cdsapi>`_ url
+    key : str
+        Override `cdsapi <https://github.com/ecmwf/cdsapi>`_ key
 
     Notes
     -----
@@ -93,7 +101,6 @@ class ERA5(ECMWFAPI):
     Local ``paths`` are loaded using :func:`xarray.open_mfdataset`.
     Pass ``xr_kwargs`` inputs to :meth:`open_metdataset` to customize file loading.
 
-
     Examples
     --------
     >>> from datetime import datetime
@@ -120,14 +127,22 @@ class ERA5(ECMWFAPI):
     __slots__ = (
         "product_type",
         "cds",
+        "url",
+        "key",
     )
 
     #: Product type, one of "reanalysis", "ensemble_mean", "ensemble_members", "ensemble_spread"
     product_type: str
 
-    #: Handle to CDSAPI client
+    #: Handle to ``cdsapi.Client``
     cds: cdsapi.Client
 
+    #: User provided ``cdsapi.Client`` url
+    url: str | None
+
+    #: User provided ``cdsapi.Client`` url
+    key: str | None
+
     __marker = object()
 
     def __init__(
@@ -140,6 +155,8 @@ class ERA5(ECMWFAPI):
         product_type: str = "reanalysis",
         grid: float = 0.25,
         cachestore: cache.CacheStore | None = __marker,  # type: ignore[assignment]
+        url: str | None = None,
+        key: str | None = None,
     ):
         # inputs
         self.product_type = product_type
@@ -147,6 +164,8 @@ class ERA5(ECMWFAPI):
             cachestore = cache.DiskCacheStore()
         self.cachestore = cachestore
         self.paths = paths
+        self.url = url or os.environ.get("CDSAPI_URL", None)
+        self.key = key or os.environ.get("CDSAPI_KEY", None)
 
         if time is None and paths is None:
             raise ValueError("Time input is required when paths is None")
@@ -504,7 +523,7 @@ class ERA5(ECMWFAPI):
                     ) from e
 
                 try:
-                    self.cds = cdsapi.Client()
+                    self.cds = cdsapi.Client(url=self.url, key=self.key)
                 # cdsapi throws base-level Exception
                 except Exception as err:
                     raise CDSCredentialsNotFound from err

pycontrails/datalib/ecmwf/hres.py

@@ -102,7 +102,9 @@ def get_forecast_filename(
 class HRES(ECMWFAPI):
     """Class to support HRES data access, download, and organization.
 
-    Requires account with ECMWF and API key set in local ``~/.ecmwfapirc`` file:
+    Requires account with ECMWF and API key.
+
+    API credentials set in local ``~/.ecmwfapirc`` file:
 
     .. code:: json
 
@@ -112,7 +114,9 @@ class HRES(ECMWFAPI):
             "key": "<key>"
         }
 
-    See `ECMWF Web API <https://www.ecmwf.int/en/computing/software/ecmwf-web-api>`_ documentation
+    Credentials can also be provided directly ``url`` ``key``, and ``email`` keyword args.
+
+    See `ecmwf-api-client <https://github.com/ecmwf/ecmwf-api-client>`_ documentation
     for more information.
 
     Parameters
@@ -154,7 +158,12 @@ class HRES(ECMWFAPI):
         Cache data store for staging data files.
         Defaults to :class:`cache.DiskCacheStore`.
         If None, cache is turned off.
-
+    url : str
+        Override `ecmwf-api-client <https://github.com/ecmwf/ecmwf-api-client>`_ url
+    key : str
+        Override `ecmwf-api-client <https://github.com/ecmwf/ecmwf-api-client>`_ key
+    email : str
+        Override `ecmwf-api-client <https://github.com/ecmwf/ecmwf-api-client>`_ email
 
     Notes
     -----
@@ -211,7 +220,7 @@ class HRES(ECMWFAPI):
     ... )
     """
 
-    __slots__ = ("server", "stream", "field_type", "forecast_time")
+    __slots__ = ("server", "stream", "field_type", "forecast_time", "url", "key", "email")
 
     #: stream type, "oper" = atmospheric model/HRES, "enfo" = ensemble forecast.
     stream: str
@@ -226,6 +235,15 @@ class HRES(ECMWFAPI):
     #: Forecast run time, either specified or assigned by the closest previous forecast run
     forecast_time: datetime
 
+    #: User provided ``ECMWFService`` url
+    url: str | None
+
+    #: User provided ``ECMWFService`` key
+    key: str | None
+
+    #: User provided ``ECMWFService`` email
+    email: str | None
+
     __marker = object()
 
     def __init__(
@@ -240,6 +258,9 @@ class HRES(ECMWFAPI):
         field_type: str = "fc",
         forecast_time: DatetimeLike | None = None,
         cachestore: cache.CacheStore | None = __marker,  # type: ignore[assignment]
+        url: str | None = None,
+        key: str | None = None,
+        email: str | None = None,
     ) -> None:
         try:
             from ecmwfapi import ECMWFService
@@ -252,7 +273,10 @@ class HRES(ECMWFAPI):
         # constants
         # ERA5 now delays creating the server attribute until it is needed to download
         # from CDS. We could do the same here.
-        self.server = ECMWFService("mars")
+        self.url = url
+        self.key = key
+        self.email = email
+        self.server = ECMWFService("mars", url=self.url, key=self.key, email=self.email)
         self.paths = paths
         if cachestore is self.__marker:
             cachestore = cache.DiskCacheStore()

pycontrails/models/cocip/cocip.py

@@ -45,9 +45,11 @@ class Cocip(Model):
     Parameters
     ----------
     met : MetDataset
-        Dataset containing  :attr:`met_variables` variables.
+        Pressure level dataset containing :attr:`met_variables` variables.
+        See *Notes* for variable names by data source.
     rad : MetDataset
-        Radiation dataset
+        Single level dataset containing top of atmosphere radiation fluxes.
+        See *Notes* for variable names by data source.
     params : dict[str, Any], optional
         Override Cocip model parameters with dictionary.
         See :class:`CocipFlightParams` for model parameters.
@@ -57,6 +59,59 @@ class Cocip(Model):
 
     Notes
     -----
+    **Inputs**
+
+    The required meteorology variables depend on the data source (e.g. ECMWF, GFS).
+
+    See :attr:`met_variables` and :attr:`rad_variables` for the list of required variables
+    to the ``met`` and ``rad`` inputs, respectively.
+    When an item in one of these arrays is a tuple, variable keys depend on data source.
+
+    The current list of required variables (labelled by ``"standard_name"``):
+
+    .. list-table:: Variable keys for pressure level data
+        :header-rows: 1
+
+        * - Parameter
+          - ECMWF
+          - GFS
+        * - Air Temperature
+          - ``air_temperature``
+          - ``air_temperature``
+        * - Specific Humidity
+          - ``specific_humidity``
+          - ``specific_humidity``
+        * - Eastward wind
+          - ``eastward_wind``
+          - ``eastward_wind``
+        * - Northward wind
+          - ``northward_wind``
+          - ``northward_wind``
+        * - Vertical velocity
+          - ``lagrangian_tendency_of_air_pressure``
+          - ``lagrangian_tendency_of_air_pressure``
+        * - Ice water content
+          - ``specific_cloud_ice_water_content``
+          - ``ice_water_mixing_ratio``
+        * - Geopotential
+          - ``geopotential``
+          - ``geopotential_height``
+
+    .. list-table:: Variable keys for single-level radiation data
+        :header-rows: 1
+
+        * - Parameter
+          - ECMWF
+          - GFS
+        * - Top solar radiation
+          - ``top_net_solar_radiation``
+          - ``toa_upward_shortwave_flux``
+        * - Top thermal radiation
+          - ``top_net_thermal_radiation``
+          - ``toa_upward_longwave_flux``
+
+    **Modifications**
+
     This implementation differs from original CoCiP (Fortran) implementation in a few places:
 
     - This model uses aircraft performance and emissions models to calculate nvPM, fuel flow,
@@ -96,6 +151,8 @@ class Cocip(Model):
     results from :cite:`teohAviationContrailClimate2022`.
     See `tests/benchmark/north-atlantic-study/validate.py`.
 
+    **Outputs**
+
     NaN values may appear in model output. Specifically, `np.nan` values are used to indicate:
 
     - Flight waypoint or contrail waypoint is not contained with the :attr:`met` domain.
@@ -108,6 +165,10 @@ class Cocip(Model):
 
     References
     ----------
+    - :cite:`schumannDeterminationContrailsSatellite1990`
+    - :cite:`schumannContrailCirrusPrediction2010`
+    - :cite:`voigtInsituObservationsYoung2010`
+    - :cite:`schumannPotentialReduceClimate2011a`
     - :cite:`schumannContrailCirrusPrediction2012`
     - :cite:`schumannParametricRadiativeForcing2012`
     - :cite:`schumannContrailsVisibleAviation2012`
@@ -154,15 +215,16 @@ class Cocip(Model):
         (met_var.Geopotential, met_var.GeopotentialHeight),
     )
 
-    #: Required radiation (single level) variables for model
+    #: Required single-level top of atmosphere radiation variables.
+    #: Variable keys depend on data source (e.g. ECMWF, GFS).
     rad_variables = (
         (ecmwf.TopNetSolarRadiation, gfs.TOAUpwardShortwaveRadiation),
         (ecmwf.TopNetThermalRadiation, gfs.TOAUpwardLongwaveRadiation),
     )
 
-    #: Minimal set of met variables needed to run the model after preprocessing
-    #: The intention here is that geopotential and sciwc are unnecessary after
-    #: tau cirrus has already been calculated.
+    #: Minimal set of met variables needed to run the model after pre-processing.
+    #: The intention here is that ``geopotential`` and ``ciwc`` are unnecessary after
+    #: ``tau_cirrus`` has already been calculated.
     processed_met_variables = (
         met_var.AirTemperature,
         met_var.SpecificHumidity,

{pycontrails-0.40.0.dist-info → pycontrails-0.40.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pycontrails
-Version: 0.40.0
+Version: 0.40.1
 Summary: Python library for modeling aviation climate impacts
 Author-email: Breakthrough Energy <py@contrails.org>
 License: Apache-2.0

{pycontrails-0.40.0.dist-info → pycontrails-0.40.1.dist-info}/RECORD

@@ -1,29 +1,29 @@
-pycontrails-0.40.0.dist-info/RECORD,,
-pycontrails-0.40.0.dist-info/LICENSE,sha256=gJ-h7SFFD1mCfR6a7HILvEtodDT6Iig8bLXdgqR6ucA,10175
-pycontrails-0.40.0.dist-info/WHEEL,sha256=doY7Ynwndq62v9G9yH4QQiKEI6qNEsMeVrkmo76vHLE,111
-pycontrails-0.40.0.dist-info/NOTICE,sha256=gKI8DcN1WhiXB2SFRKDogcjONldGubTvBxiOYdC4CXU,1926
-pycontrails-0.40.0.dist-info/top_level.txt,sha256=Z8J1R_AiBAyCVjNw6jYLdrA68PrQqTg0t3_Yek_IZ0Q,29
-pycontrails-0.40.0.dist-info/METADATA,sha256=hkJ7OO2NnXLn2E-ZPYSR7JIDTzILwyU67IxMj3RkqYA,8291
-pycontrails/_version.py,sha256=gWVz7kYkjvWUgegETRrPqz0hpRYbz2Brc0ekOeULhdI,162
+pycontrails-0.40.1.dist-info/RECORD,,
+pycontrails-0.40.1.dist-info/LICENSE,sha256=gJ-h7SFFD1mCfR6a7HILvEtodDT6Iig8bLXdgqR6ucA,10175
+pycontrails-0.40.1.dist-info/WHEEL,sha256=doY7Ynwndq62v9G9yH4QQiKEI6qNEsMeVrkmo76vHLE,111
+pycontrails-0.40.1.dist-info/NOTICE,sha256=gKI8DcN1WhiXB2SFRKDogcjONldGubTvBxiOYdC4CXU,1926
+pycontrails-0.40.1.dist-info/top_level.txt,sha256=Z8J1R_AiBAyCVjNw6jYLdrA68PrQqTg0t3_Yek_IZ0Q,29
+pycontrails-0.40.1.dist-info/METADATA,sha256=Oe51rO4DRHIm5lSgR78bisV9Wx5XCA0E7Xo021uhVm8,8291
+pycontrails/_version.py,sha256=Uv7Kv0aTKGB_HcctAoescgkUZZANf1_pdzcWwwttsDc,162
 pycontrails/__init__.py,sha256=sf7Xhr91V2jAvcQkla9oPqNCaXSKQp2M_dcxkiVkl6w,1943
 pycontrails/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pycontrails/core/vector.py,sha256=nd1shWNp3A7ebihYgiUF-SHEtk_gpuuj65KBpCMpK7Q,57940
-pycontrails/core/models.py,sha256=6vyP8E0RsX17Dyo73TcaCqGnHi2N2gzv_C0BmvmHK0A,26722
+pycontrails/core/models.py,sha256=eapTP-JlMgfXVvvLn3WcbushGpCRgbUp3u25sgwi9IU,26792
 pycontrails/core/interpolation.py,sha256=3SK7xE0ChmCc7Ev4uM1saUF3LhS7h0mqNMk4qR3XxwY,24032
 pycontrails/core/fleet.py,sha256=7BqRWNWAHhtpYsGSslYiMo1Zk4cM9vJe_L7UrZHi2dM,12341
-pycontrails/core/rgi_cython.cpython-310-darwin.so,sha256=LZMCM8Q-T07DDUam-IaPIwmvZ16nthZgxTuOUS1lDgo,286896
+pycontrails/core/rgi_cython.cpython-310-darwin.so,sha256=CowO5ca3MsYZzNK02wtNWho-g8aJamVUWlXGl4PpM4w,286896
 pycontrails/core/flight.py,sha256=o6LfqDhd2WRbVEiPxKU263dZvfrjH0JieRY1-LmqjGw,49611
 pycontrails/core/fuel.py,sha256=lEMUgLeFBoazDsiKN07s9udQ12xghOos5v3H9bjveBs,4044
 pycontrails/core/polygon.py,sha256=mkpvZ7y5M-3lJAYyM_-LJQuUwVuVUVz6P1ZbEGMU0NU,18361
 pycontrails/core/datalib.py,sha256=JVI1rGndJ6GgcfbVI8f3jpk1nROILvc2jCYumfCmEFI,21346
 pycontrails/core/cache.py,sha256=uMzN45MUgIni1uhlypLVjc0NhFDvn6m-uK78p9sDdE8,28536
 pycontrails/core/__init__.py,sha256=C6bOLNBKeQaLCHCRza1oPrQTUazutPST7hX4C6O2MG0,866
-pycontrails/core/met.py,sha256=sS6mx_Qsj26kWM1ufH57pNU0PMUFnA0vZa2FNrELNhQ,86908
+pycontrails/core/met.py,sha256=bEFiBItpxNzF0-HsTHcy4KqdJ4RvgkoPHxC1cjSXDfA,87281
 pycontrails/core/met_var.py,sha256=-gaodcmxx507ryMVKvFclqKkf1c8OHVVtXeG9s2eOOs,9191
 pycontrails/core/coordinates.py,sha256=b7D2lknnnwh8rBSla9M3ojqRYiASAOrVv0OAFD8xpDw,5078
 pycontrails/datalib/__init__.py,sha256=xcEVKnOmDvtswY6SQgiSVAWmx4YMTaqZECSnDzsTbEQ,200
-pycontrails/datalib/ecmwf/era5.py,sha256=_Kx4MY1NsRFsZ4jBSuObcLbE-M9g6hvE_yk6Ufg3Z14,18882
-pycontrails/datalib/ecmwf/hres.py,sha256=1pyVbUa83Od49Rv9eO6HFoNamM1rK1V9G2NTQXw7DIo,29499
+pycontrails/datalib/ecmwf/era5.py,sha256=ulII_wQDSLmaqpMdZpAlOCmCCxhpzfSdBBgb8NW4ioA,19590
+pycontrails/datalib/ecmwf/hres.py,sha256=wnGSZ67fnJ7NOw4hZXk3UCNcfFvShK1pWMm4nx0fz6c,30333
 pycontrails/datalib/ecmwf/variables.py,sha256=akqjUS3WKnSzV1Y0KkHLylH7QByvitc3wo8NBFeSNew,8714
 pycontrails/datalib/ecmwf/__init__.py,sha256=9rrlhfePtMrkofmFMg7t9fJ3teVufRJ0uM3Y-2PdzQ4,1045
 pycontrails/datalib/ecmwf/common.py,sha256=MCIFgGPnjb9tzjia4QzyPxIOAZBBqmpb4ucmua-B62Q,4890
@@ -56,7 +56,7 @@ pycontrails/models/emissions/static/edb-gaseous-v28c-engines.csv,sha256=9mok7P9N
 pycontrails/models/emissions/static/edb-nvpm-v28c-engines.csv,sha256=otZ3PWXcbu7ZuEgZ3v3bLB0CGjGRAacd69CGFUXAdSU,63472
 pycontrails/models/cocip/radiative_forcing.py,sha256=ReLufq2BWw_Vot18MIBkTkaOqNXrbGyGcoZnAwO0NOg,28853
 pycontrails/models/cocip/wind_shear.py,sha256=g6T_ZL77Vs7kxagrp6o_nFpycbnc5SyA4PBL1DOD0nA,3735
-pycontrails/models/cocip/cocip.py,sha256=hW0-ub6cSQyUm_qeh6OqEAAYrBAqO83Oz3_7cu_LnNA,84410
+pycontrails/models/cocip/cocip.py,sha256=PDnMfZZ7FXqd5r-WWtQCZurD_FyLIvcY2qBELw0YXZE,86552
 pycontrails/models/cocip/__init__.py,sha256=vBicDVNyw-M3bglx1iVplxm6CQRPRk5SS-3_VgL7WQM,370
 pycontrails/models/cocip/cocip_params.py,sha256=0624P6cVc2vBeD8-2S3lMnfZtKkdOaycGhscgyp_nYo,9098
 pycontrails/models/cocip/wake_vortex.py,sha256=mH8qbuWvZlFzmjBokHp6TAIgii6wVXvaV_xmHzb34MI,11654