mfcblend 0.1.0__py3-none-any.whl

mfcblend/__init__.py

@@ -0,0 +1,37 @@
+"""MFCBlend public Python API."""
+
+from .core import (
+    Cylinder,
+    FeedResult,
+    FeedSystem,
+    InputError,
+    MFCConstraints,
+    SolutionStatus,
+    StandardConditions,
+    convert_reference_flow,
+    forward_mix,
+    ghsv,
+    inverse_mix,
+    molar_flow,
+    partial_pressures,
+    total_molar_flow,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Cylinder",
+    "FeedResult",
+    "FeedSystem",
+    "InputError",
+    "MFCConstraints",
+    "SolutionStatus",
+    "StandardConditions",
+    "convert_reference_flow",
+    "forward_mix",
+    "ghsv",
+    "inverse_mix",
+    "molar_flow",
+    "partial_pressures",
+    "total_molar_flow",
+]

mfcblend/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

mfcblend/application/__init__.py

@@ -0,0 +1,5 @@
+"""Application orchestration."""
+
+from .service import RunRequest, execute, execute_and_export
+
+__all__ = ["RunRequest", "execute", "execute_and_export"]

mfcblend/application/service.py

@@ -0,0 +1,38 @@
+"""Application services shared by the CLI and GUI."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from mfcblend.core import FeedResult, forward_mix, inverse_mix
+from mfcblend.io import export_result, load_setpoints, load_system, load_target
+
+
+@dataclass(frozen=True)
+class RunRequest:
+    system_path: Path
+    values_path: Path
+    mode: str
+    allow_approximate: bool = False
+
+
+def execute(request: RunRequest) -> FeedResult:
+    system = load_system(request.system_path)
+    if request.mode == "forward":
+        return forward_mix(system, load_setpoints(request.values_path))
+    if request.mode == "inverse":
+        composition, total_flow = load_target(request.values_path)
+        return inverse_mix(
+            system,
+            composition,
+            total_flow,
+            allow_approximate=request.allow_approximate,
+        )
+    raise ValueError("mode must be 'forward' or 'inverse'.")
+
+
+def execute_and_export(request: RunRequest, destination: str | Path) -> FeedResult:
+    result = execute(request)
+    export_result(result, destination)
+    return result

mfcblend/cli.py

@@ -0,0 +1,79 @@
+"""Headless command-line adapter."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from mfcblend.application import RunRequest, execute
+from mfcblend.core import InputError
+from mfcblend.io import export_result, load_system, result_dict
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mfcblend",
+        description="Plan catalytic-reactor gas feeds from cylinders and constrained MFCs.",
+    )
+    parser.add_argument("--version", action="version", version="%(prog)s 0.1.0")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    validate = subparsers.add_parser("validate", help="validate a feed-system JSON file")
+    validate.add_argument("system", type=Path)
+
+    for mode in ("forward", "inverse"):
+        command = subparsers.add_parser(mode, help=f"run a {mode} gas-feed calculation")
+        command.add_argument(
+            "system", type=Path, help="cylinders, MFC limits, and reference conditions"
+        )
+        command.add_argument(
+            "values", type=Path, help="setpoints JSON (forward) or target JSON (inverse)"
+        )
+        command.add_argument("--output", type=Path, help="write a .json or .csv result")
+        if mode == "inverse":
+            command.add_argument(
+                "--allow-approximate",
+                action="store_true",
+                help="return a clearly labelled approximate plan when no exact plan exists",
+            )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.command == "validate":
+            system = load_system(args.system)
+            print(
+                json.dumps(
+                    {
+                        "status": "valid",
+                        "cylinders": len(system.cylinders),
+                        "species": system.species,
+                        "flow_unit": system.flow_unit,
+                    },
+                    indent=2,
+                )
+            )
+            return 0
+        request = RunRequest(
+            system_path=args.system,
+            values_path=args.values,
+            mode=args.command,
+            allow_approximate=getattr(args, "allow_approximate", False),
+        )
+        result = execute(request)
+        if args.output:
+            export_result(result, args.output)
+        print(json.dumps(result_dict(result), indent=2, sort_keys=True))
+        return 2 if result.status.value == "infeasible" else 0
+    except (InputError, OSError, ValueError) as exc:
+        print(f"mfcblend: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mfcblend/core/__init__.py

@@ -0,0 +1,31 @@
+"""Scientific core: no GUI or plotting imports."""
+
+from .derived import ghsv, partial_pressures, total_molar_flow
+from .mixing import forward_mix, inverse_mix
+from .models import (
+    Cylinder,
+    FeedResult,
+    FeedSystem,
+    InputError,
+    MFCConstraints,
+    SolutionStatus,
+    StandardConditions,
+)
+from .standard import convert_reference_flow, molar_flow
+
+__all__ = [
+    "Cylinder",
+    "FeedResult",
+    "FeedSystem",
+    "InputError",
+    "MFCConstraints",
+    "SolutionStatus",
+    "StandardConditions",
+    "convert_reference_flow",
+    "forward_mix",
+    "ghsv",
+    "inverse_mix",
+    "molar_flow",
+    "partial_pressures",
+    "total_molar_flow",
+]

mfcblend/core/derived.py

@@ -0,0 +1,42 @@
+"""Derived reactor-feed quantities with explicit bases."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from .models import FeedResult, InputError
+from .standard import molar_flow
+
+
+def total_molar_flow(result: FeedResult) -> float:
+    """Return ideal-gas molar flow in mol/s at the stated reference conditions."""
+
+    return molar_flow(result.total_flow, result.flow_unit, result.standard_conditions)
+
+
+def partial_pressures(
+    composition: Mapping[str, float], total_pressure_pa: float
+) -> dict[str, float]:
+    """Return ideal-mixture partial pressures in Pa using ``p_i = y_i P``."""
+
+    if total_pressure_pa <= 0:
+        raise InputError("Total pressure must be greater than zero Pa absolute.")
+    return {species: fraction * total_pressure_pa for species, fraction in composition.items()}
+
+
+def ghsv(result: FeedResult, catalyst_bed_volume_ml: float) -> float:
+    """Return GHSV in h^-1 from reference volumetric flow / catalyst-bed volume.
+
+    This uses the same standard/reference conditions attached to ``result``.
+    It does not convert the feed to reactor-temperature actual volume.
+    """
+
+    if catalyst_bed_volume_ml <= 0:
+        raise InputError("Catalyst-bed volume must be greater than zero mL.")
+    if result.flow_unit in {"sccm", "nml/min"}:
+        flow_ml_min = result.total_flow
+    elif result.flow_unit == "slm":
+        flow_ml_min = result.total_flow * 1000.0
+    else:  # defensive: FeedSystem already validates this
+        raise InputError(f"Unsupported flow unit {result.flow_unit!r}.")
+    return flow_ml_min * 60.0 / catalyst_bed_volume_ml

mfcblend/core/mixing.py

@@ -0,0 +1,259 @@
+"""Forward and constrained inverse linear gas-mixing calculations."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from itertools import combinations
+from math import isfinite
+
+import numpy as np
+from scipy.optimize import lsq_linear
+
+from .models import FeedResult, FeedSystem, InputError, SolutionStatus
+
+
+def _ordered_setpoints(system: FeedSystem, setpoints: Mapping[str, float]) -> np.ndarray:
+    unknown = set(setpoints) - {cylinder.name for cylinder in system.cylinders}
+    if unknown:
+        raise InputError(f"Unknown cylinder setpoints: {', '.join(sorted(unknown))}.")
+    ordered: list[float] = []
+    for cylinder in system.cylinders:
+        value = float(setpoints.get(cylinder.name, 0.0))
+        if not isfinite(value):
+            raise InputError(f"Setpoint for {cylinder.name!r} must be finite.")
+        if not cylinder.mfc.accepts(value):
+            raise InputError(
+                f"Setpoint {value:g} for {cylinder.name!r} is neither off nor within "
+                f"[{cylinder.mfc.effective_minimum:g}, {cylinder.mfc.maximum:g}] "
+                f"{system.flow_unit}."
+            )
+        ordered.append(0.0 if abs(value) <= 1e-12 else value)
+    return np.asarray(ordered, dtype=float)
+
+
+def _forward_from_vector(system: FeedSystem, flows: np.ndarray) -> FeedResult:
+    total = float(np.sum(flows))
+    if total <= 0:
+        raise InputError("Total flow must be greater than zero.")
+    component_flows = {
+        species: float(
+            sum(
+                flow * cylinder.composition.get(species, 0.0)
+                for flow, cylinder in zip(flows, system.cylinders, strict=True)
+            )
+        )
+        for species in system.species
+    }
+    composition = {
+        species: component_flow / total for species, component_flow in component_flows.items()
+    }
+    ratios = {
+        f"{numerator}/{denominator}": (
+            None
+            if composition[denominator] == 0
+            else composition[numerator] / composition[denominator]
+        )
+        for numerator, denominator in system.reported_ratios
+    }
+    diluent_fraction = (
+        sum(composition[species] for species in system.diluents) if system.diluents else None
+    )
+    return FeedResult(
+        status=SolutionStatus.EXACT,
+        setpoints={
+            cylinder.name: float(flow)
+            for cylinder, flow in zip(system.cylinders, flows, strict=True)
+        },
+        total_flow=total,
+        composition=composition,
+        component_flows=component_flows,
+        flow_unit=system.flow_unit,
+        standard_conditions=system.standard_conditions,
+        ratios=ratios,
+        diluent_fraction=diluent_fraction,
+        messages=(
+            "Composition is a molar-fraction result from ideal mixing of the stated "
+            "cylinder compositions.",
+            "This plan does not assess mixture flammability, compatibility, or process safety.",
+        ),
+    )
+
+
+def forward_mix(system: FeedSystem, setpoints: Mapping[str, float]) -> FeedResult:
+    """Calculate the mixed feed from user-supplied MFC setpoints."""
+
+    return _forward_from_vector(system, _ordered_setpoints(system, setpoints))
+
+
+def _validate_target(
+    system: FeedSystem, target_composition: Mapping[str, float], total_flow: float
+) -> dict[str, float]:
+    if not isfinite(total_flow) or total_flow <= 0:
+        raise InputError("Target total flow must be finite and greater than zero.")
+    if not target_composition:
+        raise InputError("At least one target species fraction is required.")
+    target: dict[str, float] = {}
+    for species, value in target_composition.items():
+        if species not in system.species:
+            raise InputError(f"Target species {species!r} is absent from every cylinder.")
+        fraction = float(value)
+        if not isfinite(fraction) or fraction < 0 or fraction > 1:
+            raise InputError(f"Target fraction for {species!r} must be finite and within [0, 1].")
+        target[species] = fraction
+    closure = sum(target.values())
+    if closure > 1 + 1e-9:
+        raise InputError(f"Specified target fractions sum to {closure:.12g}, which exceeds 1.")
+    return target
+
+
+def _active_subsets(count: int) -> list[tuple[int, ...]]:
+    if count > 16:
+        raise InputError(
+            "Inverse planning currently supports at most 16 MFCs because off/on limits "
+            "are enumerated exactly."
+        )
+    return [subset for size in range(1, count + 1) for subset in combinations(range(count), size)]
+
+
+def inverse_mix(
+    system: FeedSystem,
+    target_composition: Mapping[str, float],
+    total_flow: float,
+    *,
+    allow_approximate: bool = False,
+    composition_tolerance: float = 1e-7,
+    total_flow_tolerance: float = 1e-7,
+) -> FeedResult:
+    """Solve constrained MFC setpoints for a requested final feed.
+
+    The model is the linear material balance ``A q = b``. Each MFC may be off,
+    or it must lie inside its effective operating range. Those disjoint bounds
+    are handled by enumerating active MFC subsets and solving each bounded
+    linear least-squares problem. An approximate solution is returned only when
+    ``allow_approximate`` is true.
+    """
+
+    target = _validate_target(system, target_composition, total_flow)
+    if composition_tolerance <= 0 or total_flow_tolerance <= 0:
+        raise InputError("Inverse-solver tolerances must be greater than zero.")
+    target_species = tuple(target)
+    best: tuple[float, np.ndarray, FeedResult, float, float] | None = None
+
+    for active in _active_subsets(len(system.cylinders)):
+        component_matrix = np.asarray(
+            [
+                [system.cylinders[index].composition.get(species, 0.0) for index in active]
+                for species in target_species
+            ],
+            dtype=float,
+        )
+        # Normalize all material-balance rows by target total flow. This makes
+        # component and total-flow residuals dimensionless and comparable.
+        matrix = np.vstack((component_matrix, np.ones(len(active), dtype=float))) / total_flow
+        rhs = np.asarray([*target.values(), 1.0], dtype=float)
+        lower = np.asarray(
+            [system.cylinders[index].mfc.effective_minimum for index in active], dtype=float
+        )
+        upper = np.asarray([system.cylinders[index].mfc.maximum for index in active], dtype=float)
+        fixed = np.isclose(lower, upper, rtol=1e-12, atol=1e-12)
+        active_solution = np.empty(len(active), dtype=float)
+        active_solution[fixed] = (lower[fixed] + upper[fixed]) / 2
+        remaining_rhs = rhs - matrix[:, fixed] @ active_solution[fixed]
+        if np.any(~fixed):
+            solved = lsq_linear(
+                matrix[:, ~fixed],
+                remaining_rhs,
+                bounds=(lower[~fixed], upper[~fixed]),
+                lsmr_tol="auto",
+            )
+            active_solution[~fixed] = solved.x
+        flows = np.zeros(len(system.cylinders), dtype=float)
+        flows[list(active)] = active_solution
+        try:
+            forward = _forward_from_vector(system, flows)
+        except InputError:
+            continue
+        composition_error = max(
+            abs(forward.composition.get(species, 0.0) - fraction)
+            for species, fraction in target.items()
+        )
+        flow_error = abs(forward.total_flow - total_flow)
+        residual = float(np.linalg.norm(matrix @ active_solution - rhs))
+        if best is None or residual < best[0]:
+            best = (residual, flows, forward, composition_error, flow_error)
+
+    if best is None:
+        return FeedResult(
+            status=SolutionStatus.INFEASIBLE,
+            setpoints={},
+            total_flow=0.0,
+            composition={},
+            component_flows={},
+            flow_unit=system.flow_unit,
+            standard_conditions=system.standard_conditions,
+            target_composition=target,
+            target_total_flow=total_flow,
+            messages=(
+                "Target composition is infeasible with the available cylinders and MFC "
+                "operating ranges.",
+                "No setpoints are returned as a successful plan.",
+            ),
+        )
+
+    _, flows, forward, composition_error, flow_error = best
+    is_exact = (
+        composition_error <= composition_tolerance
+        and flow_error <= total_flow_tolerance * max(1.0, total_flow)
+    )
+    if not is_exact and not allow_approximate:
+        return FeedResult(
+            status=SolutionStatus.INFEASIBLE,
+            setpoints={},
+            total_flow=forward.total_flow,
+            composition=forward.composition,
+            component_flows=forward.component_flows,
+            flow_unit=system.flow_unit,
+            standard_conditions=system.standard_conditions,
+            target_composition=target,
+            target_total_flow=total_flow,
+            maximum_composition_error=composition_error,
+            total_flow_error=flow_error,
+            ratios=forward.ratios,
+            diluent_fraction=forward.diluent_fraction,
+            messages=(
+                "Target composition is infeasible within the requested tolerances and MFC "
+                "operating ranges.",
+                "The achieved composition is diagnostic only; no setpoints are returned "
+                "as a successful plan.",
+            ),
+        )
+
+    status = SolutionStatus.EXACT if is_exact else SolutionStatus.APPROXIMATE
+    status_message = (
+        "An exact constrained material-balance solution was found."
+        if is_exact
+        else "Only an approximate constrained solution was found; review the reported residuals."
+    )
+    return FeedResult(
+        status=status,
+        setpoints={
+            cylinder.name: float(flow)
+            for cylinder, flow in zip(system.cylinders, flows, strict=True)
+        },
+        total_flow=forward.total_flow,
+        composition=forward.composition,
+        component_flows=forward.component_flows,
+        flow_unit=system.flow_unit,
+        standard_conditions=system.standard_conditions,
+        target_composition=target,
+        target_total_flow=total_flow,
+        maximum_composition_error=composition_error,
+        total_flow_error=flow_error,
+        ratios=forward.ratios,
+        diluent_fraction=forward.diluent_fraction,
+        messages=(
+            status_message,
+            "The solve uses ideal linear mixing on a molar-flow basis.",
+            "This plan does not assess mixture flammability, compatibility, or process safety.",
+        ),
+    )

mfcblend/core/models.py

@@ -0,0 +1,172 @@
+"""Validated domain models for gas-feed planning.
+
+All compositions are molar fractions. Flow numbers are equivalent volumetric
+flows at one explicitly supplied reference temperature and pressure.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from math import isfinite
+
+
+class InputError(ValueError):
+    """Raised when an input is mathematically or physically invalid."""
+
+
+def _require_finite(name: str, value: float) -> None:
+    if not isfinite(value):
+        raise InputError(f"{name} must be finite; received {value!r}.")
+
+
+@dataclass(frozen=True)
+class StandardConditions:
+    """Reference conditions attached to an equivalent volumetric gas flow."""
+
+    temperature_k: float
+    pressure_pa: float
+
+    def __post_init__(self) -> None:
+        _require_finite("reference temperature", self.temperature_k)
+        _require_finite("reference pressure", self.pressure_pa)
+        if self.temperature_k <= 0:
+            raise InputError("Reference temperature must be greater than 0 K.")
+        if self.pressure_pa <= 0:
+            raise InputError("Reference pressure must be greater than 0 Pa absolute.")
+
+
+@dataclass(frozen=True)
+class MFCConstraints:
+    """Setpoint limits for one MFC, in the plan's common flow unit.
+
+    An MFC may be off (zero) or operate from ``effective_minimum`` through
+    ``maximum``. ``turndown`` is full-scale flow divided by minimum controllable
+    flow; the tool does not infer a vendor-specific turndown when it is omitted.
+    """
+
+    minimum: float
+    maximum: float
+    turndown: float | None = None
+
+    def __post_init__(self) -> None:
+        _require_finite("MFC minimum", self.minimum)
+        _require_finite("MFC maximum", self.maximum)
+        if self.minimum < 0:
+            raise InputError("MFC minimum cannot be negative.")
+        if self.maximum <= 0:
+            raise InputError("MFC maximum must be greater than zero.")
+        if self.minimum > self.maximum:
+            raise InputError("MFC minimum cannot exceed MFC maximum.")
+        if self.turndown is not None:
+            _require_finite("MFC turndown", self.turndown)
+            if self.turndown < 1:
+                raise InputError("MFC turndown must be at least 1 (full scale / minimum).")
+
+    @property
+    def effective_minimum(self) -> float:
+        turndown_minimum = 0.0 if self.turndown is None else self.maximum / self.turndown
+        return max(self.minimum, turndown_minimum)
+
+    def accepts(self, flow: float, *, atol: float = 1e-12) -> bool:
+        _require_finite("MFC setpoint", flow)
+        if abs(flow) <= atol:
+            return True
+        return self.effective_minimum - atol <= flow <= self.maximum + atol
+
+
+@dataclass(frozen=True)
+class Cylinder:
+    """A cylinder composition and the constraints of its connected MFC."""
+
+    name: str
+    composition: Mapping[str, float]
+    mfc: MFCConstraints
+
+    def __post_init__(self) -> None:
+        if not self.name.strip():
+            raise InputError("Cylinder name cannot be empty.")
+        if not self.composition:
+            raise InputError(f"Cylinder {self.name!r} must contain at least one species.")
+        normalized: dict[str, float] = {}
+        for species, fraction in self.composition.items():
+            if not species.strip():
+                raise InputError(f"Cylinder {self.name!r} contains an empty species name.")
+            _require_finite(f"fraction of {species} in {self.name}", fraction)
+            if fraction < 0 or fraction > 1:
+                raise InputError(f"Fraction of {species!r} in {self.name!r} must be within [0, 1].")
+            normalized[species.strip()] = float(fraction)
+        closure = sum(normalized.values())
+        if abs(closure - 1.0) > 1e-9:
+            raise InputError(f"Cylinder {self.name!r} composition sums to {closure:.12g}, not 1.")
+        object.__setattr__(self, "composition", normalized)
+
+
+@dataclass(frozen=True)
+class FeedSystem:
+    """Cylinders sharing one flow unit and reference condition convention."""
+
+    cylinders: tuple[Cylinder, ...]
+    flow_unit: str
+    standard_conditions: StandardConditions
+    reported_ratios: tuple[tuple[str, str], ...] = ()
+    diluents: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.cylinders:
+            raise InputError("At least one cylinder is required.")
+        names = [cylinder.name for cylinder in self.cylinders]
+        if len(set(names)) != len(names):
+            raise InputError("Cylinder names must be unique.")
+        if self.flow_unit not in {"sccm", "slm", "nml/min"}:
+            raise InputError("flow_unit must be one of: sccm, slm, nml/min.")
+        known_species = set(self.species)
+        for numerator, denominator in self.reported_ratios:
+            if numerator not in known_species or denominator not in known_species:
+                raise InputError(
+                    f"Reported ratio {numerator}/{denominator} refers to an unknown species."
+                )
+        unknown_diluents = set(self.diluents) - known_species
+        if unknown_diluents:
+            raise InputError(
+                f"Diluents are absent from every cylinder: {', '.join(sorted(unknown_diluents))}."
+            )
+
+    @property
+    def species(self) -> tuple[str, ...]:
+        return tuple(
+            sorted({species for cylinder in self.cylinders for species in cylinder.composition})
+        )
+
+    def cylinder(self, name: str) -> Cylinder:
+        for cylinder in self.cylinders:
+            if cylinder.name == name:
+                return cylinder
+        raise InputError(f"Unknown cylinder {name!r}.")
+
+
+class SolutionStatus(str, Enum):
+    EXACT = "exact"
+    APPROXIMATE = "approximate"
+    INFEASIBLE = "infeasible"
+
+
+@dataclass(frozen=True)
+class FeedResult:
+    """Common forward/inverse feed result."""
+
+    status: SolutionStatus
+    setpoints: Mapping[str, float]
+    total_flow: float
+    composition: Mapping[str, float]
+    component_flows: Mapping[str, float]
+    flow_unit: str
+    standard_conditions: StandardConditions
+    messages: tuple[str, ...] = field(default_factory=tuple)
+    target_composition: Mapping[str, float] | None = None
+    target_total_flow: float | None = None
+    maximum_composition_error: float | None = None
+    total_flow_error: float | None = None
+    ratios: Mapping[str, float | None] = field(default_factory=dict)
+    diluent_fraction: float | None = None