luna-quantum 1.0.8rc2__cp314-cp314-macosx_11_0_arm64.whl

luna_quantum/solve/use_cases/binary_paint_shop_problem.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class BinaryPaintShopProblem(UseCase):
+    r"""
+    # Binary Paint Shop.
+
+    Description
+    -----------
+
+    The Binary Paint Shop Problem tries to minimize the color change of a paint job with
+    two colors of a sequence of cars. The sequence consists of a fixed number of cars,
+    in which each car type occurs exactly twice and these are to be colored in different
+    colors. Therefore, the car sequence consists of exactly twice as many cars as there
+    are car types.
+
+    Links
+    -----
+
+    [Transformation](https://arxiv.org/pdf/2011.03403.pdf)
+
+    Attributes
+    ----------
+    ### n_cars: int
+        \n Amount of different car types.
+
+    ### sequence: List[int]
+        \n Sequence of the cars.
+    """
+
+    name: Literal["BPSP"] = "BPSP"
+    n_cars: int
+    sequence: list[int]

luna_quantum/solve/use_cases/credit_scoring_feature_selection.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class CreditScoringFeatureSelection(UseCase):
+    r"""
+    # Feature Selection for Credit Scoring.
+
+    Description
+    -----------
+
+    Find the optimal feature subset with regard to independence and influence of
+    features for credit scoring of credit applicants.
+
+    Links
+    -----
+
+    [Transformation](https://1qbit.com/files/white-papers/1QBit-White-Paper-%E2%80%93-Optimal-Feature-Selection-in-Credit-Scoring-and-Classification-Using-a-Quantum-Annealer_-_2017.04.13.pdf)
+
+    Attributes
+    ----------
+    ### U: List[List[float]]
+        \n The matrix U is the design matrix, where each column represents a feature
+        and each row represents the specific values for a feature set.
+
+    ### V: List[int]
+        \n The binary label vector for the respective row in matrix U.
+
+    ### alpha: float
+        \n The balance between feature influence and feature independence in the range
+        _[0, 1]_.
+    """
+
+    name: Literal["CSFS"] = "CSFS"
+    U: list[list[float]]
+    V: list[int]
+    alpha: float

luna_quantum/solve/use_cases/dynamic_portfolio_optimization.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class DynamicPortfolioOptimization(UseCase):
+    r"""
+    # Dynamic Portfolio Optimization.
+
+    Description
+    -----------
+
+    The Dynamic Portfolio Optimization problem tries to find the optimal portfolio for a
+    given set of assets and a fixed investment amount. It aims to find the portfolio
+    with optimal returns for a given risk tolerance. It considers transaction costs when
+    rebalancing across multiple time steps. The optimal portfolio is defined by the
+    binary choices whether to invest in a specific asset and how much to invest in it.
+    The investment amount is split into several so called packages defined as
+    2^(package number). The total number of packages determines the granularity of the
+    result. It defines the amount of possible investment sums in one asset as well as
+    the maximum possible investment in any one asset, which is
+    2^(Number of packages) - 1.
+
+    Links
+    -----
+
+    [Transformation](https://journals.aps.org/prresearch/pdf/10.1103/PhysRevResearch.4.013006)
+
+    Attributes
+    ----------
+    ### tickers: List
+        \n Tickers of assets being tested.
+    ### mu: List[List[float]]
+        \n Expected Returns of the assets.
+        \n Shape: [time_steps][number_of_assets]
+    ### sigma: List[List[List[float]]]
+        \n Coviariance Matrix of the assets.
+        \n Shape: [time_steps][number_of_assets][number_of_assets]
+    ### packages: int
+        \n Number of packages per asset, determines granularity of investment.
+        \n _Package value = 2^(package number)_
+    ### K: int
+        \n Total investment amount, which is fixed.
+    ### gamma: float
+        \n Risk Aversion Coefficient.
+        \n Range: Risk Seeking 0-100 Very Risk Averse.
+        \n Divided by factor 2 as a convention, as stated in paper.
+    ### nu: float
+        \n Transaction Cost percentage, e.g., 0.01 = 1% of transaction size.
+    ### rho: float
+        \n Total investment size constraint factor, Lagrange Multiplier.
+    """
+
+    name: Literal["DPO"] = "DPO"
+    tickers: list[str | int]
+    mu: list[list[float]]
+    sigma: list[list[list[float]]]
+    packages: int
+    K: int
+    gamma: float
+    nu: float
+    rho: float

