luna-quantum 1.0.0__cp312-cp312-macosx_10_12_x86_64.whl

luna_quantum/solve/parameters/algorithms/quantum_annealing/quantum_annealing.py

@@ -0,0 +1,105 @@
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.algorithms.base_params import (
+    QuantumAnnealingParams,
+)
+from luna_quantum.solve.parameters.backends import DWaveQpu
+
+
+class QuantumAnnealing(QuantumAnnealingParams, LunaAlgorithm[DWaveQpu]):
+    """
+    Quantum Annealing algorithm for physical quantum processors (QPUs).
+
+    Quantum Annealing is a metaheuristic that leverages quantum effects to find the
+    ground state of a system, corresponding to the optimal solution of an optimization
+    problem.
+
+    The process starts in a quantum superposition of all possible states, and gradually
+    evolves the system according to a time-dependent Hamiltonian, exploiting quantum
+    tunneling to potentially escape local minima more effectively than classical
+    methods.
+
+    This implementation is specifically for D-Wave quantum annealers or similar
+    hardware.
+
+    This class inherits all parameters from QuantumAnnealingParams, providing
+    a complete set of controls for the quantum annealing process on hardware devices.
+
+    Attributes
+    ----------
+    anneal_offsets: Any | None
+        Per-qubit time offsets for the annealing path. Default is None.
+    anneal_schedule: Any | None
+        Custom schedule for the annealing process. Default is None.
+    annealing_time: Any | None
+        Duration of the annealing process in microseconds. Default is None.
+    auto_scale: Any | None
+        Whether to automatically normalize the problem energy range.
+        Default is None.
+    fast_anneal: bool
+        Use accelerated annealing protocol. Default is False.
+    flux_biases: Any | None
+        Custom flux bias offsets for each qubit. Default is None.
+    flux_drift_compensation: bool
+        Whether to compensate for drift in qubit flux over time. Default is True.
+    h_gain_schedule: Any | None
+        Schedule for h-gain during annealing. Default is None.
+    initial_state: Any | None
+        Starting state for the annealing process. Default is None.
+    max_answers: int | None
+        Maximum number of unique answer states to return. Default is None.
+    num_reads: int
+        Number of annealing cycles to perform. Default is 1.
+    programming_thermalization: float | None
+        Wait time after programming the QPU. Default is None.
+    readout_thermalization: float | None
+        Wait time after each anneal before reading results. Default is None.
+    reduce_intersample_correlation: bool
+        Whether to add delay between samples. Default is False.
+    reinitialize_state: bool | None
+        Whether to reset to a new initial state between reads. Default is None.
+    """
+
+    @property
+    def algorithm_name(self) -> str:
+        """
+        Returns the name of the algorithm.
+
+        This abstract property method is intended to be overridden by subclasses.
+        It should provide the name of the algorithm being implemented.
+
+        Returns
+        -------
+        str
+            The name of the algorithm.
+        """
+        return "QA"
+
+    @classmethod
+    def get_default_backend(cls) -> DWaveQpu:
+        """
+        Return the default backend implementation.
+
+        This property must be implemented by subclasses to provide
+        the default backend instance to use when no specific backend
+        is specified.
+
+        Returns
+        -------
+            IBackend
+                An instance of a class implementing the IBackend interface that serves
+                as the default backend.
+        """
+        return DWaveQpu()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWaveQpu], ...]:
+        """
+        Check at runtime if the used backend is compatible with the solver.
+
+        Returns
+        -------
+        tuple[type[IBackend], ...]
+            True if the backend is compatible with the solver, False otherwise.
+
+        """
+        return (DWaveQpu,)

luna_quantum/solve/parameters/algorithms/quantum_annealing/repeated_reverse_quantum_annealing.py

