pycontrails 0.49.3__tar.gz → 0.49.5__tar.gz

{pycontrails-0.49.3 → pycontrails-0.49.5}/CHANGELOG.md

@@ -1,6 +1,45 @@
 
 # Changelog
 
+## v0.49.5
+
+## Fixes
+
+- Fix bug where `Cocip._process_rad` lost radiation dataset attributes
+
+## v0.49.4
+
+### Breaking changes
+
+- Remove the `CocipGridParams.met_slice_dt` parameter. Now met downselection is handled automatically during contrail evolution. When the `met` and `rad` data passed into `CocipGrid` are not already loaded into memory, this update may make `CocipGrid` slightly more performant.
+- No longer explicitly load `met` and `rad` time slices into memory in `CocipGrid`. This now only occurs downstream when interpolation is performed. This change better aligns `CocipGrid` with other pycontrails models.
+- Remove the `cocipgrid.cocip_time_handling` module. Any useful tooling has been moved directly to the `cocipgrid.cocip_grid` module.
+- Remove the `CocipGrid.timedict` attribute. Add a `CocipGrid.timesteps` attribute. This is now applied in the same manner that the `Cocip` model uses its `timesteps` attribute.
+- Simplify the runtime estimate used in constructing the `CocipGrid` `tqdm` progress bar. The new estimate is less precise than the previous estimate and should not be trusted for long-running simulations.
+- Deprecate `MetBase.variables` in favor of `MetBase.indexes`.
+
+### Features
+
+- Add support for 9 additional aircraft types in the [Poll-Schumann](https://py.contrails.org/notebooks/AircraftPerformance.html) (PS) aircraft performance model. The new aircraft types are:
+  - A338
+  - A339
+  - A35K
+  - B37M
+  - B38M
+  - B39M
+  - B78X
+  - BCS1
+  - BCS3
+- Modify PS coefficients for B788, B789, and A359.
+- Support running `CocipGrid` on meteorology data without a uniformly-spaced time dimension. The `CocipGrid` implementation now no longer assumes `met["time"].diff()` is constant.
+- Add a `MetDataset.downselect_met` method. This performs a met downselection in analogy with `GeoVectorDataset.downselect_met`.
+
+### Fixes
+
+- Improve clarity of warnings produced when meteorology data doesn't cover the time range required by a gridded CoCiP model.
+- No longer emit `pandas` warning when `Flight.resample_and_fill(..., drop=True, ...)` is called with non-float data.
+- Correctly handle `CocipGrid` `rad` data with non-uniform time steps.
+
 ## v0.49.3
 
 ### Features

{pycontrails-0.49.3 → pycontrails-0.49.5}/Makefile

@@ -21,8 +21,8 @@ END_COLOR = \033[0m
 # the latest open3d and accf packages often don't support the latest
 # versions of python
 pip-install:
-	pip install -U pip wheel
-	pip install -e ".[complete]"
+	python -m pip install -U pip wheel
+	python -m pip install -e ".[complete]"
 
 	# these still must be installed manually for Python < 3.10
 	# -pip install -e ".[open3d]"
@@ -30,7 +30,7 @@ pip-install:
 # development installation
 dev-install: pip-install
 
-	pip install -e ".[dev,docs]"
+	python -m pip install -e ".[dev,docs]"
 
 	# install pre-commit
 	pre-commit install

{pycontrails-0.49.3/pycontrails.egg-info → pycontrails-0.49.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pycontrails
-Version: 0.49.3
+Version: 0.49.5
 Summary: Python library for modeling aviation climate impacts
 Author-email: Breakthrough Energy <py@contrails.org>
 License: Apache-2.0
@@ -36,7 +36,7 @@ Requires-Dist: xarray>=2022.3
 Provides-Extra: complete
 Requires-Dist: pycontrails[ecmwf,gcp,gfs,goes,jupyter,pyproj,vis,zarr]; extra == "complete"
 Provides-Extra: dev
-Requires-Dist: black[jupyter]==24.1.1; extra == "dev"
+Requires-Dist: black[jupyter]==24.2.0; extra == "dev"
 Requires-Dist: dep_license; extra == "dev"
 Requires-Dist: fastparquet>=0.8; extra == "dev"
 Requires-Dist: ipdb>=0.13; extra == "dev"

{pycontrails-0.49.3 → pycontrails-0.49.5}/docs/api.rst

@@ -118,6 +118,16 @@ CoCiP
     models.cocip.wind_shear
 
 
+Gridded CoCiP
+"""""""""""""
+
+.. autosummary::
+    :toctree: api/
+
+    models.cocipgrid.CocipGrid
+    models.cocipgrid.CocipGridParams
+
+
 ACCF
 """"
 
@@ -134,8 +144,6 @@ ACCF
 Aircraft Performance
 """"""""""""""""""""
 
-*In development*
-
 .. autosummary::
     :toctree: api/
 

{pycontrails-0.49.3 → pycontrails-0.49.5}/docs/develop.rst

@@ -34,7 +34,7 @@ Python, create a dedicated Anaconda environment:
 .. code-block:: bash
 
     # create conda environment
-    $ conda create -n contrails python=3.10
+    $ conda create -n contrails
 
     # activate environment
     $ conda activate contrails
@@ -132,10 +132,10 @@ Notebook validation and doctests require `Copernicus Climate Data Store (CDS) cr
 Documentation
 -------------
 
-Documentation is written in `reStructuredText <https://docutils.sourceforge.io/rst.html>`__
+Documentation is written in `reStructuredText (rst) <https://docutils.sourceforge.io/rst.html>`__
 and built with `Sphinx <https://www.sphinx-doc.org/en/master/>`__. The `quick reStructuredText
 reference <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`__
-provides a basic overview.
+provides a decent rst syntax overview.
 
 Sphinx includes many additional
 `roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__,
@@ -145,7 +145,7 @@ and
 to enhance documentation.
 
 Sphinx configuration is written in `docs/conf.py <https://github.com/contrailcirrus/pycontrails/blob/main/docs/conf.py>`__.
-See `Sphinx configuration docs <https://www.sphinx-doc.org/en/master/usage/configuration.html>`__ for the full list of configuration options.
+See the `Sphinx configuration docs <https://www.sphinx-doc.org/en/master/usage/configuration.html>`__ for the full list of configuration options.
 
 Build HTML documentation:
 
@@ -227,17 +227,17 @@ To build manually, run:
 References
 ~~~~~~~~~~
 
+Literature references managed in the `pycontrails Zotero library <https://www.zotero.org/groups/4730892/pycontrails/library>`__.
+
 The documentation uses
 `sphinxcontrib-bibtex <https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html>`__
 to include citations and a bibliography.
 
 All references should be cited through documentation and docstrings
-using the ```:cite:``
-directive <https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#role-cite>`__.
+using the `:cite: role <https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#role-cite>`__.
 
-Literature references managed in the `pycontrails Zotero library <https://www.zotero.org/groups/4730892/pycontrails/library>`__.
 
-To automatically sync this library with the
+To automatically sync the Zotero library with the
 `docs/_static/pycontrails.bib <https://github.com/contrailcirrus/pycontrails/blob/main/docs/_static/pycontrails.bib>`__ Bibtex file:
 
 - Install `Zotero <https://www.zotero.org/>`__ and add the `pycontrails library <https://www.zotero.org/groups/4730892/pycontrails/library>`__.
@@ -277,10 +277,10 @@ Test notebook examples with `nbval pytest plugin <https://github.com/computation
 
 
 Conventions
-===========
+-----------
 
 Code
-----
+~~~~
 
 ``pycontrails`` aims to implement clear, consistent, performant data
 structures and models.
@@ -297,8 +297,7 @@ pre-commit hook.
 The project uses `pytest <https://docs.pytest.org/en/7.2.x/>`__ to run
 unit tests. New code should include clear unit tests for implementation
 and output values. New test files should be included in the
-```/tests/unit/``
-directory <https://github.com/contrailcirrus/pycontrails/tree/main/tests/unit>`__.
+`/tests/unit/ directory <https://github.com/contrailcirrus/pycontrails/tree/main/tests/unit>`__.
 
 The project uses `Github
 Actions <https://github.com/contrailcirrus/pycontrails/actions>`__ to
@@ -310,7 +309,7 @@ before pushing using:
    $ make test
 
 Docstrings
-----------
+~~~~~~~~~~
 
 Wherever possible, we adhere to the `NumPy docstring
 conventions <https://numpydoc.readthedocs.io/en/latest/format.html>`__.
@@ -333,7 +332,7 @@ General guidelines:
    Variable, module, function, and class names
    should be written between single back-ticks (`numpy`).
 
-When you specify a type in **Parameters** or **See Also**, Sphinx will
+When specifying types in **Parameters** or **See Also**, Sphinx will
 automatically replace the text with the ``napolean_type_aliases``
 specified in
 `conf.py <https://github.com/contrailcirrus/pycontrails/blob/main/docs/conf.py>`__,
@@ -364,7 +363,8 @@ The **See Also** section is *not a list*. All of the following work:
 
 When you specify a type outside of **Parameters**, you have to use the
 `sphinx cross-referencing
-syntax <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects>`__:
+syntax <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects>`__
+with the full module name:
 
 .. code:: python
 

{pycontrails-0.49.3 → pycontrails-0.49.5}/docs/notebooks/GFS.ipynb

@@ -796,7 +796,7 @@
    "source": [
     "## Run CoCiP with GFS\n",
     "\n",
-    "See the [CoCiP Notebook](https://py.contrails.org/examples/CoCiP.html) for more details on running the CoCiP model."
+    "See the [CoCiP Notebook](https://py.contrails.org/notebooks/CoCiP.html) for more details on running the CoCiP model."
    ]
   },
   {

{pycontrails-0.49.3 → pycontrails-0.49.5}/docs/notebooks.rst

@@ -4,18 +4,53 @@
 Running Notebooks
 =================
 
-The `/docs <https://github.com/contrailcirrus/pycontrails/tree/main/docs>`__
+The `/docs/notebooks <https://github.com/contrailcirrus/pycontrails/tree/main/docs/notebooks>`__
 directory in the repository contains `Jupyter Notebooks <https://jupyter.org/>`__
 demonstrating ``pycontrails``.
 
-To run these notebooks interactively, clone or download the repository,
+Local
+-----
+
+To run these notebooks locally, clone or download the repository,
 enter the ``docs`` directory, and launch ``jupyter lab``:
 
 .. code:: bash
 
    $ git clone https://github.com/contrailcirrus/pycontrails.git
    $ cd pycontrails/docs
-   $ jupyter lab
+   $ jupyter lab        # or notebook
+
+If you don't have `Jupyter installed <https://jupyter.org/install>`__,
+install the optional ``pycontrails[jupyter]`` dependencies:
+
+.. code-block:: bash
+
+    $ pip install "pycontrails[jupyter]"  # Jupyter notebook and lab interface
+
+Colab
+-----
+
+Notebooks can also be opened in `Google Colab <https://colab.research.google.com>`__.
+Select *File* -> *Open* -> **Github**, enter ``contrailcirrus/pycontrails``, then
+select the Notebook to open.
+
+.. image:: _static/img/colab.png
+  :alt: Colab example
+
+Alternatively, any notebook directly with the url ``https://colab.research.google.com/github/``
++ the path to the notebook file on github.com
+(e.g. `CoCiP.ipynb
+<https://colab.research.google.com/github/contrailcirrus/pycontrails/blob/main/docs/notebooks/CoCiP.ipynb>`__)
+
+``pycontrails`` must be installed into Colab environment by adding the top cell:
+
+.. code:: bash
+
+   !pip install pycontrails
+
+Credentials and data must be added to each Colab environment.
+Colab integrates with Google Drive to `load and save data <https://colab.research.google.com/notebooks/io.ipynb>`__
+and `store secrets <https://medium.com/@parthdasawant/how-to-use-secrets-in-google-colab-450c38e3ec75>`__.
 
 Data
 ----

{pycontrails-0.49.3 → pycontrails-0.49.5}/pycontrails/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.49.3'
-__version_tuple__ = version_tuple = (0, 49, 3)
+__version__ = version = '0.49.5'
+__version_tuple__ = version_tuple = (0, 49, 5)

{pycontrails-0.49.3 → pycontrails-0.49.5}/pycontrails/core/datalib.py

@@ -353,7 +353,7 @@ class MetDataSource(abc.ABC):
         self,
         time: TimeInput | None,
         variables: VariableInput,
-        pressure_levels: PressureLevelInput = [-1],
+        pressure_levels: PressureLevelInput = -1,
         paths: str | list[str] | pathlib.Path | list[pathlib.Path] | None = None,
         grid: float | None = None,
         **kwargs: Any,

{pycontrails-0.49.3 → pycontrails-0.49.5}/pycontrails/core/flight.py

@@ -936,8 +936,7 @@ class Flight(GeoVectorDataset):
 
         # Remove original index if requested
         if not keep_original_index:
-            filt = df.index.isin(t)
-            df = df.loc[filt]
+            df = df.loc[t]
 
         # finally reset index
         df = df.reset_index()
@@ -1200,11 +1199,13 @@ class Flight(GeoVectorDataset):
         dict[str, Any]
             Python representation of geojson FeatureCollection
         """
-        points = _return_linestring({
-            "longitude": self["longitude"],
-            "latitude": self["latitude"],
-            "altitude": self.altitude,
-        })
+        points = _return_linestring(
+            {
+                "longitude": self["longitude"],
+                "latitude": self["latitude"],
+                "altitude": self.altitude,
+            }
+        )
         geometry = {"type": "LineString", "coordinates": points}
         properties = {
             "start_time": self.time_start.isoformat(),
@@ -2041,7 +2042,7 @@ def _resample_to_freq(df: pd.DataFrame, freq: str) -> tuple[pd.DataFrame, pd.Dat
     """Resample a DataFrame to a given frequency.
 
     This function is used to resample a DataFrame to a given frequency. The new
-    index will include all the original index values and the new esampled-to-freq
+    index will include all the original index values and the new resampled-to-freq
     index values. The "longitude" and "latitude" columns will be linearly interpolated
     to the new index values.
 
@@ -2064,7 +2065,7 @@ def _resample_to_freq(df: pd.DataFrame, freq: str) -> tuple[pd.DataFrame, pd.Dat
     # and the resampled-to-freq index values.
     t0 = df.index[0]
     t1 = df.index[-1]
-    t = pd.date_range(t0, t1, freq=freq).floor(freq)
+    t = pd.date_range(t0, t1, freq=freq, name="time").floor(freq)
     if t[0] < t0:
         t = t[1:]
 
@@ -2072,8 +2073,7 @@ def _resample_to_freq(df: pd.DataFrame, freq: str) -> tuple[pd.DataFrame, pd.Dat
     concat_arr = np.unique(concat_arr)
     concat_index = pd.DatetimeIndex(concat_arr, name="time", copy=False)
 
-    out = pd.DataFrame(index=concat_index, columns=df.columns, dtype=float)
-    out.loc[df.index] = df
+    out = df.reindex(concat_index)
 
     # Linearly interpolate small horizontal gap
     coords = ["longitude", "latitude"]

{pycontrails-0.49.3 → pycontrails-0.49.5}/pycontrails/core/interpolation.py

@@ -66,7 +66,8 @@ class PycontrailsRegularGridInterpolator(scipy.interpolate.RegularGridInterpolat
         fill_value: float | np.float64 | None,
     ):
         if values.dtype not in (np.float32, np.float64):
-            raise ValueError("values must be a float array")
+            msg = f"values must be a float array, not {values.dtype}"
+            raise ValueError(msg)
 
         self.grid = points
         self.values = values
@@ -94,7 +95,8 @@ class PycontrailsRegularGridInterpolator(scipy.interpolate.RegularGridInterpolat
                 g0 = self.grid[i][0]
                 g1 = self.grid[i][-1]
                 if not (np.all(p >= g0) and np.all(p <= g1)):
-                    raise ValueError(f"One of the requested xi is out of bounds in dimension {i}")
+                    msg = f"One of the requested xi is out of bounds in dimension {i}"
+                    raise ValueError(msg)
 
             return np.zeros(xi.shape[0], dtype=bool)
 
@@ -213,7 +215,8 @@ class PycontrailsRegularGridInterpolator(scipy.interpolate.RegularGridInterpolat
             # np.interp could be better ... although that may also promote the dtype
             return rgi_cython.evaluate_linear_1d(values, indices, norm_distances, out)
 
-        raise ValueError(f"Invalid number of dimensions: {ndim}")
+        msg = f"Invalid number of dimensions: {ndim}"
+        raise ValueError(msg)
 
 
 def _floatize_time(
@@ -442,18 +445,16 @@ def interp(
         coords = {"longitude": longitude, "latitude": latitude, "level": level, "time": time}
         da = _localize(da, coords)
 
-    # Using da.coords.variables is slightly more performant than da["longitude"].values
-    variables = da.coords.variables
-    x = variables["longitude"].values
-    y = variables["latitude"].values
-    z = variables["level"].values
+    indexes = da._indexes
+    x = indexes["longitude"].index.to_numpy()  # type: ignore[attr-defined]
+    y = indexes["latitude"].index.to_numpy()  # type: ignore[attr-defined]
+    z = indexes["level"].index.to_numpy()  # type: ignore[attr-defined]
     if any(v.dtype != np.float64 for v in (x, y, z)):
-        raise ValueError(
-            "da must have float64 dtype for longitude, latitude, and level coordinates"
-        )
+        msg = "da must have float64 dtype for longitude, latitude, and level coordinates"
+        raise ValueError(msg)
 
     # Convert t and time to float64
-    t = variables["time"].values
+    t = indexes["time"].index.to_numpy()  # type: ignore[attr-defined]
     offset = t[0]
     t = _floatize_time(t, offset)
 
@@ -526,9 +527,11 @@ def _linear_interp_with_indices(
     indices: RGIArtifacts | None,
 ) -> tuple[npt.NDArray[np.float64], RGIArtifacts]:
     if interp.method != "linear":
-        raise ValueError("Parameter 'indices' is only supported for 'method=linear'")
+        msg = "Parameter 'indices' is only supported for 'method=linear'"
+        raise ValueError(msg)
     if localize:
-        raise ValueError("Parameter 'indices' is only supported for 'localize=False'")
+        msg = "Parameter 'indices' is only supported for 'localize=False'"
+        raise ValueError(msg)
 
     if indices is None:
         assert xi is not None, "xi must be provided if indices is None"
@@ -604,7 +607,10 @@ class EmissionsProfileInterpolator:
     """
 
     def __init__(
-        self, xp: npt.NDArray[np.float64], fp: npt.NDArray[np.float64], drop_duplicates: bool = True
+        self,
+        xp: npt.NDArray[np.float64],
+        fp: npt.NDArray[np.float64],
+        drop_duplicates: bool = True,
     ) -> None:
         if drop_duplicates:
             # Using np.diff to detect duplicates ... this assumes xp is sorted.
@@ -622,13 +628,17 @@ class EmissionsProfileInterpolator:
 
     def _validate(self) -> None:
         if not len(self.xp):
-            raise ValueError("xp must not be empty")
+            msg = "xp must not be empty"
+            raise ValueError(msg)
         if len(self.xp) != len(self.fp):
-            raise ValueError("xp and fp must have the same length")
+            msg = "xp and fp must have the same length"
+            raise ValueError(msg)
         if not np.all(np.diff(self.xp) > 0.0):
-            raise ValueError("xp must be strictly increasing")
+            msg = "xp must be strictly increasing"
+            raise ValueError(msg)
         if np.any(np.isnan(self.xp)):
-            raise ValueError("xp must not contain nan values")
+            msg = "xp must not contain nan values"
+            raise ValueError(msg)
 
     def interp(self, x: npt.NDArray[np.float64]) -> npt.NDArray[np.float64]:
         """Interpolate x against xp and fp.