### Install BADA extension

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/install.rst

Install the private BADA extension from the Google Artifact Registry.

```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"
```

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

### Install development version from GitHub

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/install.rst

Install the latest development version directly from the source repository.

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

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

### Install GCP Dependencies

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ECMWF.ipynb

Install the required optional dependencies for Google Cloud Storage support.

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

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

### Install development dependencies

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/develop.rst

Commands to install the project in editable mode with specific dependency sets.

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

```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 development version with pip

Source: https://github.com/contrailcirrus/pycontrails/blob/main/README.md

Install the latest development version directly from the GitHub repository.

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

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

### Install ACCF extension

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/install.rst

Install the ACCF model interface from the DLR repository.

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

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

### Install Cirium extension

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/install.rst

Install the private Cirium extension directly from the git repository.

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

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

### Authenticate for BADA extension

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/install.rst

Login to Google Cloud and install the keyring for artifact registry access.

```bash
gcloud auth login
```

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

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

### Install optional dependencies

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/install.rst

Install specific sets of optional dependencies for features like ECMWF, GFS, or visualization.

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

# install specific optional dependencies
$ pip install "pycontrails[dev]"      # Development dependencies
$ pip install "pycontrails[docs]"     # Documentation / Sphinx dependencies
$ pip install "pycontrails[ecmwf]"    # ECMWF datalib interfaces
$ pip install "pycontrails[gcp]"      # Google Cloud Platform caching interface
$ pip install "pycontrails[gfs]"      # GFS datalib interfaces
$ pip install "pycontrails[jupyter]"  # Jupyter notebook and lab interface
$ pip install "pycontrails[vis]"      # Polygon construction methods and plotting support
$ pip install "pycontrails[zarr]"     # Load data from remote Zarr stores

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

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

### Install pycontrails via pip

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/install.rst

Install the core package or the complete version with all optional dependencies.

```bash
# core installation
$ pip install pycontrails

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

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

### Install pycontrails with pip

Source: https://github.com/contrailcirrus/pycontrails/blob/main/README.md

Use pip to install the package from PyPI. Requires Python 3.11 or later.

```bash
$ pip install pycontrails

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

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

### Define example flight output file

Source: https://github.com/contrailcirrus/pycontrails/blob/main/tests/benchmark/cocip/review.ipynb

Specifies the filename for an example flight output file. This variable is used to load a specific flight's data.

```python
# Load example flight output
flight_example = "200101-20845-UAE345.pq"
```

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

### Download Input Data

Source: https://github.com/contrailcirrus/pycontrails/blob/main/tests/benchmark/cocip/README.md

Use this command to download input meteorology data for the model to the local 'inputs/' directory. Ensure Google Cloud SDK is installed.

```bash
$ make download-inputs
```

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

### Import GFSForecast Class

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/GFS.ipynb

Import the necessary GFSForecast class from pycontrails.datalib.gfs. Requires `pycontrails[gfs]` installation.

```python
import numpy as np

from pycontrails.datalib.gfs import GFSForecast
```

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

### Define ATC flight plan string

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/flightplan.ipynb

Example of a raw ICAO ATC flight plan string.

```python
atc_plan = """
(FPL-GEC8145-IN -B77L/H-SDE2E3FGHIJ3J4J5M1RWXYZ/SB1D1
-EGGL1040 -N0474F360 IMVUR1Z IMVUR N63 SAM N19 ADKIK DCT 
MOPAT DCT  LIMRI/M083F360 DCT 51N020W 47N030W/M083F380 40N040W 
34N045W  28N050W/M083F400 24N055W 19N060W DCT AMTTO DCT ANU DCT 
-PBN/A1B1C1D1L1O1S1S2 NAV/RNVD1E2A1 DAT/SVM DOF/140501 REG/DALFA 
EET/OKAC0037 ORBB0052 LTAA0159 UKFV0308 UKOV0333 LUUU0344 UKLV0406
EPWW0427 ESAA0521 EKDK0540 ENOR0557 SEL/DFBH OPR/GEC RVR/200) 
-E/0740 P/3 R/E S/ J/ A/WHITE BLUE TAIL
"""
```

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

### Get and set data from Flight object

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Flight.ipynb

Demonstrates how to get and set specific data arrays (e.g., latitude) from the Flight object using dictionary-like access. Modifications to the array are reflected in the Flight object.

```python
# get
lat = fl["latitude"]

# set
lat[5] = 20
fl["latitude"] = lat

# get updated
fl["latitude"][5]
```

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

### Sync data from GCP using gsutil

Source: https://github.com/contrailcirrus/pycontrails/blob/main/tests/benchmark/cocip/review.ipynb

Synchronizes flight input and output data from a Google Cloud Storage bucket to the local file system. Requires the google-cloud-sdk to be installed and configured.

```bash
# sync data from GCP
# requires google-cloud-sdk (https://cloud.google.com/sdk/docs/install)

# sync flight inputs
!mkdir -p inputs
!gsutil rsync -d -r $GCP_BUCKET/cocip/inputs/flight inputs/flight/

# sync outputs
!mkdir -p outputs
!gsutil rsync -d -r $GCP_BUCKET/cocip/outputs outputs/
```

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

### Import CoCiP and Flight Models

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/GFS.ipynb

Import necessary classes for running the CoCiP model and defining flight paths. Requires `pycontrails` installation.

```python
import numpy as np
import pandas as pd

from pycontrails import Flight
from pycontrails.models.cocip import Cocip
```

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

### Initialize HRES Single Level Dataset

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ECMWF.ipynb

Initialize an HRES single-level dataset for specified times and variables. Accumulated radiation parameters are noted to be from the start of the forecast.

```python
hres = HRES(
    time=time,
    variables=["tsr", "ttr"],
    grid=1,
    # url="https://api.ecmwf.int/v1",
    # key="<key>"
    # email="<email>"
)
```

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

### List available GRUAN files for a specific year

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/GRUAN.ipynb

Use the `list_files()` method to see the filenames available for a given year. This is useful for selecting specific data files to download. The example shows the first 10 files for the year 2016.

```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 flight start and end times

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Flight.ipynb

Retrieve the start and end times of the flight using the `time_start` and `time_end` properties.

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

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

### Build and serve documentation

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/develop.rst

Commands to build, serve, or clean the project documentation using Makefile or sphinx-build.

```bash
# docs build to directory docs/_build/html
$ make docs-build

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

# clean up built documentation
$ make docs-clean
```

```bash
$ sphinx-build -b html docs docs/_build/html      # HTML output
```

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

### Build Documentation Locally

Source: https://github.com/contrailcirrus/pycontrails/blob/main/CONTRIBUTING.md

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

```bash
# docs build to directory docs/_build/html
$ make docs-build
```

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

### Download and load a single GRUAN sounding

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/GRUAN.ipynb

Download a specific GRUAN data file using its filename and load it into an xarray Dataset. The `get()` method automatically caches the downloaded file. Asserts are included to verify unit conventions for pressure, temperature, and relative humidity.

```python
# Choose a single file (this one taken from the above list) and download it
file = "LIN-RS-01_2_RS92-GDP_002_20160102T120000_1-000-001.nc"
ds = gruan.get(file)  # automatically cached

# Check that our assumptions about units are correct
# Other sites or products may have different conventions
assert ds["press"].attrs["units"] == "hPa"
assert ds["temp"].attrs["units"] == "K"
assert ds["rh"].attrs["units"] == "1"

ds
```

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

### Install pycontrails via conda

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/install.rst

Install the latest release from the conda-forge channel.

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

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

### Initialize CoCiP Model

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/GFS.ipynb

Sets up the CoCiP model instance using provided meteorology, radiation data, and integration time steps.

```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)
```

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

### Install pycontrails with ECMWF dependencies

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ECMWF.ipynb

Install pycontrails with the optional ECMWF dependencies using pip.

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

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

### Initialize Cocip Model

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/CoCiP.ipynb

Configure the Cocip model with integration time steps and humidity scaling parameters.

```python
params = {
    "dt_integration": np.timedelta64(10, "m"),
    # The humidity_scaling parameter is only used for ECMWF ERA5 data
    # based on Teoh 2020 and Teoh 2022 - https://acp.copernicus.org/preprints/acp-2022-169/acp-2022-169.pdf
    # Here we use an example of constantly scaling the humidity value by 0.99
    "humidity_scaling": ConstantHumidityScaling(rhi_adj=0.99),
}
cocip = Cocip(met=met, rad=rad, params=params)
```

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

### Create and activate virtual environment

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/develop.rst

Commands to set up a standard Python virtual environment or a Conda environment for development.

```bash
# create environment in <DIR>
$ python3 -m venv <DIR>

# activate environment (Unix-like)
$ source <DIR>/bin/activate
```

```bash
# create conda environment
$ conda create -n contrails

# activate environment
$ conda activate contrails
```

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

### Build PDF Documentation

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/develop.rst

Commands to generate PDF output from the documentation source.

```bash
$ make docs-pdf
```

```bash
$ sphinx-build -b latex docs docs/_build/latex
$ cd docs/_build/latex
$ make
```

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

### Install pycontrails with conda

Source: https://github.com/contrailcirrus/pycontrails/blob/main/README.md

Install the package from the conda-forge channel. This method includes all optional runtime dependencies.

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

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

### Initialize ICON-D2 Dataset

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ICON.ipynb

Configure the ICON data provider with specific domain, time range, and variables.

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

```python
icon = ICON(
    domain="germany",
    time=("2025-11-14 12:00", "2025-11-14 15:00"),
    variables=("rlut", "rst"),
    pressure_levels=-1,
)
icon
```

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

### Initialize and run CoCiP grid model

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ICON.ipynb

Sets up the model parameters and executes the CoCiP grid evaluation.

```python
import numpy as np

from pycontrails.core import MetDataset
from pycontrails.models.cocipgrid import CocipGrid
from pycontrails.models.humidity_scaling import ConstantHumidityScaling
from pycontrails.models.ps_model import PSGrid
from pycontrails.physics import units
```

```python
params = {
    "dt_integration": np.timedelta64(5, "m"),
    "max_age": np.timedelta64(10, "h"),
    "humidity_scaling": ConstantHumidityScaling(rhi_adj=1.0),
    "aircraft_performance": PSGrid(),
}

source = MetDataset.from_coords(
    level=units.ft_to_pl(35_000),
    time="2025-11-14 13:00",
    longitude=met["longitude"].values,
    latitude=met["latitude"].values,
)

cocip_grid = CocipGrid(met=met, rad=rad, params=params)
result = cocip_grid.eval(source)
```

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

### Install pycontrails in Colab

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks.rst

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

```bash
!pip install pycontrails
```

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

### Initialize SAC Model Environment

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/SAC.ipynb

Import necessary libraries and suppress specific warnings related to ECMWF humidity scaling.

```python
# ignore pycontrails warning about ECMWF humidity scaling
import warnings

import pandas as pd

from pycontrails import Flight
from pycontrails.datalib.ecmwf import ERA5
from pycontrails.models.sac import SAC

warnings.filterwarnings(message=r"[\s\S]* humidity scaling [\s\S]*", action="ignore")
```

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

### Install pycontrails with Jupyter support

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks.rst

Install pycontrails along with the necessary dependencies for using the Jupyter notebook and lab interfaces. This command should be run in your terminal.

```bash
pip install "pycontrails[jupyter]"
```

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

### Download CoCiP-Fortran benchmark data

Source: https://github.com/contrailcirrus/pycontrails/blob/main/tests/benchmark/cocip-fortran/README.md

Downloads the benchmark output data from the Google Cloud Storage bucket to the local outputs directory.

```bash
$ gsutil -m cp -r gs://contrails-301217-benchmark-data-archive/cocip-fortran/outputs .
```

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

### Configure and initialize CoCiPGrid model

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/CoCiPGrid.ipynb

Set model parameters including integration time step, maximum contrail age, humidity scaling, and aircraft performance model. Then, initialize the CocipGrid model with the downloaded meteorological and radiative data.

```python
# Model parameters
params = {
    "dt_integration": np.timedelta64(5, "m"),
    "max_age": np.timedelta64(10, "h"),
    # The humidity_scaling parameter is only used for ECMWF ERA5 data
    # See https://py.contrails.org/api/pycontrails.models.humidity_scaling.html#module-pycontrails.models.humidity_scaling
    "humidity_scaling": HistogramMatching(),
    # Use Poll-Schumann aircraft performance model adapted for grid calculations
    # See https://py.contrails.org/api/pycontrails.models.ps_model.PSGrid.html#pycontrails.models.ps_model.PSGrid
    "aircraft_performance": PSGrid(),
}

# Initialize CocipGrid model
cocip_grid = CocipGrid(met=met, rad=rad, params=params)
```

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

### Import Libraries for Landsat Analysis

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Landsat.ipynb

Imports necessary libraries for flight data processing, Landsat data handling, and visualization. Ensure optional dependencies are installed with `pip install pycontrails[sat]`.

```python
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import pyproj
from matplotlib import dates

from pycontrails.core import Flight
from pycontrails.datalib import landsat
```

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

### Initialize Landsat Handler and Download Bands

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Landsat.ipynb

Initializes a `Landsat` handler for a specific scene and downloads bands B2, B3, and B4, which are used for creating a true-color image. Downloading may take time locally.

```python
handler = landsat.Landsat(base_url, bands=["B2", "B3", "B4"])
ds = handler.get()
ds
```

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

### Initialize CoCiP Environment

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/CoCiP.ipynb

Import necessary libraries and configure matplotlib for plotting.

```python
import numpy as np
import pandas as pd
from matplotlib import pyplot as plt

from pycontrails import Flight, MetDataset
from pycontrails.datalib.ecmwf import ERA5
from pycontrails.models.cocip import Cocip
from pycontrails.models.humidity_scaling import ConstantHumidityScaling

plt.rcParams["figure.figsize"] = (10, 6)
```

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

### Get altitude in feet

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Flight.ipynb

Retrieve the altitude of the flight in feet (ft) using the `altitude_ft` property.

```python
# Altitude, in ft
fl.altitude_ft
```

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

### List European Forecasts (ICON-EU)

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ICON.ipynb

List all available European forecast initializations for ICON-EU. These are initialized every three hours.

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

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

### Initialize Meteorological Datasets

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/run-cocip-on-flight.ipynb

Load meteorological data from ERA5 pressure level and single level sources.

```python
met = era5pl.open_metdataset()
rad = era5sl.open_metdataset()
```

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

### Load Single GFS Time Step

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/GFS.ipynb

Instantiate `GFSForecast` for a single time step, specifying variables and pressure levels. `show_progress=True` 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
```

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

### Get Total Flight Length

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Flight.ipynb

Retrieves the total length of the flight in meters. This is a direct property access.

```python
# total flight length in meters
fl.length
```

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

### Get pressure altitude

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Flight.ipynb

Access the pressure altitude of the flight in hectopascals (hPa) using the `level` property.

```python
# Pressure altitude, in hPa
fl.level
```

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

### Initialize GCPCacheStore

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Cache.ipynb

Instantiate the GCPCacheStore to manage caching with Google Cloud Storage. Requires `[gcp]` optional dependencies. Specify the bucket and a cache directory within the bucket.

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

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

### Get flight distance

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Flight.ipynb

Calculate and retrieve the total distance of the flight path in meters using the `length` property.

```python
# Flight distance, in meters
fl.length
```

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

### Get flight duration

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Flight.ipynb

Calculate and retrieve the total duration of the flight as a pandas Timedelta object using the `duration` property.

```python
# Flight duration, as a pandas Timedelta
fl.duration
```

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

### List German Forecasts (ICON-D2)

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ICON.ipynb

List all available German forecast initializations for ICON-D2. These are also initialized every three hours.

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

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

### Get Disk Cache Size

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Cache.ipynb

Retrieve the total size of the disk cache in megabytes. This helps in managing storage space.

```python
# Total cache size, in MB
disk.size
```

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

### Configure and Instantiate CoCiP

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/run-cocip-on-flight.ipynb

Define model parameters and initialize the CoCiP object with meteorological and radiation data.

```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)
```

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

### Contrail Waypoint Data Structure

Source: https://github.com/contrailcirrus/pycontrails/blob/main/tests/benchmark/cocip/data.md

Definition of the data fields available for contrail waypoints, which represent the start and end of contrail segments.

```APIDOC
## Contrail Waypoint Data Structure

### Description
Contrail waypoints are indexed by the original flight waypoint and the timestep of evolution. Properties are attached to the first waypoint in a segment.

### Parameters
#### Position & Geometry
- **flight_id** (str) - Flight ID of the contrail forming flight
- **waypoint** (int64) - 0-based index of the original flight waypoint
- **time** (datetime64[ns]) - Contrail waypoint timestamp (UTC)
- **longitude** (float64) - Longitude (EPSG:4326)
- **latitude** (float64) - Latitude (EPSG:4326)
- **altitude** (float64) - Altitude (m)
- **segment_length** (float64) - Haversine distance to next waypoint (m)

#### Meteorology
- **air_temperature** (float64) - Ambient air temperature (K)
- **air_pressure** (float64) - Air pressure (Pa)
- **specific_humidity** (float64) - Specific humidity (kg_{H20v} kg_{moist air}^1)
- **rhi** (float64) - Relative humidity over ice
- **u_wind** (float64) - Eastward wind (m s^-1)
- **v_wind** (float64) - Northward wind (m s^-1)

#### Evolution & Persistence
- **diffuse_h** (float64) - Contrail horizontal diffusivity (m^2 s^-1)
- **n_ice_per_vol** (float64) - Number of contrail ice particles per volume (m^-3)
- **terminal_fall_speed** (float64) - Terminal fall speed (m s^-1)

#### Radiative Forcing
- **tau_contrail** (float64) - Contrail optical depth
- **rsr** (float64) - Time-average reflected shortwave radiation (W m^-2)
- **olr** (float64) - Time-average outgoing longwave radiation (W m^-2)
```

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

### Prepare flight data

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/advection.ipynb

Load flight CSV data and create a Flight instance with altitude clipping.

```python
df = pd.read_csv("data/flight.csv")

# Clip at 33,000 ft to hit more ISSR
df["altitude"] = df["altitude"].clip(upper=units.ft_to_m(33000))

# Create a flight instance
fl = Flight(df, aircraft_type="A320", flight_id="example")
```

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

### Initialize ICON-EU Forecast for Surface Fluxes

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ICON.ipynb

Initializes the ICON forecast for the European domain, specifying time range, desired variables, and requesting all pressure levels using -1. This is useful for surface-related variables.

```python
icon = ICON(
    domain="europe",
    time=("2025-11-14 12:00", "2025-11-14 15:00"),
    variables=("rlut", "rst"),
    pressure_levels=-1,
)
icon
```

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

### Import necessary libraries for ERA5 data processing

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/specific-humidity-interpolation.ipynb

Imports essential libraries for data manipulation, interpolation, and meteorological calculations. Ensure these are installed before running.

```python
import matplotlib.pyplot as plt
import numpy as np
import seaborn as sns
import xarray as xr
from scipy.interpolate import PchipInterpolator

from pycontrails.core import models
from pycontrails.datalib.ecmwf import ERA5ARCO
from pycontrails.physics import thermo
```

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

### Create grid source and run simulation

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/CoCiPGrid.ipynb

Define the spatial and temporal grid for the simulation using `MetDataset.from_coords` and then execute the CoCiPGrid model evaluation.

```python
# Create a grid source
coords = {
    "level": pressure_levels,
    "time": pd.date_range(time_bounds[0], time_bounds[1], freq="1h")[0:4],  # run for first 4 hours of domain
    "longitude": np.arange(lon_bounds[0], lon_bounds[1], 1.0),
    "latitude": np.arange(lat_bounds[0], lat_bounds[1], 1.0),
}
grid_source = MetDataset.from_coords(**coords)

# Run CocipGrid model
result = cocip_grid.eval(source=grid_source)
```

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

### Initialize ICON-EU Forecast for Temperature and Humidity

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ICON.ipynb

Initializes the ICON forecast for the European domain, specifying time range and desired variables. No remapping is needed for ICON-EU as it uses a regular lat/lon grid.

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

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

### Get maximum distance gap

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Flight.ipynb

Find the largest distance gap between consecutive waypoints in the flight path, returned in meters using the `max_distance_gap` property.

```python
# Max distance gap between waypoints, in meters
fl.max_distance_gap
```

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

### Initialize IFS Data Loader

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ECMWF.ipynb

Import the IFS class and initialize it with specific time ranges, variables, and forecast paths.

```python
from pycontrails.datalib.ecmwf import IFS
```

```python
ifs = IFS(
    time=("2021-10-02 00:00:00", "2021-10-02 14:00:00"),
    variables=["air_temperature"],
    forecast_path="ifs",
    forecast_date="2021-10-01",
)
```

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

### Initialize ISSR Environment

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ISSR.ipynb

Imports necessary libraries and suppresses specific ECMWF humidity scaling warnings.

```python
# ignore pycontrails warning about ECMWF humidity scaling
import warnings

import matplotlib.pyplot as plt
import pandas as pd
from matplotlib.colors import ListedColormap

from pycontrails import Flight
from pycontrails.datalib.ecmwf import ERA5
from pycontrails.models.issr import ISSR

warnings.filterwarnings(message=r"[\s\S]* humidity scaling [\s\S]*", action="ignore")
```

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

### Initialize ICON with Shortest Lead Time Forecast

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ICON.ipynb

Initialize the ICON data class without specifying a forecast time. The system automatically selects the forecast cycle with the shortest lead time. The output confirms the selected forecast time.

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

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

### Update GRUAN Datalib

Source: https://github.com/contrailcirrus/pycontrails/blob/main/CHANGELOG.md

Introduces a lightweight GRUAN datalib for accessing GRUAN radiosonde data via FTP. Refer to the GRUAN notebook for usage examples.

```python
from pycontrails.datalib import GRUAN
```

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

### Get Meteorological Data with ERA5

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Flight.ipynb

Retrieves meteorological data from ERA5 for a specified time range, variables, and pressure levels. Requires initialization of the ERA5 object with these parameters.

```python
time = ("2022-03-01 00:00:00", "2022-03-01 03:00:00")
variables = ["t", "q", "u", "v", "w", "ciwc", "z", "cc"]
pressure_levels = [300, 250, 200]

# get met data
era5 = ERA5(time=time, variables=variables, pressure_levels=pressure_levels)
met = era5.open_metdataset()
```

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

### Execute CoCiP Model

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/CoCiP.ipynb

Initializes the CoCiP model with meteorological and radiation data and evaluates the flight source.

```python
# run model
cocip = Cocip(
    met=met,
    rad=rad,
    process_emissions=False,
    humidity_scaling=ConstantHumidityScaling(rhi_adj=0.99),
)
output_flight = cocip.eval(source=fl)
```

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

### Get maximum time gap

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Flight.ipynb

Determine the largest time gap between consecutive waypoints in the flight path, returned as a pandas Timedelta object via the `max_time_gap` property.

```python
# Max time gap between waypoints, as a pandas Timedelta
fl.max_time_gap
```

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

### Import required libraries for Google Contrails

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/integrations/GoogleForecast.ipynb

Initializes the necessary modules for handling flight data and Google forecast datasets.

```python
import cartopy.crs as ccrs
import matplotlib.pyplot as plt
import pandas as pd

from pycontrails.core.flight import Flight
from pycontrails.datalib.google_forecast import (
    ExpectedEffectiveEnergyForcing,
    GoogleForecast,
    Severity,
)
```

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

### Initialize and Evaluate Grid ACCF

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/integrations/ACCF.ipynb

Configures the ACCF model with specific emission scenarios and evaluates it over the provided 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
```

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

### Localize Cartopy Import in GOES

Source: https://github.com/contrailcirrus/pycontrails/blob/main/CHANGELOG.md

The `cartopy` import is now localized within the `extract_visualization` function in the `goes` module. This allows downloading `GOES` imagery without requiring `cartopy` to be installed.

```python
from pycontrails.datalib.goes import extract_visualization

# Example usage:
# visualization = extract_visualization(data, ...)
```

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

### Import Libraries for Sentinel-2 Analysis

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Sentinel.ipynb

Imports necessary libraries for flight data handling, Sentinel-2 data processing, plotting, and coordinate transformations. Ensure optional dependencies are installed.

```python
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import pyproj
from matplotlib import dates

from pycontrails.core import Flight
from pycontrails.datalib import sentinel
```

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

### Initialize DiskCacheStore

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Cache.ipynb

Instantiate the DiskCacheStore to manage local disk caching. Files are stored in the user cache directory or current hard drive.

```python
disk = DiskCacheStore()
```

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

### List Global Forecasts

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ICON.ipynb

List all available global forecast initializations. Global forecasts are initialized at 0z, 6z, 12z, and 18z.

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

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

### Instantiate GRUAN data object and list years

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/GRUAN.ipynb

Instantiate the GRUAN data object for a specific product and site (e.g., 'RS92-GDP.2' at 'LIN'). Then, use the `years()` method to check which years have data available for that product and site.

```python
# We instantiate using the RS92-GDP.2 product at the LIN (Lindenberg) site
gruan = GRUAN("RS92-GDP.2", "LIN")

# Check which years have data in this product/site
gruan.years()
```

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

### Contrail Dataframe Example

Source: https://github.com/contrailcirrus/pycontrails/blob/main/tests/benchmark/cocip/review.ipynb

A sample pandas DataFrame representing contrail data, including flight information, timestamps, and various atmospheric and flight parameters. This data can be used for analysis and visualization.

```python
                             flight_id      formation_time  \
timestep waypoint                                            \
36       86        200101-20845-UAE345 2020-01-01 03:29:01   
37       86        200101-20845-UAE345 2020-01-01 03:29:01   
         87        200101-20845-UAE345 2020-01-01 03:30:00   
         88        200101-20845-UAE345 2020-01-01 03:30:40   
         89        200101-20845-UAE345 2020-01-01 03:31:20   
...                                ...                 ...   
128      86        200101-20845-UAE345 2020-01-01 03:29:01   
         87        200101-20845-UAE345 2020-01-01 03:30:00   
129      86        200101-20845-UAE345 2020-01-01 03:29:01   
130      86        200101-20845-UAE345 2020-01-01 03:29:01   
131      86        200101-20845-UAE345 2020-01-01 03:29:01   

                                 time    age  longitude  latitude  \
timestep waypoint                                                   
36       86       2020-01-01 03:30:00      0  95.251264  7.115601   
37       86       2020-01-01 03:35:00    359  95.247874  7.140778   
         87       2020-01-01 03:35:00    300  95.128682  7.193805   
         88       2020-01-01 03:35:00    260  95.050572  7.227311   
         89       2020-01-01 03:35:00    220  94.972236  7.261058   
...                               ...    ...        ...       ...   
128      86       2020-01-01 11:10:00  27659  95.899134  9.470734   
         87       2020-01-01 11:10:00      0  95.843858  9.477083   
129      86       2020-01-01 11:15:00      0  95.913246  9.499670   
130      86       2020-01-01 11:20:00      0  95.927327  9.528841   
131      86       2020-01-01 11:25:00      0  95.941386  9.558227   

                       altitude       level  continuous  segment_length  ...  \
timestep waypoint                                                        ...   
36       86        12104.477563  190.142071           0        0.000000  ...   
37       86        12136.009615  189.198975           1    14412.008427  ...   
         87        12128.436189  189.425062           1     9388.026070  ...   
         88        12123.324353  189.577816           1     9421.026544  ...   
         89        12118.265025  189.729123           1     9455.212511  ...   
...                         ...         ...         ...             ...  ...   
128      86        11879.216503  197.017582           1     6103.811038  ...   
         87        11901.780132  196.317827           0        0.000000  ...   
129      86        11880.321464  196.983256           0     6090.623209  ...   
130      86        11878.808912  197.030245           0        0.000000  ...   
131      86        11881.771121  196.938232           0        0.000000  ...   

                      heat_rate   d_heat_rate      rf_sw      rf_lw  \
timestep waypoint                                                     
36       86        9.128913e-06 -5.667356e-05 -17.456228   7.687329   
37       86        1.376411e-05 -8.438302e-05 -16.924623  12.616778   
         87        2.825592e-05 -2.073150e-04 -25.348743  17.206863   
         88        3.813284e-05 -3.046355e-04 -34.244701  23.150066   
         89        4.420108e-05 -3.748469e-04 -40.959236  27.202160   
...                         ...           ...        ...        ...   
128      86        4.673915e-10 -5.103567e-07   0.000000   0.177018   
         87        1.060520e-09 -8.767716e-07   0.000000   0.332588   
129      86        6.097647e-10 -7.597042e-07   0.000000   0.258667   
130      86        8.381461e-10 -2.362873e-07   0.000000   0.101417   
131      86        1.256822e-09 -1.027896e-06   0.000000   0.360306   

                      rf_net  persistent            ef  dt_integration  \
timestep waypoint                                                        
36       86        -9.768899           1  0.000000e+00             300   
37       86        -4.307845           1 -1.455657e+10             300   
         87        -8.141880           1 -1.287425e+10             300   
         88       -11.094635           1 -1.296697e+10             300   
         89       -13.757076           1 -1.120554e+10             300   
...                      ...         ...           ...             ...   
128      86         0.177018           1  2.347958e+10             300   
         87         0.332588           1  0.000000e+00             300   
129      86         0.258667           1  0.000000e+00             300   
130      86         0.101417           1  0.000000e+00             300   
131      86         0.360306           1  0.000000e+00             300   

                    time_unix  formation_time_unix  
timestep waypoint                                   
36       86        1577849400           1577849341  
37       86        1577849700           1577849341  

```

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

### Import pandas and set GCP bucket

Source: https://github.com/contrailcirrus/pycontrails/blob/main/tests/benchmark/cocip/review.ipynb

Imports the pandas library for data manipulation and defines the Google Cloud Storage bucket for benchmark data. Ensure pandas is installed via pip.

```python
import pandas as pd  # pip install pandas

GCP_BUCKET = "gs://contrails-301217-benchmark-data"
```

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

### Load and display example flight data

Source: https://github.com/contrailcirrus/pycontrails/blob/main/tests/benchmark/cocip/review.ipynb

Loads a specific flight's output data from a Parquet file into a pandas DataFrame and displays the first few rows. It also extracts the flight ID.

```python
flight = pd.read_parquet(f"outputs/flight/{flight_example}")
flight_id = flight["flight_id"][0]

flight.head()
```

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

### Initialize an xarray.Dataset

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Meteorology.ipynb

Creates a new xarray.Dataset with specified data variables and coordinates. This is a foundational step before wrapping it with MetDataset.

```python
ds = xr.Dataset(
    {
        "random": (["longitude", "latitude", "level", "time"], rng.random((20, 15, 4, 5))),
        "ones": (["longitude", "latitude", "level", "time"], np.ones((20, 15, 4, 5))),
    },
    coords={
        "longitude": np.arange(-100, -80, 1.0),
        "latitude": np.arange(30, 45, 1.0),
        "level": np.arange(100, 500, 100),
        "time": [datetime(2021, 1, 1, h) for h in range(5)],
    },
)
```

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

### Plot Specific Humidity Data

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ICON.ipynb

Plot the specific humidity data from the MetDataset. This example demonstrates selecting a specific timestep and level, transposing the data for plotting, and applying a colormap with coastlines using Cartopy.

```python
mds["specific_humidity"].data[..., 14, -1].T.plot(
    figsize=(10, 4),
    cmap="Blues",
    subplot_kws=dict(projection=ccrs.PlateCarree(), transform=ccrs.PlateCarree()),
).axes.coastlines();
```

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

### Initialize ICON with Specific Forecast Time

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ICON.ipynb

Initialize the ICON data class, specifying a time range, a particular forecast cycle, and desired variables. The output shows the selected timesteps, variables, pressure levels, grid, domain, and forecast time.

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

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

### Plot Flight Data and Get Max Distance Gap

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Flight.ipynb

Generates a scatter plot of flight data and retrieves the maximum distance gap between waypoints. Useful for visualizing flight path and identifying large gaps.

```python
fl.plot(kind="scatter", s=5, figsize=(10, 6))
fl.max_distance_gap
```

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

### Apply Humidity Scaling to Flight Data

Source: https://context7.com/contrailcirrus/pycontrails/llms.txt

Humidity scaling models adjust specific humidity to improve contrail prediction accuracy. This example demonstrates applying constant, exponential boost, and histogram matching scaling methods to flight data.

```python
from pycontrails import Flight
from pycontrails.models.humidity_scaling import (
    ConstantHumidityScaling,
    ExponentialBoostHumidityScaling,
    HistogramMatching,
)
import numpy as np
import pandas as pd

# Constant scaling (simple multiplicative adjustment)
constant_scaler = ConstantHumidityScaling(rhi_adj=0.97)

# Exponential boost scaling (latitude-dependent)
exp_scaler = ExponentialBoostHumidityScaling(
    rhi_adj=0.97,
    rhi_boost_exponent=1.7,
)

# Histogram matching (data-driven calibration)
hist_scaler = HistogramMatching(
    product_type="reanalysis",
    level_type="pressure",
)

# Apply scaling to flight data
flight = Flight(
    longitude=np.linspace(-40, -60, 50),
    latitude=np.linspace(35, 50, 50),
    altitude=np.full(50, 10500),
    time=pd.date_range("2022-03-01T00:00", periods=50, freq="2min"),
)
flight["specific_humidity"] = np.full(50, 2e-5)
flight["air_temperature"] = np.full(50, 220)

scaled = constant_scaler.eval(flight)
print(f"Scaled RHi range: {scaled['rhi'].min():.2f} - {scaled['rhi'].max():.2f}")
```

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

### Initialize HRES Data Request

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ECMWF.ipynb

Configure the HRES class with specific time ranges, variables, and pressure levels.

```python
time = datetime(2022, 3, 26, 0), datetime(2022, 3, 26, 2)
hres = HRES(
    time=time,
    variables=["t", "q", "u", "v", "w", "z"],
    pressure_levels=[300, 250, 200],
    grid=1,
    # url="https://api.ecmwf.int/v1",
    # key="<key>"
    # email="<email>"
)
hres
```

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

### Initialize and evaluate CoCiP model

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/ARCO-ERA5.ipynb

Initializes the CoCiP model with meteorological and radiative data, integration time step, max age, aircraft performance model, and humidity scaling. Evaluates the model on the list of synthetic flights.

```python
cocip = Cocip(
    met=met,
    rad=rad,
    dt_integration="1min",
    max_age="8h",
    aircraft_performance=PSFlight(),
    humidity_scaling=ConstantHumidityScaling(rhi_adj=0.95),
)
fl_list = cocip.eval(fl_list)
```

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

### View available GRUAN products and sites

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/GRUAN.ipynb

Use the `AVAILABLE` attribute to list all available GRUAN data products and the sites they are associated with. This helps in identifying the correct product and site for data retrieval.

```python
# Use the AVAILABLE attribute to see available products and sites
GRUAN.AVAILABLE
```

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

### Prepare GFS Data for CoCiP

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/GFS.ipynb

Instantiate `GFSForecast` for both meteorological and radiative variables required by the CoCiP model. `show_progress=True` enables download progress display.

```python
time_bounds = ("2022-03-01 00:00:00", "2022-03-01 23:00:00")
pressure_levels = [300, 250, 200]

gfs_met = GFSForecast(time_bounds, variables=Cocip.met_variables, pressure_levels=pressure_levels, show_progress=True)

gfs_rad = GFSForecast(time_bounds, variables=Cocip.rad_variables, show_progress=True)
```

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

### Visualize Himawari Dynamic Target Region Imagery

Source: https://github.com/contrailcirrus/pycontrails/blob/main/docs/notebooks/Himawari.ipynb

Retrieves and visualizes Himawari satellite data for a dynamic target region ('T') using an 'ash' color scheme. This example uses the source coordinate reference system for the map projection. Imagery is available every 2.5 minutes.

```python
hima = Himawari(region="T")

t = "2025-09-14T03:00:00"
da_h = hima.get(t)

rgb, src_crs, src_extent = extract_himawari_visualization(da_h, color_scheme="ash")

fig = plt.figure(figsize=(10, 10))
ax = fig.add_subplot(projection=src_crs)
ax.imshow(rgb, extent=src_extent, transform=src_crs, interpolation="none")

ax.coastlines(resolution="50m", color="black", linewidth=0.5)
ax.add_feature(cfeature.BORDERS, edgecolor="black", linewidth=0.5)
ax.set_title(f"Himawari-9 Ash RGB {t} UTC", fontsize=16);
```