Skip to content

Arbitrage Edge-Based API Reference

Data

Data model for Arbitrage Edge-Based use case.

ArbitrageEdgeBasedData

Bases: UcData

Data for the Arbitrage Edge-Based use case.

Models a currency arbitrage problem as a directed weighted graph where nodes are currencies and edge weights are conversion rates. The goal is to find a cycle whose product of conversion rates exceeds 1.

Attributes:

  • name (Literal['arbitrage_edge_based']) –

    Identifier for this data type.

  • adjacency_matrix (NumPyArray) –

    Directed weighted graph of conversion rates. Shape [n_currencies x n_currencies]. Entry [i,j] is the rate to convert one unit of currency i into currency j. Zero means no direct edge.

  • node_names (list[str]) –

    Currency names.

plot(*, ax: Axes | None = None) -> Axes

Plot the currency exchange graph.

Parameters:

  • ax (Axes | None, default: None ) –

    Matplotlib axes to draw on. Creates a new figure if None.

Returns:

  • Axes –

    The axes with the plot.

to_string() -> str

Return a string describing the arbitrage edge-based data.

from_adjacency_matrix(adjacency_matrix: np.ndarray, node_names: list[str]) -> ArbitrageEdgeBasedData staticmethod

Create data from an adjacency matrix.

Parameters:

  • adjacency_matrix (ndarray) –

    Directed weighted graph of conversion rates.

  • node_names (list[str]) –

    Currency names.

Returns:

generate_random(n_currencies: int = 4, seed: int | None = None) -> ArbitrageEdgeBasedData staticmethod

Generate a random arbitrage instance with at least one profitable cycle.

Parameters:

  • n_currencies (int, default: 4 ) –

    Number of currencies (default: 4).

  • seed (int | None, default: None ) –

    Random seed for reproducibility (default: None).

Returns:

  • ArbitrageEdgeBasedData –

    A randomly generated data instance guaranteed to have at least one profitable arbitrage cycle.

Formulation

Formulation for Arbitrage Edge-Based use case.

ArbitrageEdgeBasedFormulation

Bases: UcFormulation[ArbitrageEdgeBasedData, ArbitrageEdgeBasedSolution]

Constraint-based formulation for edge-based currency arbitrage.

The problem finds a cycle in a directed currency exchange graph that maximises the sum of log-conversion-rates (equivalent to maximising the product of rates).

Mathematical Formulation

Decision Variables: y[i,j] in {0,1} -- directed edge (i,j) is in the cycle (only for non-zero entries in the adjacency matrix)

Objective (maximize): sum_{(i,j)} log(rate[i,j]) * y[i,j]

Constraints: 1. Flow conservation: sum_j y[v,j] == sum_j y[j,v] for each v 2. At most one outgoing per node: sum_j y[v,j] <= 1 3. Non-trivial cycle: sum_{i,j} y[i,j] >= 1

to_string(data: ArbitrageEdgeBasedData) -> str staticmethod

Format the formulation as a string.

Parameters:

Returns:

  • str –

    String representation of the formulation.

formulate(data: ArbitrageEdgeBasedData) -> Model staticmethod

Formulate edge-based arbitrage as an optimization model.

Parameters:

Returns:

  • Model –

    A Luna Model ready to be solved.

interpret(solution: Solution, data: ArbitrageEdgeBasedData) -> ArbitrageEdgeBasedSolution staticmethod

Extract solution from solver result.

Solution

Solution model for Arbitrage Edge-Based use case.

ArbitrageEdgeBasedSolution

Bases: UcSolution

Solution for the Arbitrage Edge-Based use case.

Attributes:

  • name (Literal['arbitrage_edge_based']) –

    Identifier for this solution type.

  • cycle_edges (list[tuple[str, str]]) –

    List of directed edges (from_currency, to_currency) forming the arbitrage cycle.

  • arbitrage_profit (float) –

    Product of conversion rates along the cycle. A value >1 indicates a profitable arbitrage.

  • is_valid (bool) –

    Whether the solution forms a valid cycle with flow conservation.

plot(data: ArbitrageEdgeBasedData | None = None, *, ax: Axes | None = None) -> Axes

Plot the arbitrage cycle on the currency exchange graph.

Cycle edges are drawn as directed arrows colored by profit (green for gain, red for loss) with percentage labels. The start node is visually distinguished.

Parameters:

  • data (ArbitrageEdgeBasedData | None, default: None ) –

    Problem data used to reconstruct the graph layout. Required — a ValueError is raised when None.

  • ax (Axes | None, default: None ) –

    Matplotlib axes to draw on. Creates a new figure if None.

Returns:

  • Axes –

    The axes with the plot.

Raises:

to_string() -> str

Return a string describing the arbitrage edge-based solution.

Instance

Instance model for ArbitrageEdgeBased use case.

ArbitrageEdgeBasedInstance

Bases: UcInstance[ArbitrageEdgeBasedData, ArbitrageEdgeBasedFormulation, ArbitrageEdgeBasedSolution]

Instance combining data and formulation for ArbitrageEdgeBased.

Collection

Collection of Arbitrage Edge-Based instances.

ArbitrageEdgeBasedCollection

Bases: UcInstanceCollection[ArbitrageEdgeBasedInstance]

Collection of Arbitrage Edge-Based instances.

This collection provides methods to generate benchmark instances with various characteristics for testing and evaluation.

from_random(min_currencies: int = 3, max_currencies: int = 6, num_instances: int = 1, *, seed: int | None = None) -> ArbitrageEdgeBasedCollection classmethod

Generate random Arbitrage Edge-Based instances.

Parameters:

  • min_currencies (int, default: 3 ) –

    Minimum number of currencies per instance (default: 3).

  • max_currencies (int, default: 6 ) –

    Maximum number of currencies per instance (default: 6).

  • num_instances (int, default: 1 ) –

    Number of instances per currency count (default: 1).

  • seed (int | None, default: None ) –

    Random seed for reproducibility (default: None).

Returns: