pycontrails

https://py.contrails.org
Admin
pycontrails is a Python library for modeling contrails and other aviation climate impacts, including...
Tokens:532,309
Snippets:4,507
Trust Score:8.3
Update:5 months ago
Show doc for...
Tokens:
Raw
### Run Docstring Example Tests with Doctest

Source: https://py.contrails.org/develop.html

Use this command to run tests on the examples embedded within docstrings using the doctest module.

```bash
make doctest
```

--------------------------------

### Test Notebook Examples with nbval

Source: https://py.contrails.org/develop.html

Run this command to test notebook examples using the nbval pytest plugin.

```bash
make nb-test
```

--------------------------------

### Example: Calculate Model Level Pressure

Source: https://py.contrails.org/api/pycontrails.datalib.ecmwf.model_levels.html

Demonstrates how to calculate model level pressures using `model_level_pressure`. This example sets up sample surface pressure data using xarray and then calls the function with specified model levels.

```python
import numpy as np
import xarray as xr
```

```python
sp_arr = np.linspace(101325.0, 90000.0, 16).reshape(4, 4)
longitude = np.linspace(-180, 180, 4)
latitude = np.linspace(-90, 90, 4)
sp = xr.DataArray(sp_arr, coords={"longitude": longitude, "latitude": latitude})
```

```python
model_levels = [80, 100]
model_level_pressure(sp, model_levels)
```

--------------------------------

### Manual Development Installation with Pip

Source: https://py.contrails.org/develop.html

Install pycontrails and its development/documentation dependencies manually using pip in editable mode. Remember to install pre-commit hooks if installing manually.

```bash
# core development installation
$ pip install -e ".[docs,dev]"

# install optional dependencies as above
$ pip install -e ".[ecmwf,gfs]"

# make sure to add pre-commit hooks if installing manually
$ pre-commit install
```

--------------------------------

### Install Keyring for Google Artifact Registry

Source: https://py.contrails.org/install.html

Install the necessary Python packages for keyring authentication with Google Artifact Registry. This is required for accessing private extensions like pycontrails-bada.

```bash
pip install keyring keyrings.google-artifactregistry-auth
```

--------------------------------

### Install climaccf (ACCF Model Interface)

Source: https://py.contrails.org/install.html

Install the climaccf package, which provides an interface to the DLR / UMadrid ACCF model. Installation is done directly from its GitHub repository.

```bash
pip install "climaccf @ git+ssh://git@github.com/dlr-pa/climaccf"
```

--------------------------------

### Get Flight Start and End Times

Source: https://py.contrails.org/notebooks/Flight.html

Retrieve the start and end timestamps of the flight.

```python
# Time start/end
print(fl.time_start)
print(fl.time_end)
```

--------------------------------

### Initialize and use DiskCacheStore

Source: https://py.contrails.org/api/pycontrails.core.cache.html

Demonstrates initializing a DiskCacheStore, getting a file path, and clearing the cache. Ensure to set allow_clear=True for clearing operations.

```python
from pycontrails import DiskCacheStore
cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
cache.path("file.nc")
cache.clear()  # cleanup
```

--------------------------------

### Initialize GCPCacheStore

Source: https://py.contrails.org/api/pycontrails.GCPCacheStore.html

Instantiate the GCPCacheStore with a specific bucket and cache directory. This example shows how to set up the cache and verify its configuration.

```python
from pycontrails import GCPCacheStore
cache = GCPCacheStore(
    bucket="contrails-301217-unit-test",
    cache_dir="cache",
)
cache.cache_dir
cache.bucket
```

--------------------------------

### Serve Documentation Locally

Source: https://py.contrails.org/develop.html

Automatically build and serve the documentation locally, rebuilding on changes. The documentation will be available at http://127.0.0.1:8000.

```bash
# automatically build docs on changes
# docs will be served at http://127.0.0.1:8000
$ make docs-serve
```

--------------------------------

### Install pycontrails with Jupyter Dependencies

Source: https://py.contrails.org/notebooks.html

Install pycontrails with the optional Jupyter dependencies if you do not have Jupyter installed. This enables the notebook and lab interface.

```bash
$ pip install "pycontrails[jupyter]"  # Jupyter notebook and lab interface
```

--------------------------------

### Install pycontrails with Pip (Core)

Source: https://py.contrails.org/install.html

Install the latest release from PyPI using pip for Python 3.11 or later. This is the core installation without optional dependencies.

