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 | Type | Description |
|---|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
ax
|
Axes | None
|
Matplotlib axes to draw on. Creates a new figure if |
None
|
Returns:
| Type | Description |
|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
adjacency_matrix
|
ndarray
|
Directed weighted graph of conversion rates. |
required |
node_names
|
list[str]
|
Currency names. |
required |
max_cycle_length
|
int
|
Maximum number of positions in the cycle. |
required |
Returns:
| Type | Description |
|---|---|
ArbitrageNodeBasedData
|
The data instance. |
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:
| Name | Type | Description | Default |
|---|---|---|---|
n_currencies
|
int
|
Number of currencies (default: 4). |
4
|
max_cycle_length
|
int
|
Maximum cycle length (default: 4). |
4
|
seed
|
int | None
|
Random seed for reproducibility (default: None). |
None
|
Returns:
| Type | Description |
|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
ArbitrageNodeBasedData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
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 | Type | Description |
|---|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
ArbitrageNodeBasedData | None
|
Problem data used to reconstruct the graph layout. Required —
a |
None
|
ax
|
Axes | None
|
Matplotlib axes to draw on. Creates a new figure if |
None
|
Returns:
| Type | Description |
|---|---|
Axes
|
The axes with the plot. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If data is |
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:
| 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
|
max_cycle_length
|
int
|
Maximum cycle length (default: 4). |
4
|
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 |
|---|---|
ArbitrageNodeBasedCollection
|
Collection containing generated instances. |