# usepa/water_treatment_models architecture

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

- Interactive diagram: https://gitdiagram.com/usepa/water_treatment_models
- Repository: https://github.com/usepa/water_treatment_models

## Overview

This repository is a suite of water-treatment contaminant-removal models: granular activated carbon (GAC), ion exchange (IX), and powdered activated carbon (PAC), with Shiny interfaces for the three technologies. The principal workflow is to provide treatment and contaminant inputs, run a model, and inspect predicted effluent performance. The graph also preserves batch IX, GAC/IX lead-lag modeling, and model-fitting/tooling capabilities. Source excerpts establish several model dependencies; README statements establish the product and GUI capabilities. Unsampled GUI wiring and some subsystem relationships are not inferred.

Main entry points: [`IonExchangeModel/ixpy/hsdmix.py`](https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/hsdmix.py) (IX column HSDM), [`PSDM/psdm/PSDM_functions.py`](https://github.com/usepa/water_treatment_models/blob/master/PSDM/psdm/PSDM_functions.py) (PSDM functions), [`IonExchangeModel/ixpy/colloc.py`](https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/colloc.py) (Collocation operators), [`IonExchangeModel/ixpy/psdmix.py`](https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/psdmix.py) (IX column PSDM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gac["GAC Modeling"]
  node_gac_model["GAC PSDM<br/>[PSDM.py]"]
  node_gac_tools["PSDM tools<br/>[PSDM_tools.py]"]
  node_gac_extra["PSDM extensions<br/>[PSDM_extra.py]"]
  node_ecm["ECM model<br/>[ecm.py]"]
end

subgraph group_ix["Ion Exchange"]
  node_ix_column_hsdm["IX column HSDM<br/>[hsdmix.py]"]
  node_ix_column_psdm["IX column PSDM<br/>[psdmix.py]"]
  node_ix_batch_hsdm["IX batch HSDM<br/>[hsdmixbatch.py]"]
  node_ix_batch_psdm["IX batch PSDM<br/>[psdmixbatch.py]"]
  node_ix_runner["IX runner<br/>[runner.py]"]
  node_ix_kl["K-L estimation<br/>[KL_guess.py]"]
end

subgraph group_pac["PAC Modeling"]
  node_pac_model["PAC CFPSDM<br/>[PAC.py]"]
end

subgraph group_interfaces["User Interfaces"]
  node_gac_helper["GAC interface helper"]
  node_gac_ui["GAC Shiny app<br/>[GACapp.R]"]
  node_ix_ui["IX Shiny app"]
  node_pac_ui["PAC Shiny app<br/>[PACapp.R]"]
end

subgraph group_shared["Shared Modeling"]
  node_gac_functions["PSDM functions<br/>[PSDM_functions.py]"]
  node_leadlag["Lead-lag model<br/>[lead_lag_class.py]"]
  node_ix_collocation["Collocation operators<br/>[colloc.py]"]
  node_ix_parameters["IX parameter conversion<br/>[paramsheets.py]"]
  node_ix_converter["IX result conversion<br/>[converter.py]"]
end

node_user(("Treatment analyst"))

node_user -->|"uses interface"| node_gac_ui
node_user -->|"uses interface"| node_ix_ui
node_user -->|"uses interface"| node_pac_ui
node_gac_helper -->|"runs model"| node_gac_model
node_gac_model -->|"uses functions"| node_gac_functions
node_gac_tools -->|"uses model"| node_gac_model
node_gac_tools -->|"uses functions"| node_gac_functions
node_ix_runner -->|"runs model"| node_ix_column_hsdm
node_ix_runner -->|"runs model"| node_ix_column_psdm
node_ix_column_psdm -->|"extends"| node_ix_column_hsdm
node_ix_column_hsdm -->|"builds operators"| node_ix_collocation
node_ix_column_hsdm -->|"converts parameters"| node_ix_parameters
node_ix_column_hsdm -->|"converts results"| node_ix_converter
node_ix_column_psdm -->|"builds operators"| node_ix_collocation
node_ix_batch_hsdm -->|"builds operators"| node_ix_collocation
node_ix_batch_hsdm -->|"converts parameters"| node_ix_parameters
node_ix_batch_psdm -->|"builds operators"| node_ix_collocation
node_ix_batch_psdm -->|"converts parameters"| node_ix_parameters
node_pac_model -->|"uses functions"| node_gac_functions
node_leadlag -->|"uses functions"| node_gac_functions

click node_gac_model "https://github.com/usepa/water_treatment_models/blob/master/PSDM/psdm/PSDM.py"
click node_gac_functions "https://github.com/usepa/water_treatment_models/blob/master/PSDM/psdm/PSDM_functions.py"
click node_gac_tools "https://github.com/usepa/water_treatment_models/blob/master/PSDM/psdm/PSDM_tools.py"
click node_gac_extra "https://github.com/usepa/water_treatment_models/blob/master/PSDM/psdm/PSDM_extra.py"
click node_ecm "https://github.com/usepa/water_treatment_models/blob/master/PSDM/psdm/ecm.py"
click node_leadlag "https://github.com/usepa/water_treatment_models/blob/master/PSDM/psdm/lead_lag_class.py"
click node_ix_column_hsdm "https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/hsdmix.py"
click node_ix_column_psdm "https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/psdmix.py"
click node_ix_batch_hsdm "https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/hsdmixbatch.py"
click node_ix_batch_psdm "https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/psdmixbatch.py"
click node_ix_runner "https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/runner.py"
click node_ix_collocation "https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/colloc.py"
click node_ix_parameters "https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/paramsheets.py"
click node_ix_converter "https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/converter.py"
click node_ix_kl "https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/KL_guess.py"
click node_pac_model "https://github.com/usepa/water_treatment_models/blob/master/Shiny-PAC/PAC.py"
click node_gac_helper "https://github.com/usepa/water_treatment_models/blob/master/Shiny-GAC/GAC_Shiny_helper.py"
click node_gac_ui "https://github.com/usepa/water_treatment_models/blob/master/Shiny-GAC/GACapp.R"
click node_ix_ui "https://github.com/usepa/water_treatment_models/blob/master/Shiny-IEX/Ion_Exchange_Model.R"
click node_pac_ui "https://github.com/usepa/water_treatment_models/blob/master/Shiny-PAC/PACapp.R"

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_gac_model,node_gac_tools,node_gac_extra,node_ecm toneBlue
class node_ix_column_hsdm,node_ix_column_psdm,node_ix_batch_hsdm,node_ix_batch_psdm,node_ix_runner,node_ix_kl toneAmber
class node_pac_model toneMint
class node_gac_helper,node_gac_ui,node_ix_ui,node_pac_ui toneRose
class node_gac_functions,node_leadlag,node_ix_collocation,node_ix_parameters,node_ix_converter,node_user toneIndigo
```

## Components

### GAC Modeling

- [GAC PSDM](https://github.com/usepa/water_treatment_models/blob/master/PSDM/psdm/PSDM.py): `PSDM/psdm/PSDM.py`
- [PSDM tools](https://github.com/usepa/water_treatment_models/blob/master/PSDM/psdm/PSDM_tools.py): `PSDM/psdm/PSDM_tools.py`
- [PSDM extensions](https://github.com/usepa/water_treatment_models/blob/master/PSDM/psdm/PSDM_extra.py): `PSDM/psdm/PSDM_extra.py`
- [ECM model](https://github.com/usepa/water_treatment_models/blob/master/PSDM/psdm/ecm.py): `PSDM/psdm/ecm.py`

### Ion Exchange

- [IX column HSDM](https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/hsdmix.py): `IonExchangeModel/ixpy/hsdmix.py`
- [IX column PSDM](https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/psdmix.py): `IonExchangeModel/ixpy/psdmix.py`
- [IX batch HSDM](https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/hsdmixbatch.py): `IonExchangeModel/ixpy/hsdmixbatch.py`
- [IX batch PSDM](https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/psdmixbatch.py): `IonExchangeModel/ixpy/psdmixbatch.py`
- [IX runner](https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/runner.py): `IonExchangeModel/ixpy/runner.py`
- [K-L estimation](https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/KL_guess.py): `IonExchangeModel/ixpy/KL_guess.py`

### PAC Modeling

- [PAC CFPSDM](https://github.com/usepa/water_treatment_models/blob/master/Shiny-PAC/PAC.py): `Shiny-PAC/PAC.py`

### User Interfaces

- [GAC interface helper](https://github.com/usepa/water_treatment_models/blob/master/Shiny-GAC/GAC_Shiny_helper.py): `Shiny-GAC/GAC_Shiny_helper.py`
- [GAC Shiny app](https://github.com/usepa/water_treatment_models/blob/master/Shiny-GAC/GACapp.R): `Shiny-GAC/GACapp.R`
- [IX Shiny app](https://github.com/usepa/water_treatment_models/blob/master/Shiny-IEX/Ion_Exchange_Model.R): `Shiny-IEX/Ion_Exchange_Model.R`
- [PAC Shiny app](https://github.com/usepa/water_treatment_models/blob/master/Shiny-PAC/PACapp.R): `Shiny-PAC/PACapp.R`

### Shared Modeling

- [PSDM functions](https://github.com/usepa/water_treatment_models/blob/master/PSDM/psdm/PSDM_functions.py): `PSDM/psdm/PSDM_functions.py`
- [Lead-lag model](https://github.com/usepa/water_treatment_models/blob/master/PSDM/psdm/lead_lag_class.py): `PSDM/psdm/lead_lag_class.py`
- [Collocation operators](https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/colloc.py): `IonExchangeModel/ixpy/colloc.py`
- [IX parameter conversion](https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/paramsheets.py): `IonExchangeModel/ixpy/paramsheets.py`
- [IX result conversion](https://github.com/usepa/water_treatment_models/blob/master/IonExchangeModel/ixpy/converter.py): `IonExchangeModel/ixpy/converter.py`

### Other components

- **Treatment analyst**

## Connections

- Treatment analyst → GAC Shiny app: uses interface (evidence: `Readme.md`)
- Treatment analyst → IX Shiny app: uses interface (evidence: `Readme.md`)
- Treatment analyst → PAC Shiny app: uses interface (evidence: `Readme.md`)
- GAC interface helper → GAC PSDM: runs model (evidence: `Shiny-GAC/GAC_Shiny_helper.py`)
- GAC PSDM → PSDM functions: uses functions (evidence: `PSDM/psdm/PSDM.py`)
- PSDM tools → GAC PSDM: uses model (evidence: `PSDM/psdm/PSDM_tools.py`)
- PSDM tools → PSDM functions: uses functions (evidence: `PSDM/psdm/PSDM_tools.py`)
- IX runner → IX column HSDM: runs model (evidence: `IonExchangeModel/ixpy/runner.py`)
- IX runner → IX column PSDM: runs model (evidence: `IonExchangeModel/ixpy/runner.py`)
- IX column PSDM → IX column HSDM: extends (evidence: `IonExchangeModel/ixpy/psdmix.py`)
- IX column HSDM → Collocation operators: builds operators (evidence: `IonExchangeModel/ixpy/hsdmix.py`)
- IX column HSDM → IX parameter conversion: converts parameters (evidence: `IonExchangeModel/ixpy/hsdmix.py`)
- IX column HSDM → IX result conversion: converts results (evidence: `IonExchangeModel/ixpy/hsdmix.py`)
- IX column PSDM → Collocation operators: builds operators (evidence: `IonExchangeModel/ixpy/psdmix.py`)
- IX batch HSDM → Collocation operators: builds operators (evidence: `IonExchangeModel/ixpy/hsdmixbatch.py`)
- IX batch HSDM → IX parameter conversion: converts parameters (evidence: `IonExchangeModel/ixpy/hsdmixbatch.py`)
- IX batch PSDM → Collocation operators: builds operators (evidence: `IonExchangeModel/ixpy/psdmixbatch.py`)
- IX batch PSDM → IX parameter conversion: converts parameters (evidence: `IonExchangeModel/ixpy/psdmixbatch.py`)
- PAC CFPSDM → PSDM functions: uses functions (evidence: `Shiny-PAC/PAC.py`)
- Lead-lag model → PSDM functions: uses functions (evidence: `PSDM/psdm/lead_lag_class.py`)
