luna-quantum 1.0.8rc2__cp314-cp314-macosx_10_12_x86_64.whl

luna_quantum/solve/use_cases/support_vector_machine.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class SupportVectorMachine(UseCase):
+    r"""
+    # Support Vector Machine.
+
+    Description
+    -----------
+
+    In machine learning, support vector machines are supervised learning models that
+    perform linear classification in such a way that the seperating hyperplane is as far
+    away from each data point as possible.
+
+    Note that, in this implementation, the model always assumes the separating
+    hyperplane to be unbiased, i.e. it goes through the origin.
+
+    Q-Bit Interpretation
+    --------------------
+
+    For interpretation, the qubit vector has to be cut into N sublists of length K
+    (specified below). The sum of each of the products of each of these sublists and the
+    precision vector gives a lagrangian multiplier for each data point.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Support-vector_machine)
+
+    [Transformation](https://doi.org/10.1038/s41598-021-89461-4)
+
+    Attributes
+    ----------
+    ### X: List[List[float]]
+        \n Training data set in form of a nested list.
+        \n All inner lists have to be of the same length.
+        \n (e.g. 3 data points with 2 features:
+        \n _[[1.1, 4.23], [0.1, -2.4], [-2.3, 1.11]]_
+
+    ### Y: List[int]
+        \n Classification labels of the training data set.
+        \n e.g. for 3 data points:
+        \n _[-1, 1, 1]_
+
+    ### K: int
+        \n Length of the precision vector.
+        \n As the problem outputs are supposed to be real values but the qubo only
+        gives a binary vector, we need a precision vector, consisting of positive powers
+        of 2, to simulate real values. This parameter determines the length of this
+        vector.
+        \n (e.g. for K = 5, the precision vector is _[0.25, 0.5, 1, 2, 4]_)
+        \n This parameter also determines the size of the qubo matrix together with the
+        number of data points _N_:
+        \n _size = N * K_
+    """
+
+    name: Literal["SVM"] = "SVM"
+    X: list[list[float]]
+    Y: list[int]
+    K: int = 5

luna_quantum/solve/use_cases/traffic_flow.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class TrafficFlow(UseCase):
+    r"""
+    # Traffic Flow Optimization.
+
+    Description
+    -----------
+
+    The Traffic Flow Optimization problem tries to minimize the total time for a given
+    set of cars to travel between their individual sources and destinations. This is
+    achieved by minimizing the number of overlapping segments between assigned routes
+    for each car.
+
+    Links
+    -----
+
+    [Description and Transformation](https://www.frontiersin.org/articles/10.3389/fict.2017.00029/full)
+
+    Attributes
+    ----------
+    ### car_routes: List[List[List[int]]]
+        \n The route segments of each possible route for each car.
+        \n (e.g. for two cars, where car 1 can take either route 0, 1, 2 or route 0, 3,
+        4 and car 2 can take either route 3, 0, 5 or route 6, 7, 5:
+        \n _[[[0, 1, 2], [0, 3, 4]], [[3, 0, 5], [6, 7, 5]]]_
+    """
+
+    name: Literal["TFO"] = "TFO"
+    car_routes: list[list[list[int]]]

luna_quantum/solve/use_cases/travelling_salesman_problem.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class TravellingSalesmanProblem(UseCase):
+    r"""
+    # Travelling Salesman.
+
+    Description
+    -----------
+
+    The Travelling Salesman problem, either for a directed or undirected graph, asks the
+    following: given a graph, where the edges are labeled with the distances between the
+    corresponding nodes, what is the shortest possible route that visits each node
+    exactly once and returns to the origin node?
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Travelling_salesman_problem)
+
+    [Transformation](https://arxiv.org/pdf/1302.5843.pdf)
+
+    Attributes
+    ----------
+    graph: Dict[int, Dict[int, Dict[str, float]]]
+        \n Problem graph for the travelling salesman problem in form of nested
+        dictionaries.
+        \n (e.g. fully connected graph with 3 nodes:
+        \n _{0: {1: {}, 2: {}}, 1: {0: {}, 2: {}}, 2: {0: {}, 1: {}}}_
+        \n or _networkx.to_dict_of_dicts(networkx.complete_graph(3))_ )
+
+    A: Optional[float]
+        \n Positive penalty value which enforces that each node is visited exactly once.
+        \n if _None_, will be calculated with the equation: _A = B * _max_weight_ + 1_
+        \n Default: _None_
+
+    B: Optional[float]
+        \n Positive penalty value (_B * _max_weight_) < A_) which helps find the
+        shortest route.
+        \n Default: _1.0_
+    """
+
+    name: Literal["TSP"] = "TSP"
+    graph: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]
+    directed: bool | None = False
+    B: float | None = 1.0
+    A: float | None = None

luna_quantum/solve/use_cases/type_aliases.py

@@ -0,0 +1,9 @@
+Node = int | str
+
+NestedDictGraph = dict[Node, dict[Node, dict[str, float]]]
+
+NestedDictIntGraph = dict[int, dict[int, dict[str, float]]]
+
+CalculusLiteral = tuple[int, bool]
+
+Clause = tuple[CalculusLiteral, ...]

luna_quantum/solve/use_cases/weighted_max_cut.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class WeightedMaxCut(UseCase):
+    r"""
+    # Weighted Maximum Cut.
+
+    Description
+    -----------
+
+    The Weighted Maximum Cut problem tries to find a cut that maximizes the weight of
+    intersecting edges in an undirected weighted graph.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Maximum_cut)
+
+    [Transformation](https://arxiv.org/pdf/2009.05008.pdf)
+
+    Attributes
+    ----------
+    ### graph: Dict[int, Dict[int, Dict[str, float]]]
+        \n Problem graph for the weighted maximum cut problem in form of nested
+        dictionaries.
+        \n Every edge has to have an assigned weight.
+        \n (e.g. fully connected graph with 3 nodes and edge weights:
+        \n _{0: {1: {"weight": 1}, 2: {"weight": 1}}, 1: {0: {"weight": 1},
+        2: {"weight": 1}}, 2: {0: {"weight": 1}, 1: {"weight": 1}}}_ )
+    """
+
+    name: Literal["WMC"] = "WMC"
+    graph: dict[int, dict[int, dict[str, float]]]

luna_quantum/solve/usecases/__init__.py

@@ -0,0 +1,45 @@
+from luna_quantum.solve.usecases.model_delete_usecase import ModelDeleteUseCase
+from luna_quantum.solve.usecases.model_fetch_metadata_usecase import (
+    ModelFetchMetadataUseCase,
+)
+from luna_quantum.solve.usecases.model_get_solution_usecase import (
+    ModelGetSolutionUseCase,
+)
+from luna_quantum.solve.usecases.model_get_solve_jobs_usecase import (
+    ModelGetSolveJobsUseCase,
+)
+from luna_quantum.solve.usecases.model_load_by_id_usecase import (
+    ModelLoadByIdUseCase,
+)
+from luna_quantum.solve.usecases.model_load_by_metadata_usecase import (
+    ModelLoadByMetadataUseCase,
+)
+from luna_quantum.solve.usecases.model_load_metadata_by_hash_usecase import (
+    ModelLoadMetadataByHashUseCase,
+)
+from luna_quantum.solve.usecases.model_save_usecase import ModelSaveUseCase
+from luna_quantum.solve.usecases.solve_job_cancel_usecase import SolveJobCancelUseCase
+from luna_quantum.solve.usecases.solve_job_create_usecase import SolveJobCreateUseCase
+from luna_quantum.solve.usecases.solve_job_delete_usecase import SolveJobDeleteUseCase
+from luna_quantum.solve.usecases.solve_job_fetch_updates_usecase import (
+    SolveJobFetchUpdatesUseCase,
+)
+from luna_quantum.solve.usecases.solve_job_get_result_usecase import (
+    SolveJobGetResultUseCase,
+)
+
+__all__ = [
+    "ModelDeleteUseCase",
+    "ModelFetchMetadataUseCase",
+    "ModelGetSolutionUseCase",
+    "ModelGetSolveJobsUseCase",
+    "ModelLoadByIdUseCase",
+    "ModelLoadByMetadataUseCase",
+    "ModelLoadMetadataByHashUseCase",
+    "ModelSaveUseCase",
+    "SolveJobCancelUseCase",
+    "SolveJobCreateUseCase",
+    "SolveJobDeleteUseCase",
+    "SolveJobFetchUpdatesUseCase",
+    "SolveJobGetResultUseCase",
+]

luna_quantum/solve/usecases/model_delete_usecase.py