@@ -0,0 +1,174 @@
+from typing import Any
+
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.backends import DWaveQpu
+
+
+class RepeatedReverseQuantumAnnealing(LunaAlgorithm[DWaveQpu]):
+    """
+    Parameters for the Repeated Reverse Quantum Annealing algorithm.
+
+    This approach combines reverse annealing (starting from a classical state) with
+    repetition to refine solutions iteratively. It's particularly useful for:
+    1. Local refinement of solutions found by classical methods
+    2. Escaping local minima by temporarily increasing quantum fluctuations
+    3. Improving solutions through multiple rounds of quantum optimization
+
+    The process involves:
+    - Starting with classical initial states
+    - Partially "unsolving" them by increasing quantum fluctuations
+    - Re-annealing to find potentially better nearby solutions
+    - Repeating with the best solutions found
+
+    Attributes
+    ----------
+    anneal_offsets: Any | None
+        Per-qubit time offsets for the annealing path, allowing qubits to anneal at
+        different rates. Useful for problems with varying energy scales or when certain
+        qubits need different annealing trajectories. Default is None, which uses
+        standard annealing for all qubits.
+    annealing_time: Any | None
+        Duration of the annealing process in microseconds. Longer times can improve
+        solution quality for problems with small energy gaps but increase runtime.
+        Default is None, which uses the QPU's default annealing time.
+    auto_scale: Any | None
+        Whether to automatically normalize the problem energy range to match hardware
+        capabilities, preventing precision issues in the physical implementation.
+        Default is None, which uses the D-Wave system's default setting.
+    flux_biases: Any | None
+        Custom flux bias offsets for each qubit to compensate for manufacturing
+        variations in the QPU hardware or to intentionally bias certain qubits.
+        Default is None, using standard calibration values.
+    flux_drift_compensation: bool
+        Whether to compensate for drift in qubit flux over time, improving the
+        reliability and consistency of results across multiple runs.
+        Default is True, which is recommended for most applications.
+    h_gain_schedule: Any | None
+        Schedule for h-gain (linear coefficient strength) during annealing,
+        allowing dynamic adjustment of problem coefficients throughout the process.
+        Default is None, using standard gain settings.
+    max_answers: int | None
+        Maximum number of unique answer states to return from the quantum hardware.
+        Useful for collecting diverse solutions while filtering out duplicates.
+        Must be greater than or equal to 1 if specified. Default is None, which returns
+        all unique solutions found.
+    programming_thermalization: float | None
+        Wait time (in microseconds) after programming the QPU, allowing it to
+        reach thermal equilibrium before starting the annealing process.
+        Must be positive if specified. Default is None, using system default.
+    readout_thermalization: float | None
+        Wait time (in microseconds) after each anneal before reading results.
+        Helps ensure the qubits have settled into their final states before measurement.
+        Must be positive if specified. Default is None, using system default.
+    reduce_intersample_correlation: bool
+        Whether to add delay between samples to reduce temporal correlations
+        that might bias results across multiple runs. Default is False to minimize
+        runtime, but can be set to True when sample independence is critical.
+    initial_states: list[dict[str, int]] | None
+        Initial classical states to start the reverse annealing from, specified as
+        dictionaries mapping variable names to binary values (0 or 1). For each state,
+        one call to the sampler with parameter `initial_state=state` will be made
+        in the first iteration. Default is None, in which case random or specified
+        states are generated according to n_initial_states.
+    n_initial_states: int
+        Number of initial states to create when `initial_states` is None.
+        Controls the diversity of starting points for the algorithm.
+        Ignored if `initial_states` is provided. Default is 1. Must be ≥1.
+    samples_per_state: int
+        How many samples to create per state in each iteration after the first.
+        More samples increase the chance of finding improvements but use more QPU time.
+        Controls the breadth of exploration around each promising solution.
+        Default is 1. Must be ≥1.
+    beta_schedule: list[float]
+        Beta schedule controlling the quantum fluctuation strength during reverse
+        annealing. Beta is the inverse temperature (1/T), with lower values allowing
+        more thermal excitation to explore the energy landscape more widely.
+        Default [0.5, 3] provides moderate initial fluctuation followed by cooling,
+        balancing exploration and exploitation.
+    timeout: float
+        Maximum runtime in seconds before the solver stops, regardless of convergence.
+        Provides a hard time limit to ensure the algorithm completes within a reasonable
+        timeframe. Default is 300 seconds (5 minutes), balancing solution quality with
+        timeliness.
+    max_iter: int
+        Maximum number of iterations (reverse annealing cycles) to perform.
+        Each iteration refines the solutions from the previous round, potentially
+        discovering better solutions in the neighborhood of good candidates.
+        Default is 10, providing good refinement without excessive QPU usage.
+    target: Any | None
+        Target energy value that, if reached, causes the algorithm to terminate early.
+        Allows for early stopping when a sufficiently good solution is found.
+        Default is None (run until other stopping criteria are met).
+    check_trivial: bool
+        Whether to check for and handle trivial variables (those without interactions)
+        before sending the problem to the QPU. Adds some computational overhead but
+        prevents potential runtime errors and improves embedding efficiency.
+        Default is True, which is recommended for robust operation.
+    """
+
+    anneal_offsets: Any | None = None
+    annealing_time: Any | None = None
+    auto_scale: Any | None = None
+    flux_biases: Any | None = None
+    flux_drift_compensation: bool = True
+    h_gain_schedule: Any | None = None
+    max_answers: int | None = Field(default=None, ge=1)
+    programming_thermalization: float | None = Field(default=None, gt=0)
+    readout_thermalization: float | None = Field(default=None, gt=0)
+    reduce_intersample_correlation: bool = False
+
+    initial_states: list[dict[str, int]] | None = None
+    n_initial_states: int = Field(default=1, ge=1)
+    samples_per_state: int = Field(default=1, ge=1)
+    beta_schedule: list[float] = Field(default_factory=lambda: [0.5, 3])
+    timeout: float = 300
+    max_iter: int = 10
+    target: Any | None = None
+    check_trivial: bool = True
+
+    @property
+    def algorithm_name(self) -> str:
+        """
+        Returns the name of the algorithm.
+
+        This abstract property method is intended to be overridden by subclasses.
+        It should provide the name of the algorithm being implemented.
+
+        Returns
+        -------
+        str
+            The name of the algorithm.
+        """
+        return "RRQA"
+
+    @classmethod
+    def get_default_backend(cls) -> DWaveQpu:
+        """
+        Return the default backend implementation.
+
+        This property must be implemented by subclasses to provide
+        the default backend instance to use when no specific backend
+        is specified.
+
+        Returns
+        -------
+            IBackend
+                An instance of a class implementing the IBackend interface that serves
+                as the default backend.
+        """
+        return DWaveQpu()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWaveQpu], ...]:
+        """
+        Check at runtime if the used backend is compatible with the solver.
+
+        Returns
+        -------
+        tuple[type[IBackend], ...]
+            True if the backend is compatible with the solver, False otherwise.
+
+        """
+        return (DWaveQpu,)