```bash
# core installation
$ pip install pycontrails
```

--------------------------------

### Build Documentation Locally

Source: https://py.contrails.org/contributing.html

Use this command to build the documentation locally. The output will be placed in the docs/_build/html directory.

```shell
make docs-build
```

--------------------------------

### GRUAN Class Initialization

Source: https://py.contrails.org/api/pycontrails.datalib.gruan.GRUAN.html

Instantiate the GRUAN class by providing the desired product and site. An optional cachestore can be provided to manage downloaded files.

```APIDOC
## GRUAN(product, site, cachestore=None)

### Description
Initializes the GRUAN data access object.

### Parameters
* **product** (str) - Required - GRUAN data product. See `AVAILABLE` for available products.
* **site** (str) - Required - GRUAN station identifier. See `AVAILABLE` for available sites for each product.
* **cachestore** (cache.CacheStore | None) - Optional - Cache store to use for downloaded files. If not provided, a disk cache store will be created in the user cache directory under `gruan/`. Set to `None` to disable caching.
```

--------------------------------

### Install Specific Optional Dependencies with Pip

Source: https://py.contrails.org/install.html

Install specific optional dependencies for pycontrails based on your needs. Use this to add support for particular features without installing everything.

```bash
# install all optional runtime dependencies
$ pip install "pycontrails[complete]"
```

```bash
# install specific optional dependencies
$ pip install "pycontrails[dev]"      # Development dependencies
```

```bash
$ pip install "pycontrails[docs]"     # Documentation / Sphinx dependencies
```

```bash
$ pip install "pycontrails[ecmwf]"    # ECMWF datalib interfaces
```

```bash
$ pip install "pycontrails[gcp]"      # Google Cloud Platform caching interface
```

```bash
$ pip install "pycontrails[gfs]"      # GFS datalib interfaces
```

```bash
$ pip install "pycontrails[jupyter]"  # Jupyter notebook and lab interface
```

```bash
$ pip install "pycontrails[vis]"      # Polygon construction methods and plotting support
```

```bash
$ pip install "pycontrails[zarr]"     # Load data from remote Zarr stores
```

```bash
# These packages may not support the latest python version
# and are excluded from "complete"
$ pip install "pycontrails[open3d]"   # Polyhedra contruction methods
```

--------------------------------

### Loading Forecast Data

Source: https://py.contrails.org/integrations/GoogleForecast.html

This example demonstrates loading hourly forecast data, including rounding departure and arrival times and including all intermediate hours. The forecast data is structured with specific dimensions and data types.

```python
from contrails.forecast import Forecast

forecast = Forecast(
    departure_time=datetime(2023, 1, 1, 10, 0), # Round down
    arrival_time=datetime(2023, 1, 1, 12, 0),   # Round up
    dataset=Dataset.CONTRAILS_FORECAST,
    provider=Provider.GOOGLE,
    product=Product.FORECAST,
    aircraft_class=AircraftClass.DEFAULT,
)

# Load all hours in between
forecast.load()

# The forecast data is loaded into forecast.data
# Example structure:
# forecast.data.shape == (1441, 721, 18, 4)
# forecast.data.dtype == float32
```

--------------------------------

### Install pycontrails with ECMWF dependencies

Source: https://py.contrails.org/notebooks/ECMWF.html

Install pycontrails with the optional 'ecmwf' dependencies to enable ECMWF data access.

```bash
$ pip install pycontrails[ecmwf]
```

--------------------------------

### BADAFlight Parameters

Source: https://py.contrails.org/api/pycontrails.ext.bada.BADAFlight.html

Parameters for initializing BADAFlight.

```APIDOC
## BADAFlight Parameters

### Description
Parameters for initializing BADAFlight.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **true_airspeed** (npt.NDArray[np.floating] | float | None) - True airspeed for each waypoint, [m/s]. If None, a nominal value is used.
- **aircraft_mass** (npt.NDArray[np.floating] | float) - Aircraft mass for each waypoint, [kg].
- **engine_efficiency** (npt.NDArray[np.floating] | float | None) - Override the engine efficiency at each waypoint.
- **fuel_flow** (npt.NDArray[np.floating] | float | None) - Override the fuel flow at each waypoint, [kg/s].
- **thrust** (npt.NDArray[np.floating] | float | None) - Override the thrust setting at each waypoint, [N].
- **q_fuel** (float) - Lower calorific value (LCV) of fuel, [J/kg_fuel].
- **kwargs** (Any) - Additional keyword arguments to pass to the model.

### Returns
`AircraftPerformanceData` – Derived performance metrics at each waypoint.
```

