luna-quantum 1.0.0__cp311-cp311-manylinux_2_34_x86_64.whl

luna_quantum/client/schemas/solve_job.py

@@ -0,0 +1,47 @@
+from datetime import datetime
+
+from pydantic import BaseModel
+
+from luna_quantum.client.schemas.enums.model_format import ModelFormat
+from luna_quantum.client.schemas.enums.status import StatusEnum
+
+
+class SolveJobSchema(BaseModel):
+    """
+    Solve job schema.
+
+    Attributes
+    ----------
+    id: str
+        The ID of the solve job.
+    status: StatusEnum
+        The current status of the solve job.
+    status_timeline: dict[StatusEnum, datetime]
+        The history of status changes for the solve job.
+    used_format: ModelFormat | None
+        The format that is used for solving. None if not applicable.
+    error_message: str | None
+        The error message if the solve job failed.
+    provider: str
+        The name of the provider where the solve job is scheduled.
+    solver_job_info: str | None
+        Additional information about the solve job. None if not available.
+    is_cancelable: bool
+        Indicates if the solve job can be cancelled.
+    is_cancellation_requested: bool
+        Indicates if cancellation of the solve job has been requested.
+    """
+
+    id: str
+    status: StatusEnum
+    status_timeline: dict[StatusEnum, datetime]
+    used_format: ModelFormat | None = None
+
+    error_message: str | None
+    provider: str
+
+    # TODO(Lev): Consider renaming? # noqa: FIX002
+    solver_job_info: str | None = None
+
+    is_cancelable: bool
+    is_cancellation_requested: bool

luna_quantum/client/schemas/solver_info.py

@@ -0,0 +1,11 @@
+from pydantic import BaseModel
+
+
+class SolverInfo(BaseModel):
+    """Solver info schema."""
+
+    full_name: str
+    short_name: str
+    available: bool
+    params: dict  # type: ignore[type-arg]
+    description: str | None

luna_quantum/client/schemas/user.py

@@ -0,0 +1,11 @@
+from pydantic import BaseModel, EmailStr
+
+
+class User(BaseModel):
+    """Pydantic model for user going OUT."""
+
+    email: EmailStr
+    first_name: str
+    last_name: str
+    groups: list[str] = []
+    orgs: list[str] = []

luna_quantum/client/schemas/wrappers/__init__.py

@@ -0,0 +1,5 @@
+from luna_quantum.client.schemas.wrappers.datetime_wrapper import (
+    PydanticDatetimeWrapper,
+)
+
+__all__ = ["PydanticDatetimeWrapper"]

luna_quantum/client/schemas/wrappers/datetime_wrapper.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated
+
+from dateutil.parser import parse
+from pydantic import BeforeValidator
+
+
+def validate_datetime(date_string: str | datetime) -> datetime:
+    """Validate an ISO date string and return it in the local timezone.
+
+    Parameters
+    ----------
+    date_string : str
+        The ISO date string
+
+    Returns
+    -------
+    datetime
+        The datetime in the user's local timezone
+
+    Raises
+    ------
+    ValueError
+        If `date_string` does not have a valid format.
+    """
+    dt = date_string if isinstance(date_string, datetime) else parse(date_string)
+    return dt.astimezone()
+
+
+PydanticDatetimeWrapper = Annotated[datetime, BeforeValidator(validate_datetime)]

luna_quantum/client/utils/qpu_token_utils.py

@@ -0,0 +1,147 @@
+import os
+
+from luna_quantum.client.schemas.qpu_token.qpu_token import (
+    QpuToken,
+    QpuTokenSource,
+    TokenProvider,
+)
+
+
+class QpuTokenUtils:
+    """Utilities for QPU tokens."""
+
+    @staticmethod
+    def patch_qpu_tokens_from_env(
+        qpu_token: TokenProvider = TokenProvider(),
+    ) -> TokenProvider | None:
+        """
+        Add QPU tokens from environment variables.
+
+        If a token is not found in the environment, it will be set to None.
+        If no token-provider is provided, a new one will be created.
+
+        Parameters
+        ----------
+        qpu_token: TokenProvider
+            Token-provider to update. If no token-provider is provided,
+            a new one will be created.
+
+        Returns
+        -------
+        Optional[TokenProvider]
+            Returns the updated token-provider. If the token-provider is empty,
+            returns None.
+        """
+        qpu_token.dwave = QpuTokenUtils.get_token_from_provider_or_env(
+            token=qpu_token.dwave, env_key="LUNA_DWAVE_TOKEN"
+        )
+        qpu_token.ibm = QpuTokenUtils.get_token_from_provider_or_env(
+            token=qpu_token.ibm, env_key="LUNA_IBM_TOKEN"
+        )
+        qpu_token.qctrl = QpuTokenUtils.get_token_from_provider_or_env(
+            token=qpu_token.qctrl, env_key="LUNA_QCTRL_TOKEN"
+        )
+        qpu_token.fujitsu = QpuTokenUtils.get_token_from_provider_or_env(
+            token=qpu_token.fujitsu, env_key="LUNA_FUJITSU_TOKEN"
+        )
+        qpu_token.aws_access_key = QpuTokenUtils.get_token_from_provider_or_env(
+            token=qpu_token.aws_access_key, env_key="LUNA_AWS_ACCESS_KEY"
+        )
+        qpu_token.aws_secret_access_key = QpuTokenUtils.get_token_from_provider_or_env(
+            token=qpu_token.aws_secret_access_key, env_key="LUNA_AWS_SECRET_ACCESS_KEY"
+        )
+        qpu_token.aws_session_token = QpuTokenUtils.get_token_from_provider_or_env(
+            token=qpu_token.aws_session_token, env_key="LUNA_AWS_SESSION_TOKEN"
+        )
+
+        if QpuTokenUtils.is_token_provider_empty(qpu_token):
+            return None
+
+        return qpu_token
+
+    @staticmethod
+    def is_qpu_token_empty(qpu_token: QpuToken) -> bool:
+        """
+        Check if the QpuToken object is empty.
+
+        An empty QpuToken is defined as having both its `name` and `token`
+        attributes set to `None`.
+
+        Parameters
+        ----------
+        qpu_token : QpuToken
+            The QpuToken object to check for emptiness.
+
+        Returns
+        -------
+        bool
+            True if the QpuToken is empty, otherwise False.
+
+        """
+        return qpu_token.name is None and qpu_token.token is None
+
+    @staticmethod
+    def is_token_provider_empty(qpu_token: TokenProvider) -> bool:
+        """
+        Check if the token provider is empty.
+
+        The function checks whether all attributes of the provided token provider are
+        None, indicating that it is empty.
+
+        Parameters
+        ----------
+        qpu_token : TokenProvider
+            The token provider object containing various token attributes.
+
+        Returns
+        -------
+        bool
+            True if all token attributes are None, otherwise False.
+        """
+        if qpu_token is None:
+            return True
+        for field in [
+            qpu_token.dwave,
+            qpu_token.ibm,
+            qpu_token.qctrl,
+            qpu_token.fujitsu,
+            qpu_token.aws_access_key,
+            qpu_token.aws_secret_access_key,
+            qpu_token.aws_session_token,
+        ]:
+            if field is not None and not QpuTokenUtils.is_qpu_token_empty(field):
+                return False
+        return True
+
+    @staticmethod
+    def get_token_from_provider_or_env(
+        token: QpuToken | None, env_key: str
+    ) -> QpuToken | None:
+        """
+        Get token from provider or environment variable.
+
+        If a token is provided and not empty, return it. Otherwise, attempt to retrieve
+        a token from the specified environment variable. If no token is found, return
+        None.
+
+        Parameters
+        ----------
+        token : Optional[QpuToken]
+            Token provided by the caller.
+        env_key : str
+            The key for the environment variable to look for a token.
+
+        Returns
+        -------
+        Optional[QpuToken]
+            The token retrieved either from the provided input or the environment.
+        """
+        if token is None or QpuTokenUtils.is_qpu_token_empty(token):
+            env_value = os.environ.get(env_key, None)
+            if env_value is not None:
+                return QpuToken(
+                    source=QpuTokenSource.INLINE,
+                    token=env_value,
+                )
+            return None
+        return token

luna_quantum/errors.py

@@ -0,0 +1 @@
+from ._core.errors import *  # type: ignore[import-not-found] # noqa: F403

luna_quantum/errors.pyi

@@ -0,0 +1,202 @@
+class VariableOutOfRangeError(Exception):
+    """
+    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
+    """
+
+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.
+    """
+
+class VariableNotExistingError(Exception):
+    """
+    Raised when trying to get a variable with a name that does not exist.
+    """
+
+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.
+    """
+
+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.
+    """
+
+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.
+    """
+
+class NoActiveEnvironmentFoundError(Exception):
+    """
+    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.
+    """
+
+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.
+    """
+
+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()`.
+    """
+
+class VariableNamesError(Exception):
+    """
+    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.
+    """
+
+class IllegalConstraintNameError(Exception):
+    """
+    Raised when a constraint is tried to be created with an illegal name.
+    """
+
+class TranslationError(Exception):
+    """
+    Raised when an error occurred during translation.
+    """
+
+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.
+    """
+
+class ModelNotUnconstrainedError(TranslationError):
+    """
+    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.
+    """
+
+class ModelSenseNotMinimizeError(TranslationError):
+    """
+    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.
+    """
+
+class ModelVtypeError(TranslationError):
+    """
+    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.
+    """
+
+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.
+    """
+
+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.
+    """
+
+class SampleUnexpectedVariableError(SolutionTranslationError):
+    """
+    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.
+    """
+
+class SampleIncompatibleVtypeError(SolutionTranslationError):
+    """
+    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.
+    """
+
+class ComputationError(Exception):
+    """
+    Raised when an error occured in an internal computation.
+    """
+
+class EvaluationError(Exception):
+    """
+    Raised when an error occured during evaluation of a model.
+    """
+
+__all__ = [
+    "ComputationError",
+    "DecodeError",
+    "DifferentEnvsError",
+    "EvaluationError",
+    "IllegalConstraintNameError",
+    "ModelNotQuadraticError",
+    "ModelNotUnconstrainedError",
+    "ModelSenseNotMinimizeError",
+    "ModelVtypeError",
+    "MultipleActiveEnvironmentsError",
+    "NoActiveEnvironmentFoundError",
+    "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/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,75 @@
+from typing import ClassVar
+
+from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+
+
+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.
+    """
+
+    _client_class: ClassVar[type[ILunaSolve]]
+
+    @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):
+            return client
+        if isinstance(client, str):
+            return LunaSolveClientFactory.get_client_class()(client)
+        return LunaSolveClientFactory.get_client_class()()
+
+    @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