homology-operator 0.0.2__tar.gz

homology_operator-0.0.2/.gitattributes

@@ -0,0 +1,2 @@
+# Keep regression fixture bytes stable across platforms.
+tests/fixtures/*.json text eol=lf

homology_operator-0.0.2/.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: Documentation and Pages
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install documentation dependencies
+        run: python -m pip install -r docs/requirements.txt
+      - name: Check Markdown source links
+        run: pwsh -NoProfile -File ./scripts/check_docs.ps1
+      - name: Build Chinese documentation
+        run: python -m sphinx -E -n -W --keep-going -b html docs .task-artifacts/docs-site
+      - name: Build English documentation
+        run: python -m sphinx -E -n -W --keep-going -b html docs/en .task-artifacts/docs-site/en
+      - run: touch .task-artifacts/docs-site/.nojekyll
+      - uses: actions/upload-artifact@v4
+        with:
+          name: documentation-site
+          path: .task-artifacts/docs-site
+          if-no-files-found: error
+      - uses: actions/upload-pages-artifact@v3
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        with:
+          path: .task-artifacts/docs-site
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: docs
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

homology_operator-0.0.2/.github/workflows/native.yml

@@ -0,0 +1,67 @@
+name: Native checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  native:
+    strategy:
+      matrix:
+        include:
+          - os: windows-latest
+            python: "3.10"
+          - os: ubuntu-latest
+            python: "3.12"
+    runs-on: ${{ matrix.os }}
+    env:
+      RUSTUP_TOOLCHAIN: "1.98.1"
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.11.5"
+      - run: uv sync --locked --group oracle --python ${{ matrix.python }}
+      - run: rustup toolchain install 1.98.1 --profile minimal --component rustfmt --component clippy
+      - run: cargo fmt --manifest-path native/Cargo.toml --check
+      - run: cargo clippy --manifest-path native/Cargo.toml --locked --all-targets -- -D warnings
+      - name: Build and install optional release wheel
+        run: |
+          $pythonPath = uv run --locked python -c "import sys; print(sys.executable)"
+          uv tool run --from maturin==1.15.0 maturin build --manifest-path native/Cargo.toml --release --locked --interpreter $pythonPath --out .task-artifacts/native-wheels
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }
+          $wheel = Get-ChildItem .task-artifacts/native-wheels/*.whl
+          uv pip install --python $pythonPath $wheel.FullName
+          exit $LASTEXITCODE
+      - name: Require native differential and regression tests
+        env:
+          HOMOLOGY_NATIVE_REQUIRED: "1"
+          HOMOLOGY_GUDHI_REQUIRED: "1"
+        run: uv run --locked --no-sync python -m unittest discover -s tests -v
+      - name: Check installed reference and native wheels in isolation
+        env:
+          HOMOLOGY_NATIVE_REQUIRED: "1"
+        run: |
+          $pythonPath = uv run --locked --no-sync python -c "import sys; print(sys.executable)"
+          uv build --no-build-isolation
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }
+          uv venv .task-artifacts/installed-env --python $pythonPath
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }
+          $installedPython = if ($IsWindows) { '.task-artifacts/installed-env/Scripts/python.exe' } else { '.task-artifacts/installed-env/bin/python' }
+          $referenceWheel = Get-ChildItem dist/*.whl
+          $nativeWheel = Get-ChildItem .task-artifacts/native-wheels/*.whl
+          uv pip install --python $installedPython $referenceWheel.FullName $nativeWheel.FullName
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }
+          & $installedPython -I -c "from homology_operator.native import backend_info; info = backend_info(); assert info['native'] == 'Available', info; print(info)"
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }
+          & $installedPython -I -m unittest discover -s tests -p test_integration.py -v
+          if ($LASTEXITCODE) { exit $LASTEXITCODE }
+          & $installedPython -I -m unittest discover -s tests -p test_legacy_results.py -v
+          exit $LASTEXITCODE

homology_operator-0.0.2/.github/workflows/oracle.yml

@@ -0,0 +1,33 @@
+name: GUDHI oracle checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  oracle:
+    strategy:
+      matrix:
+        include:
+          - os: windows-latest
+            python: "3.12"
+          - os: ubuntu-latest
+            python: "3.10"
+          - os: ubuntu-latest
+            python: "3.12"
+    runs-on: ${{ matrix.os }}
+    env:
+      HOMOLOGY_GUDHI_REQUIRED: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.11.5"
+      - run: uv sync --locked --group oracle --group oracle-secondary --python ${{ matrix.python }}
+      - run: uv run --locked --group oracle --group oracle-secondary python -m unittest discover -s tests -p test_simplicial_inputs.py -v
+      - run: uv run --locked --group oracle --group oracle-secondary python -m unittest discover -s tests -p test_gudhi_oracle.py -v
+      - run: uv run --locked --group oracle --group oracle-secondary python -m unittest discover -s tests -p test_oracle_corpus.py -v

homology_operator-0.0.2/.github/workflows/reference.yml

@@ -0,0 +1,48 @@
+name: Reference checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  reference:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.11.5"
+      - run: uv sync --locked --python ${{ matrix.python }}
+      - run: uv run --locked python -m unittest discover -s tests -v
+      - run: uv run --locked python examples/single_scale.py
+      - run: uv run --locked python examples/filtration.py
+      - run: uv run --locked ruff check .
+      - run: uv run --locked ruff format --check .
+      - run: uv build --no-build-isolation
+      - name: Check wheel in an isolated environment
+        shell: bash
+        run: |
+          uv venv .task-artifacts/wheel-env --python ${{ matrix.python }}
+          uv pip install --python .task-artifacts/wheel-env/bin/python dist/*.whl
+          .task-artifacts/wheel-env/bin/python -I -c "import homology_operator; print(homology_operator.__version__)"
+          .task-artifacts/wheel-env/bin/python -I -c "from homology_operator.native import backend_info; info=backend_info(); assert info['native']=='Unavailable', info; print(info)"
+          .task-artifacts/wheel-env/bin/python -I -m unittest discover -s tests -p test_integration.py -v
+          .task-artifacts/wheel-env/bin/python -I -m unittest discover -s tests -p test_legacy_results.py -v
+          .task-artifacts/wheel-env/bin/python -I -m unittest discover -s tests -p test_backend_integration.py -v
+      - run: pwsh -NoProfile -File ./scripts/check_docs.ps1
+      - run: git diff --check
+      - name: Check whitespace in the complete pull request
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: git diff --check "$BASE_SHA...$HEAD_SHA"

homology_operator-0.0.2/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+name: Publish Python package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.11.5"
+      - run: uv sync --locked --python ${{ matrix.python }}
+      - name: Match release tag to package version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: uv run --locked python -c "import os, homology_operator; assert os.environ['RELEASE_TAG'] == 'v' + homology_operator.__version__"
+      - run: uv run --locked python -m unittest discover -s tests -v
+      - run: uv run --locked python examples/single_scale.py
+      - run: uv run --locked python examples/filtration.py
+      - run: uv run --locked ruff check .
+      - run: uv run --locked ruff format --check .
+      - run: pwsh -NoProfile -File ./scripts/check_docs.ps1
+      - run: uv build --no-build-isolation
+      - run: uv tool run --from twine==6.2.0 twine check --strict dist/*
+      - name: Test the installed wheel independently of the source tree
+        run: |
+          uv venv .task-artifacts/release-env --python ${{ matrix.python }}
+          uv pip install --python .task-artifacts/release-env/bin/python dist/*.whl
+          .task-artifacts/release-env/bin/python -I -c "import homology_operator; from homology_operator.native import backend_info; assert backend_info()['native'] == 'Unavailable'; print(homology_operator.__version__)"
+          .task-artifacts/release-env/bin/python -I -m unittest discover -s tests -v
+      - uses: actions/upload-artifact@v4
+        if: matrix.python == '3.10'
+        with:
+          name: python-distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/homology-operator/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+      - name: Publish with PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

homology_operator-0.0.2/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.py[cod]
+.ruff_cache/
+dist/
+.task-artifacts/
+native/target/

homology_operator-0.0.2/AGENTS.md

@@ -0,0 +1,46 @@
+# homology-operator 项目约定
+
+默认使用中文回答。修改前阅读 README、docs 与相关代码，沿用现有文件和类型；
+修改后检查文档、注释、测试和示例。做最小可验证修改，不覆盖用户已有工作。
+
+## 产品范围
+
+仓库保留 Python 公共接口、Rust 计算后端、产品回归测试、示例和双语文档。
+研究原型、阶段计划、历史实验原值/报告与一次性测量工具不进入当前产品目录。
+`src/homology_operator/` 和 `native/src/` 都是维护中的产品代码。
+reference 运行时仅依赖 Python 3.10+ 标准库；Rust 扩展单独构建，支持域见 docs/INTERFACE.md。
+
+## 数学与工程红线
+
+- 输入为固定次数的带基链窗口 `C_{k+1} --D--> C_k --A--> C_{k-1}`，在 F2 上验证维数、`AD=0` 与正权重。
+- 同一个 `HomologyOperator` 的拓扑、代表、距离、支撑和 stretch 必须来自同一个 `P`，保留 `input_id`、`basis_id`、`weight_id`、`projection_id`、`operator_id` 和 `solver_run_id`。
+- 任何 solver 输出进入算子前，独立验证 `P²=P`、`AP=0`、`PD=0` 以及循环同调保持。前三项不能替代最后一项；零投影也可能满足前三项。
+- `selected_mass(z)=m_w(Pz)` 不能被命名或序列化为真实最短类质量。合法投影、当前 objective 的精确计算、全局最优认证分别报告。
+- F2 代数精确不代表浮点权重下的 objective 精确。`ExactOptimal` 必须有最优性证书；资源耗尽、不可用、未计算、空定义域与合法零值分别表达。
+- 同调类查询默认只接受循环；原始 `project`、`apply_operator` 作用于全部链。不得静默把非循环解释成同调类。
+- Persistence 从 `OperatorFamily` 的 `T_ij=P_j J_ij|ker(L_i)` 和 rank invariant 读取。独立 PH reduction 只允许作为 `tests/oracle/` 或性能对照，不能填充主结果。
+- 理论来源固定在文档列出的研究提交；研究仓库的代码、依赖和验证成绩不能当作本仓库已有能力。迁移 fixture 必须记录来源和 hash。
+
+
+## 文档与验证
+
+- README 与 docs/index.md：安装、能力、用法和站点入口。
+- docs/INTERFACE.md：实际 API、支持域与 native 安装。
+- docs/ARCHITECTURE.md、docs/SOLVER_CONTRACT.md：数学定义、模块边界、算法与认证。
+- docs/RESULT_MODEL.md：身份、状态、几何语义、序列化与恢复。
+- docs/FIXTURES.md：产品测试输入与来源。
+- docs/VALIDATION.md：reference/native/oracle、打包、文档与 CI 的真实命令。
+
+普通文档改动运行：
+
+```powershell
+pwsh -NoProfile -File ./scripts/check_docs.ps1
+git diff --check
+```
+
+数学、投影、solver、transport、身份或恢复改动补独立不变量与失败输入测试。
+Rust 改动重建扩展并强制 native 差分；未安装扩展的跳过不能当作 native 通过。
+需要保留的产品兼容性样本与 oracle 位于 tests/fixtures 和 tests/oracle。
+临时构建、测量和运行日志写入忽略的 .task-artifacts，不提交到产品目录。
+最终报告实际修改、验证、跳过项和剩余限制，区分本地与远端 CI。
+具体数学契约优先于通用 skills；明确的用户要求优先。

homology_operator-0.0.2/CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: "If you use homology-operator in research, please cite the exact software version and commit."
+title: "homology-operator: boundary-native F2 homology operators"
+type: software
+version: 0.0.2
+license: MIT
+authors:
+  - name: "homology-operator contributors"
+repository-code: "https://github.com/proffitteoy/homology-operator"
+url: "https://github.com/proffitteoy/homology-operator"
+abstract: "Homology operators from based F2 chain windows, with same-projection topology, representatives, weighted geometry, and finite-filtration transport."

homology_operator-0.0.2/CONTRIBUTING.en.md

@@ -0,0 +1,29 @@
+# Contributing to homology-operator
+
+[中文](CONTRIBUTING.md) · [Development](docs/en/VALIDATION.md)
+
+Documentation, examples, input validation, correctness, performance and platform
+improvements are welcome. Read [project conventions](AGENTS.md) and the relevant
+mathematical contract first. Keep changes small and describe the trigger, final
+behavior, checks actually run, skipped checks and remaining limitations.
+
+1. Update both language entries, relevant API docs, comments, examples and tests
+   for public behavior changes.
+2. Validate projection legality independently, including cycle homology preservation.
+   Feasibility, current objective and global optimality are separate claims.
+3. Keep `selected_mass` distinct from true minimum class mass. Independent PH and
+   GUDHI comparisons must not fill production results.
+4. For native changes, rebuild the matching extension and require native tests.
+5. Bind performance claims to source/build/input, arithmetic, certificate and budget,
+   and retain complete costs, failures and regressions.
+6. Do not commit environments, build caches, wheels or temporary measurements.
+   Keep temporary measurements and research material in ignored directories.
+
+At minimum, run the applicable checks from [development](docs/en/VALIDATION.md).
+Documentation edits require source-link checks and both strict site builds;
+modified Python snippets must actually run. Mathematical or serialization changes
+need independent invariants and rejection/round-trip evidence.
+
+Report problems through [GitHub Issues](https://github.com/proffitteoy/homology-operator/issues).
+The project uses MIT; the 0.x compatibility policy and Trusted Publisher procedure
+are in [public releases](docs/en/VALIDATION.md#public-releases).

homology_operator-0.0.2/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# 为 homology-operator 贡献
+
+[README](README.md) · [English](CONTRIBUTING.en.md) · [开发与验证](docs/VALIDATION.md)
+
+欢迎提交文档、示例、输入校验、正确性、性能和跨平台构建改进。
+开始前阅读 [项目约定](AGENTS.md)及改动领域的契约；提交小范围改动，说明触发条件、
+最终行为与实际运行的检查。问题与建议可提交到 [GitHub Issues](https://github.com/proffitteoy/homology-operator/issues)。
+
+## 开发环境
+
+Python 3.10+ 和 uv；reference 运行时只依赖标准库。仓库根目录执行：
+
+```console
+uv sync --locked --python 3.10
+uv run --locked python -m unittest discover -s tests -v
+uv run --locked ruff check .
+uv run --locked ruff format --check .
+pwsh -NoProfile -File ./scripts/check_docs.ps1
+git diff --check
+```
+
+未安装扩展时 native 测试会明确跳过。改动 Rust 或 native 适配必须重建匹配扩展，
+并用 `HOMOLOGY_NATIVE_REQUIRED=1` 运行适用测试；命令见[验证说明](docs/VALIDATION.md)。
+GUDHI 是可选测试 oracle，须使用锁定依赖并强制运行对应检查。
+
+## 修改与验收
+
+| 改动 | 随改动提交的内容 |
+| --- | --- |
+| 文档或示例 | 更新实际入口；运行本地链接检查与严格站点构建；新增/修改代码片段实际执行 |
+| 输入、F2 代数、投影或 solver | 独立不变量、失败输入、循环同调保持、认证与资源状态测试 |
+| transport / barcode | composition、全区间 rank、独立 oracle 对拍、重复尺度与末端存活 |
+| 身份、schema 或恢复 | round-trip、混用与篡改拒绝、旧格式兼容、合法零与缺失状态 |
+| 性能 | 同输入/P/认证/预算的完整成本；源码、构建、环境、样本与失败/退化记录 |
+
+完整门槛以 [VALIDATION](docs/VALIDATION.md) 为准。请同步检查 API、注释、README、测试及示例。
+不将 `selected_mass` 表述为最短类质量，不将合法投影升级为最优认证，
+不以独立 PH reduction 或 GUDHI 输出填充主结果。
+
+## 文档站
+
+站点沿用现有 Markdown；Python 3.11+ 的文档依赖独立安装，命令见
+[文档构建](docs/VALIDATION.md#文档站构建)。中英文公开入口变更需同步检查示例和能力边界。
+仓库只保留产品实现、测试、示例与文档；临时测量或调研材料放入忽略目录。
+
+## Pull request
+
+描述问题与最终行为，注明修改范围、实际验证、跳过项和剩余限制。
+涉及性能时链接可复现命令与绑定源码的证据；所有退化与失败一起公开。
+不要提交虚拟环境、构建缓存、wheel 或临时测量产物。
+0.x 发行的兼容政策和 Trusted Publisher 流程见[发行说明](docs/VALIDATION.md#公开发行)。

homology_operator-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 homology-operator contributors
+
+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.