mixle.utils.hvis.umap_np module

A dependency-free UMAP core (numpy/scipy only) – the fallback engine behind humap.

humap prefers umap-learn when it is installed; this module exists so a missing optional dependency degrades to a slower-but-correct layout instead of an ImportError, and so embedding goals (mixle.utils.hvis.goals) have an optimizer they can actually steer – umap-learn’s numba SGD loop cannot take per-iteration external gradients.

It is the standard UMAP construction (McInnes, Healy & Melville 2018), deliberately minimal:

  1. fuzzy_simplicial_set() – per-row smoothed-kNN calibration (rho = nearest distance, sigma binary-searched so the row’s total membership is log2(k)), then probabilistic t-conorm symmetrization W + W^T - W o W^T.

  2. fit_ab() – least-squares fit of the low-dimensional curve 1/(1 + a d^(2b)) to the min_dist/spread target, exactly as umap-learn does.

  3. simplicial_set_layout() – spectral initialization (normalized-Laplacian eigenvectors, random fallback) and the epochs-per-sample SGD with negative sampling and per-component +-4 move clipping, vectorized per epoch over the due edges rather than numba-jitted per edge.

The knn graph comes from the caller (humap hands in MODEL distances), so nothing here embeds raw vectors – it lays out whatever graph the model-based affinity machinery produced.

fit_ab(min_dist, spread=1.0)[source]

Fit (a, b) of the low-dimensional membership curve 1/(1 + a d^(2b)) to the target exp(-(d - min_dist)/spread) (1 inside min_dist) – umap-learn’s own calibration.

Parameters:
Return type:

tuple[float, float]

fuzzy_simplicial_set(knn_idx, knn_dist)[source]

Symmetric fuzzy graph from a kNN graph of (model) distances.

Per-row memberships exp(-(d - rho)/sigma) with the smoothed-kNN calibration, then the probabilistic t-conorm W + W^T - W o W^T – an undirected membership strength that is high when EITHER direction considers the edge close.

Parameters:
Return type:

coo_matrix

internal_umap(knn_idx, knn_dist, emb_dim=2, *, min_dist=0.1, spread=1.0, n_epochs=None, seed=None, negative_sample_rate=5, learning_rate=1.0, goals=None)[source]

kNN graph in, embedding out: the dependency-free humap engine, end to end.

Parameters:
Return type:

ndarray

simplicial_set_layout(graph, emb_dim=2, n_epochs=None, a=1.577, b=0.8951, *, seed=None, Y=None, negative_sample_rate=5, learning_rate=1.0, goals=None)[source]

UMAP’s epochs-per-sample SGD on a fuzzy graph, vectorized per epoch over the due edges.

Attractive moves apply to both endpoints, repulsive (negative-sampled) moves to the head only, every per-component move clipped to +-4 and the learning rate annealed linearly to zero – the reference algorithm’s behavior, minus numba. goals gradients are applied once per epoch at the same annealed rate, followed by hard-constraint projection.

Parameters:
Return type:

ndarray