luna-quantum 1.1.0__cp312-cp312-win_amd64.whl

luna_quantum/solve/use_cases/sensor_placement.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class SensorPlacement(UseCase):
+    r"""
+    # Sensor Placement.
+
+    Description
+    -----------
+
+    The Sensor Placement problem finds the optimal placement of pressure sensors on a
+    water distribution network, which is modelled by a graph where the edges have
+    weights assigned to them. A higher weight corresponds to a higher importance that a
+    sensor is placed on one of the nodes of the edge. Placing a sensor at a given node
+    has a cost attached to it. The total cost of placing the sensors should also be
+    minimized. As a constraint, there is a predetermined number of sensors s, which
+    should be placed on the network.
+
+    Links
+    -----
+
+    [Transformation](https://arxiv.org/pdf/2108.04075.pdf)
+
+    Attributes
+    ----------
+    ### graph: Dict[int, Dict[int, Dict[str, float]]]
+        \n Problem graph for the sensor placement problem in form of nested
+        dictionaries.
+        \n (e.g. network with 3 nodes:
+        \n _{0: {2: {'weight': 1.0}}, 1: {2: {'weight': 6.0}},
+            2: {0: {'weight': 1.0}, 1: {'weight': 6.0}}}_
+        \n or _networkx.to_dict_of_dicts(networkx.Graph(...))_ )
+
+    ### costs: List[float]
+        \n Cost of placing a sensor on specific node.
+
+    ### s: int
+        \n Number of sensors.
+
+    ### A: float
+        \n Lagrange multiplier in front of constraint in eq. (15).
+
+    ### B: float
+        \n Lagrange multiplier in front of constraint in eq. (13).
+    """
+
+    name: Literal["SPL"] = "SPL"
+    graph: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]
+    costs: list[float]
+    s: int
+    A: float = 1
+    B: float = 30

luna_quantum/solve/use_cases/set_cover.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class SetCover(UseCase):
+    r"""
+    # Set Cover.
+
+    Description
+    -----------
+
+    Given a set _S_ and a list of subsets of _S_, so that each element of _S_ is
+    contained in at least one of the subsets, the Set Cover problem tries to find the
+    smallest possible  family _C_ of these subsets so that all elements of _S_ are
+    contained in at least one subset of _C_.
+
+    Q-Bit Interpretation
+    --------------------
+
+    Let _n_ be the number of elements of _S_ and let _N_ be the number of subsets of
+    _S_. Then, the qubit vector _x_ will have length _N + N * n_. For _x[:N]_,
+    _x[i] = 1_, iff. subset _i_ is contained in the set cover. For _x[N:]_, _x[i] = 1_,
+    iff. the number of subsets which include element _a_ is _m > 0_ and
+    _i = N + a * N + m_.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Set_cover_problem)
+
+    [Transformation](https://arxiv.org/pdf/1302.5843.pdf)
+
+    Attributes
+    ----------
+    ### subset_matrix: List[List[float]]
+        \n A matrix containing all subsets.
+        \n e.g. for the set _{1, 2, 3}_ and the subsets _{1, 2}_, _{2, 3}_, and _{3}_:
+        \n _[[1, 1, 0], [0, 1, 1], [0, 0, 1]]_
+        \n or:
+        \n _SetCover.gen_subsets_matrix([1, 2, 3], [[1, 2], [2, 3], [3]])_
+
+    ### A: int
+        \n A positive constant enforcing that each element of _S_ is contained in at
+        least one subset.
+
+    ### B: int
+        \n A constant (_0 < B < A) minimizing the number of subsets included.
+    """
+
+    name: Literal["SC"] = "SC"
+    subset_matrix: list[list[int]]
+    A: int = 4
+    B: int = 2

luna_quantum/solve/use_cases/set_packing.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class SetPacking(UseCase):
+    r"""
+    # Set Packing.
+
+    Description
+    -----------
+
+    Given a set _S_ and a list of subsets of _S_, a packing is a family _C_ of these
+    subsets so that all sets in _C_ are pairwise disjoint. For a set _S_ and a list of
+    subsets of _S_, the Set Packing problem assigns a weight to each set and tries to
+    find a packing so that the sum of the weights of the used sets is maximized.
+
+    Note that, in contrast to the [transformation](https://arxiv.org/pdf/1811.11538.pdf)
+    mentioned below, our QUBO formulation searches for _min x^t Q x_ instead of
+    _max x^t Q x_ and thus all signs are flipped.
+
+    Q-Bit Interpretation
+    --------------------
+
+    Subset _i_ is part of the packing iff. qubit _i_ is 1.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Set_packing)
+
+    [Transformation](https://arxiv.org/pdf/1811.11538.pdf)
+
+    Attributes
+    ----------
+    ### subset_matrix: List[List[int]]
+        \n A matrix containing all subsets.
+        \n e.g. for the set _{1, 2, 3}_ and the subsets _{1, 2}_, _{2, 3}_, and _{3}_:
+        \n _[[1, 1, 0], [0, 1, 1], [0, 0, 1]]_
+
+    ### weights: List[int]
+        \n An array of length n_subsets which assigns a weight to each subset.
+
+    ### P: int
+        \n Positive, scalar penalty value to penalize subsets that are not disjoint.
+        \n Default: _6_
+    """
+
+    name: Literal["SP"] = "SP"
+    subset_matrix: list[list[int]]
+    weights: list[float]
+    P: int = 6

luna_quantum/solve/use_cases/set_partitioning.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class SetPartitioning(UseCase):
+    r"""
+    # Set Partitioning.
+
+    Description
+    -----------
+
+    The Set Partitioning problem partitions a set of items into a selection of possible
+    subsets so that each item of the set occurs in one and only one subset and the cost
+    of the chosen subsets is minimized.
+
+    Q-Bit Interpretation
+    --------------------
+
+    Subset _i_ is part of the partitioning iff. qubit _i_ is 1.
+
+    Links
+    -----
+
+    [Description and Transformation](https://arxiv.org/pdf/1811.11538.pdf)
+
+    Attributes
+    ----------
+    ### set_: List[int]
+        \n The set of items which has to be partitioned.
+
+    ### subsets: List[List[int]]
+        \n The possible subsets of set_.
+        \n e.g. for _set=[1, 2, 3]_ and the possible subsets _{1, 2}_ and _{3}_ one
+        has to specify _subsets=[[1, 2], [3]]_.
+
+    ### costs: List[int]
+        \n The cost of each possible subset. Has to be of the same length as _subsets_.
+
+    ### P: int
+        \n Positive, scalar penalty value to penalize items that occur in more than one
+        subset.
+        \n Default: _10_
+    """
+
+    name: Literal["SPP"] = "SPP"
+    set_: list[int]
+    subsets: list[list[int]]
+    costs: list[int]
+    P: int = 10

luna_quantum/solve/use_cases/subgraph_isomorphism.py

@@ -0,0 +1,55 @@
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+from luna_quantum.solve.use_cases.type_aliases import NestedDictIntGraph
+
+
+class SubGraphIsomorphism(UseCase):
+    r"""
+    # Subgraph Isomorphism.
+
+    Description
+    -----------
+
+    The Subgraph Isomorphism problem tries to find out whether, for two graphs _G1_ and
+    _G2_, _G2_ contains a subgraph _G3_ that is isomorphic to _G1_, i.e. there exists a
+    bijective, edge-invariant vertex mapping from _G1_ to _G3_. It returns the best such
+    mapping it is able to find.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Subgraph_isomorphism_problem)
+
+    [Transformation](https://researchspace.auckland.ac.nz/bitstream/handle/2292/31756/CDMTCS499.pdf?sequence=1)
+
+    Attributes
+    ----------
+    ### graph1: Dict[int, Dict[int, Dict[str, float]]]
+        \n The graph (in form of nested dictionaries) for which to check whether it is
+        isomorphic to a subgraph of graph2.
+        \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))_ )
+
+    ### graph2: Dict[int, Dict[int, Dict[str, float]]]
+        \n The graph (in form of nested dictionaries) for which to check whether it
+        contains a subgraph that is isomorphic to graph1.
+        \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: float = 1
+        \n A penalty value enforcing the bijectivity of the isomorphism.
+
+    ### b: float = 2
+        \n A penalty value (b > a) enforcing the edge-invariance of the isomorphism.
+    """
+
+    name: Literal["SGI"] = "SGI"
+    graph1: NestedDictIntGraph = Field(name="graph")  # type: ignore[call-overload]
+    graph2: NestedDictIntGraph = Field(name="graph")  # type: ignore[call-overload]
+    a: float = 1
+    b: float = 2

luna_quantum/solve/use_cases/subset_sum.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class SubsetSum(UseCase):
+    r"""
+    # Subset Sum.
+
+    Description
+    -----------
+
+    The Subset Sum problem finds a subset of numbers from a given set of integers where
+    the total sum over the subset is equal or maximally close to a target value t.
+    Example: Set _{5, 8, 4, 6}_ and Target _9_ returns the Subset _{5, 4}_
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Subset_sum_problem)
+
+    [Transformation](https://arxiv.org/pdf/1911.08043.pdf) (section 3.2.3)
+
+    Attributes
+    ----------
+    ### numbers: List[int]
+        \n Set of integers from which the subset is chosen.
+
+    ### t: int
+        \n Target value for sum over all numbers in subset.
+    """
+
+    name: Literal["SS"] = "SS"
+    numbers: list[int]
+    t: int

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())