void_and_cluster
void_and_cluster
#
Void & cluster sampling for distribution-aware session selection.
Select a subset of candidate items that maximize diversity relative to a set of existing items, using a user-provided distance metric. Adapted from the Void & Cluster dithering algorithm, the sampler works over a coverage field — every candidate's energy from the capture history plus the picks so far — in two steps per iteration: the void step adds the least-covered candidate, and the cluster step releases the most-covered pick unless that is the one just added (a stable set), so a pick that later became crowded is re-placed.
EnergyMode = Literal['sum', 'max']
#
How the energies a candidate draws from several points fold into one.
select_sessions(potential_sessions, previous_sessions, distance_fn, energy_fn=_DEFAULT_ENERGY_FN, energy_mode='sum', selections=10)
#
Select diverse sessions with a Void & Cluster sampler.
Each iteration fills the largest "void": it computes every unselected
candidate's energy — its similarity to the previous sessions plus the
selections made so far — and selects the candidate with the lowest
energy. It then finds the tightest "cluster" — the selected point with
the highest energy — and, unless that is the point just added (a stable
set), releases it so a later iteration can place it in a better void.
The first pick is the candidate least covered by previous_sessions;
with no previous sessions it is uniformly random. Total releases are
bounded by len(potential_sessions) to guarantee termination.
Energy functions are applied to whole numpy distance matrices, so
custom energy_fn callables must be numpy-vectorized. Ties are broken
with the global numpy RNG; seed np.random for reproducibility.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
potential_sessions
|
Array[T]
|
Candidate sessions to select from. A candidate the metric cannot compare — every dimension missing — is never offered. |
required |
previous_sessions
|
Array[T]
|
Already-captured sessions. New selections are spread away from these; one the metric cannot compare covers nothing. |
required |
distance_fn
|
Callable[[T, T], float]
|
Statistical distance between two sessions. A
|
required |
energy_fn
|
EnergyFunction
|
Converts distance to coverage energy. Default is Gaussian with sigma=1. |
_DEFAULT_ENERGY_FN
|
energy_mode
|
EnergyMode
|
How to combine energies from multiple sources — |
'sum'
|
selections
|
int
|
Number of sessions to select. Clamped to the number of comparable candidates. |
10
|
Returns:
| Type | Description |
|---|---|
Array[T]
|
Array of selected sessions, in |
Array[T]
|
(not selection order). |
Raises:
| Type | Description |
|---|---|
ValueError
|
If energy_mode is not "sum" or "max". |