qmlkit 0.1.0__tar.gz

qmlkit-0.1.0/.gitattributes

@@ -0,0 +1,10 @@
+# Normalise to LF in the repository and in the sdist. Without this, a checkout on
+# Windows commits CRLF, and `ruff format --check` then disagrees with a Linux CI run
+# over files nobody edited.
+* text=auto eol=lf
+
+# Never touch these.
+*.png binary
+*.jpg binary
+*.pdf binary
+*.ipynb text eol=lf

qmlkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,188 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Core: no optional SDK installed. Proves `pip install qmlkit` is genuinely
+  # self-sufficient and that a missing backend degrades to a clear message.
+  core:
+    name: core · py${{ matrix.python }} · ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        include:
+          - os: windows-latest
+            python: "3.12"
+          - os: macos-latest
+            python: "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - name: Lint
+        run: |
+          ruff check src tests
+          ruff format --check src tests
+      - name: Type-check
+        run: mypy
+      - name: Test
+        run: coverage run --parallel-mode --source=qmlkit -m pytest -q
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage-core-${{ matrix.os }}-${{ matrix.python }}
+          path: .coverage.*
+          include-hidden-files: true
+
+  # Every optional dependency gets a job where its marked tests actually execute.
+  # The core job installs none of them, so without this they would only ever skip:
+  # a suite that silently skips its hardest tests is worse than no suite.
+  #
+  #   qiskit, cirq -> the cross-backend equivalence suite
+  #   torch        -> the autograd bridge and the backprop gradient
+  #   pennylane    -> 301 cross-validation cases against a second implementation
+  sdk:
+    name: ${{ matrix.sdk }} · py3.12
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk: [qiskit, cirq, torch, pennylane]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev,${{ matrix.sdk }}]"
+      # This line is load-bearing. If the SDK were missing, importorskip and skipif
+      # would turn every test in this job green by skipping it -- verified locally:
+      # `pytest -m spinqit` without SpinQit installed exits 0, not 5, because the
+      # tests are collected and then skipped. An SDK job that proves nothing is worse
+      # than no SDK job, so assert the import before trusting the run below.
+      - name: Confirm ${{ matrix.sdk }} actually imports
+        run: python -c "import ${{ matrix.sdk }}"
+      - name: Run the ${{ matrix.sdk }}-marked tests
+        run: coverage run --parallel-mode --source=qmlkit -m pytest -q -m ${{ matrix.sdk }}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.sdk }}
+          path: .coverage.*
+          include-hidden-files: true
+
+  # Everything installed at once, running the whole suite rather than a marker
+  # selection. Two reasons. First, the coverage number: the core jobs have no optional
+  # SDK and the sdk jobs each run one marker, so between them a file can be covered by
+  # nobody -- test_advanced.py ran in *no* CI job for exactly that reason, and
+  # nn/advanced.py sat at 66%. Second, integration: this is the only job where torch,
+  # Qiskit, Cirq and PennyLane are present together, which is how most users install.
+  full:
+    name: All extras · py3.12
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev,torch,qiskit,cirq,aer,sklearn,pennylane,viz]"
+      # aer is here and not in the matrix above because its distribution and its
+      # import name differ, and because it is the only way the qiskit-aer noisy
+      # backend gets exercised at all: without it every test in
+      # tests/test_noisy_backends.py skips itself and the job still goes green.
+      - name: Confirm every extra actually imported
+        run: python -c "import torch, qiskit, qiskit_aer, cirq, sklearn, pennylane, matplotlib"
+      - name: Whole suite, no marker filter
+        run: coverage run --parallel-mode --source=qmlkit -m pytest -q
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage-full
+          path: .coverage.*
+          include-hidden-files: true
+
+  # SpinQit only has wheels for 3.8-3.10 and pins numpy<2, so it gets its own job
+  # on 3.10. Allowed to fail without blocking: the NumPy backend is the reference,
+  # and a SpinQit packaging problem upstream is not a qmlkit regression.
+  spinqit:
+    name: spinqit · py3.10
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: pip
+      - run: pip install -e ".[dev,spinqit]"
+      - name: Convention self-check
+        run: |
+          python -c "
+          import qmlkit as qk
+          r = qk.get_backend('spinqit').verify_conventions()
+          print(r)
+          assert all(r.values()), [k for k, v in r.items() if not v]
+          "
+      - name: Cross-backend equivalence
+        run: pytest -q -m spinqit
+
+  # One honest coverage number, measured across every environment, because no
+  # single interpreter can import all four backends.
+  coverage:
+    name: Combined coverage
+    needs: [core, sdk, full]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-*
+          merge-multiple: true
+      - run: |
+          coverage combine
+          coverage report --fail-under=90
+          coverage xml
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+
+  build:
+    name: Build and check the distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      # Install the built wheel into an environment that has nothing else, and run
+      # the library from there. An editable install imports out of src/ and would
+      # keep working even if a module were missing from the wheel entirely.
+      - name: Verify the wheel in a clean environment
+        run: |
+          python -m venv /tmp/clean
+          /tmp/clean/bin/pip install --quiet dist/*.whl
+          /tmp/clean/bin/python scripts/verify_install.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

qmlkit-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,60 @@
+# Build the documentation on every change, and publish it from main.
+#
+# The build runs `pytest tests/test_docs.py` first, which executes every Python
+# block on every page. Docs that no longer run are treated as a broken build, not
+# as cosmetic drift -- the first thing a new reader does is copy the first snippet
+# on the page, and a tutorial that stopped working two releases ago looks exactly
+# like one that still works.
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build and verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      # sklearn and torch so the pages that need them run rather than skip
+      - run: pip install -e ".[docs,dev,sklearn,torch]"
+      - name: Every snippet in the docs must run
+        run: pytest tests/test_docs.py -q
+      # llms.txt is generated from these pages and from the package, and committed.
+      # Regenerating here would hide the drift; checking makes the staleness the failure.
+      - name: The llms.txt files must be current
+        run: python scripts/generate_llms_txt.py --check
+      # --strict turns broken internal links and missing nav entries into failures
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    name: Publish to GitHub Pages
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - id: deploy
+        uses: actions/deploy-pages@v4

qmlkit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,115 @@
+# Publish to PyPI when a version tag is pushed.
+#
+#   git tag v0.1.0 && git push origin v0.1.0
+#
+# Authentication is PyPI Trusted Publishing (OIDC), so there is no API token in
+# this repository's secrets and nothing to rotate or leak. It has to be configured
+# once on PyPI first: Your projects -> qmlkit -> Publishing -> add a GitHub
+# publisher for owner `Ziadt160`, repository `qmlkit`, workflow `release.yml`,
+# environment `pypi`. For the very first upload, where the project does not exist
+# yet, add it under "Pending publishers" instead.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # Never publish something the test suite has not seen: a tag can be pushed to a
+  # commit CI never ran on. Deliberately narrower than ci.yml -- the version floor
+  # and a current release, with PennyLane so the 301 cross-validation cases run.
+  # Resolving torch + qiskit + cirq + pennylane together across every interpreter is
+  # fragile, and ci.yml already covers each of them on its own on every push.
+  verify:
+    name: Test before publishing
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        python: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: pip install -e ".[dev,pennylane]"
+      - run: ruff check src tests && ruff format --check src tests
+      - run: mypy
+      - run: pytest -q
+
+  build:
+    name: Build and verify the distribution
+    needs: verify
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - name: Verify the wheel in a clean environment
+        run: |
+          python -m venv /tmp/clean
+          /tmp/clean/bin/pip install --quiet dist/*.whl
+          /tmp/clean/bin/python scripts/verify_install.py
+      # A tag that disagrees with pyproject.toml would publish a version nobody
+      # asked for, and PyPI will not let it be replaced afterwards.
+      - name: Tag must match the packaged version
+        id: version
+        run: |
+          packaged=$(python -c "import tomllib,pathlib;print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          echo "version=$packaged" >> "$GITHUB_OUTPUT"
+          if [ "${GITHUB_REF_TYPE}" = "tag" ] && [ "${GITHUB_REF_NAME}" != "v$packaged" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} does not match pyproject version $packaged"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # TestPyPI first, so a broken description or a bad filename is caught somewhere
+  # that can be thrown away. A PyPI version number can never be reused.
+  testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/qmlkit
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  pypi:
+    name: Publish to PyPI
+    needs: testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/qmlkit
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

qmlkit-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Testing / typing caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Environments
+.venv/
+venv/
+env/
+
+# OS / editors
+.DS_Store
+Thumbs.db
+Desktop.ini
+.vscode/
+.idea/
+
+# Built documentation
+site/
+
+# the Kaggle credit-risk CSV: redistributable only from Kaggle, and 1.8 MB
+credit_risk_dataset.csv

qmlkit-0.1.0/AGENTS.md

@@ -0,0 +1,81 @@
+# AGENTS.md
+
+Instructions for a coding agent working **on** qmlkit. To *use* the library, read
+[`docs/llms.txt`](docs/llms.txt) instead — it is the same information written for
+the caller rather than the contributor.
+
+[`HANDOFF.md`](HANDOFF.md) is the long version of this file: current status, why
+each convention exists, and what to do next. Read it before anything non-trivial.
+This page is the short list of things that will break the build if you get them
+wrong.
+
+## Commands
+
+```bash
+pip install -e ".[dev,torch,qiskit,cirq,sklearn,pennylane]"
+pytest -q                                  # the whole suite
+pytest -q -m "not pennylane"               # faster, skips the 301 parity cases
+ruff check src tests && mypy               # both must be clean
+python scripts/generate_llms_txt.py        # after any docs or public-API change
+python scripts/verify_install.py           # the core really does import with only NumPy
+```
+
+SpinQit needs its own interpreter — it ships wheels for Python 3.8–3.10 only and
+pins `numpy<2`:
+
+```bash
+C:/Users/pc/miniconda3/envs/spinq_env/python.exe -m pytest -m spinqit
+```
+
+## Rules the tests enforce
+
+1. **An algorithm owns its loop, not its circuit.** Every model takes `ansatz=` /
+   `feature_map=` / `filter=` and must actually use it. `tests/test_injection.py`
+   injects two different sizes and asserts the parameter count follows.
+2. **Estimators must be scikit-learn clonable.** Constructor arguments stored under
+   their own names, plus `SklearnCompatible`. This keeps scikit-learn optional while
+   letting QSVC/QSVR run inside `Pipeline` and `GridSearchCV`.
+3. **The core depends on NumPy and nothing else.** Not SciPy — use `math.erf` and the
+   stdlib. CI installs nothing else in the `core` jobs, and this has been broken once.
+4. **Documentation is executable.** `tests/test_docs.py` runs every Python block on
+   every page, so an API change and its docs go in the same commit.
+5. **Names have to stay findable.** `qmlkit/_aliases.py` maps what PennyLane and
+   Qiskit call each thing; `tests/test_agent_api.py` asserts every target still
+   exists. Rename a public name and you update that table in the same commit.
+6. **`docs/llms.txt` is generated and committed.** Change the docs or the public API
+   and regenerate it, or CI fails on the stale copy.
+
+## Traps that have already cost time
+
+- **Never use a NumPy-2-only API** (`np.trapezoid`, `np.in1d`, …) in `src/` or
+  `tests/`. SpinQit pins `numpy<2` and the suite must pass in both environments.
+- **Always write `npt.NDArray[Any]`, never bare `np.ndarray`.** Type-parameter
+  defaults only arrived in NumPy 2.3, so 3.10 CI fails with 60 `type-arg` errors.
+- **Never set `python_version` in `[tool.mypy]`.** It makes mypy parse dependency
+  stubs at that version too, and NumPy's stubs use PEP 695 `type` statements, which
+  are a syntax error before 3.12. Cross-version signal comes from CI running mypy
+  on 3.10.
+- **The PennyLane parity fuzzer draws gate names from a snapshot taken at import**,
+  not from the live registry — other test modules register throwaway gates at run
+  time, which made it pass alone and fail in a full run.
+- **Extend `tests/test_pennylane_parity.py` when adding a gate.** A test there
+  asserts the mapping covers every built-in gate, so a new one cannot escape
+  cross-validation. Every bug found in this project has been the
+  plausible-wrong-number kind that only a second implementation catches.
+
+## Design commitments
+
+- **Simulator-only for the whole 0.x line.** This is a constraint that propagates,
+  not a scope trim: it makes `adjoint` the correct default gradient, makes shot
+  noise opt-in, and demotes anything whose value is cutting *measurement* cost.
+  Parameter-shift stays the teaching subject and the reference that validates
+  adjoint — never the performance default.
+- **Simple on top, open underneath.** Three layers, and nothing at a higher one
+  hides a lower one. Every extension point is a registry.
+- **When something is named after a pattern rather than a structure, make it a
+  composition, not a class.** Data re-uploading is `EncodingLayer` in the block
+  vocabulary, with `reupload()` as a convenience over it.
+- **The error message is the documentation.** Most callers are models that will not
+  read the docs site; they read the traceback. An error about a name says what was
+  wrong, what was probably meant, and what is allowed — build it with
+  `qmlkit.utils.errors.unknown`.