luna_quantum/solve/parameters/algorithms/quantum_gate/__init__.py

@@ -0,0 +1,6 @@
+from .flex_qaoa import FlexQAOA
+from .qaoa import QAOA
+from .qaoa_fo import QAOA_FO
+from .vqe import VQE
+
+__all__ = ["QAOA", "QAOA_FO", "VQE", "FlexQAOA"]

luna_quantum/solve/parameters/algorithms/quantum_gate/flex_qaoa/__init__.py

@@ -0,0 +1,26 @@
+from .config import AdvancedConfig, XYMixer
+from .flex_qaoa import FlexQAOA
+from .optimizers import (
+    CombinedOptimizerParams,
+    InterpolateOptimizerParams,
+    LinearOptimizerParams,
+)
+from .pipeline import (
+    IndicatorFunctionParams,
+    OneHotParams,
+    PipelineParams,
+    QuadraticPenaltyParams,
+)
+
+__all__ = [
+    "AdvancedConfig",
+    "CombinedOptimizerParams",
+    "FlexQAOA",
+    "IndicatorFunctionParams",
+    "InterpolateOptimizerParams",
+    "LinearOptimizerParams",
+    "OneHotParams",
+    "PipelineParams",
+    "QuadraticPenaltyParams",
+    "XYMixer",
+]

luna_quantum/solve/parameters/algorithms/quantum_gate/flex_qaoa/config.py

@@ -0,0 +1,80 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from luna_quantum.solve.errors.solve_base_error import SolveBaseError
+
+
+class MixerTypeError(SolveBaseError):
+    """Custom Mixer type exception."""
+
+    def __init__(self) -> None:
+        super().__init__("XY-mixer type can only occur once.")
+
+
+class XYMixer(BaseModel):
+    """XY-mixer configuration.
+
+    Attributes
+    ----------
+    types: list[Literal["even", "odd", "last"]]
+        XY-ring-mixer pipeline
+    """
+
+    types: list[Literal["even", "odd", "last"]] = Field(
+        default=["even", "odd", "last"],
+        description="XY-ring-mixer types and order.",
+    )
+
+    @field_validator("types")
+    @classmethod
+    def _validate_type_once(
+        cls, v: list[Literal["even", "odd", "last"]]
+    ) -> list[Literal["even", "odd", "last"]]:
+        if len(set(v)) < len(v):
+            raise MixerTypeError
+        return v
+
+
+class AdvancedConfig(BaseModel):
+    """Additional FlexQAOA algorithm configuration.
+
+    Attributes
+    ----------
+    mixer: XYMixer | Dict
+        Mixer types in XY-ring-mixer. Default: `["even", "odd", "last"]`
+    parallel_indicators: bool
+        Toggle to apply indicator functions in parallel. Does not affect sampling
+        performance of QAOA, but only circuit metrics, like number of qubits and
+        circuit depth.
+    discard_slack: bool
+        Discard slack qubits in evaluation, i.e. only measure on the binary variables of
+        the initial problem. This requires an auxilary cost function that penalizes
+        infeasible solutions.
+    infeas_penalty: float | None
+        Penalty for infeasible solutions if `discard_slack` is activated. By defalt,
+        10 times the max absolute intial bias is chosen.
+    """
+
+    mixer: XYMixer = Field(
+        default_factory=lambda: XYMixer(),
+        description='Mixer types in XY-ring-mixer. Default: `["even", "odd", "last"]`',
+    )
+    parallel_indicators: bool = Field(
+        default=True,
+        description="Toggle to apply indicator functions in parallel. Does not affect "
+        "sampling performance of QAOA, but only circuit metrics, "
+        "like number of qubits and circuit depth.",
+    )
+    discard_slack: bool = Field(
+        default=False,
+        description="Discard slack qubits in evaluation, i.e. only measure on the "
+        "binary variables of the initial problem. This requires an auxilary cost "
+        "function that penalizes infeasible solutions.",
+    )
+    infeas_penalty: float | None = Field(
+        default=None,
+        ge=0,
+        description="Penalty for infeasible solutions if `discard_slack` is activated."
+        "By defalt, 10 times the max absolute intial bias is chosen.",
+    )

luna_quantum/solve/parameters/algorithms/quantum_gate/flex_qaoa/flex_qaoa.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field, model_validator
+
+from luna_quantum.solve.domain.abstract.luna_algorithm import LunaAlgorithm
+from luna_quantum.solve.errors.solve_base_error import SolveBaseError
+from luna_quantum.solve.parameters.algorithms.base_params.qaoa_circuit_params import (
+    BasicQAOAParams,
+    LinearQAOAParams,
+    RandomQAOAParams,
+)
+from luna_quantum.solve.parameters.algorithms.base_params.scipy_optimizer import (
+    ScipyOptimizerParams,
+)
+from luna_quantum.solve.parameters.backends.aqarios import Aqarios
+
+from .config import AdvancedConfig
+from .optimizers import (
+    CombinedOptimizerParams,
+    InterpolateOptimizerParams,
+    LinearOptimizerParams,
+)
+from .pipeline import PipelineParams
+
+
+class QAOAParameterOptimizerError(SolveBaseError):
+    """QAOA cirucit parameters mismatch with optimizer exception."""
+
+    def __init__(
+        self,
+        optimizer: ScipyOptimizerParams
+        | LinearOptimizerParams
+        | CombinedOptimizerParams
+        | InterpolateOptimizerParams
+        | None,
+        params: BasicQAOAParams | LinearQAOAParams | RandomQAOAParams,
+        extra: str = "",
+    ) -> None:
+        super().__init__(
+            f"Parameter Mismatch of {optimizer.__class__} and {params.__class__}"
+            + ((". " + extra) if extra else "")
+        )
+
+
+class InterpolateOptimizerError(SolveBaseError):
+    """Interpolate optimizer error when final number of reps is too small."""
+
+    def __init__(self, reps_end: int, reps_start: int) -> None:
+        super().__init__(f"{reps_end=} needs to be larger than {reps_start=}.")
+
+
+class QAOAParameterDepthMismatchError(SolveBaseError):
+    """QAOA circuit params mismatch the specified reps."""
+
+    def __init__(self, params_reps: int, reps: int) -> None:
+        super().__init__(f"{params_reps=} needs to match {reps=}.")
+
+
+class FlexQAOA(LunaAlgorithm[Aqarios], BaseModel):
+    """The FlexQAOA Algorithm for constrained quantum optimization.
+
+    The FlexQAOA is an extension to the default QAOA with the capabilities to encode
+    inequality constriants with indicator functions as well as one-hot constraints
+    through XY-mixers. This algorithm will dynamically extract all constraints from the
+    given constraint input optimization model, and construct an accoring QAOA circuit.
+    Currently only simulation of the circuit is supported. But due to the constrained
+    nature, the subspace of the Hilbertspace required for simulation is smaller,
+    depending on the problem instance. This allows for simulation of problems with
+    more qubits than ordinary state vector simulation allows. For now, the simulation
+    size is limited to Hilbertspaces with less <= 2**18 dimensions.
+
+    The FlexQAOA allows for a dynamic circuit construction depending on input paramters.
+    Central to this is the pipeline parameter which allows for different configurations.
+
+    For instance, if one likes to explore ordinary QUBO simulation with all constraints
+    represented as quadratic penalties, the `one_hot` and `indicator_function` options
+    need to be manually disabled
+    ```
+    pipeline = {"one_hot": None, "indicator_function": None}
+    ```
+
+    If no indicator function is employed, but the input problem contains inequality
+    constraints, slack variables are added to the optimization problem. FlexQAOA allows
+    for a configuration that discards slack variables as their assignment is not
+    necessarily of interest. This option can be enbled by setting
+    ```
+    qaoa_config = {"discard_slack": True}
+    ```
+
+    Following the standard protocol for QAOA, a classical optimizer is required that
+    tunes the variational parameters of the circuit. Besides the classical
+    `ScipyOptimizer` other optimizers are also featured, allowing for optimizing only a
+    linear schedule, starting with optimizing for a linear schedule followed by
+    individual parameter fine tuning, and interpolating between different QAOA circuit
+    depts.
+
+    Attributes
+    ----------
+    shots: int
+        Number of sampled shots.
+    reps: int
+        Number of QAOA layer repetitions
+    pipeline: PipelineParams | Dict
+        The pipeline defines the selected features for QAOA circuit generation. By
+        default, all supported features are enabled (one-hot constraints, inequality
+        constraints and quadratic penalties).
+    optimizer: ScipyOptimizerParams | LinearOptimizerParams | CombinedOptimizerParams |\
+        InterpolateOptimizerParams | None | Dict
+        The classical optimizer for parameter tuning. Default: ScipyOptimizer. Setting
+        to `None` disables the optimization, leading to an evaluation of the initial
+        parameters.
+    qaoa_config: AdvancedConfig | Dict
+        Additional options for the QAOA circuit and evalutation
+    initial_params: LinearQAOAParams | BasicQAOAParams | RandomQAOAParams | Dict
+        Custom QAOA variational circuit parameters. By default linear
+        increasing/decreasing parameters for the selected `reps` are generated.
+    """
+
+    shots: int = Field(default=1024, ge=1, description="Number of sampled shots.")
+    reps: int = Field(default=1, ge=1, description="Number of QAOA layer repetitions")
+    pipeline: PipelineParams = Field(
+        default_factory=lambda: PipelineParams(),
+        description="The pipeline defines the selected features for QAOA circuit "
+        "generation. By default, all supported features are enabled "
+        "(one-hot constraints, inequality constraints and quadratic penalties).",
+    )
+    optimizer: (
+        ScipyOptimizerParams
+        | LinearOptimizerParams
+        | CombinedOptimizerParams
+        | InterpolateOptimizerParams
+        | None
+    ) = Field(
+        default_factory=lambda: ScipyOptimizerParams(),
+        description="The classical optimizer. Default: ScipyOptimizer",
+    )
+    qaoa_config: AdvancedConfig = Field(
+        default_factory=lambda: AdvancedConfig(),
+        description="Additional options for the QAOA circuit and evalutation",
+    )
+    initial_params: LinearQAOAParams | BasicQAOAParams | RandomQAOAParams = Field(
+        default_factory=lambda: LinearQAOAParams(delta_beta=0.5, delta_gamma=0.5),
+        description="Custom QAOA circuit parameters. By default linear "
+        "increasing/decreasing parameters for the selected `reps` are generated.",
+    )
+
+    @model_validator(mode="after")
+    def _check_param_type(self) -> FlexQAOA:
+        if isinstance(self.optimizer, LinearOptimizerParams) and isinstance(
+            self.initial_params, BasicQAOAParams
+        ):
+            raise QAOAParameterOptimizerError(self.optimizer, self.initial_params)
+        if isinstance(self.optimizer, CombinedOptimizerParams) and isinstance(
+            self.initial_params, BasicQAOAParams
+        ):
+            raise QAOAParameterOptimizerError(self.optimizer, self.initial_params)
+        if (
+            isinstance(self.optimizer, InterpolateOptimizerParams)
+            and isinstance(self.optimizer.optimizer, LinearOptimizerParams)
+            and isinstance(self.initial_params, BasicQAOAParams)
+        ):
+            raise QAOAParameterOptimizerError(
+                self.optimizer,
+                self.initial_params,
+                extra="LinearOptimizer used in InterpolateOptimizer.",
+            )
+        if (
+            isinstance(self.optimizer, InterpolateOptimizerParams)
+            and self.optimizer.reps_end < self.reps
+        ):
+            raise InterpolateOptimizerError(self.optimizer.reps_end, self.reps)
+        return self
+
+    @model_validator(mode="after")
+    def _check_depth(self) -> FlexQAOA:
+        if (
+            isinstance(self.initial_params, BasicQAOAParams)
+            and self.initial_params.reps != self.reps
+        ):
+            raise QAOAParameterDepthMismatchError(self.initial_params.reps, self.reps)
+        return self
+
+    @property
+    def algorithm_name(self) -> str:
+        """
+        Returns the name of the algorithm.
+
+        This abstract property method is intended to be overridden by subclasses.
+        It should provide the name of the algorithm being implemented.
+
+        Returns
+        -------
+        str
+            The name of the algorithm.
+        """
+        return "FlexQAOA"
+
+    @classmethod
+    def get_default_backend(cls) -> Aqarios:
+        """
+        Return the default backend implementation.
+
+        This property must be implemented by subclasses to provide
+        the default backend instance to use when no specific backend
+        is specified.
+
+        Returns
+        -------
+            IBackend
+                An instance of a class implementing the IBackend interface that serves
+                as the default backend.
+        """
+        return Aqarios()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[Aqarios]]:
+        """
+        Check at runtime if the used backend is compatible with the solver.
+
+        Returns
+        -------
+        tuple[type[IBackend], ...]
+            True if the backend is compatible with the solver, False otherwise.
+
+        """
+        return (Aqarios,)