--------------------------------

### GOES Class Initialization and Data Retrieval

Source: https://py.contrails.org/api/pycontrails.datalib.goes.html

Demonstrates how to initialize the GOES class with specific regions and bands, and retrieve data for a given timestamp. It also shows how to manage caching.

```APIDOC
## GOES Class

### Description
Support for GOES-16 data access via GCP.
This interface requires the `gcsfs` package.

### Parameters
* **region** (`GOESRegion | str`, _optional_) – GOES Region of interest. Uses the following conventions.
  * F: Full Disk
  * C: CONUS
  * M1: Mesoscale 1
  * M2: Mesoscale 2
By default, Full Disk (F) is used.
* **bands** (`str | Iterable[str] | None`) – Set of bands or bands for CMIP data. The 16 possible bands are represented by the strings “C01” to “C16”. For the SEVIRI ash color scheme, set `bands=("C11", "C14", "C15")`. For the true color scheme, set `bands=("C01", "C02", "C03")`. By default, the bands required by the SEVIRI ash color scheme are used. The bands must have a common horizontal resolution. The resolutions are:
  * C01: 1.0 km
  * C02: 0.5 km (treated as 1.0 km)
  * C03: 1.0 km
  * C04: 2.0 km
  * C05: 1.0 km
  * C06 - C16: 2.0 km
* **cachestore** (`cache.CacheStore | None`, _optional_) – Cache store for GOES data. If None, data is downloaded directly into memory. By default, a `cache.DiskCacheStore` is used.
* **bucket** (`str | None`, _optional_) – GCP bucket for GOES data. If None, the default option, the bucket is automatically set to `GOES_16_BUCKET` if the requested time is before `GOES_16_19_SWITCH_DATE` and `GOES_19_BUCKET` otherwise. The satellite number used for filename construction is derived from the last two characters of this bucket name.

### Examples
```python
>>> goes = GOES(region="M1", bands=("C11", "C14"))
>>> da = goes.get("2021-04-03 02:10:00")
>>> da.shape
(2, 500, 500)
```

```python
>>> da.dims
('band_id', 'y', 'x')
```

```python
>>> da.band_id.values
array([11, 14], dtype=int32)
```

```python
>>> # Print out a sample of the data
>>> da.sel(band_id=11).isel(x=slice(0, 50, 10), y=slice(0, 50, 10)).values
array([[266.8644 , 265.50812, 271.5592 , 271.45486, 272.75897],
       [250.53697, 273.28064, 273.80225, 270.77673, 274.8977 ],
       [272.8633 , 272.65466, 271.5592 , 274.01093, 273.12415],
       [274.16742, 274.11523, 276.5148 , 273.85443, 270.51593],
       [274.84555, 275.15854, 272.60248, 270.67242, 272.23734]],
      dtype=float32)
