luna-quantum 1.1.0__cp312-cp312-win_amd64.whl

luna_quantum/solve/use_cases/graph_partitioning.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class GraphPartitioning(UseCase):
+    r"""
+    Graph Partitioning.
+
+    Description
+    -----------
+
+    The Graph Partitioning problem tries to find two equal sized partitions for a given
+    undirected graph with an even number of vertices, so that the number of edges
+    connecting the two subsets is minimized.
+
+    Links
+    -----
+
+    [Transformation](https://arxiv.org/abs/1302.5843)
+
+    Attributes
+    ----------
+    ### graph : Dict[int, Dict[int, Dict[str, float]]]
+        \n The graph, for which the partitions are to be foundin 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[int]
+        \n Penalty parameter A panalizes violation of the constraint that makes sure
+        both partitions are of equal size. It can be left "None" to be estimated from
+        the problem graph via the papers suggestion.
+
+    ### B : Optional[int]
+        \n Optimization penalty parameter B penalizes each edge connecting two nodes of
+        different partitions. If not given it defaults to 1.
+    """
+
+    name: Literal["GP"] = "GP"
+    graph: dict[str, dict[str, dict[str, float]]]
+    A: int | None = None
+    B: int | None = 1

luna_quantum/solve/use_cases/hamiltonian_cycle.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class HamiltonianCycle(UseCase):
+    r"""
+    # Hamiltonian Cycle.
+
+    Description
+    -----------
+
+    The Hamiltonian Cycle problem, either for a directed or undirected graph, asks the
+    following: starting at an arbitrary node in the graph, can one travel along the
+    edges of the graph so that each graph will be visited exactly once and there is an
+    edge between the starting node and the last node?
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Hamiltonian_path_problem)
+
+    [Transformation](https://arxiv.org/pdf/1302.5843.pdf)
+
+    Attributes
+    ----------
+    ### graph: Dict[int, Dict[int, Dict[str, float]]]
+        \n Problem graph for the hamiltonian cycle 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 Default: _1.0_
+    """
+
+    # Hamiltonian Cycle is just TSP with B = 0.
+
+    name: Literal["HC"] = "HC"
+    graph: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]
+    directed: bool | None = False
+    A: float = 1.0
+    B: float = 0.0

luna_quantum/solve/use_cases/induced_subgraph_isomorphism.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class InducedSubGraphIsomorphism(UseCase):
+    r"""
+    # Induced Subgraph Isomorphism.
+
+    Description
+    -----------
+
+    Given two graphs the induced subgraph isomorphism problem is to decide if there
+    exists an edge invariant injective mapping from the vertices of the first graph to
+    the second graph.
+    The task is slightly different from the subgraph isomorphism problem, because here
+    additional edges present between two vertices in the second graph to which the
+    isomorphism maps, are prohibited.
+
+    This Implementation is heavily based on the subgraph isomorphism problem
+    implementation.
+    It uses slack variables to counterbalance unnecessary penalties.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Induced_subgraph_isomorphism_problem)
+
+    [Transformation](https://researchspace.auckland.ac.nz/bitstream/handle/2292/31756/CDMTCS499.pdf)
+
+    Attributes
+    ----------
+    ### graph1: Dict[int, Dict[int, Dict[str, float]]]
+        \n The first graph 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))_ )
+
+    ### graph2: Dict[int, Dict[int, Dict[str, float]]]
+        \n The second graph, on which the first one is to be mapped, also in form of
+        nested dictionaries.
+    """
+
+    name: Literal["ISGI"] = "ISGI"
+    graph1: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]
+    graph2: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]

luna_quantum/solve/use_cases/job_shop_scheduling.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class JobShopScheduling(UseCase):
+    r"""
+    # Job Shop Scheduling.
+
+    Description
+    -----------
+
+    Consider a number of jobs, each of which consists of a number of operations which
+    have to be processed in a specific order. Each operation has a specific machine that
+    it needs to be processed on and only one operation in a job can be processed at a
+    given time. Also, each machine can only execute one job at a time. The objective of
+    the Job Shop Scheduling problem is to schedule all operations in a valid sequence
+    while minimizing the makespan of the jobs, i.e. the completion time of the last
+    running job.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Job-shop_scheduling)
+
+    [Transformation](https://arxiv.org/pdf/1506.08479.pdf)
+
+    Attributes
+    ----------
+    ### jobs: Dict[int, List[Tuple[int, int]]]
+        \n A dictionary containing all jobs. Each job is a list of operations and each
+        operation is tuple containing the machine and the processing time.
+
+    ### T: int
+        \n Strict upper bound when all jobs should be finished.
+    """
+
+    name: Literal["JSS"] = "JSS"
+    jobs: dict[int, list[tuple[int, int]]] = Field(name="dict")  # type: ignore[call-overload]
+    T: int = 0

luna_quantum/solve/use_cases/k_medoids_clustering.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class KMedoidsClustering(UseCase):
+    r"""
+    # K-Medoids Clustering.
+
+    Description
+    -----------
+
+    The authors are concerned with k-medoids clustering and propose a quadratic
+    unconstrained binary optimization (*QUBO*) formulation of the problem of
+    identifying *k* medoids among *n* data points without having to cluster the data.
+    Given our *QUBO* formulation of this NP-hard problem, it should be possible to solve
+    it on adiabatic quantum computers.
+
+    Q-Bit Interpretation
+    --------------------
+
+    "The qubit vector at index _k_ is 1 iff. data point _k_ from the distance matrix is
+    chosen as medoid of a cluster. The step of assigning the remaining data points to
+    clusters is not covered in this problem but can be easily done in linear time with
+    respect to the number of data points."
+
+    Links
+    -----
+
+    [Transformation](http://ceur-ws.org/Vol-2454/paper_39.pdf)
+
+    Attributes
+    ----------
+    D : List[List[float]]
+        \n The (*n x n*) similarity matrix (diagonal elements are *1* (*one*)).
+
+    k : int
+        \n The number of medoids.
+
+    gamma :  float
+        \n Penalty coefficient to enforce feasibility.
+    """
+
+    name: Literal["KMC"] = "KMC"
+    D: list[list[float]]
+    k: int
+    gamma: float

luna_quantum/solve/use_cases/knapsack_integer_weights.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class KnapsackIntegerWeights(UseCase):
+    r"""
+    # Knapsack with Integer Weights.
+
+    Description
+    -----------
+
+    Given a knapsack that can only carry a weight _W_ and a set of objects, each object
+    having a weight _w_ and a value _c_, the Knapsack with Integer Weights problem tries
+    to find objects so that the sum of their values is maximized while, at the same
+    time, the sum of their weights does not exceed the capacity of the knapsack.
+
+    Links
+    -----
+
+    [Description and Transformation](https://arxiv.org/pdf/1302.5843.pdf)
+
+    Attributes
+    ----------
+    ### w: List[int]
+        \n The weight of each object.
+
+    ### c: List[float]
+        \n The value of each object.
+
+    ### W: int
+        \n The weight that the knapsack can carry.
+
+    ### B: float
+        \n A positive constant to reward putting an object into the knapsack.
+        \n Default: _1_
+
+    ### A: Optional[float]
+        \n A positive penalty value, enforcing that the maximal weight will not be
+        exceeded. If specified, the equation _A > B _max_(c)_ must hold. If not
+        specified, will be computed automatically as _A = 1 + B _max_(c)_.
+
+    ### linear_encoding: bool
+        \n If false, the number of qubits will be highly reduced, using the log trick
+        from section 2.4 of the paper linked above.
+    """
+
+    name: Literal["KIW"] = "KIW"
+    w: list[int]
+    c: list[float]
+    W: int
+    B: float = 1.0
+    A: float | None = None
+    linear_encoding: bool = False

luna_quantum/solve/use_cases/linear_regression.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class LinearRegression(UseCase):
+    r"""
+    # Linear Regression.
+
+    Description
+    -----------
+
+    In statistics, linear regression is a linear approach to modelling the relationship
+    between a real-valued dependent variable and one or more real-valued independent
+    variables.
+
+    Q-Bit Interpretation
+    --------------------
+
+    For interpretation, the qubit vector has to be cut into (n_features + 1) sublists of
+    length K (specified below). The sum of each of the product of each of these sublists
+    and the precision vector gives an estimated feature weight.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Linear_regression)
+
+    [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 Regression labels of the training data set.
+        \n (e.g. for 3 data points:
+        \n _[1.2, -3.4, 2.41]_ )
+
+    ### 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 powers of 2, to
+        simulate real values. This parameter determines the length of this vector.
+        \n (e.g. for K = 6, the precision vector is _[-2, -1, -0.5, 0.5, 1, 2]_)
+        \n This parameter also determines the size of the qubo matrix together with the
+        number of features _d_:
+        \n _size = (d + 1) * K_
+    """
+
+    name: Literal["LR"] = "LR"
+    X: list[list[float]]
+    Y: list[float]
+    K: int = 24

luna_quantum/solve/use_cases/lmwcs.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+if TYPE_CHECKING:
+    from luna_quantum.solve.use_cases.type_aliases import NestedDictGraph
+
+
+class LabeledMaxWeightedCommonSubgraph(UseCase):
+    r"""
+    # Labeled Maximum Weighted Common Subgraph.
+
+    Description
+    -----------
+
+    The Labeled Maximum Weighted Common Subgraph (LMWCS) problem finds, given two graphs
+    _G1_ and _G2_, the largest subgraph of _G1_ that is isomorphic to a subgraph of
+    _G2_. A weight is associated with each possible mapping between a node in _G1_ and a
+    node in _G2_ to model a difference in importance for different mappings between
+    nodes in the first graph and the second graph. The vertex pairs with assigned value
+    _1_ form the common subgraph. Besides the constraint on the mappings which follow
+    from requiring bijectivity, one can also define user-defined constraints.
+
+    Notes
+    -----
+    There is an error in definition of _C_ (bijectivity constraint): condition one
+    should be: _((i == m)_ or _(j == n))_ and not _((i == j)_ and _(j == n))_.
+
+    We need to map the binary vector elements _b_{i, j}_, where _i_ and _j_ describe a
+    node in the graphs 1 and 2 respectively, to an entry in a
+    _(graph1.order() * graph2.order())_ dimensional vector. Here, we say that the
+    element _b_{i, j}_ is mapped to the _(i * graph2.order() + j)_th entry of the
+    vector.
+
+    Generally, we have to fulfill _a_{(i, j), (m, n)} > min(w_{i, j}, w_{m, n})_ with
+    _w_ being the weights for the pairs _(i, j)_. Here, we choose _a > max(weights)_ as
+    if _a_ fulfills this condition for all _a_{(i, j), (m, n)}_.
+
+    Q-Bit Interpretation
+    --------------------
+
+    The tuple _(i, j)_ is part of the mapping iff. qubit _i * graph2.order() + j_ is 1.
+
+    Links
+    -----
+
+    [Transformation](https://arxiv.org/pdf/1601.06693.pdf)
+
+    Attributes
+    ----------
+    ### graph1: Dict[int, Dict[int, Dict[str, float]]]
+        \n First problem graph for the lmwcs 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))_ )
+
+    ### graph2: Dict[int, Dict[int, Dict[str, float]]]
+        \n Second problem graph for the lmwcs 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))_ )
+
+    ### weigths: List[float]
+        \n Weights for all pairs _(i, j)_ in _graph1.nodes x graph2.nodes_.
+
+    ### a: float
+        \n Penalty for mapping violating bijectivity or user constraints.
+
+    ### user_constraints: List[Tuple[Tuple[int, int], Tuple[int, int]]]
+        \n User given constraints on the vertex mapping.
+        \n _((i, j), (m, n))_ being part of the user constraints means that _(i, j)_ and
+        _(m, n)_ must not be part of the mapping at the same time.
+    """
+
+    name: Literal["LMWCS"] = "LMWCS"
+    graph1: NestedDictGraph = Field(name="graph")  # type: ignore[call-overload]
+    graph2: NestedDictGraph = Field(name="graph")  # type: ignore[call-overload]
+    weights: list[float]
+    a: float
+    user_constraints: list[tuple[tuple[int, int], tuple[int, int]]] | None = None