@@ -0,0 +1,49 @@
+from luna_quantum.aqm_overwrites import Model
+from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+from luna_quantum.solve.interfaces.usecases.model_delete_usecase_i import (
+    IModelDeleteUseCase,
+)
+from luna_quantum.util.log_utils import progress
+
+
+class ModelDeleteUseCase(IModelDeleteUseCase):
+    """
+    Handle the deletion of models.
+
+    This class facilitates the execution of the model delete method
+    for a given Model.
+
+    Attributes
+    ----------
+    client : ILunaSolve
+        The client instance used for invoking the model delete method.
+    """
+
+    client: ILunaSolve
+
+    def __init__(self, client: ILunaSolve) -> None:
+        self.client = client
+
+    @progress(total=None, desc="Deleting model...")
+    def __call__(self, model: Model) -> None:
+        """
+        Delete the given Model from the client.
+
+        If the Model does not have metadata, this method does nothing. It is assumed
+        that the model was not stored in the client.
+
+        Parameters
+        ----------
+        model : Model
+            The Model instance for which the model delete method is called.
+
+        Returns
+        -------
+        None
+            This method does not return a value.
+
+        """
+        if model.metadata is None:
+            return
+
+        self.client.model.delete(model_id=model.metadata.id)

luna_quantum/solve/usecases/model_fetch_metadata_usecase.py

@@ -0,0 +1,50 @@
+from luna_quantum.aqm_overwrites import Model
+from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+from luna_quantum.solve.domain.model_metadata import ModelMetadata
+from luna_quantum.solve.interfaces.usecases.model_fetch_metadata_usecase_i import (
+    IModelFetchMetadataUseCase,
+)
+from luna_quantum.util.log_utils import progress
+
+
+class ModelFetchMetadataUseCase(IModelFetchMetadataUseCase):
+    """Use case for fetching metadata of an AQ model.
+
+    The `ModelFetchMetadataUseCase` works with a given client interface to
+    retrieve metadata for a specified AQ model.
+
+    Attributes
+    ----------
+    client : ILunaSolve
+        Client used to fetch the metadata for an AQ model.
+    """
+
+    client: ILunaSolve
+
+    def __init__(self, client: ILunaSolve) -> None:
+        self.client = client
+
+    @progress(total=None, desc="Fetching model...")
+    def __call__(self, model: Model) -> ModelMetadata:
+        """
+        Fetch the metadata of the given Model.
+
+        Load the metadata associated with the given Model instance from the client.
+        The metadata is validated before returning it. The metadata is not written to
+        the Model instance.
+
+        Parameters
+        ----------
+        model : Model
+            The Model instance to be associated with metadata.
+
+        Returns
+        -------
+        ModelMetadata
+            The metadata associated with the provided Model.
+        """
+        metadata_schema = self.client.model.get_metadata_by_hash(
+            model_hash=model.__hash__()
+        )
+
+        return ModelMetadata.model_validate(metadata_schema.model_dump())

luna_quantum/solve/usecases/model_get_solution_usecase.py

@@ -0,0 +1,59 @@
+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,
+)
+from luna_quantum.util.log_utils import progress
+
+
+class ModelGetSolutionUseCase(IModelGetSolutionUseCase):
+    """
+    Use case for retrieving solutions of a model.
+
+    Handles the process of interacting with the client to get all solutions
+    for a specific AQ model based on its metadata and associated ID.
+
+    Attributes
+    ----------
+    client : ILunaSolve
+        The client responsible for fetching solutions from the external source.
+    """
+
+    client: ILunaSolve
+
+    def __init__(self, client: ILunaSolve) -> None:
+        self.client = client
+
+    @progress(total=None, desc="Loading solution...")
+    def __call__(self, model: Model) -> list[Solution]:
+        """
+        Load solutions of the given Model input.
+
+        This function retrieves and returns a list of ISolution instances for the
+        given Model. If the Model does not have metadata, an empty list is returned.
+
+        Parameters
+        ----------
+        model : Model
+            The input Model object whose associated solutions are to be retrieved.
+
+        Returns
+        -------
+        list[Solution]
+            A list of Solution objects associated with the given Model.
+        """
+        if model.metadata is None:
+            return []
+
+        model_id = model.metadata.id
+
+        solve_jobs = self.client.solve_job.get_all(model_id=model_id)
+
+        # 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
+            if s.status is StatusEnum.DONE
+        ]

luna_quantum/solve/usecases/model_get_solve_jobs_usecase.py

