luna-quantum 1.0.0__cp312-cp312-musllinux_1_2_x86_64.whl

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

@@ -0,0 +1,97 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from luna_quantum.solve.parameters.algorithms.base_params.scipy_optimizer import (
+    ScipyOptimizerParams,
+)
+
+
+class LinearOptimizerParams(ScipyOptimizerParams):
+    """Optimizer for tuning a linear schedule of QAOA parameters.
+
+    Optimizes onyl two parameters: `delta_beta` and `delta_gamma` with the default
+    ScipyOptimizer.
+
+    Wrapper for scipy.optimize.minimize. See
+    https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html
+    for more information of the available methods and parameters.
+
+    Attributes
+    ----------
+    method: ScipyOptimizerMethod
+        Type of solver. See
+        https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html
+        for supported methods.
+    tol: float | None
+        Tolerance for termination.
+    bounds: None | tuple[float, float] | list[tuple[float, float]]
+        Bounds on variables for Nelder-Mead, L-BFGS-B, TNC, SLSQP, Powell,
+        trust-constr, COBYLA, and COBYQA methods. None is used to specify no bounds,
+        `(min, max)` is used to specify bounds for all variables. A sequence of
+        `(min, max)` can be used to specify bounds for each parameter individually.
+    jac: None | Literal["2-point", "3-point", "cs"]
+        Method for computing the gradient vector. Only for CG, BFGS, Newton-CG,
+        L-BFGS-B, TNC, SLSQP, dogleg, trust-ncg, trust-krylov, trust-exact and
+        trust-constr.
+    hess: None | Literal["2-point", "3-point", "cs"]
+        Method for computing the Hessian matrix. Only for Newton-CG, dogleg, trust-ncg,
+        trust-krylov, trust-exact and trust-constr.
+    maxiter: int
+        Maximum number of iterations to perform. Depending on the method
+        each iteration may use several function evaluations. Will be ignored for TNC
+        optimizer. Default: 100
+    options: dict[str, float]
+        A dictionary of solver options.
+    """
+
+    optimizer_type: Literal["linear"] = "linear"
+
+
+class CombinedOptimizerParams(BaseModel):
+    """Combination of LinearOptimizer and ScipyOptimizer.
+
+    Optimizer that first performs an optimization of the linear schedule and then
+    fine tunes individual parameters.
+
+
+    Attributes
+    ----------
+    linear: LinearOptimizerParams | Dict
+        Parameters of the linear optimizer.
+    fine_tune: ScipyOptimizerParams | Dict
+        Parameters of the fine tuning optimizer.
+    """
+
+    optimizer_type: Literal["combined"] = "combined"
+    linear: LinearOptimizerParams = Field(
+        default_factory=lambda: LinearOptimizerParams()
+    )
+    fine_tune: ScipyOptimizerParams = Field(
+        default_factory=lambda: ScipyOptimizerParams()
+    )
+
+
+class InterpolateOptimizerParams(BaseModel):
+    """Optimizer with sequentially increasing number of QAOA layers.
+
+    Optimizer that starts with `reps` iteration and interpolates sequentially in
+    `reps_step` steps to `reps_end`. In between it performs a full optimization routine
+    tunes individual parameters.
+
+    Attributes
+    ----------
+    optimiezr: LinearOptimizerParams | ScipyOptimizerParams | Dict
+        Parameters of the optimizer.
+    reps_step: int
+        Number of QAOA layers added for one interpolation.
+    reps_end: int
+        Final number of QAOA layers to be reached.
+    """
+
+    optimizer_type: Literal["interpolate"] = "interpolate"
+    optimizer: ScipyOptimizerParams | LinearOptimizerParams = Field(
+        default_factory=lambda: ScipyOptimizerParams()
+    )
+    reps_step: int = Field(default=1, ge=1)
+    reps_end: int = Field(default=10, ge=1)

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

@@ -0,0 +1,87 @@
+from pydantic import BaseModel, Field
+
+
+class OneHotParams(BaseModel):
+    """Implements one-hot constraints through XY-mixers."""
+
+
+class IndicatorFunctionParams(BaseModel):
+    """Implements inequality constraints via indicator functions.
+
+    Attributes
+    ----------
+    penalty: float | None
+        Custom penalty factor for indicator functions. If none set, automatically
+        determined through upper and lower bounds.
+    penalty_scaling: float
+        Scaling of automatically determined penalty factor. Default: 2
+    """
+
+    penalty: float | None = Field(
+        default=None,
+        ge=0,
+        description="Custom penalty factor for indicator functions. If none set, "
+        "automatically determined through upper and lower bounds.",
+    )
+    penalty_scaling: float = Field(
+        default=2,
+        ge=0,
+        description="Scaling of automatically determined penalty factor. Default: 2",
+    )
+
+
+class QuadraticPenaltyParams(BaseModel):
+    """Implements all constraints through quadratic penalties.
+
+    Adds penalty terms to the objective. Adds slack variables for inequality constraints
+    if neccessaray.
+
+    Attributes
+    ----------
+    penalty: float | None
+        Custom penalty factor for quadratic penalty terms. If none is set, it is
+        automatically determined by taking 10 times the maximum absolute initial bias.
+    """
+
+    penalty: float | None = Field(
+        default=None,
+        ge=0,
+        description="Custom penalty factor for quadratic penalty terms. If none set, "
+        "automatically determined by taking 10 times the maximum absolute initial "
+        "bias.",
+    )
+
+
+class PipelineParams(BaseModel):
+    """Defines the modular Constrained QAOA Pipeline.
+
+    By default all features are enabled.
+
+    Attributes
+    ----------
+    indicator_function: IndicatorFunctionParams | Dict | None
+        Whether to implement inequality constraints with indicator functions. Disable
+        with setting to `None`.
+    one_hot: OneHotParams | Dict | None
+        Whether to implement inequality constraints with indicator functions. Disable
+        with setting to `None`.
+    quadratic_penalty: QuadraticPenaltyParams | Dict | None
+        Whether to implement inequality constraints with indicator functions. Disable
+        with setting to `None`.
+    """
+
+    indicator_function: IndicatorFunctionParams | None = Field(
+        default_factory=lambda: IndicatorFunctionParams(),
+        description="Whether to implement inequality constraints with indicator "
+        "functions. Disable with setting to `None`.",
+    )
+    one_hot: OneHotParams | None = Field(
+        default_factory=lambda: OneHotParams(),
+        description="Whether to implement inequality constraints with indicator "
+        "functions. Disable with setting to `None`.",
+    )
+    quadratic_penalty: QuadraticPenaltyParams | None = Field(
+        default_factory=lambda: QuadraticPenaltyParams(),
+        description="Whether to implement inequality constraints with indicator "
+        "functions. Disable with setting to `None`.",
+    )

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

@@ -0,0 +1,104 @@
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+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 import AWS, IBM, IQM, IonQ, Rigetti
+
+
+class QAOA(LunaAlgorithm[AWS | IonQ | IQM | Rigetti | IBM]):
+    """
+    Quantum Approximate Optimization Algorithm (QAOA).
+
+    QAOA is a hybrid quantum-classical algorithm for solving combinatorial optimization
+    problems. It works by preparing a quantum state through alternating applications of
+    problem-specific (cost) and mixing Hamiltonians, controlled by variational
+    parameters that are optimized classically to maximize the probability of measuring
+    the optimal solution.
+
+    QAOA is particularly suited for problems that can be encoded as quadratic
+    unconstrained binary optimization (QUBO) or Ising models, such as MaxCut, TSP, and
+    portfolio optimization.
+
+    Attributes
+    ----------
+    reps : int
+        Number of QAOA layers (p). Each layer consists of applying both the cost and
+        mixing Hamiltonians with different variational parameters. Higher values
+        generally lead to better solutions but increase circuit depth and quantum
+        resources required. Default is 1.
+    shots : int
+        Number of measurement samples to collect per circuit execution. Higher values
+        reduce statistical noise but increase runtime. Default is 1024.
+    optimizer : ScipyOptimizerParams | Dict
+        Configuration for the classical optimization routine that updates the
+        variational parameters. Default is a ScipyOptimizer instance with default
+        settings. See ScipyOptimizer class or
+        https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html
+        for details of contained parameters.
+    initial_params: LinearQAOAParams | BasicQAOAParams | RandomQAOAParams | Dict
+        Custom QAOA variational circuit parameters. By default linear
+        increasing/decreasing parameters for the selected `reps` are generated.
+    """
+
+    reps: int = Field(default=1, ge=1)
+    shots: int = Field(default=1024, ge=1)
+    optimizer: ScipyOptimizerParams = Field(
+        default_factory=lambda: ScipyOptimizerParams()
+    )
+    initial_params: RandomQAOAParams | BasicQAOAParams | LinearQAOAParams = Field(
+        default_factory=lambda: LinearQAOAParams(delta_beta=0.5, delta_gamma=0.5)
+    )
+
+    @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 "QAOA"
+
+    @classmethod
+    def get_default_backend(cls) -> AWS | IonQ | IQM | Rigetti | IBM:
+        """
+        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 IBM()
+
+    @classmethod
+    def get_compatible_backends(
+        cls,
+    ) -> tuple[type[AWS | IonQ | IQM | Rigetti | IBM], ...]:
+        """
+        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 AWS, IonQ, IQM, Rigetti, IBM

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

