impregcalc 0.1.0__tar.gz

impregcalc-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,27 @@
+name: Bug report
+description: Report reproducible software behavior that is not a scientific-definition question.
+title: "[Bug]: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: "Do not upload confidential or unpublished research data to this public issue."
+  - type: input
+    id: version
+    attributes:
+      label: ImpregCalc version
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Minimal reproduction and full error output
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+

impregcalc-0.1.0/.github/ISSUE_TEMPLATE/dataset.yml

@@ -0,0 +1,27 @@
+name: Real dataset compatibility
+description: Propose a public catalyst-preparation record for validation or compatibility.
+title: "[Dataset]: "
+labels: [dataset]
+body:
+  - type: markdown
+    attributes:
+      value: "Only public, licensed data. Never attach unpublished or confidential laboratory records."
+  - type: input
+    id: doi
+    attributes:
+      label: DOI or stable public URL
+    validations:
+      required: true
+  - type: input
+    id: license
+    attributes:
+      label: Dataset license
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Files, checksum, and proposed validation scope
+    validations:
+      required: true
+

impregcalc-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,19 @@
+name: Feature request
+description: Propose a focused preparation workflow or usability improvement.
+title: "[Feature]: "
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: "Do not include confidential research data. Scientific features need definitions and references."
+  - type: textarea
+    id: workflow
+    attributes:
+      label: Research workflow and current limitation
+    validations:
+      required: true
+  - type: textarea
+    id: science
+    attributes:
+      label: Scientific definition, validity range, and reference
+

impregcalc-0.1.0/.github/ISSUE_TEMPLATE/macos-gui.yml

@@ -0,0 +1,53 @@
+name: macOS or GUI issue
+description: Report installation, Tkinter, window lifecycle, or backend behavior on macOS.
+title: "[macOS/GUI]: "
+labels: [macos, gui]
+body:
+  - type: markdown
+    attributes:
+      value: "Do not post confidential data. Remove paths or environment values that reveal secrets."
+  - type: input
+    id: macos
+    attributes:
+      label: macOS version
+    validations:
+      required: true
+  - type: dropdown
+    id: architecture
+    attributes:
+      label: Architecture
+      options: [Apple Silicon, Intel]
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+    validations:
+      required: true
+  - type: input
+    id: package
+    attributes:
+      label: ImpregCalc version
+    validations:
+      required: true
+  - type: input
+    id: gui
+    attributes:
+      label: Tk/Tcl version
+      description: Run `python -c "import tkinter; print(tkinter.TkVersion)"`.
+    validations:
+      required: true
+  - type: input
+    id: install
+    attributes:
+      label: Installation method
+    validations:
+      required: true
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Full traceback or terminal output
+    validations:
+      required: true
+

impregcalc-0.1.0/.github/ISSUE_TEMPLATE/scientific-result.yml

@@ -0,0 +1,26 @@
+name: Scientific result question
+description: Ask about an equation, convention, unit, assumption, or numerical result.
+title: "[Science]: "
+labels: [scientific-question]
+body:
+  - type: markdown
+    attributes:
+      value: "Use a minimal non-confidential example. Do not post unpublished or proprietary data."
+  - type: textarea
+    id: definition
+    attributes:
+      label: Loading definition, units, and assumptions
+      description: State target quantity and denominator explicitly.
+    validations:
+      required: true
+  - type: textarea
+    id: calculation
+    attributes:
+      label: Input and observed result
+    validations:
+      required: true
+  - type: input
+    id: reference
+    attributes:
+      label: Relevant publication or reference
+

impregcalc-0.1.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+

impregcalc-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,173 @@
+name: DGX CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: impregcalc-dgx-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  required:
+    name: DGX ARM64 / required
+    # Persistent research hardware may only execute trusted owner-authored code.
+    if: >-
+      github.event_name != 'pull_request' ||
+      (github.actor == github.repository_owner &&
+       github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: [self-hosted, Linux, ARM64, dgx-spark]
+    timeout-minutes: 60
+    env:
+      PIP_NO_CACHE_DIR: "1"
+      MPLBACKEND: Agg
+      IMPREGCALC_CI_VENV: impregcalc-ci-${{ github.run_id }}-${{ github.run_attempt }}
+      IMPREGCALC_WHEEL_VENV: impregcalc-wheel-${{ github.run_id }}-${{ github.run_attempt }}
+      IMPREGCALC_CI_OUTPUT: impregcalc-output-${{ github.run_id }}-${{ github.run_attempt }}
+    steps:
+      - name: Check out source
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          clean: true
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - name: Configure validated shared Tk and Xvfb runtime
+        env:
+          IMPREGCALC_GUI_RUNTIME: /opt/catalysttwin-actions/shared-gui-runtime
+        run: |
+          set -eu
+          runtime="$IMPREGCALC_GUI_RUNTIME"
+          bin_dir="$runtime/usr/bin"
+          lib_dir="$runtime/usr/lib/aarch64-linux-gnu"
+          tk_dir="$runtime/usr/share/tcltk/tk8.6"
+          test -d "$bin_dir"
+          test -d "$lib_dir"
+          test -d "$tk_dir"
+          export PATH="$bin_dir:$PATH"
+          export LD_LIBRARY_PATH="$lib_dir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+          export TK_LIBRARY="$tk_dir"
+          printf '%s\n' "$bin_dir" >> "$GITHUB_PATH"
+          {
+            printf 'LD_LIBRARY_PATH=%s\n' "$LD_LIBRARY_PATH"
+            printf 'TK_LIBRARY=%s\n' "$TK_LIBRARY"
+          } >> "$GITHUB_ENV"
+          command -v Xvfb
+          command -v xvfb-run
+          python -c 'import tkinter; print(tkinter.TkVersion)'
+      - name: Create isolated environments
+        run: |
+          python -m venv "$RUNNER_TEMP/$IMPREGCALC_CI_VENV"
+          python -m venv "$RUNNER_TEMP/$IMPREGCALC_WHEEL_VENV"
+          mkdir -p "$RUNNER_TEMP/$IMPREGCALC_CI_OUTPUT"
+      - name: Install project and development dependencies
+        run: |
+          "$RUNNER_TEMP/$IMPREGCALC_CI_VENV/bin/python" -m pip install --upgrade pip
+          "$RUNNER_TEMP/$IMPREGCALC_CI_VENV/bin/python" -m pip install -e ".[dev,plot]"
+          "$RUNNER_TEMP/$IMPREGCALC_CI_VENV/bin/python" -m pip check
+      - name: Check formatting
+        run: |
+          "$RUNNER_TEMP/$IMPREGCALC_CI_VENV/bin/python" -m ruff format --check .
+      - name: Lint
+        run: |
+          "$RUNNER_TEMP/$IMPREGCALC_CI_VENV/bin/python" -m ruff check .
+      - name: Type check
+        run: |
+          "$RUNNER_TEMP/$IMPREGCALC_CI_VENV/bin/python" -m mypy src
+      - name: Unit, scientific, integration, and import-isolation tests
+        run: |
+          "$RUNNER_TEMP/$IMPREGCALC_CI_VENV/bin/python" -m pytest
+      - name: CLI and example workflow
+        run: |
+          py="$RUNNER_TEMP/$IMPREGCALC_CI_VENV/bin/python"
+          "$py" -m impregcalc.cli formula 'Co(NO3)2·6H2O'
+          "$py" -m impregcalc.cli validate examples/co_ru_iwi.json
+          "$py" -m impregcalc.cli calculate examples/co_ru_iwi.json \
+            --output "$RUNNER_TEMP/$IMPREGCALC_CI_OUTPUT/recipe.xlsx" \
+            --plot "$RUNNER_TEMP/$IMPREGCALC_CI_OUTPUT/recipe.svg"
+          test -s "$RUNNER_TEMP/$IMPREGCALC_CI_OUTPUT/recipe.xlsx"
+          test -s "$RUNNER_TEMP/$IMPREGCALC_CI_OUTPUT/recipe.svg"
+      - name: Wired GUI calculation, export, close, and exit
+        run: |
+          xvfb-run -a "$RUNNER_TEMP/$IMPREGCALC_CI_VENV/bin/python" \
+            tests/gui_widget_smoke.py \
+            "$RUNNER_TEMP/$IMPREGCALC_CI_OUTPUT/gui-recipe.md"
+          test -s "$RUNNER_TEMP/$IMPREGCALC_CI_OUTPUT/gui-recipe.md"
+      - name: Build and validate distributions
+        run: |
+          py="$RUNNER_TEMP/$IMPREGCALC_CI_VENV/bin/python"
+          "$py" -m build
+          "$py" -m twine check dist/*
+      - name: Verify clean wheel without GUI or plotting dependencies
+        run: |
+          py="$RUNNER_TEMP/$IMPREGCALC_WHEEL_VENV/bin/python"
+          "$py" -m pip install --upgrade pip
+          "$py" -m pip install dist/*.whl
+          "$py" -m pip check
+          "$py" - <<'PY'
+          import importlib.metadata
+          import platform
+          import sys
+          import impregcalc
+
+          assert platform.machine().lower() in {"aarch64", "arm64"}
+          assert impregcalc.__version__ == importlib.metadata.version("impregcalc")
+          assert "tkinter" not in sys.modules
+          assert "matplotlib" not in sys.modules
+          print(platform.machine(), impregcalc.__version__, impregcalc.__file__)
+          PY
+          "$RUNNER_TEMP/$IMPREGCALC_WHEEL_VENV/bin/impregcalc" --help
+          "$RUNNER_TEMP/$IMPREGCALC_WHEEL_VENV/bin/impregcalc" calculate \
+            examples/co_ru_iwi.json \
+            --output "$RUNNER_TEMP/$IMPREGCALC_CI_OUTPUT/wheel-recipe.md"
+          xvfb-run -a "$py" tests/gui_widget_smoke.py \
+            "$RUNNER_TEMP/$IMPREGCALC_CI_OUTPUT/wheel-gui.md"
+      - name: Clean isolated files and verify checkout
+        if: always()
+        run: |
+          python - <<'PY'
+          import os
+          from pathlib import Path
+          import shutil
+
+          runner_temp = Path(os.environ["RUNNER_TEMP"]).resolve()
+          workspace = Path(os.environ["GITHUB_WORKSPACE"]).resolve()
+          for variable in (
+              "IMPREGCALC_CI_VENV",
+              "IMPREGCALC_WHEEL_VENV",
+              "IMPREGCALC_CI_OUTPUT",
+          ):
+              target = (runner_temp / os.environ[variable]).resolve()
+              if runner_temp not in target.parents:
+                  raise RuntimeError(f"Refusing to clean outside runner temp: {target}")
+              shutil.rmtree(target, ignore_errors=True)
+          for relative in (
+              "build",
+              "dist",
+              ".mypy_cache",
+              ".pytest_cache",
+              ".ruff_cache",
+              ".coverage",
+              "htmlcov",
+          ):
+              target = (workspace / relative).resolve()
+              if workspace not in target.parents:
+                  raise RuntimeError(f"Refusing to clean outside workspace: {target}")
+              if target.is_dir():
+                  shutil.rmtree(target)
+              elif target.exists():
+                  target.unlink()
+          for target in workspace.rglob("__pycache__"):
+              if workspace in target.resolve().parents:
+                  shutil.rmtree(target)
+          PY
+          test -z "$(git status --porcelain)"

impregcalc-0.1.0/.github/workflows/macos.yml

@@ -0,0 +1,95 @@
+name: macOS GUI compatibility
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: impregcalc-macos-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  macos:
+    name: ${{ matrix.label }} / Python ${{ matrix.python }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - label: macos-15
+            python: "3.10"
+            architecture: arm64
+          - label: macos-15-intel
+            python: "3.13"
+            architecture: x86_64
+    runs-on: ${{ matrix.label }}
+    timeout-minutes: 35
+    env:
+      MPLBACKEND: Agg
+    steps:
+      - name: Check out source
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Confirm OS, architecture, Tk, and absence of Qt
+        env:
+          EXPECTED_ARCH: ${{ matrix.architecture }}
+        run: |
+          test "$(uname -m)" = "$EXPECTED_ARCH"
+          sw_vers
+          python -c 'import platform, tkinter; print(platform.python_version(), tkinter.TkVersion)'
+          python - <<'PY'
+          import importlib.util
+          for name in ("PyQt5", "PyQt6", "PySide2", "PySide6"):
+              assert importlib.util.find_spec(name) is None, name
+          PY
+      - name: Install source in a virtual environment
+        run: |
+          python -m venv "$RUNNER_TEMP/impregcalc-macos"
+          "$RUNNER_TEMP/impregcalc-macos/bin/python" -m pip install --upgrade pip
+          "$RUNNER_TEMP/impregcalc-macos/bin/python" -m pip install -e ".[dev,plot]"
+          "$RUNNER_TEMP/impregcalc-macos/bin/python" -m pip check
+      - name: Scientific, CLI, and GUI-import tests
+        run: |
+          py="$RUNNER_TEMP/impregcalc-macos/bin/python"
+          "$py" -m pytest tests/unit tests/integration tests/gui
+          "$py" -m impregcalc.cli validate examples/co_ru_iwi.json
+      - name: Real Tk window workflow and normal process exit
+        run: |
+          py="$RUNNER_TEMP/impregcalc-macos/bin/python"
+          "$py" tests/gui_widget_smoke.py "$RUNNER_TEMP/macos-gui-recipe.md"
+          test -s "$RUNNER_TEMP/macos-gui-recipe.md"
+      - name: Explicit Agg plot backend and export
+        run: |
+          py="$RUNNER_TEMP/impregcalc-macos/bin/python"
+          "$py" -m impregcalc.cli calculate examples/co_ru_iwi.json \
+            --output "$RUNNER_TEMP/macos-recipe.xlsx" \
+            --plot "$RUNNER_TEMP/macos-recipe.pdf"
+          "$py" -c 'import matplotlib; assert "agg" in matplotlib.get_backend().lower()'
+          test -s "$RUNNER_TEMP/macos-recipe.xlsx"
+          test -s "$RUNNER_TEMP/macos-recipe.pdf"
+      - name: Build and clean-wheel installation
+        run: |
+          py="$RUNNER_TEMP/impregcalc-macos/bin/python"
+          "$py" -m build
+          "$py" -m twine check dist/*
+          python -m venv "$RUNNER_TEMP/impregcalc-wheel"
+          wheel_py="$RUNNER_TEMP/impregcalc-wheel/bin/python"
+          "$wheel_py" -m pip install dist/*.whl
+          "$wheel_py" -m pip check
+          "$wheel_py" -c 'import impregcalc, sys; assert "tkinter" not in sys.modules'
+          "$RUNNER_TEMP/impregcalc-wheel/bin/impregcalc" calculate \
+            examples/co_ru_iwi.json --output "$RUNNER_TEMP/wheel-recipe.md"
+          "$wheel_py" tests/gui_widget_smoke.py "$RUNNER_TEMP/wheel-gui.md"
+          test -s "$RUNNER_TEMP/wheel-recipe.md"
+          test -s "$RUNNER_TEMP/wheel-gui.md"
+

impregcalc-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,69 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    if: github.event.release.prerelease == false
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - name: Check out tagged source
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.12"
+      - name: Build and verify tagged version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+          python -m venv /tmp/impregcalc-release-wheel
+          /tmp/impregcalc-release-wheel/bin/python -m pip install dist/*.whl
+          /tmp/impregcalc-release-wheel/bin/python -m pip check
+          /tmp/impregcalc-release-wheel/bin/python - <<'PY'
+          import importlib.metadata
+          import os
+          import sys
+          import impregcalc
+
+          expected = os.environ["RELEASE_TAG"].removeprefix("v")
+          assert impregcalc.__version__ == expected
+          assert importlib.metadata.version("impregcalc") == expected
+          assert "tkinter" not in sys.modules
+          PY
+          /tmp/impregcalc-release-wheel/bin/impregcalc --help
+          /tmp/impregcalc-release-wheel/bin/impregcalc calculate \
+            examples/co_ru_iwi.json --output /tmp/impregcalc-release-example.md
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/impregcalc
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+

impregcalc-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+build/
+dist/
+*.egg-info/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+

impregcalc-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes will be recorded here. ImpregCalc follows semantic versioning
+while scientific definition corrections may appear in patch releases.
+
+## 0.1.0 — unreleased
+
+- Initial elemental-metal, metal-oxide, and precursor loading engine.
+- Final-catalyst and support-relative mass-balance conventions.
+- Hydrate-dot formula parser and precursor assay correction.
+- Co-impregnation, atomic-ratio promoter, IWI/wet liquid planning, and cycle splits.
+- Python API, CLI, Tkinter GUI, JSON/Markdown/CSV/XLSX and figure export.
+
+The conditions for 1.0.0 are not met. They require external-user experience,
+definition-stable workflows, and suitable public experimental validation.
+

impregcalc-0.1.0/CITATION.cff

@@ -0,0 +1,16 @@
+cff-version: 1.2.0
+message: "If you use ImpregCalc, please cite this software and the scientific references documented in the repository."
+title: "ImpregCalc"
+type: software
+version: 0.1.0
+authors:
+  - family-names: Kim
+    given-names: Hyun Dong
+repository-code: "https://github.com/hdkim99/ImpregCalc"
+url: "https://github.com/hdkim99/ImpregCalc"
+license: MIT
+keywords:
+  - catalysis
+  - catalyst preparation
+  - impregnation
+  - stoichiometry

impregcalc-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing
+
+Thank you for improving ImpregCalc. Do not put unpublished, proprietary,
+export-controlled, or otherwise confidential research data in a public issue or pull
+request.
+
+## Scientific changes
+
+Every scientific-core change must state:
+
+1. the equation or definition and the convention it implements;
+2. every input/output unit and loading denominator;
+3. assumptions, validity range, and unsupported cases;
+4. an original publication, established textbook, or peer-reviewed review when the
+   change is not a direct dimensional/stoichiometric derivation;
+5. an independent numerical validation (hand calculation, literature benchmark, or
+   controlled synthetic benchmark);
+6. boundary and invalid-input behavior plus a regression test.
+
+Do not add an undocumented coefficient, threshold, uncertainty, or confidence claim.
+Do not infer model validity from R² alone.
+
+## GUI and plotting changes
+
+Record the supported platform, dependency change, backend impact, macOS smoke result,
+and proof that CLI/core imports remain GUI-independent. Do not add Qt without a
+documented need, one binding only, clean-environment macOS lifecycle validation, and
+explicit backend checks.
+
+## Local checks
+
+```bash
+python -m pip install -e ".[dev,plot]"
+ruff format --check .
+ruff check .
+mypy src
+pytest
+python -m build
+twine check dist/*
+```
+

impregcalc-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+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.
+