luna-quantum 1.0.0__cp313-cp313-win_amd64.whl → 1.0.1rc10__cp313-cp313-win_amd64.whl

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/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/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

luna_quantum/translator.pyi

@@ -17,8 +17,8 @@ class ZibTranslator:
 
         - Convert a Zib-style solution into our solution `Solution`.
 
-    The conversions are especially required when interacting with external zib solvers/samplers or
-    libraries that operate on zib-based problem-solving/sampling.
+    The conversions are especially required when interacting with external zib
+    solvers/samplers or libraries that operate on zib-based problem-solving/sampling.
 
     Examples
     --------
@@ -63,8 +63,8 @@ class ZibTranslator:
         NoActiveEnvironmentFoundError
             If no environment is passed to the method or available from the context.
         SolutionTranslationError
-            Generally if the solution translation fails. Might be specified by one of the
-                two following errors.
+            Generally if the solution translation fails. Might be specified by one of
+            the two following errors.
         SampleIncorrectLengthError
             If a solution's sample has a different number of variables than the model
             environment passed to the translator.
@@ -72,10 +72,13 @@ class ZibTranslator:
             If the result's variable types are incompatible with the model environment's
             variable types.
         """
+        ...
 
 class Qubo:
-    """
-    A wrapper around qubo matrices that holds all relevant metadata, e.g., the model offset.
+    """The result of the QuboTranslator.
+
+    A wrapper around qubo matrices that holds all relevant metadata,
+    e.g., the model offset.
     """
 
     @property
@@ -89,6 +92,7 @@ class Qubo:
             A square NumPy array representing the QUBO matrix derived from
             the model's objective.
         """
+        ...
 
     @property
     def variable_names(self, /) -> list[str]:
@@ -100,6 +104,7 @@ class Qubo:
         list[Variable]
             The variable names in the order they appear in the QUBO.
         """
+        ...
 
     @property
     def name(self, /) -> str:
@@ -111,6 +116,7 @@ class Qubo:
         str
             The model name.
         """
+        ...
 
     @property
     def offset(self, /) -> float:
@@ -122,6 +128,7 @@ class Qubo:
         float
             The constant offset of the model.
         """
+        ...
 
     @property
     def vtype(self, /) -> Vtype:
@@ -133,6 +140,7 @@ class Qubo:
         Vtype
             The variable type.
         """
+        ...
 
 class QuboTranslator:
     """
@@ -148,7 +156,7 @@ class QuboTranslator:
     Examples
     --------
     >>> import numpy as np
-    >>> from luna_quantum import QuboTranslator, Vtype
+    >>> from luna_quantum.translator import QuboTranslator, Vtype
     >>> q = np.array([[1.0, -1.0], [-1.0, 2.0]])
 
     Create a model from a matrix:
@@ -200,6 +208,7 @@ class QuboTranslator:
             If a list of variable names is provided but contains duplicates or has an
             incorrect length.
         """
+        ...
 
     @staticmethod
     def from_aq(model: Model) -> Qubo:
@@ -215,9 +224,10 @@ class QuboTranslator:
         Returns
         -------
         Qubo
-            An object representing a QUBO with information additional to the square NumPy array
-            representing the QUBO matrix derived from the model's objective. This object also
-            includes the `variable_ordering` as well as the `offset` of the original model.
+            An object representing a QUBO with information additional to the square
+            NumPy array representing the QUBO matrix derived from the model's objective.
+            This object also includes the `variable_ordering` as well as the `offset`
+            of the original model.
 
         Raises
         ------
@@ -234,6 +244,7 @@ class QuboTranslator:
             If the model contains different vtypes or vtypes other than binary and
             spin.
         """
+        ...
 
 class QctrlTranslator:
     """
@@ -242,8 +253,8 @@ class QctrlTranslator:
     `QctrlTranslator` provides methods to:
     - Convert a Qctrl-style solution into our solution `Solution`.
 
-    The conversions are especially required when interacting with external qctrl solvers/samplers or
-    libraries that operate on qctrl-based problem-solving/sampling.
+    The conversions are especially required when interacting with external qctrl
+    solvers/samplers or libraries that operate on qctrl-based problem-solving/sampling.
 
     Examples
     --------
@@ -291,8 +302,8 @@ class QctrlTranslator:
         NoActiveEnvironmentFoundError
             If no environment is passed to the method or available from the context.
         SolutionTranslationError
-            Generally if the solution translation fails. Might be specified by one of the
-            two following errors.
+            Generally if the solution translation fails. Might be specified by one of
+            the two following errors.
         SampleIncorrectLengthError
             If a solution's sample has a different number of variables than the model
             environment passed to the translator.
@@ -300,11 +311,13 @@ class QctrlTranslator:
             If the result's variable types are incompatible with the model environment's
             variable types.
         """
+        ...
 
 class NumpyTranslator:
-    """
-    Utility class for converting between a result consisting of numpy arrays and our solution
-    format.
+    """Translate between numpy arrays and our solution format.
+
+    Utility class for converting between a result consisting of numpy arrays and our
+    solution format.
 
     `NumpyTranslator` provides methods to:
     - Convert a numpy-array result into our solution `Solution`.
@@ -341,7 +354,8 @@ class NumpyTranslator:
         env: Environment | None = ...,
     ) -> Solution:
         """
-        Convert an IBM solution to our solution format.
+        Convert a solution in the format of numpy arrays to our solution format.
+        Note that the optimization sense is always assumed to be minimization.
 
         Parameters
         ----------
@@ -359,8 +373,8 @@ class NumpyTranslator:
         NoActiveEnvironmentFoundError
             If no environment is passed to the method or available from the context.
         SolutionTranslationError
-            Generally if the solution translation fails. Might be specified by one of the
-                two following errors.
+            Generally if the solution translation fails. Might be specified by one of
+            the two following errors.
         SampleIncorrectLengthError
             If a solution's sample has a different number of variables than the model
             environment passed to the translator.
@@ -368,6 +382,7 @@ class NumpyTranslator:
             If the result's variable types are incompatible with the model environment's
             variable types.
         """
+        ...
 
 class LpTranslator:
     """
@@ -383,7 +398,7 @@ class LpTranslator:
     Examples
     --------
     >>> from pathlib import Path
-    >>> from luna_quantum import LpTranslator
+    >>> from luna_quantum.translator import LpTranslator
     >>> lp_filepath = Path("path/to/the/lp_file")
 
     >>> model = LpTranslator.to_aq(lp_filepath)
@@ -398,7 +413,9 @@ class LpTranslator:
     def to_aq(file: Path) -> Model: ...
     @overload
     @staticmethod
-    def to_aq(file: str) -> Model:
+    def to_aq(file: str) -> Model: ...
+    @staticmethod
+    def to_aq(file: str | Path) -> Model:
         """
         Convert an LP file into a symbolic `Model`.
 
@@ -422,13 +439,16 @@ class LpTranslator:
         TranslationError
             If the translation fails for a different reason.
         """
+        ...
 
     @overload
     @staticmethod
     def from_aq(model: Model) -> str: ...
     @overload
     @staticmethod
-    def from_aq(model: Model, *, filepath: Path) -> None:
+    def from_aq(model: Model, *, filepath: Path) -> None: ...
+    @staticmethod
+    def from_aq(model: Model, *, filepath: Path | None = ...) -> None:
         """
         Convert a symbolic model to an LP file representation.
 
@@ -449,16 +469,16 @@ class LpTranslator:
         TranslationError
             If the translation fails for some reason.
         """
+        ...
 
 class IbmTranslator:
-    """
-    Utility class for converting between an IBM solution and our solution format.
+    """Utility class for converting between an IBM solution and our solution format.
 
     `IbmTranslator` provides methods to:
     - Convert an IBM-style solution into our solution `Solution`.
 
-    The conversions are especially required when interacting with external ibm solvers/samplers or
-    libraries that operate on ibm-based problem-solving/sampling.
+    The conversions are especially required when interacting with external ibm
+    solvers/samplers oe libraries that operate on ibm-based problem-solving/sampling.
 
     Examples
     --------
@@ -524,8 +544,8 @@ class IbmTranslator:
         NoActiveEnvironmentFoundError
             If no environment is passed to the method or available from the context.
         SolutionTranslationError
-            Generally if the solution translation fails. Might be specified by one of the
-                two following errors.
+            Generally if the solution translation fails. Might be specified by one of
+            the two following errors.
         SampleIncorrectLengthError
             If a solution's sample has a different number of variables than the model
             environment passed to the translator.
@@ -533,16 +553,17 @@ class IbmTranslator:
             If the result's variable types are incompatible with the model environment's
             variable types.
         """