@@ -0,0 +1,69 @@
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.backends import Qctrl
+
+
+class QAOA_FO(LunaAlgorithm[Qctrl]):  # noqa: N801
+    """
+    Quantum Approximate Optimization Algorithm via Fire Opal (QAOA_FO).
+
+    QAOA_FO is Q-CTRL's implementation of the Quantum Approximate Optimization Algorithm
+    (QAOA) through their Fire Opal framework. It is a hybrid quantum-classical algorithm
+    for solving combinatorial optimization problems with enhanced performance through
+    Q-CTRL's error mitigation and control techniques. For more details, please refer
+    to the `Fire Opal QAOA documentation <https://docs.q-ctrl.com/fire-opal/execute/run-algorithms/solve-optimization-problems/fire-opals-qaoa-solver>`_.
+
+    The algorithm works by preparing a quantum state through alternating applications of
+    problem-specific (cost) and mixing Hamiltonians, controlled by variational
+    parameters that are optimized classically to maximize the probability of measuring
+    the optimal solution.
+
+    QAOA_FO leverages Q-CTRL's expertise in quantum control to improve circuit fidelity
+    and optimization performance. It is particularly suited for problems that can be
+    encoded as quadratic unconstrained binary optimization (QUBO) or Ising models,
+    such as MaxCut, TSP, and portfolio optimization.
+    """
+
+    @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 "QAOA_FO"
+
+    @classmethod
+    def get_default_backend(cls) -> Qctrl:
+        """
+        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 Qctrl()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[Qctrl]]:
+        """
+        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 (Qctrl,)

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

@@ -0,0 +1,109 @@
+import math
+from typing import Any, Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.algorithms.base_params.scipy_optimizer import (
+    ScipyOptimizerParams,
+)
+from luna_quantum.solve.parameters.backends import IBM
+
+
+class VQE(LunaAlgorithm[IBM]):
+    """
+    Parameters for the Variational Quantum Eigensolver (VQE) algorithm.
+
+    VQE is a hybrid quantum-classical algorithm designed to find the ground state energy
+    of a Hamiltonian by variationally optimizing a parameterized quantum circuit.
+    It's widely used in quantum chemistry to compute molecular ground state energies
+    and electronic structure properties.
+
+    Attributes
+    ----------
+    ansatz : Literal["NLocal", "EfficientSU2", "RealAmplitudes", "PauliTwoDesign"]
+        The variational form (parameterized circuit) to use. Default is "EfficientSU2",
+        a hardware-efficient ansatz using SU(2) rotation gates that works well on NISQ
+        devices due to its shallow depth and flexibility.
+    ansatz_config : dict[str, Any]
+        Configuration options for the selected ansatz, such as:
+
+        - entanglement: Pattern of entangling gates ("linear", "full", etc.)
+        - reps: Number of repetitions of the ansatz structure
+        - rotation_blocks: Types of rotation gates to use
+
+        Default is an empty dictionary, using the ansatz's default settings.
+    shots : int | None
+        Number of measurement samples per circuit execution. Higher values improve
+        accuracy by reducing statistical noise at the cost of longer runtime.
+        Default is 1024, which balances accuracy with execution time.
+    optimizer : ScipyOptimizerParams | Dict
+        Configuration for the classical optimization routine that updates the
+        variational parameters. Default is a ScipyOptimizer instance with default
+        settings. See ScipyOptimizer class or
+        https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html
+        for details of contained parameters.
+    initial_params_seed: int | None
+        Seed for random number generator for intial params.
+    initial_params_range: tuple[float, float]
+        Range of initial parameter values.
+    """
+
+    ansatz: Literal["NLocal", "EfficientSU2", "RealAmplitudes", "PauliTwoDesign"] = (
+        "EfficientSU2"
+    )
+
+    ansatz_config: dict[str, Any] = Field(default_factory=dict)
+    shots: int | None = 1024  # Number of circuit executions
+
+    optimizer: ScipyOptimizerParams = Field(
+        default_factory=lambda: ScipyOptimizerParams()
+    )
+
+    initial_params_seed: int | None = None
+    initial_params_range: tuple[float, float] = Field(default=(0, 2 * math.pi))
+
+    @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 "VQE"
+
+    @classmethod
+    def get_default_backend(cls) -> IBM:
+        """
+        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 IBM()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[IBM]]:
+        """
+        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 (IBM,)

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

@@ -0,0 +1,5 @@
+from .dialectic_search import DialecticSearch
+from .qbsolv_like_tabu_search import QBSolvLikeTabuSearch
+from .tabu_search import TabuSearch
+
+__all__ = ["DialecticSearch", "QBSolvLikeTabuSearch", "TabuSearch"]

