# climada-project/climada_python architecture

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

- Interactive diagram: https://gitdiagram.com/climada-project/climada_python
- Repository: https://github.com/climada-project/climada_python

## Overview

##### Project Type and Purpose
- CLIMADA Python (`climada_python`) is an open-source scientific software library (not a web or client-server app) for probabilistic climate risk assessment and adaptation option appraisal.
- It provides core modules for hazard event handling, exposure and impact functions, engine routines (forecast, impact, cost-benefit, uncertainty), and utility routines (API client, data I/O, plotting, calibration).

##### File Structure Analysis
- Top-level packaging:
- `climada/` – the Python package root
- `climada/engine/` – core computation modules
- `climada/entity/` – definitions of exposures, impact functions, measures, discount rates
- `climada/hazard/` – hazard data loaders, centroid computations, tracks, scenario modules
- `climada/util/` – supporting utilities (config, I/O, calibration wrappers, plotting, etc.)
- `climada/data/` – example/demo/system data shipped with the package
- Tests are co-located under each subpackage’s `test/` folder.
- Configuration & metadata: `climada.conf`, `.pre-commit-config.yaml`, `pyproject.toml`, `setup.py`.
- Documentation: `doc/` (Sphinx source, tutorials, guides); GitHub Actions / Jenkins scripts under `.github/` and `script/jenkins/`.

##### README Insights
- CLIMADA core focuses on probabilistic impact, uncertainty, forecast, and adaptation appraisal.
- Data ingest can occur via a hosted Data API (`util/api_client.py`).
- Tutorials demonstrate example notebooks that wire modules together.

a. Main Components
- Package Interface (User API)
- Data Ingestion Layer
- Local demo/system data (`climada/data/`)
- Remote Data API client (`climada/util/api_client.py`)
- Core Engine Modules (`climada/engine/`)
- Forecast, Impact, Cost-Benefit, Calibration (uncertainty)
- Entity Layer (`climada/entity/`)
- Exposures, Impact Function Sets, Measures, Discount Rates
- Hazard Layer (`climada/hazard/`)
- Event generation (tropical cyclone, storm Europe, etc.), centroid computations
- Utility Layer (`climada/util/`)
- Configuration, I/O, Plotting, Calibration optimizers, file handlers
- Output / Visualization
- Plots, HDF5/NetCDF outputs, CSV, Excel
- External Services
- CLIMADA Data API
- Conda-Forge (packaging)
- ReadTheDocs (documentation)
- CI/CD Pipelines
- GitHub Actions, Jenkins, pre-commit

b. Relationships and Data Flow
- User code / notebooks call the Package Interface →
- Interface resolves configuration → chooses Data Ingestion path (local vs. remote) →
- Loads hazard and exposure data →
- Entity layer constructs geographical/population/asset exposure grids →
- Core Engine runs Forecast → Impact → Cost-Benefit → Uncertainty
- Results passed back to User or to Utility Layer for saving/plotting.

c. Architectural Patterns / Design Principles
- Modular layering: clear separation between data sources, domain entities, engine computations, utilities.
- Plug-in pattern: new hazard or exposure modules can be added under `climada/hazard/` or `climada/entity/exposures/`.
- Test-first: each module contains its own `test/` folder.
- Configuration-driven: `.conf` file, `config.py` centralizes settings.

d. Key Technologies / Libraries
- Python 3.9+; NumPy, Pandas, xarray, HDF5 (h5py), SciPy, Matplotlib.
- Sphinx for documentation; GitHub Actions / Jenkins for CI; Conda/Mamba for packaging.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User Layer"
        direction TB
        UserNotebooks(["User Notebooks / Scripts"]):::user
        PackageInterface(["Package Interface\\nclimada/__init__.py"]):::interface
    end

    %% Data Ingestion Layer
    subgraph "Data Ingestion Layer" 
        direction TB
        LocalData(["Local Data\\nclimada/data/demo/, system/"]):::data
        RemoteAPI(["Remote Data API Client\\nutil/api_client.py"]):::data
    end

    %% Entity Layer
    subgraph "Entity Layer"
        direction TB
        EntityDef(["Entity Definitions\\nentity/entity_def.py"]):::core
        DiscRates(["Discount Rates\\nentity/disc_rates/base.py"]):::core
        Exposures(["Exposures\\nentity/exposures/base.py, litpop/"]):::core
        ImpactFuncs(["Impact Function Sets\\nentity/impact_funcs/"]):::core
        Measures(["Measures\\nentity/measures/measure_set.py"]):::core
        Tagging(["Tagging\\nentity/tag/tag.py"]):::core
    end

    %% Hazard Layer
    subgraph "Hazard Layer"
        direction TB
        HazardBase(["Base & I/O\\nhazard/base.py, io.py"]):::core
        Centroids(["Centroid Computations\\nhazard/centroids/centr.py"]):::core
        Tracks(["Tracks & Scenarios\\nhazard/tc_tracks*, storm_europe.py, trop_cyclone/"]):::core
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        direction TB
        Forecast(["Forecast\\nengine/forecast.py"]):::core
        Impact(["Impact\\nengine/impact.py, impact_calc.py"]):::core
        CostBenefit(["Cost-Benefit\\nengine/cost_benefit.py"]):::core
        Calibration(["Calibration / Uncertainty\\nengine/calibration_opt.py, unsequa/"]):::core
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        Config(["Config & Settings\\nutil/config.py, climada.conf"]):::util
        CalWrappers(["Calibration Wrappers\\nutil/calibrate/"]):::util
        IOHandlers(["I/O & File Handlers\\nutil/files_handler.py, hdf5_handler.py"]):::util
        Plotting(["Plotting & Visualization\\nutil/plot.py, scalebar_plot.py"]):::util
        MiscSupport(["Misc. Support\\nutil/{checker,dates_times,coordinates,finance,...}.py"]):::util
        SaveExport(["Save & Export Formats\\nutil/save.py, hdf5_handler.py"]):::util
    end

    %% Output / Visualization
    subgraph "Output / Visualization"
        direction TB
        Outputs(["Plots, CSV, Excel, NetCDF, HDF5"]):::external
    end

    %% External Services
    subgraph "External Services"
        direction TB
        DataAPI(["CLIMADA Data API"]):::external
        CondaForge(["Conda-Forge"]):::external
        ReadTheDocs(["ReadTheDocs"]):::external
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        direction TB
        GitHubActions(["GitHub Actions\\n.github/workflows/*.yml"]):::ci
        Jenkins(["Jenkins Scripts\\nscript/jenkins/"]):::ci
        PreCommit(["Pre-commit Hooks\\n.pre-commit-config.yaml"]):::ci
    end

    %% Data Flow
    UserNotebooks -->|calls| PackageInterface
    PackageInterface -->|chooses local| LocalData
    PackageInterface -->|calls API| RemoteAPI
    LocalData --> EntityDef
    RemoteAPI --> EntityDef
    EntityDef --> Forecast
    DiscRates --> Forecast
    Exposures --> Forecast
    ImpactFuncs --> Impact
    Forecast --> Impact
    Impact --> CostBenefit
    CostBenefit --> Calibration
    Calibration --> SaveExport
    SaveExport --> Outputs
    Outputs --> UserNotebooks

    %% Config and Utilities Control Flow
    PackageInterface -->|reads config| Config
    Forecast -->|uses| IOHandlers
    Impact -->|uses| IOHandlers
    Calibration -->|uses| CalWrappers
    SaveExport -->|uses| Plotting

    %% External Integrations
    RemoteAPI --> DataAPI
    PackageInterface --> CondaForge
    Documentation["doc/"]:::external --> ReadTheDocs

    %% CI/CD Flow
    PreCommit -.->|runs on push| GitHubActions
    GitHubActions -.->|runs tests| Forecast
    GitHubActions -.->|builds docs| Documentation
    GitHubActions -.->|publishes| CondaForge
    GitHubActions -.->|publishes| ReadTheDocs
    Jenkins -.->|runs pipelines| Forecast
    Jenkins -.->|runs pipelines| Impact

    %% Click Events
    click PackageInterface "https://github.com/climada-project/climada_python/blob/main/climada/__init__.py"
    click LocalData "https://github.com/climada-project/climada_python/tree/main/climada/data/demo/"
    click LocalData "https://github.com/climada-project/climada_python/tree/main/climada/data/system/"
    click RemoteAPI "https://github.com/climada-project/climada_python/blob/main/climada/util/api_client.py"
    click Forecast "https://github.com/climada-project/climada_python/blob/main/climada/engine/forecast.py"
    click Impact "https://github.com/climada-project/climada_python/blob/main/climada/engine/impact.py"
    click Impact "https://github.com/climada-project/climada_python/blob/main/climada/engine/impact_calc.py"
    click CostBenefit "https://github.com/climada-project/climada_python/blob/main/climada/engine/cost_benefit.py"
    click Calibration "https://github.com/climada-project/climada_python/blob/main/climada/engine/calibration_opt.py"
    click Calibration "https://github.com/climada-project/climada_python/tree/main/climada/engine/unsequa/"
    click EntityDef "https://github.com/climada-project/climada_python/blob/main/climada/entity/entity_def.py"
    click DiscRates "https://github.com/climada-project/climada_python/blob/main/climada/entity/disc_rates/base.py"
    click Exposures "https://github.com/climada-project/climada_python/blob/main/climada/entity/exposures/base.py"
    click Exposures "https://github.com/climada-project/climada_python/tree/main/climada/entity/exposures/litpop/"
    click ImpactFuncs "https://github.com/climada-project/climada_python/blob/main/climada/entity/impact_funcs/impact_func_set.py"
    click ImpactFuncs "https://github.com/climada-project/climada_python/blob/main/climada/entity/impact_funcs/trop_cyclone.py"
    click ImpactFuncs "https://github.com/climada-project/climada_python/blob/main/climada/entity/impact_funcs/storm_europe.py"
    click Measures "https://github.com/climada-project/climada_python/blob/main/climada/entity/measures/measure_set.py"
    click Tagging "https://github.com/climada-project/climada_python/blob/main/climada/entity/tag/tag.py"
    click HazardBase "https://github.com/climada-project/climada_python/blob/main/climada/hazard/base.py"
    click HazardBase "https://github.com/climada-project/climada_python/blob/main/climada/hazard/io.py"
    click Centroids "https://github.com/climada-project/climada_python/blob/main/climada/hazard/centroids/centr.py"
    click Tracks "https://github.com/climada-project/climada_python/blob/main/climada/hazard/tc_tracks.py"
    click Tracks "https://github.com/climada-project/climada_python/blob/main/climada/hazard/tc_tracks_synth.py"
    click Tracks "https://github.com/climada-project/climada_python/blob/main/climada/hazard/tc_clim_change.py"
    click Tracks "https://github.com/climada-project/climada_python/blob/main/climada/hazard/storm_europe.py"
    click Tracks "https://github.com/climada-project/climada_python/blob/main/climada/hazard/trop_cyclone/trop_cyclone.py"
    click Config "https://github.com/climada-project/climada_python/blob/main/climada/util/config.py"
    click CalWrappers "https://github.com/climada-project/climada_python/tree/main/climada/util/calibrate/"
    click IOHandlers "https://github.com/climada-project/climada_python/blob/main/climada/util/files_handler.py"
    click IOHandlers "https://github.com/climada-project/climada_python/blob/main/climada/util/hdf5_handler.py"
    click Plotting "https://github.com/climada-project/climada_python/blob/main/climada/util/plot.py"
    click Plotting "https://github.com/climada-project/climada_python/blob/main/climada/util/scalebar_plot.py"
    click SaveExport "https://github.com/climada-project/climada_python/blob/main/climada/util/save.py"
    click SaveExport "https://github.com/climada-project/climada_python/blob/main/climada/util/hdf5_handler.py"
    click GitHubActions "https://github.com/climada-project/climada_python/blob/main/.github/workflows/ci.yml"
    click GitHubActions "https://github.com/climada-project/climada_python/blob/main/.github/workflows/make-release.yml"
    click GitHubActions "https://github.com/climada-project/climada_python/blob/main/.github/workflows/pull-request.yml"
    click GitHubActions "https://github.com/climada-project/climada_python/blob/main/.github/workflows/python-publish.yml"
    click Jenkins "https://github.com/climada-project/climada_python/tree/main/script/jenkins/"
    click Documentation "https://github.com/climada-project/climada_python/tree/main/doc/"
    click PreCommit "https://github.com/climada-project/climada_python/blob/main/.pre-commit-config.yaml"

    %% Styles
    classDef user fill:#f9f,stroke:#333,stroke-width:1px;
    classDef interface fill:#bbf,stroke:#333,stroke-width:1px;
    classDef data fill:#afa,stroke:#333,stroke-width:1px;
    classDef core fill:#ffd,stroke:#333,stroke-width:1px;
    classDef util fill:#ddf,stroke:#333,stroke-width:1px;
    classDef external fill:#fdd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef ci fill:#efe,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2;
```