luna_quantum/solve/use_cases/exact_cover.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class ExactCover(UseCase):
+    r"""
+    # Exact Cover.
+
+    Description
+    -----------
+
+    Given a set _S_ and a list of subsets of _S_, an exact cover is a family _C_ of
+    these subsets so that all elements of _S_ are contained in exactly one subset of
+    _C_. For a set _S_ and a list of subsets of _S_, the Exact Cover problem tries to
+    find the smallest exact cover, i.e. the one that uses the least subsets.
+
+    Q-Bit Interpretation
+    --------------------
+
+    Subset _i_ is part of the exact cover iff. qubit _i_ is 1.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Exact_cover)
+
+    [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 _ExactCover.gen_subsets_matrix([1, 2, 3], [[1, 2], [2, 3], [3]])_
+
+    ### A: int
+        \n A constant enforcing the exact cover of the solution.
+
+    ### B: int
+        \n A constant (_A > nB_) helping find the smallest exact cover.
+    """
+
+    name: Literal["EC"] = "EC"
+    subset_matrix: list[list[int]]
+    A: int = 2
+    B: int = 2

luna_quantum/solve/use_cases/flight_gate_assignment.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class FlightGateAssignment(UseCase):
+    r"""
+    # Flight Gate Assignment.
+
+    Description
+    -----------
+
+    Flight Gate Assignment is a highly relevant optimization problem in airport
+    management. It tries to minimize the total transit time of passengers, considering
+    three typical parts of passenger flow in an airport:
+    \n 1) After a flight, passengers claim their baggage and leave the airport.
+    \n 2) Other passengers switch from one plane to another to get a connecting flight.
+    \n 3) A third group of passengers pass the security check and leave with a flight.
+
+    Links
+    -----
+
+    [Description and Transformation](https://arxiv.org/pdf/1811.09465.pdf)
+
+    Attributes
+    ----------
+    ### n_flights: int
+        \n Number of flights.
+
+    ### n_gates: int
+        \n Number of gates.
+
+    ### n_passengers: List[Tuple[int, int]]
+        \n Number of passengers arriving and departing with each flight.
+        \n Example: _n_passengers[3][departure_index]_, gives us the number of
+        passengers departing with flight _3_.
+
+    ### time_gates: List[Tuple[float, float]]
+        \n The time it takes between every gate and check-in (when leaving) or the gate
+        and baggage claim (when arriving).
+        \n Example: _time_gates[0][arriving_index]_, gives us the time it takes to go
+        from gate _0_ to baggage claim.
+
+    ### time_flights: List[Tuple[float, float]]
+        \n The time at which a flight arrives/leaves.
+        \n Example: _time_flights[2][departure_index]_, gives us the time at which
+        flight 2 departs.
+
+    ### transfer_passengers: List[List[int]]
+        \n Matrix with the information of the passengers transferring from one flight to
+        another.
+        \n Example: _transfer_passengers[2][5]_, gives the number of passengers
+        transferring from flight 2 to flight 5.
+
+    ### time_between_gates: List[List[float]]
+        \n Gives the time it takes to go from one gate to another.
+
+    ### t_buf: float
+        \n Time needed for a gate to be free after a flight has departed.
+
+    ### arrival_index, departure_index: int
+        \n Index to subscribe the variables _time_gates_, _n_passengers_,
+        _time_gates_, _time_flights_.
+        \n One of these variables needs to be _0_, the other _1_.
+    """
+
+    name: Literal["FGO"] = "FGO"
+    n_flights: int
+    n_gates: int
+    n_passengers: list[tuple[int, int]]
+    time_gates: list[tuple[float, float]]
+    time_flights: list[tuple[float, float]]
+    transfer_passengers: list[list[int]]
+    time_between_gates: list[list[float]]
+    t_buf: float
+    arrival_index: int = 0
+    departure_index: int = 1

luna_quantum/solve/use_cases/graph_coloring.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class GraphColoring(UseCase):
+    r"""
+    # Graph Coloring.
+
+    Description
+    -----------
+
+    The Graph Coloring problem tries to color the nodes of a graph with a given number
+    of different colors so that no adjacent nodes have the same color.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Graph_coloring)
+
+    [Transformation](https://arxiv.org/pdf/1811.11538.pdf)
+
+    Attributes
+    ----------
+    ### graph: Dict[int, Dict[int, Dict[str, float]]]
+        \n Problem graph for the graph coloring 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))_ )
+
+    ### n_colors: int
+        \n Number of different colors.
+    """
+
+    name: Literal["GC"] = "GC"
+    graph: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]
+    n_colors: int
+    P: int = 4

luna_quantum/solve/use_cases/graph_isomorphism.py

@@ -0,0 +1,52 @@
+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 GraphIsomorphism(UseCase):
+    r"""
+    # Graph Isomorphism.
+
+    Description
+    -----------
+
+    The Graph Isomorphism problem tries to find out whether two graphs _G1_ and _G2_are
+    isomorphic, i.e. there exists a bijective, edge-invariant vertex mapping from _G1_
+    to _G2_.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Graph_isomorphism)
+
+    [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 first graph (in form of nested dictionaries) to check for isomorphism.
+        \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 (in form of nested dictionaries) to check for isomorphism.
+        \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
+        \n A penalty value enforcing the bijectivity of the isomorphism.
+
+    ### b: float
+        \n A penalty value (b > a) enforcing the edge-invariance of the isomorphism.
+    """
+
+    name: Literal["GI"] = "GI"
+    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/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