# noaa-gfdl/pace architecture

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

- Interactive diagram: https://gitdiagram.com/noaa-gfdl/pace
- Repository: https://github.com/noaa-gfdl/pace

## Overview

Pace is a Python orchestration layer for the FV3GFS/SHiELD atmospheric model. The documented user workflow is to launch `pace.run` with a YAML configuration; it builds and runs the driver, which coordinates grid and initial-state setup, model dynamics and physics, and diagnostics. The repository excerpts support the CLI-to-driver path and several module dependencies, but do not show the full timestep implementation. The README documents the dynamics/physics submodule roles; their internal implementations were not sampled.

Main entry points: [`pace/driver.py`](https://github.com/noaa-gfdl/pace/blob/develop/pace/driver.py) (Simulation driver), [`pace/diagnostics.py`](https://github.com/noaa-gfdl/pace/blob/develop/pace/diagnostics.py) (Diagnostics output), [`pace/state.py`](https://github.com/noaa-gfdl/pace/blob/develop/pace/state.py) (Model state), [`pace/run.py`](https://github.com/noaa-gfdl/pace/blob/develop/pace/run.py) (Run CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Execution"]
  node_cli["Run CLI<br/>[run.py]"]
  node_driver["Simulation driver<br/>[driver.py]"]
  node_registry["Config registry<br/>[registry.py]"]
end

subgraph group_setup["Model setup"]
  node_communication["Communication<br/>[comm.py]"]
  node_grid["Grid setup<br/>[grid.py]"]
  node_initialization["State initialization<br/>[initialization.py]"]
  node_state["Model state<br/>[state.py]"]
end

subgraph group_simulation["Simulation"]
  node_dynamics["FV3 dynamics"]
  node_physics["SHiELD physics"]
end

subgraph group_outputs["Outputs and checks"]
  node_diagnostics["Diagnostics output<br/>[diagnostics.py]"]
  node_safety["State checks<br/>[safety_checks.py]"]
  node_output["Run output"]
end

node_user(("Model user"))

node_user -->|"launches"| node_cli
node_cli -->|"creates and runs"| node_driver
node_driver -->|"imports"| node_communication
node_driver -->|"imports"| node_grid
node_driver -->|"imports"| node_initialization
node_driver -->|"imports"| node_state
node_driver -->|"imports"| node_diagnostics
node_driver -->|"imports"| node_safety
node_initialization -->|"constructs"| node_state
node_grid -->|"registers types"| node_registry
node_communication -->|"registers types"| node_registry
node_diagnostics -->|"reads"| node_state
node_driver -.->|"runs dynamics"| node_dynamics
node_driver -.->|"runs physics"| node_physics
node_diagnostics -.->|"writes diagnostics"| node_output

click node_cli "https://github.com/noaa-gfdl/pace/blob/develop/pace/run.py"
click node_driver "https://github.com/noaa-gfdl/pace/blob/develop/pace/driver.py"
click node_registry "https://github.com/noaa-gfdl/pace/blob/develop/pace/registry.py"
click node_communication "https://github.com/noaa-gfdl/pace/blob/develop/pace/comm.py"
click node_grid "https://github.com/noaa-gfdl/pace/blob/develop/pace/grid.py"
click node_initialization "https://github.com/noaa-gfdl/pace/blob/develop/pace/initialization.py"
click node_state "https://github.com/noaa-gfdl/pace/blob/develop/pace/state.py"
click node_dynamics "https://github.com/noaa-gfdl/pace/tree/develop/pyFV3"
click node_physics "https://github.com/noaa-gfdl/pace/tree/develop/pySHiELD"
click node_diagnostics "https://github.com/noaa-gfdl/pace/blob/develop/pace/diagnostics.py"
click node_safety "https://github.com/noaa-gfdl/pace/blob/develop/pace/safety_checks.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_cli,node_driver,node_registry,node_user toneBlue
class node_communication,node_grid,node_initialization,node_state toneAmber
class node_dynamics,node_physics toneMint
class node_diagnostics,node_safety,node_output toneRose
```

## Components

### Execution

- [Run CLI](https://github.com/noaa-gfdl/pace/blob/develop/pace/run.py): `pace/run.py`
- [Simulation driver](https://github.com/noaa-gfdl/pace/blob/develop/pace/driver.py): `pace/driver.py`
- [Config registry](https://github.com/noaa-gfdl/pace/blob/develop/pace/registry.py): `pace/registry.py`

### Model setup

- [Communication](https://github.com/noaa-gfdl/pace/blob/develop/pace/comm.py): `pace/comm.py`
- [Grid setup](https://github.com/noaa-gfdl/pace/blob/develop/pace/grid.py): `pace/grid.py`
- [State initialization](https://github.com/noaa-gfdl/pace/blob/develop/pace/initialization.py): `pace/initialization.py`
- [Model state](https://github.com/noaa-gfdl/pace/blob/develop/pace/state.py): `pace/state.py`

### Simulation

- [FV3 dynamics](https://github.com/noaa-gfdl/pace/tree/develop/pyFV3): `pyFV3`
- [SHiELD physics](https://github.com/noaa-gfdl/pace/tree/develop/pySHiELD): `pySHiELD`

### Outputs and checks

- [Diagnostics output](https://github.com/noaa-gfdl/pace/blob/develop/pace/diagnostics.py): `pace/diagnostics.py`
- [State checks](https://github.com/noaa-gfdl/pace/blob/develop/pace/safety_checks.py): `pace/safety_checks.py`
- **Run output**

### Other components

- **Model user**

## Connections

- Model user → Run CLI: launches (evidence: `README.md`)
- Run CLI → Simulation driver: creates and runs (evidence: `pace/run.py`)
- Simulation driver → Communication: imports (evidence: `pace/driver.py`)
- Simulation driver → Grid setup: imports (evidence: `pace/driver.py`)
- Simulation driver → State initialization: imports (evidence: `pace/driver.py`)
- Simulation driver → Model state: imports (evidence: `pace/driver.py`)
- Simulation driver → Diagnostics output: imports (evidence: `pace/driver.py`)
- Simulation driver → State checks: imports (evidence: `pace/driver.py`)
- State initialization → Model state: constructs (evidence: `pace/initialization.py`)
- Grid setup → Config registry: registers types (evidence: `pace/grid.py`)
- Communication → Config registry: registers types (evidence: `pace/comm.py`)
- Diagnostics output → Model state: reads (evidence: `pace/diagnostics.py`)
- Simulation driver → FV3 dynamics: runs dynamics (evidence: `README.md`)
- Simulation driver → SHiELD physics: runs physics (evidence: `README.md`)
- Diagnostics output → Run output: writes diagnostics (evidence: `README.md`)