luna_quantum/solve/parameters/algorithms/search_algorithms/dialectic_search.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from luna_quantum.solve.domain.abstract import LunaAlgorithm
+from luna_quantum.solve.parameters.algorithms.base_params import (
+    Decomposer,
+    TabuSearchBaseParams,
+)
+from luna_quantum.solve.parameters.backends import DWave
+from luna_quantum.solve.parameters.constants import DEFAULT_ATOL, DEFAULT_RTOL
+
+
+class DialecticSearch(LunaAlgorithm[DWave]):
+    """
+    Parameters for the Dialectic Search optimization algorithm.
+
+    Dialectic Search is an iterative metaheuristic that uses a
+    thesis-antithesis-synthesis approach to explore the solution space. It starts with
+    a thesis (initial solution) and generates an antithesis (complementary solution).
+    Then it performs a path search between them to synthesize improved solutions, using
+    tabu search for all three phases.
+
+    Attributes
+    ----------
+    antithesis_tabu_params: TabuSearchParams
+        Parameters for the antithesis phase of the search process. The antithesis
+        deliberately explores contrasting regions of the solution space to ensure
+        diversity and avoid getting trapped in local optima. This phase often uses
+        different tabu parameters to promote exploration over exploitation.
+        Default is a TabuSearchParams instance with default settings.
+    synthesis_tabu_params: TabuSearchParams
+        Parameters for the synthesis phase of the search process. The synthesis combines
+        aspects of both thesis and antithesis to generate new candidate solutions,
+        exploring the path between these solutions to find potentially better optima.
+        This phase is critical for discovering high-quality solutions that neither
+        thesis nor antithesis alone would find.
+        Default is a TabuSearchParams instance with default settings.
+    max_iter: int | None
+        Maximum number of iterations for the solver. This limits the total number of
+        dialectic cycles (thesis-antithesis-synthesis) that will be performed.
+        Higher values allow for more thorough exploration but increase runtime.
+        Default is 100.
+    max_time: int
+        Maximum time in seconds for the solver to run. Provides a hard time limit
+        regardless of convergence or iteration status. Useful for time-constrained
+        scenarios where some solution is needed within a specific timeframe.
+        Default is 5.
+    convergence: int
+        Number of consecutive iterations without improvement before declaring
+        convergence. Higher values ensure more stable solutions but may increase
+        computation time unnecessarily if the algorithm has already found the best
+        solution. Default is 3.
+    target: float | None
+        Target objective value that triggers termination if reached. Allows early
+        stopping when a sufficiently good solution is found. Default is None, which
+        means the algorithm will run until other stopping criteria are met.
+    rtol: float
+        Relative tolerance for convergence detection. Used when comparing objective
+        values between iterations to determine if significant improvement has occurred.
+        Default is DEFAULT_RTOL.
+    atol: float
+        Absolute tolerance for convergence detection. Used alongside rtol when comparing
+        objective values to determine if the algorithm has converged. Default is
+        DEFAULT_ATOL.
+    max_tries: int | None
+        Maximum number of synthesis attempts for each input state before moving to a new
+        thesis. Controls how persistently the algorithm explores the path between
+        thesis and antithesis before generating new starting points. Higher values
+        allow for more thorough path exploration but may slow progress if paths are
+        unproductive. Default is 100. Must be ≥1.
+    decomposer: Decomposer
+        Decomposer: Breaks down problems into subproblems of manageable size
+        Default is a Decomposer instance with default settings.
+
+    Notes
+    -----
+    The Dialectic Search algorithm operates through two distinct phases:
+
+    1. Antithesis: Generates a complementary solution designed to explore different
+       regions of the solution space
+    2. Synthesis: Creates new solutions by exploring paths between thesis and antithesis
+
+    Each phase uses tabu search with potentially different parameter settings to
+    guide the exploration process. This approach is particularly effective for
+    problems with complex landscapes containing many local optima.
+
+    The algorithm uses D-Wave's backend technology to efficiently solve optimization
+    problems. For more details on D-Wave solvers, see:
+    https://docs.dwavesys.com/
+    """
+
+    antithesis_tabu_params: TabuSearchBaseParams = Field(
+        default_factory=TabuSearchBaseParams
+    )
+    synthesis_tabu_params: TabuSearchBaseParams = Field(
+        default_factory=TabuSearchBaseParams
+    )
+
+    decomposer: Decomposer = Field(default_factory=Decomposer)
+    max_iter: int | None = 100
+    max_time: int = 5
+    convergence: int = 3
+    target: float | None = None
+    rtol: float = DEFAULT_RTOL
+    atol: float = DEFAULT_ATOL
+    max_tries: int | None = Field(default=100, ge=1)
+
+    @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 "DS"
+
+    @classmethod
+    def get_default_backend(cls) -> DWave:
+        """
+        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 DWave()
+
+    @classmethod
+    def get_compatible_backends(cls) -> tuple[type[DWave], ...]:
+        """
+        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 (DWave,)