patchcraft 0.5.0__tar.gz → 0.5.1__tar.gz

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

@@ -3,6 +3,10 @@ __pycache__/
 *.py[cod]
 *$py.class
 *.so
+# Built in place by an editable install (setuptools-rust).
+src/patchcraft/_accel_native*
+# Generated at build time by setuptools-scm.
+src/patchcraft/_version.py
 
 # Distribution / packaging
 build/

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

@@ -6,6 +6,121 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-09-02
+
+> Numbered `0.6.0` while it was being built. Corrected before release: the
+> middle digit is the compatibility boundary, and this release changes no
+> signature, no name and no output value. See the versioning policy and its
+> errata in [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+### Changed
+
+- **The native accelerator ships inside this wheel.** It was going to be a
+  second PyPI project, `patchcraft-accel`, reached through
+  `pip install patchcraft[accel]`. That project was never published and now
+  never will be. A release produces one sdist and six wheels for the single
+  `patchcraft` project: five tagged `cp312-abi3-<platform>` with the Rust
+  kernel compiled in as `patchcraft._accel_native`, and one `py3-none-any`
+  for every other platform. Installers prefer the most specific compatible
+  tag, so `pip install patchcraft` picks up the accelerator where one exists
+  and the pure wheel everywhere else, with no extra to remember. The pattern
+  and its universal fallback follow `coverage`, which publishes the same two
+  shapes for one version.
+- The `accel` extra is removed. Nothing depended on it, because it never
+  reached the index.
+- The accelerator is now on by default where a wheel carries it, rather than
+  opt-in. The two paths are bit-identical by test, and `PATCHCRAFT_ACCEL=0`
+  still forces the pure one at runtime.
+- Build backend moves from hatchling to setuptools with setuptools-rust, which
+  is what makes one project able to emit both shapes of wheel. `setup.py`
+  holds the single decision, driven by `PATCHCRAFT_PURE_PYTHON` and
+  `PATCHCRAFT_REQUIRE_EXTENSION`; everything else stays declarative in
+  `pyproject.toml`. Installing from the sdist compiles the extension when a
+  Rust toolchain is present and degrades to a pure install when it is not.
+- License metadata follows PEP 639: the SPDX expression `MIT` with
+  `license-files`, and the superseded `License :: OSI Approved` classifier is
+  gone. setuptools rejects carrying both.
+
+### Added
+
+- **The version comes from the git tag.** `setuptools-scm` derives it at build
+  time, so no file in the source states a version, the release procedure loses
+  its bump step, and a tag and a release can no longer disagree.
+  `patchcraft.__version__` still works: the build writes a generated
+  `_version.py` that `__init__.py` imports, which costs nothing at import time,
+  with `importlib.metadata` as a fallback for a tree that was never built.
+  Measured before choosing: `importlib.metadata` alone was the wrong default,
+  because it took 56 ms on first call and reported a stale version in an
+  editable install.
+- `docs/PERFORMANCE.md`, which is where the accelerator's measurements live.
+  It carries the test machine, the versions, the date, the reproduction
+  command and what the numbers do not say, and its table is pasted from
+  `tools/benchmark.py --markdown` rather than retyped.
+- The Rust kernel is now always built in release mode, including in an
+  editable install. It was following the build command, so a development
+  checkout compiled a debug kernel: measured here, that turned a 14x speedup
+  into 2.1x, which made local benchmarks meaningless and made the accelerated
+  CI job exercise code no user runs.
+- `patchcraft.__version__` is re-exported explicitly, so `mypy --strict` in a
+  consuming project still accepts it. Moving it out of a literal and into an
+  import had quietly made it an implicit re-export, which strict mode rejects.
+- `tools/benchmark.py` measures the accelerated fold against the pure one and
+  refuses to report a timing unless the two results are bit-identical. The
+  numbers in the documentation come from it, and it is the reproduction
+  command they cite.
+- Every build checkout uses `fetch-depth: 0`. The default shallow clone hides
+  the tags, and setuptools-scm's fallback for that is a silent
+  `0.1.dev1+g<sha>`, a version that walks backwards rather than an error.
+- `tools/check_dist.py` grew `--expect-version` and `--require-universal`, and
+  it now rejects any artifact carrying a local version segment. PyPI refuses
+  those on upload, so this turns a late and confusing server-side rejection
+  into an early local one. It also fixes a bug in the job that checks the
+  native wheels, which demanded a universal wheel that job never has.
+- Linux aarch64 wheels, which the previous four-target matrix did not cover.
+- `tools/check_dist.py`, run before every upload. It fails the release if a
+  platform wheel lost its extension, which `optional=True` would otherwise
+  let through as a silently slow wheel, or if the universal wheel gained one.
+- The versioning policy now names the resolver rule it follows, which is that
+  `0.y` is the compatibility boundary in Cargo, npm and PEP 440 alike, and it
+  carries an errata for the two releases numbered before the rule was written.
+- Version numbers are gone from the documentation surface. The three cover
+  pages carry none at all, since the PyPI badge already shows the current
+  release, and the manual keeps only the one the citation entry needs. The
+  release archaeology those pages used to recite lives here, and the rest is
+  in the git history.
+- `MANIFEST.in`, which puts `accel/` in the sdist so the source path can build
+  the extension, and keeps `lab/`, `.superpowers/` and cargo's `target/` out.
+
+- **Corrected: the hand-rolled and library tile-and-blend results are not
+  bit-identical.** The three cover pages and GUIDE section 1 claimed they were,
+  and the GUIDE block asserted it. Re-measured: they agree to 1.17e-05 on a
+  value in [0, 1], differing on 24500 of 49152 elements. The cause is the 0.3.0
+  separable denominator, where `stitch` sums two 1-D window folds while the
+  hand-rolled twin folds a replicated 2-D kernel. `stitch(weight="uniform")`
+  is still bit-identical to `reconstruct`. Nothing about the round-trip
+  contract changed; the documentation was simply asserting more than the code
+  delivered.
+- Documentation corrections found by auditing every page against the code:
+  the changelog's reference links did not define the two most recent versions;
+  `docs/AUXILIARY.md` listed wheel contents that predate three releases;
+  `docs/SCOPE.md` still promised "pure-Python single-threaded", which the
+  rayon-parallel kernel contradicts; `docs/ROADMAP.md` still named hatchling;
+  GUIDE said the library "is not faster", that the no-zstandard branch is
+  untested, and that CI is six cells; the cover pages pointed at `USAGE.md` as
+  a walkthrough of 20 symbols when it covers 18 and says so. `CONTRIBUTING.md`
+  told a contributor to run `pytest` after a `uv sync` that does not install it.
+
+### Notes
+
+- No signature, no name and no output value changed. The public surface is the
+  same 20 names, still pinned by `tests/test_public_api.py`.
+- Measured on torch 2.14, CPU, mean over the dev machine: `reconstruct` at
+  3x512x512 p=32 s=16 goes 11.4 ms to 2.5 ms (4.5x), at 3x2048x2048 p=64 s=32
+  477.9 ms to 31.8 ms (15.0x); `stitch[hann]` 21.6 ms to 7.0 ms (3.1x) and
+  488.7 ms to 38.8 ms (12.6x). The gain is algorithmic rather than a thread
+  count: the pure `F.fold` measured between 365 and 465 ms on that largest
+  case at 4, 8, 16 and 36 torch threads.
+
 ## [0.5.0] - 2026-09-02
 
 ### Added
@@ -472,9 +587,12 @@ 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
+[Unreleased]: https://github.com/LeoPR/PatchCraft/compare/v0.5.1...HEAD
+[0.5.1]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.1
+[0.5.0]: https://github.com/LeoPR/PatchCraft/releases/tag/v0.5.0
+
+<!-- 0.4.0 and 0.3.0 are deliberately unlinked: they are source milestones that
+     were never tagged and never released, as their own entries say. -->
 [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

patchcraft-0.5.1/CONTRIBUTING.md

@@ -0,0 +1,270 @@
+# 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
+
+The test runner and the linters live in the `dev` extra, so a plain `uv sync`
+does not install them:
+
+```
+uv sync --locked --extra cache --extra dev
+```
+
+```
+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}` for the pure path, plus a second job on both operating systems for the accelerated one. To run the same checks locally before pushing:
+
+```
+ruff check src tests
+mypy --strict src
+pytest -m "not gpu"
+```
+
+---
+
+## The two paths
+
+The overlapping fold in `reconstruct` and `stitch` has a Rust implementation
+in [`accel/`](accel/), compiled into the wheel on the platforms CI builds for.
+Everything else runs the same operation in torch. The two are bit-identical by
+test, so a contribution has to keep both green rather than pick one.
+
+Which one your checkout runs depends on whether the extension got built:
+
+```
+python -c "import patchcraft; print(patchcraft.accel_available())"
+```
+
+`uv sync --extra cache --extra dev` builds it when a Rust toolchain is on
+PATH, always in release mode. Two environment variables override that, and CI
+sets both explicitly rather than relying on what happens to be installed:
+
+| Variable | Effect |
+|---|---|
+| `PATCHCRAFT_PURE_PYTHON=1` | Skip the extension. How the universal wheel is built. |
+| `PATCHCRAFT_REQUIRE_EXTENSION=1` | Make a Rust build failure fatal instead of degrading to the pure path. |
+| `PATCHCRAFT_ACCEL=0` | Runtime only: ignore an extension that is already built. |
+
+The Rust kernel has its own tests, which need no Python at all:
+
+```
+cargo test --manifest-path accel/Cargo.toml
+```
+
+One local wrinkle worth knowing. If your checkout sits under a path with
+non-ASCII characters, `setuptools-rust` mis-decodes the artifact path that
+cargo reports and the copy step fails. Point the build at an ASCII directory
+and it works:
+
+```
+CARGO_TARGET_DIR=/tmp/pc-target uv sync --extra cache --extra dev
+```
+
+---
+
+## Layout
+
+```
+PatchCraft/
+├── pyproject.toml                  package metadata, build backend, cibuildwheel targets
+├── setup.py                        the one build decision: with or without the Rust extension
+├── tools/check_dist.py             gate: extension present, versions agree, tag respected
+├── tools/benchmark.py              accelerated vs pure, and proves they agree first
+├── MANIFEST.in                     what the sdist carries
+├── 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 and the generated 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/                          the Rust crate compiled into this wheel (pyo3, setuptools-rust)
+│   ├── Cargo.toml                  crate metadata; the version there is internal
+│   ├── src/kernel.rs               the gather-fold kernel, pure Rust, cargo-tested
+│   ├── src/lib.rs                  pyo3 glue, exports patchcraft._accel_native
+│   └── README.md                   how to build it, and how to check it is active
+├── 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 extension was built
+│   ├── 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; the scripts themselves are not)
+│   └── .gitignore                  ignores everything else (tracked)
+├── docs/
+│   ├── GUIDE.md                    the manual, every README claim measured with its output
+│   ├── PERFORMANCE.md              what the accelerator is worth, and how to re-measure
+│   ├── 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.
+
+**While the project is pre-1.0, the middle digit is the compatibility
+boundary.** SemVer itself leaves `0.y.z` open, saying only that "anything MAY
+change at any time", so the meaning comes from the resolvers instead, and they
+agree: Cargo expands `^0.2.3` to `>=0.2.3, <0.3.0`, npm does the same, and
+PEP 440's `~=0.5.0` means `>=0.5.0, <0.6.0`. In every one of them a `0.y` bump
+is the announcement that something may break, and a `0.y.z` bump is the
+promise that nothing does.
+
+That fixes what each digit is for here:
+
+| Change | Bump | Why |
+|---|---|---|
+| An output value, a signature, a name or documented behaviour changes | `0.Y.0` | Resolvers stop at the y boundary, so this is where a break belongs |
+| New functionality that breaks nothing, or a fix | `0.y.Z` | Anyone pinned to the y-series should get it |
+| Documentation, tests, CI, packaging or tooling only | `0.y.Z` | Still a release if it is published, still no break |
+| Nothing published | nothing | Accumulate under `[Unreleased]` |
+
+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).
+
+### Errata
+
+The rule above was written after the fact, and two releases predate it.
+
+`0.4.0` should have been `0.3.1`. It added `accel_available()` and nothing
+else: no signature changed, and the accelerated path was bit-exact against the
+pure one. Additive and non-breaking is a z-bump under the boundary rule, and
+minting a y announced a break that never happened.
+
+`0.5.1` was briefly numbered `0.6.0` before release. It changes only how the
+package is built and shipped, so it is a z-bump.
+
+Two others were right and are worth recording as the shape to copy. `0.3.0`
+moved `stitch` output by ULPs through a different summation order, which is an
+output change and belongs at a y boundary. `0.5.0` made `tilings` return 73
+specs where it returned 100, which is squarely a break.
+
+The accelerator in [`accel/`](accel/) has no version of its own to manage. It
+is compiled into this wheel, so it ships when `patchcraft` ships. The version
+in `accel/Cargo.toml` is internal and nothing reads it; what the Python side
+actually checks is `_ABI_VERSION` in `accel/src/lib.rs`, and a mismatch there
+means a silent fall back to the pure path rather than a crash.
+
+---
+
+## Where the version comes from
+
+The git tag, and nowhere else. `setuptools-scm` derives it at build time, so
+no file in the source states a version and there is no literal to forget.
+`v0.5.1` produces `0.5.1`; the leading `v` is stripped for you.
+
+At build time setuptools-scm writes `src/patchcraft/_version.py`, which
+`__init__.py` imports and re-exports as `patchcraft.__version__`. That file is
+generated and gitignored, so a checkout that was never built falls back to
+`importlib.metadata` and then to `0+unknown`. The fallback exists so an
+un-built tree still imports; it is not a supported way to learn the version.
+
+Anything other than a clean tree sitting exactly on a tag produces a version
+with a local segment, like `0.5.2.dev0+gb4edfd81.d20260902` from a dirty tree
+or `0.1.dev1+gb4edfd81` from a checkout whose tags were never fetched. PyPI
+refuses local segments outright, so such a build can never be published by
+accident, and `tools/check_dist.py` rejects it before the upload rather than
+letting the upload fail.
+
+That last point is why every `actions/checkout` that builds uses
+`fetch-depth: 0`. The default shallow clone hides the tags, and the failure is
+silent: a version that walks backwards rather than an error.
+
+---
+
+## Releasing (maintainer only)
+
+1. Close the `[Unreleased]` section in [`CHANGELOG.md`](CHANGELOG.md) as `[X.Y.Z] YYYY-MM-DD`.
+2. Update the `version` field of the BibTeX entry in [`docs/GUIDE.md`](docs/GUIDE.md) section 9. It is the one version string left in the documentation, because a citation needs a concrete one.
+3. Update [`docs/ROADMAP.md`](docs/ROADMAP.md) milestone checkboxes.
+4. Commit: `release: vX.Y.Z`.
+5. Tag + push: `git tag -a vX.Y.Z -m "..."` then `git push origin vX.Y.Z`.
+6. `release.yml` fires automatically: validates, builds, publishes to PyPI via Trusted Publishing, then creates the GitHub Release with every artifact attached.
+
+There is no version to bump in step 4, and no way for a tag and a release to
+disagree. The `validate` job still cross-checks that setuptools-scm derived
+exactly what the tag says, which catches a dirty or shallow checkout before
+anything is built.
+
+One release produces one sdist and six wheels: five `cp312-abi3-<platform>`
+wheels with the Rust extension inside, and one `py3-none-any` wheel for
+everywhere else. `tools/check_dist.py` runs before the upload and fails the
+release if a platform wheel lost its extension, if the universal wheel gained
+one, if the artifacts disagree about the version, or if any of them is not the
+version the tag names. Publishing is a single project, so there is nothing to
+register on PyPI beyond the publisher that already exists.

patchcraft-0.5.1/MANIFEST.in

@@ -0,0 +1,37 @@
+# The sdist is the reproducible source snapshot: the product (`src/`, `accel/`)
+# plus the track that proves it works (`tests/`, `docs/`). `accel/` has to be
+# here, because an sdist build compiles it when a Rust toolchain is present.
+#
+# The `prune` lines below are load-bearing rather than decorative, and the
+# reason changed with setuptools-scm. Its file finder offers every git-tracked
+# file to the sdist, so this file stopped being an allowlist and became a
+# blocklist over everything git knows about. Measured: with no prune for it,
+# `.vscode/settings.json` reached the sdist.
+#
+# Note that `lab/` is only *mostly* ignored: `lab/README.md` and
+# `lab/.gitignore` are tracked, so the finder offers them and the prune is what
+# stops them. The rest of `lab/` is scratch work that no commit can reproduce,
+# and patchcraft-0.2.0.tar.gz shipped three such files to PyPI.
+#
+# Adding a tracked directory to this repository ships it to PyPI by default.
+# `tools/check_dist.py` holds the matching allowlist and will fail the release
+# for anything unexpected, which is the reminder to come back here.
+
+include LICENSE
+include CHANGELOG.md CONTRIBUTING.md
+include README.md README.pt-BR.md README.pypi.md
+include pyproject.toml setup.py uv.lock .python-version
+
+recursive-include src *.py
+include src/patchcraft/py.typed
+recursive-include tests *.py
+recursive-include docs *.md
+recursive-include accel *.rs *.toml *.lock *.md
+prune accel/target
+recursive-include tools *.py
+
+prune lab
+prune archive
+prune .superpowers
+prune .github
+prune .vscode

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

@@ -1,45 +1,44 @@
-Metadata-Version: 2.5
+Metadata-Version: 2.4
 Name: patchcraft
-Version: 0.5.0
+Version: 0.5.1
 Summary: Image patch extraction, reconstruction, pairing and seam-aware stitching for super-resolution and dataset pipelines.
+Author: Leonardo Marques de Souza
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/LeoPR/PatchCraft
 Project-URL: Repository, https://github.com/LeoPR/PatchCraft
 Project-URL: Issues, https://github.com/LeoPR/PatchCraft/issues
 Project-URL: Changelog, https://github.com/LeoPR/PatchCraft/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/LeoPR/PatchCraft/blob/main/docs/GUIDE.md
-Author: Leonardo Marques de Souza
-License-Expression: MIT
-License-File: LICENSE
-Keywords: dataset,image,patches,super-resolution,torch
+Keywords: image,patches,super-resolution,dataset,torch
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 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: Programming Language :: Rust
 Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
 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'
+Requires-Dist: pillow>=10
 Provides-Extra: cache
-Requires-Dist: zstandard>=0.22; extra == 'cache'
+Requires-Dist: zstandard>=0.22; extra == "cache"
 Provides-Extra: dev
-Requires-Dist: mypy>=1.10; extra == 'dev'
-Requires-Dist: pytest-cov; extra == 'dev'
-Requires-Dist: pytest>=8; extra == 'dev'
-Requires-Dist: ruff>=0.5; extra == 'dev'
-Requires-Dist: torchvision>=0.20; extra == 'dev'
-Description-Content-Type: text/markdown
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: torchvision>=0.20; extra == "dev"
+Dynamic: license-file
 
 # PatchCraft
 
@@ -81,16 +80,17 @@ pip install patchcraft
 pip install "patchcraft[cache]"     # adds zstandard, which compresses Cache payloads
 ```
 
-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]
-```
+There is nothing else to install for speed. On Windows x64, Linux x86_64 and
+aarch64, and both macOS architectures, the wheel carries a Rust accelerator for
+the overlapping fold, which is where `reconstruct` and `stitch` spend their
+time. Every other platform gets the universal wheel and runs the pure-torch
+paths, which return the same values.
 
-`patchcraft.accel_available()` reports at runtime whether the accelerator is
-active; `PATCHCRAFT_ACCEL=0` in the environment forces the pure path.
+`patchcraft.accel_available()` reports at runtime which one you got, and
+`PATCHCRAFT_ACCEL=0` in the environment forces the pure path. On the overlapping
+fold it is worth between 2.6x and 14x on the machine it was measured on, which
+the [performance page](https://github.com/LeoPR/PatchCraft/blob/main/docs/PERFORMANCE.md)
+reports in full.
 
 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.
 
@@ -144,7 +144,7 @@ assert scrambled.shape == patches.shape                      # the right shape
 assert not torch.equal(scrambled, patches)                   # and the wrong pixels
 ```
 
-The saving is real on the other side too. Tiling an image, running a per-patch model and blending the result back with a Hann window took 17 non-blank lines by hand against 3 with `extract` and `stitch`, and the two outputs were bit-identical.
+The saving is real on the other side too. Tiling an image, running a per-patch model and blending the result back with a Hann window took 17 non-blank lines by hand against 3 with `extract` and `stitch`, and the two outputs agreed to about 1.2e-05 on a value in [0, 1].
 
 ## The geometry has to cover the image
 
@@ -170,14 +170,15 @@ The everyday shorthand is that `stride == patch_size` and `stride == patch_size
 
 ## Status
 
-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.
+This is pre-1.0, so both the output values and the API shape can still move. While the leading digit is zero the middle one is the compatibility boundary, which makes a new `0.y.z` safe to take and a new `0.y` the place where a change is allowed to land, and the [changelog](https://github.com/LeoPR/PatchCraft/blob/main/CHANGELOG.md) records each one 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 20 public symbols
+- [Performance](https://github.com/LeoPR/PatchCraft/blob/main/docs/PERFORMANCE.md), what the native accelerator is worth and how to re-measure it
+- [Usage](https://github.com/LeoPR/PatchCraft/blob/main/docs/USAGE.md), a walkthrough of the public surface, captured against an older release
 - [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)

{patchcraft-0.5.0 → patchcraft-0.5.1}/README.md

@@ -39,16 +39,16 @@ pip install patchcraft
 pip install "patchcraft[cache]"     # adds zstandard, which compresses Cache payloads
 ```
 
-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):
+There is nothing else to install for speed. On Windows x64, Linux x86_64 and
+aarch64, and both macOS architectures, the wheel carries a Rust accelerator for
+the overlapping fold, which is where `reconstruct` and `stitch` spend their
+time. Every other platform gets the universal wheel and runs the pure-torch
+paths, which return the same values.
 
-```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.
+`patchcraft.accel_available()` reports at runtime which one you got, and
+`PATCHCRAFT_ACCEL=0` in the environment forces the pure path. On the overlapping
+fold it is worth between 2.6x and 14x here, measured in
+[docs/PERFORMANCE.md](docs/PERFORMANCE.md).
 
 The distribution name and the import name are both `patchcraft`. The runtime dependencies are `torch>=2.6`, `numpy>=1.26` and `pillow>=10`, and the supported Python versions are in [the guide](docs/GUIDE.md#9-install-details-and-citation) together with the note you need before you install a GPU wheel.
 
@@ -77,7 +77,7 @@ That is the whole loop. You extract, you do your work per patch, and then you co
 
 The two functions answer two different questions, so choosing between them is the first decision you make.
 
-`reconstruct` is the inverse. It assumes the patches still hold the pixels `extract` gave you, it divides by the count map, and on a covering geometry it hands the image back unchanged.
+`reconstruct` is the inverse. It assumes the patches still hold the pixels `extract` gave you, it divides by the count map, and on the geometries described further down it hands the image back unchanged.
 
 `stitch` is for patches a model rewrote. Neighbouring patches now disagree about the pixels they share, and uniform averaging leaves that disagreement visible as a grid of seams, so `stitch` weights each patch by a window that fades toward its border.
 
@@ -108,7 +108,7 @@ assert not torch.equal(scrambled, patches)                   # and the wrong pix
 
 The second one is a stride that does not cover the image. On a 128 by 128 image with `patch=32, stride=20` the grid stops at pixel 112, which leaves 3840 of the 16384 pixels at zero, and a hand-rolled `fold` returns that partly black image without complaining.
 
-Writing the tile-and-blend loop by hand costs 17 non-blank lines against 3 here, and the two results are bit-identical. [The guide](docs/GUIDE.md#1-why-not-unfold-and-fold-directly) runs both versions side by side.
+Writing the tile-and-blend loop by hand costs 17 non-blank lines against 3 here, and the two results agree to about 1.2e-05 on a value in [0, 1], the two routes differing only in the order they sum a separable window. [The guide](docs/GUIDE.md#1-why-not-unfold-and-fold-directly) runs both versions side by side.
 
 ## The geometry has to cover the image
 
@@ -144,7 +144,7 @@ The round trip is exact when every value in the count map is a power of two, whi
 
 ## Status
 
-**0.5.0, pre-1.0.** Output values can still change in a minor release, and [CHANGELOG.md](CHANGELOG.md) records each change with the measurement behind it.
+**Pre-1.0**, and the badge above is the current release. While the leading digit is zero the middle one is the compatibility boundary, so `0.y.z` is safe to take and a new `0.y` is where an output value or a signature is allowed to move. [CHANGELOG.md](CHANGELOG.md) records every such change with the measurement behind it.
 
 1571 tests collected and CI is green on {Ubuntu, Windows} x {Python 3.12, 3.13, 3.14}, with `ruff check` and `mypy --strict` in the same run. The package is typed and ships `py.typed`.
 
@@ -155,7 +155,8 @@ No external project has consumed it yet, and no CUDA path in this library has ev
 | If you want | Open |
 |---|---|
 | The manual: every argument above, measured, with its output | [docs/GUIDE.md](docs/GUIDE.md) |
-| A walkthrough of each of the 20 public symbols | [docs/USAGE.md](docs/USAGE.md) |
+| What the native accelerator is worth, and how to re-measure it | [docs/PERFORMANCE.md](docs/PERFORMANCE.md) |
+| A walkthrough of the public surface, captured against an older release | [docs/USAGE.md](docs/USAGE.md) |
 | The line between this library and your pipeline | [docs/SCOPE.md](docs/SCOPE.md) |
 | The math, the decisions and the per-function contract | [docs/THEORY.md](docs/THEORY.md) |
 | Why the API looks like this | [docs/ADR/](docs/ADR) |