# kwr-water/pysimdeum architecture

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

- Interactive diagram: https://gitdiagram.com/kwr-water/pysimdeum
- Repository: https://github.com/kwr-water/pysimdeum

## Overview

PYSIMDEUM models residential water use and linked wastewater discharge. The main workflow builds a statistically populated house, simulates user/end-use events into labelled time-series results, then supports aggregation, plotting, and serialization. Population-level spatial aggregation is a separate capability. Some connections—especially in unsampled tools and population code—are shown only where the source index or README supports them; no external service wiring is inferred.

Main entry points: [`pysimdeum/core/house.py`](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/house.py) (House model), [`pysimdeum/core/statistics.py`](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/statistics.py) (Regional statistics), [`pysimdeum/api.py`](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/api.py) (Public API), [`pysimdeum/tools/helper.py`](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/tools/helper.py) (Usage summaries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Household model"]
  node_api["Public API<br/>[api.py]"]
  node_statistics["Regional statistics<br/>[statistics.py]"]
  node_regional_data["Regional TOML data"]
  node_house["House model<br/>[house.py]"]
  node_user["User presence<br/>[user.py]"]
end

subgraph group_simulation["Simulation engine"]
  node_enduse["End-use devices<br/>[end_use.py]"]
  node_patterns["Pattern shaping<br/>[patterns.py]"]
  node_probability["Probability sampling<br/>[probability.py]"]
  node_time_series[("Simulation arrays<br/>[house.py]")]
end

subgraph group_population["Population workflows"]
  node_population["Spatial population<br/>[population.py]"]
  node_misc["Population utilities<br/>[misc.py]"]
  node_ww_quality["Wastewater quality"]
end

subgraph group_outputs["Analysis and outputs"]
  node_helper["Usage summaries<br/>[helper.py]"]
  node_plot["Plotting<br/>[plot.py]"]
  node_write["Serialization<br/>[write.py]"]
  node_infoworks["InfoWorks tools<br/>[infoworks.py]"]
end

node_engineer(("Python user"))

node_engineer -->|"builds house"| node_api
node_api -->|"loads statistics"| node_statistics
node_api -->|"builds and simulates"| node_house
node_statistics -->|"loads regional config"| node_regional_data
node_statistics -->|"builds patterns"| node_patterns
node_house -->|"uses statistics"| node_statistics
node_house -->|"creates users"| node_user
node_house -->|"creates devices"| node_enduse
node_house -->|"produces arrays"| node_time_series
node_enduse -->|"samples events"| node_probability
node_enduse -->|"uses event patterns"| node_patterns
node_user -->|"uses diurnal data"| node_statistics
node_population -->|"simulates households"| node_api
node_population -->|"uses utilities"| node_misc
node_population -->|"computes wastewater"| node_ww_quality
node_ww_quality -->|"samples concentrations"| node_probability
node_ww_quality -->|"loads nutrient data"| node_regional_data
node_helper -->|"summarizes usage"| node_house
node_helper -->|"builds patterns"| node_statistics
node_plot -->|"uses summaries"| node_helper
node_plot -->|"plots results"| node_house
node_write -->|"uses summaries"| node_helper
node_write -->|"serializes results"| node_house

click node_api "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/api.py"
click node_statistics "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/statistics.py"
click node_regional_data "https://github.com/kwr-water/pysimdeum/tree/master/pysimdeum/data"
click node_house "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/house.py"
click node_user "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/user.py"
click node_enduse "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/end_use.py"
click node_patterns "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/utils/patterns.py"
click node_probability "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/utils/probability.py"
click node_time_series "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/house.py"
click node_population "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/population.py"
click node_misc "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/utils/misc.py"
click node_ww_quality "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/utils/wastewater_quality.py"
click node_helper "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/tools/helper.py"
click node_plot "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/tools/plot.py"
click node_write "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/tools/write.py"
click node_infoworks "https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/tools/infoworks.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_api,node_statistics,node_regional_data,node_house,node_user,node_engineer toneBlue
class node_enduse,node_patterns,node_probability,node_time_series toneAmber
class node_population,node_misc,node_ww_quality toneMint
class node_helper,node_plot,node_write,node_infoworks toneRose
```

## Components

### Household model

- [Public API](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/api.py): `pysimdeum/api.py`
- [Regional statistics](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/statistics.py): `pysimdeum/core/statistics.py`
- [Regional TOML data](https://github.com/kwr-water/pysimdeum/tree/master/pysimdeum/data): `pysimdeum/data`
- [House model](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/house.py): `pysimdeum/core/house.py`
- [User presence](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/user.py): `pysimdeum/core/user.py`

### Simulation engine

- [End-use devices](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/end_use.py): `pysimdeum/core/end_use.py`
- [Pattern shaping](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/utils/patterns.py): `pysimdeum/utils/patterns.py`
- [Probability sampling](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/utils/probability.py): `pysimdeum/utils/probability.py`
- [Simulation arrays](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/house.py): `pysimdeum/core/house.py`

### Population workflows

- [Spatial population](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/core/population.py): `pysimdeum/core/population.py`
- [Population utilities](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/utils/misc.py): `pysimdeum/utils/misc.py`
- [Wastewater quality](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/utils/wastewater_quality.py): `pysimdeum/utils/wastewater_quality.py`

### Analysis and outputs

- [Usage summaries](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/tools/helper.py): `pysimdeum/tools/helper.py`
- [Plotting](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/tools/plot.py): `pysimdeum/tools/plot.py`
- [Serialization](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/tools/write.py): `pysimdeum/tools/write.py`
- [InfoWorks tools](https://github.com/kwr-water/pysimdeum/blob/master/pysimdeum/tools/infoworks.py): `pysimdeum/tools/infoworks.py`

### Other components

- **Python user**

## Connections

- Python user → Public API: builds house (evidence: `README.md`)
- Public API → Regional statistics: loads statistics (evidence: `pysimdeum/api.py`)
- Public API → House model: builds and simulates (evidence: `pysimdeum/api.py`)
- Regional statistics → Regional TOML data: loads regional config (evidence: `pysimdeum/core/statistics.py`)
- Regional statistics → Pattern shaping: builds patterns (evidence: `pysimdeum/core/statistics.py`)
- House model → Regional statistics: uses statistics (evidence: `pysimdeum/core/house.py`)
- House model → User presence: creates users (evidence: `pysimdeum/core/house.py`)
- House model → End-use devices: creates devices (evidence: `pysimdeum/core/house.py`)
- House model → Simulation arrays: produces arrays (evidence: `README.md`)
- End-use devices → Probability sampling: samples events (evidence: `pysimdeum/core/end_use.py`)
- End-use devices → Pattern shaping: uses event patterns (evidence: `pysimdeum/core/end_use.py`)
- User presence → Regional statistics: uses diurnal data (evidence: `pysimdeum/core/user.py`)
- Spatial population → Public API: simulates households (evidence: `pysimdeum/core/population.py`)
- Spatial population → Population utilities: uses utilities (evidence: `pysimdeum/core/population.py`)
- Spatial population → Wastewater quality: computes wastewater (evidence: `pysimdeum/core/population.py`)
- Wastewater quality → Probability sampling: samples concentrations (evidence: `pysimdeum/utils/wastewater_quality.py`)
- Wastewater quality → Regional TOML data: loads nutrient data (evidence: `pysimdeum/utils/wastewater_quality.py`)
- Usage summaries → House model: summarizes usage (evidence: `pysimdeum/tools/helper.py`)
- Usage summaries → Regional statistics: builds patterns (evidence: `pysimdeum/tools/helper.py`)
- Plotting → Usage summaries: uses summaries (evidence: `pysimdeum/tools/plot.py`)
- Plotting → House model: plots results (evidence: `pysimdeum/tools/plot.py`)
- Serialization → Usage summaries: uses summaries (evidence: `pysimdeum/tools/write.py`)
- Serialization → House model: serializes results (evidence: `pysimdeum/tools/write.py`)
