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 | Type | Description |
|---|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
distance_matrix
|
ndarray
|
An n x n symmetric matrix of pairwise distances. |
required |
k
|
int
|
Number of clusters (medoids) to select. |
required |
node_names
|
list[int | str] | None
|
Identifiers for each point. Auto-generated if |
None
|
Returns:
| Type | Description |
|---|---|
KMedoidsClusteringData
|
A data instance backed by the distance matrix. |
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:
| 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 data.
Returns:
| Type | Description |
|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
n_points
|
int
|
Total number of points, by default 8. |
8
|
k
|
int
|
Number of clusters, by default 2. |
2
|
seed
|
int | None
|
Random seed for reproducibility, by default None. |
None
|
Returns:
| Type | Description |
|---|---|
KMedoidsClusteringData
|
A randomly generated data instance. |
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:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
KMedoidsClusteringData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
str
|
String representation of the formulation. |
formulate(data: KMedoidsClusteringData) -> Model
staticmethod
Formulate the K-Medoids Clustering problem.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
KMedoidsClusteringData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
Model
|
A LunaModel ready to be solved. |
interpret(solution: Solution, data: KMedoidsClusteringData) -> KMedoidsClusteringSolution
staticmethod
Extract solution from quantum result.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solution
|
Solution
|
The quantum solution. |
required |
data
|
KMedoidsClusteringData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
KMedoidsClusteringSolution
|
Structured solution with metrics. |
Solution
Solution model for K-Medoids Clustering use case.
KMedoidsClusteringSolution
Bases: UcSolution
Solution for the K-Medoids Clustering use case.
Attributes:
| Name | Type | Description |
|---|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
KMedoidsClusteringData | None
|
Problem data used to compute 2-D coordinates via MDS.
When |
None
|
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 solution.
Returns:
| Type | Description |
|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
min_size
|
int | None
|
Minimum number of points. |
None
|
max_size
|
int | None
|
Maximum number of points. |
None
|
num_instances
|
int
|
Number of instances per size, by default 1. |
1
|
k
|
int
|
Number of clusters, by default 2. |
2
|
seed
|
int | None
|
Random seed for reproducibility, by default None. |
None
|
sizes
|
Sequence[int] | None
|
Explicit sizes to generate, e.g. |
None
|
Returns:
| Type | Description |
|---|---|
KMedoidsClusteringCollection
|
Collection containing generated instances. |
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:
| Name | Type | Description | Default |
|---|---|---|---|
max_runtime
|
float
|
SCIP time limit per instance in seconds. Must be positive. Defaults to 3600 seconds. |
3600
|
quiet
|
bool
|
Suppress the SCIP solver output. |
True
|
Returns:
| Type | Description |
|---|---|
list[bool]
|
Feasibility mask over the instances as they were before filtering,
in that order: |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |