luna-quantum 1.0.0__cp312-cp312-win_amd64.whl

luna_quantum/solve/parameters/backends/dwave_qpu.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field, StringConstraints
+
+from luna_quantum.client.schemas import QpuToken, QpuTokenSource, TokenProvider
+from luna_quantum.solve.domain.abstract.qpu_token_backend import QpuTokenBackend
+from luna_quantum.solve.parameters.backends.dwave import DWave
+
+
+class DWaveQpu(DWave, QpuTokenBackend):
+    """
+    Configuration for D-Wave quantum processing backends.
+
+    This class provides settings for problem decomposition and embedding when using
+    D-Wave quantum processors. It can be configured to use either manual embedding
+    parameters or automatic embedding based on problem characteristics.
+
+    Attributes
+    ----------
+    embedding_parameters: Embedding | None, default=None
+        Detailed configuration for manual embedding when not using auto-embedding.
+        If None and decomposer is also None, default embedding parameters will be used.
+        Ignored if decomposer is set to AutoEmbedding.
+    qpu_backend: str
+        Specific D-Wave quantum processing unit (QPU) for your optimization
+    """
+
+    class Embedding(BaseModel):
+        """
+        Configuration parameters for embedding problems onto D-Wave QPUs.
+
+        Embedding maps logical variables from a problem to physical qubits on the QPU,
+        with chains of qubits representing individual variables.
+
+        Attributes
+        ----------
+        max_no_improvement: int, default=10
+            Maximum number of consecutive failed iterations to improve the current
+            solution before giving up. Each iteration attempts to find an embedding for
+            each variable such that it is adjacent to all its neighbors.
+
+        random_seed: Optional[int], default=None
+            Seed for the random number generator. If None, seed is set by
+            `os.urandom()`.
+
+        timeout: int, default=1000
+            Maximum time in seconds before the algorithm gives up.
+
+        max_beta: Optional[float], default=None
+            Controls qubit weight assignment using formula (beta^n) where n is the
+            number of chains containing that qubit. Must be greater than 1 if specified.
+             If None, `max_beta` is effectively infinite.
+
+        tries: int, default=10
+            Number of restart attempts before the algorithm stops. On D-Wave 2000Q, a
+            typical restart takes between 1 and 60 seconds.
+
+        inner_rounds: Optional[int], default=None
+            Maximum iterations between restart attempts. Restart attempts are typically
+            terminated due to `max_no_improvement`. If None, effectively infinite.
+
+        chainlength_patience: int, default=10
+            Maximum number of consecutive failed iterations to improve chain lengths
+            before moving on. Each iteration attempts to find more efficient embeddings.
+
+        max_fill: Optional[int], default=None
+            Restricts the number of chains that can simultaneously use the same qubit
+            during search. Values above 63 are treated as 63. If None, effectively
+            infinite.
+
+        threads: int, default=1
+            Maximum number of threads to use. Parallelization is only advantageous when
+            the expected variable degree significantly exceeds the thread count. Min: 1.
+
+        return_overlap: bool, default=False
+            Controls return value format:
+            - True: Returns (embedding, validity_flag) tuple
+            - False: Returns only the embedding
+            This function returns an embedding regardless of whether qubits are used by
+            multiple variables.
+
+        skip_initialization: bool, default=False
+            If True, skips the initialization pass. Only works with semi-valid
+            embeddings provided through `initial_chains` and `fixed_chains`.
+            A semi-valid embedding has chains where every adjacent variable pair (u,v)
+            has a coupler (p,q) in the hardware with p in chain(u) and q in chain(v).
+
+        initial_chains: Any, default=()
+            Initial chains inserted before `fixed_chains` and before initialization.
+            Can be used to restart algorithm from a previous state. Missing or empty
+            entries are ignored. Each value is a list of qubit labels.
+
+        fixed_chains: Any, default=()
+            Fixed chains that cannot change during the algorithm. Qubits in these chains
+            are not used by other chains. Missing or empty entries are ignored.
+            Each value is a list of qubit labels.
+
+        restrict_chains: Any, default=()
+            Restricts each chain[i] to be a subset of `restrict_chains[i]` throughout
+            the algorithm. Missing or empty entries are ignored. Each value is a list
+            of qubit labels.
+
+        suspend_chains: Any, default=()
+            A metafeature only implemented in the Python interface. For each suspended
+            variable i, `suspend_chains[i]` is an iterable of iterables (blobs).
+            For each blob in a suspension, at least one qubit from that blob must be
+            in the chain for variable i.
+        """
+
+        max_no_improvement: int = 10
+        random_seed: int | None = None
+        timeout: int = 1_000
+        max_beta: float | None = None
+        tries: int = 10
+        inner_rounds: int | None = None
+        chainlength_patience: int = 10
+        max_fill: int | None = None
+        threads: int = Field(default=1, ge=1)
+        return_overlap: bool = False
+        skip_initialization: bool = False
+        initial_chains: dict = Field(default_factory=dict)  # type: ignore[type-arg]
+        fixed_chains: dict = Field(default_factory=dict)  # type: ignore[type-arg]
+        restrict_chains: dict = Field(default_factory=dict)  # type: ignore[type-arg]
+        suspend_chains: dict = Field(default_factory=dict)  # type: ignore[type-arg]
+
+    class AutoEmbedding(BaseModel):
+        """
+        Configuration for automatic embedding of problems onto D-Wave hardware.
+
+        This class provides a simpler interface to configure the embedding process
+        when the details of the underlying hardware are not known or when optimal
+        embedding parameters should be determined automatically.
+
+        Attributes
+        ----------
+        embedding_parameters: EmbeddingParameters, default=EmbeddingParameters()
+            Detailed configuration parameters for the embedding algorithm.
+            See EmbeddingParameters documentation for details on specific settings.
+        """
+
+        embedding_parameters: DWaveQpu.Embedding = Field(
+            default_factory=lambda: DWaveQpu.Embedding()
+        )
+
+    embedding_parameters: Embedding | AutoEmbedding | None = None
+    qpu_backend: Annotated[
+        str, StringConstraints(strip_whitespace=True, min_length=1)
+    ] = "default"
+
+    token: str | QpuToken | None = Field(repr=False, exclude=True, default=None)
+
+    def _get_token(self) -> TokenProvider | None:
+        if self.token is None:
+            return None
+        if isinstance(self.token, QpuToken):
+            return TokenProvider(dwave=self.token)
+        return TokenProvider(
+            dwave=QpuToken(
+                source=QpuTokenSource.INLINE,
+                token=self.token,
+            )
+        )

luna_quantum/solve/parameters/backends/ibm.py

@@ -0,0 +1,132 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from luna_quantum.solve.interfaces.backend_i import IBackend
+
+
+class IBM(IBackend):
+    """IBM quantum backend configuration.
+
+    This class provides configuration options for IBM quantum backends, supporting
+    both local simulators and fake provider backends for quantum algorithm execution.
+    The configuration allows users to specify which type of backend to use without
+    requiring an IBM token for simulator-based execution.
+
+    The class supports two main backend types:
+
+    - Simulator backends: Execute quantum algorithms locally using simulators
+    - Fake provider backends: Use IBM's fake backends for testing and development
+
+    Attributes
+    ----------
+    backend : SimulatorBackend | FakeProviderBackend
+        The backend configuration, defaults to AER simulator.
+    """
+
+    class SimulatorBackend(BaseModel):
+        """Simulator.
+
+        Use a simulator as backend. The QAOA is executed completely on our server, and
+        no IBM token is required.
+
+        Attributes
+        ----------
+        backend_name: Literal['aer', 'statevector']
+            Which simulator to use. Currently, `AerSimulator` from `qiskit_aer`
+            and the statevector simulator from `qiskit.primitives` are available.
+        """
+
+        backend_type: Literal["simulator"] = "simulator"
+        backend_name: Literal["aer", "statevector"] = "aer"
+
+    class FakeProviderBackend(BaseModel):
+        """FaleProvider.
+
+        Use a V2 fake backend from `qiskit_ibm_runtime.fake_provider`. The QAOA is
+        executed entirely on our server, and no IBM token is required.
+
+        Attributes
+        ----------
+        backend_name: str
+            Which backend to use
+        """
+
+        backend_type: Literal["fake_provider"] = "fake_provider"
+        backend_name: Literal[
+            "FakeAlgiers",
+            "FakeAlmadenV2",
+            "FakeArmonkV2",
+            "FakeAthensV2",
+            "FakeAuckland",
+            "FakeBelemV2",
+            "FakeBoeblingenV2",
+            "FakeBogotaV2",
+            "FakeBrisbane",
+            "FakeBrooklynV2",
+            "FakeBurlingtonV2",
+            "FakeCairoV2",
+            "FakeCambridgeV2",
+            "FakeCasablancaV2",
+            "FakeCusco",
+            "FakeEssexV2",
+            "FakeFez",
+            "FakeFractionalBackend",
+            "FakeGeneva",
+            "FakeGuadalupeV2",
+            "FakeHanoiV2",
+            "FakeJakartaV2",
+            "FakeJohannesburgV2",
+            "FakeKawasaki",
+            "FakeKolkataV2",
+            "FakeKyiv",
+            "FakeKyoto",
+            "FakeLagosV2",
+            "FakeLimaV2",
+            "FakeLondonV2",
+            "FakeManhattanV2",
+            "FakeManilaV2",
+            "FakeMarrakesh",
+            "FakeMelbourneV2",
+            "FakeMontrealV2",
+            "FakeMumbaiV2",
+            "FakeNairobiV2",
+            "FakeOsaka",
+            "FakeOslo",
+            "FakeOurenseV2",
+            "FakeParisV2",
+            "FakePeekskill",
+            "FakePerth",
+            "FakePrague",
+            "FakePoughkeepsieV2",
+            "FakeQuebec",
+            "FakeQuitoV2",
+            "FakeRochesterV2",
+            "FakeRomeV2",
+            "FakeSantiagoV2",
+            "FakeSherbrooke",
+            "FakeSingaporeV2",
+            "FakeSydneyV2",
+            "FakeTorino",
+            "FakeTorontoV2",
+            "FakeValenciaV2",
+            "FakeVigoV2",
+            "FakeWashingtonV2",
+            "FakeYorktownV2",
+        ]
+
+    backend: SimulatorBackend | FakeProviderBackend = Field(
+        default=SimulatorBackend(), discriminator="backend_type"
+    )
+
+    @property
+    def provider(self) -> str:
+        """
+        Retrieve the name of the provider.
+
+        Returns
+        -------
+        str
+            The name of the provider.
+        """
+        return "ibm"

luna_quantum/solve/parameters/backends/qctrl.py

@@ -0,0 +1,130 @@
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from luna_quantum.client.schemas import QpuToken, QpuTokenSource, TokenProvider
+from luna_quantum.solve.domain.abstract import QpuTokenBackend
+
+
+class Qctrl(QpuTokenBackend):
+    """
+    Configuration parameters for Q-CTRL`s Fire Opal Backend.
+
+    QAOA (Quantum Approximate Optimization Algorithm) is a quantum algorithm designed
+    for combinatorial optimization problems. This implementation leverages Q-CTRL's
+    Fire Opal framework, which optimizes QAOA execution on quantum hardware to reduce
+    errors and improve solution quality.
+
+    Fire Opal's hardware-tailored optimizations enable solving larger problems with
+    better convergence in fewer iterations, reducing overall execution time on real
+    quantum devices.
+
+    Attributes
+    ----------
+    organization_slug: str | None, default=None
+        Organization identifier from your Q-CTRL account. Required only if you belong
+        to multiple organizations. This can be retrieved from your Q-CTRL account
+        settings or dashboard.
+
+    backend_name: str | None, default=None
+        The IBM Quantum backend to use for computations:
+        - Specific backend: e.g., 'ibm_fez', 'ibm_marrakesh'
+        - 'least_busy': Automatically selects the least busy available backend
+        - 'basic_simulator': Uses the basic simulator (default if None)
+        Check your IBM Quantum account for available backends.
+
+    ibm_credentials: QCtrl.IBMQ | QCtrl.IBMCloud, default=Qctrl.IBMQ()
+        The IBM backend credentials, i.e. how to access the IBM service. Q-Ctrl
+        currently supports two mehtods, via the old IBMQ pattern or the new IBMCloud
+        pattern.
+
+    token: QpuToken | str | None, default=None
+        The Q-Ctrl API token.
+
+
+    Notes
+    -----
+    For detailed information about Fire Opal's QAOA solver and its capabilities,
+    see Q-CTRL's documentation: https://docs.q-ctrl.com/fire-opal/topics/fire-opals-qaoa-solver
+    """
+
+    class IBMQ(BaseModel):
+        """
+        Configuration parameters for the IBM Quantum backend.
+
+        Attributes
+        ----------
+        hub: str, default="ibm-q"
+            The IBM Quantum hub to use for accessing quantum resources.
+            This defines your access level and available systems.
+
+        group: str, default="open"
+            The IBM Quantum group within your hub.
+            Groups help organize users and projects within a hub.
+
+        project: str, default="main"
+            The IBM Quantum project within your group.
+            Projects help organize work and resource allocation.
+
+        token: Union[str, None, QpuToken], default=None
+            The IBM API token.
+        """
+
+        hub: str = "ibm-q"
+        group: str = "open"
+        project: str = "main"
+
+        token: str | QpuToken | None = Field(repr=False, exclude=True, default=None)
+
+    class IBMCloud(BaseModel):
+        """
+        Configuration parameters for the IBM Cloud backend.
+
+        Attributes
+        ----------
+        instance: str
+            The Qiskit runtime instance CRN (Cloud Resource Name).
+
+        token: Union[str, None, QpuToken], default=None
+            The IBM API token.
+        """
+
+        instance: str
+
+        token: str | QpuToken | None = Field(repr=False, exclude=True, default=None)
+
+    organization_slug: Any = None
+    backend_name: str | None = None
+
+    ibm_credentials: IBMQ | IBMCloud = Field(default=IBMQ())
+
+    token: str | QpuToken | None = Field(repr=False, exclude=True, default=None)
+
+    def _get_token(self) -> TokenProvider | None:
+        if self.token is None or self.ibm_credentials.token is None:
+            return None
+        qctrl_token = (
+            self.token
+            if isinstance(self.token, QpuToken)
+            else QpuToken(source=QpuTokenSource.INLINE, token=self.token)
+        )
+        ibm_token = (
+            self.ibm_credentials.token
+            if isinstance(self.ibm_credentials.token, QpuToken)
+            else QpuToken(
+                source=QpuTokenSource.INLINE, token=self.ibm_credentials.token
+            )
+        )
+        return TokenProvider(qctrl=qctrl_token, ibm=ibm_token)
+
+    @property
+    def provider(self) -> str:
+        """
+        Retrieve the name of the provider.
+
+        Returns
+        -------
+        str
+            The name of the provider.
+        """
+        return "qctrl"

luna_quantum/solve/parameters/backends/zib.py

@@ -0,0 +1,17 @@
+from luna_quantum.solve.interfaces.backend_i import IBackend
+
+
+class ZIB(IBackend):
+    """Configuration class for the ZIB backend."""
+
+    @property
+    def provider(self) -> str:
+        """
+        Retrieve the name of the provider.
+
+        Returns
+        -------
+        str
+            The name of the provider.
+        """
+        return "zib"

luna_quantum/solve/parameters/constants.py

@@ -0,0 +1,11 @@
+# The default absolute tolerance that should be used for `numpy.isclose(...)`
+# calls. Equal to the default used in `numpy.isclose(..)`.
+DEFAULT_ATOL: float = 1.0e-8
+
+# The default relative tolerance that should be used for ``numpy.isclose(...)``
+# calls. Equal to the default used in ``numpy.isclose(..)``.
+DEFAULT_RTOL: float = 1.0e-5
+
+# The default timeout used for solver run with a specified target.
+# Number of seconds before routine halts. Default is 2592000 for dimod.qbsolv.
+DEFAULT_TIMEOUT: int = 10