luna-quantum 1.1.0__cp312-cp312-win_amd64.whl

luna_quantum/errors.pyi

@@ -0,0 +1,287 @@
+class VariableOutOfRangeError(Exception):
+    """Referenced variable is out of bounds for the environment.
+
+    Raised when a variable referenced in an expression is out of bounds for the
+    environment.
+
+    This error typically occurs when querying coefficients (linear, quadratic,
+    or higher-order) from an `Expression` using a `Variable` whose index does not
+    exist in the environment's internal registry.
+
+    This may happen if:
+        - A variable is used from a different environment
+        - A variable was removed or never registered properly
+        - A raw index or tuple refers to a non-existent variable ID
+    """
+
+    def __str__(self, /) -> str: ...
+
+class VariableExistsError(Exception):
+    """
+    Raised when trying to create a variable with a name that already exists.
+
+    Variable names must be unique within an `Environment`. Attempting to redefine
+    a variable with the same name will raise this exception.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class VariableNotExistingError(Exception):
+    """Raised when trying to get a variable with a name that does not exist."""
+
+    def __str__(self, /) -> str: ...
+
+class VariableCreationError(Exception):
+    """
+    Raised when an error occurs during the creation of a variable.
+
+    For example, binary and spin variables cannot be created with bounds.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class VariablesFromDifferentEnvsError(Exception):
+    """
+    Raised when multiple variables from different environments are used together.
+
+    All variables in an expression or constraint must belong to the same
+    `Environment`. Mixing across environments is disallowed to ensure consistency.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class DifferentEnvsError(Exception):
+    """
+    Raised when two incompatible environments are passed to a model or operation.
+
+    Unlike `VariablesFromDifferentEnvsError`, this error may occur at the model level
+    or in structural operations that require consistency across multiple environments.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class NoActiveEnvironmentFoundError(Exception):
+    """Variable or Expression created without an environment (or context).
+
+    Raised when a variable or expression is created without an active environment
+    context.
+
+    This typically happens when not using `with Environment(): ...` and no environment
+    was explicitly provided.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class MultipleActiveEnvironmentsError(Exception):
+    """
+    Raised when multiple environments are active simultaneously.
+
+    This is a logic error, since `aqmodels` only supports one active environment
+    at a time. This is enforced to maintain clarity and safety.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class DecodeError(Exception):
+    """
+    Raised when decoding or deserialization of binary data fails.
+
+    This can occur if the encoded data is corrupted, incompatible, or not generated
+    by `aqmodels.encode()`.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class VariableNamesError(Exception):
+    """The provided variable names are invalid.
+
+    Raised when the QuboTranslator tries to create a model from a QUBO matrix, but
+    the provided variable names are invalid.
+
+    If variable names are provided to the QuboTranslator, they have to be unique, and
+    the number of names has to match the number of variables in the QUBO matrix.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class IllegalConstraintNameError(Exception):
+    """Raised when a constraint is tried to be created with an illegal name."""
+
+    def __str__(self, /) -> str: ...
+
+class TranslationError(Exception):
+    """Raised when an error occurred during translation."""
+
+    def __str__(self, /) -> str: ...
+
+class ModelNotQuadraticError(TranslationError):
+    """
+    Raised when a model is expected to be quadratic but contains higher-order terms.
+
+    Some solvers or transformations require the model to have at most quadratic
+    expressions. This error signals that unsupported terms were detected.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class ModelNotUnconstrainedError(TranslationError):
+    """Operation requires an unconstrained model.
+
+    Raised when an operation requires an unconstrained model, but constraints are
+    present.
+
+    Some solution methods may only work on unconstrained models, such as when
+    transforming a symbolic model to a low-level format.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class ModelSenseNotMinimizeError(TranslationError):
+    """Operation requires a model for minimization.
+
+    Raised when an operation requires a model with minimization sense, but has
+    maximization sense.
+
+    Some model formats only work with minimization sense. In this case, consider
+    setting the sense to `minimize` before the transformation, and multiplying the
+    objective by `-1` if necessary.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class ModelVtypeError(TranslationError):
+    """Operation has constraints on model's variable types.
+
+    Raised when an operation has certain constraints on a model's variable types that
+    are violated.
+
+    Some solution methods may only work on models where all variables have the same
+    type, or where only certain variable types are permitted.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class SolutionTranslationError(Exception):
+    """
+    Raised when something goes wrong during the translation of a solution.
+
+    This may happen during the translation to an AqSolution from a different solution
+    format, e.g., when the samples have different lengths or the variable types are not
+    consistent with the model the solution is created for.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class SampleIncorrectLengthError(SolutionTranslationError):
+    """
+    Raised when a sample length is different from the number of model variables.
+
+    When an external solution format is translated to an AqSolution, the number of
+    variable assignments in the solution's sample has to exactly match the number of
+    variables in the model environment that is passed to the translator.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class SampleUnexpectedVariableError(SolutionTranslationError):
+    """Variable not present in environment.
+
+    Raised when a sample contains a variable with a name that is not present in the
+    environment.
+
+    When a sample is translated to an AqResult, the currently active environment has to
+    contain the same variables as the sample.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class SampleIncompatibleVtypeError(SolutionTranslationError):
+    """A sample's assignments have incompatible vtypes.
+
+    Raised when a sample's assignments have variable types incompatible with the
+    model's variable types.
+
+    When an external solution format is translated to an AqSolution, the variable
+    assignments are tried to be converted into the model's corresponding variable type.
+    This may fail when the assignment types are incompatible.
+
+    Note that conversions with precision loss or truncation are admitted, but
+    conversions of variables outside the permitted range will fail.
+    """
+
+    def __str__(self, /) -> str: ...
+
+class ComputationError(Exception):
+    """Raised when an error occured in an internal computation."""
+
+    def __str__(self, /) -> str: ...
+
+class EvaluationError(Exception):
+    """Raised when an error occured during evaluation of a model."""
+
+    def __str__(self, /) -> str: ...
+
+class DuplicateConstraintNameError(Exception):
+    """Raised when a duplicate constraint name is used."""
+
+    def __str__(self, /) -> str: ...
+
+class CompilationError(RuntimeError):
+    """Raised when an error occured during compilation of a model in the PassManager."""
+
+    def __str__(self, /) -> str: ...
+
+class StartCannotBeInferredError(TypeError):
+    """To be raised when the start value in the quicksum cannot be inferred."""
+
+    def __str__(self, /) -> str: ...
+
+class NoConstraintForKeyError(IndexError):
+    """Raised getting a constraint from the constraints that does not exist."""
+
+    def __str__(self, /) -> str: ...
+
+class SampleColCreationError(IndexError):
+    """Raised when an error occured during creation of a sample column."""
+
+    def __str__(self, /) -> str: ...
+
+class EnvMismatchError(RuntimeError):
+    """Raised when environments of provided expressions mismatch."""
+
+    def __str__(self, /) -> str: ...
+
+class InternalPanicError(RuntimeError):
+    """Raised when an internal and unrecoverable error occurred."""
+
+    def __str__(self, /) -> str: ...
+
+__all__ = [
+    "ComputationError",
+    "ComputationError",
+    "DecodeError",
+    "DifferentEnvsError",
+    "DuplicateConstraintNameError",
+    "EvaluationError",
+    "IllegalConstraintNameError",
+    "InternalPanicError",
+    "ModelNotQuadraticError",
+    "ModelNotUnconstrainedError",
+    "ModelSenseNotMinimizeError",
+    "ModelVtypeError",
+    "MultipleActiveEnvironmentsError",
+    "NoActiveEnvironmentFoundError",
+    "NoConstraintForKeyError",
+    "SampleColCreationError",
+    "SampleIncompatibleVtypeError",
+    "SampleIncorrectLengthError",
+    "SampleUnexpectedVariableError",
+    "SolutionTranslationError",
+    "TranslationError",
+    "VariableCreationError",
+    "VariableExistsError",
+    "VariableNamesError",
+    "VariableNotExistingError",
+    "VariableOutOfRangeError",
+    "VariablesFromDifferentEnvsError",
+]

luna_quantum/exceptions/base_luna_quantum_error.py

@@ -0,0 +1,2 @@
+class BaseLunaQuantumError(Exception):
+    """Base class for all Luna Quantum errors."""

luna_quantum/exceptions/luna_quantum_call_type_error.py

@@ -0,0 +1,9 @@
+from luna_quantum.client.schemas.enums.call_style import CallStyle
+from luna_quantum.exceptions.base_luna_quantum_error import BaseLunaQuantumError
+
+
+class LunaQuantumCallStyleError(BaseLunaQuantumError):
+    """Luna Quantum call style error."""
+
+    def __init__(self, call_style: CallStyle) -> None:
+        super().__init__(f"The call style '{call_style}' is not supported.")

luna_quantum/exceptions/patch_class_field_exists_error.py

@@ -0,0 +1,10 @@
+from luna_quantum.exceptions.base_luna_quantum_error import BaseLunaQuantumError
+
+
+class PatchClassFieldExistsError(BaseLunaQuantumError, AttributeError):
+    """Raised when a field is already present in a class."""
+
+    def __init__(self, class_name: str, field_name: str) -> None:
+        super().__init__(
+            f"The class {class_name} already has a field named '{field_name}'"
+        )

luna_quantum/factories/__init__.py

@@ -0,0 +1,4 @@
+from .luna_solve_client_factory import LunaSolveClientFactory
+from .usecase_factory import UseCaseFactory
+
+__all__ = ["LunaSolveClientFactory", "UseCaseFactory"]

luna_quantum/factories/luna_solve_client_factory.py

@@ -0,0 +1,100 @@
+from logging import Logger
+from typing import ClassVar
+
+from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+from luna_quantum.util.log_utils import Logging
+
+
+class LunaSolveClientFactory:
+    """
+    Factory class for managing ILunaSolve client instances.
+
+    This class provides methods to retrieve and manage ILunaSolve client instances
+    based on class configurations and input specifications.
+    """
+
+    _logger: Logger = Logging.get_logger(__name__)
+    _client_class: ClassVar[type[ILunaSolve]]
+
+    _client: ClassVar[ILunaSolve | None] = None
+
+    @staticmethod
+    def get_client(client: ILunaSolve | str | None) -> ILunaSolve:
+        """
+        Get a client based on the input or create a default one.
+
+        This method retrieves an ILunaSolve client based on the provided input.
+        If a client is not given or if the input is invalid,
+        a default ILunaSolve client is instantiated and returned.
+
+        Parameters
+        ----------
+        client : Optional[Union[ILunaSolve, str]]
+            The input client. It can either be an instance of ILunaSolve, a string
+            representation of the client, or None.
+
+        Returns
+        -------
+        ILunaSolve
+            An ILunaSolve client instance.
+        """
+        if isinstance(client, ILunaSolve):
+            LunaSolveClientFactory._logger.debug(
+                "Client is already an instance of ILunaSolve"
+            )
+            return client
+
+        if (
+            LunaSolveClientFactory._client
+            and isinstance(
+                LunaSolveClientFactory._client,
+                LunaSolveClientFactory.get_client_class(),
+            )
+            and LunaSolveClientFactory._client.is_same(client)
+        ):
+            LunaSolveClientFactory._logger.debug(
+                "Cache hit. Last used default client is the same as the new one."
+            )
+            return LunaSolveClientFactory._client
+        LunaSolveClientFactory._logger.debug(
+            "Cache miss. No used default client or configuration changed. "
+            "Creating new client."
+        )
+        client = LunaSolveClientFactory.get_client_class()(client)
+        LunaSolveClientFactory._client = client
+        return client
+
+    @staticmethod
+    def get_client_class() -> type[ILunaSolve]:
+        """
+        Return the class type for the client.
+
+        Retrieve the class type associated with the client from the client factory.
+
+        Returns
+        -------
+        Type[ILunaSolve]
+            The class type of the client.
+        """
+        return LunaSolveClientFactory._client_class
+
+    @staticmethod
+    def set_client_class(client_class: type[ILunaSolve]) -> None:
+        """
+        Set the client class for the ClientFactory.
+
+        This method assigns a specific implementation class of ILunaSolve to the
+        ClientFactory for creating client instances. This allows the factory to use
+        the specified class when creating its objects.
+
+        Parameters
+        ----------
+        client_class : Type[ILunaSolve]
+            The class implementing the ILunaSolve interface to be used by the factory.
+
+        Returns
+        -------
+        None
+
+        """
+        LunaSolveClientFactory._client_class = client_class