ket-lang 0.10.4.3.dev0__tar.gz → 0.10.4.3.dev2__tar.gz

{ket_lang-0.10.4.3.dev0/src/ket_lang.egg-info → ket_lang-0.10.4.3.dev2}/PKG-INFO

@@ -1,48 +1,44 @@
 Metadata-Version: 2.4
 Name: ket-lang
-Version: 0.10.4.3.dev0
+Version: 0.10.4.3.dev2
 Summary: Ket quantum programming language interpreter and library
-Home-page: https://quantumket.org
-Author: Evandro Chagas Ribeiro da Rosa
-Author-email: evandro@quantuloop.com
-License: Apache-2.0
-Project-URL: Source, https://gitlab.com/quantum-ket/ket
 Keywords: quantum computer,quantum programming,quantum simulator
-Platform: linux
-Platform: win32
-Platform: osx
+Author: Evandro Chagas Ribeiro da Rosa
+Author-email: Evandro Chagas Ribeiro da Rosa <evandro@quantuloop.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
 Classifier: Topic :: Scientific/Engineering :: Quantum Computing
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: MacOS
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Rust
+Requires-Dist: amazon-braket-sdk ; extra == 'amazon'
+Requires-Dist: qiskit>=2.0.0,<3.0 ; extra == 'ibm'
+Requires-Dist: qiskit-aer ; extra == 'ibm'
+Requires-Dist: qiskit-ibm-runtime ; extra == 'ibm'
+Requires-Dist: quimb ; extra == 'mps'
+Requires-Dist: jax ; extra == 'mps'
+Requires-Dist: jaxlib ; extra == 'mps'
+Requires-Dist: cotengra ; extra == 'mps'
+Requires-Dist: numpy ; extra == 'plot'
+Requires-Dist: plotly ; extra == 'plot'
+Requires-Dist: pandas ; extra == 'plot'
+Requires-Dist: nbformat ; extra == 'plot'
+Requires-Dist: kaleido ; extra == 'plot'
+Requires-Dist: qiskit[visualization]>=2.0.0,<3.0 ; extra == 'plot'
+Requires-Dist: requests ; extra == 'remote'
+Requires-Dist: pyjwt[crypto] ; extra == 'remote'
+Requires-Dist: bcrypt ; extra == 'remote'
 Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
+Project-URL: Homepage, https://quantumket.org
+Project-URL: Source, https://gitlab.com/quantum-ket/ket
 Provides-Extra: amazon
-Requires-Dist: amazon-braket-sdk; extra == "amazon"
 Provides-Extra: ibm
-Requires-Dist: qiskit<3.0,>=2.0.0; extra == "ibm"
-Requires-Dist: qiskit-aer; extra == "ibm"
-Requires-Dist: qiskit-ibm-runtime; extra == "ibm"
+Provides-Extra: mps
 Provides-Extra: plot
-Requires-Dist: numpy; extra == "plot"
-Requires-Dist: plotly; extra == "plot"
-Requires-Dist: pandas; extra == "plot"
-Requires-Dist: nbformat; extra == "plot"
-Requires-Dist: kaleido; extra == "plot"
-Requires-Dist: qiskit[visualization]<3.0,>=2.0.0; extra == "plot"
 Provides-Extra: remote
-Requires-Dist: requests; extra == "remote"
-Requires-Dist: PyJWT[crypto]; extra == "remote"
-Requires-Dist: bcrypt; extra == "remote"
-Provides-Extra: mps
-Requires-Dist: quimb; extra == "mps"
-Requires-Dist: jax; extra == "mps"
-Requires-Dist: jaxlib; extra == "mps"
-Requires-Dist: cotengra; extra == "mps"
-Dynamic: license-file
+Description-Content-Type: text/markdown
 
 <!--
 SPDX-FileCopyrightText: 2020 Evandro Chagas Ribeiro da Rosa <evandro@quantuloop.com>

