Skip to content

K-Medoids Clustering API Reference

Data

Data model for K-Medoids Clustering use case.

KMedoidsClusteringData

Bases: UcData

Data for the K-Medoids Clustering use case.

The K-Medoids Clustering problem partitions a set of points into k clusters, each represented by a medoid (an actual data point), minimizing the total distance from each point to its assigned medoid.

Attributes:

  • name (Literal['k_medoids_clustering']) –

    Identifier for this data type.

  • distance_matrix (NumPyArray) –

    An n x n symmetric matrix of pairwise distances between points.

  • k (int) –

    Number of clusters (medoids) to select.

  • node_names (list[int | str]) –

    Identifiers for each point.

from_distance_matrix(distance_matrix: np.ndarray, k: int, node_names: list[int | str] | None = None) -> KMedoidsClusteringData classmethod

Create data from a symmetric distance matrix.

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

Parameters:

  • distance_matrix (ndarray) –

    An n x n symmetric matrix of pairwise distances.

  • k (int) –

    Number of clusters (medoids) to select.

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

    Identifiers for each point. Auto-generated if None.

Returns:

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

Plot the distance data as a complete graph with distance labels.

Nodes are positioned via classical MDS on the distance matrix. Edges are drawn between all pairs with their distance as a label, coloured from short (dark) to long (light).

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_points: int = 8, k: int = 2, seed: int | None = None) -> KMedoidsClusteringData staticmethod

Generate a random K-Medoids Clustering instance.

Creates clustered points in 2D space and computes the pairwise Euclidean distance matrix.

Parameters:

  • n_points (int, default: 8 ) –

    Total number of points, by default 8.

  • 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 K-Medoids Clustering use case.

KMedoidsClusteringFormulation

Bases: UcFormulation[KMedoidsClusteringData, KMedoidsClusteringSolution]

Constraint-based formulation for K-Medoids Clustering.

Mathematical Formulation

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

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

Constraints: 1. Exactly k medoids: sum_i z[i] == k 2. Each point 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: KMedoidsClusteringData) -> str staticmethod

Return a string describing the formulation.

Parameters:

Returns:

  • str –

    String representation of the formulation.

formulate(data: KMedoidsClusteringData) -> Model staticmethod

Formulate the K-Medoids Clustering problem.

Parameters:

Returns:

  • Model –

    A Luna Model ready to be solved.

interpret(solution: Solution, data: KMedoidsClusteringData) -> KMedoidsClusteringSolution staticmethod

Extract solution from quantum result.

Parameters:

Returns:

Solution

Solution model for K-Medoids Clustering use case.

KMedoidsClusteringSolution

Bases: UcSolution

Solution for the K-Medoids Clustering use case.

Attributes:

  • name (Literal['k_medoids_clustering']) –

    Identifier for this solution type.

  • medoids (list[int | str]) –

    List of selected medoid point identifiers.

  • cluster_assignments (dict[str, str]) –

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

  • total_objective (float) –

    Sum of distances from each point to its assigned medoid.

  • is_valid (bool) –

    Whether the solution satisfies all constraints.

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

Plot the clustering solution as a 2-D scatter.

Points are positioned using classical MDS on the distance matrix when data is provided, otherwise a circular layout is used as fallback. Stocks are coloured by cluster, with medoids shown as larger square markers. Light lines connect each point to its medoid.

Parameters:

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

    Problem data used to compute 2-D coordinates via MDS. 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 KMedoidsClustering use case.

KMedoidsClusteringInstance

Bases: UcInstance[KMedoidsClusteringData, KMedoidsClusteringFormulation, KMedoidsClusteringSolution]

Instance combining data and formulation for KMedoidsClustering.

Collection

Collection of K-Medoids Clustering instances.

KMedoidsClusteringCollection

Bases: UcInstanceCollection[KMedoidsClusteringInstance]

Collection of K-Medoids Clustering instances.

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

Generate random K-Medoids Clustering instances.

Parameters:

  • min_size (int) –

    Minimum number of points.

  • max_size (int) –

    Maximum number of points.

  • num_instances (int, default: 1 ) –

    Number of instances per size, by default 1.

  • k (int, default: 2 ) –

    Number of clusters, by default 2.

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

    Random seed for reproducibility, by default None.

Returns: