gbskernels 0.2.0__tar.gz → 0.2.1__tar.gz

gbskernels-0.2.1/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+## [0.2.1] - 2026-07-24
+
+### Correctness
+
+- Add explicit absolute underflow terms to the certified FP64 and
+  double-double permanent, hafnian, loop-hafnian, and recursive-torontonian
+  recurrences.
+  Per-operation propagation now encloses mixed-scale products where an
+  intermediate underflows and a later factor amplifies the lost term.
+- Replace assumed forward constants for double-double division and square root
+  with outward FMA residual bounds on the values actually returned. Complex
+  division refuses denominator, numerator-product, and dot-product ranges that
+  cannot be enclosed safely, and preserves tiny numerator uncertainty through
+  large quotient amplification.
+- Preserve `+inf` refusal through host subtree reductions. Certified Python
+  APIs now reject non-finite inputs and refuse non-finite values, negative or
+  non-finite bounds, and invalid tolerances; an explicit `rtol` may escalate a
+  refused certificate to an independently computed finite reference value.
+- Make `tor_single` fail before GPU dispatch unless its real binary64 input is
+  finite and exactly symmetric. The recursive Cholesky walk consumes one
+  triangle, so silently accepting a nonsymmetric matrix made the evaluated
+  problem depend on storage convention.
+- Explicitly symmetrize the xxpp Husimi covariance and returned
+  `threshold_O_xxpp` matrix after binary64 linear algebra, satisfying the new
+  single-large input contract without retaining inversion roundoff skew.
+- Replace the historical Jiuzhang fixed-sample summary with its actual
+  finite-population stratified estimand. Remove pseudo-confirmatory intervals
+  and normalizer significance calculations that could not be justified from
+  the retained inputs; report the event standard error, normalizer diagonal
+  sensitivity, and arithmetic proxy separately.
+
+### Reproducibility
+
+- Extend artifact provenance with the full Git commit and a tracked-dirty
+  indicator, so output generated from modified tracked sources cannot be
+  attributed to a clean release commit.
+- Package the deterministic historical selector, aggregator, decoder audit,
+  five retained checkpoint JSONL files, and a hash-bound regenerated
+  selection/result pair under `results/jiuzhang/legacy_fixed_sample/`.
+- The retained checkpoint rows predate the common provenance schema and do not
+  contain recoverable original GPU, container, driver, or commit metadata. The
+  release preserves their exact hashes and records current provenance for the
+  audit artifacts; it does not invent missing historical environment data.
+
+### Scope
+
+- The historical fixed sample was selected and evaluated during exploratory
+  development. It is not held out, preregistered, or confirmatory, and this
+  correction does not turn it into a confirmatory scientific result.
+- The v0.2.1 tag is conditioned on a clean-tree release-validation session:
+  all 24 device gates, the Python binding smoke, adversarial and physical
+  enclosure coverage, and the Jiuzhang Gate C probe. The GitHub release carries
+  a hash-bound validation manifest for the exact tagged commit. Retained v0.2.0
+  RTX 4090 evidence remains historical rather than validation of v0.2.1.
+
+## [0.2.0] - 2026-07-22
+
+### Important Correction
+
+- Replace the legacy Jiuzhang state reconstruction with the published
+  paired-source Q7 construction and the exact real xxpp threshold-torontonian
+  matrix. The two v0.1 frontier JSON files remain historical artifacts and are
+  rejected by the current figure tooling.
+
+### Added
+
+- A fail-closed Jiuzhang confirmatory-v2 workflow covering exposure-ledger
+  audit, outcome-blind design, immutable public registration and beacon-derived
+  selection, content-addressed evaluation, refusal recovery,
+  reconstruction/calibration uncertainty, joint normalizer replicates,
+  absolute predictive checks, simultaneous coherence-grid inference, and
+  hash-verified release bundles.
+- Canonical registration, design, and exposure templates plus focused contract
+  and regression tests for the workflow and exact xxpp construction.
+
+### Fixed
+
+- Harden certified recursive-torontonian bounds with directed downward
+  subtraction, sound double-double magnitude bounds, and explicit
+  double-double-to-FP64 collapse residual accounting, plus a dedicated
+  enclosure gate.
+
+### Scope
+
+- This release provides code, templates, and validation contracts. It contains
+  no completed v2 registration or new scientific outcome; external calibration,
+  public timestamp/beacon evidence, and acquisition inputs remain required.
+
+[0.2.1]: https://github.com/chaofanzhougit/GBSKernels/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/chaofanzhougit/GBSKernels/compare/v0.1.1...v0.2.0

