Metadata-Version: 2.5
Name: impregcalc
Version: 0.1.0
Summary: Explicit supported-catalyst impregnation recipe calculations.
Project-URL: Homepage, https://github.com/hdkim99/ImpregCalc
Project-URL: Repository, https://github.com/hdkim99/ImpregCalc
Project-URL: Issues, https://github.com/hdkim99/ImpregCalc/issues
Project-URL: Documentation, https://github.com/hdkim99/ImpregCalc#readme
Project-URL: Releases, https://github.com/hdkim99/ImpregCalc/releases
Author: Hyun Dong Kim
License: MIT License
        
        Copyright (c) 2026 Hyun Dong Kim
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
License-File: LICENSE
Keywords: catalysis,catalyst-preparation,chemical-engineering,impregnation,research-software,stoichiometry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: matplotlib>=3.7; extra == 'all'
Requires-Dist: openpyxl>=3.1; extra == 'all'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: openpyxl>=3.1; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Requires-Dist: types-openpyxl>=3.1; extra == 'dev'
Provides-Extra: gui
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == 'plot'
Provides-Extra: xlsx
Requires-Dist: openpyxl>=3.1; extra == 'xlsx'
Description-Content-Type: text/markdown

# ImpregCalc

**Explicit, mass-conserving recipes for supported-catalyst impregnation.**

[![DGX CI](https://github.com/hdkim99/ImpregCalc/actions/workflows/ci.yml/badge.svg)](https://github.com/hdkim99/ImpregCalc/actions/workflows/ci.yml)
[![macOS](https://github.com/hdkim99/ImpregCalc/actions/workflows/macos.yml/badge.svg)](https://github.com/hdkim99/ImpregCalc/actions/workflows/macos.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10–3.13](https://img.shields.io/badge/Python-3.10--3.13-blue.svg)](pyproject.toml)

![A result-derived ImpregCalc recipe figure](assets/social-preview.png)

ImpregCalc answers a narrow laboratory question: **what mass of each specified
precursor should I weigh, and what nominal liquid volume follows from my explicitly
chosen loading convention?** It keeps elemental-metal, metal-oxide, and precursor
loadings separate; it also keeps final-catalyst and support-relative denominators
separate.

## Why

`15 wt% Co`, `15 wt% Co3O4`, and `15 wt% cobalt nitrate` are different recipes.
Hydrate state and assay/purity change the mass to weigh. A promoter atomic ratio
couples to the main component mass. ImpregCalc records these choices in the input
and in every exported result instead of silently guessing them.

## Install

ImpregCalc is currently source-installable while the first PyPI release is prepared:

```bash
git clone https://github.com/hdkim99/ImpregCalc.git
cd ImpregCalc
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
```

XLSX and publication-figure export are optional:

```bash
python -m pip install ".[xlsx,plot]"
```

The GUI uses Python's Tkinter/ttk. On macOS, use a Python distribution built with
Tcl/Tk support. `python -c "import tkinter"` should succeed.

## 30-second example

The included example specifies 15 wt% elemental Co on a final-formulated-catalyst
basis, a Ru:Co atomic ratio of 0.01, hydrated cobalt nitrate at 98% assay, 8 g of
support, and two arithmetic impregnation cycles:

```bash
impregcalc validate examples/co_ru_iwi.json
impregcalc calculate examples/co_ru_iwi.json --output recipe.md
impregcalc calculate examples/co_ru_iwi.json --output recipe.xlsx
impregcalc calculate examples/co_ru_iwi.json --plot recipe.svg
```

The same core is available from Python:

```python
from impregcalc import calculate_recipe

result = calculate_recipe("examples/co_ru_iwi.json")
print(result.requirements[0].commercial_precursor_mass_g)
print(result.mass_closure_residual_g)
```

## GUI

```bash
python -m impregcalc.gui
# or: impregcalc-gui
```

The main GUI workflow performs a real single-target calculation, displays the full
recipe and assumptions, and exports Markdown, JSON, CSV, or XLSX. Co-impregnation
and promoter-ratio workflows are available through JSON, CLI, and Python API in
0.1.0; the compact GUI does not yet provide multi-target editors.

Tkinter is intentionally used instead of Qt. The core and CLI do not import Tkinter,
matplotlib, PyQt, or PySide. Result figures use the explicit non-interactive `Agg`
backend and are exported as PNG, SVG, or PDF.

## Scientific basis

- Hydrate-dot formulas such as `Co(NO3)2·6H2O`, `Ni(NO3)2·6H2O`,
  `Fe(NO3)3·9H2O`, and `Cu(NO3)2·3H2O` are parsed into integer elemental counts.
- Coupled final-basis and support-relative loadings are solved from one component
  mass balance.
- Oxide targets use the specified oxide stoichiometry; purity scales the commercial
  precursor mass, not the requested active-component mass.
- Promoters may be specified by an elemental atomic ratio to a named main target.
- IWI nominal volume is `dry support mass × supplied pore volume`. It is reported as
  a planning value, not as a universal wetting truth.

Equations, derivations, atomic-weight policy, and peer-reviewed references are in
[`docs/scientific-basis.md`](docs/scientific-basis.md).

## Validation

The test suite covers hand-calculated elemental and oxide loadings, hydrated
precursors, purity, co-impregnation, atomic-ratio promoters, mass closure, nominal
IWI volume, wet impregnation, cycle splits, invalid compositions, exports, CLI/core
import isolation, and GUI calculation/export/close lifecycle. See
[`docs/validation.md`](docs/validation.md).

Real-data validation is **pending**. The repository does not label a synthetic or
manually constructed recipe as a literature-data validation.

## Scope and limitations

ImpregCalc is recipe arithmetic, not a catalyst-structure simulator. Version 0.1.0:

- supports IWI and wet-impregnation liquid planning;
- does not calculate precipitation, sol-gel, hydrothermal, or deposition kinetics;
- does not contain an asserted solubility database or declare a recipe feasible or
  impossible from concentration alone;
- does not predict pore filling, adsorption, drying redistribution, calcination
  loss, phase formation, dispersion, morphology, activity, or safety;
- treats multi-cycle preparation as an arithmetic allocation only;
- rejects charges, variable hydrate states (`xH2O`), fractional stoichiometry, and
  isotopically enriched formulas rather than guessing them.

## Supported platforms

- Python: 3.10–3.13 (3.14 is locally smoke-tested but not yet in the supported range)
- macOS CI: macOS 15 on Apple Silicon and Intel, Python 3.10 and 3.13
- local macOS validation: macOS 27.0, Apple Silicon, Python 3.14.7, Tk 9.0
- scientific CI: Linux ARM64 DGX self-hosted runner
- GUI: Tkinter/ttk; no Qt dependency

See [`docs/macos.md`](docs/macos.md) for the support matrix and diagnostic commands.

## Development

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

Scientific contributions must state the definition, units, assumptions, reference,
and a numerical regression case. See [CONTRIBUTING.md](CONTRIBUTING.md).
