luna-quantum 1.1.0__cp312-cp312-win_amd64.whl

luna_quantum/solve/use_cases/max_clique.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class MaxClique(UseCase):
+    r"""
+    # Maximum Clique.
+
+    Description
+    -----------
+
+    The Maximum Clique problem describes the task of finding the largest sized clique in
+    a given graph. A clique is a set of nodes in a graph, where every node has an edge
+    to every other node in the clique. A k-clique denotes a clique with exactly k nodes.
+    The maximum clique of a graph is the clique with the highest possible k value.
+
+    There is a closely related problem, the decisional clique problem, which describes
+    the challenge of determining whether a clique of at least size k exists in the given
+    graph.
+
+    Math
+    ----
+
+    ![Formula](https://www.matthiasknoll.net/storage/img/max_clique.svg)
+
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Clique_problem#Finding_a_single_maximal_clique)
+
+    [Transformation](https://arxiv.org/pdf/1801.08649.pdf)
+
+    Attributes
+    ----------
+    ### graph: Dict[int, Dict[int, Dict[str, float]]]
+        \n Problem graph for the maximum clique 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))_ )
+
+    ### hard_constraints: Dict
+        \n Hard constraints that must be fulfilled by any valid instance. They are
+        defined in _aqcore.transformator.specifications.graph_specifications_.
+
+    ### soft_constraints: Optional[Dict]
+        \n Desirable traits that instances should fulfill.
+
+    ### check_soft_constraints: bool
+        \n Defines whether soft constraints should also be fulfilled. Default is
+        _False_.
+    """
+
+    name: Literal["MCQ"] = "MCQ"
+    graph: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]

luna_quantum/solve/use_cases/max_cut.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class MaxCut(UseCase):
+    r"""
+    # Maximum Cut.
+
+    Description
+    -----------
+
+    The Maximum Cut problem tries to find a cut that maximizes the number of
+    intersecting edges in an undirected graph.
+
+    Q-Bit Interpretation
+    --------------------
+    A cut defines two sets of nodes, 0 and 1.
+    The qubits x = (x_0, x_1, ..., x_n) can be interpreted like this:
+    x_i = 0 iff. node i belongs to set 0 and x_i = 1 iff. it belongs to set 1.
+
+    Math
+    ----
+
+    ![Formula](https://drive.google.com/uc?id=1D41KIt4S6gVkdOefWkwGDWLoIiTyexai)
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Maximum_cut)
+
+    [Transformation](https://arxiv.org/pdf/1811.11538.pdf)
+
+    Attributes
+    ----------
+    ### graph: Dict[int, Dict[int, Dict[str, float]]]
+        \n Problem graph for the maximum cut 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))_ )
+    """
+
+    name: Literal["MC"] = "MC"
+    graph: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]

luna_quantum/solve/use_cases/max_independent_set.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class MaxIndependentSet(UseCase):
+    r"""
+    # Maximum Independent Set.
+
+    Description
+    -----------
+
+    An independent set of a graph _G_ is a set of vertices of _G_, where every two
+    vertices are not connected by an edge in _G_. The Maximum Independent Set problem
+    tries to find the largest independent set of a graph.
+
+    Links
+    -----
+
+    [Description and Transformation](https://arxiv.org/pdf/1801.08653.pdf)
+
+    Attributes
+    ----------
+    ### graph: Dict[int, Dict[int, Dict[str, float]]]
+        \n Problem graph for the maximum independent set 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))_ )
+    """
+
+    name: Literal["MIS"] = "MIS"
+    graph: dict[int, dict[int, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]

luna_quantum/solve/use_cases/minimal_maximal_matching.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class MinimalMaximalMatching(UseCase):
+    r"""
+    # Minimal Maximal Matching.
+
+    Description
+    -----------
+
+    For a graph _G = (V, E)_, the Minimal Maximal Matching problem tries to find a
+    "coloring" _C ⊆ E_ with the following three constraints:
+    \n 1. For each edge in _C_, the incident vertices shall be colored and the union of
+    all these vertices shall be called _D_.
+    \n 2. No two edges in _C_ share a vertex.
+    \n 3. If _u, v ∈ D_, then _(uv) ∉ E_.\n
+
+    Links
+    -----
+
+    [Description and Transformation](https://arxiv.org/pdf/1302.5843.pdf)
+
+    Attributes
+    ----------
+    ### graph: Dict[int, Dict[int, Dict[str, float]]]
+        \n Problem graph for the minimal maximal matching 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: int
+        \n A positive constant enforcing that no vertex has two colored edges.
+
+    ### B: int
+        \n A constant to penalize when an edge is uncolored although it would not
+        violate the coloring condition. For _d_ being the maximal degree in the graph,
+        choose _A > (d - 2)B_.
+
+    ### C: int
+        \n A constant (C < B) to minimize the number of colored edges.
+    """
+
+    name: Literal["MMM"] = "MMM"
+    graph: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]
+    A: int = 10
+    B: int = 2
+    C: int = 1

