watertrain 1.0.0__tar.gz

watertrain-1.0.0/PKG-INFO

@@ -0,0 +1,136 @@
+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
+```

watertrain-1.0.0/README.md

@@ -0,0 +1,121 @@
+# 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
+```

watertrain-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "watertrain"
+version = "1.0.0"
+description = "Automatic water-treatment-plant flowsheet generator: superstructure enumeration with pruning, analytical reliability and TAC ranking, plus equipment sizing."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Anjan Tula" }]
+keywords = ["water treatment", "flowsheet", "process synthesis",
+            "superstructure", "reverse osmosis", "desalination"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Chemistry",
+]
+dependencies = []          # pure standard library
+
+[project.optional-dependencies]
+excel = ["openpyxl>=3.1"]  # read cases / tech DB from the original workbook
+
+[project.scripts]
+watertrain = "watertrain.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

watertrain-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

watertrain-1.0.0/src/watertrain/__init__.py

@@ -0,0 +1,42 @@
+"""watertrain — Automatic Water-Treatment-Plant Flowsheet Generator.
+
+Python port of the validated Excel/VBA tool (WTP_FlowsheetGenerator.xlsm).
+
+Typical use::
+
+    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, source="Treated Wastewater/Sewage",
+        max_train_len=9, max_flowsheets=10)
+
+    flowsheets = generate(case)          # every feasible train
+    best = rank(flowsheets, top_x=5)     # cheapest first (TAC)
+    print(design(best[0], case).report())
+
+Workflow: generate -> rank -> design (same as the workbook macros
+GenerateFlowsheets -> RankFlowsheets -> DesignSelected).
+"""
+from .model import (NO_LIMIT, NP, PARAMS, Flowsheet, Technology, WaterCase)
+from .database import DEFAULT_TECHNOLOGIES, TECH_BY_NAME
+from .engine import generate, rank
+from .design import Design, Equipment, Stream, design
+from .examples import EXAMPLES, get_example
+from .sfiles import sfiles_string, sfiles_tag
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "PARAMS", "NP", "NO_LIMIT",
+    "Technology", "WaterCase", "Flowsheet",
+    "DEFAULT_TECHNOLOGIES", "TECH_BY_NAME",
+    "generate", "rank", "design",
+    "Design", "Equipment", "Stream",
+    "EXAMPLES", "get_example",
+    "sfiles_string", "sfiles_tag",
+    "__version__",
+]

watertrain-1.0.0/src/watertrain/cli.py

@@ -0,0 +1,107 @@
+"""Command-line interface.
+
+Examples::
+
+    watertrain --list-examples
+    watertrain --example 6 --top 5
+    watertrain --example 6 --top 5 --design 1
+    watertrain --case mycase.json --top 10 --design 2
+
+mycase.json format::
+
+    {
+      "feed":   {"turbidity": 10, "tss": 15, "tds": 5384, "...": 0},
+      "target": {"turbidity": 1,  "tss": 1,  "tds": 100,  "...": 0},
+      "product_flow": 19.3,
+      "source": "Treated Wastewater/Sewage",
+      "max_train_len": 9,
+      "max_flowsheets": 200
+    }
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .design import design as design_fs
+from .engine import generate, rank
+from .examples import EXAMPLES, get_example
+from .model import WaterCase
+
+
+def _load_case_json(path: str) -> WaterCase:
+    with open(path, "r", encoding="utf-8") as fh:
+        d = json.load(fh)
+    return WaterCase.create(
+        feed=d["feed"], target=d["target"],
+        product_flow=d["product_flow"], source=d.get("source", ""),
+        max_train_len=d.get("max_train_len", 7),
+        max_flowsheets=d.get("max_flowsheets", 200),
+        name=d.get("name", path))
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="watertrain",
+        description="Automatic WTP flowsheet generator "
+                    "(generate -> rank -> design).")
+    ap.add_argument("--version", action="version", version=__version__)
+    ap.add_argument("--list-examples", action="store_true",
+                    help="list the built-in example cases and exit")
+    src = ap.add_mutually_exclusive_group()
+    src.add_argument("--example", metavar="N",
+                     help="use built-in example (1-7 or full name)")
+    src.add_argument("--case", metavar="FILE.json",
+                     help="load a case from a JSON file")
+    ap.add_argument("--top", type=int, default=10, metavar="X",
+                    help="rank: keep the X cheapest trains (default 10)")
+    ap.add_argument("--design", type=int, metavar="RANK",
+                    help="print the full design of the given rank (1 = best)")
+    ap.add_argument("--max-flowsheets", type=int, metavar="M",
+                    help="override the enumeration cap")
+    args = ap.parse_args(argv)
+
+    if args.list_examples:
+        for name in EXAMPLES:
+            print(name)
+        return 0
+
+    if args.example:
+        case = get_example(args.example)
+    elif args.case:
+        case = _load_case_json(args.case)
+    else:
+        ap.error("choose --example N or --case FILE.json "
+                 "(or --list-examples)")
+
+    if args.max_flowsheets:
+        case = WaterCase.create(
+            feed=case.feed_dict(), target=case.target_dict(),
+            product_flow=case.product_flow, source=case.source,
+            max_train_len=case.max_train_len,
+            max_flowsheets=args.max_flowsheets, name=case.name)
+
+    fss = generate(case)
+    print(f"Case: {case.name or '(custom)'}  |  "
+          f"generated {len(fss)} feasible flowsheet(s)")
+    top = rank(fss, top_x=args.top)
+    print(f"\nTop {len(top)} by TAC:")
+    print(f"{'#':>3} {'TAC':>8} {'Rec%':>6} {'Rel%':>6} {'Intake':>8}  SFILES")
+    for r, fs in enumerate(top, 1):
+        print(f"{r:>3} {fs.tac:8.3f} {fs.recovery_pct:6.1f} "
+              f"{fs.reliability_pct:6.1f} {fs.intake:8.2f}  {fs.sfiles}")
+
+    if args.design:
+        if not (1 <= args.design <= len(top)):
+            print(f"\n--design {args.design} is out of range (1..{len(top)})",
+                  file=sys.stderr)
+            return 2
+        print("\n" + "=" * 70)
+        print(design_fs(top[args.design - 1], case).report())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

watertrain-1.0.0/src/watertrain/database.py

@@ -0,0 +1,75 @@
+"""Default technology database.
+
+Ported 1:1 from sheet '2.ProcessGroups' of WTP_FlowsheetGenerator.xlsm.
+rem_* = removal fraction (0-1); in_* = max inlet the unit tolerates
+(absent = no limit). Stage: 1 pre-treatment, 2 filtration, 3 RO, 4 polish.
+
+Users can pass their own list of Technology objects to generate(); this
+module is only the built-in default.
+"""
+from .model import Technology
+
+T = Technology.create
+
+DEFAULT_TECHNOLOGIES = [
+    T("Clarifier", 1, 0.991, 0.35, 1.6, 0.5,
+      removal=dict(turbidity=0.98, tss=0.97, oil_grease=0.9, fe=0.8, mn=0.6,
+                   cod=0.4, toc=0.35, tds=0.0, sio2=0.1, hardness=0.0)),
+    T("DAF", 1, 0.99, 0.35, 1.7, 0.8,
+      removal=dict(turbidity=0.9, tss=0.92, oil_grease=0.95,
+                   cod=0.35, toc=0.25)),
+    T("HRSCC", 1, 0.985, 0.35, 2.2, 1.0,
+      removal=dict(turbidity=0.985, tss=0.98, fe=0.85, mn=0.7,
+                   cod=0.45, toc=0.4, sio2=0.3, hardness=0.6)),
+    T("ABF", 2, 0.992, 0.30, 0.8, 0.2,
+      removal=dict(turbidity=0.6, tss=0.7, fe=0.4, mn=0.3),
+      inlet_max=dict(turbidity=50, tss=50)),
+    T("MMF", 2, 0.97, 0.30, 1.0, 0.3,
+      removal=dict(turbidity=0.8, tss=0.85, oil_grease=0.3, fe=0.5, mn=0.4,
+                   cod=0.05, toc=0.05),
+      inlet_max=dict(turbidity=50, tss=50)),
+    T("GSF", 2, 0.973, 0.30, 1.1, 0.35,
+      removal=dict(turbidity=0.9, tss=0.92, oil_grease=0.3, fe=0.85, mn=0.8,
+                   cod=0.05, toc=0.05),
+      inlet_max=dict(turbidity=50, tss=50)),
+    T("ACF", 2, 0.93, 0.35, 1.2, 0.6,
+      removal=dict(turbidity=0.4, tss=0.5, oil_grease=0.85,
+                   cod=0.55, toc=0.65),
+      inlet_max=dict(turbidity=10, tss=10)),
+    T("SF", 2, 0.97, 0.30, 0.9, 0.25,
+      removal=dict(turbidity=0.8, tss=0.85),
+      inlet_max=dict(turbidity=20, tss=20)),
+    T("WAC", 2, 0.975, 0.20, 1.3, 0.9,
+      removal=dict(tds=0.05, hardness=0.98),
+      inlet_max=dict(turbidity=5, tss=5)),
+    T("UF", 2, 0.90, 0.20, 1.8, 0.7,
+      removal=dict(turbidity=0.995, tss=0.999, oil_grease=0.7, fe=0.6, mn=0.3,
+                   cod=0.25, toc=0.2),
+      inlet_max=dict(turbidity=100, tss=100, oil_grease=5)),
+    T("RO Pass1", 3, 0.75, 0.35, 3.0, 2.0,
+      removal=dict(turbidity=0.95, tss=0.99, oil_grease=0.9, fe=0.98, mn=0.98,
+                   cod=0.9, toc=0.95, tds=0.92, sio2=0.9, hardness=0.94),
+      inlet_max=dict(turbidity=1, tss=1, oil_grease=0.1, fe=0.3, mn=0.1,
+                     tds=10000)),
+    T("SWRO", 3, 0.45, 0.30, 5.0, 4.5,
+      removal=dict(turbidity=0.95, tss=0.99, oil_grease=0.9, fe=0.98, mn=0.98,
+                   cod=0.9, toc=0.95, tds=0.991, sio2=0.99, hardness=0.995),
+      inlet_max=dict(turbidity=1, tss=1, oil_grease=0.1, tds=50000)),
+    T("RO Pass2", 3, 0.85, 0.30, 2.2, 1.2,
+      removal=dict(cod=0.85, toc=0.9, tds=0.95, sio2=0.95, hardness=0.97),
+      inlet_max=dict(turbidity=0.5, tss=0.5, tds=2000)),
+    T("EDI", 4, 0.90, 0.25, 2.5, 1.5,
+      removal=dict(toc=0.5, tds=0.99, sio2=0.95, hardness=0.999),
+      inlet_max=dict(turbidity=0.2, fe=0.01, mn=0.01, toc=0.5,
+                     tds=50, sio2=1, hardness=1)),
+    T("NRMB", 4, 1.0, 0.25, 1.4, 2.5,
+      removal=dict(tds=0.99, sio2=0.98, hardness=0.999),
+      inlet_max=dict(turbidity=0.2, tds=20)),
+    T("GUARD", 4, 1.0, 0.05, 0.3, 0.2,
+      removal=dict(turbidity=0.95, tss=0.95, fe=0.3)),
+    T("UV", 4, 1.0, 0.40, 0.6, 0.4,
+      removal=dict(cod=0.1, toc=0.3),
+      inlet_max=dict(turbidity=5)),
+]
+
+TECH_BY_NAME = {t.name: t for t in DEFAULT_TECHNOLOGIES}