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 Type Description
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:

Name Type Description Default
ax Axes | None

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

 None

Returns:

Type Description
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:

Name Type Description Default
adjacency_matrix ndarray

Directed weighted graph of conversion rates.

 required
node_names list[str]

Currency names.

 required

Returns:

Type Description
ArbitrageEdgeBasedData

The data instance.

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

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

Parameters:

Name Type Description Default
n_currencies int

Number of currencies (default: 4).

 4
seed int | None

Random seed for reproducibility (default: None).

 None

Returns:

Type Description
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:

Name Type Description Default
data ArbitrageEdgeBasedData

The problem data.

 required

Returns:

Type Description
str

String representation of the formulation.

formulate(data: ArbitrageEdgeBasedData) -> Model staticmethod

Formulate edge-based arbitrage as an optimization model.

Parameters:

Name Type Description Default
data ArbitrageEdgeBasedData

The problem data.

 required

Returns:

Type Description
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 Type Description
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:

Name Type Description Default
data ArbitrageEdgeBasedData | None

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

 None
ax Axes | None

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

 None

Returns:

Type Description
Axes

The axes with the plot.

Raises:

Type Description
ValueError

If data is None.

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:

Name Type Description Default
min_currencies int

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

 3
max_currencies int

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

 6
num_instances int

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

 1
seed int | None

Random seed for reproducibility (default: None).

 None

Returns:

Type Description
ArbitrageEdgeBasedCollection

Collection containing generated instances.