# envdes/pyclmuapp architecture

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

- Interactive diagram: https://gitdiagram.com/envdes/pyclmuapp
- Repository: https://github.com/envdes/pyclmuapp

## Overview

pyclmuapp prepares and runs urban-climate simulations with CLMU in Docker or Singularity: users provide or create forcing and urban surface inputs, configure a case, execute it, and inspect model outputs. The CLI is the evidenced runtime entry point; the README also documents U-Surf and local-climate-zone integration. Several subsystems are represented by their exact tree paths, but their wiring is not established by the sampled excerpts, so uncertain links are omitted.

Main entry points: [`pyclmuapp/usp.py`](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/usp.py) (USP simulation workflow), [`pyclmuapp/_cli.py`](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/_cli.py) (CLI workflow), [`pyclmuapp/era5_forcing.py`](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/era5_forcing.py) (Forcing acquisition), [`dockerfile/pyclmuapp/clmuapp.py`](https://github.com/envdes/pyclmuapp/blob/main/dockerfile/pyclmuapp/clmuapp.py) (Web interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI workflow<br/>[_cli.py]"]
  node_web["Web interface<br/>[clmuapp.py]"]
end

subgraph group_inputs["Simulation inputs"]
  node_caseconfig["Case configuration<br/>[config_man.json]"]
  node_surface["Surface and domain inputs<br/>[usp.py]"]
  node_surfacegen["Surface data creation<br/>[input_data.py]"]
  node_citydata["City and LCZ integration<br/>[getcity.py]"]
  node_forcingapi["Forcing acquisition<br/>[era5_forcing.py]"]
  node_forcingconvert["Forcing conversion<br/>[era_forcing.py]"]
  node_forcinggee["GEE forcing path"]
end

subgraph group_runtime["Case execution"]
  node_usp["USP simulation workflow<br/>[usp.py]"]
  node_pts["PTS workflow<br/>[pts.py]"]
  node_caseops["CLMU case operations<br/>[clmu.py]"]
  node_container["Container control<br/>[container.py]"]
end

subgraph group_results["Outputs and data"]
  node_outputs["Simulation outputs"]
  node_inspect["Output inspection<br/>[usp.py]"]
  node_forcingfile["Forcing NetCDF"]
end

node_user(("Research user"))
node_era5service(("ERA5 services"))
node_containerengine{{"Container runtime"}}
node_clmu{{"CLMU model"}}

node_user -->|"runs"| node_cli
node_cli -->|"invokes"| node_usp
node_cli -->|"requests forcing"| node_forcingapi
node_cli -->|"loads defaults"| node_caseconfig
node_user -.->|"uses"| node_web
node_web -->|"runs simulation"| node_usp
node_web -->|"creates forcing"| node_forcingapi
node_forcingapi -.->|"retrieves data"| node_era5service
node_forcingapi -->|"converts data"| node_forcingconvert
node_forcingconvert -->|"writes"| node_forcingfile
node_forcinggee -.->|"retrieves data"| node_era5service
node_usp -->|"checks and modifies"| node_surface
node_usp -->|"prepares case"| node_caseops
node_usp -->|"dispatches run"| node_container
node_pts -->|"prepares case"| node_caseops
node_pts -->|"dispatches run"| node_container
node_caseops -->|"configures case"| node_clmu
node_container -->|"controls"| node_containerengine
node_containerengine -->|"runs model"| node_clmu
node_clmu -->|"writes results"| node_outputs
node_usp -->|"reads outputs"| node_inspect
node_inspect -->|"opens NetCDF"| node_outputs

click node_cli "https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/_cli.py"
click node_web "https://github.com/envdes/pyclmuapp/blob/main/dockerfile/pyclmuapp/clmuapp.py"
click node_caseconfig "https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/config/config_man.json"
click node_surface "https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/usp.py"
click node_surfacegen "https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/input_data.py"
click node_citydata "https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/getcity.py"
click node_forcingapi "https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/era5_forcing.py"
click node_forcingconvert "https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/era_forcing.py"
click node_forcinggee "https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/era5_forcing_gee.py"
click node_usp "https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/usp.py"
click node_pts "https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/pts.py"
click node_caseops "https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/clmu.py"
click node_container "https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/container.py"
click node_inspect "https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/usp.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_web,node_user toneBlue
class node_caseconfig,node_surface,node_surfacegen,node_citydata,node_forcingapi,node_forcingconvert,node_forcinggee toneAmber
class node_usp,node_pts,node_caseops,node_container toneMint
class node_outputs,node_inspect,node_forcingfile toneRose
class node_era5service,node_containerengine,node_clmu toneIndigo
```

## Components

### User interfaces

- [CLI workflow](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/_cli.py): `pyclmuapp/_cli.py`
- [Web interface](https://github.com/envdes/pyclmuapp/blob/main/dockerfile/pyclmuapp/clmuapp.py): `dockerfile/pyclmuapp/clmuapp.py`

### Simulation inputs

- [Case configuration](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/config/config_man.json): `pyclmuapp/config/config_man.json`
- [Surface and domain inputs](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/usp.py): `pyclmuapp/usp.py`
- [Surface data creation](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/input_data.py): `pyclmuapp/input_data.py`
- [City and LCZ integration](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/getcity.py): `pyclmuapp/getcity.py`
- [Forcing acquisition](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/era5_forcing.py): `pyclmuapp/era5_forcing.py`
- [Forcing conversion](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/era_forcing.py): `pyclmuapp/era_forcing.py`
- [GEE forcing path](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/era5_forcing_gee.py): `pyclmuapp/era5_forcing_gee.py`

### Case execution

- [USP simulation workflow](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/usp.py): `pyclmuapp/usp.py`
- [PTS workflow](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/pts.py): `pyclmuapp/pts.py`
- [CLMU case operations](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/clmu.py): `pyclmuapp/clmu.py`
- [Container control](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/container.py): `pyclmuapp/container.py`

### Outputs and data

- **Simulation outputs**
- [Output inspection](https://github.com/envdes/pyclmuapp/blob/main/pyclmuapp/usp.py): `pyclmuapp/usp.py`
- **Forcing NetCDF**

### Other components

- **Research user**
- **ERA5 services**
- **Container runtime**
- **CLMU model**

## Connections

- Research user → CLI workflow: runs
- CLI workflow → USP simulation workflow: invokes
- CLI workflow → Forcing acquisition: requests forcing
- CLI workflow → Case configuration: loads defaults
- Research user → Web interface: uses
- Web interface → USP simulation workflow: runs simulation
- Web interface → Forcing acquisition: creates forcing
- Forcing acquisition → ERA5 services: retrieves data
- Forcing acquisition → Forcing conversion: converts data
- Forcing conversion → Forcing NetCDF: writes
- GEE forcing path → ERA5 services: retrieves data
- USP simulation workflow → Surface and domain inputs: checks and modifies
- USP simulation workflow → CLMU case operations: prepares case
- USP simulation workflow → Container control: dispatches run
- PTS workflow → CLMU case operations: prepares case
- PTS workflow → Container control: dispatches run
- CLMU case operations → CLMU model: configures case
- Container control → Container runtime: controls
- Container runtime → CLMU model: runs model
- CLMU model → Simulation outputs: writes results
- USP simulation workflow → Output inspection: reads outputs
- Output inspection → Simulation outputs: opens NetCDF