+        ...
 
 class DwaveTranslator:
-    """
-    Utility class for converting between a DWAVE solution and our solution format.
+    """Utility class for converting between a DWAVE solution and our solution format.
 
     `DWaveSolutionTranslator` provides methods to:
     - Convert a dimod-style solution into our solution `Solution`.
 
     The conversions are especially required when interacting with external dwave/dimod
-    solvers/samplers or libraries that operate on dwave/dimod-based problem-solving/sampling.
+    solvers/samplers or libraries that operate on dwave/dimod-based problem-solving/
+    sampling.
 
     Examples
     --------
@@ -590,8 +611,8 @@ class DwaveTranslator:
         NoActiveEnvironmentFoundError
             If no environment is passed to the method or available from the context.
         SolutionTranslationError
-            Generally if the solution translation fails. Might be specified by one of the
-                two following errors.
+            Generally if the solution translation fails. Might be specified by one of
+            the two following errors.
         SampleIncorrectLengthError
             If a solution's sample has a different number of variables than the model
             environment passed to the translator.
@@ -599,9 +620,11 @@ class DwaveTranslator:
             If the result's variable types are incompatible with the model environment's
             variable types.
         """
+        ...
 
 class CqmTranslator:
-    """
+    """CQM to AQM translator.
+
     Utility class for converting between dimod.BinaryQuadraticModel (CQM) and symbolic
     models.
 
@@ -616,7 +639,7 @@ class CqmTranslator:
     --------
     >>> import dimod
     >>> import numpy as np
-    >>> from luna_quantum import CqmTranslator, Vtype
+    >>> from luna_quantum.translator import CqmTranslator, Vtype
     >>> bqm = dimod.generators.gnm_random_bqm(5, 10, "BINARY")
 
     Create a model from a matrix:
@@ -650,6 +673,8 @@ class CqmTranslator:
         TranslationError
             If the translation fails for some reason.
         """
+        ...
+
     @staticmethod
     def from_aq(model: Model) -> ConstrainedQuadraticModel:
         """
@@ -671,9 +696,11 @@ class CqmTranslator:
         TranslationError
             If the translation fails for some reason.
         """
+        ...
 
 class BqmTranslator:
-    """
+    """BQM to AQM translator.
+
     Utility class for converting between dimod.BinaryQuadraticModel (BQM) and symbolic
     models.
 
@@ -688,7 +715,7 @@ class BqmTranslator:
     --------
     >>> import dimod
     >>> import numpy as np
-    >>> from luna_quantum import BqmTranslator, Vtype
+    >>> from luna_quantum.translator import BqmTranslator, Vtype
     >>> bqm = dimod.generators.gnm_random_bqm(5, 10, "BINARY")
 
     Create a model from a matrix:
@@ -705,7 +732,9 @@ class BqmTranslator:
     def to_aq(bqm: BinaryQuadraticModel) -> Model: ...
     @overload
     @staticmethod
-    def to_aq(bqm: BinaryQuadraticModel, *, name: str) -> Model:
+    def to_aq(bqm: BinaryQuadraticModel, *, name: str) -> Model: ...
+    @staticmethod
+    def to_aq(bqm: BinaryQuadraticModel, *, name: str | None = ...) -> Model:
         """
         Convert a BQM into a symbolic `Model`.
 
@@ -721,6 +750,8 @@ class BqmTranslator:
         Model
             A symbolic model representing the given BQM.
         """
+        ...
+
     @staticmethod
     def from_aq(model: Model) -> BinaryQuadraticModel:
         """
@@ -752,6 +783,7 @@ class BqmTranslator:
             If the model contains different vtypes or vtypes other than binary and
             spin.
         """
