luna-quantum 1.0.0__cp312-cp312-macosx_11_0_arm64.whl → 1.0.1__cp312-cp312-macosx_11_0_arm64.whl

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

@@ -14,14 +14,16 @@ class LinearOptimizerParams(ScipyOptimizerParams):
     ScipyOptimizer.
 
     Wrapper for scipy.optimize.minimize. See
-    https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html
+    [SciPy minimize documentation](
+    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
+        [SciPy minimize documentation](
+        https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html)
         for supported methods.
     tol: float | None
         Tolerance for termination.

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

@@ -39,9 +39,7 @@ class QAOA(LunaAlgorithm[AWS | IonQ | IQM | Rigetti | IBM]):
     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.
+        settings. See ScipyOptimizerParams class 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.

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

@@ -40,9 +40,8 @@ class VQE(LunaAlgorithm[IBM]):
     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.
+        settings. See ScipyOptimizer Params class or for details
+        of contained parameters.
     initial_params_seed: int | None
         Seed for random number generator for intial params.
     initial_params_range: tuple[float, float]

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

@@ -72,22 +72,6 @@ class DialecticSearch(LunaAlgorithm[DWave]):
     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(

luna_quantum/solve/parameters/backends/__init__.py

@@ -6,7 +6,7 @@ from .ibm import IBM
 from .qctrl import Qctrl
 from .zib import ZIB
 
-__all__ = [
+__all__: list[str] = [
     "AWS",
     "IBM",
     "IQM",

luna_quantum/solve/parameters/backends/dwave_qpu.py

@@ -19,10 +19,10 @@ class DWaveQpu(DWave, QpuTokenBackend):
 
     Attributes
     ----------
-    embedding_parameters: Embedding | None, default=None
+    embedding_parameters: Embedding | AutoEmbedding | 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.
+        Ignored if decomposer is set to AutoEmbedding. Default is None.
     qpu_backend: str
         Specific D-Wave quantum processing unit (QPU) for your optimization
     """
@@ -76,8 +76,10 @@ class DWaveQpu(DWave, QpuTokenBackend):
 
         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.
 

luna_quantum/solve/parameters/backends/ibm.py

@@ -25,7 +25,7 @@ class IBM(IBackend):
     """
 
     class SimulatorBackend(BaseModel):
-        """Simulator.
+        """Qiskit Statevector Simulator.
 
         Use a simulator as backend. The QAOA is executed completely on our server, and
         no IBM token is required.
@@ -41,7 +41,13 @@ class IBM(IBackend):
         backend_name: Literal["aer", "statevector"] = "aer"
 
     class FakeProviderBackend(BaseModel):
-        """FaleProvider.
+        """Simulator with emulated QPU noise model.
+
+        The Qiskit fake provider runs a simulation with a noise model derived from
+        an actual QPU hardware implementation.
+        See [IBM documentation](
+        https://docs.quantum.ibm.com/api/qiskit-ibm-runtime/fake-provider) for
+        available “fake” devices.
 
         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.

luna_quantum/solve/parameters/backends/qctrl.py

@@ -33,10 +33,10 @@ class Qctrl(QpuTokenBackend):
         - '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()
+    ibm_credentials: IBMQ | IBMCloud
         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.
+        pattern. Default is Qctrl.IBMQ()
 
     token: QpuToken | str | None, default=None
         The Q-Ctrl API token.
@@ -45,7 +45,8 @@ class Qctrl(QpuTokenBackend):
     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
+    see [Q-CTRL's documentation](
+    https://docs.q-ctrl.com/fire-opal/topics/fire-opals-qaoa-solver)
     """
 
     class IBMQ(BaseModel):

luna_quantum/solve/use_cases/hamiltonian_cycle.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Final, Literal
+from typing import Literal
 
 from pydantic import Field
 
@@ -46,4 +46,4 @@ class HamiltonianCycle(UseCase):
     graph: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]
     directed: bool | None = False
     A: float = 1.0
-    B: Final[float] = 0.0
+    B: float = 0.0

luna_quantum/solve/usecases/model_get_solution_usecase.py

@@ -1,6 +1,7 @@
 from luna_quantum._core import Solution
 from luna_quantum.aqm_overwrites import Model
 from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+from luna_quantum.client.schemas.enums.status import StatusEnum
 from luna_quantum.solve.interfaces.usecases.model_get_solutions_usecase_i import (
     IModelGetSolutionUseCase,
 )
@@ -52,5 +53,7 @@ class ModelGetSolutionUseCase(IModelGetSolutionUseCase):
 
         # TODO THIS IS SUPER INEFFICIENT  # noqa: FIX002, TD002, TD004
         return [
-            self.client.solve_job.get_solution(solve_job_id=s.id) for s in solve_jobs
+            self.client.solve_job.get_solution(solve_job_id=s.id)
+            for s in solve_jobs
+            if s.status is StatusEnum.DONE
         ]

luna_quantum/solve/usecases/solve_job_get_result_usecase.py

@@ -82,9 +82,7 @@ class SolveJobGetResultUseCase(ISolveJobGetResultUseCase):
                 return None
             if solve_job.status == StatusEnum.FAILED:
                 self.logger.error(
-                    "Solve job is failed."
-                    " See 'error_message'"
-                    " field in solve job object for further information."
+                    f"Solve job failed with the error '{solve_job.error_message}'."
                 )
                 return None
             aq_solution: Solution = self.client.solve_job.get_solution(

luna_quantum/transformations.py

@@ -0,0 +1,18 @@
+"""Transformations collection.
+
+The `transformations` module provides a collection of transformations for converting
+between various representations of optimization problems and their solutions.
+
+Transformations generally convert between different representations of an optimization
+model. For example, changing the Sense of a model.
+
+Each transformation encapsulates the logic needed for transforming a model to a desired
+output model with changed properties and the logic to convert a solution of the output
+model back to a solution representation matching the input model.
+
+In addition to the predefined transformations contained in this module.
+One can implement their own transformations by implementing the `TransformationPass`
+and `AnalysisPass` abstract classes. See the examples for further details.
+"""
+
+from ._core.transformations import *  # type: ignore[reportMissingImports] # noqa: F403

luna_quantum/transformations.pyi

@@ -0,0 +1,258 @@
+from abc import abstractmethod
+from enum import Enum
+from typing import Any, Literal, overload
+
+from aqmodels import Model, Sense, Solution, Timing, Vtype
+
+class BasePass:
+    @property
+    def name(self) -> str:
+        """Get the name of this pass."""
+        ...
+    @property
+    def requires(self) -> list[str]:
+        """Get a list of required passes that need to be run before this pass."""
+        ...
+
+class TransformationPass(BasePass):
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Get the name of this pass."""
+        ...
+    @property
+    def requires(self) -> list[str]:
+        """Get a list of required passes that need to be run before this pass."""
+        ...
+    @property
+    def invalidates(self) -> list[str]:
+        """Get a list of passes that are invalidated by this pass."""
+        ...
+    @abstractmethod
+    def run(self, model: Model, cache: AnalysisCache) -> tuple[Model, ActionType]:
+        """Run/Execute this transformation pass."""
+        ...
+    @abstractmethod
+    def backwards(self, solution: Solution, cache: AnalysisCache) -> Solution:
+        """Convert a solution back to fit this pass' input.
+
+        Convert a solution from a representation fitting this pass' output to
+        a solution representation fitting this pass' input.
+        """
+        ...
+
+class AnalysisCache:
+    @overload
+    def __getitem__(  # type: ignore[reportOverlappingOverload]
+        self, key: Literal["max-bias"]
+    ) -> MaxBias: ...
+    @overload
+    def __getitem__(self, key: str) -> dict[Any, Any]: ...
+    def __getitem__(self, key: str) -> Any:
+        """Get the analysis result for a specific analysis pass."""
+        ...
+
+class AnalysisPass(BasePass):
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Get the name of this pass."""
+        ...
+    @property
+    def requires(self) -> list[str]:
+        """Get a list of required passes that need to be run before this pass."""
+        ...
+    @abstractmethod
+    def run(self, model: Model, cache: AnalysisCache) -> float:
+        """Run/Execute this analysis pass."""
+        ...
+
+class ActionType(Enum):
+    DidTransform = ...
+    """Indicate that the pass did transform the model."""
+    DidAnalysis = ...
+    """Indicate that the pass did analyse the model."""
+    Nothing = ...
+    """Indicate that the pass did NOT do anything."""
+
+class ChangeSensePass(BasePass):
+    """A transformation pass to change the model's Sense to a target Sense."""
+
+    def __init__(self, sense: Sense) -> None:
+        """Transform the model's Sense to a target Sense.
+
+        Parameters
+        ----------
+        sense : Sense
+            The target sense of the model after calling the `run` method on it.
+        """
+        ...
+    @property
+    def sense(self) -> Sense:
+        """Get the specified target sense of this pass."""
+        ...
+
+class MaxBias:
+    """An analysis pass result storing the max bias (coefficient) of a model."""
+
+    @property
+    def val(self) -> float:
+        """Get the value of the maxium bias."""
+        ...
+
+class MaxBiasAnalysis(BasePass):
+    """An analysis pass computing the maximum bias contained in the model."""
+
+    def __init__(self) -> None: ...
+
+class BinarySpinAnalysis(BasePass):
+    """An analysis pass noting down which variables need to be transformed."""
+
+    def __init__(self, vtype: Literal[Vtype.Binary, Vtype.Spin]) -> None: ...
+    @property
+    def vtype(self) -> Vtype:
+        """Get the target vtype."""
+        ...
+
+class BinarySpinInfo:
+    @property
+    def old_vtype(self) -> Vtype:
+        """Get the source vtype."""
+        ...
+
+    @property
+    def new_vtype(self) -> Vtype:
+        """Get the target vtype."""
+        ...
+
+    @property
+    def map(self) -> dict[str, str]:
+        """Get the variable name mapping."""
+        ...
+
+class BinarySpinPass(BasePass):
+    """An transformation pass changing the denoted variables to target."""
+
+    def __init__(self) -> None: ...
+
+class LogElement:
+    """An element of the execution log of an intermediate representation (IR)."""
+
+    @property
+    def pass_name(self) -> str:
+        """The name of the pass."""
+        ...
+
+    @property
+    def timing(self) -> Timing:
+        """Timing information for this log element."""
+        ...
+
+    @property
+    def kind(self) -> ActionType | None:
+        """Transformation type information for this log element, if available."""
+        ...
+
+class IR:
+    """The intermediate representation (IR) of a model after transformation.
+
+    The IR contains the resulting model after transformation (`ir.model`) as well
+    as the analysis cache (`ir.cache`) and an execution log (`ir.execution_log`).
+    """
+
+    @property
+    def model(self) -> Model:
+        """Get the model stored in the IR."""
+        ...
+
+    @property
+    def cache(self) -> AnalysisCache:
+        """Get the analysis cache stored the IR."""
+        ...
+
+    @property
+    def execution_log(self) -> list[LogElement]:
+        """Get the analysis cache stored the IR."""
+        ...
+
+class PassManager:
+    """Manage and execute a sequence of passes on a model.
+
+    The PassManager implements a compiler-style pass pattern, enabling both
+    general-purpose and algorithm-specific manipulations of optimization
+    models. Each pass is an atomic operation (for example, ChangeSensePass)
+    that transforms the model or its intermediate representation (IR). The
+    PassManager runs each pass in order and produces a rich IR that records
+    the transformations applied and supports back-transformations.
+    """
+
+    def __init__(
+        self, passes: list[BasePass | TransformationPass | AnalysisPass]
+    ) -> None:
+        """Manage and execute a sequence of passes on a model.
+
+        The PassManager implements a compiler-style pass pattern, enabling both
+        general-purpose and algorithm-specific manipulations of optimization
+        models. Each pass is an atomic operation (for example, ChangeSensePass)
+        that transforms the model or its intermediate representation (IR). The
+        PassManager runs each pass in order and produces a rich IR that records
+        the transformations applied and supports back-transformations.
+
+        Parameters
+        ----------
+        passes : list[TransformationPass | AnalysisPass]
+            An ordered sequence of Pass instances to apply. Each Pass must conform to
+            the `TransformationPass` or `AnalysisPass` interface.
+        """
+        ...
+
+    def run(self, model: Model) -> IR:
+        """Apply all configures passes.
+
+        Apply all configured passes to the given model and return the
+        resulting intermediate representation.
+
+        Parameters
+        ----------
+        model : Model
+            The model to be transformed.
+
+        Returns
+        -------
+        IR
+            The intermediate representation of the model after transformation.
+        """
+        ...
+
+    def backwards(self, solution: Solution, ir: IR) -> Solution:
+        """Apply the back transformation to the given solution.
+
+        Parameters
+        ----------
+        solution : Solution
+            The solution to transform back to a representation fitting the original
+            (input) model of this `PassManager`.
+        ir : IR
+            The intermediate representation (IR) resulted from the `run` call.
+
+        Returns
+        -------
+        Solution
+            A solution object representing a solution to the original problem passed
+            to this `PassManager`'s run method.
+        """
+        ...
+
+__all__ = [
+    "IR",
+    "ActionType",
+    "AnalysisCache",
+    "AnalysisPass",
+    "BasePass",
+    "ChangeSensePass",
+    "LogElement",
+    "MaxBias",
+    "MaxBiasAnalysis",
+    "PassManager",
+    "TransformationPass",
+]

luna_quantum/translator.py

@@ -1 +1,23 @@
-from ._core.translator import *  # type: ignore[reportMissingImports, import-not-found,unused-ignore] # noqa: F403
+"""Translator collection.
+
+The `translator` module provides a collection of translators for converting between
+various formats related to optimization problems and their solutions.
+
+Translators are categorized into two main groups:
+
+1. **Model Translators**: These handle conversions *to* and *from* the internal `Model`
+   representation. They enable interoperability between external formats
+   (e.g., QUBO, LP) and the standardized internal model format used within the system.
+
+2. **Solution Translators**: These support conversion *from* external solution formats
+   into the internal `Solution` representation. This enables solutions generated by
+   different solvers or formats to be interpreted and processed consistently within
+   the system. Note that these translators do not support conversion *from* the internal
+   solution to external formats.
+
+Each translator encapsulates the logic needed for bidirectional format conversion,
+ensuring consistency and modularity when integrating with diverse optimization
+frameworks and solvers.
+"""
+
+from ._core.translator import *  # type: ignore[reportMissingImports] # noqa: F403