reactorcheck 0.2.0__py3-none-any.whl

reactorcheck/__init__.py

@@ -0,0 +1,21 @@
+"""ReactorCheck public API."""
+
+from reactorcheck.models import (
+    AnalysisConfig,
+    AnalysisResult,
+    ChannelMapping,
+    CompositionSettings,
+    Species,
+)
+from reactorcheck.service import analyze_file, analyze_frame
+
+__all__ = [
+    "AnalysisConfig",
+    "AnalysisResult",
+    "ChannelMapping",
+    "CompositionSettings",
+    "Species",
+    "analyze_file",
+    "analyze_frame",
+]
+__version__ = "0.2.0"

reactorcheck/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m reactorcheck``."""
+
+from reactorcheck.cli import main
+
+raise SystemExit(main())

reactorcheck/calculations.py

@@ -0,0 +1,142 @@
+"""Pure scientific calculations for catalytic reactor data.
+
+All flow arrays accepted here are mol/h. Dimensioned inputs are normalized by
+the service layer before entering this module, keeping equations explicit and
+testable without any GUI or file-I/O state.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from reactorcheck.models import Species
+
+
+def _arrays(
+    numerator: ArrayLike, denominator: ArrayLike
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    return np.asarray(numerator, dtype=float), np.asarray(denominator, dtype=float)
+
+
+def safe_ratio(numerator: ArrayLike, denominator: ArrayLike) -> NDArray[np.float64]:
+    """Divide while representing a zero/invalid denominator as NaN."""
+    top, bottom = _arrays(numerator, denominator)
+    result = np.full(np.broadcast_shapes(top.shape, bottom.shape), np.nan, dtype=float)
+    valid = np.isfinite(top) & np.isfinite(bottom) & (bottom != 0.0)
+    np.divide(top, bottom, out=result, where=valid)
+    return result
+
+
+def conversion(inlet: ArrayLike, outlet: ArrayLike) -> NDArray[np.float64]:
+    """Reactant conversion X = (F_in - F_out) / F_in."""
+    inlet_array, outlet_array = _arrays(inlet, outlet)
+    return safe_ratio(inlet_array - outlet_array, inlet_array)
+
+
+def net_formation(inlet: ArrayLike, outlet: ArrayLike) -> NDArray[np.float64]:
+    """Net species formation F_out - F_in in mol/h."""
+    inlet_array, outlet_array = _arrays(inlet, outlet)
+    return outlet_array - inlet_array
+
+
+def molar_selectivity(
+    product_formation: ArrayLike, reactant_consumption: ArrayLike
+) -> NDArray[np.float64]:
+    """Molar selectivity = mol product formed / mol reference reactant consumed."""
+    return safe_ratio(product_formation, reactant_consumption)
+
+
+def carbon_selectivity(
+    product_formation: ArrayLike,
+    product_carbon_number: int,
+    reactant_consumption: ArrayLike,
+    reactant_carbon_number: int,
+) -> NDArray[np.float64]:
+    """Carbon selectivity based on carbon atoms in net product and consumed feed."""
+    if reactant_carbon_number <= 0:
+        return np.full(np.asarray(product_formation).shape, np.nan, dtype=float)
+    return safe_ratio(
+        np.asarray(product_formation) * product_carbon_number,
+        np.asarray(reactant_consumption) * reactant_carbon_number,
+    )
+
+
+def direct_yield(product_formation: ArrayLike, reactant_inlet: ArrayLike) -> NDArray[np.float64]:
+    """Molar product yield = net mol product formed / mol reference reactant fed.
+
+    Under the same molar basis, this is identically conversion times molar
+    selectivity. Keeping the direct equation permits an independent consistency
+    check in the service and tests.
+    """
+    return safe_ratio(product_formation, reactant_inlet)
+
+
+def element_balance(
+    inlet_flows: Mapping[str, NDArray[np.float64]],
+    outlet_flows: Mapping[str, NDArray[np.float64]],
+    species: Mapping[str, Species],
+    element: str,
+) -> NDArray[np.float64]:
+    """Element recovery = total elemental molar outflow / inflow."""
+    sample = next(iter(outlet_flows.values()))
+    element_in = np.zeros_like(sample, dtype=float)
+    element_out = np.zeros_like(sample, dtype=float)
+    for name, item in species.items():
+        count = item.composition.get(element, 0)
+        element_in += inlet_flows[name] * count
+        element_out += outlet_flows[name] * count
+    return safe_ratio(element_out, element_in)
+
+
+def mass_balance(
+    inlet_flows: Mapping[str, NDArray[np.float64]],
+    outlet_flows: Mapping[str, NDArray[np.float64]],
+    species: Mapping[str, Species],
+) -> NDArray[np.float64]:
+    """Measured-species mass recovery = Σ(F_out MW) / Σ(F_in MW).
+
+    This is a measured-stream closure, not a total plant balance when unmeasured
+    species exist; the report labels it accordingly.
+    """
+    sample = next(iter(outlet_flows.values()))
+    mass_in = np.zeros_like(sample, dtype=float)
+    mass_out = np.zeros_like(sample, dtype=float)
+    for name, item in species.items():
+        mass_in += inlet_flows[name] * item.molecular_weight_g_mol
+        mass_out += outlet_flows[name] * item.molecular_weight_g_mol
+    return safe_ratio(mass_out, mass_in)
+
+
+def reaction_rate_mol_gcat_h(
+    formation_mol_h: ArrayLike, catalyst_mass_g: float
+) -> NDArray[np.float64]:
+    """Net formation rate r = ΔF / m_cat in mol g_cat⁻¹ h⁻¹."""
+    if catalyst_mass_g <= 0:
+        raise ValueError("Catalyst mass must be positive")
+    return np.asarray(formation_mol_h, dtype=float) / catalyst_mass_g
+
+
+def sty_gproduct_gcat_h(
+    formation_mol_h: ArrayLike,
+    molecular_weight_g_mol: float,
+    catalyst_mass_g: float,
+) -> NDArray[np.float64]:
+    """Mass-based STY = ΔF_product MW_product / m_cat."""
+    return reaction_rate_mol_gcat_h(formation_mol_h, catalyst_mass_g) * molecular_weight_g_mol
+
+
+def ghsv_h_inverse(volumetric_feed_ml_h: float, reactor_volume_ml: float) -> float:
+    """GHSV = standard volumetric feed rate / packed reactor volume, h⁻¹."""
+    if volumetric_feed_ml_h < 0 or reactor_volume_ml <= 0:
+        raise ValueError("Feed flow cannot be negative and reactor volume must be positive")
+    return volumetric_feed_ml_h / reactor_volume_ml
+
+
+def whsv_h_inverse(mass_feed_g_h: float, catalyst_mass_g: float) -> float:
+    """WHSV = total feed mass flow / catalyst mass, h⁻¹."""
+    if mass_feed_g_h < 0 or catalyst_mass_g <= 0:
+        raise ValueError("Feed flow cannot be negative and catalyst mass must be positive")
+    return mass_feed_g_h / catalyst_mass_g

reactorcheck/cli.py

@@ -0,0 +1,74 @@
+"""Command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from reactorcheck import __version__
+from reactorcheck.io import (
+    export_csv_bundle,
+    export_excel,
+    load_config,
+    read_table,
+    suggest_mappings,
+)
+from reactorcheck.plotting import save_result_plot
+from reactorcheck.service import analyze_file
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Create the public CLI parser."""
+    parser = argparse.ArgumentParser(prog="reactorcheck", description=__doc__)
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    analyze = subparsers.add_parser("analyze", help="Analyze reactor CSV/XLSX data")
+    analyze.add_argument("data", type=Path)
+    analyze.add_argument("--config", "-c", type=Path, required=True)
+    analyze.add_argument(
+        "--output", "-o", type=Path, required=True, help=".xlsx file or CSV bundle directory"
+    )
+    analyze.add_argument("--plot", type=Path)
+    suggest = subparsers.add_parser("suggest", help="Suggest species mappings for user review")
+    suggest.add_argument("data", type=Path)
+    suggest.add_argument("--output", "-o", type=Path)
+    subparsers.add_parser("gui", help="Launch the desktop GUI")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run CLI and return a process exit code."""
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "analyze":
+            result = analyze_file(args.data, load_config(args.config))
+            if args.output.suffix.lower() == ".xlsx":
+                export_excel(result, args.output)
+            else:
+                export_csv_bundle(result, args.output)
+            if args.plot:
+                save_result_plot(result, args.plot)
+            print(f"Analyzed {len(result.processed)} rows; QC issues: {len(result.qc_issues)}")
+            return 0
+        if args.command == "suggest":
+            text = json.dumps(suggest_mappings(read_table(args.data)), indent=2) + "\n"
+            if args.output:
+                args.output.write_text(text, encoding="utf-8")
+            else:
+                print(text, end="")
+            return 0
+        if args.command == "gui":
+            from reactorcheck.gui import main as gui_main
+
+            gui_main()
+            return 0
+    except (OSError, ValueError) as exc:
+        print(f"reactorcheck: error: {exc}", file=sys.stderr)
+        return 2
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

reactorcheck/composition.py

@@ -0,0 +1,115 @@
+"""Mole-fraction normalization and internal-standard flow reconstruction."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from reactorcheck.models import CompositionTreatment
+
+
+class CompositionError(ValueError):
+    """Raised when a composition cannot be physically reconstructed."""
+
+
+@dataclass(frozen=True)
+class CompositionResolution:
+    """Raw/used fractions and reconstructed outlet molar flows."""
+
+    raw_fractions: dict[str, NDArray[np.float64]]
+    used_fractions: dict[str, NDArray[np.float64]]
+    outlet_mol_h: dict[str, NDArray[np.float64]]
+    raw_sum: NDArray[np.float64]
+    used_sum: NDArray[np.float64]
+    normalization_applied: bool
+
+
+def to_fraction(values: ArrayLike, unit: str) -> NDArray[np.float64]:
+    """Convert an explicitly labeled composition unit to mole fraction."""
+    normalized = unit.strip().lower().replace(" ", "_")
+    factors = {
+        "fraction": 1.0,
+        "mole_fraction": 1.0,
+        "mol/mol": 1.0,
+        "1": 1.0,
+        "%": 0.01,
+        "percent": 0.01,
+        "mol%": 0.01,
+        "mole_percent": 0.01,
+        "ppm": 1e-6,
+        "ppmv": 1e-6,
+    }
+    if normalized not in factors:
+        raise CompositionError(
+            f"Unsupported composition unit {unit!r}; use fraction, percent/mol%, or ppm/ppmv"
+        )
+    return np.asarray(values, dtype=float) * factors[normalized]
+
+
+def reconstruct_with_internal_standard(
+    measurements: Mapping[str, ArrayLike],
+    units: Mapping[str, str],
+    normalization: CompositionTreatment,
+    internal_standard: str,
+    standard_feed_mol_h: float,
+) -> CompositionResolution:
+    """Reconstruct F_out,i = y_i/y_std * F_std,in.
+
+    The caller must have already validated the user's explicit assumption that
+    the standard is nonreactive, so F_std,out equals F_std,in. Normalization is
+    applied only when ``normalization`` is ``normalized``. Wet/dry water basis is
+    validated independently by the domain model and does not alter the ratio.
+    Global normalization must not alter reconstructed flows; retaining raw and
+    used values makes that invariant auditable.
+    """
+    if internal_standard not in measurements:
+        raise CompositionError("Internal-standard composition channel is missing")
+    if standard_feed_mol_h <= 0 or not np.isfinite(standard_feed_mol_h):
+        raise CompositionError("Internal-standard feed flow must be finite and positive")
+    raw = {name: to_fraction(values, units[name]) for name, values in measurements.items()}
+    lengths = {len(values) for values in raw.values()}
+    if len(lengths) != 1:
+        raise CompositionError("Composition channels have inconsistent lengths")
+    standard_values = raw[internal_standard]
+    invalid_standard = ~np.isfinite(standard_values) | (standard_values <= 0)
+    if invalid_standard.any():
+        rows = tuple(int(value) for value in np.flatnonzero(invalid_standard)[:20])
+        raise CompositionError(
+            f"Internal-standard fraction must be finite and positive; invalid rows={rows}"
+        )
+    negative = {
+        name: tuple(int(value) for value in np.flatnonzero(values < 0)[:20])
+        for name, values in raw.items()
+        if (values < 0).any()
+    }
+    if negative:
+        raise CompositionError(f"Negative mole fractions are physically invalid: {negative}")
+
+    stack = np.vstack(tuple(raw.values()))
+    raw_sum = np.sum(stack, axis=0)
+    normalization_applied = normalization == "normalized"
+    if normalization_applied:
+        invalid_sum = ~np.isfinite(raw_sum) | (raw_sum <= 0)
+        if invalid_sum.any():
+            rows = tuple(int(value) for value in np.flatnonzero(invalid_sum)[:20])
+            raise CompositionError(
+                "Composition sum must be finite and positive for normalization; "
+                f"invalid rows={rows}"
+            )
+        used = {name: values / raw_sum for name, values in raw.items()}
+    else:
+        used = {name: values.copy() for name, values in raw.items()}
+    used_sum = np.sum(np.vstack(tuple(used.values())), axis=0)
+    used_standard = used[internal_standard]
+    outlet = {name: (values / used_standard) * standard_feed_mol_h for name, values in used.items()}
+    return CompositionResolution(
+        raw_fractions=raw,
+        used_fractions=used,
+        outlet_mol_h=outlet,
+        raw_sum=np.asarray(raw_sum, dtype=float),
+        used_sum=np.asarray(used_sum, dtype=float),
+        normalization_applied=normalization_applied,
+    )