@@ -0,0 +1,62 @@
+from typing import TYPE_CHECKING
+
+from luna_quantum.aqm_overwrites import Model
+from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+from luna_quantum.solve.domain.solve_job import SolveJob
+from luna_quantum.solve.interfaces.usecases.model_get_solve_jobs_usecase_i import (
+    IModelGetSolveJobUseCase,
+)
+from luna_quantum.util.log_utils import progress
+
+if TYPE_CHECKING:
+    from luna_quantum.client.schemas.solve_job import SolveJobSchema
+
+
+class ModelGetSolveJobsUseCase(IModelGetSolveJobUseCase):
+    """
+    Handle the retrieval of solve jobs for a given Model.
+
+    This class is responsible for interacting with the client to fetch solve jobs
+    related to a given Model. It ensures that the required metadata is present
+    before performing operations with the client.
+
+    Attributes
+    ----------
+    client : ILunaSolve
+        The client used to communicate with the solve job backend or service.
+    """
+
+    client: ILunaSolve
+
+    def __init__(self, client: ILunaSolve) -> None:
+        self.client = client
+
+    @progress(total=None, desc="Loading solve job...")
+    def __call__(self, model: Model) -> list[SolveJob]:
+        """
+        Load solve jobs from the given Model instance.
+
+        Fetches and validates all solve jobs associated with the given Model's
+        metadata and returns them as a list of SolveJob objects. If metadata is
+        missing in the Model, an empty list is returned.
+
+        Parameters
+        ----------
+        model : Model
+            The Model instance whose associated solve jobs are to be fetched.
+
+        Returns
+        -------
+        List[SolveJob]
+            A list of SolveJob objects derived from the fetched solve jobs..
+        """
+        if model.metadata is None:
+            return []
+
+        model_id = model.metadata.id
+
+        solutions: list[SolveJobSchema] = self.client.solve_job.get_all(
+            model_id=model_id
+        )
+
+        return [SolveJob.model_validate(s.model_dump()) for s in solutions]

luna_quantum/solve/usecases/model_load_by_id_usecase.py

@@ -0,0 +1,47 @@
+from luna_quantum.aqm_overwrites import Model
+from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+from luna_quantum.solve.interfaces.usecases.model_load_by_id_usecase_i import (
+    IModelLoadByIdUseCase,
+)
+from luna_quantum.util.log_utils import progress
+
+
+class ModelLoadByIdUseCase(IModelLoadByIdUseCase):
+    """
+    Load an Model by its identifier.
+
+    This class interacts with a client implementing ILunaSolve to fetch and load
+    model models, providing their metadata and content.
+
+    Attributes
+    ----------
+    client : ILunaSolve
+        The client used for fetching the model models.
+    """
+
+    client: ILunaSolve
+
+    def __init__(self, client: ILunaSolve) -> None:
+        self.client = client
+
+    @progress(total=None, desc="Retrieving model...")
+    def __call__(self, model_id: str) -> Model:
+        """
+        Retrieve a Model object based on the given model id.
+
+        This method fetches a model schema using the provided model identifier, converts
+        it to a Model object, and validates its metadata before returning it.
+
+        Parameters
+        ----------
+        model_id : str
+            The unique identifier of the model to retrieve.
+
+        Returns
+        -------
+        Model
+            The retrieved model, with associated metadata validated and populated.
+        """
+        aq_model: Model = self.client.model.get_model(model_id=model_id)
+
+        return aq_model

luna_quantum/solve/usecases/model_load_by_metadata_usecase.py

@@ -0,0 +1,52 @@
+from luna_quantum.aqm_overwrites import Model
+from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+from luna_quantum.solve.domain.model_metadata import ModelMetadata
+from luna_quantum.solve.interfaces.usecases.model_load_by_metadata_usecase_i import (
+    IModelLoadByMetadataUseCase,
+)
+from luna_quantum.util.log_utils import progress
+
+
+class ModelLoadByMetadataUseCase(IModelLoadByMetadataUseCase):
+    """
+    Loads an model model using metadata.
+
+    The purpose of this class is to load an model model from a given metadata
+    object using the specified client. It retrieves the model and attaches the metadata
+    to it.
+
+    Attributes
+    ----------
+    client : ILunaSolve
+        The client responsible for interacting with the model backend.
+    """
+
+    client: ILunaSolve
+
+    def __init__(self, client: ILunaSolve) -> None:
+        self.client = client
+
+    @progress(total=None, desc="Retrieving model...")
+    def __call__(self, model_metadata: ModelMetadata) -> Model:
+        """
+        Callable to retrieve and update an Model instance.
+
+        This method interacts with the client to fetch an Model based on the
+        provided ModelMetadata, updates the model's metadata, and then returns
+        the updated Model instance.
+
+        Parameters
+        ----------
+        model_metadata : ModelMetadata
+            The metadata object containing the ID and relevant data for fetching
+            the corresponding Model.
+
+        Returns
+        -------
+        Model
+            The fetched and updated Model instance.
+
+        """
+        aq_model: Model = self.client.model.get_model(model_id=model_metadata.id)
+
+        return aq_model

