watertrain 1.0.0__py3-none-any.whl

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/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/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}

watertrain/design.py

@@ -0,0 +1,218 @@
+"""Detailed design of a selected flowsheet.
+
+Port of DesignSelected / SizeUnit / MotorKW / stream summary in
+modWTP.bas: backward flow balance, per-unit equipment sizing, forward
+composition profile and a full stream table (product path + rejects).
+Instead of Excel shapes, the PFD is rendered as text (Design.pfd_text()).
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Dict, List, Sequence, Tuple
+
+from .model import NP, PARAMS, Flowsheet, WaterCase
+from .engine import round_up_01
+
+_IEC_MOTORS = (0.37, 0.55, 0.75, 1.1, 1.5, 2.2, 3.0, 4.0, 5.5, 7.5, 11.0,
+               15.0, 18.5, 22.0, 30.0, 37.0, 45.0, 55.0, 75.0, 90.0, 110.0,
+               132.0, 160.0, 200.0, 250.0)
+
+
+def motor_kw(hydraulic_kw: float) -> float:
+    """Next IEC motor size above hydraulic power / 0.72 * 1.1 margin."""
+    p = hydraulic_kw / 0.72 * 1.1
+    for x in _IEC_MOTORS:
+        if x >= p:
+            return x
+    return 250.0
+
+
+def _size_unit(name: str, qf: float, qp: float) -> Tuple[str, str, float]:
+    """Return (type, key size, pump motor kW or 0)."""
+    typ, sz, mkw = "-", "", 0.0
+    if name in ("Clarifier", "DAF", "HRSCC"):
+        typ = "clarifier / flotation"
+        sz = f"area {round(qf / 1.0, 1)} m2 (2x50%)"
+        mkw = motor_kw(qf * 2.0 / 36.0)
+    elif name in ("ABF", "MMF", "GSF", "ACF", "SF"):
+        typ = "pressure filter (N+1)"
+        sz = f"area {round(qf / 15.0, 1)} m2"
+        mkw = motor_kw((qf / 2.0) * 2.0 / 36.0)
+    elif name == "WAC":
+        typ = "WAC softener (ion exchange)"
+        sz = f"resin {round(qf * 24.0 * 20.0 / 2.0)} L"
+        mkw = motor_kw((qf / 2.0) * 2.5 / 36.0)
+    elif name == "UF":
+        typ = "ultrafiltration (75 m2 modules)"
+        sz = f"{math.ceil(qp * 1000.0 / (50.0 * 75.0))} modules"
+        mkw = motor_kw((qf / 2.0) * 3.0 / 36.0)
+    elif name in ("RO Pass1", "RO Pass2", "SWRO"):
+        flux = 14.0 if name == "SWRO" else 27.0
+        bar = {"SWRO": 60.0, "RO Pass2": 10.0, "RO Pass1": 15.0}[name]
+        el = math.ceil(qp * 1000.0 / (flux * 37.2))
+        pv = math.ceil(el / 6.0)
+        typ = "reverse osmosis"
+        sz = f"{el} elements / {pv} PV @ {bar:g} bar"
+        mkw = motor_kw(qf * bar / 36.0)
+    elif name == "EDI":
+        typ = "electrodeionisation"
+        sz = f"{math.ceil(qp / 10.5)} modules"
+    elif name == "NRMB":
+        typ = "mixed-bed polisher"
+        sz = f"resin {round(qf / 50.0, 2)} m3"
+    elif name == "GUARD":
+        typ, sz = "guard cartridges 0.22/0.05um", "absolute barrier"
+    elif name == "UV":
+        typ, sz = "UV 185nm", "N+1 reactors"
+    return typ, sz, mkw
+
+
+def _reject_tag(name: str) -> str:
+    if name in ("Clarifier", "HRSCC"):
+        return "sludge"
+    if name == "DAF":
+        return "float"
+    if name in ("ABF", "MMF", "GSF", "ACF", "SF", "UF"):
+        return "backwash"
+    if name == "WAC":
+        return "regenerant"
+    if name in ("RO Pass1", "RO Pass2", "SWRO"):
+        return "concentrate"
+    if name in ("EDI", "NRMB"):
+        return "reject"
+    return "waste"
+
+
+@dataclass(frozen=True)
+class Equipment:
+    unit: str
+    flow_in: float
+    flow_out: float
+    recovery_pct: float
+    type: str
+    size: str
+    motor_kw: float
+
+
+@dataclass(frozen=True)
+class Stream:
+    name: str          # S1..Sn product path, R1..Rn rejects
+    src: str
+    dst: str
+    flow: float        # m3/h
+    quality: Tuple[float, ...]   # one value per PARAMS entry
+
+    def quality_dict(self) -> Dict[str, float]:
+        return dict(zip(PARAMS, self.quality))
+
+
+@dataclass(frozen=True)
+class Design:
+    flowsheet: Flowsheet
+    case: WaterCase
+    equipment: Tuple[Equipment, ...]
+    streams: Tuple[Stream, ...]
+
+    # ---- reports ---------------------------------------------------------
+    def pfd_text(self) -> str:
+        """One-line text PFD: FEED -> units (in->out) -> PRODUCT, rejects below."""
+        fs = self.flowsheet
+        top = [f"FEED {fs.intake:.1f}"]
+        rejects = []
+        for e in self.equipment:
+            top.append(f"[{e.unit} {e.flow_in:.1f}->{e.flow_out:.1f}]")
+            r = e.flow_in - e.flow_out
+            if r > 1e-3:
+                rejects.append(f"  {e.unit}: {_reject_tag(e.unit)} "
+                               f"{r:.1f} m3/h")
+        top.append(f"PRODUCT {self.case.product_flow:.1f} m3/h")
+        out = " -> ".join(top)
+        if rejects:
+            out += "\nReject streams:\n" + "\n".join(rejects)
+        return out
+
+    def report(self) -> str:
+        fs = self.flowsheet
+        L: List[str] = []
+        L.append(f"Flowsheet : {fs.sfiles}")
+        L.append(f"Intake    : {fs.intake:.2f} m3/h   "
+                 f"Recovery: {fs.recovery_pct:.1f}%   "
+                 f"Reliability: {fs.reliability_pct:.1f}%   "
+                 f"TAC: {fs.tac:.3f}")
+        L.append("")
+        L.append("Equipment schedule")
+        hdr = (f"{'Unit':10} {'In m3/h':>8} {'Out m3/h':>9} {'Rec %':>6}  "
+               f"{'Type':30} {'Key size':28} {'Motor':>8}")
+        L.append(hdr)
+        L.append("-" * len(hdr))
+        for e in self.equipment:
+            L.append(f"{e.unit:10} {e.flow_in:8.1f} {e.flow_out:9.1f} "
+                     f"{e.recovery_pct:6.1f}  {e.type:30} {e.size:28} "
+                     f"{(str(e.motor_kw) + ' kW') if e.motor_kw else '':>8}")
+        L.append("")
+        L.append("Process Flow Diagram")
+        L.append(self.pfd_text())
+        L.append("")
+        L.append("Stream summary (flow + quality; product path and rejects)")
+        head = f"{'Stream':7} {'From':10} {'To':12} {'m3/h':>8} " + \
+               " ".join(f"{p:>9}" for p in PARAMS)
+        L.append(head)
+        L.append("-" * len(head))
+        for s in self.streams:
+            L.append(f"{s.name:7} {s.src:10} {s.dst:12} {s.flow:8.2f} " +
+                     " ".join(f"{v:9.4f}" for v in s.quality))
+        return "\n".join(L)
+
+
+def design(flowsheet: Flowsheet, case: WaterCase) -> Design:
+    """Size every unit of the flowsheet and build the stream table."""
+    seq = flowsheet.techs
+    m = len(seq)
+    if m == 0:
+        raise ValueError("Flowsheet has no units.")
+
+    # backward flow balance
+    fout = [0.0] * m
+    fin = [0.0] * m
+    fl = round_up_01(case.product_flow)
+    for k in range(m - 1, -1, -1):
+        fout[k] = fl
+        fl = round_up_01(fl / seq[k].recovery)
+        fin[k] = fl
+    intake = fin[0]
+
+    # equipment schedule
+    equipment = []
+    for k, t in enumerate(seq):
+        typ, sz, mkw = _size_unit(t.name, fin[k], fout[k])
+        equipment.append(Equipment(
+            unit=t.name, flow_in=round(fin[k], 1), flow_out=round(fout[k], 1),
+            recovery_pct=round(fout[k] / fin[k] * 100.0, 1),
+            type=typ, size=sz, motor_kw=mkw))
+
+    # forward composition profile
+    qmat = [list(case.feed)]
+    for t in seq:
+        qmat.append([qmat[-1][p] * (1.0 - t.removal[p]) for p in range(NP)])
+
+    # stream table: S1 feed, S2..Sm+1 product path, Rk rejects
+    streams: List[Stream] = [
+        Stream("S1", "intake", seq[0].name, round(intake, 2),
+               tuple(round(v, 4) for v in qmat[0]))]
+    for k in range(m):
+        dst = seq[k + 1].name if k < m - 1 else "PRODUCT"
+        streams.append(Stream(f"S{k + 2}", seq[k].name, dst,
+                              round(fout[k], 2),
+                              tuple(round(v, 4) for v in qmat[k + 1])))
+        rej = fin[k] - fout[k]
+        if rej > 1e-3:
+            qr = tuple(round(max(
+                (fin[k] * qmat[k][p] - fout[k] * qmat[k + 1][p]) / rej, 0.0), 4)
+                for p in range(NP))
+            streams.append(Stream(f"R{k + 1}", seq[k].name,
+                                  _reject_tag(seq[k].name),
+                                  round(rej, 2), qr))
+
+    return Design(flowsheet=flowsheet, case=case,
+                  equipment=tuple(equipment), streams=tuple(streams))

watertrain/engine.py

@@ -0,0 +1,180 @@
+"""Flowsheet generation and ranking engine.
+
+Superstructure depth-first enumeration with pruning rules P1..P7; each
+feasible train is solved by a backward flow balance, an analytical
+reliability (log-normal / normal-in-log-space approximation) and a
+total-annualised-cost (TAC) screening index.
+
+Direct port of GenerateFlowsheets / Dfs / Allowed / RecordTrain /
+RankFlowsheets in modWTP.bas — same numbers, same order.
+"""
+from __future__ import annotations
+
+import math
+from typing import List, Optional, Sequence
+
+from .model import (CAPITAL_CHARGE, HOURS_PER_YEAR, NP, RAW_COST, REJECT_COST,
+                    Flowsheet, Technology, WaterCase)
+from .database import DEFAULT_TECHNOLOGIES
+from .sfiles import sfiles_string
+
+EPS = 1e-9
+TDS = 7  # index of 'tds' in PARAMS
+
+
+def _phi(z: float) -> float:
+    """Standard normal CDF (VBA's Application.NormSDist)."""
+    return 0.5 * (1.0 + math.erf(z / math.sqrt(2.0)))
+
+
+def round_up_01(x: float) -> float:
+    """Round a flow up to 0.1 m3/h (VBA RoundUp01)."""
+    return math.ceil(x * 10.0 - EPS) / 10.0
+
+
+def _meets_spec(q: Sequence[float], target: Sequence[float]) -> bool:
+    return all(q[p] <= target[p] + EPS for p in range(NP))
+
+
+def _allowed(train: List[int], tech_i: int, q: Sequence[float],
+             techs: Sequence[Technology], case: WaterCase) -> bool:
+    """Pruning rules P1..P7: may technology tech_i extend this train?"""
+    t = techs[tech_i]
+
+    # P4 - no duplicate technology
+    if tech_i in train:
+        return False
+
+    # P1 - stage monotonicity
+    if train and t.stage < techs[train[-1]].stage:
+        return False
+
+    # P2 - inlet feasibility
+    for p in range(NP):
+        if q[p] > t.inlet_max[p] + EPS:
+            return False
+
+    # P3 - usefulness: must attack an outstanding difference
+    useful = any(
+        q[p] > case.target[p] + EPS and case.feed[p] > 0 and t.removal[p] > 0.05
+        for p in range(NP))
+    if not useful:
+        return False
+
+    # P6 - domain triggers
+    nm = t.name
+    if nm in ("EDI", "NRMB", "RO Pass2"):
+        if not any(techs[k].stage == 3 for k in train):
+            return False
+    if nm == "SWRO" and case.feed[TDS] < 10000:
+        return False
+    if nm == "RO Pass1" and case.feed[TDS] >= 10000:
+        return False
+    if nm == "GSF" and (q[3] + q[4]) < 0.1 and q[0] < 1:   # Fe+Mn, turbidity
+        return False
+
+    # P7 - first-pass RO needs a filtration barrier immediately upstream
+    if nm in ("RO Pass1", "SWRO"):
+        if not train or techs[train[-1]].stage != 2:
+            return False
+
+    return True
+
+
+def _make_flowsheet(train: List[int], q: Sequence[float],
+                    techs: Sequence[Technology],
+                    case: WaterCase) -> Flowsheet:
+    seq = [techs[k] for k in train]
+    depth = len(seq)
+
+    # backward flow balance (round each stream up to 0.1 m3/h)
+    fout = [0.0] * depth
+    fin = [0.0] * depth
+    fl = round_up_01(case.product_flow)
+    for k in range(depth - 1, -1, -1):
+        fout[k] = fl
+        fl = round_up_01(fl / seq[k].recovery)
+        fin[k] = fl
+    intake = fin[0]
+
+    # analytical reliability = min over attributes of P(quality <= spec)
+    rel = 1.0
+    for p in range(NP):
+        if case.feed[p] > 0 and case.target[p] > 0:
+            mu = math.log(case.feed[p])
+            var = 0.0
+            for t in seq:
+                e = min(t.removal[p], 0.9999)
+                s2 = math.log(1.0 + t.leak_cv ** 2)
+                mu += math.log(1.0 - e) - 0.5 * s2
+                var += s2
+            if var < EPS:
+                rp = 1.0 if q[p] <= case.target[p] else 0.0
+            else:
+                rp = _phi((math.log(case.target[p]) - mu) / math.sqrt(var))
+            rel = min(rel, rp)
+
+    # TAC screening index
+    capex = opex = rej = 0.0
+    for k, t in enumerate(seq):
+        capex += t.capex * fin[k] * 10000.0
+        opex += t.opex * fout[k] * 0.05
+        rej += fin[k] - fout[k]
+    tac = (CAPITAL_CHARGE * capex + HOURS_PER_YEAR * opex
+           + HOURS_PER_YEAR * RAW_COST * intake
+           + HOURS_PER_YEAR * REJECT_COST * rej)
+
+    return Flowsheet(
+        techs=tuple(seq),
+        sfiles=sfiles_string([t.name for t in seq]),
+        intake=round(intake, 2),
+        recovery_pct=round(case.product_flow / intake * 100.0, 1),
+        reliability_pct=round(rel * 100.0, 1),
+        tac=round(tac / 1e6, 3),
+        quality_out=tuple(q),
+    )
+
+
+def generate(case: WaterCase,
+             technologies: Optional[Sequence[Technology]] = None
+             ) -> List[Flowsheet]:
+    """Enumerate every feasible treatment train for the case.
+
+    Returns flowsheets in discovery (DFS) order, capped at
+    case.max_flowsheets and case.max_train_len.
+    """
+    case.validate()
+    techs = list(technologies if technologies is not None
+                 else DEFAULT_TECHNOLOGIES)
+    if not techs:
+        raise ValueError("Technology database is empty.")
+
+    out: List[Flowsheet] = []
+
+    def dfs(train: List[int], q: List[float]) -> None:
+        if len(out) >= case.max_flowsheets:
+            return
+        # goal: product spec met -> record and stop (no gold-plating)
+        if train and _meets_spec(q, case.target):
+            out.append(_make_flowsheet(train, q, techs, case))
+            return
+        if len(train) >= case.max_train_len:
+            return
+        for i in range(len(techs)):
+            if _allowed(train, i, q, techs, case):
+                nq = [q[p] * (1.0 - techs[i].removal[p]) for p in range(NP)]
+                train.append(i)
+                dfs(train, nq)
+                train.pop()
+                if len(out) >= case.max_flowsheets:
+                    return
+
+    dfs([], list(case.feed))
+    return out
+
+
+def rank(flowsheets: Sequence[Flowsheet], top_x: int = 10) -> List[Flowsheet]:
+    """Return the top_x flowsheets sorted ascending by TAC (stable)."""
+    if top_x <= 0:
+        top_x = 10
+    return sorted(flowsheets, key=lambda f: f.tac)[:top_x]

watertrain/examples.py

@@ -0,0 +1,51 @@
+"""The 7 built-in example cases (sheet 'Examples' of the workbook)."""
+from .model import WaterCase
+
+def _ex(name, feed, target, flow, source):
+    keys = ("turbidity", "tss", "oil_grease", "fe", "mn",
+            "cod", "toc", "tds", "sio2", "hardness")
+    return WaterCase.create(feed=dict(zip(keys, feed)),
+                            target=dict(zip(keys, target)),
+                            product_flow=flow, source=source,
+                            max_train_len=9, max_flowsheets=200, name=name)
+
+EXAMPLES = {e.name: e for e in [
+    _ex("1. CTBD reclaim (Ullah 2023)",
+        (17.1, 38.4, 0.5, 0.3, 0.1, 30, 8, 1484.8, 68.4, 1230),
+        (1, 1, 0.1, 0.1, 0.05, 10, 3, 300, 25, 270),
+        9, "Treated Wastewater/Sewage"),
+    _ex("2. SWRO desalination",
+        (15, 25, 0.5, 0.05, 0.02, 8, 3, 40000, 1, 6500),
+        (0.5, 1, 0.05, 0.2, 0.05, 5, 2, 450, 1, 80),
+        600, "Open Intake"),
+    _ex("3. TSE reuse to process water",
+        (8, 15, 2, 0.3, 0.1, 45, 12, 1200, 18, 250),
+        (1, 1, 0.1, 0.1, 0.05, 10, 2, 100, 5, 50),
+        500, "Treated Wastewater/Sewage"),
+    _ex("4. Ultra-pure water",
+        (5, 2, 0.2, 0.2, 0.1, 15, 10, 300, 10, 146),
+        (0.05, 0.05, 0.02, 0.005, 0.005, 0.5, 0.02, 0.06, 0.05, 0.05),
+        152, "Municipal"),
+    _ex("5. PFD-6 seawater desalination",
+        (12, 20, 0.3, 0.05, 0.02, 6, 2.5, 45000, 1, 6500),
+        (0.5, 1, 0.05, 0.2, 0.05, 5, 2, 500, 1, 100),
+        500, "Open Intake"),
+    _ex("6. PFD-1 reject reclaim",
+        (10, 15, 1, 0.3, 0.1, 40, 10, 5384, 30, 193),
+        (1, 1, 0.1, 0.1, 0.05, 10, 2, 100, 5, 20),
+        19.3, "Treated Wastewater/Sewage"),
+    _ex("7. PFD-2 HRSCC reclaim",
+        (12, 18, 1, 0.4, 0.15, 50, 12, 9735, 40, 300),
+        (1, 1, 0.1, 0.1, 0.05, 10, 2, 150, 8, 30),
+        17.9, "Treated Wastewater/Sewage"),
+]}
+
+def get_example(key) -> WaterCase:
+    """Look up an example by full name or by its leading number (1-7)."""
+    if key in EXAMPLES:
+        return EXAMPLES[key]
+    s = str(key).strip()
+    for name, case in EXAMPLES.items():
+        if name.split(".")[0] == s:
+            return case
+    raise KeyError(f"No example '{key}'. Available: {list(EXAMPLES)}")

watertrain/excel.py

@@ -0,0 +1,88 @@
+"""Optional Excel bridge (requires openpyxl: pip install watertrain[excel]).
+
+Lets users keep maintaining the technology database and inputs in the
+original workbook (WTP_FlowsheetGenerator.xlsm) and run the Python engine
+against it — same cell layout as the VBA ReadDatabase / ReadInputs.
+"""
+from __future__ import annotations
+
+from typing import List
+
+from .model import NP, Technology, WaterCase, PARAMS
+
+try:
+    from openpyxl import load_workbook
+except ImportError as _e:  # pragma: no cover
+    load_workbook = None
+    _import_error = _e
+
+
+def _require_openpyxl():
+    if load_workbook is None:
+        raise ImportError(
+            "openpyxl is required for Excel loading. "
+            "Install with: pip install watertrain[excel]") from _import_error
+
+
+def _num(v, default=0.0) -> float:
+    """Locale-safe numeric read (VBA NumVal)."""
+    if v is None:
+        return default
+    if isinstance(v, str):
+        v = v.strip().replace(",", ".")
+        if not v:
+            return default
+        try:
+            return float(v)
+        except ValueError:
+            return default
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return default
+
+
+def load_technologies(path: str,
+                      sheet: str = "2.ProcessGroups") -> List[Technology]:
+    """Read the technology database from the workbook (rows 4+)."""
+    _require_openpyxl()
+    wb = load_workbook(path, data_only=True, read_only=True, keep_vba=False)
+    ws = wb[sheet]
+    techs: List[Technology] = []
+    for row in ws.iter_rows(min_row=4, values_only=True):
+        if not row or row[0] in (None, ""):
+            break
+        name = str(row[0])
+        removal = {PARAMS[p]: _num(row[6 + p]) for p in range(NP)}
+        inlet = {}
+        for p in range(NP):
+            v = row[16 + p] if len(row) > 16 + p else None
+            if v not in (None, ""):
+                inlet[PARAMS[p]] = _num(v)
+        techs.append(Technology.create(
+            name=name, stage=int(_num(row[1])),
+            recovery=_num(row[2]), leak_cv=_num(row[3]),
+            capex=_num(row[4]), opex=_num(row[5]),
+            removal=removal, inlet_max=inlet))
+    wb.close()
+    return techs
+
+
+def load_case(path: str, sheet: str = "1.WaterQuality") -> WaterCase:
+    """Read the current inputs from the workbook (feed, spec, flow...)."""
+    _require_openpyxl()
+    wb = load_workbook(path, data_only=True, read_only=True, keep_vba=False)
+    ws = wb[sheet]
+    feed, target = {}, {}
+    for p in range(NP):
+        r = 4 + p
+        feed[PARAMS[p]] = _num(ws.cell(r, 2).value)
+        target[PARAMS[p]] = _num(ws.cell(r, 3).value)
+    flow = _num(ws.cell(15, 2).value)
+    source = str(ws.cell(16, 2).value or "")
+    max_len = int(_num(ws.cell(17, 2).value)) or 7
+    max_fs = int(_num(ws.cell(18, 2).value)) or 200
+    wb.close()
+    return WaterCase.create(feed=feed, target=target, product_flow=flow,
+                            source=source, max_train_len=max_len,
+                            max_flowsheets=max_fs, name=path)

watertrain/model.py

@@ -0,0 +1,131 @@
+"""Core data model for the WTP flowsheet generator.
+
+Direct port of the Excel/VBA tool (modWTP.bas). The 10 water-quality
+attributes and their order are fixed and must match everywhere:
+removals, inlet limits, feed and product-spec vectors.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Sequence, Tuple
+
+#: Water-quality attribute order (index 0..9). Matches 1.WaterQuality rows 4-13.
+PARAMS: Tuple[str, ...] = (
+    "turbidity", "tss", "oil_grease", "fe", "mn",
+    "cod", "toc", "tds", "sio2", "hardness",
+)
+NP = len(PARAMS)
+
+#: "no inlet limit" sentinel (same as 1E30 in the VBA)
+NO_LIMIT = 1e30
+
+# Economics constants (screening index, not a bid price)
+CAPITAL_CHARGE = 0.1     # /yr
+HOURS_PER_YEAR = 8000.0
+RAW_COST = 0.3           # $/m3 raw water proxy
+REJECT_COST = 0.5        # $/m3 reject disposal proxy
+
+
+def _vec(values: Optional[Dict[str, float]], default: float) -> Tuple[float, ...]:
+    values = values or {}
+    unknown = set(values) - set(PARAMS)
+    if unknown:
+        raise ValueError(f"Unknown water-quality parameter(s): {sorted(unknown)}. "
+                         f"Valid: {list(PARAMS)}")
+    return tuple(float(values.get(p, default)) for p in PARAMS)
+
+
+@dataclass(frozen=True)
+class Technology:
+    """One row of the 2.ProcessGroups technology database.
+
+    removal:  fraction removed per attribute (0-1)
+    inlet_max: max tolerated inlet concentration per attribute (NO_LIMIT = none)
+    stage: 1 = pre-treatment, 2 = filtration, 3 = RO, 4 = polish
+    """
+    name: str
+    stage: int
+    recovery: float          # water recovery fraction (0-1]
+    leak_cv: float           # performance CV driving reliability spread
+    capex: float             # relative capex index
+    opex: float              # relative opex index
+    removal: Tuple[float, ...]
+    inlet_max: Tuple[float, ...]
+
+    @classmethod
+    def create(cls, name: str, stage: int, recovery: float, leak_cv: float,
+               capex: float, opex: float,
+               removal: Optional[Dict[str, float]] = None,
+               inlet_max: Optional[Dict[str, float]] = None) -> "Technology":
+        rec = float(recovery) if recovery and recovery > 0 else 1.0  # guard /0
+        return cls(name=name, stage=int(stage), recovery=rec,
+                   leak_cv=float(leak_cv), capex=float(capex), opex=float(opex),
+                   removal=_vec(removal, 0.0),
+                   inlet_max=_vec(inlet_max, NO_LIMIT))
+
+
+@dataclass(frozen=True)
+class WaterCase:
+    """A design case: raw-water quality, product spec, product flow.
+
+    feed / target are given as {parameter: value} dicts; missing
+    parameters default to 0 (feed) which means "not present".
+    """
+    feed: Tuple[float, ...]
+    target: Tuple[float, ...]
+    product_flow: float                    # m3/h
+    source: str = ""
+    max_train_len: int = 7
+    max_flowsheets: int = 200
+    name: str = ""
+
+    @classmethod
+    def create(cls, feed: Dict[str, float], target: Dict[str, float],
+               product_flow: float, source: str = "",
+               max_train_len: int = 7, max_flowsheets: int = 200,
+               name: str = "") -> "WaterCase":
+        case = cls(feed=_vec(feed, 0.0), target=_vec(target, 0.0),
+                   product_flow=float(product_flow), source=source,
+                   max_train_len=int(max_train_len),
+                   max_flowsheets=int(max_flowsheets), name=name)
+        case.validate()
+        return case
+
+    def validate(self) -> None:
+        if all(f <= 0 for f in self.feed):
+            raise ValueError("All feed values are zero/blank - nothing to treat.")
+        blanks = [PARAMS[p] for p in range(NP)
+                  if self.feed[p] > 0 and self.target[p] <= 0]
+        if blanks:
+            raise ValueError(
+                "Product spec is blank/zero for parameters present in the feed "
+                f"(a spec of 0 can never be met): {blanks}")
+        if self.product_flow <= 0:
+            raise ValueError("product_flow must be > 0 (m3/h).")
+
+    def feed_dict(self) -> Dict[str, float]:
+        return dict(zip(PARAMS, self.feed))
+
+    def target_dict(self) -> Dict[str, float]:
+        return dict(zip(PARAMS, self.target))
+
+
+@dataclass(frozen=True)
+class Flowsheet:
+    """One feasible treatment train with its screening metrics."""
+    techs: Tuple[Technology, ...]
+    sfiles: str
+    intake: float          # m3/h at battery limit
+    recovery_pct: float    # product / intake * 100
+    reliability_pct: float # P(product meets spec) * 100
+    tac: float             # total annualised cost, screening index (M$/yr scale)
+    quality_out: Tuple[float, ...]   # deterministic product quality
+
+    @property
+    def unit_names(self) -> List[str]:
+        return [t.name for t in self.techs]
+
+    def __str__(self) -> str:
+        return (f"{self.sfiles}  intake={self.intake:.2f} m3/h  "
+                f"rec={self.recovery_pct:.1f}%  rel={self.reliability_pct:.1f}%  "
+                f"TAC={self.tac:.3f}")

watertrain/sfiles.py

@@ -0,0 +1,15 @@
+"""SFILES-style string representation of a treatment train."""
+from typing import Iterable
+
+_TAGS = {
+    "Clarifier": "clar", "DAF": "daf", "HRSCC": "hrscc", "ABF": "abf",
+    "MMF": "mmf", "GSF": "gsf", "ACF": "acf", "SF": "sf", "WAC": "wac",
+    "UF": "uf", "RO Pass1": "rop1", "SWRO": "swro", "RO Pass2": "rop2",
+    "EDI": "edi", "NRMB": "nrmb", "GUARD": "guard", "UV": "uv",
+}
+
+def sfiles_tag(name: str) -> str:
+    return _TAGS.get(name, name.lower())
+
+def sfiles_string(unit_names: Iterable[str]) -> str:
+    return "(iF)" + "".join(f"({sfiles_tag(n)})" for n in unit_names) + "(oP)"

watertrain-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+watertrain/__init__.py,sha256=HFXtGRlhqe-7HA83rC3DmGR--EByTVGYKDzi1IOWEPo,1563
+watertrain/cli.py,sha256=pLT6H3MfrA-NhAnukt4m5iZfwZg3c8ftsvEe7LePOgc,3717
+watertrain/database.py,sha256=1O-z4SqBjGfWPl8ASb7m0FqNXIU8-DppC6qcz9mu0po,3509
+watertrain/design.py,sha256=E0tcQKoJm7G0hcMFvdZ4VjynP0oCZUf0e6EynH4jzpg,7871
+watertrain/engine.py,sha256=gJsI22CcLtAyaVH-B4oSX0di1qHKLUXjkb3_4m32l3E,5949
+watertrain/examples.py,sha256=9y1oOtJU8tJlt1ab9oIA5LzwIbGUhTlfMB7yN4tlGxY,2196
+watertrain/excel.py,sha256=D2n6aPJig2K1wUiv0JcOp1-gHgb6SaAHE2hx9Pgn-HE,3040
+watertrain/model.py,sha256=UH9xNm9FMVDyvYUYyltNH4l2rYjcW79smSj2Ar4tsO4,5032
+watertrain/sfiles.py,sha256=-tLaCDsCIzFAc_q-damIiiHvskRt1rb057dV4xj__C4,592
+watertrain-1.0.0.dist-info/METADATA,sha256=Ym3ldzRnJCDzAlywxZObgWo1jISXGuTfP9lxbObKQPc,4702
+watertrain-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+watertrain-1.0.0.dist-info/entry_points.txt,sha256=TUsMtx0_t5aSdDFnoO7p5Q7NDauZVhWvholA6xO2kOQ,51
+watertrain-1.0.0.dist-info/top_level.txt,sha256=XcNd979HWJH-1Ms0lm5zDifBxCaTZlyjw7Nu4CwiEg0,11
+watertrain-1.0.0.dist-info/RECORD,,

watertrain-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

watertrain-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+watertrain = watertrain.cli:main

watertrain-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+watertrain