mfcblend 0.1.0__tar.gz

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

@@ -0,0 +1,27 @@
+name: Bug report
+description: Report reproducible incorrect behavior unrelated to scientific interpretation.
+title: "[Bug]: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: Do not upload confidential, proprietary, export-controlled, or unpublished research data.
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Observed and expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Minimal reproduction
+      description: Redact sensitive cylinder and facility information.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: MFCBlend and Python versions
+    validations:
+      required: true

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

@@ -0,0 +1,26 @@
+name: Real dataset compatibility
+description: Propose or report a public catalytic-reactor feed dataset.
+title: "[Dataset]: "
+labels: [dataset]
+body:
+  - type: markdown
+    attributes:
+      value: Only link data you are authorized to share. Do not upload confidential or unpublished data.
+  - type: input
+    id: identifier
+    attributes:
+      label: DOI or stable identifier
+    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

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

@@ -0,0 +1,20 @@
+name: Feature request
+description: Propose a focused gas-feed planning workflow.
+title: "[Feature]: "
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: Do not include confidential facility or research information.
+  - type: textarea
+    id: workflow
+    attributes:
+      label: Research workflow and decision supported
+    validations:
+      required: true
+  - type: textarea
+    id: science
+    attributes:
+      label: Definitions, units, assumptions, and references
+    validations:
+      required: true

mfcblend-0.1.0/.github/ISSUE_TEMPLATE/macos.yml

@@ -0,0 +1,52 @@
+name: macOS or GUI issue
+description: Report installation, Tkinter, backend, lifecycle, or export problems on macOS.
+title: "[macOS/GUI]: "
+labels: [macos, gui]
+body:
+  - type: markdown
+    attributes:
+      value: Do not upload confidential data. Include the full traceback after removing sensitive paths.
+  - 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: MFCBlend version
+    validations:
+      required: true
+  - type: input
+    id: framework
+    attributes:
+      label: Tk/Tcl version
+    validations:
+      required: true
+  - type: textarea
+    id: install
+    attributes:
+      label: Installation method and command
+    validations:
+      required: true
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Full traceback
+      render: shell
+    validations:
+      required: true

mfcblend-0.1.0/.github/ISSUE_TEMPLATE/scientific.yml

@@ -0,0 +1,26 @@
+name: Scientific result question
+description: Ask about an equation, convention, unit basis, or calculated result.
+title: "[Scientific result]: "
+labels: [scientific-question]
+body:
+  - type: markdown
+    attributes:
+      value: Do not upload unpublished or confidential research data. MFCBlend is not a process-safety assessment.
+  - type: textarea
+    id: definition
+    attributes:
+      label: Equation, definition, and unit basis in question
+    validations:
+      required: true
+  - type: textarea
+    id: reference
+    attributes:
+      label: Authoritative reference or hand calculation
+    validations:
+      required: true
+  - type: textarea
+    id: minimal
+    attributes:
+      label: Minimal non-confidential input and result
+    validations:
+      required: true

mfcblend-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: monthly
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: monthly

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

@@ -0,0 +1,140 @@
+name: DGX CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: mfcblend-dgx-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  required:
+    name: DGX / required
+    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"
+      PYTHONDONTWRITEBYTECODE: "1"
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          clean: true
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Configure validated shared Tk and Xvfb runtime
+        env:
+          MFCBLEND_GUI_RUNTIME: /opt/catalysttwin-actions/shared-gui-runtime
+        run: |
+          set -eu
+          test -x "$MFCBLEND_GUI_RUNTIME/usr/bin/Xvfb"
+          test -x "$MFCBLEND_GUI_RUNTIME/usr/bin/xvfb-run"
+          test -d "$MFCBLEND_GUI_RUNTIME/usr/lib/aarch64-linux-gnu"
+          test -d "$MFCBLEND_GUI_RUNTIME/usr/share/tcltk/tk8.6"
+          echo "$MFCBLEND_GUI_RUNTIME/usr/bin" >> "$GITHUB_PATH"
+          {
+            echo "LD_LIBRARY_PATH=$MFCBLEND_GUI_RUNTIME/usr/lib/aarch64-linux-gnu${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+            echo "TK_LIBRARY=$MFCBLEND_GUI_RUNTIME/usr/share/tcltk/tk8.6"
+          } >> "$GITHUB_ENV"
+      - name: Create isolated job environments
+        run: |
+          export MFCBLEND_CI_ROOT="$RUNNER_TEMP/mfcblend-ci-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+          echo "MFCBLEND_CI_ROOT=$MFCBLEND_CI_ROOT" >> "$GITHUB_ENV"
+          python - <<'PY'
+          import os
+          from pathlib import Path
+
+          root = Path(os.environ["MFCBLEND_CI_ROOT"]).resolve()
+          runner_temp = Path(os.environ["RUNNER_TEMP"]).resolve()
+          if root.parent != runner_temp or not root.name.startswith("mfcblend-ci-"):
+              raise RuntimeError(f"Unsafe CI root: {root}")
+          root.mkdir()
+          PY
+          python -m venv "$MFCBLEND_CI_ROOT/dev-venv"
+          python -m venv "$MFCBLEND_CI_ROOT/wheel-venv"
+      - name: Install development environment
+        run: |
+          "$MFCBLEND_CI_ROOT/dev-venv/bin/python" -m pip install --upgrade pip
+          "$MFCBLEND_CI_ROOT/dev-venv/bin/python" -m pip install -e ".[dev]"
+          "$MFCBLEND_CI_ROOT/dev-venv/bin/python" -m pip check
+          xvfb-run -a "$MFCBLEND_CI_ROOT/dev-venv/bin/python" -c 'import tkinter; print(tkinter.TkVersion)'
+      - name: Ruff format
+        run: >-
+          "$MFCBLEND_CI_ROOT/dev-venv/bin/python" -m ruff format --check .
+      - name: Ruff lint
+        run: >-
+          "$MFCBLEND_CI_ROOT/dev-venv/bin/python" -m ruff check .
+      - name: Strict type check
+        run: >-
+          "$MFCBLEND_CI_ROOT/dev-venv/bin/python" -m mypy src
+      - name: Unit, integration, and scientific regression tests
+        run: >-
+          "$MFCBLEND_CI_ROOT/dev-venv/bin/python" -m pytest
+      - name: CLI and example workflow smoke
+        run: |
+          "$MFCBLEND_CI_ROOT/dev-venv/bin/mfcblend" --help
+          "$MFCBLEND_CI_ROOT/dev-venv/bin/mfcblend" validate examples/co2_hydrogen_system.json
+          "$MFCBLEND_CI_ROOT/dev-venv/bin/mfcblend" inverse \
+            examples/co2_hydrogen_system.json examples/target_5co2_20h2.json \
+            --output "$MFCBLEND_CI_ROOT/example.json"
+          test -s "$MFCBLEND_CI_ROOT/example.json"
+      - name: Real Tk widget workflow and exit smoke
+        run: |
+          xvfb-run -a "$MFCBLEND_CI_ROOT/dev-venv/bin/python" tests/gui_widget_smoke.py \
+            examples/co2_hydrogen_system.json examples/target_5co2_20h2.json \
+            "$MFCBLEND_CI_ROOT/gui.json"
+          test -s "$MFCBLEND_CI_ROOT/gui.json"
+      - name: Build and validate distributions
+        run: |
+          "$MFCBLEND_CI_ROOT/dev-venv/bin/python" -m build --outdir "$MFCBLEND_CI_ROOT/dist" .
+          "$MFCBLEND_CI_ROOT/dev-venv/bin/python" -m twine check "$MFCBLEND_CI_ROOT"/dist/*
+      - name: Clean wheel installation on ARM64
+        run: |
+          "$MFCBLEND_CI_ROOT/wheel-venv/bin/python" -m pip install --upgrade pip
+          "$MFCBLEND_CI_ROOT/wheel-venv/bin/python" -m pip install "$MFCBLEND_CI_ROOT"/dist/*.whl
+          "$MFCBLEND_CI_ROOT/wheel-venv/bin/python" -m pip check
+          "$MFCBLEND_CI_ROOT/wheel-venv/bin/python" - <<'PY'
+          import platform
+          import sys
+          import mfcblend
+          import mfcblend.cli
+
+          assert platform.machine().lower() in {"arm64", "aarch64"}
+          assert mfcblend.__version__ == "0.1.0"
+          assert "tkinter" not in sys.modules
+          assert "matplotlib.pyplot" not in sys.modules
+          PY
+          "$MFCBLEND_CI_ROOT/wheel-venv/bin/mfcblend" forward \
+            examples/co2_hydrogen_system.json examples/setpoints_5co2_20h2.json \
+            --output "$MFCBLEND_CI_ROOT/wheel.csv"
+          test -s "$MFCBLEND_CI_ROOT/wheel.csv"
+      - name: Clean isolated job environment
+        if: always()
+        run: |
+          python - <<'PY'
+          import os
+          import shutil
+          from pathlib import Path
+
+          root = Path(os.environ["MFCBLEND_CI_ROOT"]).resolve()
+          runner_temp = Path(os.environ["RUNNER_TEMP"]).resolve()
+          if root.parent != runner_temp or not root.name.startswith("mfcblend-ci-"):
+              raise RuntimeError(f"Unsafe cleanup target: {root}")
+          shutil.rmtree(root, ignore_errors=True)
+          PY
+          test -z "$(git status --porcelain)"

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

@@ -0,0 +1,96 @@
+name: macOS GUI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: mfcblend-macos-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  macos-gui:
+    name: macOS / ${{ matrix.arch }} / Python ${{ matrix.python-version }} / Tk
+    if: >-
+      github.event_name != 'pull_request' ||
+      (github.actor == github.repository_owner &&
+       github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-15
+            arch: arm64
+            python-version: "3.10"
+          - os: macos-15
+            arch: arm64
+            python-version: "3.14"
+          - os: macos-15-intel
+            arch: x86_64
+            python-version: "3.13"
+    env:
+      PIP_NO_CACHE_DIR: "1"
+      MPLBACKEND: Agg
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Record native platform and Tk runtime
+        run: |
+          sw_vers
+          uname -m
+          test "$(uname -m)" = "${{ matrix.arch }}"
+          python -VV
+          python -c 'import tkinter; print("Tk", tkinter.TkVersion)'
+      - name: Install source with GUI and development dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev,gui]"
+          python -m pip check
+      - name: Scientific and import-isolation tests
+        run: |
+          python -m pytest tests/unit tests/integration tests/macos
+          python -c "import sys, mfcblend.cli; assert 'tkinter' not in sys.modules; assert 'PySide6' not in sys.modules; assert 'PyQt6' not in sys.modules"
+      - name: CLI smoke without GUI initialization
+        run: |
+          mfcblend validate examples/co2_hydrogen_system.json
+          mfcblend inverse examples/co2_hydrogen_system.json \
+            examples/target_5co2_20h2.json --output /tmp/mfcblend-macos-cli.json
+          test -s /tmp/mfcblend-macos-cli.json
+      - name: Native Tk window, workflow, export, and clean exit
+        run: |
+          python -m mfcblend.gui --smoke-test \
+            --system examples/co2_hydrogen_system.json \
+            --values examples/target_5co2_20h2.json \
+            --mode inverse --output /tmp/mfcblend-macos-gui.json
+          test -s /tmp/mfcblend-macos-gui.json
+      - name: Explicit noninteractive Matplotlib backend smoke
+        run: |
+          python scripts/generate_preview.py
+          python -c "from PIL import Image; image=Image.open('docs/assets/social-preview.png'); assert image.size == (1280, 640), image.size"
+      - name: Build and clean wheel install
+        run: |
+          python -m build --outdir /tmp/mfcblend-dist .
+          python -m twine check /tmp/mfcblend-dist/*
+          python -m venv /tmp/mfcblend-clean-wheel
+          /tmp/mfcblend-clean-wheel/bin/python -m pip install /tmp/mfcblend-dist/*.whl matplotlib
+          /tmp/mfcblend-clean-wheel/bin/python -m pip check
+          /tmp/mfcblend-clean-wheel/bin/mfcblend --version
+          /tmp/mfcblend-clean-wheel/bin/python -m mfcblend.gui --smoke-test \
+            --system examples/co2_hydrogen_system.json \
+            --values examples/target_5co2_20h2.json \
+            --mode inverse --output /tmp/mfcblend-clean-wheel-gui.json
+          test -s /tmp/mfcblend-clean-wheel-gui.json

mfcblend-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Release package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    if: github.event.release.prerelease == false
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Build and validate
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Clean wheel CLI smoke
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python -m venv /tmp/mfcblend-release
+          /tmp/mfcblend-release/bin/python -m pip install dist/*.whl
+          /tmp/mfcblend-release/bin/python -m pip check
+          /tmp/mfcblend-release/bin/python - <<'PY'
+          import os
+          import mfcblend
+
+          expected = os.environ["RELEASE_TAG"].removeprefix("v")
+          assert mfcblend.__version__ == expected
+          PY
+          /tmp/mfcblend-release/bin/mfcblend inverse \
+            examples/co2_hydrogen_system.json examples/target_5co2_20h2.json \
+            --output /tmp/mfcblend-release-result.json
+      - 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-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mfcblend
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish with PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

mfcblend-0.1.0/.gitignore

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

mfcblend-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes will be documented here. Versioning follows semantic
+versioning while the scientific interface remains in 0.x development.
+
+## [Unreleased] — planned 0.1.0
+
+- Initial forward and constrained inverse gas-feed planning core.
+- Explicit MFC ranges, turndown, reference conditions, and infeasibility status.
+- Python API, CLI, Tkinter GUI, JSON/CSV export, and result plotting.
+- DGX and macOS verification workflows and scientific regression tests.

mfcblend-0.1.0/CITATION.cff

@@ -0,0 +1,16 @@
+cff-version: 1.2.0
+message: "If you use MFCBlend in research, please cite the software and version used."
+title: "MFCBlend"
+type: software
+authors:
+  - family-names: "Kim"
+    given-names: "Hyun Dong"
+repository-code: "https://github.com/hdkim99/MFCBlend"
+url: "https://github.com/hdkim99/MFCBlend"
+version: 0.1.0
+license: MIT
+keywords:
+  - catalysis
+  - gas mixtures
+  - mass flow controller
+  - reaction engineering

mfcblend-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Contributions are welcome. Do not post unpublished, export-controlled,
+proprietary, or confidential experimental data in a public issue.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+ruff format --check .
+ruff check .
+mypy src
+pytest
+python -m build
+twine check dist/*
+```
+
+A scientific-core change must state the equation or definition, units and basis,
+assumptions, validity boundary, authoritative reference or derivation, numerical
+validation, and regression test. Do not add an empirical threshold, coefficient,
+uncertainty, or confidence interval without a verifiable source and applicability
+range.
+
+A GUI change must additionally document platform support, dependency/backend
+impact, macOS smoke evidence, and CLI/core import isolation. Do not move formulas
+into the GUI or initialize Tk/Matplotlib from a scientific-core import.
+
+External fork pull requests do not execute on the persistent DGX runner. A
+maintainer must review untrusted code before trusted-hardware execution.

mfcblend-0.1.0/LICENSE

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