{gbskernels-0.2.0 → gbskernels-0.2.1}/CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 message: "If you use this software, please cite it as below."
 title: "GBSKernels: a GPU-native, batched library of photonic sampling matrix functions"
-version: 0.2.0
-date-released: 2026-07-22
+version: 0.2.1
+date-released: 2026-07-24
 license: Apache-2.0
 repository-code: "https://github.com/chaofanzhougit/GBSKernels"
 authors:

{gbskernels-0.2.0 → gbskernels-0.2.1}/MANIFEST.in

@@ -7,7 +7,9 @@ graft examples
 graft docs
 graft scripts
 graft envs
-include LICENSE README.md CHANGELOG.md CITATION.cff pyproject.toml
+graft tests
+graft results/jiuzhang/legacy_fixed_sample
+include LICENSE README.md CHANGELOG.md CITATION.cff THIRD_PARTY_NOTICES.md pyproject.toml uv.lock
 prune core/build
 prune core/build_prof
 prune bindings/build

{gbskernels-0.2.0 → gbskernels-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gbskernels
-Version: 0.2.0
+Version: 0.2.1
 Summary: GPU-native, batched library of photonic sampling matrix functions (hafnian, loop hafnian, permanent, torontonian).
 Author-email: Chaofan Zhou <chaofanzhou97@gmail.com>
 License-Expression: Apache-2.0
@@ -44,24 +44,31 @@ companion with an explicit accuracy characterization. The Walrus is used here as
 one of several independent test oracles.
 
 > **Status.** The CPU library is complete and `pip`-installable (pure Python,
-> `numpy` + `mpmath` only). Historical release validation covers NVIDIA hardware
-> (RTX 4090, A100); the v0.2 changes pass the CPU host-shim gates and still require
-> a fresh on-device validation session. This is pre-1.0 software and the public
-> API may change.
-
-Version 0.2.0 adds the fail-closed Jiuzhang confirmatory workflow and corrects
-the real threshold-torontonian construction used by the Jiuzhang examples. See
-the [changelog](CHANGELOG.md) for the release scope and compatibility notes.
+> `numpy` + `mpmath` only). A v0.2.1 tag is released only with a clean-tree GPU
+> validation manifest covering all 24 device gates, the Python binding smoke,
+> adversarial and physical enclosure families, and the Jiuzhang Gate C probe.
+> The manifest and its hash-bound evidence are attached to the GitHub release
+> and identify the exact commit. Historical v0.2.0 RTX 4090 and A100 evidence is
+> retained separately; see the [device evidence](results/README.md#v020-device-validation).
+> This is pre-1.0 software and the public API may change.
+
+Version 0.2.1 is a correctness patch that adds subnormal-aware certified bounds
+and fail-closed certificate handling, makes the single-large real torontonian
+input contract explicit, removes inversion roundoff skew from the xxpp
+construction, records whether artifacts came from modified tracked sources,
+and packages the corrected historical Jiuzhang fixed-sample audit. That audit
+is exploratory, not a retrospective confirmatory result. See the
+[changelog](CHANGELOG.md) for the release scope.
 
 ## Installation
 
-Not yet on PyPI; install from source. The CPU backend needs only `numpy` +
-`mpmath`; the CUDA extension is a separate, optional build (see
+The CPU package is available from
+[PyPI](https://pypi.org/project/gbskernels/0.2.1/) and needs only `numpy` +
+`mpmath`. The CUDA extension is a separate, optional source build (see
 [`bindings/README.md`](bindings/README.md)):
 
 ```bash
-uv build                        # -> dist/gbskernels-*.whl, then pip install it
-# pip install gbskernels        # planned once published to PyPI
+python -m pip install gbskernels==0.2.1
 ```
 
 ## Quick start
@@ -103,7 +110,7 @@ implicit:
 | `"dd"` | Double-double arithmetic carried internally through the cancelling sum (a GPU tier); recovers a correct double-precision result where plain double precision cancels. |
 | `"ref"` | Arbitrary-precision reference (`mpmath`); the accuracy ground truth. |
 | `"auto"` | Double precision plus a per-evaluation cancellation indicator; evaluations flagged as risky are recomputed in a higher tier (`mpmath` on CPU, double-double on GPU). The indicator is a calibrated heuristic, not a certificate. |
-| `"certified"` | The double-precision value together with a **rigorous a-posteriori error bound**: `\|value − exact\| ≤ abs_error_bound`, a running error bound in the standard model of floating-point arithmetic (on the GPU, the bound arithmetic uses per-instruction directed rounding). Available for all four functions on CPU and GPU. With `rtol=`, a failed certified-fp64 bound escalates to the arbitrary-precision reference; GPU permanent and hafnian first try a certified double-double bound. The reference result is flagged as non-certified. `tor_single(..., dd=True)` provides a separate certified-double-double large-torontonian path. |
+| `"certified"` | The double-precision value together with a **rigorous a-posteriori error bound**: `\|value − exact\| ≤ abs_error_bound`, including explicit absolute terms for subnormal underflow (on the GPU, bound arithmetic uses per-instruction directed rounding). Non-finite inputs and invalid/non-finite certificates fail closed. Available for all four functions on CPU and GPU. With `rtol=`, a failed or refused certified-fp64 result escalates to the arbitrary-precision reference; GPU permanent and hafnian first try a certified double-double bound. The reference result is flagged as non-certified. `tor_single(..., dd=True)` provides a separate certified-double-double large-torontonian path. |
 
 ## Features
 
@@ -161,6 +168,15 @@ The Jiuzhang v2 tooling adds workflow-contract tests for canonical hashing,
 registration timing, exclusion-ledger completeness, selection, immutable run
 reduction, refusal recovery, inference, reconstruction, and release assembly.
 
+To run the public v0.2.1 GPU validation from a fresh clone, first stage the
+small hash-bound inputs (the raw USTC and Zenodo archives remain
+external; see [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) for data
+attribution and licensing scope):
+
+```bash
+python scripts/prepare_validation_data.py
+```
+
 The development discipline is CPU-first: host-shim-compatible CUDA kernels are
 compiled and run through the CPU pre-flight (part of the test suite), then the
 full source set is checked on-device against independent CPU references before

{gbskernels-0.2.0 → gbskernels-0.2.1}/README.md

@@ -22,24 +22,31 @@ companion with an explicit accuracy characterization. The Walrus is used here as
 one of several independent test oracles.
 
 > **Status.** The CPU library is complete and `pip`-installable (pure Python,
-> `numpy` + `mpmath` only). Historical release validation covers NVIDIA hardware
-> (RTX 4090, A100); the v0.2 changes pass the CPU host-shim gates and still require
-> a fresh on-device validation session. This is pre-1.0 software and the public
-> API may change.
-
-Version 0.2.0 adds the fail-closed Jiuzhang confirmatory workflow and corrects
-the real threshold-torontonian construction used by the Jiuzhang examples. See
-the [changelog](CHANGELOG.md) for the release scope and compatibility notes.
+> `numpy` + `mpmath` only). A v0.2.1 tag is released only with a clean-tree GPU
+> validation manifest covering all 24 device gates, the Python binding smoke,
+> adversarial and physical enclosure families, and the Jiuzhang Gate C probe.
+> The manifest and its hash-bound evidence are attached to the GitHub release
+> and identify the exact commit. Historical v0.2.0 RTX 4090 and A100 evidence is
+> retained separately; see the [device evidence](results/README.md#v020-device-validation).
+> This is pre-1.0 software and the public API may change.
+
+Version 0.2.1 is a correctness patch that adds subnormal-aware certified bounds
+and fail-closed certificate handling, makes the single-large real torontonian
+input contract explicit, removes inversion roundoff skew from the xxpp
+construction, records whether artifacts came from modified tracked sources,
+and packages the corrected historical Jiuzhang fixed-sample audit. That audit
+is exploratory, not a retrospective confirmatory result. See the
+[changelog](CHANGELOG.md) for the release scope.
 
 ## Installation
 
-Not yet on PyPI; install from source. The CPU backend needs only `numpy` +
-`mpmath`; the CUDA extension is a separate, optional build (see
+The CPU package is available from
+[PyPI](https://pypi.org/project/gbskernels/0.2.1/) and needs only `numpy` +
+`mpmath`. The CUDA extension is a separate, optional source build (see
 [`bindings/README.md`](bindings/README.md)):
 
 ```bash
-uv build                        # -> dist/gbskernels-*.whl, then pip install it
-# pip install gbskernels        # planned once published to PyPI
+python -m pip install gbskernels==0.2.1
 ```
 
 ## Quick start
@@ -81,7 +88,7 @@ implicit:
 | `"dd"` | Double-double arithmetic carried internally through the cancelling sum (a GPU tier); recovers a correct double-precision result where plain double precision cancels. |
 | `"ref"` | Arbitrary-precision reference (`mpmath`); the accuracy ground truth. |
 | `"auto"` | Double precision plus a per-evaluation cancellation indicator; evaluations flagged as risky are recomputed in a higher tier (`mpmath` on CPU, double-double on GPU). The indicator is a calibrated heuristic, not a certificate. |
-| `"certified"` | The double-precision value together with a **rigorous a-posteriori error bound**: `\|value − exact\| ≤ abs_error_bound`, a running error bound in the standard model of floating-point arithmetic (on the GPU, the bound arithmetic uses per-instruction directed rounding). Available for all four functions on CPU and GPU. With `rtol=`, a failed certified-fp64 bound escalates to the arbitrary-precision reference; GPU permanent and hafnian first try a certified double-double bound. The reference result is flagged as non-certified. `tor_single(..., dd=True)` provides a separate certified-double-double large-torontonian path. |
+| `"certified"` | The double-precision value together with a **rigorous a-posteriori error bound**: `\|value − exact\| ≤ abs_error_bound`, including explicit absolute terms for subnormal underflow (on the GPU, bound arithmetic uses per-instruction directed rounding). Non-finite inputs and invalid/non-finite certificates fail closed. Available for all four functions on CPU and GPU. With `rtol=`, a failed or refused certified-fp64 result escalates to the arbitrary-precision reference; GPU permanent and hafnian first try a certified double-double bound. The reference result is flagged as non-certified. `tor_single(..., dd=True)` provides a separate certified-double-double large-torontonian path. |
 
 ## Features
 
@@ -139,6 +146,15 @@ The Jiuzhang v2 tooling adds workflow-contract tests for canonical hashing,
 registration timing, exclusion-ledger completeness, selection, immutable run
 reduction, refusal recovery, inference, reconstruction, and release assembly.
 
+To run the public v0.2.1 GPU validation from a fresh clone, first stage the
+small hash-bound inputs (the raw USTC and Zenodo archives remain
+external; see [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) for data
+attribution and licensing scope):
+
+```bash
+python scripts/prepare_validation_data.py
+```
+
 The development discipline is CPU-first: host-shim-compatible CUDA kernels are
 compiled and run through the CPU pre-flight (part of the test suite), then the
 full source set is checked on-device against independent CPU references before

gbskernels-0.2.1/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,27 @@
+# Third-party validation data
+
+The Apache-2.0 license for GBSKernels source code does not relicense the
+third-party scientific data under `examples/jiuzhang/validation_data/`.
+
+The files `click_probs_squeezed_0.npy` and
+`click_probs_squashed_0.npy` are retained Jiuzhang 1.0 probability arrays from:
+
+- Javier Martinez-Cifuentes, Karen Milena Fonseca-Romero, and Nicolas Quesada,
+  "Classical models are a better explanation of the Jiuzhang 1.0 Gaussian
+  Boson Sampler than its targeted squeezed light model," Zenodo record
+  [7194775](https://doi.org/10.5281/zenodo.7194775), licensed
+  [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+The files `T_full.npy`, `events_band13_32.npy`,
+`squeezing parameters.txt`, and `empirical_click_rates.npy` are small derived
+validation inputs from the Jiuzhang 1.0 data published by Han-Sen Zhong et al.:
+
+- [Experimental raw data of "Quantum computational advantage using
+  photons"](https://quantum.ustc.edu.cn/web/en/node/915), University of Science
+  and Technology of China, 2020.
+
+The USTC page makes the raw data publicly downloadable but does not state a
+separate data license. These derived inputs are included for validation,
+attribution, and reproducibility; no Apache-2.0 license is asserted over the
+underlying USTC data. Every redistributed or derived file is bound to the
+SHA-256 digest in `scripts/prepare_validation_data.py`.

{gbskernels-0.2.0 → gbskernels-0.2.1}/bench/_provenance.py

@@ -77,6 +77,25 @@ def commit() -> str | None:
         return None
 
 
+def git_state() -> dict[str, Any]:
+    """Record whether local tracked bytes are exactly represented by a commit."""
+    env_commit = os.environ.get("GBS_COMMIT", "").strip()
+    if env_commit:
+        return {"commit": env_commit, "tracked_dirty": None, "source": "GBS_COMMIT"}
+    try:
+        full = subprocess.run(
+            ["git", "rev-parse", "HEAD"], capture_output=True, text=True, timeout=10
+        ).stdout.strip()
+        if not full:
+            return {"commit": None, "tracked_dirty": None, "source": "unavailable"}
+        dirty = subprocess.run(
+            ["git", "diff", "--quiet", "HEAD", "--"], timeout=10
+        ).returncode != 0
+        return {"commit": full, "tracked_dirty": dirty, "source": "git"}
+    except Exception:
+        return {"commit": None, "tracked_dirty": None, "source": "unavailable"}
+
+
 def container_digest() -> str | None:
     """The pinned container image digest the run was launched from (or None)."""
     env = os.environ.get("GBS_CONTAINER_DIGEST", "").strip()
@@ -95,8 +114,10 @@ def container_digest() -> str | None:
 def provenance() -> dict[str, Any]:
     """The common provenance block embedded in every artifact (commit + container digest +
     machine environment), so a result reproduces from the file alone (docs/DESIGN.md §9)."""
+    state = git_state()
     return {
         "commit": commit(),
+        "git": state,
         "container_digest": container_digest(),
         "hostname": platform.node() or None,
         "captured_utc": datetime.now(timezone.utc).isoformat(),

{gbskernels-0.2.0 → gbskernels-0.2.1}/core/README.md

@@ -28,6 +28,14 @@ and run on the CPU (`core/preflight/`, exercised by the test suite via
 against independent CPU references. Device-only variants, including
 `permanent_warp.cu`, are validated in the CUDA session rather than the host shim.
 
+**Certified arithmetic is relative-plus-absolute.** Every recurrence includes
+an explicit binary64 subnormal floor, and mixed-scale products propagate that
+absolute error through later factors. Double-double division and square root
+are bounded from outward FMA residuals of the values actually returned rather
+than assumed forward constants. Unsafe division ranges and any non-finite or
+negative certificate refuse instead of producing a finite claim; see
+[`docs/dd_certificate_proof.md`](../docs/dd_certificate_proof.md).
+
 **Execution model.** The default kernels evaluate one instance per thread and
 batch across the grid. Only the permanent uses the Gray-code delta walk; the
 hafnian, loop hafnian, and torontonian enumerate the `2^k` subsets independently,
@@ -41,7 +49,8 @@ inputs.
 **Size limits** (fixed per-thread buffers): permanent ≤ 28, hafnian ≤ 20 (double-
 double ≤ 16), loop hafnian ≤ 20 (double-double ≤ 14), torontonian 2n ≤ 24; larger
 inputs are rejected at the Python boundary. The single-large recursive torontonian
-extends to dimension 64.
+extends to dimension 64 and requires a finite matrix that is exactly symmetric
+after conversion to binary64, because its Cholesky walk consumes one triangle.
 
 ### Build and run