Skip to content

Arbitrage Node-Based API Reference

Data

Data model for Arbitrage Node-Based use case.

ArbitrageNodeBasedData

Bases: UcData

Data for the Arbitrage Node-Based use case.

Models a currency arbitrage problem using a position-based (node-based) assignment formulation. Each currency can be placed at a position in a fixed-length cycle, and the objective is to find the most profitable cycle of at most max_cycle_length steps.

Attributes:

  • name (Literal['arbitrage_node_based']) –

    Identifier for this data type.

  • adjacency_matrix (NumPyArray) –

    Directed weighted graph of conversion rates. Shape [n_currencies x n_currencies].

  • node_names (list[str]) –

    Currency names.

  • max_cycle_length (int) –

    Maximum number of positions in the cycle.

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 node-based data.

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

Create data from an adjacency matrix.

Parameters:

  • adjacency_matrix (ndarray) –

    Directed weighted graph of conversion rates.

  • node_names (list[str]) –

    Currency names.

  • max_cycle_length (int) –

    Maximum number of positions in the cycle.

Returns:

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

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

Parameters:

  • n_currencies (int, default: 4 ) –

    Number of currencies (default: 4).

  • max_cycle_length (int, default: 4 ) –

    Maximum cycle length (default: 4).

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

    Random seed for reproducibility (default: None).

Returns:

  • ArbitrageNodeBasedData –

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

Formulation

Formulation for Arbitrage Node-Based use case.

ArbitrageNodeBasedFormulation

Bases: UcFormulation[ArbitrageNodeBasedData, ArbitrageNodeBasedSolution]

Constraint-based formulation for node-based currency arbitrage.

Uses a position-assignment formulation where binary variable x[i,p] indicates that currency i is placed at position p in the cycle. The cycle length is exactly max_cycle_length.

Mathematical Formulation

Decision Variables: x[i,p] in {0,1} -- node i at position p (n_nodes * K)

Objective (maximize): sum_p sum_{i,j where rate>0} log(rate[i,j]) * x[i,p] * x[j,(p+1)%K]

Constraints: 1. Each position exactly one node: sum_i x[i,p] == 1 2. Each node at most one position: sum_p x[i,p] <= 1 3. Consecutive connected: for non-edges: x[i,p] + x[j,(p+1)%K] <= 1

to_string(data: ArbitrageNodeBasedData) -> str staticmethod

Format the formulation as a string.

formulate(data: ArbitrageNodeBasedData) -> Model staticmethod

Formulate node-based arbitrage as an optimization model.

Parameters:

Returns:

  • Model –

    A Luna Model ready to be solved.

interpret(solution: Solution, data: ArbitrageNodeBasedData) -> ArbitrageNodeBasedSolution staticmethod

Extract solution from solver result.

Solution

Solution model for Arbitrage Node-Based use case.

ArbitrageNodeBasedSolution

Bases: UcSolution

Solution for the Arbitrage Node-Based use case.

Attributes:

  • name (Literal['arbitrage_node_based']) –

    Identifier for this solution type.

  • cycle_nodes (list[str]) –

    Ordered list of currency names in the arbitrage cycle.

  • arbitrage_profit (float) –

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

  • trade_rates (list[float]) –

    Exchange rate for each consecutive trade in the cycle.

  • is_valid (bool) –

    Whether the solution forms a valid cycle with positive profit.

plot(data: ArbitrageNodeBasedData | 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 (ArbitrageNodeBasedData | 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 node-based solution.

Instance

Instance model for ArbitrageNodeBased use case.

ArbitrageNodeBasedInstance

Bases: UcInstance[ArbitrageNodeBasedData, ArbitrageNodeBasedFormulation, ArbitrageNodeBasedSolution]

Instance combining data and formulation for ArbitrageNodeBased.

Collection

Collection of Arbitrage Node-Based instances.

ArbitrageNodeBasedCollection

Bases: UcInstanceCollection[ArbitrageNodeBasedInstance]

Collection of Arbitrage Node-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, max_cycle_length: int = 4, num_instances: int = 1, *, seed: int | None = None) -> ArbitrageNodeBasedCollection classmethod

Generate random Arbitrage Node-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).

  • max_cycle_length (int, default: 4 ) –

    Maximum cycle length (default: 4).

  • 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: