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 LunaModel 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 | None = None, max_size: int | None = None, num_instances: int = 1, *, sizes: Sequence[int] | None = None, k: int = 2, seed: int | None = None) -> KMedoidsClusteringCollection classmethod

Generate random K-Medoids Clustering instances.

Parameters:

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

    Minimum number of points.

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

    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.

  • sizes (Sequence[int] | None, default: None ) –

    Explicit sizes to generate, e.g. [10, 50, 100], instead of a range. Mutually exclusive with min_size/max_size, by default None.

Returns:

filter_infeasible(max_runtime: float = 3600, *, quiet: bool = True) -> list[bool]

Drop the instances of this collection that have no feasible solution.

Every instance is formulated and handed to SCIP, which stops as soon as it finds the first feasible solution. An instance is removed from the collection when SCIP proves the model infeasible, when no solution turns up within max_runtime, or when formulating it fails altogether. This keeps randomly generated instances from breaking a downstream pipeline.

Parameters:

  • max_runtime (float, default: 3600 ) –

    SCIP time limit per instance in seconds. Must be positive. Defaults to 3600 seconds.

  • quiet (bool, default: True ) –

    Suppress the SCIP solver output.

Returns:

  • list[bool] –

    Feasibility mask over the instances as they were before filtering, in that order: True where the instance was kept, False where it was removed.

Raises: