# contrailcirrus/pycontrails architecture

> Architecture diagram of the GitHub repository contrailcirrus/pycontrails, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/contrailcirrus/pycontrails
- Repository: https://github.com/contrailcirrus/pycontrails

## Overview

pycontrails is a Python library for modeling aircraft contrails and other aviation climate impacts. The main workflow represents aircraft trajectories and meteorology as shared data structures, obtains weather from data-source adapters, then evaluates models such as CoCiP to estimate contrail properties and radiative forcing. Aircraft-performance, emissions, and related models are additional branches built on the same common interfaces. The map uses the README and SOURCE INDEX references; unsampled modules are included where they represent major capabilities, but their internal call paths are not inferred.

Main entry points: [`pycontrails/core/met.py`](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/met.py) (Meteorology data), [`pycontrails/core/flight.py`](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/flight.py) (Flight data), [`pycontrails/models/apcemm/apcemm.py`](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/models/apcemm/apcemm.py) (APCEMM model), [`pycontrails/models/cocip/cocip.py`](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/models/cocip/cocip.py) (CoCiP contrails)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared data"]
  node_flight["Flight data<br/>[flight.py]"]
  node_vector["Vector datasets<br/>[vector.py]"]
  node_fleet["Aircraft fleets<br/>[fleet.py]"]
  node_metdata["Meteorology data<br/>[met.py]"]
  node_metvars["Meteorology variables<br/>[met_var.py]"]
end

subgraph group_sources["Data sources"]
  node_metsource["Weather source interface<br/>[metsource.py]"]
  node_ecmwf["ECMWF weather"]
  node_gfs["GFS weather"]
  node_dwd["DWD ICON weather"]
end

subgraph group_models["Climate models"]
  node_modelbase["Model interfaces<br/>[models.py]"]
  node_cocip["CoCiP contrails<br/>[cocip.py]"]
  node_contrailprops["Contrail properties"]
  node_cocipgrid["CoCiP grid model<br/>[cocip_grid.py]"]
  node_apcemm["APCEMM model<br/>[apcemm.py]"]
  node_emissions["Emissions models"]
  node_humidity["Humidity scaling"]
end

subgraph group_physics["Aircraft and physics"]
  node_performance["Aircraft performance"]
  node_thermo["Thermodynamics<br/>[thermo.py]"]
  node_units["Unit conversions<br/>[units.py]"]
end

subgraph group_satellite["Satellite data"]
  node_satsearch["Satellite search<br/>[search.py]"]
  node_goes["GOES imagery<br/>[goes.py]"]
  node_landsat["Landsat imagery<br/>[landsat.py]"]
  node_sentinel["Sentinel imagery<br/>[sentinel.py]"]
end

node_user(("Library user"))

node_user -->|"provides trajectory"| node_flight
node_user -->|"provides meteorology"| node_metdata
node_user -->|"runs models"| node_modelbase
node_flight -->|"extends"| node_vector
node_fleet -->|"uses"| node_flight
node_metsource -->|"provides weather"| node_metdata
node_ecmwf -->|"provides weather"| node_metdata
node_gfs -->|"provides weather"| node_metdata
node_dwd -->|"provides weather"| node_metdata
node_modelbase -->|"selects variables"| node_metdata
node_modelbase -->|"processes trajectories"| node_flight
node_cocip -->|"uses interface"| node_modelbase
node_cocip -->|"uses trajectory"| node_flight
node_cocip -->|"uses weather"| node_metdata
node_cocip -->|"uses properties"| node_contrailprops
node_contrailprops -->|"uses thermodynamics"| node_thermo
node_contrailprops -->|"uses conversions"| node_units
node_cocipgrid -->|"uses model"| node_cocip
node_cocipgrid -->|"uses properties"| node_contrailprops
node_apcemm -->|"uses interface"| node_modelbase
node_apcemm -->|"uses trajectory"| node_flight
node_apcemm -->|"uses weather"| node_metdata
node_apcemm -->|"uses emissions"| node_emissions
node_apcemm -->|"uses scaling"| node_humidity
node_performance -->|"uses trajectory"| node_flight
node_satsearch -.->|"searches imagery"| node_goes
node_user -.->|"queries imagery"| node_satsearch

click node_flight "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/flight.py"
click node_vector "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/vector.py"
click node_fleet "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/fleet.py"
click node_metdata "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/met.py"
click node_metvars "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/met_var.py"
click node_metsource "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/datalib/_met_utils/metsource.py"
click node_ecmwf "https://github.com/contrailcirrus/pycontrails/tree/main/pycontrails/datalib/ecmwf"
click node_gfs "https://github.com/contrailcirrus/pycontrails/tree/main/pycontrails/datalib/gfs"
click node_dwd "https://github.com/contrailcirrus/pycontrails/tree/main/pycontrails/datalib/dwd"
click node_modelbase "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/models.py"
click node_cocip "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/models/cocip/cocip.py"
click node_contrailprops "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/models/cocip/contrail_properties.py"
click node_cocipgrid "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/models/cocipgrid/cocip_grid.py"
click node_apcemm "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/models/apcemm/apcemm.py"
click node_emissions "https://github.com/contrailcirrus/pycontrails/tree/main/pycontrails/models/emissions"
click node_humidity "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/models/humidity_scaling/humidity_scaling.py"
click node_performance "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/aircraft_performance.py"
click node_thermo "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/physics/thermo.py"
click node_units "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/physics/units.py"
click node_satsearch "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/datalib/leo_utils/search.py"
click node_goes "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/datalib/goes.py"
click node_landsat "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/datalib/landsat.py"
click node_sentinel "https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/datalib/sentinel.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flight,node_vector,node_fleet,node_metdata,node_metvars,node_user toneBlue
class node_metsource,node_ecmwf,node_gfs,node_dwd toneAmber
class node_modelbase,node_cocip,node_contrailprops,node_cocipgrid,node_apcemm,node_emissions,node_humidity toneMint
class node_performance,node_thermo,node_units toneRose
class node_satsearch,node_goes,node_landsat,node_sentinel toneIndigo
```

## Components

### Shared data

- [Flight data](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/flight.py): `pycontrails/core/flight.py`
- [Vector datasets](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/vector.py): `pycontrails/core/vector.py`
- [Aircraft fleets](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/fleet.py): `pycontrails/core/fleet.py`
- [Meteorology data](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/met.py): `pycontrails/core/met.py`
- [Meteorology variables](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/met_var.py): `pycontrails/core/met_var.py`

### Data sources

- [Weather source interface](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/datalib/_met_utils/metsource.py): `pycontrails/datalib/_met_utils/metsource.py`
- [ECMWF weather](https://github.com/contrailcirrus/pycontrails/tree/main/pycontrails/datalib/ecmwf): `pycontrails/datalib/ecmwf`
- [GFS weather](https://github.com/contrailcirrus/pycontrails/tree/main/pycontrails/datalib/gfs): `pycontrails/datalib/gfs`
- [DWD ICON weather](https://github.com/contrailcirrus/pycontrails/tree/main/pycontrails/datalib/dwd): `pycontrails/datalib/dwd`

### Climate models

- [Model interfaces](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/models.py): `pycontrails/core/models.py`
- [CoCiP contrails](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/models/cocip/cocip.py): `pycontrails/models/cocip/cocip.py`
- [Contrail properties](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/models/cocip/contrail_properties.py): `pycontrails/models/cocip/contrail_properties.py`
- [CoCiP grid model](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/models/cocipgrid/cocip_grid.py): `pycontrails/models/cocipgrid/cocip_grid.py`
- [APCEMM model](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/models/apcemm/apcemm.py): `pycontrails/models/apcemm/apcemm.py`
- [Emissions models](https://github.com/contrailcirrus/pycontrails/tree/main/pycontrails/models/emissions): `pycontrails/models/emissions`
- [Humidity scaling](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/models/humidity_scaling/humidity_scaling.py): `pycontrails/models/humidity_scaling/humidity_scaling.py`

### Aircraft and physics

- [Aircraft performance](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/core/aircraft_performance.py): `pycontrails/core/aircraft_performance.py`
- [Thermodynamics](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/physics/thermo.py): `pycontrails/physics/thermo.py`
- [Unit conversions](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/physics/units.py): `pycontrails/physics/units.py`

### Satellite data

- [Satellite search](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/datalib/leo_utils/search.py): `pycontrails/datalib/leo_utils/search.py`
- [GOES imagery](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/datalib/goes.py): `pycontrails/datalib/goes.py`
- [Landsat imagery](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/datalib/landsat.py): `pycontrails/datalib/landsat.py`
- [Sentinel imagery](https://github.com/contrailcirrus/pycontrails/blob/main/pycontrails/datalib/sentinel.py): `pycontrails/datalib/sentinel.py`

### Other components

- **Library user**

## Connections

- Library user → Flight data: provides trajectory
- Library user → Meteorology data: provides meteorology
- Library user → Model interfaces: runs models
- Flight data → Vector datasets: extends (evidence: `pycontrails/core/flight.py`)
- Aircraft fleets → Flight data: uses (evidence: `pycontrails/core/fleet.py`)
- Weather source interface → Meteorology data: provides weather (evidence: `pycontrails/datalib/_met_utils/metsource.py`)
- ECMWF weather → Meteorology data: provides weather (evidence: `pycontrails/datalib/ecmwf/hres.py`)
- GFS weather → Meteorology data: provides weather (evidence: `pycontrails/core/models.py`)
- DWD ICON weather → Meteorology data: provides weather (evidence: `pycontrails/datalib/dwd/icon.py`)
- Model interfaces → Meteorology data: selects variables (evidence: `pycontrails/core/models.py`)
- Model interfaces → Flight data: processes trajectories (evidence: `pycontrails/core/models.py`)
- CoCiP contrails → Model interfaces: uses interface (evidence: `pycontrails/models/cocip/cocip.py`)
- CoCiP contrails → Flight data: uses trajectory (evidence: `pycontrails/models/cocip/cocip.py`)
- CoCiP contrails → Meteorology data: uses weather (evidence: `pycontrails/models/cocip/cocip.py`)
- CoCiP contrails → Contrail properties: uses properties (evidence: `pycontrails/models/cocip/cocip.py`)
- Contrail properties → Thermodynamics: uses thermodynamics (evidence: `pycontrails/models/cocip/contrail_properties.py`)
- Contrail properties → Unit conversions: uses conversions (evidence: `pycontrails/models/cocip/contrail_properties.py`)
- CoCiP grid model → CoCiP contrails: uses model (evidence: `pycontrails/models/cocipgrid/cocip_grid.py`)
- CoCiP grid model → Contrail properties: uses properties (evidence: `pycontrails/models/cocipgrid/cocip_grid.py`)
- APCEMM model → Model interfaces: uses interface (evidence: `pycontrails/models/apcemm/apcemm.py`)
- APCEMM model → Flight data: uses trajectory (evidence: `pycontrails/models/apcemm/apcemm.py`)
- APCEMM model → Meteorology data: uses weather (evidence: `pycontrails/models/apcemm/apcemm.py`)
- APCEMM model → Emissions models: uses emissions (evidence: `pycontrails/models/apcemm/apcemm.py`)
- APCEMM model → Humidity scaling: uses scaling (evidence: `pycontrails/models/apcemm/apcemm.py`)
- Aircraft performance → Flight data: uses trajectory (evidence: `pycontrails/core/aircraft_performance.py`)
- Satellite search → GOES imagery: searches imagery
- Library user → Satellite search: queries imagery