luna_quantum/solve/use_cases/minimal_spanning_tree.py

@@ -0,0 +1,90 @@
+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 MinimalSpanningTree(UseCase):
+    r"""
+    # Minimal Spanning Tree with maximal degree constraint.
+
+    Description
+    -----------
+
+    The Minimal Spanning Tree problem tries to find a spanning tree over all nodes in a
+    given input graph such that the cost of the covered edges (the sum of the weights
+    inside the tree) is minimal. The addition maximal degree constraint, i.e. limiting
+    the degree of the tree at each node to a maximum value, makes this problem NP-hard.
+
+    Convention on depth index of vertex and edge:
+    Zero index is vertex root and all the edges leaving from root, etc.
+    That means there are N/2 possible depths for edges and N/2 + 1 possible depths for
+    vertices.
+
+    Q-Bit Interpretation
+    --------------------
+
+    Assume we have a graph with _m_ nodes, _n_ edges, a max degree of _k_, and the qubit
+    vector _q_.
+    Then, for _i = 0, ..., n-1_, _q[i] = 1_ iff. edge _i_ is included in the tree.
+    Variables _n, ..., n + ⌈ m / 2 ⌉_ keep track of the depth of a node in the tree.
+    Now, let _a := n + ⌈ m / 2 ⌉_. Variables _a, ..., a + 2 * n_ tell for each edge in
+    the graph which vertex is closer to the root of the tree.
+    Finally, with _b := a * 2 * n_, the variables
+    _b, ..., b + m * ⌊ log2(maxDegree) + 1 ⌋_ count the degree of a node in the tree.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Degree-constrained_spanning_tree),
+    [Without degree constraint](https://en.wikipedia.org/wiki/Minimum_spanning_tree)
+
+    [Transformation](https://arxiv.org/abs/1302.5843)
+
+    Attributes
+    ----------
+    ### graph: Dict[int, Dict[int, Dict[str, float]]
+        \n Problem graph for the minimal spanning tree problem in form of nested
+        dictionaries. Each vertex needs to be weighted.
+        \n (e.g. Wikipedia example
+        \n _{
+            0: {1: {"weight": 1}, 3: {"weight": 4}, 4: {"weight": 3}},
+            1: {3: {"weight": 4}, 4: {"weight": 2}},
+            2: {4: {"weight": 4}, 5: {"weight": 5}},
+            3: {4: {"weight": 4}},
+            4: {5: {"weight": 7}}
+        }_ )
+
+    ### max_degree : int
+        \n The maximum degree at one joint of the tree. (e.g. 2 is a special case of the
+        travelling salesman problem).
+
+    ### A : Optional[float] = None.
+        \n The penalty factor for constraints. Can be left _None_ to be estimated from
+        the problem graph via the papers suggestion.
+        \n Default: _None_
+
+    ### B : Optional[float] = 1.
+        \n The optimization penalty factor.
+        \n Deafult: _1_
+
+    ### ba_ratio : Optional[float] = 0.1
+        \n A factor that increases or decreases the ratio between constraint and
+        model penalty factors in the automatic estimation. If constraints are
+        violated, this ratio needs to be decreased as the _A_ penalty needs to be
+        increased. _0.1_ is a good starting point.
+        \n Default: _0.1_
+    """
+
+    name: Literal["MST"] = "MST"
+    graph: NestedDictGraph = Field(name="graph")  # type: ignore[call-overload]
+    max_degree: int
+    A: float | None = None
+    B: float | None = 1.0
+    ba_ratio: float | None = 0.1

luna_quantum/solve/use_cases/minimum_vertex_cover.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class MinimumVertexCover(UseCase):
+    r"""
+    # Minimum Vertex Cover.
+
+    Description
+    -----------
+
+    A vertex cover of an undirected graph is a set of vertices that includes at least
+    one endpoint of every edge of this graph. The Minimum Vertex Cover problem tries to
+    find the smallest vertex cover in a given graph. The smallest vertex cover is the
+    one that contains the least amount of nodes.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Vertex_cover)
+
+    [Transformation](https://arxiv.org/pdf/1811.11538.pdf)
+
+    Attributes
+    ----------
+    ### graph: Dict[int, Dict[int, Dict[str, float]]]
+        \n Problem graph for the minimum vertex cover 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))_ )
+
+    ### P: int
+        \n Positive, scalar penalty value to penalize edges that are not covered.
+        \n Default: _8_
+    """
+
+    name: Literal["MVC"] = "MVC"
+    graph: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]
+    P: int = 8

luna_quantum/solve/use_cases/number_partitioning.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class NumberPartitioning(UseCase):
+    r"""
+    # Number Partitioning.
+
+    Description
+    -----------
+
+    The Number Partitioning problem partitions a set of numbers into two subsets such
+    that the difference of the subset sums is minimized.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Partition_problem)
+
+    [Transformation](https://arxiv.org/pdf/1811.11538.pdf)
+
+    Attributes
+    ----------
+    ### numbers: List[int]
+        \n The set of numbers which has to be partitioned.
+    """
+
+    name: Literal["NP"] = "NP"
+    numbers: list[int]

luna_quantum/solve/use_cases/portfolio_optimization.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class PortfolioOptimization(UseCase):
+    r"""
+    # Portfolio Optimization.
+
+    Description
+    -----------
+
+    The Portfolio Optimization problem tries to find the optimal portfolio of assets
+    which achieves an equal or higher return than the target return with the lowest
+    risk possible. The optimal portfolio is defined by the binary choices whether to
+    invest in a specific asset or not.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Portfolio_optimization)
+
+    [Transformation](https://arxiv.org/pdf/2012.01121.pdf)
+
+    Attributes
+    ----------
+    ### returns: List[List[float]]
+        \n Returns matrix which contains time-series of returns per asset i.
+
+    ### R: float
+        \n Target for overall return of portfolio.
+
+    ### n: int
+        \n Number of wanted assets in set.
+
+    ### lambda0: int = 1
+        \n Default lagrange multiplier.
+    """
+
+    name: Literal["PO"] = "PO"
+    returns: list[list[float]]
+    R: float
+    n: int
+    lambda0: int = 1

luna_quantum/solve/use_cases/portfolio_optimization_ib_tv.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class PortfolioOptimizationInvestmentBandsTargetVolatility(UseCase):
+    r"""
+    # Portfolio Optimization with Investment Bands and Target Volatility.
+
+    Description
+    -----------
+
+    The Portfolio Optimization problem tries to find the optimal portfolio of assets
+    which achieves an equal or higher return than the target return with the lowest
+    risk possible. The optimal portfolio is defined by the binary choices whether to
+    invest in a specific asset or not.
+
+    This special case of portfolio optimization handles to additional constraints. On
+    the one hand, it tries to find optimal investment portfolios with a fixed
+    volatility. On the other hand, it imposes investment bands in the computed
+    portfolios, i.e. the investment for each asset is between a minimum and a maximum.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Portfolio_optimization)
+
+    [Transformation](https://arxiv.org/pdf/2106.06735.pdf)
+
+    Attributes
+    ----------
+    ### log_returns: List[float]
+        \n Log return of each asset.
+
+    ### sigma: List[List[float]]
+        \n Risk matrix.
+
+    ### investment_bands: List[Tuple[float, float]]
+        \n Investment bands for each asset.
+
+    ### target_volatility: float
+        \n Target volatility of portfolio.
+
+    ### max_budget: int
+        \n Maximum budget.
+
+    ### budget_weight: float
+        \n Budget penalty factor.
+
+    ### volatility_weight: float
+        \n Volatility penalty factor.
+    """
+
+    name: Literal["POIBTV"] = "POIBTV"
+    log_returns: list[float]
+    sigma: list[list[float]]
+    investment_bands: list[tuple[float, float]]
+    target_volatility: float
+    max_budget: int
+    budget_weight: float = 5.0
+    volatility_weight: float = 50.0

luna_quantum/solve/use_cases/quadratic_assignment.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class QuadraticAssignment(UseCase):
+    r"""
+    # Quadratic Assignment.
+
+    Description
+    -----------
+
+    There are a set of _n_ facilities and a set of _n_ locations. For each pair of
+    locations, a distance is specified and for each pair of facilities a weight or flow
+    is specified. The Quadratic Assignment problem assigns all facilities to different
+    locations with the goal of minimizing the sum of products of the distances and the
+    corresponding flows.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Quadratic_assignment_problem)
+
+    [Transformation](https://arxiv.org/pdf/1811.11538.pdf)
+
+    Attributes
+    ----------
+    ### flow_matrix: List[List]
+        \n A matrix denoting the flow (or weight) between the facilities.
+        \n e.g. for two facilities with a flow of 3, the flow_matrix will be
+        _[[0, 3], [3, 0]]_.
+
+    ### distance_matrix: List[List]
+        \n A matrix denoting the distance between the locations.
+        \n e.g. for two places with a distance of 8, the flow_matrix will be
+        _[[0, 8], [8, 0]]_.
+
+    ### P: int
+        \n Positive, scalar penalty value to penalize when a facility is mapped to two
+        different locations or vice versa.
+        \n Default: _200_
+    """
+
+    name: Literal["QA"] = "QA"
+    flow_matrix: list[list[float]]
+    distance_matrix: list[list[float]]
+    P: int = 200

luna_quantum/solve/use_cases/quadratic_knapsack.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class QuadraticKnapsack(UseCase):
+    r"""
+    # Quadratic Knapsack.
+
+    Description
+    -----------
+
+    Given an upper bound of budget and a set of potential projects, each having a
+    certain cost, a certain value, and value interactions with the other projects, the
+    Quadratic Knapsack problem selects the combination of projects with the highest
+    total value, without exceeding the budget restraint.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Quadratic_knapsack_problem)
+
+    [Transformation](https://arxiv.org/pdf/1811.11538.pdf)
+
+    Attributes
+    ----------
+    ### projects: List[List[float]]
+        \n A double nested list with entries _projects[i][j]_ corresponding to the value
+        gain of choosing both projects i and j at the same time.
+
+    ### costs: List[float]
+        \n The individual costs of each project.
+
+    ### budget: float
+        \n Budget restraint (upper bound) on projects.
+
+    ### P: int
+        \n The weight of the penalty term.
+        \n Default: _10_
+    """
+
+    name: Literal["QK"] = "QK"
+    projects: list[list[float]]
+    costs: list[float]
+    budget: float
+    P: float = 10

luna_quantum/solve/use_cases/satellite_scheduling.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class SatelliteScheduling(UseCase):
+    r"""
+    # Satellite Scheduling.
+
+    Description
+    -----------
+
+    We assume a satellite can occupy three states: charging (*c*), downlink (*d*) and
+    experiment (*e*). We discretize the time and assume time steps *t ∈ {0,1,...,T}*.
+    The variable *x_st* tells us if the satellite is in the state *s ∈ {c,d,e}* at time
+    *t*. With this, the time sequence of these variables represents the schedule we want
+    to optimize. The optimization goal is to record as much data as possible during the
+    mission. [1]
+
+    There are two satellite variables which may change over time: The charge of the
+    battery *C* and the data stored on the memory *D*. The rate with which these
+    variables are changing depending on state *s* are denoted by *c_s* and *d_s*
+    respectively. [1]
+
+    For example the experiment state will increase the data *dd > 0* and decrease the
+    charge *dc < 0*. Both the battery and the memory define an upper and lower limit
+    for  the charge and the data, respectively. Not every state can be occupied at each
+    instance in time. For example, the charging through solar panels is only possible
+    in sunlight, or the downlink is only possible in the vicinity of a ground station.
+    Therefore for each state s there is a subset of times `τ_s ⊆ {0,1,...,T}* at which
+    the satellite can occupy this state. To enforce this constraint, we remove all
+    variables *x_st ∈ {x_st |t ∈ τ_s}*. [1]
+
+    For the sake of simplicity, we assume that each state has minimum duration of *1*.
+
+    Links
+    -----
+
+    [Transformation (Experiences with Scheduling Problems on Adiabatic Quantum Computers)](https://elib.dlr.de/110044/1/43.pdf)
+
+    Attributes
+    ----------
+    ### T: int
+        \n T is the latest included time step. Note that the earliest included time step
+        is always *0*.
+
+    ### P: Tuple[int, int, int, int, int, int]
+        \n The penalties for each constraint.
+
+    ### Tau: List[List[int]]
+        \n Times to be removed for each state.
+
+    ### d: Dict
+        \n Dict describing downlink state which includes entries *rate*, *initial*,
+        *max*, *min*.
+
+    ### c: Dict
+        \n Dict describing charging state which includes entries *rate*, *initial*,
+        *max*, *min*.
+
+    ### S: int
+        \n *S* is the total number of possible states.
+    """
+
+    name: Literal["SSC"] = "SSC"
+    T: int
+    P: tuple[int, int, int, int, int, int]
+    Tau: list[list[int]]
+    d: dict[str, float]
+    c: dict[str, float]
+    S: int = 3