Skip to content

Market Graph Clustering API Reference

Data

Data model for Market Graph Clustering use case.

MarketGraphClusteringData

Bases: UcData

Data for the Market Graph Clustering use case.

This use case clusters stocks based on their return correlations using a k-medoids approach on a correlation-derived distance metric.

Attributes:

  • name (Literal['market_graph_clustering']) –

    Identifier for this data type.

  • returns_matrix (NumPyArray) –

    An n_stocks x n_observations matrix of stock returns.

  • k (int) –

    Number of clusters to form.

  • stock_names (list[str]) –

    Identifiers for each stock.

from_corr_matrix(corr_matrix: np.ndarray, k: int, stock_names: list[str] | None = None) -> MarketGraphClusteringData classmethod

Create data from a symmetric correlation matrix.

The correlation matrix is symmetrised via (C + C^T) / 2 to guard against small floating-point asymmetries.

Parameters:

  • corr_matrix (ndarray) –

    An n_stocks x n_stocks symmetric correlation matrix.

  • k (int) –

    Number of clusters to form.

  • stock_names (list[str] | None, default: None ) –

    Identifiers for each stock. Auto-generated if None.

Returns:

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

Plot the correlation matrix as a heatmap.

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

Returns:

  • str –

    String representation of the data.

generate_random(n_stocks: int = 6, n_observations: int = 20, k: int = 2, seed: int | None = None) -> MarketGraphClusteringData staticmethod

Generate a random Market Graph Clustering instance.

Creates correlated groups of stock returns to simulate market sectors.

Parameters:

  • n_stocks (int, default: 6 ) –

    Number of stocks, by default 6.

  • n_observations (int, default: 20 ) –

    Number of return observations per stock, by default 20.

  • k (int, default: 2 ) –

    Number of clusters, by default 2.

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

    Random seed for reproducibility, by default None.

Returns:

Formulation

Formulation for Market Graph Clustering use case.

MarketGraphClusteringFormulation

Bases: UcFormulation[MarketGraphClusteringData, MarketGraphClusteringSolution]

Constraint-based formulation for Market Graph Clustering.

Preprocessing converts Pearson correlations to distances using d_ij = sqrt(0.5 * (1 - corr_ij)), then applies the standard k-medoids formulation.

Mathematical Formulation

Decision Variables: z_i in {0,1}: 1 if stock i is a medoid y_{i,j} in {0,1}: 1 if stock i is assigned to medoid j

Objective: minimize sum_{i,j} d[i][j] * y[i,j]

Constraints: 1. Exactly k medoids: sum_i z[i] == k 2. Each stock assigned to one medoid: sum_j y[i,j] == 1 for all i 3. Assign only to medoids: y[i,j] <= z[j] for all i,j 4. Medoid self-assignment: y[j,j] >= z[j] for all j

to_string(data: MarketGraphClusteringData) -> str staticmethod

Return a string describing the formulation.

Parameters:

Returns:

  • str –

    String representation of the formulation.

formulate(data: MarketGraphClusteringData) -> Model staticmethod

Formulate the Market Graph Clustering problem.

Parameters:

Returns:

  • Model –

    A Luna Model ready to be solved.

interpret(solution: Solution, data: MarketGraphClusteringData) -> MarketGraphClusteringSolution staticmethod

Extract solution from quantum result.

Parameters:

Returns:

Solution

Solution model for Market Graph Clustering use case.

MarketGraphClusteringSolution

Bases: UcSolution

Solution for the Market Graph Clustering use case.

Attributes:

  • name (Literal['market_graph_clustering']) –

    Identifier for this solution type.

  • medoids (list[str]) –

    List of selected medoid stock names.

  • cluster_assignments (dict[str, str]) –

    Mapping from each stock to its assigned medoid (str keys for JSON).

  • total_objective (float) –

    Sum of correlation-derived distances from each stock to its medoid.

  • is_valid (bool) –

    Whether the solution satisfies all constraints.

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

Plot the clustering solution as a return-vs-volatility scatter.

Each stock is positioned by its mean return (x-axis) and volatility (y-axis). Stocks are coloured by cluster, with medoids shown as larger square markers. Light lines connect each stock to its medoid.

Parameters:

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

    Problem data used to compute return and volatility coordinates. When None a simple circular layout is used as fallback.

  • 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 solution.

Returns:

  • str –

    String representation of the solution.

Instance

Instance model for MarketGraphClustering use case.

MarketGraphClusteringInstance

Bases: UcInstance[MarketGraphClusteringData, MarketGraphClusteringFormulation, MarketGraphClusteringSolution]

Instance combining data and formulation for MarketGraphClustering.

Collection

Collection of Market Graph Clustering instances.

MarketGraphClusteringCollection

Bases: UcInstanceCollection[MarketGraphClusteringInstance]

Collection of Market Graph Clustering instances.

from_random(min_size: int, max_size: int, num_instances: int = 1, *, n_observations: int = 20, k: int = 2, seed: int | None = None) -> MarketGraphClusteringCollection classmethod

Generate random Market Graph Clustering instances.

Parameters:

  • min_size (int) –

    Minimum number of stocks.

  • max_size (int) –

    Maximum number of stocks.

  • num_instances (int, default: 1 ) –

    Number of instances per size, by default 1.

  • n_observations (int, default: 20 ) –

    Number of return observations, by default 20.

  • k (int, default: 2 ) –

    Number of clusters, by default 2.

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

    Random seed for reproducibility, by default None.

Returns: