ReactorCheck

Turn reactor compositions or measured species flows into auditable catalytic metrics and QC.

ReactorCheck reads CSV/XLSX reactor data, reconstructs outlet molar flows from an explicitly confirmed internal standard or accepts direct measured flows, and runs both paths through one unit-aware scientific core. Results include reaction metrics, material closure, steady-state candidates, structured QC, calculation settings, and source provenance.

Install

Python 3.10 or newer is required. Tk is needed only for the desktop GUI.

python -m pip install reactorcheck

For the bundled example datasets, unreleased development code, or contributions, clone the public source and use an editable install instead:

30-second bundled example (source install)

git clone https://github.com/hdkim99/ReactorCheck.git
cd ReactorCheck
python -m pip install -e .
reactorcheck analyze examples/synthetic_composition.csv \
  --config examples/synthetic_composition_config.json \
  --output reactorcheck-composition.xlsx \
  --plot reactorcheck-composition.png
reactorcheck-gui

The synthetic CO hydrogenation example is available as both CSV and XLSX. Its hand calculation reconstructs CO/H2/CH3OH/N2 outlet flows of 0.5/1.0/0.5/1.0 mol/h.

The backward-compatible direct-flow example remains available:

reactorcheck analyze examples/synthetic_reactor.csv \
  --config examples/synthetic_config.json \
  --output reactorcheck-direct.xlsx

Supported scope in 0.2.x

Scientific safeguards

ReactorCheck never chooses an internal standard or infers that it is inert. A composition configuration must name the standard, provide its feed flow, set an actual JSON boolean confirmation, and record a written assumption. Missing, zero, negative, or non-finite standard fractions stop reconstruction. Wet/dry water basis and raw/normalized treatment are independent settings; the ambiguous single composition.basis key is rejected rather than guessed.

Raw composition sums are always retained and checked against a configured tolerance. Normalization does not change the internal-standard ratio, a property covered by scientific regression tests. See docs/scientific-definitions.md and the complete composition configuration.

Selected public real-data validation

ReactorCheck's IO and mapping paths have also been exercised against selected public fixed-bed reactor exports: a Zenodo online-GC workbook/processed-flow pair and a Mendeley Data dry-composition table. This does not imply validation for every instrument or published metric definition. Dataset DOI, license, checksums, files/columns used, failures found, scientific boundaries, and the opt-in reproduction command are recorded in docs/public-data-sources.md.

Outputs

Excel export contains summary, processed, qc, settings, and provenance sheets. Composition analyses preserve raw/used mole fractions, sums, source columns/units, inlet sources, reference reactant, water basis, normalization, internal-standard feed, reconstruction equation, and the user's assumption text.

Limitations

• Version 0.2.x uses one configured reference reactant; multi-reactant aggregate bases and stoichiometric selectivity coefficients are planned, not inferred.
• Internal-standard reconstruction assumes F_std,out = F_std,in exactly as the user declares; ReactorCheck cannot prove nonreactivity from composition data.
• Dry-basis data cannot reconstruct water flow. H2O must not be mapped as an outlet composition on a dry basis.
• Element and measured-mass closure cover mapped species only.
• Standard-volume conversion uses the ideal-gas equation at explicit T/P.
• The steady-state detector identifies statistical candidates only.

Related tools

These are independent repositories; interoperability is planned through public tabular/JSON schemas rather than shared private code.

• Ordifile — instrument-data standardization
• ReactorCheck — this reactor-analysis tool
• TPxLab — temperature-programmed analysis
• OperandoMerge — heterogeneous timeline alignment

Development

python -m pip install -e ".[dev]"
ruff format --check .
ruff check .
mypy src
pytest
python -m build
twine check dist/*

Synthetic example data are MIT-licensed with the project. See CONTRIBUTING.md and CITATION.cff. The 1280×640 social-preview.png is the current repository social-preview candidate and is generated from the same synthetic composition example shown above.