ftproductlab 0.1.0__tar.gz

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

@@ -0,0 +1,20 @@
+name: Bug report
+description: Report reproducible software behavior that appears incorrect.
+title: "[Bug]: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: Do not upload unpublished, confidential, proprietary, or identifying research data.
+  - type: textarea
+    id: description
+    attributes: {label: What happened?, description: Include the command and expected behavior.}
+    validations: {required: true}
+  - type: input
+    id: version
+    attributes: {label: FTProductLab version}
+    validations: {required: true}
+  - type: textarea
+    id: reproducer
+    attributes: {label: Minimal public or synthetic reproducer}
+    validations: {required: true}

ftproductlab-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/hdkim99/FTProductLab/security/advisories/new
+    about: Privately report a security vulnerability.

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

@@ -0,0 +1,24 @@
+name: Real dataset compatibility
+description: Propose a public dataset or report a documented import limitation.
+title: "[Dataset]: "
+labels: [dataset]
+body:
+  - type: markdown
+    attributes:
+      value: Only public, redistributable data may be linked. Do not attach confidential research data.
+  - type: input
+    id: doi
+    attributes: {label: DOI or stable repository URL}
+    validations: {required: true}
+  - type: input
+    id: license
+    attributes: {label: Dataset license}
+    validations: {required: true}
+  - type: textarea
+    id: schema
+    attributes: {label: Files, checksum, and column definitions}
+    validations: {required: true}
+  - type: textarea
+    id: scope
+    attributes: {label: Proposed validation scope}
+    validations: {required: true}

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

@@ -0,0 +1,17 @@
+name: Feature request
+description: Propose one evidence-backed research workflow.
+title: "[Feature]: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: workflow
+    attributes: {label: Researcher workflow and decision supported}
+    validations: {required: true}
+  - type: textarea
+    id: science
+    attributes: {label: Scientific definition, assumptions, and references}
+    validations: {required: true}
+  - type: textarea
+    id: exclusions
+    attributes: {label: Explicit non-goals and validity limits}
+    validations: {required: true}

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

@@ -0,0 +1,36 @@
+name: macOS/GUI issue
+description: Report installation, Tk/backend, window lifecycle, or export failures.
+title: "[macOS GUI]: "
+labels: [macos, gui]
+body:
+  - type: markdown
+    attributes:
+      value: Remove secrets and confidential paths/data before posting the full traceback.
+  - 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: FTProductLab version}
+    validations: {required: true}
+  - type: input
+    id: framework
+    attributes: {label: Tk/Tcl version, description: Run `python -c "import tkinter; print(tkinter.TkVersion)"`.}
+    validations: {required: true}
+  - type: input
+    id: install
+    attributes: {label: Installation command or method}
+    validations: {required: true}
+  - type: textarea
+    id: traceback
+    attributes: {label: Full sanitized traceback}
+    validations: {required: true}

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

@@ -0,0 +1,20 @@
+name: Scientific result question
+description: Ask about an equation, basis, fit convention, or numerical result.
+title: "[Scientific result]: "
+labels: [scientific-result]
+body:
+  - type: markdown
+    attributes:
+      value: Do not post confidential or unpublished datasets. Reduce the case to synthetic or public data.
+  - type: textarea
+    id: definition
+    attributes: {label: Equation or definition, description: State input basis, fit range, and weighting.}
+    validations: {required: true}
+  - type: textarea
+    id: expected
+    attributes: {label: Independent calculation or reference, description: Provide DOI and exact convention where possible.}
+    validations: {required: true}
+  - type: input
+    id: version
+    attributes: {label: FTProductLab version}
+    validations: {required: true}

ftproductlab-0.1.0/.github/actionlint.yaml

@@ -0,0 +1,3 @@
+self-hosted-runner:
+  labels:
+    - dgx-spark

ftproductlab-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

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

@@ -0,0 +1,98 @@
+name: DGX CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ftproductlab-dgx-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  required:
+    name: DGX / required
+    # Persistent research hardware never executes an external fork's 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: 45
+    env:
+      PIP_NO_CACHE_DIR: "1"
+      MPLBACKEND: Agg
+    steps:
+      - name: Check out source
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          clean: true
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.14"
+      - name: Configure established Tk and Xvfb runtime
+        env:
+          FTPRODUCTLAB_GUI_RUNTIME: /opt/catalysttwin-actions/shared-gui-runtime
+        run: |
+          set -eu
+          runtime="$FTPRODUCTLAB_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"
+          printf '%s\n' "$bin_dir" >> "$GITHUB_PATH"
+          {
+            printf 'LD_LIBRARY_PATH=%s\n' "$lib_dir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+            printf 'TK_LIBRARY=%s\n' "$tk_dir"
+          } >> "$GITHUB_ENV"
+          export PATH="$bin_dir:$PATH"
+          export LD_LIBRARY_PATH="$lib_dir${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+          export TK_LIBRARY="$tk_dir"
+          command -v Xvfb
+          command -v xvfb-run
+          python -c 'import tkinter; print(tkinter.TkVersion)'
+      - name: Create isolated environment
+        run: python -m venv .ci-venv
+      - name: Install project
+        run: |
+          .ci-venv/bin/python -m pip install --upgrade pip
+          .ci-venv/bin/python -m pip install -e ".[dev]"
+      - name: Format check
+        run: .ci-venv/bin/python -m ruff format --check .
+      - name: Lint
+        run: .ci-venv/bin/python -m ruff check .
+      - name: Strict type check
+        run: .ci-venv/bin/python -m mypy
+      - name: Scientific and integration tests
+        run: .ci-venv/bin/python -m pytest tests/unit tests/integration
+      - name: GUI workflow under Xvfb
+        run: xvfb-run -a .ci-venv/bin/python -m pytest tests/gui
+      - name: CLI and example smoke
+        run: |
+          .ci-venv/bin/ftproductlab validate
+          .ci-venv/bin/python scripts/run_example.py --output "$RUNNER_TEMP/ftproductlab-example"
+      - name: Build and metadata check
+        run: |
+          .ci-venv/bin/python -m build
+          .ci-venv/bin/python -m twine check dist/*
+      - name: Clean-wheel install and GUI-free CLI
+        run: |
+          python -m venv "$RUNNER_TEMP/ftproductlab-wheel"
+          "$RUNNER_TEMP/ftproductlab-wheel/bin/python" -m pip install --no-cache-dir dist/*.whl
+          "$RUNNER_TEMP/ftproductlab-wheel/bin/python" -m pip check
+          "$RUNNER_TEMP/ftproductlab-wheel/bin/ftproductlab" validate
+          "$RUNNER_TEMP/ftproductlab-wheel/bin/python" -c "import ftproductlab,sys; assert 'tkinter' not in sys.modules; assert 'matplotlib' not in sys.modules"
+      - name: Dependency audit
+        run: .ci-venv/bin/python -m pip_audit
+      - name: Remove isolated environment
+        if: always()
+        run: rm -rf .ci-venv

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

@@ -0,0 +1,74 @@
+name: macOS GUI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ftproductlab-macos-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  gui:
+    name: macOS 15 / ${{ matrix.architecture }} / Python ${{ matrix.python }}
+    # The hosted runner has no repository secrets; still reject external fork execution.
+    if: >-
+      github.event_name != 'pull_request' ||
+      (github.actor == github.repository_owner &&
+       github.event.pull_request.head.repo.full_name == github.repository)
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: macos-15
+            architecture: arm64
+            python: "3.10"
+          - runner: macos-15
+            architecture: arm64
+            python: "3.14"
+          - runner: macos-15-intel
+            architecture: x86_64
+            # setup-python 3.10 on this image links Tk 8.5 headers to the
+            # image's Tk 8.6 runtime. Python 3.13 is the verified Intel pair.
+            python: "3.13"
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 30
+    env:
+      MPLBACKEND: Agg
+    steps:
+      - name: Check out source
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Record platform and Tk
+        run: |
+          python -c "import platform; print(platform.platform(), platform.machine())"
+          python -c "import tkinter; print('Tk', tkinter.TkVersion)"
+      - name: Install source with GUI extras
+        run: python -m pip install -e ".[gui,dev]"
+      - name: Core, CLI, and import-isolation tests
+        run: |
+          python -m pytest tests/unit tests/integration/test_cli.py tests/integration/test_import_isolation.py
+          ftproductlab validate
+      - name: Real window workflow, export, close, and exit
+        run: python -m pytest tests/gui tests/macos
+      - name: Build and clean wheel
+        run: |
+          python -m build
+          python -m venv "$RUNNER_TEMP/wheel-env"
+          "$RUNNER_TEMP/wheel-env/bin/python" -m pip install "ftproductlab[gui] @ file://$PWD/$(ls dist/*.whl)"
+          "$RUNNER_TEMP/wheel-env/bin/python" -m pip check
+          "$RUNNER_TEMP/wheel-env/bin/ftproductlab" validate
+      - name: Clean-wheel GUI lifecycle
+        run: |
+          "$RUNNER_TEMP/wheel-env/bin/python" -c "import tkinter as tk; from ftproductlab.gui.app import MainWindow; root=tk.Tk(); window=MainWindow(root); root.update(); assert window.winfo_exists(); root.destroy()"

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

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.14"
+      - name: Build distributions
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python -m pip install build==1.5.0 twine==6.2.0
+          version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "$RELEASE_TAG" = "v$version"
+          python -m build
+          python -m twine check dist/*
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: pypi-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ftproductlab
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: pypi-distributions
+          path: dist/
+      - name: Publish with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

ftproductlab-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+ftproductlab-output/

ftproductlab-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+- Initial species-preserving carbon-number aggregation.
+- Explicit molar, mass, and carbon input bases.
+- User-ranged single-alpha ASF fitting with uniform or amount weighting.
+- C1/C2 and per-carbon residual diagnostics, user-defined cuts, and O/P states.
+- Shared Python API, CLI, Tkinter GUI, deterministic tables, and PNG/SVG/PDF figures.

ftproductlab-0.1.0/CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+message: "If you use FTProductLab, please cite the software and the scientific sources for the ASF convention."
+title: "FTProductLab"
+type: software
+version: 0.1.0
+date-released: 2026-08-23
+authors:
+  - family-names: "Kim"
+    given-names: "Peter"
+repository-code: "https://github.com/hdkim99/FTProductLab"
+url: "https://github.com/hdkim99/FTProductLab"
+license: BSD-3-Clause
+keywords:
+  - Fischer-Tropsch
+  - Anderson-Schulz-Flory
+  - catalysis
+  - product distribution
+references:
+  - type: article
+    title: "Molecular Size Distribution in Linear Condensation Polymers"
+    authors:
+      - family-names: "Flory"
+        given-names: "Paul J."
+    journal: "Journal of the American Chemical Society"
+    year: 1936
+    doi: "10.1021/ja01301a016"

ftproductlab-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+Use a focused issue or pull request and do not upload unpublished, confidential, export-
+controlled, or personally identifiable research data to a public issue.
+
+Scientific-core changes must state the equation or definition, units/basis, assumptions,
+validity range, authoritative reference, independent numerical validation, and regression
+test. A higher R² alone does not justify a new model. Do not add coefficients or thresholds
+without a traceable source or derivation.
+
+GUI changes must additionally record supported platforms, dependency changes, backend
+impact, macOS smoke results, and CLI/core import isolation. PyQt and PySide must never be
+mixed; introducing Qt requires a separate architecture decision and the compatibility tests
+listed in the issue template. Tk code must create one root and must not update widgets from a
+background thread.
+
+Run before submitting:
+
+```bash
+python -m ruff format --check .
+python -m ruff check .
+python -m mypy
+python -m pytest
+python -m build
+python -m twine check dist/*
+```

ftproductlab-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Peter Kim
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ftproductlab-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: ftproductlab
+Version: 0.1.0
+Summary: Reproducible Fischer-Tropsch product-distribution and ASF analysis
+Project-URL: Homepage, https://github.com/hdkim99/FTProductLab
+Project-URL: Documentation, https://github.com/hdkim99/FTProductLab#readme
+Project-URL: Issues, https://github.com/hdkim99/FTProductLab/issues
+Project-URL: Repository, https://github.com/hdkim99/FTProductLab
+Author: Peter Kim
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: anderson-schulz-flory,catalysis,fischer-tropsch,product-distribution
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: <3.15,>=3.10
+Provides-Extra: dev
+Requires-Dist: build==1.5.0; extra == 'dev'
+Requires-Dist: matplotlib<4,>=3.8; extra == 'dev'
+Requires-Dist: mypy<2,>=1.15; extra == 'dev'
+Requires-Dist: pip-audit<3,>=2.9; extra == 'dev'
+Requires-Dist: pytest<10,>=8.3; extra == 'dev'
+Requires-Dist: ruff<0.18,>=0.11; extra == 'dev'
+Requires-Dist: twine<7,>=6.1; extra == 'dev'
+Provides-Extra: gui
+Requires-Dist: matplotlib<4,>=3.8; extra == 'gui'
+Provides-Extra: plot
+Requires-Dist: matplotlib<4,>=3.8; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# FTProductLab
+
+[![DGX CI](https://github.com/hdkim99/FTProductLab/actions/workflows/ci.yml/badge.svg)](https://github.com/hdkim99/FTProductLab/actions/workflows/ci.yml)
+[![macOS GUI](https://github.com/hdkim99/FTProductLab/actions/workflows/macos.yml/badge.svg)](https://github.com/hdkim99/FTProductLab/actions/workflows/macos.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab)](https://www.python.org/)
+
+Reproducible Fischer–Tropsch carbon-number distribution, single-alpha ASF, product-cut,
+deviation, and olefin/paraffin analysis.
+
+![Observed FT product distribution, fitted ASF line, and residuals](assets/social-preview.png)
+
+## Why
+
+FTProductLab keeps carbon-number definitions, input basis, fit range, regression weighting,
+and truncation conventions visible. It does not turn a high R² into a claim that an ideal ASF
+mechanism is valid. Species remain category-resolved while totals are aggregated by carbon
+number for analysis.
+
+## Install
+
+```bash
+python -m pip install ftproductlab
+```
+
+The base package contains the scientific core and CLI and has no GUI, Qt, or plotting
+dependency. For figures and the Tk interface:
+
+```bash
+python -m pip install "ftproductlab[gui]"
+```
+
+Tk itself is supplied by Python, not PyPI. Homebrew Python users may need the matching
+formula, for example `brew install python-tk@3.14`.
+
+## 30-second example
+
+```bash
+ftproductlab analyze examples/sample_distribution.csv \
+  --basis molar --fit-min 5 --fit-max 20 \
+  --cut C1:1:1 --cut C2-C4:2:4 --cut C5+:5 \
+  --output ftproductlab-output --plots
+```
+
+The command writes a machine-readable `analysis.json`, point/cut/O-P CSV tables, and
+PNG/SVG/PDF figures. Run the built-in hand-checkable regression with:
+
+```bash
+ftproductlab validate
+```
+
+Python uses the same core:
+
+```python
+from ftproductlab import FitConfig, InputBasis, ProductRecord, analyze_distribution
+
+records = [ProductRecord(n, 0.2 * 0.8 ** (n - 1)) for n in range(1, 21)]
+result = analyze_distribution(records, InputBasis.MOLAR, FitConfig(3, 20))
+assert abs(result.fit.alpha - 0.8) < 1e-12
+```
+
+## GUI
+
+```bash
+python -m ftproductlab.gui
+```
+
+The GUI is deliberately Tkinter/ttk rather than Qt. It creates one `Tk()` root, calls the
+same application service as the CLI, exports the same tables, and closes the event loop
+normally. Plot exports explicitly select Matplotlib `Agg`; the core and CLI do not import
+Tkinter, Matplotlib, PyQt, or PySide.
+
+## CSV schema and basis
+
+Required columns are `carbon_number` and `amount`. Optional columns are `category`,
+`species`, `molecular_weight_g_mol`, and `below_detection`.
+
+- `molar`: amount is proportional to moles of product molecules.
+- `carbon`: amount is proportional to carbon moles; it is divided by carbon number before
+  fitting.
+- `mass`: each record must provide molecular weight. FTProductLab never approximates all
+  paraffins, olefins, and oxygenates as `CH2`.
+
+Amounts may use any consistent scale. Zero measurements remain in output but cannot enter a
+logarithmic fit. Below-detection records remain visible and are excluded from fitting by
+default. Repeat `--cut LABEL:MIN[:MAX]` to define CLI cuts; the GUI exposes the same cut
+specification, and the Python API accepts `CutDefinition` objects directly.
+
+## Scientific basis
+
+For molecular amount at carbon number `n`, the ideal single-alpha model is
+
+```text
+x_n = (1 - alpha) alpha^(n - 1)
+```
+
+and the corresponding carbon fraction is
+
+```text
+w_n = n (1 - alpha)^2 alpha^(n - 1).
+```
+
+FTProductLab estimates the slope of `ln(molar-equivalent amount)` against `n` over the
+user-specified range; `alpha = exp(slope)`. The intercept is free because experimental
+datasets may be scaled or truncated. Uniform and amount-weighted regressions are explicit
+choices. No fit range is selected automatically, and C1/C2 are not silently removed.
+
+The primary/statistical foundation is Flory's chain-length distribution
+([JACS 1936, DOI 10.1021/ja01301a016](https://doi.org/10.1021/ja01301a016)); its early FT
+application includes Friedel and Anderson
+([JACS 1950, DOI 10.1021/ja01159a039](https://doi.org/10.1021/ja01159a039)). A modern
+discussion of ideal ASF and structured deviations is
+[Vervloet et al., Catalysis Science & Technology 2013](https://doi.org/10.1039/C3CY00080J).
+See [the scientific-basis document](docs/scientific-basis.md) for conventions and equations.
+
+## Validation
+
+- Exact synthetic geometric distributions recover alpha to floating-point precision.
+- Infinite molecular/carbon normalization and analytical carbon-cut sums have independent
+  direct-summation tests.
+- Species aggregation, mass-to-mole conversion, C1/C2 deviations, product-cut closure,
+  O/P zero denominators, detection flags, CSV, CLI, GUI export, plotting, and import
+  isolation are tested.
+- The open-access Partington et al. Co/TiO2 study reports alpha=0.92 for C10–C40 and provides
+  a useful external target, but repository-level numerical reproduction remains pending
+  because a redistributable tabular C10–C40 fixture has not yet been extracted. Synthetic
+  fixtures are never labeled real data.
+
+Details: [validation record](docs/validation.md).
+
+## Supported platforms
+
+- Python 3.10–3.14 for the core and CLI
+- Linux scientific core/CLI and Xvfb GUI checks on the project DGX runner
+- macOS GUI workflow on GitHub-hosted macOS plus local Apple Silicon smoke testing
+- Tk 8.6 or newer; no Qt binding is used or installed
+
+The hosted GUI matrix covers Apple Silicon on Python 3.10 and 3.14 and Intel on Python
+3.13. The `setup-python` 3.10 build on the `macos-15-intel` image is not a supported GUI
+combination because its Tk 8.5 build metadata conflicts with the image's Tk 8.6 runtime.
+See [macOS notes](docs/macos.md).
+
+## Limitations
+
+- Version 0.1 implements an ideal, single-alpha descriptive fit only. Dual-alpha and
+  modified ASF models are intentionally unsupported.
+- Missing products, detector response, phase collection, recycle, and analytical recovery
+  can structure residuals; the software does not correct them without supplied data.
+- Observed product-cut fractions close over the supplied dataset. They are not an estimate
+  of an unmeasured heavy tail.
+- Category names such as “gasoline”, “diesel”, and “wax” are not assigned automatically;
+  carbon-number cut definitions are shown explicitly.
+- This is product-distribution decision support, not a reactor or kinetic mechanism model.
+
+## Development and citation
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) before changing an equation or GUI dependency and
+use [CITATION.cff](CITATION.cff) when citing the software. The name and competitive audit is
+recorded in [docs/naming-audit.md](docs/naming-audit.md).