paulikit 0.1.0__tar.gz

paulikit-0.1.0/.github/workflows/paulikit-wheels.yml

@@ -0,0 +1,160 @@
+# Build manylinux wheels for paulikit (sdist is a separate job in this
+# workflow). Config lives in pyproject.toml under [tool.cibuildwheel]:
+# Linux x86_64 + aarch64, CPython 3.10-3.13, musllinux/Windows/macOS
+# skipped by design.
+#
+# Runs on the GitHub mirror (github.com/beavernets-inc/paulikit). Codeberg
+# (codeberg.org/beavernets/paulikit) is the canonical repository;
+# hosted Forgejo Actions runners are not used for this matrix (need
+# Docker-capable manylinux builds). Manual or tag-triggered only —
+# not on every push. Kernel import gates (wht_native / coeffs_native /
+# gather_native) run inside cibuildwheel's test-command so a wheel
+# without the transform path fails the job.
+#
+# Publish: prefer Trusted Publishing (OIDC). Optional fallback: set
+# environment secret TEST_PYPI_API_TOKEN or PYPI_API_TOKEN (pypi.org
+# "API token" with upload scope) on the matching GitHub Environment.
+# Do not commit tokens.
+
+name: paulikit wheels
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: "Upload built artifacts"
+        type: choice
+        options:
+          - none
+          - testpypi
+          - pypi
+        default: none
+
+jobs:
+  build_wheels:
+    name: Wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - ubuntu-24.04-arm
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v4.2.1
+        with:
+          package-dir: .
+          output-dir: wheelhouse
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: paulikit-wheels-${{ matrix.os }}-${{ strategy.job-index }}
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist
+        run: |
+          python -m pip install --upgrade build
+          python -m build --sdist --outdir dist
+
+      - name: Sanity-check sdist contents
+        run: |
+          python - <<'PY'
+          import tarfile
+          from pathlib import Path
+          sdists = list(Path("dist").glob("*.tar.gz"))
+          assert len(sdists) == 1, sdists
+          names = tarfile.open(sdists[0]).getnames()
+          banned = ("plans/", "profiling/", ".worktrees/", "PYPI_RELEASE")
+          hits = [n for n in names if any(b in n for b in banned)]
+          assert not hits, f"sdist carries private/research paths: {hits[:20]}"
+          print(f"ok: {sdists[0].name} ({len(names)} entries)")
+          PY
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: paulikit-sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: Publish package
+    needs: [build_wheels, build_sdist]
+    if: >
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v'))
+      || (github.event_name == 'workflow_dispatch'
+          && inputs.publish != 'none')
+    runs-on: ubuntu-latest
+    environment:
+      name: ${{ (github.event_name == 'workflow_dispatch' && inputs.publish == 'testpypi') && 'testpypi' || 'pypi' }}
+      url: ${{ (github.event_name == 'workflow_dispatch' && inputs.publish == 'testpypi') && 'https://test.pypi.org/project/paulikit/' || 'https://pypi.org/project/paulikit/' }}
+    permissions:
+      id-token: write
+    env:
+      # Resolved when the job starts (safe to branch on in step if:).
+      TEST_PYPI_API_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN }}
+      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: paulikit-*
+          merge-multiple: true
+          path: dist
+
+      - name: Show artifacts
+        run: ls -la dist
+
+      - name: Publish to TestPyPI (Trusted Publishing)
+        if: github.event_name == 'workflow_dispatch' && inputs.publish == 'testpypi' && env.TEST_PYPI_API_TOKEN == ''
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist
+
+      - name: Publish to TestPyPI (API token)
+        if: github.event_name == 'workflow_dispatch' && inputs.publish == 'testpypi' && env.TEST_PYPI_API_TOKEN != ''
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist
+          user: __token__
+          password: ${{ env.TEST_PYPI_API_TOKEN }}
+
+      - name: Publish to PyPI (Trusted Publishing)
+        if: >
+          ((github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v'))
+            || (github.event_name == 'workflow_dispatch' && inputs.publish == 'pypi'))
+          && env.PYPI_API_TOKEN == ''
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+
+      - name: Publish to PyPI (API token)
+        if: >
+          ((github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v'))
+            || (github.event_name == 'workflow_dispatch' && inputs.publish == 'pypi'))
+          && env.PYPI_API_TOKEN != ''
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          user: __token__
+          password: ${{ env.PYPI_API_TOKEN }}

paulikit-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+
+# Virtual environments
+.venv/
+venv/
+
+# Build and packaging artefacts
+build/
+dist/
+*.egg-info/
+.mesonpy-*/
+*.so
+
+# Generated by ./configure; Makefile.in is the source template.
+# Anchored to the root: docs/Makefile is a checked-in source file that
+# Sphinx needs, and `make clean` tests for its presence.
+/Makefile
+config.log
+config.status
+
+# Test and tooling caches
+.pytest_cache/
+.ruff_cache/
+
+# Sphinx output
+docs/_build/
+
+# Local agent plans/specs and git worktrees — never ship these.
+plans/
+.worktrees/
+
+# Lockfiles are deliberately not tracked: this is a library, not an
+# application, so pinning a resolved dependency set here would
+# constrain downstreams without benefiting them.
+uv.lock
+poetry.lock

paulikit-0.1.0/AUTHORS

@@ -0,0 +1,17 @@
+paulikit was written by:
+
+    Mohammadreza Khellat
+    Mohammad Masoumi
+    Saman Nasouri
+    Soroush Nasouri
+
+all at Beavernets Technologies.
+
+The citation order, and the metadata to use when citing this software
+in published work, are in CITATION.cff. That file is the authoritative
+record; this one exists because the GNU Coding Standards expect an
+AUTHORS file, and because a reader looking for "who wrote this" should
+not have to know what CITATION.cff is.
+
+Contributors are credited in the git history. Substantial ongoing
+contributors will be added here on request.

paulikit-0.1.0/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+While the version is 0.x, the public API may change between minor
+versions; see the README's Status section.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-26
+
+First public release (PyPI target). Package contents were prepared
+2026-09-10; this dated entry is the freeze for the first tagged /
+uploaded artifacts.
+
+### Added
+
+- **Pauli decomposition by fast Walsh-Hadamard transform.**
+  `paulikit.algorithms.fwht` decomposes any $2^n \times 2^n$ complex matrix
+  into its Pauli-basis coefficients in $O(n \cdot 4^n)$. Hermitian and
+  non-Hermitian input take the same transform; `assume_hermitian=True`
+  (the default) returns real coefficients and verifies the input
+  really is Hermitian rather than assuming it.
+
+- **Bounded memory.** The active-x set is chunked and each chunk is
+  thresholded and emitted before the next is computed, so peak
+  resident memory is set by `chunk_size` rather than by the size of
+  the result. Sparse input is kept sparse throughout.
+
+- **Streaming entry points.** `fwht_pauli_terms_iter` and
+  `parallel_decompose_arrays` yield per chunk, so a caller can consume
+  and discard results that would not fit in memory if accumulated.
+
+- **Multi-core execution.** `parallel_decompose` and
+  `parallel_decompose_arrays` distribute independent chunks across a
+  process pool or a thread pool. Worker count is taken from the CPUs
+  actually available to the process rather than from `os.cpu_count()`,
+  so a cgroup- or cpuset-restricted machine is not oversubscribed.
+  Threaded drain (`executor="thread"` / `"auto"`) uses physical-core
+  pinning, capacity-weighted slices, work-stealing, and optional eager
+  thread spin-up.
+
+- **Checkpoint and restart.** A binary chunk-framed checkpoint format
+  cheap enough to leave permanently enabled. Frames carry their own
+  chunk index, so completed work replays on resume regardless of the
+  order a pool returns it in, and a torn tail means exactly "that
+  chunk was not recorded".
+
+- **Optional compiled kernels.** Under three meson options:
+  `wht_kernel` (Walsh–Hadamard butterfly, fused coefficients, dense
+  gather, Hermiticity check, with optional x86-64-v3 twins), `native`
+  (Pauli label kernel with a oneTBB-parallel variant), and
+  `cache_probe` (empirical cache-latency probe). All are optional: the
+  package is correct and installable with no C toolchain, and reports
+  once when a fallback path is taken. Manylinux wheels ship
+  `wht_kernel` (+ `cache_probe`) with `-Dnative=disabled` (no oneTBB
+  in the wheel image); label generation falls back to pure Python.
+
+- **Cache-aware auto-tuning.** `paulikit.algorithms.autotune` sizes
+  chunks against measured cache boundaries, interpolating between
+  measured anchor points rather than applying a closed-form fit.
+
+- **Command-line interface.** `paulikit decompose`, `paulikit
+  benchmark` and `paulikit regenerate-fixtures`.
+
+- **Exhaustive verification.** Every term of a decomposition checked
+  individually against an independently derived projection oracle -
+  not sampled - up to 91,652,096 terms at 14 qubits, Hermitian and
+  non-Hermitian. Artifacts and method under `verification/`.
+
+- **Test suite.** 323 default tests (8 further slow benchmark
+  comparisons excluded by default).
+
+- **Documentation.** Installation, tutorial, theory, background,
+  non-Hermitian operators, annotated source tree, and an API
+  reference built from the docstrings.
+
+- GitHub Actions workflow (`.github/workflows/paulikit-wheels.yml` on
+  the GitHub mirror,
+  [github.com/beavernets-inc/paulikit](https://github.com/beavernets-inc/paulikit))
+  that builds manylinux wheels (x86_64 / aarch64, CPython 3.10–3.13)
+  and an sdist on tag / manual dispatch, with an optional Trusted
+  Publishing upload job. Codeberg remains the canonical repository;
+  hosted Forgejo runners are not used for the manylinux matrix.
+
+### Changed
+
+- README Usage leads with the measured sparse/dense fastest paths;
+  Sphinx tutorial, installation, and native docs match the multi-kernel
+  surface; `--chunk-size` help no longer claims auto-tuning is absent
+  from the library APIs.
+- GitHub mirror moved to
+  [beavernets-inc/paulikit](https://github.com/beavernets-inc/paulikit);
+  install docs lead with `pip install paulikit` for the first PyPI
+  upload.
+
+### Fixed
+
+- `make check` no longer dumps expected autotune/fork warnings from
+  intentional no-probe and process-pool tests.
+
+### Removed
+
+- Stale Status/CHANGELOG claim of an unexplained 14-to-15 qubit
+  parallel-efficiency step under the process-pool drain.
+
+### Known limitations
+
+- Linux manylinux wheels ship `wht_kernel` (+ `cache_probe`) but omit
+  `pauli_label_native` (oneTBB). macOS / Windows / musllinux use the
+  sdist. Install with `pip install paulikit`.
+- CPU pinning and topology detection are Linux-only, with a documented
+  fallback elsewhere; the non-Linux paths are not exercised in CI.
+
+[Unreleased]: https://codeberg.org/beavernets/paulikit/compare/v0.1.0...HEAD
+[0.1.0]: https://codeberg.org/beavernets/paulikit/releases/tag/v0.1.0

paulikit-0.1.0/CITATION.cff

@@ -0,0 +1,65 @@
+cff-version: 1.2.0
+title: >-
+  paulikit: memory-bounded, checkpointable Pauli decomposition of
+  complex matrices
+message: >-
+  If you use this software, please cite it using the metadata in this
+  file.
+type: software
+# Order is the intended citation order, with the corresponding author
+# first. These are the people credited when the SOFTWARE is cited,
+# which need not be identical to the author list of any paper about
+# it - keep the two in step deliberately rather than by accident.
+authors:
+  - given-names: Mohammadreza
+    family-names: Khellat
+    affiliation: Beavernets Technologies
+  - given-names: Mohammad
+    family-names: Masoumi
+    affiliation: Beavernets Technologies
+  - given-names: Saman
+    family-names: Nasouri
+    affiliation: Beavernets Technologies
+  - given-names: Soroush
+    family-names: Nasouri
+    affiliation: Beavernets Technologies
+repository-code: "https://codeberg.org/beavernets/paulikit"
+# Wheel CI / GitHub mirror (not the citation canonical URL):
+# https://github.com/beavernets-inc/paulikit
+# Project contact rather than any individual's address: it survives
+# people changing roles, and a CITATION.cff is archived permanently
+# alongside the DOI.
+contact:
+  - name: paulikit developers
+    email: dev@beavernets.com
+abstract: >-
+  paulikit computes the exact Pauli decomposition of an arbitrary
+  complex matrix via the fast Walsh-Hadamard transform. Hermitian and
+  non-Hermitian input are equally supported and take the same
+  transform; declaring input Hermitian additionally yields real
+  coefficients and checks that assumption rather than trusting it.
+  Both are verified against an independent projection oracle, and at
+  small sizes against PennyLane.
+  The transform itself is established practice; the contribution here
+  is making it usable at scale - a streaming formulation whose peak
+  resident memory is bounded independently of the term count,
+  multi-core execution over independent chunks, a chunk-framed binary
+  checkpoint format cheap enough to leave permanently enabled,
+  cache-aware automatic chunk sizing, and exhaustive per-term
+  verification against an independent projection oracle at up to
+  91,652,096 terms.
+keywords:
+  - Pauli decomposition
+  - fast Walsh-Hadamard transform
+  - quantum Hamiltonian simulation
+  - linear combination of unitaries
+  - memory-bounded algorithms
+  - parallel computing
+  - scientific Python
+  - checkpoint and restart
+license: GPL-3.0-or-later
+version: 0.1.0
+# NOTE: no DOI yet. This is added on the first archived release
+# (Zenodo), and the version above must be bumped to match the tag that
+# is archived. A CITATION.cff claiming a version that was never
+# released is worse than none.

paulikit-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,136 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation
+in our community a harassment-free experience for everyone, regardless
+of age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance,
+race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open,
+welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for
+our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our
+  mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or
+  political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in
+  a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our
+standards of acceptable behavior and will take appropriate and fair
+corrective action in response to any behavior that they deem
+inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit,
+or reject comments, commits, code, wiki edits, issues, and other
+contributions that are not aligned to this Code of Conduct, and will
+communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also
+applies when an individual is officially representing the community in
+public spaces. Examples of representing our community include using an
+official email address, posting via an official social media account,
+or acting as an appointed representative at an online or offline
+event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior
+may be reported to the community leaders responsible for enforcement
+at dev@beavernets.com.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and
+security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in
+determining the consequences for any action they deem in violation of
+this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior
+deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders,
+providing clarity around the nature of the violation and an
+explanation of why the behavior was inappropriate. A public apology
+may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior.
+No interaction with the people involved, including unsolicited
+interaction with those enforcing the Code of Conduct, for a specified
+period of time. This includes avoiding interactions in community
+spaces as well as external channels like social media. Violating these
+terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards,
+including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or
+public communication with the community for a specified period of
+time. No public or private interaction with the people involved,
+including unsolicited interaction with those enforcing the Code of
+Conduct, is allowed during this period. Violating these terms may lead
+to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of
+community standards, including sustained inappropriate behavior,
+harassment of an individual, or aggression toward or disparagement of
+classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction
+within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][
+homepage], version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the
+FAQ at https://www.contributor-covenant.org/faq. Translations are
+available at https://www.contributor-covenant.org/translations.
+
+[homepage]: https://www.contributor-covenant.org
+[Mozilla CoC]: https://github.com/mozilla/diversity

paulikit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,128 @@
+# Contributing to paulikit
+
+Thank you for your interest. This document covers how to build the
+package, how to run its tests, and what a change is expected to carry
+with it.
+
+## Where the project lives
+
+**Canonical repository:**
+[codeberg.org/beavernets/paulikit](https://codeberg.org/beavernets/paulikit)
+(`origin`).
+
+**Mirror:**
+[github.com/beavernets-inc/paulikit](https://github.com/beavernets-inc/paulikit)
+(`github`).
+
+Issues and pull requests are welcome at either. Prefer Codeberg when
+you have a choice; the GitHub remote exists so Linux wheel CI can use
+GitHub-hosted runners with Docker (manylinux), which Codeberg's
+hosted Forgejo Actions runners are not sized for.
+
+## Building
+
+The package uses [meson-python](https://mesonbuild.com/meson-python/),
+the same build backend as NumPy and SciPy. A `configure` script wraps
+the setup:
+
+```bash
+./configure          # creates a venv, reports what the toolchain offers
+make                 # editable install with the correct sequencing
+make check           # run the test suite
+make docs            # Sphinx HTML under docs/_build/html
+```
+
+`./configure` prints an itemised capability report - compiler, Cython,
+oneTBB, cache hierarchy, NumPy's BLAS backend - and then generates a
+Makefile with the standard GNU targets. Run `./configure --help` for
+the options.
+
+If you would rather not use it, `docs/installation.md` gives the
+manual sequence. The one thing that matters is `--no-build-isolation`
+on editable installs; without it NumPy's include path is baked in from
+a throwaway environment and goes stale on the next rebuild.
+
+## Running the tests
+
+```bash
+make check                       # or: pytest
+make test-native                 # the standalone C and C++ kernel self-tests
+```
+
+`pyproject.toml` sets `addopts = "-m 'not slow'"`, so the eight
+benchmark comparisons are skipped by default. To run them, override
+that rather than adding to it:
+
+```bash
+pytest -o addopts="" -m slow
+```
+
+The suite passes with no compiled extensions and no development
+dependencies installed - a few tests skip in that configuration, which
+is deliberate. That is the same environment the pure-Python fallback
+exists to serve, so it needs to stay green there.
+
+## Wheels and releases
+
+```bash
+pip install paulikit
+```
+
+Manylinux wheels (x86_64 and aarch64, CPython 3.10–3.13) and the sdist
+are built by `.github/workflows/paulikit-wheels.yml` on the GitHub
+mirror
+([github.com/beavernets-inc/paulikit](https://github.com/beavernets-inc/paulikit)):
+push a `v*` tag, or run the workflow manually. The job fails
+if `wht_native` / `coeffs_native` / `gather_native` are missing from
+the wheel. musllinux, macOS, and Windows are intentionally not wheel
+targets; those platforms use the sdist and documented fallbacks.
+Wheels omit `pauli_label_native` (oneTBB).
+
+Codeberg remains the source of truth for the tree. Do not expect the
+same cibuildwheel matrix to run on Codeberg's hosted Actions without
+a self-hosted runner that can drive Docker.
+
+## What a change should carry
+
+- **A test.** A bug fix should come with a test that fails without it.
+  A new code path should come with tests that cover it.
+- **The reason, not just the change.** Comments and docstrings here
+  record why something is the way it is, including approaches that
+  were measured and rejected. That is the most expensive information
+  in the codebase and the easiest to lose.
+- **A measurement, if the claim is about performance.** Wall-clock
+  time on a laptop is not evidence: CPU frequency scaling alone moves
+  it by a factor of two. Prefer instruction and cycle counts
+  (`perf stat -e instructions:u,cycles:u`), report the problem size,
+  and replicate before quoting a ratio.
+- **Documentation, if behaviour changed.** Including the docstring, so
+  the API reference stays correct. User-visible behaviour also updates
+  the README and/or CHANGELOG `[Unreleased]` section.
+- **Atomic commits.** One reviewable design step per commit (see the
+  repository history). Prefer a few closely related files over a
+  mega-commit that mixes engine, UI, and docs.
+
+## Style
+
+`ruff` is configured in `pyproject.toml` (line length 92) and is part
+of the `dev` extra. Most of the codebase is wrapped tighter than that,
+at 79, and new code should follow the file it lives in.
+
+Commit messages follow the GNU convention: a short imperative subject
+line, a blank line, then a body explaining *why* the change is being
+made, wrapped at 72 characters. The existing history is the reference.
+
+## Reporting a bug
+
+Please include the paulikit version, the Python version, the operating
+system, whether the compiled extensions were built (`./configure`
+reports this), and the smallest input that reproduces the problem.
+
+For a decomposition that produces a wrong result, the most useful
+report includes the operator - or the code that builds it - and the
+term that disagrees.
+
+## Licence
+
+paulikit is GPL-3.0-or-later. By contributing you agree that your
+contribution is licensed under the same terms.