luna-quantum 1.0.8rc2__cp314-cp314-macosx_11_0_arm64.whl

luna_quantum/solve/parameters/mixins/fujitsu_common_params_mixin.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class FujitsuCommonParamsMixin(BaseModel):
+    """
+    Common parameters used across various quantum and classical optimization solvers.
+
+    This class encapsulates parameters for auto-tuning, scaling, and general
+    configuration options that are applicable to multiple solver types. It provides a
+    consistent interface for these common settings to simplify configuration and
+    enhance reusability.
+
+    Attributes
+    ----------
+    auto_tuning: Literal["NOTHING", "SCALING", "AUTO_SCALING", "SAMPLING",
+                        "AUTO_SCALING_AND_SAMPLING", "SCALING_AND_SAMPLING"]
+        Controls automatic parameter adjustment strategies:
+        - "NOTHING": No auto-tuning (use parameters exactly as specified)
+        - "SCALING": Apply scaling_factor to model coefficients and parameters
+        - "AUTO_SCALING": Automatically determine optimal scaling factor based on bit
+        precision
+        - "SAMPLING": Automatically determine temperature parameters through sampling
+        - "AUTO_SCALING_AND_SAMPLING": Combine auto-scaling and sampling
+        - "SCALING_AND_SAMPLING": Apply explicit scaling and determine temperatures
+        Default is "NOTHING", giving full control to the user.
+    scaling_factor: Union[int, float]
+        Multiplicative factor applied to model coefficients, temperatures, and other
+        parameters.
+        Higher values can improve numerical precision but may lead to overflow.
+        Default is 1.0 (no scaling).
+    scaling_bit_precision: int
+        Maximum bit precision to use when scaling. Determines the maximum allowable
+        coefficient magnitude. Default is 64, using full double precision.
+    guidance_config: Union[PartialConfig, None]
+        Optional configuration for guiding the optimization process with prior
+        knowledge. Can specify initial values or constraints for variables. Default is
+        None.
+    random_seed: Union[int, None]
+        Seed for random number generation to ensure reproducible results.
+        Must be between 0 and 9,999. Default is None (random seed).
+    timeseries_max_bits: Union[int, None]
+        Maximum number of bits to use for timeseries representation.
+        Limits memory usage for large problems. Default is None (no limit).
+    solver_max_bits: int
+        Maximum problem size (in bits/variables) that the solver can handle.
+        Default is 2¹³ (8,192), suitable for most solvers.
+    var_shape_set: Optional[VarShapeSet]
+        This parameter should be an object of :class:`VarShapeSet` or ``None``
+    auto_fill_cold_bits: Optional[bool]
+        In case ``var_shape_set`` is defined and contains a 1-hot group,
+        and a hot bit is set to ``True`` and this parameter is also set to ``True``,
+        then all related cold bits are set to ``False``. Default is ``True``
+    """
+
+    class BitArrayShape(BaseModel):
+        """BitArrayShape.
+
+        An object of the class :class:`BitArrayShape` represents an array structure as
+        part of a bit vector. It allows multidimensional indexed access to the bit
+        variables of a :class:`BinPol` polynomial. :class:`BitArrayShape` objects are
+        used inside :class:`VarShapeSet` objects, which organize index data of a
+        complete bit vector for a polynomial. Bit variables of such polynomials can
+        then be accessed by name and indices according to the shape specified in the
+        :class:`BitArrayShape` object.
+
+        Parameters
+        ----------
+        shape: List[int]
+            shape of the index; specify the length of each dimension
+        constant_bits: Optional[NDArray]
+            numpy array of type int8 with same shape as the previous parameter
+            containing 0 and 1 for constant bits and -1 variable bits
+        one_hot: OneHot
+            define variable as one_hot section
+        axis_names: Optional[List[str]]
+            Names for the axis.
+        index_offsets: Optional[List[int]]
+            index_offsets of the index, specify the index_offsets of each dimension
+        """
+
+        type: Literal["BitArrayShape"] = "BitArrayShape"
+        axis_names: list[str] | None = None
+        index_offsets: list[int] | None = None
+        name: str
+        one_hot: Literal["no_way", "one_way", "two_way"] = "no_way"
+
+    class Category(BaseModel):
+        """Category.
+
+        An object of the class :class:`Category` represents an array structure as part
+        of a bit vector. It allows indexed access to the bit variables of a
+        :class:`BinPol` polynomial. :class:`Category`
+        objects are used inside :class:`VarShapeSet` objects, which organize index data
+        of a complete bit vector for a polynomial. Bit variables of such polynomials
+        can then be accessed by ``name`` and categorical indices according to the
+        ``values`` specified in the :class:`BitArrayShape` object. A categorical index
+        can be any sequence of unique values.
+
+        Parameters
+        ----------
+        name: str
+            name of the new index
+        values: List[Any]
+            list of unique values for this category
+        one_hot: OneHot
+            define variable as one_hot section
+        axis_names: List[str]
+            Names for the axis.
+        """
+
+        type: Literal["Category"] = "Category"
+        values: list[Any] = Field(default_factory=list)
+        axis_names: list[str] | None = None
+        name: str
+        one_hot: Literal["no_way", "one_way", "two_way"] = "no_way"
+
+    class Variable(BaseModel):
+        """Variable.
+
+        A ``Variable`` is a binary polynomial, that represents a numerical value
+        according to values of the underlying bits. The variable is defined by a value
+        range and a specific representation scheme that is realized in respective
+        inherited classes.
+
+        Parameters
+        ----------
+        name: str
+            name of the variable
+        start: float
+            first number in the list of values to be represented by the variable
+        stop: float
+            stop value for the list of numbers to be represented by the variable; stop
+            is omitted
+        step: float
+            increment for the list of numbers to be represented by the variable
+        shape: List[int]
+            shape of the index; specify the length of each dimension
+        constant_bits: Optional[NDArray]
+            numpy array of type int8 with same shape as the previous parameter
+            containing 0 and 1 for constant bits and -1 variable bits
+        one_hot: OneHot
+            define variable as one_hot section
+        """
+
+        type: Literal["Variable"] = "Variable"
+        start: float
+        stop: float
+        step: float
+
+        shape: list[int] | None = None
+        constant_bits: list[int] | None = None
+
+        name: str
+        one_hot: Literal["no_way", "one_way", "two_way"] = "no_way"
+
+    class VarShapeSet(BaseModel):
+        """VarShapeSet.
+
+        :class:`dadk.BinPol.VarShapeSet` defines an indexing structure for the bits of
+        a BinPol polynomial. Plain BinPol polynomials are defined on a set of bits
+        indexed by a ``range(N)`` for some integer ``N``. The ``VarShapeSet`` lays
+        a sequence of disjoint named sections over this linear structure. Bits within a
+        section can be addressed by the defined name. With a ``BitArrayShape`` a
+        section can be defined as multidimensional array and single bits in the section
+        can be addressed by an appropriate tuple of indices. With a ``Variable``
+        definition the section represents a number encoded in certain bit schemes; in
+        this case it is possible to retrieve the represented value instead of reading
+        single bits.
+
+        Parameters
+        ----------
+        var_defs: Union[BitArrayShape, Variable, Category]
+            one or more section definitions of type :class:`BitArrayShape`,
+            :class:`Variable` or :class:`Category`
+        one_hot_groups: Optional[List[OneHotGroup]]
+            optional list of special one_hot group definitions
+        """
+
+        var_defs: list[
+            Annotated[
+                FujitsuCommonParamsMixin.BitArrayShape
+                | FujitsuCommonParamsMixin.Variable
+                | FujitsuCommonParamsMixin.Category,
+                Field(discriminator="type"),
+            ]
+        ] = Field(default_factory=list)
+        one_hot_groups: list[Literal["no_way", "one_way", "two_way"]] | None = None
+
+    class PartialConfig:
+        """Produces a dict that can be used for the annealing algorithm.
+
+        The start state for an annealing or parallel tempering model can be specified.
+        The used dictionary addresses bits with their flattened index. With the class
+        :class:`PartialConfig` those bits can be specified on the symbolic level of
+        :class:`BitArrayShape` or :class:`Variable` and the offsets in a
+        :class:`VarShapeSet` are calculated automatically. Flat indices can be used
+        directly, if they are known. For variables, indices are used directly and do
+        not need to be adjusted by a global index consideration from the
+        :class:`VarShapeSet`. After setting the start state accordingly, a string can
+        be created with the method ``as_json``. If one_hot or two_hot specifications
+        are given in :class:`VarShapeSet`, the dictionary generated in the methods
+        ``get_dict`` or ``as_json`` is build up with respect to the set bit variables
+        and one-way or two-way rules.
+
+        The object is initialized by a :class:`VarShapeSet` object or None.
+        An initialization with None can be used for :class:`BinPol`.
+
+        Parameters
+        ----------
+        var_shape_set: Optional[VarShapeSet]
+            This parameter should be an object of :class:`VarShapeSet` or ``None``
+        auto_fill_cold_bits: bool
+            In case ``var_shape_set`` is defined and contains a 1-hot group,
+            and a hot bit is set to ``True`` and this parameter is also set to ``True``,
+            then all related cold bits are set to ``False``. Default is ``True``
+        """
+
+        var_shape_set: FujitsuCommonParamsMixin.VarShapeSet | None = None
+        auto_fill_cold_bits: bool = True
+
+    auto_tuning: Literal[
+        "NOTHING",
+        "SCALING",
+        "AUTO_SCALING",
+        "SAMPLING",
+        "AUTO_SCALING_AND_SAMPLING",
+        "SCALING_AND_SAMPLING",
+    ] = "NOTHING"
+    scaling_factor: int | float = 1.0
+    scaling_bit_precision: int = 64
+    random_seed: int | None = Field(default=None, ge=0, le=9_999)
+    timeseries_max_bits: int | None = None
+    solver_max_bits: int = 2**13
+    var_shape_set: VarShapeSet | None = None
+    auto_fill_cold_bits: bool | None = True

luna_quantum/solve/parameters/mixins/fujitsu_v2_mixin.py

@@ -0,0 +1,70 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class FujitsuV2Mixin(BaseModel):
+    """
+    FujitsuV2Mixin.
+
+    Parameters for V2 optimization algorithms, particularly relevant for
+    Digital Annealer implementations.
+
+    This class defines parameters controlling the annealing process, temperature
+    scheduling, and solution mode for V2 solvers. These parameters impact how
+    the algorithm traverses the energy landscape and converges to solutions.
+
+    Attributes
+    ----------
+    optimization_method: Literal["annealing", "parallel_tempering"]
+        Algorithm to use for optimization:
+        - "annealing": Standard simulated annealing with gradual cooling
+        - "parallel_tempering": Simultaneous runs at different temperatures with
+          periodic state exchanges, effective for complex energy landscapes
+        Default is "annealing".
+    temperature_start: float
+        Initial temperature for the annealing process. Higher values enable more
+        exploration initially. Default is 1000.0. Range: [0.0, 1e20].
+    temperature_end: float
+        Final temperature for the annealing process. Lower values enforce more
+        exploitation in final phases. Default is 1.0. Range: [0.0, 1e20].
+    temperature_mode: int
+        Cooling curve mode for temperature decay:
+        - 0: Exponential cooling - reduce by factor at fixed intervals
+        - 1: Inverse cooling - faster initial cooling, slower later
+        - 2: Inverse root cooling - another non-linear cooling schedule
+        Default is 0 (exponential).
+    temperature_interval: int
+        Number of iterations between temperature adjustments. Larger values
+        allow more exploration at each temperature. Default is 100. Range: [1, 1e20].
+    offset_increase_rate: float
+        Rate at which dynamic offset increases when no bit is selected.
+        Helps escape plateaus in the energy landscape. Default is 5.0.
+        Range: [0.0, 1e20].
+    solution_mode: Literal["QUICK", "COMPLETE"]
+        Determines solution reporting strategy:
+        - "QUICK": Return only the overall best solution (faster)
+        - "COMPLETE": Return best solutions from all runs (more diverse)
+        Default is "COMPLETE", providing more solution options.
+    flip_probabilities: Tuple[float, float]
+        Probabilities used for determining temperature parameters.
+        First value is probability of accepting worse solutions at start temperature,
+        second value is probability at end temperature. Default is (0.99, 0.01).
+    annealing_steps: Tuple[float, float]
+        Portion of annealing trajectory where end_progress_probability is reached.
+        Controls the annealing schedule shape. Default is (0.0, 0.5).
+    sampling_runs: int
+        Number of random walkers used for energy delta determination during
+        parameter estimation sampling. Default is 100.
+    """
+
+    optimization_method: Literal["annealing", "parallel_tempering"] = "annealing"
+    temperature_start: float = Field(default=1_000.0, ge=0.0, le=1e20)
+    temperature_end: float = Field(default=1.0, ge=0.0, le=1e20)
+    temperature_mode: int = 0
+    temperature_interval: int = Field(default=100, ge=1, le=int(1e20))
+    offset_increase_rate: float = Field(default=5.0, ge=0.0, le=1e20)
+    solution_mode: Literal["QUICK", "COMPLETE"] = "COMPLETE"
+    flip_probabilities: tuple[float, float] = 0.99, 0.01
+    annealing_steps: tuple[float, float] = 0.0, 0.5
+    sampling_runs: int = 100

luna_quantum/solve/parameters/mixins/qbsolv_like_mixin.py

@@ -0,0 +1,60 @@
+from pydantic import BaseModel
+
+from luna_quantum.solve.parameters.constants import DEFAULT_ATOL, DEFAULT_RTOL
+
+
+class QBSolvLikeMixin(BaseModel):
+    """
+    QBSolvLikeMixin.
+
+    Attributes
+    ----------
+    decomposer_size: int
+        Size for the decomposer, which determines the maximum subproblem size to be
+        handled in each iteration. Larger values may produce better solutions but
+        increase computational complexity exponentially. Default is 50, which balances
+        solution quality with reasonable runtime.
+    rolling: bool
+        Whether to use rolling window decomposition for the solver. When enabled,
+        this allows for overlapping subproblems with shared variables, which can
+        improve solution quality by better handling interactions across subproblem
+        boundaries. Default is True.
+    rolling_history: float
+        Rolling history factor controlling how much of previous subproblem solutions
+        are considered when solving subsequent subproblems. Higher values incorporate
+        more historical information but may slow convergence to new solutions.
+        Default is 0.15 (15% retention).
+    max_iter: int | None
+        Maximum number of iterations (decomposition and solving cycles) to perform.
+        Higher values allow for more thorough optimization but increase runtime.
+        Default is 100.
+    max_time: int
+        Time in seconds after which the algorithm will stop, regardless of convergence
+        status. Provides a hard time limit for time-constrained applications.
+        Default is 5.
+    convergence: int
+        Number of iterations with unchanged output to terminate algorithm. Higher values
+        ensure more stable solutions but may increase computation time unnecessarily
+        if the algorithm has already found the best solution. Default is 3.
+    target: float | None
+        Energy level that the algorithm tries to reach. If this target energy is
+        achieved, the algorithm will terminate early. Default is None, meaning the
+        algorithm will run until other stopping criteria are met.
+    rtol: float
+        Relative tolerance for convergence. Used when comparing energy values between
+        iterations to determine if significant improvement has occurred. Default uses
+        DEFAULT_RTOL.
+    atol: float
+        Absolute tolerance for convergence. Used alongside rtol when comparing energy
+        values to determine if the algorithm has converged. Default uses DEFAULT_ATOL.
+    """
+
+    decomposer_size: int = 50
+    rolling: bool = True
+    rolling_history: float = 0.15
+    max_iter: int | None = 100
+    max_time: int = 5
+    convergence: int = 3
+    target: float | None = None
+    rtol: float = DEFAULT_RTOL
+    atol: float = DEFAULT_ATOL

luna_quantum/solve/use_cases/__init__.py

@@ -0,0 +1,119 @@
+from luna_quantum.solve.use_cases.arbitrage_edge_based import ArbitrageEdgeBased
+from luna_quantum.solve.use_cases.arbitrage_node_based import ArbitrageNodeBased
+from luna_quantum.solve.use_cases.base import UseCase
+from luna_quantum.solve.use_cases.binary_integer_linear_programming import (
+    BinaryIntegerLinearProgramming,
+)
+from luna_quantum.solve.use_cases.binary_paint_shop_problem import (
+    BinaryPaintShopProblem,
+)
+from luna_quantum.solve.use_cases.credit_scoring_feature_selection import (
+    CreditScoringFeatureSelection,
+)
+from luna_quantum.solve.use_cases.dynamic_portfolio_optimization import (
+    DynamicPortfolioOptimization,
+)
+from luna_quantum.solve.use_cases.exact_cover import ExactCover
+from luna_quantum.solve.use_cases.flight_gate_assignment import FlightGateAssignment
+from luna_quantum.solve.use_cases.graph_coloring import GraphColoring
+from luna_quantum.solve.use_cases.graph_isomorphism import GraphIsomorphism
+from luna_quantum.solve.use_cases.graph_partitioning import GraphPartitioning
+from luna_quantum.solve.use_cases.hamiltonian_cycle import HamiltonianCycle
+from luna_quantum.solve.use_cases.induced_subgraph_isomorphism import (
+    InducedSubGraphIsomorphism,
+)
+from luna_quantum.solve.use_cases.job_shop_scheduling import JobShopScheduling
+from luna_quantum.solve.use_cases.k_medoids_clustering import KMedoidsClustering
+from luna_quantum.solve.use_cases.knapsack_integer_weights import KnapsackIntegerWeights
+from luna_quantum.solve.use_cases.linear_regression import LinearRegression
+from luna_quantum.solve.use_cases.lmwcs import LabeledMaxWeightedCommonSubgraph
+from luna_quantum.solve.use_cases.longest_path import LongestPath
+from luna_quantum.solve.use_cases.market_graph_clustering import MarketGraphClustering
+from luna_quantum.solve.use_cases.max2sat import Max2SAT
+from luna_quantum.solve.use_cases.max3sat import Max3SAT
+from luna_quantum.solve.use_cases.max_clique import MaxClique
+from luna_quantum.solve.use_cases.max_cut import MaxCut
+from luna_quantum.solve.use_cases.max_independent_set import MaxIndependentSet
+from luna_quantum.solve.use_cases.minimal_maximal_matching import MinimalMaximalMatching
+from luna_quantum.solve.use_cases.minimal_spanning_tree import MinimalSpanningTree
+from luna_quantum.solve.use_cases.minimum_vertex_cover import MinimumVertexCover
+from luna_quantum.solve.use_cases.number_partitioning import NumberPartitioning
+from luna_quantum.solve.use_cases.portfolio_optimization import PortfolioOptimization
+from luna_quantum.solve.use_cases.portfolio_optimization_ib_tv import (
+    PortfolioOptimizationInvestmentBandsTargetVolatility,
+)
+from luna_quantum.solve.use_cases.quadratic_assignment import QuadraticAssignment
+from luna_quantum.solve.use_cases.quadratic_knapsack import QuadraticKnapsack
+from luna_quantum.solve.use_cases.satellite_scheduling import SatelliteScheduling
+from luna_quantum.solve.use_cases.sensor_placement import SensorPlacement
+from luna_quantum.solve.use_cases.set_cover import SetCover
+from luna_quantum.solve.use_cases.set_packing import SetPacking
+from luna_quantum.solve.use_cases.set_partitioning import SetPartitioning
+from luna_quantum.solve.use_cases.subgraph_isomorphism import SubGraphIsomorphism
+from luna_quantum.solve.use_cases.subset_sum import SubsetSum
+from luna_quantum.solve.use_cases.support_vector_machine import SupportVectorMachine
+from luna_quantum.solve.use_cases.traffic_flow import TrafficFlow
+from luna_quantum.solve.use_cases.travelling_salesman_problem import (
+    TravellingSalesmanProblem,
+)
+from luna_quantum.solve.use_cases.type_aliases import (
+    CalculusLiteral,
+    Clause,
+    NestedDictGraph,
+    NestedDictIntGraph,
+    Node,
+)
+from luna_quantum.solve.use_cases.weighted_max_cut import WeightedMaxCut
+
+__all__ = [
+    "ArbitrageEdgeBased",
+    "ArbitrageNodeBased",
+    "BinaryIntegerLinearProgramming",
+    "BinaryPaintShopProblem",
+    "CalculusLiteral",
+    "Clause",
+    "CreditScoringFeatureSelection",
+    "DynamicPortfolioOptimization",
+    "ExactCover",
+    "FlightGateAssignment",
+    "GraphColoring",
+    "GraphIsomorphism",
+    "GraphPartitioning",
+    "HamiltonianCycle",
+    "InducedSubGraphIsomorphism",
+    "JobShopScheduling",
+    "KMedoidsClustering",
+    "KnapsackIntegerWeights",
+    "LabeledMaxWeightedCommonSubgraph",
+    "LinearRegression",
+    "LongestPath",
+    "MarketGraphClustering",
+    "Max2SAT",
+    "Max3SAT",
+    "MaxClique",
+    "MaxCut",
+    "MaxIndependentSet",
+    "MinimalMaximalMatching",
+    "MinimalSpanningTree",
+    "MinimumVertexCover",
+    "NestedDictGraph",
+    "NestedDictIntGraph",
+    "Node",
+    "NumberPartitioning",
+    "PortfolioOptimization",
+    "PortfolioOptimizationInvestmentBandsTargetVolatility",
+    "QuadraticAssignment",
+    "QuadraticKnapsack",
+    "SatelliteScheduling",
+    "SensorPlacement",
+    "SetCover",
+    "SetPacking",
+    "SetPartitioning",
+    "SubGraphIsomorphism",
+    "SubsetSum",
+    "SupportVectorMachine",
+    "TrafficFlow",
+    "TravellingSalesmanProblem",
+    "UseCase",
+    "WeightedMaxCut",
+]

luna_quantum/solve/use_cases/arbitrage_edge_based.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 ArbitrageEdgeBased(UseCase):
+    r"""
+    # Arbitrage Edge Based.
+
+    Description
+    -----------
+
+    In economics and finance, arbitrage is the practice of taking advantage of a
+    difference in prices in two or more markets; striking a combination of matching
+    deals to capitalize on the difference.
+    The edge based Arbitrage problem tries to find the best cycle in a directed and
+    complete graph. In this graph, each node corresponds to an asset and each directed
+    edge is weighted with the corresponding conversion rate. It creates a QUBO with the
+    size _n_edges x n_edges_, which produces a solution vector where each binary
+    position maps to an edge.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Arbitrage)
+
+    [Transformation](http://1qbit.com/files/white-papers/1QBit-White-Paper-%E2%80%93-Finding-Optimal-Arbitrage-Opportunities-Using-a-Quantum-Annealer.pdf)
+
+    Attributes
+    ----------
+    ### graph: Dict[str, Dict[str, Dict[str, float]]]
+        \n The input graph as described above in the form of nested dictionaries.
+        \n Example for three different currencies:
+        \n _{_
+        \n     _0: {1: {'weight': 1.31904}, 2: {'weight': 6.72585}},_
+        \n     _1: {0: {'weight': 0.75799}, 2: {'weight': 5.10327},_
+        \n     _2: {0: {'weight': 0.14864}, 1: {'weight': 0.19586}}_
+        \n _}_
+
+    ### penalty: Optional[float] = None
+        \n The penalty term for the QUBO matrix. Has to be greater than 0.
+    """
+
+    name: Literal["AEB"] = "AEB"
+    graph: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]
+    penalty: float | None = None

luna_quantum/solve/use_cases/arbitrage_node_based.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class ArbitrageNodeBased(UseCase):
+    r"""
+    # Arbitrage Node Based.
+
+    Description
+    -----------
+
+    In economics and finance, arbitrage is the practice of taking advantage of a
+    difference in prices in two or more markets; striking a combination of matching
+    deals to capitalize on the difference.
+    The node based Arbitrage problem tries to find the best cycle in a directed and
+    complete graph. In this graph, each node corresponds to an asset and each directed
+    edge is weighted with the corresponding conversion rate.
+    The problem creates a QUBO with the size
+    _(n_nodes * cycle_length) x (n_nodes * cycle_length)_, which produces a solution
+    vector where each binary position maps to to a node and its position in the cycle.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Arbitrage)
+
+    [Transformation](http://1qbit.com/files/white-papers/1QBit-White-Paper-%E2%80%93-Finding-Optimal-Arbitrage-Opportunities-Using-a-Quantum-Annealer.pdf)
+
+    Attributes
+    ----------
+    ### graph: Dict[str, Dict[str, Dict[str, float]]]
+        \n The input graph as described above in the form of nested dictionaries.
+        \n Example for three different currencies:\n
+        \n _{_
+        \n     _0: {1: {'weight': 1.31904}, 2: {'weight': 6.72585}},_
+        \n     _1: {0: {'weight': 0.75799}, 2: {'weight': 5.10327},_
+        \n     _2: {0: {'weight': 0.14864}, 1: {'weight': 0.19586}}_
+        \n _}_
+
+    ### penalty: Optional[float] = None
+        \n The penalty term for the QUBO matrix. Has to be greater than 0.
+
+    ### K: Optional[int] = None
+        \n The maximum length of the arbitrage cycle.
+    """
+
+    name: Literal["ANB"] = "ANB"
+    graph: dict[str, dict[str, dict[str, float]]] = Field(name="graph")  # type: ignore[call-overload]
+    penalty: float | None = None
+    K: int | None = None

luna_quantum/solve/use_cases/base.py

@@ -0,0 +1,7 @@
+from luna_quantum.util.pretty_base import PrettyBase
+
+
+class UseCase(PrettyBase):
+    """Base class for all UseCases."""
+
+    name: str

luna_quantum/solve/use_cases/binary_integer_linear_programming.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from luna_quantum.solve.use_cases.base import UseCase
+
+
+class BinaryIntegerLinearProgramming(UseCase):
+    r"""
+    # Binary Integer Linear Programming.
+
+    Description
+    -----------
+
+    For a binary decision vector _x_ and some vector _c_ of length _N_, the Binary
+    Integer Linear Programming problem maximizes _c * x_, given the constraint _Sx = b_
+    with _S_ being an _m x N_ matrix and _b_ a vector with _m_ components.
+
+    Q-Bit Interpretation
+    --------------------
+
+    The vector of qubits is simply the decision vector _x_.
+
+    Links
+    -----
+
+    [Wikipedia](https://en.wikipedia.org/wiki/Integer_programming)
+
+    [Transformation](https://arxiv.org/pdf/1302.5843.pdf)
+
+    Attributes
+    ----------
+    ### S: List[List[int]]
+        \n The _m x N_ matrix.
+
+    ### b: List[int]
+        \n Vector with _m_ components.
+
+    ### c: List[int]
+        \n Custom vector of length _N_.
+
+    ### A: int
+        \n A constant enforcing, if possible, that _Sx = b_.
+
+    ### B: int
+        \n A constant (_B << A_) helping maximize _c * x_.
+    """
+
+    name: Literal["BIP"] = "BIP"
+    S: list[list[int]]
+    b: list[int]
+    c: list[int]
+    A: int = 10
+    B: int = 2