# umep-dev/umep-core architecture

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

- Interactive diagram: https://gitdiagram.com/umep-dev/umep-core
- Repository: https://github.com/umep-dev/umep-core

## Overview

##### Project type and purpose
- This is a Python-based scientific library (“UMEP Core”) for urban climate and thermal comfort calculations.
- It exposes a set of algorithms (shadow, sky-view factor, SOLWEIG) in a headless library, driven by scripts in the `demos/` folder.
- It is packaged with `pyproject.toml`, tested under `tests/`, and released via GitHub Actions to PyPI.

##### File structure
Top level:
- `.github/workflows/python-publish.yml` – CI/CD pipeline for building and publishing
- `pyproject.toml` – package metadata, dependencies, entry points
- `umep/` – the core library module
– `functions/` – SOLWEIG and related thermal-radiation algorithms (COMFA, PET, etc.)
– `shadow_generator_algorithm.py`, `skyviewfactor_algorithm.py`, `solweig_algorithm.py`, `wall_heightaspect_algorithm.py` – pre-processing and solver entrypoints
– `class_configs.py`, `common.py`, `parametersforsolweig.json`, `configsolweig.ini` – configuration and common utilities
– `util/` – vendor code from SEBESOLWEIGCommonFiles and other misc utilities
- `demos/` – example Python scripts plus demo datasets (GeoTIFF, shapefiles, EPW weather files)
- `tests/` – unit tests for core calculations
- `deprecated/` – legacy code kept for reference

##### README insights
- Headless Python workflows (no QGIS dependency)
- Demo scripts at `/demos` and testing workflows
- Upstream origin from UMEP-processing and GPLv3 license

##### Capturing essential elements
- Tests as a parallel validation flow fed from Core Solver outputs back to `tests/`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Demo/CLI Layer
    subgraph "Demo/CLI Layer"
        direction TB
        AthensDemo["athens-demo.py"]:::code
        SmallNbhd["small_nbhd_walls.py"]:::code
        SolweigGbg["solweig_gbg_test.py"]:::code
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        CoreConfigIni["configsolweig.ini"]:::config
        ParamsJson["parametersforsolweig.json"]:::config
        DemoConfigIni["demos/data/athens/configsolweig.ini"]:::config
        DemoParamsJson["demos/data/athens/parametersforsolweig.json"]:::config
    end

    %% Data Sources & Formats
    subgraph "Data Sources & Formats"
        direction TB
        RasterInputs["Raster Inputs (.tif)"]:::data
        VectorInputs["Vector Inputs (.shp/.geojson)"]:::data
        WeatherFiles["Weather Files (.epw/.txt)"]:::data
    end

    %% Preprocessing Algorithms
    subgraph "Preprocessing Algorithms"
        direction TB
        ShadowGen["shadow_generator_algorithm.py"]:::code
        SkyView["skyviewfactor_algorithm.py"]:::code
        WallHeight["wall_heightaspect_algorithm.py"]:::code
    end

    %% Core Solver
    subgraph "Core Solver"
        direction TB
        SolweigAlgo["solweig_algorithm.py"]:::code
        COMFA["COMFA Sub-Modules"]:::code
        RadiationVeg["Radiation & Vegetation"]:::code
    end

    %% Utility & Vendor Code
    subgraph "Utility & Vendor Code"
        direction TB
        CommonPy["common.py"]:::code
        ClassConfigs["class_configs.py"]:::code
        MiscUtil["misc.py"]:::code
        VendorCode["SEBESOLWEIGCommonFiles"]:::code
    end

    %% Outputs
    subgraph "Outputs"
        direction TB
        SymbologyDB["symbology-style.db"]:::output
        ExportComponent["umep_solweig_export_component.py"]:::output
    end

    %% Testing
    subgraph "Testing"
        direction TB
        UnitTests["tests/test_common.py"]:::test
    end

    %% Deployment
    subgraph "Deployment"
        direction TB
        CIworkflow["python-publish.yml"]:::deploy
        PyPI["pyproject.toml"]:::deploy
    end

    %% Connections
    AthensDemo -->|uses config| CoreConfigIni
    AthensDemo -->|uses params| ParamsJson
    AthensDemo -->|reads data| RasterInputs
    AthensDemo -->|reads data| VectorInputs
    AthensDemo -->|reads data| WeatherFiles

    SmallNbhd -->|uses config| DemoConfigIni
    SmallNbhd -->|uses params| DemoParamsJson
    SmallNbhd -->|reads data| RasterInputs
    SmallNbhd -->|reads data| VectorInputs

    SolweigGbg -->|uses config| DemoConfigIni
    SolweigGbg -->|uses params| DemoParamsJson
    SolweigGbg -->|reads data| WeatherFiles

    RasterInputs --> ShadowGen
    VectorInputs --> SkyView
    VectorInputs --> WallHeight

    CoreConfigIni --> ShadowGen
    CoreConfigIni --> SkyView
    CoreConfigIni --> WallHeight
    ParamsJson --> SolweigAlgo

    ShadowGen --> SolweigAlgo
    SkyView --> SolweigAlgo
    WallHeight --> SolweigAlgo

    SolweigAlgo --> COMFA
    SolweigAlgo --> RadiationVeg

    CommonPy --> ShadowGen
    CommonPy --> SolweigAlgo
    ClassConfigs --> SolweigAlgo
    MiscUtil --> SolweigAlgo
    VendorCode --> SolweigAlgo

    SolweigAlgo --> SymbologyDB
    SolweigAlgo --> ExportComponent

    SymbologyDB --> UnitTests
    ExportComponent --> UnitTests

    SolweigAlgo -->|validated by| UnitTests

    CIworkflow -->|publishes| PyPI

    %% Click Events
    click AthensDemo "https://github.com/umep-dev/umep-core/blob/main/demos/athens-demo.py"
    click SmallNbhd "https://github.com/umep-dev/umep-core/blob/main/demos/small_nbhd_walls.py"
    click SolweigGbg "https://github.com/umep-dev/umep-core/blob/main/demos/solweig_gbg_test.py"

    click CoreConfigIni "https://github.com/umep-dev/umep-core/blob/main/umep/configsolweig.ini"
    click ParamsJson "https://github.com/umep-dev/umep-core/blob/main/umep/parametersforsolweig.json"
    click DemoConfigIni "https://github.com/umep-dev/umep-core/blob/main/demos/data/athens/configsolweig.ini"
    click DemoParamsJson "https://github.com/umep-dev/umep-core/blob/main/demos/data/athens/parametersforsolweig.json"

    click ShadowGen "https://github.com/umep-dev/umep-core/blob/main/umep/shadow_generator_algorithm.py"
    click SkyView "https://github.com/umep-dev/umep-core/blob/main/umep/skyviewfactor_algorithm.py"
    click WallHeight "https://github.com/umep-dev/umep-core/blob/main/umep/wall_heightaspect_algorithm.py"

    click SolweigAlgo "https://github.com/umep-dev/umep-core/blob/main/umep/solweig_algorithm.py"
    click COMFA "https://github.com/umep-dev/umep-core/tree/main/umep/functions/SOLWEIGpython/COMFA"
    click RadiationVeg "https://github.com/umep-dev/umep-core/tree/main/umep/functions/SOLWEIGpython"

    click CommonPy "https://github.com/umep-dev/umep-core/blob/main/umep/common.py"
    click ClassConfigs "https://github.com/umep-dev/umep-core/blob/main/umep/class_configs.py"
    click MiscUtil "https://github.com/umep-dev/umep-core/blob/main/umep/util/misc.py"
    click VendorCode "https://github.com/umep-dev/umep-core/tree/main/umep/util/SEBESOLWEIGCommonFiles"

    click RasterInputs "https://github.com/umep-dev/umep-core/blob/main/demos/data/Goteborg_SWEREF99_1200/DEM_KRbig.tif"
    click VectorInputs "https://github.com/umep-dev/umep-core/blob/main/demos/data/Goteborg_SWEREF99_1200/buildings.shp"
    click WeatherFiles "https://github.com/umep-dev/umep-core/blob/main/demos/data/athens/athens_2023.epw"

    click SymbologyDB "https://github.com/umep-dev/umep-core/blob/main/symbology-style.db"
    click ExportComponent "https://github.com/umep-dev/umep-core/blob/main/umep/util/umep_solweig_export_component.py"

    click UnitTests "https://github.com/umep-dev/umep-core/blob/main/tests/test_common.py"
    click CIworkflow "https://github.com/umep-dev/umep-core/blob/main/.github/workflows/python-publish.yml"
    click PyPI "https://github.com/umep-dev/umep-core/blob/main/pyproject.toml"

    %% Styles
    classDef code fill:#cce5ff,stroke:#036,stroke-width:1px
    classDef data fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef output fill:#ffe5b4,stroke:#cc5500,stroke-width:1px
    classDef test fill:#f5c6cb,stroke:#721c24,stroke-width:1px
    classDef deploy fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
```
