Metadata-Version: 2.4
Name: watertrain
Version: 1.0.0
Summary: Automatic water-treatment-plant flowsheet generator: superstructure enumeration with pruning, analytical reliability and TAC ranking, plus equipment sizing.
Author: Anjan Tula
License: MIT
Keywords: water treatment,flowsheet,process synthesis,superstructure,reverse osmosis,desalination
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == "excel"

# watertrain — Automatic WTP Flowsheet Generator

Python port of the Excel/VBA tool `WTP_FlowsheetGenerator.xlsm`. Generates
every feasible water-treatment train for a given raw-water quality and
product spec, ranks them by a total-annualised-cost (TAC) screening index,
and sizes the equipment of any selected train.

**Method:** superstructure depth-first enumeration with pruning rules P1–P7,
backward flow / forward composition balance, analytical reliability
(log-normal approximation driven by the leak-CV column) and a TAC index.
The Python engine reproduces the VBA workbook results exactly (see
`tests/test_parity.py`).

## Install

```bash
pip install .            # core (no dependencies, pure Python >= 3.9)
pip install .[excel]     # + openpyxl, to read cases/DB from the workbook
```

## Quick start (Python API)

```python
from watertrain import WaterCase, generate, rank, design

case = WaterCase.create(
    feed=dict(turbidity=10, tss=15, oil_grease=1, fe=0.3, mn=0.1,
              cod=40, toc=10, tds=5384, sio2=30, hardness=193),
    target=dict(turbidity=1, tss=1, oil_grease=0.1, fe=0.1, mn=0.05,
                cod=10, toc=2, tds=100, sio2=5, hardness=20),
    product_flow=19.3,                     # m3/h
    source="Treated Wastewater/Sewage",
    max_train_len=9, max_flowsheets=200)

flowsheets = generate(case)      # 1. all feasible trains
best = rank(flowsheets, top_x=5) # 2. cheapest first (TAC)
d = design(best[0], case)        # 3. size the chosen train
print(d.report())                # equipment schedule + PFD + stream table
```

The workflow mirrors the workbook macros:
`GenerateFlowsheets → RankFlowsheets → DesignSelected`.

Built-in example cases (same 7 as the workbook):

```python
from watertrain import get_example
case = get_example(6)            # "6. PFD-1 reject reclaim"
```

## Command line

```bash
watertrain --list-examples
watertrain --example 6 --top 5 --design 1
watertrain --case mycase.json --top 10
```

`mycase.json`:

```json
{
  "feed":   {"turbidity": 10, "tss": 15, "tds": 5384, "hardness": 193},
  "target": {"turbidity": 1,  "tss": 1,  "tds": 100,  "hardness": 20},
  "product_flow": 19.3,
  "max_train_len": 9
}
```

Parameters omitted from `feed` default to 0 (not present).

## Custom technology database

The default database (`watertrain.DEFAULT_TECHNOLOGIES`) is the
`2.ProcessGroups` sheet. Pass your own list to `generate()`:

```python
from watertrain import Technology, generate

my_tech = Technology.create(
    "MyMBR", stage=2, recovery=0.95, leak_cv=0.25, capex=2.0, opex=0.9,
    removal=dict(turbidity=0.99, tss=0.999, cod=0.6, toc=0.5),
    inlet_max=dict(turbidity=200))

techs = list(__import__("watertrain").DEFAULT_TECHNOLOGIES) + [my_tech]
flowsheets = generate(case, technologies=techs)
```

Or keep editing the database in Excel and load it live
(requires `pip install .[excel]`):

```python
from watertrain.excel import load_case, load_technologies
case  = load_case("WTP_FlowsheetGenerator.xlsm")
techs = load_technologies("WTP_FlowsheetGenerator.xlsm")
```

## Water-quality parameters (fixed order)

`turbidity, tss, oil_grease, fe, mn, cod, toc, tds, sio2, hardness`

## Notes

* Reliability is P(product meets spec) under performance uncertainty.
* TAC is a screening cost index for ranking, not a bid price.
* Run the parity tests with `pytest`.

## Package layout

```
src/watertrain/
  model.py      dataclasses: Technology, WaterCase, Flowsheet; constants
  database.py   default technology database (2.ProcessGroups)
  examples.py   the 7 example cases
  engine.py     generate() + rank(): DFS, pruning P1–P7, reliability, TAC
  design.py     design(): flow balance, equipment sizing, streams, text PFD
  sfiles.py     SFILES string helpers
  excel.py      optional openpyxl bridge to the original workbook
  cli.py        `watertrain` command
tests/test_parity.py   reproduces the workbook numbers exactly
```
