# umep-dev/suews architecture

> Architecture diagram of the GitHub repository umep-dev/suews, 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/umep-dev/suews
- Repository: https://github.com/umep-dev/suews

## Overview

SUEWS is an urban land-surface model, with SuPy providing Python and command-line interfaces for configuring and running neighbourhood-scale energy and water balance simulations. The primary workflow takes configuration and meteorological forcing through validation and model execution, then exposes simulation output for analysis. Separate branches cover configuration conversion, schema and knowledge access, and optional MCP access. The README documents the Fortran physics engine and major physical schemes; sampled source is incomplete, so internal links not established by the evidence are omitted.

Main entry points: [`src/supy/_run.py`](https://github.com/umep-dev/suews/blob/master/src/supy/_run.py) (Simulation control), [`src/suews/src`](https://github.com/umep-dev/suews/tree/master/src/suews/src) (Fortran physics), [`src/supy/cmd/suews_cli.py`](https://github.com/umep-dev/suews/blob/master/src/supy/cmd/suews_cli.py) (SUEWS CLI), [`mcp/src/suews_mcp/server.py`](https://github.com/umep-dev/suews/blob/master/mcp/src/suews_mcp/server.py) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_cli["SUEWS CLI<br/>[suews_cli.py]"]
end

subgraph group_simulation["Simulation workflow"]
  node_config["YAML configuration<br/>[config.py]"]
  node_validation["Config validation<br/>[orchestrator.py]"]
  node_forcing["Forcing preparation<br/>[_load.py]"]
  node_run["Simulation control<br/>[_run.py]"]
  node_bridge["Rust bridge<br/>[_run_rust.py]"]
  node_output["Simulation output<br/>[_run_output.py]"]
  node_postprocess["Output analysis<br/>[_post.py]"]
end

subgraph group_model["Model capabilities"]
  node_physics["Fortran physics"]
  node_radiation["Radiation schemes"]
  node_storage["Heat storage schemes"]
  node_building["Building energy"]
  node_water["Water balance<br/>[hydro.py]"]
end

subgraph group_utilities["Configuration and analysis"]
  node_convert["Config conversion"]
  node_schema["Schema tools<br/>[registry.py]"]
  node_knowledge["Knowledge pack<br/>[pack.py]"]
  node_diagnostics["Run diagnostics<br/>[_checks.py]"]
end

subgraph group_mcp["MCP integration"]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_mcp_tools["MCP tools"]
  node_mcp_resources["MCP resources"]
end

node_user(("Model user"))

node_user -->|"uses"| node_python_api
node_user -->|"invokes"| node_cli
node_python_api -->|"runs simulation"| node_run
node_cli -->|"validates config"| node_validation
node_cli -->|"runs simulation"| node_run
node_config -->|"validated by"| node_validation
node_validation -->|"checks config"| node_run
node_run -->|"prepares inputs"| node_forcing
node_run -->|"invokes"| node_bridge
node_bridge -->|"calls engine"| node_physics
node_physics -->|"produces"| node_output
node_run -->|"returns output"| node_output
node_output -->|"analyzed by"| node_postprocess
node_radiation -.->|"parameterizes"| node_physics
node_storage -.->|"parameterizes"| node_physics
node_building -.->|"parameterizes"| node_physics
node_water -.->|"parameterizes"| node_physics
node_user -->|"converts config"| node_convert
node_user -->|"queries schema"| node_schema
node_user -->|"queries knowledge"| node_knowledge
node_user -->|"checks run"| node_diagnostics
node_mcp_server -->|"registers tools"| node_mcp_tools
node_mcp_server -->|"registers resources"| node_mcp_resources
node_user -.->|"connects via MCP"| node_mcp_server
node_mcp_tools -.->|"invokes CLI"| node_cli

click node_python_api "https://github.com/umep-dev/suews/blob/master/src/supy/__init__.py"
click node_cli "https://github.com/umep-dev/suews/blob/master/src/supy/cmd/suews_cli.py"
click node_config "https://github.com/umep-dev/suews/blob/master/src/supy/data_model/core/config.py"
click node_validation "https://github.com/umep-dev/suews/blob/master/src/supy/data_model/validation/pipeline/orchestrator.py"
click node_forcing "https://github.com/umep-dev/suews/blob/master/src/supy/_load.py"
click node_run "https://github.com/umep-dev/suews/blob/master/src/supy/_run.py"
click node_bridge "https://github.com/umep-dev/suews/blob/master/src/supy/_run_rust.py"
click node_physics "https://github.com/umep-dev/suews/tree/master/src/suews/src"
click node_output "https://github.com/umep-dev/suews/blob/master/src/supy/_run_output.py"
click node_postprocess "https://github.com/umep-dev/suews/blob/master/src/supy/_post.py"
click node_radiation "https://github.com/umep-dev/suews/blob/master/src/supy/data_model/core/physics_families.py"
click node_storage "https://github.com/umep-dev/suews/blob/master/src/supy/data_model/core/physics_families.py"
click node_building "https://github.com/umep-dev/suews/blob/master/src/supy/data_model/core/physics_families.py"
click node_water "https://github.com/umep-dev/suews/blob/master/src/supy/data_model/core/hydro.py"
click node_convert "https://github.com/umep-dev/suews/blob/master/src/supy/util/conversion_engine.py"
click node_schema "https://github.com/umep-dev/suews/blob/master/src/supy/data_model/schema/registry.py"
click node_knowledge "https://github.com/umep-dev/suews/blob/master/src/supy/knowledge/pack.py"
click node_diagnostics "https://github.com/umep-dev/suews/blob/master/src/supy/diagnostics/_checks.py"
click node_mcp_server "https://github.com/umep-dev/suews/blob/master/mcp/src/suews_mcp/server.py"
click node_mcp_tools "https://github.com/umep-dev/suews/tree/master/mcp/src/suews_mcp/tools"
click node_mcp_resources "https://github.com/umep-dev/suews/tree/master/mcp/src/suews_mcp/resources"

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_python_api,node_cli,node_user toneBlue
class node_config,node_validation,node_forcing,node_run,node_bridge,node_output,node_postprocess toneAmber
class node_physics,node_radiation,node_storage,node_building,node_water toneMint
class node_convert,node_schema,node_knowledge,node_diagnostics toneRose
class node_mcp_server,node_mcp_tools,node_mcp_resources toneIndigo
```

## Components

### User interfaces

- [Python API](https://github.com/umep-dev/suews/blob/master/src/supy/__init__.py): `src/supy/__init__.py`
- [SUEWS CLI](https://github.com/umep-dev/suews/blob/master/src/supy/cmd/suews_cli.py): `src/supy/cmd/suews_cli.py`

### Simulation workflow

- [YAML configuration](https://github.com/umep-dev/suews/blob/master/src/supy/data_model/core/config.py): `src/supy/data_model/core/config.py`
- [Config validation](https://github.com/umep-dev/suews/blob/master/src/supy/data_model/validation/pipeline/orchestrator.py): `src/supy/data_model/validation/pipeline/orchestrator.py`
- [Forcing preparation](https://github.com/umep-dev/suews/blob/master/src/supy/_load.py): `src/supy/_load.py`
- [Simulation control](https://github.com/umep-dev/suews/blob/master/src/supy/_run.py): `src/supy/_run.py`
- [Rust bridge](https://github.com/umep-dev/suews/blob/master/src/supy/_run_rust.py): `src/supy/_run_rust.py`
- [Simulation output](https://github.com/umep-dev/suews/blob/master/src/supy/_run_output.py): `src/supy/_run_output.py`
- [Output analysis](https://github.com/umep-dev/suews/blob/master/src/supy/_post.py): `src/supy/_post.py`

### Model capabilities

- [Fortran physics](https://github.com/umep-dev/suews/tree/master/src/suews/src): `src/suews/src`
- [Radiation schemes](https://github.com/umep-dev/suews/blob/master/src/supy/data_model/core/physics_families.py): `src/supy/data_model/core/physics_families.py`
- [Heat storage schemes](https://github.com/umep-dev/suews/blob/master/src/supy/data_model/core/physics_families.py): `src/supy/data_model/core/physics_families.py`
- [Building energy](https://github.com/umep-dev/suews/blob/master/src/supy/data_model/core/physics_families.py): `src/supy/data_model/core/physics_families.py`
- [Water balance](https://github.com/umep-dev/suews/blob/master/src/supy/data_model/core/hydro.py): `src/supy/data_model/core/hydro.py`

### Configuration and analysis

- [Config conversion](https://github.com/umep-dev/suews/blob/master/src/supy/util/conversion_engine.py): `src/supy/util/conversion_engine.py`
- [Schema tools](https://github.com/umep-dev/suews/blob/master/src/supy/data_model/schema/registry.py): `src/supy/data_model/schema/registry.py`
- [Knowledge pack](https://github.com/umep-dev/suews/blob/master/src/supy/knowledge/pack.py): `src/supy/knowledge/pack.py`
- [Run diagnostics](https://github.com/umep-dev/suews/blob/master/src/supy/diagnostics/_checks.py): `src/supy/diagnostics/_checks.py`

### MCP integration

- [MCP server](https://github.com/umep-dev/suews/blob/master/mcp/src/suews_mcp/server.py): `mcp/src/suews_mcp/server.py`
- [MCP tools](https://github.com/umep-dev/suews/tree/master/mcp/src/suews_mcp/tools): `mcp/src/suews_mcp/tools`
- [MCP resources](https://github.com/umep-dev/suews/tree/master/mcp/src/suews_mcp/resources): `mcp/src/suews_mcp/resources`

### Other components

- **Model user**

## Connections

- Model user → Python API: uses
- Model user → SUEWS CLI: invokes
- Python API → Simulation control: runs simulation
- SUEWS CLI → Config validation: validates config
- SUEWS CLI → Simulation control: runs simulation
- YAML configuration → Config validation: validated by
- Config validation → Simulation control: checks config
- Simulation control → Forcing preparation: prepares inputs
- Simulation control → Rust bridge: invokes
- Rust bridge → Fortran physics: calls engine
- Fortran physics → Simulation output: produces
- Simulation control → Simulation output: returns output
- Simulation output → Output analysis: analyzed by
- Radiation schemes → Fortran physics: parameterizes
- Heat storage schemes → Fortran physics: parameterizes
- Building energy → Fortran physics: parameterizes
- Water balance → Fortran physics: parameterizes
- Model user → Config conversion: converts config
- Model user → Schema tools: queries schema
- Model user → Knowledge pack: queries knowledge
- Model user → Run diagnostics: checks run
- MCP server → MCP tools: registers tools
- MCP server → MCP resources: registers resources
- Model user → MCP server: connects via MCP
- MCP tools → SUEWS CLI: invokes CLI