+        ...
 
 class AwsTranslator:
     """
@@ -760,8 +792,8 @@ class AwsTranslator:
     `AwsTranslator` provides methods to:
     - Convert an AWS-style result into our solution `Solution`.
 
-    The conversions are especially required when interacting with external aws solvers/samplers or
-    libraries that operate on aws-based problem-solving/sampling.
+    The conversions are especially required when interacting with external aws
+    solvers/samplers or libraries that operate on aws-based problem-solving/sampling.
 
     Examples
     --------
@@ -808,8 +840,8 @@ class AwsTranslator:
         NoActiveEnvironmentFoundError
             If no environment is passed to the method or available from the context.
         SolutionTranslationError
-            Generally if the solution translation fails. Might be specified by one of the
-            two following errors.
+            Generally if the solution translation fails. Might be specified by one of
+            the two following errors.
         SampleIncorrectLengthError
             If a solution's sample has a different number of variables than the model
             environment passed to the translator.
@@ -817,6 +849,7 @@ class AwsTranslator:
             If the result's variable types are incompatible with the model environment's
             variable types.
         """
+        ...
 
 __all__ = [
     "AwsTranslator",

luna_quantum/utils.py

@@ -1,17 +1,37 @@
+"""Utility module containing convenience functions."""
+
 from collections.abc import Iterable
 
 from ._core import Expression, Variable
 
 
+class InvalidStartTypeError(TypeError):
+    """To be raised when an invalid start type is specified in quicksum."""
+
+    def __init__(self, actual: type) -> None:
+        super().__init__(f"start must be of type `Expression`, is '{actual}'")
+
+
+class StartCannotBeInferredError(TypeError):
+    """To be raised when the start value in the quicksum cannot be inferred."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "iterable must contain at least one Expression or Variable, "
+            "or 'start' needs to be set."
+        )
+
+
 def quicksum(
     iterable: Iterable[Expression | Variable | int | float],
     /,
     start: Expression | None = None,
 ) -> Expression:
-    """
-    Create an Expression based on an iterable of Expression, Variable, int or float elements.
-    Note that either the `iterable` must contain at least one `Expression` or `Variable` or
-    the start parameter is set.
+    """Sum over an Iterable of Expression, Variable, int or float values.
+
+    Create an Expression based on an iterable of Expression, Variable, int or float
+    elements. Note that either the `iterable` must contain at least one `Expression`
+    or `Variable` or the start parameter is set.
 
     Parameters
     ----------
@@ -27,24 +47,22 @@ def quicksum(
 
     Raises
     ------
-    TypeError
+    TypeError (InvalidStartTypeError | StartCannotBeInferredError)
         If the `iterable` does not contain any Expression or Variable.
         If the `start` is not of type Expression.
     """
     items = list(iterable)
     if start is None:
         for item in items:
-            if isinstance(item, Expression) or isinstance(item, Variable):
-                start = Expression(env=item._environment)  # type: ignore
+            if isinstance(item, Expression | Variable):
+                start = Expression(env=item._environment)  # noqa: SLF001
                 break
 
     if start is None:
-        raise TypeError(
-            "iterable must contain at least one Expression or Variable,or 'start' needs to be set."
-        )
+        raise StartCannotBeInferredError
 
     if not isinstance(start, Expression):
-        raise TypeError("start must be of type `Expression`")
+        raise InvalidStartTypeError(type(start))
 
     _start: Expression = start
 

{luna_quantum-1.0.0.dist-info → luna_quantum-1.0.1rc10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: luna-quantum
-Version: 1.0.0
+Version: 1.0.1rc10
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
@@ -10,15 +10,13 @@ Requires-Dist: numpy>=1
 Requires-Dist: pydantic[email]>=2.11.3,<3
 Requires-Dist: python-dateutil>=2.9.0,<3
 Requires-Dist: rich>=14.0.0
-Requires-Dist: networkx>=3.4.2,<4 ; extra == 'examples'
-Provides-Extra: examples
 License-File: LICENSE
 License-File: NOTICE
 Summary: Python SDK for Aqarios' Luna Platform
 Keywords: aqarios,luna,quantum computing,quantum optimization,optimization,sdk
 Author-email: Aqarios <pypi@aqarios.com>
 License: Apache-2.0
-Requires-Python: >=3.11.0, <4
+Requires-Python: >=3.11.0, <3.14
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 Project-URL: Homepage, https://aqarios.com/
 Project-URL: Documentation, https://docs.aqarios.com/