ket_lang-0.10.4.3.dev2/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14"]
+build-backend = "uv_build"
+
+[project]
+name = "ket-lang"
+version = "0.10.4.3.dev2"
+description = "Ket quantum programming language interpreter and library"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+keywords = [
+    "quantum computer",
+    "quantum programming",
+    "quantum simulator",
+]
+classifiers = [
+    "Topic :: Scientific/Engineering :: Quantum Computing",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Rust",
+]
+
+[[project.authors]]
+name = "Evandro Chagas Ribeiro da Rosa"
+email = "evandro@quantuloop.com"
+
+[project.urls]
+Homepage = "https://quantumket.org"
+Source = "https://gitlab.com/quantum-ket/ket"
+
+[project.optional-dependencies]
+amazon = ["amazon-braket-sdk"]
+ibm = [
+    "qiskit>=2.0.0,<3.0",
+    "qiskit-aer",
+    "qiskit-ibm-runtime",
+]
+plot = [
+    "numpy",
+    "plotly",
+    "pandas",
+    "nbformat",
+    "kaleido",
+    "qiskit[visualization]>=2.0.0,<3.0",
+]
+remote = [
+    "requests",
+    "PyJWT[crypto]",
+    "bcrypt",
+]
+mps = [
+    "quimb",
+    "jax",
+    "jaxlib",
+    "cotengra",
+]
+
+[tool.uv.build-backend]
+module-name = "ket"
+module-root = "src"
+wheel-exclude = [
+    "ket/clib/libs/kbw",
+    "ket/clib/libs/libket",
+]
+source-exclude = ["target"]
+
+[tool.pytest.ini_options]
+addopts = [
+    "--cov=ket",
+    "--cov-report=html",
+]
+testpaths = ["tests"]

ket_lang-0.10.4.3.dev2/pyproject.toml.orig

@@ -0,0 +1,59 @@
+# SPDX-FileCopyrightText: 2020 Evandro Chagas Ribeiro da Rosa <evandro@quantuloop.com>
+# SPDX-FileCopyrightText: 2020 Rafael de Santiago <r.santiago@ufsc.br>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14"]
+build-backend = "uv_build"
+
+[project]
+name = "ket-lang"
+version = "0.10.4.3.dev2"
+description = "Ket quantum programming language interpreter and library"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+keywords = ["quantum computer", "quantum programming", "quantum simulator"]
+authors = [
+    { name = "Evandro Chagas Ribeiro da Rosa", email = "evandro@quantuloop.com" },
+]
+classifiers = [
+    "Topic :: Scientific/Engineering :: Quantum Computing",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Rust",
+]
+
+[project.urls]
+Homepage = "https://quantumket.org"
+Source = "https://gitlab.com/quantum-ket/ket"
+
+[project.optional-dependencies]
+amazon = ["amazon-braket-sdk"]
+ibm = ["qiskit>=2.0.0,<3.0", "qiskit-aer", "qiskit-ibm-runtime"]
+plot = [
+    "numpy",
+    "plotly",
+    "pandas",
+    "nbformat",
+    "kaleido",
+    "qiskit[visualization]>=2.0.0,<3.0",
+]
+remote = ["requests", "PyJWT[crypto]", "bcrypt"]
+mps = ["quimb", "jax", "jaxlib", "cotengra"]
+
+[tool.uv.build-backend]
+module-name = "ket"
+module-root = "src"
+# The libkbw/libket binaries in src/ket/clib/libs are shipped; the Rust
+# submodules next to them are build inputs only.
+wheel-exclude = ["ket/clib/libs/kbw", "ket/clib/libs/libket"]
+source-exclude = ["target"]
+
+[tool.pytest.ini_options]
+addopts = ["--cov=ket", "--cov-report=html"]
+testpaths = ["tests"]

{ket_lang-0.10.4.3.dev0 → ket_lang-0.10.4.3.dev2}/src/ket/__init__.py

@@ -63,6 +63,8 @@ Examples:
 
 """
 
+from importlib import metadata as _metadata
+
 from .clib import libs
 from .base import *
 from .base import __all__ as all_base
@@ -83,7 +85,10 @@ from .fermion import *
 from .fermion import __all__ as all_fermion
 from . import qulib
 
-__version__ = "0.10.4.3.dev0"
+try:
+    __version__ = _metadata.version("ket-lang")
+except _metadata.PackageNotFoundError:  # running from a source checkout
+    __version__ = "unknown"
 
 __all__ = (
     all_base

ket_lang-0.10.4.3.dev2/src/ket/_shared_control.py

@@ -0,0 +1,109 @@
+"""Shared multi-qubit controls through a clean auxiliary qubit.
+
+Used by :func:`~ket.operations.control` when a block is controlled by two or
+more qubits.
+"""
+
+from __future__ import annotations
+
+# SPDX-FileCopyrightText: 2026 Evandro Chagas Ribeiro da Rosa <evandro@quantuloop.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# pylint: disable=protected-access
+
+from typing import TYPE_CHECKING
+
+from .clib.libket import Block
+from .clib.wrapper import LibketError
+from ._verification import _block_proprieties, _touched_qubits
+
+if TYPE_CHECKING:
+    from .base import Process, Quant
+
+
+def _mark(process: Process, block: Block):
+    """Apply the diagonal/permutation annotation of the enclosing builders."""
+    if process._is_diagonal > 0:
+        block.set_as_diagonal()
+    elif process._is_permutation > 0:
+        block.set_as_permutation()
+
+
+def append_controlled(process: Process, body: Block, control_qubits: Quant):
+    r"""Append ``body`` controlled by two or more ``control_qubits``.
+
+    If sharing reduces the CNOT count (estimated by Libket, see below), the
+    controls are shared through a clean auxiliary qubit:
+
+    .. code-block:: text
+
+        compute:   aux ^= AND(control_qubits)   (relative-phase decomposition allowed)
+        action:    body controlled by aux
+        uncompute: adjoint of compute
+
+    The action only reads ``aux`` (as a control) and does not touch the control
+    qubits, so ``aux`` returns to |0> and the approximated decomposition of the
+    compute step is exact. Each gate of the body then needs a single control
+    instead of the whole control set. Otherwise (no CNOT saved,
+    no decomposition of the gates, a body that acts on a control qubit, or no
+    qubit left for the auxiliary), the controls are added to every gate of
+    ``body``.
+
+    The estimate is computed by ``Process::shared_control_gain`` in Libket.
+    Sharing costs the compute and the uncompute of the approximated AND of the
+    controls. It saves, for each gate of the body,
+    the difference between its cost with all the controls and with one, and a
+    non-zero global phase saves its correction, a :math:`C^{n-1}P` gate on the
+    controls, which becomes a :math:`P` gate on ``aux``. Libket obtains each
+    cost from the decomposition it would select with the qubits free now, so
+    the decision takes into account the auxiliary qubits available to the
+    decompositions, including the one that the shared control takes. The
+    controls are never shared when the process does not decompose the gates,
+    since the shared form would only add a qubit and gates to the circuit.
+
+    The auxiliary qubit comes from a pool reserved for shared controls (see
+    :meth:`~ket.base.Process._alloc_control_aux`), which the verification of
+    :func:`~ket.operations.around` ignores: it is |0> outside the three steps
+    above, which are always appended together.
+    """
+    aux = None
+    num_controls = len(control_qubits)
+    touches_controls = bool(
+        _touched_qubits(_block_proprieties(body)) & set(control_qubits.qubits)
+    )
+    if (
+        not touches_controls
+        and process.shared_control_gain(
+            body, num_controls, not process._control_aux_free
+        ).value
+        > 0
+    ):
+        try:
+            aux = process._alloc_control_aux()
+        except LibketError:
+            aux = None
+
+    if aux is None:
+        controlled = body.control(control_qubits.qubits)
+        _mark(process, controlled)
+        process.append_block(controlled)
+        return
+
+    try:
+        target = Block(process)
+        target.append_gate("PauliX", aux.qubits[0])
+        compute = target.control(control_qubits.qubits)
+        _mark(process, compute)
+        compute.lock_control()
+        compute.enable_approximated_decomposition()
+        uncompute = compute.inverse()
+
+        action = body.control(aux.qubits)
+        _mark(process, action)
+
+        process.append_block(compute, check_qubits=False)
+        process.append_block(action)
+        process.append_block(uncompute, check_qubits=False)
+    finally:
+        process._free_control_aux(aux)

ket_lang-0.10.4.3.dev2/src/ket/_verification.py

@@ -0,0 +1,146 @@
+"""Verification helpers for the compute-action-uncompute pattern.
+
+Used by :func:`~ket.operations.around` and :func:`~ket.operations.undo` to
+check the safe use of auxiliary qubits (clean auxiliary qubit pattern) and to
+decide when the approximated decomposition can be enabled. They query the
+per-qubit properties (gate classification and read qubits) that Libket
+records for each block.
+"""
+
+from __future__ import annotations
+
+# SPDX-FileCopyrightText: 2026 Evandro Chagas Ribeiro da Rosa <evandro@quantuloop.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# pylint: disable=protected-access
+
+from ctypes import c_size_t
+import json
+from typing import TYPE_CHECKING
+
+from ket.clib.libket import API as libket
+
+if TYPE_CHECKING:
+    from .base import Process
+
+
+def _block_proprieties(block) -> dict[int, dict]:
+    """Return the per-qubit properties of a block, keyed by qubit index."""
+    proprieties_ptr = block.proprieties_json()
+    proprieties = json.loads(proprieties_ptr.value)
+    libket["ket_string_delete"](proprieties_ptr)
+    return {int(target): op for target, op in proprieties.items()}
+
+
+def _block_proprieties_subset(block, qubits) -> dict[int, dict]:
+    """Return the per-qubit properties of a block for the given qubits only.
+
+    Equivalent to ``{q: p for q, p in _block_proprieties(block).items() if q in qubits}``,
+    but Libket only serializes the requested qubits (using its cached records),
+    so the cost does not grow with the size of the block.
+    """
+    qubits = list(qubits)
+    array = (c_size_t * len(qubits))(*qubits)
+    proprieties_ptr = block.proprieties_subset_json(array, len(qubits))
+    proprieties = json.loads(proprieties_ptr.value)
+    libket["ket_string_delete"](proprieties_ptr)
+    return {int(target): op for target, op in proprieties.items()}
+
+
+def _without_control_aux(
+    proprieties: dict[int, dict], control_aux: set[int]
+) -> dict[int, dict]:
+    """Remove the shared-control auxiliary qubits from block properties.
+
+    A shared-control auxiliary qubit (see ``ket.operations.control``) holds the
+    AND of a set of control qubits only between its compute and uncompute
+    steps, which are always appended together, so it is |0> outside them. It
+    is removed from the properties, and a qubit that reads it reads, instead,
+    the qubits it was computed from (transitively).
+    """
+
+    def sources(qubit, seen):
+        result = set()
+        for read in proprieties.get(qubit, {}).get("read_qubits", ()):
+            if read in control_aux:
+                if read not in seen:
+                    seen.add(read)
+                    result |= sources(read, seen)
+            else:
+                result.add(read)
+        return result
+
+    filtered = {}
+    for target, op in proprieties.items():
+        if target in control_aux:
+            continue
+        read_qubits = set(op["read_qubits"])
+        if read_qubits & control_aux:
+            read_qubits = (read_qubits - control_aux) | sources(target, set())
+            op = {**op, "read_qubits": sorted(read_qubits)}
+        filtered[target] = op
+    return filtered
+
+
+def _analyze_compute(proprieties: dict[int, dict], ket_process: Process):
+    """Check the compute block of a compute-action-uncompute pattern.
+
+    Returns the set of qubits that must remain unchanged (except for diagonal
+    operations) until the uncomputation, and whether every qubit modified by
+    the compute block is classified as identity, diagonal, or permutation.
+
+    The returned blocked set is the transitive closure of the qubits read by
+    the auxiliary qubits: if an auxiliary qubit reads ``q`` and ``q`` reads
+    ``r`` in the compute block, both ``q`` and ``r`` are blocked.
+
+    Raises:
+        RuntimeError: If an auxiliary qubit is subject to a non-permutation
+            operation, or if a qubit read (directly or transitively) by an
+            auxiliary qubit is subject to a non-permutation operation in the
+            compute block.
+    """
+
+    if ket_process._control_aux:
+        proprieties = _without_control_aux(proprieties, ket_process._control_aux)
+
+    blocked_qubits = set()
+    for target, op in proprieties.items():
+        if not ket_process._is_aux(target):
+            continue
+        match op["propriety"]:
+            case "Permutation":
+                blocked_qubits.update(op["read_qubits"])
+            case "Unitary":
+                raise RuntimeError("Operation not allowed on axillary qubit.")
+
+    pending = list(blocked_qubits)
+    while pending:
+        qubit = pending.pop()
+        op = proprieties.get(qubit)
+        if op is None:
+            continue
+        if op["propriety"] == "Unitary":
+            raise RuntimeError(
+                "Operation violates uncomputation: a qubit read by an auxiliary "
+                "qubit is subject to a non-permutation operation in the compute block."
+            )
+        for read_qubit in op["read_qubits"]:
+            if read_qubit not in blocked_qubits:
+                blocked_qubits.add(read_qubit)
+                pending.append(read_qubit)
+
+    is_permutation = all(
+        op["propriety"] in ("Identity", "Diagonal", "Permutation")
+        for op in proprieties.values()
+    )
+
+    return blocked_qubits, is_permutation
+
+
+def _touched_qubits(proprieties: dict[int, dict]) -> set[int]:
+    """Return the qubits a block acts on, either as target or as control."""
+    touched = set(proprieties)
+    for op in proprieties.values():
+        touched.update(op["read_qubits"])
+    return touched

{ket_lang-0.10.4.3.dev0 → ket_lang-0.10.4.3.dev2}/src/ket/base/__init__.py

@@ -18,7 +18,7 @@ from __future__ import annotations
 
 from collections import defaultdict
 from contextlib import contextmanager
-from ctypes import c_void_p
+from ctypes import c_size_t, c_void_p
 import json
 from typing import Literal, Optional
 
@@ -169,6 +169,12 @@ class Process(LibketProcess):  # pylint: disable=too-many-instance-attributes
 
         self._qubit_pool = []
         self._aux = set()
+        # Auxiliary qubits used to share multi-qubit controls (see
+        # ``ket.operations.control``). They are never returned to
+        # ``_qubit_pool``: they are only used by the compute, action, and
+        # uncompute steps of a shared control, which are appended together.
+        self._control_aux = set()
+        self._control_aux_free = []
         self._blocked_qubits = defaultdict(int)
 
         self._blocks = []
@@ -222,6 +228,30 @@ class Process(LibketProcess):  # pylint: disable=too-many-instance-attributes
             return self._qubit_pool.pop(0)
         return super().__getattr__("alloc")().value
 
+    def _alloc_control_aux(self) -> Quant:
+        """Allocate an auxiliary qubit to share a multi-qubit control."""
+        if self._control_aux_free:
+            index = self._control_aux_free.pop()
+        else:
+            index = self._alloc()
+            self._control_aux.add(index)
+        return Quant(qubits=[index], process=self)
+
+    def _free_control_aux(self, aux: Quant):
+        self._control_aux_free.extend(aux.qubits)
+
+    def _set_unknown_state(self, qubits: Quant):
+        """Declare that the initial state of ``qubits`` is unknown.
+
+        Libket skips controlled gates that act as the identity on qubits known
+        to be in |0> (every qubit starts in |0>). Functions that analyze a gate
+        for arbitrary inputs, such as :func:`~ket.qulib.gate_count`, declare
+        the input qubits as unknown. Must be called before any gate is applied
+        to ``qubits``.
+        """
+        array = (c_size_t * len(qubits.qubits))(*qubits.qubits)
+        super().__getattr__("set_unknown_state")(array, len(qubits.qubits))
+
     def _is_aux(self, index):
         return index in self._aux
 
@@ -493,22 +523,23 @@ class Process(LibketProcess):  # pylint: disable=too-many-instance-attributes
         try:
             yield block
         finally:
-            if inverse:
-                block.set(block.inverse())
-            if control is not None:
-                block.set(block.control(control))
-
-            if self._is_diagonal > 0:
-                block.set_as_diagonal()
-            elif self._is_permutation > 0:
-                block.set_as_permutation()
-
-            if diagonal:
-                self._is_diagonal -= 1
-            elif permutation:
-                self._is_permutation -= 1
-
-            self._blocks.pop()
+            try:
+                if inverse:
+                    block.set(block.inverse())
+                if control is not None:
+                    block.set(block.control(control))
+
+                if self._is_diagonal > 0:
+                    block.set_as_diagonal()
+                elif self._is_permutation > 0:
+                    block.set_as_permutation()
+            finally:
+                if diagonal:
+                    self._is_diagonal -= 1
+                elif permutation:
+                    self._is_permutation -= 1
+
+                self._blocks.pop()
             if append:
                 self.append_block(block)
 

{ket_lang-0.10.4.3.dev0 → ket_lang-0.10.4.3.dev2}/src/ket/clib/kbw.py

@@ -28,8 +28,15 @@ api_argtypes = {
         ],
         [c_void_p],  # qpu_config
     ),
+    "kbw_gpu_tune": (
+        [c_bool],  # force
+        [c_size_t, c_bool],  # block_size, cached
+    ),
 }
 
+NO_BLOCKING = 64
+"""Block size meaning that the ``"dense gpu"`` simulator never splits the state."""
+
 
 def kbw_path():
     """Get KBW path"""
@@ -76,7 +83,10 @@ def get_simulator(  # pylint: disable=too-many-arguments,too-many-positional-arg
             - ``"dense v1"``: Previous dense simulator variant.
             - ``"dense v2"``: Dense simulator with a smaller memory footprint.
             - ``"dense gpu"``: Dense simulator targeting most GPUs (Intel, AMD,
-              Apple, and NVIDIA). Recommended for large qubit counts.
+              Apple, and NVIDIA). Recommended for large qubit counts. Large
+              states are split into blocks to keep gates inside the GPU
+              caches; the block size is tuned for the device on first use
+              (about two seconds) and stored, see :func:`tune_gpu_block_size`.
 
         coupling_graph: Optional list of ``(control, target)`` qubit pairs
             describing the hardware connectivity. When provided, the compiler
@@ -103,3 +113,35 @@ def get_simulator(  # pylint: disable=too-many-arguments,too-many-positional-arg
         gradient,  # gradient
         coupling_graph_json,  # coupling_graph
     )
+
+
+def tune_gpu_block_size(force: bool = False) -> int:
+    """Tune the block size of the ``"dense gpu"`` simulator for this device.
+
+    The ``"dense gpu"`` simulator splits states with many qubits into blocks
+    of ``2**block_size`` amplitudes so that gates stay inside the GPU caches.
+    The best size depends on the GPU, so it is measured with a short benchmark
+    (about one to two seconds) the first time the simulator is used, then
+    stored in ``gpu_tuning.json`` in the user cache directory, per device and
+    KBW version. Call this function to run the tuning ahead of time, or with
+    ``force=True`` to measure again (for example, after a driver update).
+
+    Environment variables:
+
+    - ``KBW_BLOCK_SIZE``: use this block size and skip tuning.
+    - ``KBW_GPU_TUNE=0``: skip tuning and use the default block size, 20.
+    - ``KBW_GPU_RETUNE=1``: measure again on first use.
+    - ``KBW_CACHE_DIR``: directory of ``gpu_tuning.json``.
+
+    Args:
+        force: Measure even if a stored result exists.
+
+    Returns:
+        The chosen block size. :data:`NO_BLOCKING` (64) means that the state is
+        never split.
+
+    Raises:
+        LibketError: If no GPU is available or KBW was built without GPU support.
+    """
+    block_size, _cached = API["kbw_gpu_tune"](force)
+    return block_size.value