luna_quantum/solve/use_cases/longest_path.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class LongestPath(UseCase):
+    r"""
+    # Longest Path.
+
+    Description
+    -----------
+
+    The longest path problem is the problem of finding a simple path of maximum length
+    from a given start node to a given terminal node in a given graph. A path is called
+    simple if it does not have any repeated vertices.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Longest_path_problem)
+
+    [Transformation](https://www.sciencedirect.com/science/article/abs/pii/S030439752100092X#!)
+
+    Attributes
+    ----------
+    ### graph: Dict[int, Dict[int, Dict[str, float]]]
+        \n Problem graph for the longest path 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))_ )
+
+    ### start_node:
+        \n At which node to start.
+
+    ### terminal_node:
+        \n At which node to stop.
+
+    ### steps:
+        \n How many nodes to include in the path.
+    """
+
+    name: Literal["LP"] = "LP"
+    graph: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]
+    start_node: str
+    terminal_node: str
+    steps: int

luna_quantum/solve/use_cases/market_graph_clustering.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class MarketGraphClustering(UseCase):
+    r"""
+    # Market Graph Clustering.
+
+    Description
+    -----------
+
+    The authors formulate the index-tracking problem as a QUBO graph-clustering problem.
+    Their formulation restricts the number of assets while identifying the most
+    representative exemplars of an index. Their thesis is that a portfolio consisting of
+    the most representative set of exemplars will minimize tracking-error.
+    Initial results are very encouraging. Their tests show they accurately replicate the
+    returns of broad market indices, using only a small subset of their constituent
+    assets. Moreover, their QUBO formulation allows us to take advantage of recent
+    hardware advances to overcome the NP-hard nature of the clustering problem.
+    Using these novel architectures they obtain better solutions within small fractions
+    of the time required to solve equivalent problems formulated in traditional
+    constrained form and solved on traditional hardware. Their initial results certainly
+    offer hope and set the stage for larger-scale problems, in finance and beyond.
+
+    Their implementation is based on the work of *Bauckhage et al.*.
+
+    Q-Bit Interpretation
+    --------------------
+
+    "The qubit vector at index _k_ is 1 iff. stock _k_ from matrix _G_ (see below) is
+    chosen as medoid of a cluster. The step of assigning the remaining stocks to
+    clusters is not covered in this problem but can be easily done in linear time with
+    respect to the number of data points."
+
+    Links
+    -----
+
+    [Transformation (Market Graph Clustering via QUBO and Digital Annealing)](https://www.mdpi.com/1911-8074/14/1/34)
+
+    [Bauckhage et al. (A QUBO Formulation of the k-Medoids Problem)](http://ceur-ws.org/Vol-2454/paper_39.pdf)
+
+    Attributes
+    ----------
+    ### G: List[List[float]]
+        \n An *n x m* matrix, where *n* is the number of stocks and *m* is the number of
+        time units with returns for the respective stock at this time.
+
+    ### k: int
+        \n The number of representatives desired.
+
+    ### gamma: float
+        \n Penalty coefficient to enforce feasibility of the solution.
+    """
+
+    name: Literal["MGC"] = "MGC"
+    G: list[list[float]]
+    k: int
+    gamma: float