```

```python
>>> # The data has been cached locally
>>> assert goes.cachestore.listdir()
```

```python
>>> # Download GOES data directly into memory by setting cachestore=None
>>> goes = GOES(region="M2", bands=("C11", "C12", "C13"), cachestore=None)
>>> da = goes.get("2021-04-03 02:10:00")
```

```python
>>> da.shape
(3, 500, 500)
```

```python
>>> da.dims
('band_id', 'y', 'x')
```

```python
>>> da.band_id.values
array([11, 12, 13], dtype=int32)
```

```python
>>> da.attrs["long_name"]
'ABI L2+ Cloud and Moisture Imagery brightness temperature'
```

```python
>>> da.sel(band_id=11).values
array([[251.31944, 249.59802, 249.65018, ..., 270.30725, 270.51593,
        269.83777],
       [250.53697, 249.0242 , 249.12854, ..., 270.15076, 270.30725,
        269.73346],
       [249.1807 , 249.33719, 251.99757, ..., 270.15076, 270.20294,
        268.7945 ],
       ...,
       [277.24512, 277.29727, 277.45377, ..., 274.42822, 274.11523,
        273.7501 ],
       [277.24512, 277.45377, 278.18408, ..., 274.6369 , 274.01093,
        274.06308],

```

--------------------------------

### Install pycontrails with Pip (Complete)

Source: https://py.contrails.org/install.html

Install pycontrails with all optional dependencies included. This is useful for enabling all features of the library.

```bash
# install with all optional dependencies
$ pip install "pycontrails[complete]"
```

--------------------------------

### BADAFlight.__init__

Source: https://py.contrails.org/api/pycontrails.ext.bada.BADAFlight.html

Initializes a BADAFlight object with aircraft performance parameters.

```APIDOC
## BADAFlight.__init__()

### Description
Initializes a BADAFlight object with aircraft performance parameters.

### Parameters
#### Path Parameters
- **amass_mtow** (float) - Aircraft maximum take-off weight, [𝑘⁢𝑔]. Used to determine the initial aircraft mass if `takeoff_mass` is not provided. This quantity is constant for a given aircraft type.
- **amass_mpl** (float) - Aircraft maximum payload, [𝑘⁢𝑔]. Used to determine the initial aircraft mass if `takeoff_mass` is not provided. This quantity is constant for a given aircraft type.
- **payload** (float) - Aircraft payload, [𝑘⁢𝑔]. See `estimate_payload()` for methodology.
- **takeoff_mass** (float | None) - Optional. If known, the takeoff mass can be provided to skip the calculation in `jet.initial_aircraft_mass()`. In this case, the parameters `payload`, `amass_oew`, `amass_mtow`, and `amass_mpl` are ignored.
- ****kwargs** (Any) - Additional keyword arguments are passed to `calculate_aircraft_performance()`.
```

--------------------------------

### Install pycontrails with GFS support

Source: https://py.contrails.org/notebooks/GFS.html

Install the pycontrails library with the optional GFS dependencies to enable GFS data loading.

```bash
pip install pycontrails[gfs]
```

--------------------------------

### Initialize and Run CoCiP Module

Source: https://py.contrails.org/notebooks/run-cocip-with-fdr.html

Instantiate the CoCiP module with meteorological and radiative transfer data, an aircraft performance model (Poll-Schumann), and humidity scaling. Then, evaluate the flight data to obtain contrail impact predictions.

```python
cocip = Cocip(
    met=met, rad=rad, aircraft_performance=PSFlight(), humidity_scaling=HistogramMatching()
)
fl = cocip.eval(fl)
fl
```

--------------------------------

### Install pycontrails with Conda

Source: https://py.contrails.org/install.html

Install the latest release from conda-forge using the conda package manager. This includes all optional runtime dependencies.

```bash
$ conda install -c conda-forge pycontrails
```

--------------------------------

### Initialize DiskCacheStore

Source: https://py.contrails.org/api/pycontrails.DiskCacheStore.html

Instantiate a DiskCacheStore with a specified cache directory and enable clearing functionality.

```python
from pycontrails import DiskCacheStore
disk_cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
disk_cache.cache_dir
'cache'
```

--------------------------------

### Install pycontrails in Colab

Source: https://py.contrails.org/notebooks.html

Install the pycontrails library within a Google Colab environment. This is typically done in the first cell of a Colab notebook.

```python
!pip install pycontrails
```

--------------------------------

### Load a range of GFS time steps

Source: https://py.contrails.org/notebooks/GFS.html

Instantiate GFSForecast for a time range, specifying variables and pressure levels. The `show_progress=True` argument displays download progress.

```python
# get a range of time
gfs = GFSForecast(
    time=("2022-03-01 00:00:00", "2022-03-01 02:00:00"),
    variables=[
        "air_temperature",
        "q",
    ],  # supports CF name or short names
    pressure_levels=[200, 250, 300],
    show_progress=True,
)
gfs
```

--------------------------------

### Install Development Version with Make

Source: https://py.contrails.org/develop.html

Install the development version of pycontrails using the 'make dev-install' command after cloning the repository and activating the environment.

```bash
$ make dev-install
```

--------------------------------

### Initialize CoCiP Model

Source: https://py.contrails.org/notebooks/GFS.html

Set up the CoCiP model with GFS meteorology and radiation data, specifying integration time step.

```python
# set up CoCiP model with GFS meteorology and radiation
params = {"dt_integration": np.timedelta64(10, "m")}
cocip = Cocip(met=met, rad=rad, params=params)
```

--------------------------------

### Initialize and Check DiskCacheStore Size

Source: https://py.contrails.org/api/pycontrails.DiskCacheStore.html

Demonstrates how to initialize a DiskCacheStore and check its current size. The cache_dir specifies the location for the cache, and allow_clear enables clearing the cache.

```python
>>> from pycontrails import DiskCacheStore
>>> cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
>>> cache.size
0.0...
```

--------------------------------

### Install pycontrails-cirium Extension

Source: https://py.contrails.org/install.html

Install the pycontrails-cirium extension directly from its GitHub repository using SSH. This extension provides an interface to the Cirium database.

```bash
pip install "pycontrails-cirium @ git+ssh://git@github.com/contrailcirrus/pycontrails-cirium.git"
```

--------------------------------

### NumPy Docstring Example - Parameters

Source: https://py.contrails.org/develop.html

Example of how to format the Parameters section in a NumPy-style docstring. Sphinx will automatically replace 'np.ndarray' with its configured alias.

```python
"""
Parameters
----------
x : np.ndarray
    Sphinx will automatically replace
    "np.ndarray" with the napolean type alias "numpy.ndarray"
"""
```

--------------------------------

### Get data path from cache

Source: https://py.contrails.org/api/pycontrails.core.cache.html

The `get` method returns the relative path to a stored file within the cache. It is an alias for the `path()` method.

```python
>>> from pycontrails import DiskCacheStore
>>> disk_cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
>>>
>>> # returns a path
>>> disk_cache.get("test/file.md")
```

--------------------------------

### List Global ICON Forecasts

Source: https://py.contrails.org/notebooks/ICON.html

List available global ICON forecast initialization times. No credentials are required.

```python
ods.list_forecasts("global")
```

--------------------------------

### Load a single GFS time step

Source: https://py.contrails.org/notebooks/GFS.html

Instantiate GFSForecast for a specific time, selecting variables and pressure levels. The `show_progress=True` argument displays download progress.

```python
# get a single time
gfs = GFSForecast(
    time="2022-03-01 01:00:00",
    variables=["t", "q"],  # Supports CF name or short names
    pressure_levels=[200, 250, 300],
    show_progress=True,  # Shows download progress from AWS
)
gfs
```

--------------------------------

### Install pycontrails-bada Extension

Source: https://py.contrails.org/install.html

Install the pycontrails-bada extension from the specified index URL. This extension interfaces with BADA aircraft performance data and requires access approval.

```bash
pip install --index-url https://us-central1-python.pkg.dev/contrails-301217/pycontrails/simple \
    pycontrails-bada
```

```bash
# or at a tag
pip install --index-url https://us-central1-python.pkg.dev/contrails-301217/pycontrails/simple \
    "pycontrails-bada==0.6.0"
```

--------------------------------

### Initialize and Run CoCiP Model

Source: https://py.contrails.org/notebooks/model-levels.html

Sets up and executes the CoCiP model using provided meteorological and radiation data, fleet information, and integration parameters. It then accesses the resulting contrail data.

```python
cocip = Cocip(
    met=met,
    rad=rad,
    dt_integration="5 min",
    max_age="12 hours",
    aircraft_performance=PSFlight(),
    humidity_scaling=HistogramMatching(),
)
cocip_pred = cocip.eval(fleet)
contrail = cocip.contrail
```

--------------------------------

### Initialize and Check Cache Existence

Source: https://py.contrails.org/api/pycontrails.DiskCacheStore.html

Creates a DiskCacheStore instance and checks if a non-existent file is present in the cache.

```python
from pycontrails import DiskCacheStore
cache = DiskCacheStore(cache_dir="cache", allow_clear=True)
cache.exists("file.nc")
False
```

--------------------------------

### Install pycontrails Development Version from GitHub

Source: https://py.contrails.org/install.html

Install the latest development version directly from the GitHub repository using pip. This is useful for testing the newest features or contributing to the project.

```bash
$ pip install git+https://github.com/contrailcirrus/pycontrails.git
```

--------------------------------

### Initialize and Run Emissions Module

Source: https://py.contrails.org/notebooks/run-cocip-with-fdr.html

Initialize the Emissions module with meteorological data and humidity scaling. Then, evaluate the flight data to compute emissions. The result 'fl' contains the computed emissions.

```python
emissions = Emissions(met=met, humidity_scaling=HistogramMatching())
fl = emissions.eval(fl)
fl
```

--------------------------------

### Initialize Landsat Handler and Get Data

Source: https://py.contrails.org/notebooks/Landsat.html

Initializes the Landsat handler with specified bands and retrieves the dataset. Ensure 'base_url' is defined before use.

```python
handler = landsat.Landsat(base_url, bands=["B9", "B10", "B11"])
ds = handler.get()
```

--------------------------------

### PSFlight.get_source_param

Source: https://py.contrails.org/api/pycontrails.models.ps_model.PSFlight.html

Gets a parameter from the data source.

```APIDOC
## PSFlight.get_source_param()

### Description
Gets a parameter from the data source.
```

--------------------------------

### Initialize ERA5 dataset

Source: https://py.contrails.org/api/pycontrails.MetDataset.html

Create an ERA5 dataset instance by specifying time range, desired variables, and pressure levels.

```python
time = ("2022-03-01T00", "2022-03-01T02")
variables = ["air_temperature", "specific_humidity"]
pressure_levels = [200, 250, 300]
era5 = ERA5(time, variables, pressure_levels)
```

--------------------------------

### PSFlight.get_data_param

Source: https://py.contrails.org/api/pycontrails.models.ps_model.PSFlight.html

Gets a specific data parameter.

```APIDOC
## PSFlight.get_data_param()

### Description
Gets a specific data parameter.
```

--------------------------------

### Initialize ICON-D2 Model

Source: https://py.contrails.org/notebooks/ICON.html

Instantiate the ICON model for a specific domain and time range. Ensure the domain and time parameters are correctly formatted.

```python
icon = ICON(
    domain="germany",
    time=("2025-11-14 12:00", "2025-11-14 15:00"),
    variables=("t", "q"),
)
icon
```

--------------------------------

### VectorDataset.get_data_or_attr

Source: https://py.contrails.org/api/pycontrails.core.vector.html

Get value from data or attrs.

```APIDOC
## get_data_or_attr

### Description
Get value from `data` or `attrs`.
This method first checks if `key` is in `data` and returns the value if so. If `key` is not in `data`, then this method checks if `key` is in `attrs` and returns the value if so. If `key` is not in `data` or `attrs`, then the `default` value is returned if provided. Otherwise a `KeyError` is raised.

### Parameters
#### Path Parameters
- **key** (str) - Required - Key to get from `data` or `attrs`
- **default** (Any) - Optional - Default value to return if `key` is not in `data` or `attrs`.

### Returns
- **Any** - Value at `data[key]` or `attrs[key]`

### Raises
- **KeyError** - If `key` is not in `data` or `attrs` and `default` is not provided.

### Examples
```
>>> vector = VectorDataset({"a": [1, 2, 3]}, attrs={"b": 4})
>>> vector.get_data_or_attr("a")
array([1, 2, 3])
```

```
>>> vector.get_data_or_attr("b")
4
```

```
>>> vector.get_data_or_attr("c")
Traceback (most recent call last):
... 
KeyError: "Key 'c' not found in data or attrs."
```

```
>>> vector.get_data_or_attr("c", default=5)
5
```

### See also
`get_constant`
```

--------------------------------

### Initialize GFSForecast with default grid

Source: https://py.contrails.org/api/pycontrails.datalib.gfs.GFSForecast.html

Instantiate GFSForecast to retrieve air temperature at specified pressure levels for a given time range. Data files are stored locally by default.

```python
times = ("2022-03-22 00:00:00", "2022-03-22 03:00:00")
gfs = GFSForecast(times, variables="air_temperature", pressure_levels=[300, 250])
print(gfs)
```

--------------------------------

### HRES.url

Source: https://py.contrails.org/api/pycontrails.datalib.ecmwf.HRES.html

Get the URL for the data source.

```APIDOC
## HRES.url

### Description
Get the URL for the data source.

### Property
`url` (str)
```

--------------------------------

### forecast_frequency

Source: https://py.contrails.org/api/pycontrails.datalib.dwd.icon.html

Get forecast cycle frequency.

```APIDOC
## forecast_frequency(domain)

### Description
Get forecast cycle frequency.

### Parameters
* **domain** (str) - Description of the domain parameter.
```

--------------------------------

### flight_level_pressure

Source: https://py.contrails.org/api/pycontrails.datalib.dwd.icon.html

Get pressure at flight levels.

```APIDOC
## flight_level_pressure(fl_min=None, fl_max=None)

### Description
Get pressure at flight levels.

### Parameters
* **fl_min** (int | None, _optional_) - Minimum flight level.
* **fl_max** (int | None, _optional_) - Maximum flight level.
```

--------------------------------

### Initialize ICON with Automatic Forecast Time Selection

Source: https://py.contrails.org/notebooks/ICON.html

Instantiate the ICON class, specifying a time range and variables. If `forecast_time` is not provided, the library automatically selects the forecast cycle with the shortest lead time.

```python
icon = ICON(
    time=("2025-11-14 12:00", "2025-11-14 15:00"),
    variables=("t", "q"),
)
icon
```

--------------------------------

### GCPCacheStore.bucket

Source: https://py.contrails.org/notebooks/Cache.html

Get the configured bucket name for the GCPCacheStore.

```APIDOC
## GCPCacheStore.bucket

### Description
Get the configured bucket name for the GCPCacheStore.

### Method
```python
gcp.bucket
```

### Response
#### Success Response (string)
- Returns the name of the Google Cloud Storage bucket.
```

--------------------------------

### VectorDataset.get_constant

Source: https://py.contrails.org/api/pycontrails.core.vector.html

Get a constant value from attrs or data.

```APIDOC
## get_constant

### Description
Get a constant value from `attrs` or `data`.
  * If `key` is found in `attrs`, the value is returned.
  * If `key` is found in `data`, the common value is returned if all values are equal.
  * If `key` is not found in `attrs` or `data` and a `default` is provided, the `default` is returned.
  * Otherwise, a KeyError is raised.

### Parameters
#### Path Parameters
- **key** (str) - Required - Key to look for.
- **default** (Any) - Optional - Default value to return if `key` is not found in `attrs` or `data`.

### Returns
- **Any** - The constant value for `key`.

### Raises
- **KeyError** - If `key` is not found in `attrs` or the values in `data` are not equal and `default` is not provided.

### Examples
```
>>> vector = VectorDataset({"a": [1, 1, 1], "b": [2, 2, 3]})
>>> vector.get_constant("a")
np.int64(1)
>>> vector.get_constant("b")
Traceback (most recent call last):
... 
KeyError: "A constant key 'b' not found in attrs or data"
>>> vector.get_constant("b", 3)
3
```

### See also
`get_data_or_attr`, `GeoVectorDataset.constants`
```

--------------------------------

### Import Cache Stores - Python

Source: https://py.contrails.org/notebooks/Cache.html

Imports the necessary classes for disk and GCP cache storage.

```python
from pycontrails import DiskCacheStore, GCPCacheStore
```

--------------------------------

### coords

Source: https://py.contrails.org/api/pycontrails.core.fleet.html

Get geospatial coordinates for compatibility with MetDataArray.

```APIDOC
## coords

### Description
Get geospatial coordinates for compatibility with MetDataArray.

### Returns
`dict[str, np.ndarray]` – A dictionary with fields longitude, latitude, level, and time.
```

--------------------------------

### Initialize GFSForecast for Specific Time

Source: https://py.contrails.org/notebooks/GFS.html

Instantiate GFSForecast to fetch temperature and humidity data for specified pressure levels within a time range. Requires numpy and GFSForecast.

```python
import numpy as np
from pycontrails.models.gfs import GFSForecast

time_bounds = ("2022-11-18 16:00:00", "2022-11-18 18:00:00")
gfs = GFSForecast(
    time_bounds,
    variables=["t", "q"],
    pressure_levels=[200, 250, 300, 350],
    forecast_time=np.datetime64("2022-11-17 00:06:00"),
    show_progress=True,
)
gfs
```

--------------------------------

### Initialize GOES object with custom bands and caching

Source: https://py.contrails.org/api/pycontrails.datalib.goes.html

Instantiate the GOES class with a specific region and bands. Data will be cached locally by default.

```python
goes = GOES(region="M1", bands=("C11", "C14"))
da = goes.get("2021-04-03 02:10:00")
da.shape
```

--------------------------------

### supported_variables

Source: https://py.contrails.org/api/pycontrails.datalib.ecmwf.IFS.html

Property to get the supported variables for IFS.

```APIDOC
## supported_variables

### Description
IFS parameters available.

### Returns
- `list[MetVariable] | None` – List of MetVariable available in datasource
```

--------------------------------

### Initialize Grid ACCF with Parameters

Source: https://py.contrails.org/integrations/ACCF.html

Instantiate the ACCF class with specified parameters for emission scenario, ACCF version, and unit conversion. The eval() method then evaluates the model over the meteorological grid.

```python
ac = ACCF(
    pl,
    sl,
    params={"emission_scenario": "future_scenario", "accf_v": "V1.0", "unit_K_per_kg_fuel": True},
)
ds = ac.eval()  # This will evaluate over the met grid
```

--------------------------------

### valid_forecast_hours

Source: https://py.contrails.org/api/pycontrails.datalib.dwd.icon.html

Get valid forecast initialization hours.

```APIDOC
## valid_forecast_hours(domain)

### Description
Get valid forecast initialization hours.

### Parameters
* **domain** (str) - Description of the domain parameter.
```

--------------------------------

### Discover Available Products and Sites

Source: https://py.contrails.org/api/pycontrails.datalib.gruan.GRUAN.html

Use the `AVAILABLE` attribute or `available_sites()` method to discover which GRUAN products and corresponding sites are accessible.

```APIDOC
## AVAILABLE

### Description
A dictionary mapping GRUAN data products to a list of available sites for each product.

## available_sites()

### Description
Retrieves a list of available GRUAN sites for each supported product. This method is cached for efficiency.

### Returns
dict[str, list[str]] - Mapping of product names to lists of available site identifiers.
```

--------------------------------

### last_step

Source: https://py.contrails.org/api/pycontrails.datalib.dwd.icon.html

Get time of last forecast step.

```APIDOC
## last_step(domain, forecast_time)

### Description
Get time of last forecast step.

### Parameters
* **domain** (str) - Description of the domain parameter.
* **forecast_time** (datetime-like) - Description of the forecast_time parameter.
```

--------------------------------

### Configure CoCIP Model Parameters

Source: https://py.contrails.org/notebooks/run-cocip-on-flight.html

Sets up the CoCIP model with specific parameters, including whether to process emissions, verbosity of outputs, humidity scaling adjustments, and the maximum age of data to consider. The 'met' and 'rad' datasets are passed during initialization.

```python
params = {
    "process_emissions": False,
    "verbose_outputs": True,
    "humidity_scaling": ConstantHumidityScaling(rhi_adj=0.98),
    "max_age": pd.Timedelta(hours=10),
}
cocip = Cocip(met=met, rad=rad, params=params)
```

--------------------------------

### pycontrails.datalib.dwd.ods.rpath

Source: https://py.contrails.org/api/pycontrails.datalib.dwd.ods.html

Get URL remote data file.

```APIDOC
## pycontrails.datalib.dwd.ods.rpath

### Description
Get URL remote data file.

### Parameters
#### Path Parameters
- **domain** (str) - Required - ICON domain. Must be one of "global", "europe", or "germany".
- **forecast** (datetime) - Required - Start time of forecast cycle.
- **variable** (str) - Required - Open Data Server variable name.
- **step** (int) - Required - Forecast step.
- **level** (int | None) - Required - Model level for 3d variables or `None` for 2d variables

### Returns
- **str** - URL of remote data file.
```

--------------------------------

### List GRUAN files for a specific year

Source: https://py.contrails.org/notebooks/GRUAN.html

Use the `list_files()` method with a year to retrieve a list of available filenames for that product and site. The first 10 files are shown.

```python
# See the available files in 2016
# Use the extract_gruan_time function to get datetime info from filenames (not shown here)
gruan.list_files(2016)[:10]
```

--------------------------------

### get

Source: https://py.contrails.org/api/pycontrails.GCPCacheStore.html

Retrieves data from the local cache store.

```APIDOC
## get

### Description
Get data from the local cache store.

### Parameters
* **cache_path** (`str`) – Path in cache store to get data

### Returns
* `str` – Returns path to downloaded local file

### Raises
* **ValueError** – Raises value error is `cache_path` refers to a directory

### Request Example
```python
>>> import pathlib
>>> from pycontrails import GCPCacheStore
>>> cache = GCPCacheStore(
...     bucket="contrails-301217-unit-test",
...     cache_dir="cache",
... 
```

--------------------------------

### Initialize GCPCacheStore - Python

Source: https://py.contrails.org/notebooks/Cache.html

Initializes the GCPCacheStore for Google Cloud Storage. Requires `[gcp]` optional dependencies and specifies the bucket and a cache directory within the bucket.

```python
gcp = GCPCacheStore(bucket="contrails-301217-unit-test", cache_dir="test/objects")
```
Tokens:
Raw