patchcraft 0.2.2__tar.gz → 0.5.0__tar.gz

{patchcraft-0.2.2 → patchcraft-0.5.0}/.github/workflows/release.yml

@@ -64,6 +64,46 @@ jobs:
           name: dist
           path: dist/
 
+  build-accel:
+    name: accel wheel (${{ matrix.target }})
+    runs-on: ${{ matrix.os }}
+    needs: validate
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # macos-13 is the Intel runner; macos-latest is arm64.
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: macos-latest
+            target: aarch64-apple-darwin
+          - os: macos-13
+            target: x86_64-apple-darwin
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build accel wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist-accel --manifest-path accel/Cargo.toml
+
+      - name: Build accel sdist (linux only)
+        # The sdist is OS-independent; one is enough. Building it from source
+        # requires a Rust toolchain -- documented in accel/README.md.
+        if: matrix.target == 'x86_64-unknown-linux-gnu'
+        run: pipx run maturin sdist --manifest-path accel/Cargo.toml --out dist-accel
+
+      - name: Check accel artifacts
+        run: pipx run twine check dist-accel/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: accel-${{ matrix.target }}
+          path: dist-accel/
+
   publish-pypi:
     name: publish to PyPI (Trusted Publishing)
     runs-on: ubuntu-latest
@@ -94,10 +134,38 @@ jobs:
         #   Workflow:          release.yml
         #   Environment:       pypi
 
+  publish-accel:
+    name: publish patchcraft-accel to PyPI (Trusted Publishing)
+    runs-on: ubuntu-latest
+    needs: build-accel
+    environment:
+      name: pypi
+      url: https://pypi.org/project/patchcraft-accel/
+    permissions:
+      id-token: write  # required for OIDC token exchange with PyPI
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: accel-*
+          path: dist-accel
+          merge-multiple: true
+      - name: Publish via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+          packages-dir: dist-accel/
+        # FIRST RELEASE REQUIRES a one-time "pending publisher" config on
+        # pypi.org (user action, not this repo's):
+        #   PyPI project name: patchcraft-accel
+        #   Owner:             LeoPR
+        #   Repository:        PatchCraft
+        #   Workflow:          release.yml
+        #   Environment:       pypi
+
   github-release:
     name: create GitHub Release with assets
     runs-on: ubuntu-latest
-    needs: publish-pypi
+    needs: [publish-pypi, build-accel]
     permissions:
       contents: write  # required to create a Release
     steps:
@@ -106,6 +174,11 @@ jobs:
         with:
           name: dist
           path: dist/
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: accel-*
+          path: dist-accel
+          merge-multiple: true
       - name: Extract version from tag
         id: ver
         run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
@@ -123,6 +196,8 @@ jobs:
           files: |
             dist/*.whl
             dist/*.tar.gz
+            dist-accel/*.whl
+            dist-accel/*.tar.gz
           fail_on_unmatched_files: true
           draft: false
           prerelease: false

{patchcraft-0.2.2 → patchcraft-0.5.0}/.github/workflows/test.yml

@@ -18,7 +18,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python: ["3.12", "3.13"]
+        python: ["3.12", "3.13", "3.14"]
     env:
       # Force uv to use the matrix Python in every uv* invocation
       # (otherwise `uv run` re-resolves to its default, which is the
@@ -49,3 +49,45 @@ jobs:
 
       - name: Pytest (skip GPU markers)
         run: uv run pytest -m "not gpu"
+
+  test-accel:
+    name: ${{ matrix.os }} / py3.12 / accel
+    runs-on: ${{ matrix.os }}
+    env:
+      UV_PYTHON: "3.12"
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install project with dev + cache extras
+        run: uv sync --locked --extra cache --extra dev
+
+      - name: Rust unit tests
+        # The venv's interpreter on PATH lets the pyo3 build script resolve
+        # libpython (extension-module is off outside maturin builds).
+        run: uv run cargo test --manifest-path accel/Cargo.toml
+
+      - name: Build + install the accelerator
+        run: |
+          uv pip install maturin
+          uv run maturin develop --manifest-path accel/Cargo.toml --release
+
+      - name: Accelerator is detected
+        run: uv run python -c "import patchcraft; assert patchcraft.accel_available()"
+
+      - name: Pytest (accelerated mode)
+        run: uv run pytest -m "not gpu"

{patchcraft-0.2.2 → patchcraft-0.5.0}/.gitignore

@@ -53,3 +53,6 @@ runs/
 
 # Datasets and caches live on Z:
 data/
+
+# Rust accelerator build artifacts (accel/Cargo.lock IS committed)
+accel/target/

{patchcraft-0.2.2 → patchcraft-0.5.0}/CHANGELOG.md

@@ -6,8 +6,165 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-02
+
+### Added
+
+- Python 3.14 is supported and declared. The classifiers list it, the CI
+  matrix runs the full suite plus `ruff check` and `mypy --strict` against it
+  on Ubuntu and Windows, and all six cells are green. The floor stays at 3.12
+  because `cache.py` uses PEP 695 generic syntax, which 3.11 cannot parse.
+
+### Changed
+
+- `tilings`/`paired_tilings` no longer emit degenerate single-patch overlap
+  specs: with one patch the stride is unobservable and the spec duplicated
+  the exact tile. `tilings((28, 28), allow_overlap=True)` now returns 73
+  specs instead of 100; `paired_tilings((14, 14), (28, 28), allow_overlap=True)`
+  returns 27 instead of 40.
+- The development lock moved to torch 2.14.0 and torchvision 0.29.0, with the
+  linters and the rest of the toolchain along with it. The full
+  126,736-geometry exactness sweep passes on torch 2.14, so the count-map
+  contract is unchanged by the upgrade. Runtime requirements are untouched and
+  stay at `torch>=2.6`.
+
+### Fixed
+
+- **Public retraction: the documented exactness boundary was wrong.** The old
+  wording (`k_max <= 4`, "`stride == patch_size / 2`", "within ~1 ULP" outside
+  the rule) was measured false: the error grows with the pixel's coverage
+  count (up to 19 ULP at count 81 in float32). The correct contract
+  (ADR 0003): the `extract`/`reconstruct` round trip is bit-exact iff every
+  value of the overlap count map is a power of two, which is always true
+  at `stride == patch_size`, and outside the rule the per-pixel error is
+  bounded by `(k+1)·eps·|v|`, with `k` the pixel's coverage count.
+  Docstrings and docs (SCOPE, THEORY, GUIDE, USAGE, READMEs) now state this
+  form; THEORY §9.1 records the extract-truncates / reconstruct-rejects
+  asymmetry.
+- Packaging: the sdist no longer carries `.superpowers/`, an untracked
+  directory of agent tooling that hatchling swept in (62 files). The same
+  class of leak as the `lab/` files that reached PyPI in 0.2.0.
+- Documentation: GUIDE section 6 still printed the pre-0.5.0 enumeration
+  output and described the single-patch duplicates as an open wart; section 7
+  asserted `__version__ == "0.4.0"`; section 8 and the BibTeX entry quoted
+  0.4.0 and its test counts. All four now match the release.
+- Prose: the em-dashes that entered the docstrings, docs and tests during
+  0.3.0 to 0.5.0 are rewritten as ordinary sentences, per the project's
+  writing rule.
+- Test suite: round-trip assertions now run on seeded full-mantissa noise
+  (integer ramps and widened-float32 data could mask ULP-level errors); a
+  falsification suite (`tests/test_exactness.py`) enumerates the 126,736
+  legal geometries, samples 256 (seeded; full sweep via
+  `PATCHCRAFT_SWEEP_FULL=1`), and pins both halves of the predicate; a naive
+  loop-based reference (`tests/test_reference.py`) cross-checks the fast
+  paths; the 20-name public surface is frozen by `tests/test_public_api.py`;
+  the no-`zstandard` cache branch is now covered.
+
+### Notes
+
+- No signature changed. The public surface is exactly the 20 names of 0.4.0,
+  now pinned by test.
+
+## [0.4.0] - 2026-09-01
+
+> Source milestone, never uploaded to PyPI. Its contents reached
+> users inside 0.5.0. See the versioning policy in
+> [`CONTRIBUTING.md`](CONTRIBUTING.md) for why the number was minted
+> early and why that no longer happens.
+
+
+### Added
+
+- Optional native accelerator `patchcraft-accel` (`pip install patchcraft[accel]`):
+  a Rust/pyo3 kernel for the overlap fold of `reconstruct`/`stitch`. Prebuilt
+  abi3 wheels (Python 3.12+) for Windows x64, Linux x86_64 (manylinux), macOS
+  arm64 and macOS x86_64; self-contained, no system dependencies, no torch
+  linkage. When it is absent, ABI-mismatched, ineligible (CUDA/integer
+  tensors), or disabled via `PATCHCRAFT_ACCEL=0`, every path falls back
+  silently to pure torch.
+- `patchcraft.accel_available()` reports whether the accelerator is active.
+
+### Performance
+
+- Overlap fold with the accelerator, mean of `lab/bench_phase2.py` on the
+  dev machine: reconstruct 3x512x512 p=32 s=16 17.727 ms -> 2.609 ms (6.80x);
+  stitch[hann] same geometry 23.714 ms -> 8.894 ms (2.67x); 3x2048x2048 p=64
+  s=32 reconstruct 469.814 ms -> 32.458 ms (14.47x). The accelerated `stitch`
+  also skips the full pre-multiply pass over the patches tensor.
+
+### Notes
+
+- Numeric equivalence accel vs pure: bit-exact (`torch.equal`) across the
+  test grid (overlap x rectangular x stride∤patch x C in {1,3,4} x f32/f64).
+- Linux validation: wheel
+  `patchcraft_accel-0.1.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl`
+  installed and the test suite passed accelerated on Ubuntu 26.04 (WSL),
+  built via the manylinux maturin container.
+
+## [0.3.0] - 2026-09-01
+
+> Source milestone, never uploaded to PyPI. Its contents reached
+> users inside 0.5.0. See the versioning policy in
+> [`CONTRIBUTING.md`](CONTRIBUTING.md) for why the number was minted
+> early and why that no longer happens.
+
+
+### Performance
+
+- `extract` uses a strided-window view (`Tensor.unfold`) for `dilation == 1`,
+  one copy instead of im2col + permute-contiguous: 13-21x faster on CPU,
+  bit-exact. `dilation > 1` still uses `F.unfold`.
+- `reconstruct` skips `F.fold` entirely on non-overlapping grids (a pure
+  rearrangement, 27x faster on CPU) and computes the overlap count map in
+  closed form O(H+W) instead of folding a tensor of ones.
+- `stitch` builds its denominator from two 1-D window folds (the kernels are
+  separable) instead of a second 2-D `F.fold`. `uniform` stays bit-exact vs
+  `reconstruct`; `hann`/`gaussian` may differ by ULPs (summation order).
+- `patch_metrics`/`per_patch_mse` materialize one f64 tensor instead of
+  three and sync the device once instead of three times.
+
 ### Fixed
 
+- `resize` with `backend="pil"` clamped integer tensors to the uint8 range
+  before casting; values outside [0, 255] used to wrap (300 became 44).
+- Removed the machine-local `cache_dir = "Z:\caches\pytest"` from
+  `pyproject.toml` (created a literal `Z:\caches\...` directory on
+  Linux/macOS).
+
+### Documentation
+
+- Corrected stale 0.2.1 version strings on all cover pages and in GUIDE.
+- Corrected the gaussian-kernel floor claim in `stitch` (exp(-4) at corners,
+  not exp(-2) everywhere).
+- Corrected the bit-exactness rule in THEORY/USAGE (power-of-two count map).
+- SCOPE §4.4 no longer claims `reconstruct` lacks a dtype guard.
+- CHANGELOG: link targets for [Unreleased], [0.2.2], [0.2.1].
+
+### Internal
+
+- `reconstruct`/`stitch` share one fold-geometry validator
+  (`patchcraft._foldgeom.check_fold_geometry`); error messages unchanged.
+
+## [0.2.2] - 2026-08-30
+
+Documentation release. No behaviour changes, so every call that worked on 0.2.1
+works identically here, and the only file under `src/` that changed is a
+docstring.
+
+### Fixed
+
+- **`reconstruct`'s docstring claimed the overlap round trip returns the
+  original image.** It said each pixel comes back as "the average of all patches
+  covering it, the same as the original when patches came from `extract`
+  unmodified". The second half is false. Measured on a 16x16 image with
+  `patch_size=4, stride=1`, unmodified patches straight from `extract` come back
+  with `torch.equal` False and a maximum absolute error of 2.4e-07 in float32.
+
+  The docstring now states the real rule: the round trip is bit-exact when every
+  value in the count map is a power of two, because dividing a float by a power
+  of two is the one division that never rounds. It also says that widening the
+  dtype does not rescue it, since the deciding axis is the geometry rather than
+  the precision.
 - **`pair()`'s docstring double-applied the stride, and could silently
   misplace every patch for a caller who trusted it.** It said patch `k` has
   its top-left at LR pixel `(row * sh_lr, col * sw_lr)`, but `PatchMeta.row`
@@ -37,32 +194,11 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   Reported from an API review done for the QSR prototype, which uses patch
   position as a context feature.
 
-## [0.2.2] 2026-08-30
-
-Documentation release. No behaviour changes, so every call that worked on 0.2.1
-works identically here, and the only file under `src/` that changed is a
-docstring.
-
-### Fixed
-
-- **`reconstruct`'s docstring claimed the overlap round trip returns the
-  original image.** It said each pixel comes back as "the average of all patches
-  covering it, the same as the original when patches came from `extract`
-  unmodified". The second half is false. Measured on a 16x16 image with
-  `patch_size=4, stride=1`, unmodified patches straight from `extract` come back
-  with `torch.equal` False and a maximum absolute error of 2.4e-07 in float32.
-
-  The docstring now states the real rule: the round trip is bit-exact when every
-  value in the count map is a power of two, because dividing a float by a power
-  of two is the one division that never rounds. It also says that widening the
-  dtype does not rescue it, since the deciding axis is the geometry rather than
-  the precision.
-
 ### Changed
 
 - **The README is now a call page and the manual moved to `docs/GUIDE.md`.** The
   README had reached 864 lines, which made it a manual printed on the front
-  door. It is 137 lines now, and it answers what the library is, where you are
+  door. It is 156 lines now, and it answers what the library is, where you are
   getting into, and which of `reconstruct` or `stitch` you want. Nothing was
   discarded: every measurement, table and long example moved into the guide,
   which gained its own table of contents.
@@ -233,7 +369,7 @@ kernel so each pixel "trusts" patches closer to its center more.
   on overlap). With `"hann"` it strongly suppresses seams at the
   cost of zeroing image corners that fall on Hann's edge-weight-zero
   region (documented artifact). With `"gaussian"`
-  (`sigma = max(1, min(ph, pw) / 4)`) it blends smoothly with no
+  (per-axis `sigma = max(1.0, n / 4.0)`) it blends smoothly with no
   corner artifact.
 
 Floating-point patches only, because window kernels are float-valued and we
@@ -336,5 +472,10 @@ First public release. Public API stable; signatures will only change in 1.x.
 - [`README.md`](README.md) covers installation, the car-vs-track metaphor,
   validation lab.
 
+[Unreleased]: https://github.com/LeoPR/PatchCraft/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.4.0
+[0.3.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.3.0
+[0.2.2]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.2.2
+[0.2.1]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.2.1
 [0.2.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.2.0
 [0.1.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.1.0

patchcraft-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,161 @@
+# Contributing to PatchCraft
+
+If you've cloned this repo and want to run the test suite, understand how the project is laid out, or follow the validation conventions, this is the page. For installation and usage, see the [README](README.md).
+
+---
+
+## Run tests
+
+```
+pytest
+pytest -m "not gpu"        # skip GPU-requiring tests
+```
+
+CI runs the full suite on every push and PR. See [`.github/workflows/test.yml`](.github/workflows/test.yml). Matrix is `{ubuntu-latest, windows-latest} × {python 3.12, 3.13, 3.14}`. To run the same checks locally before pushing:
+
+```
+ruff check src tests
+mypy --strict src
+pytest -m "not gpu"
+```
+
+---
+
+## Layout
+
+```
+PatchCraft/
+├── pyproject.toml                  package metadata, build backend (hatchling)
+├── README.md                       the call page, canonical, English
+├── README.pt-BR.md                 the same call page in Portuguese
+├── README.pypi.md                  the PyPI page (long_description), links absolute
+├── CONTRIBUTING.md                 this file
+├── CHANGELOG.md                    Keep-a-Changelog format
+├── LICENSE                         MIT
+├── .python-version                 3.13
+├── .gitignore                      ignores archive/, venvs, caches, outputs
+├── .github/workflows/
+│   ├── test.yml                    matrix CI on PRs/main, plus the accelerated job
+│   └── release.yml                 publishes to PyPI on vX.Y.Z tag push (Trusted Publishing)
+├── src/patchcraft/                 library core, one-image-at-a-time primitives
+│   ├── __init__.py                 re-exports the full public API, holds __version__
+│   ├── extract.py                  patches via strided view or F.unfold; Patchify (ADR 0002)
+│   ├── reconstruct.py              inverse via F.fold + count map, closed-form fast path
+│   ├── stitch.py                   weighted reassembly for modified patches
+│   ├── geometry.py                 pre-flight: num_patches, tilings, scale_factor, paired_tilings
+│   ├── metrics.py                  patch_metrics, per_patch_mse, per_patch_psnr
+│   ├── pair.py                     LR↔HR pairing; PatchPair, PatchMeta
+│   ├── resize.py                   resize with PIL or torch backends
+│   ├── cache.py                    content-addressed disk cache
+│   ├── _accel.py                   bridge to the optional native accelerator, falls back silently
+│   └── _foldgeom.py                shared fold-geometry validation for reconstruct and stitch
+├── accel/                          patchcraft-accel, a separate distribution (Rust, pyo3/maturin)
+│   ├── Cargo.toml                  crate metadata, holds the accel version
+│   ├── src/kernel.rs               the gather-fold kernel, pure Rust, cargo-tested
+│   ├── src/lib.rs                  pyo3 glue
+│   └── README.md                   how to build it from source
+├── tests/                          pytest suite (contract tests for src/)
+│   ├── test_extract.py             extract + Patchify
+│   ├── test_reconstruct.py
+│   ├── test_stitch.py
+│   ├── test_geometry.py            num_patches + tilings + scale_factor + paired_tilings
+│   ├── test_metrics.py
+│   ├── test_pair.py
+│   ├── test_resize.py
+│   ├── test_cache.py
+│   ├── test_exactness.py           falsifies the count-map predicate over the legal space
+│   ├── test_reference.py           naive loop-based reference for the fast paths
+│   ├── test_public_api.py          freezes the 20 names, their signatures and carrier fields
+│   ├── test_accel.py               native path, skipped unless the accelerator is installed
+│   ├── test_datasets_helper.py     label_subset
+│   ├── test_import.py
+│   ├── _rng.py                     audited round-trip helpers (data generation, bit equality)
+│   ├── test_rng.py                 tests for those helpers
+│   └── _datasets.py                dev-only fixtures (MNIST, etc), NOT public API
+├── lab/                            ephemeral experiments; see lab/README.md
+│   ├── README.md                   bench rules (tracked)
+│   ├── usage_demo.py               regenerates the live REPL outputs in docs/USAGE.md
+│   └── .gitignore                  ignores everything else (tracked)
+├── docs/
+│   ├── GUIDE.md                    the manual, every README claim measured with its output
+│   ├── USAGE.md                    REPL walkthrough of every public symbol (behind, see B4)
+│   ├── SCOPE.md                    responsibilities matrix + parallelization analysis
+│   ├── AUXILIARY.md                tests/_datasets, lab/, Z:\ conventions (NOT part of the wheel)
+│   ├── THEORY.md                   distilled design + §9 condition contract; §0 binding scope
+│   ├── ROADMAP.md                  milestone plan
+│   ├── FOCO-1.0.md                 what 1.0 freezes and the blockers in the way
+│   ├── ADR/                        one file per decision that shaped the API
+│   ├── STUDIES/                    background reading behind those decisions
+│   └── superpowers/                the design specs and implementation plans per work phase
+└── archive/                        reference-only; gitignored (pruned 2026-05-17, only HISTORY.md kept)
+```
+
+---
+
+## Validation lab
+
+The library is "one image in, one tensor out" by design, but you only know it works once you run it end-to-end on real images. That happens in two places, neither of which is part of the shipped package:
+
+- [`tests/`](tests/) holds the formal pytest suite that defines the contract from [`docs/THEORY.md`](docs/THEORY.md) §9.
+- [`lab/`](lab/) holds ephemeral scripts and notebooks for fast hypothesis-checking. See [`lab/README.md`](lab/README.md) for the bench rules; outputs go to `Z:\outputs\patchcraft\` (off-tree).
+
+Datasets used by tests/lab are downloaded lazily into `Z:\caches\datasets\<name>\` on first use; they do not ship with the package and are never bundled into the wheel.
+
+The dev framework that makes this all work (fixtures, dataset helpers, `Z:\` conventions) is documented in [`docs/AUXILIARY.md`](docs/AUXILIARY.md).
+
+---
+
+## Versioning policy
+
+The scheme is [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html),
+expressed in the [PEP 440](https://peps.python.org/pep-0440/) form that PyPI
+accepts. Two rules matter more than the arithmetic, because both were broken
+once and both cost work to undo.
+
+**The number names a published artifact, not a unit of work.** Finishing a
+phase, merging a branch and landing a refactor are not releases, and none of
+them touches `__version__`. Everything between releases accumulates under
+`[Unreleased]` in [`CHANGELOG.md`](CHANGELOG.md), and the number is assigned
+in the release commit itself. Versions 0.3.0 and 0.4.0 came from the opposite
+habit: each internal work phase minted a minor, so three numbers existed
+before any of them reached PyPI.
+
+**A published version is frozen.** PyPI refuses a filename it has already
+seen, so a version that shipped can only be superseded, never edited. That is
+also why a failed pipeline never costs a number: `skip-existing` makes the
+upload a no-op and the same tag can be re-run.
+
+Which component moves, while the project is pre-1.0 and SemVer leaves `0.y.z`
+open:
+
+| Change | Bump |
+|---|---|
+| Any output value, signature, name or documented behaviour changes | minor, `0.Y.0` |
+| A fix that changes no documented behaviour and no signature | patch, `0.y.Z` |
+| Documentation, tests, CI or tooling only | nothing |
+
+After 1.0 the ordinary reading applies: breaking is major, additive is minor,
+fixed is patch. What 1.0 freezes is written in
+[`docs/FOCO-1.0.md`](docs/FOCO-1.0.md).
+
+The accelerator in [`accel/`](accel/) is a separate distribution with its own
+version in `accel/Cargo.toml`. It moves on its own schedule, and the two
+numbers are not meant to track each other.
+
+---
+
+## Releasing (maintainer only)
+
+1. Bump `__version__` in [`src/patchcraft/__init__.py`](src/patchcraft/__init__.py).
+2. Close the `[Unreleased]` section in [`CHANGELOG.md`](CHANGELOG.md) as `[X.Y.Z] YYYY-MM-DD`.
+3. Sweep the version strings the docs quote, which live in
+   [`docs/GUIDE.md`](docs/GUIDE.md) (the provenance note, the section 7
+   assertion, section 8 and the BibTeX entry) and in the Status block of the
+   three cover pages.
+4. Update [`docs/ROADMAP.md`](docs/ROADMAP.md) milestone checkboxes.
+5. Commit: `release: vX.Y.Z`.
+6. Tag + push: `git tag -a vX.Y.Z -m "..."` then `git push origin vX.Y.Z`.
+7. `release.yml` fires automatically: validates → builds → publishes to PyPI via Trusted Publishing → creates GitHub Release with `.whl` + `.tar.gz`.
+
+The tag must match `__version__`, and the `validate` job fails the run if it
+does not.

{patchcraft-0.2.2 → patchcraft-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchcraft
-Version: 0.2.2
+Version: 0.5.0
 Summary: Image patch extraction, reconstruction, pairing and seam-aware stitching for super-resolution and dataset pipelines.
 Project-URL: Homepage, https://github.com/LeoPR/PatchCraft
 Project-URL: Repository, https://github.com/LeoPR/PatchCraft
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Image Processing
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -28,6 +29,8 @@ Requires-Python: >=3.12
 Requires-Dist: numpy>=1.26
 Requires-Dist: pillow>=10
 Requires-Dist: torch>=2.6
+Provides-Extra: accel
+Requires-Dist: patchcraft-accel>=0.1.0; extra == 'accel'
 Provides-Extra: cache
 Requires-Dist: zstandard>=0.22; extra == 'cache'
 Provides-Extra: dev
@@ -51,6 +54,24 @@ PatchCraft takes a single `(C, H, W)` float tensor, cuts it into a stack of patc
 
 The scope is one image at a time, and that is worth knowing before you install anything, because it is the constraint that decides whether PatchCraft fits your problem at all. There is no batching across images, no `Dataset`, no `DataLoader` and no training loop, so multi-image work stays in your own `for` loop, in your `torch.vmap`, or in your `DataLoader` calling this once per item.
 
+```
+   one image                     the patch stack                one image again
+   (1, 4, 4)                     (4, 1, 2, 2), row-major        (1, 4, 4)
+
+   +-----+-----+                 +-----+   +-----+              +-----+-----+
+   | A A | B B |                 | A A |   | B B |              | A A | B B |
+   | A A | B B |    extract      | A A |   | B B |  reconstruct | A A | B B |
+   +-----+-----+   ---------->   +--p0-+   +--p1-+  ----------> +-----+-----+
+   | C C | D D |   patch_size=2  +-----+   +-----+   stride=2   | C C | D D |
+   | C C | D D |   stride=2      | C C |   | D D |              | C C | D D |
+   +-----+-----+                 | C C |   | D D |              +-----+-----+
+                                 +--p2-+   +--p3-+
+```
+
+The image goes out as a stack of patches, you do your work on the stack, and it comes back as one
+image. That last arrow has two doors: `reconstruct` when the patches are untouched, and `stitch`
+when a model rewrote them and the seams need to fade.
+
 This page is the short one. The manual is [docs/GUIDE.md](https://github.com/LeoPR/PatchCraft/blob/main/docs/GUIDE.md), which carries the measurements, the tables and the long examples.
 
 ## Install
@@ -60,7 +81,18 @@ pip install patchcraft
 pip install "patchcraft[cache]"     # adds zstandard, which compresses Cache payloads
 ```
 
-The distribution name and the import name are both `patchcraft`. The extra is optional, because `Cache` works without `zstandard` as well and simply stores its payload uncompressed.
+Or with the optional native accelerator (prebuilt wheels for Windows x64,
+Linux x86_64, macOS arm64 and macOS x86_64; the package stays pure-Python
+and fully functional without it):
+
+```bash
+pip install patchcraft[accel]
+```
+
+`patchcraft.accel_available()` reports at runtime whether the accelerator is
+active; `PATCHCRAFT_ACCEL=0` in the environment forces the pure path.
+
+The distribution name and the import name are both `patchcraft`. The cache extra is optional, because `Cache` works without `zstandard` as well and simply stores its payload uncompressed.
 
 ## Sixty seconds
 
@@ -118,7 +150,7 @@ The saving is real on the other side too. Tiling an image, running a per-patch m
 
 `extract` follows whatever grid you hand it, but `reconstruct` and `stitch` refuse a grid that does not cover the image exactly, rather than returning a plausible tensor built on missing pixels. On a 128x128 image with `patch_size=32` and `stride=20` the grid reaches only 112x112, which leaves 3840 of the 16384 pixels at zero, and the error message names that covered extent instead of hiding it.
 
-The answer is to pick a legal geometry rather than to pad the image into one, because padding synthesizes pixels you never had. `tilings(image_shape)` enumerates the legal geometries from the shape alone and allocates nothing while it does so, so you can call it before you have committed to anything: a 28x28 image has 5 exact tilings, and 100 of them once `allow_overlap=True` lets the patches overlap.
+The answer is to pick a legal geometry rather than to pad the image into one, because padding synthesizes pixels you never had. `tilings(image_shape)` enumerates the legal geometries from the shape alone and allocates nothing while it does so, so you can call it before you have committed to anything: a 28x28 image has 5 exact tilings, and 73 of them once `allow_overlap=True` lets the patches overlap.
 
 Two narrower questions have their own entry points. `num_patches` takes a geometry you already have in mind and returns the grid it implies, and `paired_tilings` is the one to reach for when a low-resolution image and a high-resolution image have to stay aligned patch for patch.
 
@@ -132,20 +164,20 @@ It helps when you tile one image for an inference pass too large to run in a sin
 
 The round trip is exact when every value in the count map is a power of two. The reason is that reconstruction divides each pixel by the number of patches that covered it, and dividing a float by a power of two is the one division that never rounds.
 
-That makes the geometry the deciding axis rather than the dtype, so `float64` is not a safe harbour: outside the rule `float32` misses by roughly `1e-7`, and `float64` misses too, by roughly `1e-16`.
+That makes the geometry the deciding axis rather than the dtype, so `float64` is not a safe harbour: outside the rule the per-pixel error is bounded by `(k+1)·eps·|v|`, with `k` the pixel's coverage count. A wider float buys a smaller miss and never exactness.
 
 The everyday shorthand is that `stride == patch_size` and `stride == patch_size / 2` always satisfy the rule. Both are sufficient conditions rather than necessary ones, so a geometry outside them can still be exact, and the [guide](https://github.com/LeoPR/PatchCraft/blob/main/docs/GUIDE.md#4-when-the-round-trip-is-bit-for-bit) carries the sweep that measures it.
 
 ## Status
 
-This page documents 0.2.1, which is pre-1.0, so both the output values and the API shape can still change in a minor release, and the [changelog](https://github.com/LeoPR/PatchCraft/blob/main/CHANGELOG.md) is where each of those changes is recorded with the measurement behind it. The suite runs 346 tests and they pass on Python 3.12 and 3.13, on Ubuntu and on Windows alike.
+This page documents 0.5.0, which is pre-1.0, so both the output values and the API shape can still change in a minor release, and the [changelog](https://github.com/LeoPR/PatchCraft/blob/main/CHANGELOG.md) is where each of those changes is recorded with the measurement behind it. The suite collects 1571 tests and passes on Python 3.12, 3.13 and 3.14, on Ubuntu and on Windows alike.
 
 Two limits are worth knowing before you depend on it. Every figure on this page was measured on CPU, and no CUDA path has ever executed in the test matrix, so the pipeline does preserve the device you hand it while the exactness numbers stay unverified on GPU. The other limit is that no external project has consumed the published API in real use yet, and that consumption is this project's own stated gate for calling the shape settled.
 
 ## Documentation
 
 - [Guide](https://github.com/LeoPR/PatchCraft/blob/main/docs/GUIDE.md), the manual, with every figure on this page shown as runnable code
-- [Usage](https://github.com/LeoPR/PatchCraft/blob/main/docs/USAGE.md), a walkthrough of each of the 19 public symbols
+- [Usage](https://github.com/LeoPR/PatchCraft/blob/main/docs/USAGE.md), a walkthrough of each of the 20 public symbols
 - [Theory](https://github.com/LeoPR/PatchCraft/blob/main/docs/THEORY.md), the math and the per-function contract
 - [Scope](https://github.com/LeoPR/PatchCraft/blob/main/docs/SCOPE.md), the line between this library and your pipeline
 - [Repository](https://github.com/LeoPR/PatchCraft), [issues](https://github.com/LeoPR/PatchCraft/issues) and [contributing](https://github.com/LeoPR/PatchCraft/blob/main/CONTRIBUTING.md)