luna_quantum/solve/use_cases/max2sat.py

@@ -0,0 +1,54 @@
+"""Provides the Max2SAT class."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+if TYPE_CHECKING:
+    from luna_quantum.solve.use_cases.type_aliases import Clause
+
+
+class Max2SAT(UseCase):
+    r"""
+    # Maximum 2-SAT.
+
+    Description
+    -----------
+
+    For a formula in conjunctive normal form (CNF) with two literals per clause, the
+    Maximum 2-SAT problem determines the maximum number of clauses that can be
+    simultaneously satisfied by an assignment.
+
+    Q-Bit Interpretation
+    --------------------
+
+    Each qubit corresponds to the truth value of one of the variables, to be precise:
+    _sorted(variables)[i] == True_ iff. _qubits[i] == 1_.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/2-satisfiability#Maximum-2-satisfiability)
+
+    [Transformation](https://arxiv.org/pdf/1811.11538.pdf)
+
+    Attributes
+    ----------
+    ### clauses: List[Tuple[Tuple[int, bool], Tuple[int, bool]]]
+        \n A list containing all clauses of the formula in CNF in form of tuples.
+        \n (e.g. the formula _x0 * x1 + -x1 * x2_:
+        \n _[((0, True), (1, True)), ((1, False), (2, True))]_ )
+        \n It is possible to use arbitrary variable indices.
+
+    ### n_vars: Optional[int]
+        \n The number of different variables. Can be used to check whether the input
+        clauses have the desired number of different variables.
+    """
+
+    name: Literal["M2SAT"] = "M2SAT"
+    clauses: list[Clause] = Field(name="clauses")  # type: ignore[call-overload]
+    n_vars: int | None = None

luna_quantum/solve/use_cases/max3sat.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+if TYPE_CHECKING:
+    from luna_quantum.solve.use_cases.type_aliases import Clause
+
+
+class Max3SAT(UseCase):
+    r"""
+    # Maximum 3-SAT.
+
+    Description
+    -----------
+
+    For a formula in conjunctive normal form (CNF) with three literals per clause, the
+    Maximum 3-SAT problem determines the maximum number of clauses that can be
+    simultaneously satisfied by an assignment.
+
+    Q-Bit Interpretation
+    --------------------
+
+    Let _n_ be the number of different variables and let _m_ be the number of clauses.
+    Then, each of the first _n_ qubits corresponds to the truth value of one of the
+    variables, to be precise: _sorted(variables)[i] == True_ iff. _qubits[i] == 1_. Each
+    of the last _m_ qubits tells whether the corresponding clause is fulfilled,
+    formally: _clauses[i]_ is fulfilled iff. _qubits[n + i] == 1_.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/MAX-3SAT)
+
+    [Transformation](https://canvas.auckland.ac.nz/courses/14782/files/574983/download?verifier=1xqRikUjTEBwm8PnObD8YVmKdeEhZ9Ui8axW8HwP&wrap=1)
+
+    Attributes
+    ----------
+    ### clauses: List[Tuple[Tuple[int, bool], Tuple[int, bool], Tuple[int, bool]]]
+        \n A list containing all clauses of the formula in CNF in form of tuples.
+        \n (e.g. the formula _x0 * x1 * -x2 + -x1 * x2 * x3_:
+        \n _[((0, True), (1, True), (2, False)), ((1, False), (2, True), (3, True))]_ )
+        \n It is possible to use arbitrary variable indices.
+
+    ### n_vars: Optional[int]
+        \n The number of different variables. Can be used to check whether the input
+        clauses have the desired number of different variables.
+    """
+
+    name: Literal["M3SAT"] = "M3SAT"
+    clauses: list[Clause] = Field(name="clauses")  # type: ignore[call-overload]
+    n_vars: int | None = None