luna_quantum/solve/usecases/model_load_metadata_by_hash_usecase.py

@@ -0,0 +1,51 @@
+from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+from luna_quantum.solve.domain.model_metadata import ModelMetadata
+from luna_quantum.solve.interfaces.usecases import (
+    IModelLoadMetadataByHashUseCase,
+)
+from luna_quantum.util.log_utils import progress
+
+
+class ModelLoadMetadataByHashUseCase(IModelLoadMetadataByHashUseCase):
+    """
+    Load metadata for an AQ model using a hash.
+
+    This class interacts with the client to retrieve and validate the metadata
+    of an AQ model by providing its unique hash value.
+
+    Attributes
+    ----------
+    client : ILunaSolve
+        The client used to retrieve AQ model metadata.
+    """
+
+    client: ILunaSolve
+
+    def __init__(self, client: ILunaSolve) -> None:
+        self.client = client
+
+    @progress(total=None, desc="Retrieving model metadata...")
+    def __call__(self, model_hash: int) -> ModelMetadata:
+        """
+        Retrieve the metadata for a specific model using its unique hash.
+
+        This callable retrieves the model metadata by communicating with a client
+        based on the provided model hash. It validates the
+        retrieved metadata against the ModelMetadata schema and returns a
+        validated object.
+
+        Parameters
+        ----------
+        model_hash : int
+            The unique hash identifier for the model whose metadata is to be
+            retrieved.
+
+        Returns
+        -------
+        ModelMetadata
+            A validated object containing metadata information about the model.
+
+        """
+        aq_model_schema = self.client.model.get_metadata_by_hash(model_hash=model_hash)
+
+        return ModelMetadata.model_validate(aq_model_schema.model_dump())

luna_quantum/solve/usecases/model_save_usecase.py

@@ -0,0 +1,63 @@
+from typing import TYPE_CHECKING
+
+from luna_quantum.aqm_overwrites import Model
+from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+from luna_quantum.solve.domain.model_metadata import ModelMetadata
+from luna_quantum.solve.interfaces.usecases.model_save_usecase_i import (
+    IModelSaveUseCase,
+)
+from luna_quantum.util.log_utils import progress
+
+if TYPE_CHECKING:
+    from luna_quantum.client.schemas.model_metadata import ModelMetadataSchema
+
+
+class ModelSaveUseCase(IModelSaveUseCase):
+    """
+    Represents a use case for saving an Model instance.
+
+    Provides functionality to interface with a client implementation for
+    retrieving or creating model metadata and saving model information. The
+    metadata retrieved is not written to the model instance.
+
+    Attributes
+    ----------
+    client : ILunaSolve
+        The client used to perform operations related to saving and retrieving
+        Model metadata, such as fetching metadata by hash or creating new
+        metadata.
+    """
+
+    client: ILunaSolve
+
+    def __init__(self, client: ILunaSolve) -> None:
+        self.client = client
+
+    @progress(total=None, desc="Saving model...")
+    def __call__(self, model: Model) -> ModelMetadata:
+        """
+        Retrieve model metadata, if the model does not exist create and retrieve it.
+
+        This function attempts to fetch the metadata of the given `Model` instance
+        from the model client. If the metadata is not found, the model is saved
+        with the client and the metadata is retrieved again.
+
+        Parameters
+        ----------
+        model : Model
+            The model instance for which metadata is being retrieved or created.
+
+        Returns
+        -------
+        ModelMetadata
+            The validated metadata associated with the given model instance.
+        """
+        metadata: ModelMetadataSchema
+        try:
+            metadata = self.client.model.get_metadata_by_hash(
+                model_hash=model.__hash__()
+            )
+        except Exception:  # TODO(Llewellyn): make more specific to # noqa: FIX002
+            #  Not found exception
+            metadata = self.client.model.create(model=model)
+        return ModelMetadata.model_validate(metadata.model_dump())