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 Luna Model 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, max_size: int, num_instances: int = 1, *, k: int = 2, seed: int | None = None) -> KMedoidsClusteringCollection
classmethod
Generate random K-Medoids Clustering instances.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
min_size
|
int
|
Minimum number of points. |
required |
max_size
|
int
|
Maximum number of points. |
required |
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
|
Returns:
| Type | Description |
|---|---|
KMedoidsClusteringCollection
|
Collection containing generated instances. |