Skip to content

energy

energy #

Convert distances into coverage/energy values for void-and-cluster selection.

Energy functions convert distances into "coverage" or "energy" values used by select_sessions. High energy means two points are similar (close); low energy means they are different (far). The sampler fills "voids" — the candidates with the lowest energy relative to existing and selected points.

Distances arriving here are already dimensionless: each distance function normalizes by its own sigma (degrees, meters, ...), so the sigma of an energy function is a unitless radius of influence in normalized-distance units, not degrees or meters.

Both functions are factories — call them to obtain the energy function (e.g. cgsh.energy.inverse(), not cgsh.energy.inverse). The returned functions are applied to whole numpy distance matrices, so custom energy functions must be numpy-vectorized.

Available Functions
  • gaussian(sigma): Smooth Gaussian falloff, exp(-d²/σ²).
  • inverse(max_energy): Regularized inverse distance, 1/(d + 1/max_energy).
Example 
import capturegraph.scheduling as cgsh

# Influence extends ~2 normalized distance units
energy_fn = cgsh.energy.gaussian(sigma=2.0)

energy_fn(0.0)  # → 1.0 (identical points)
energy_fn(2.0)  # → 0.368 (at sigma distance)
energy_fn(10.0)  # → ~0.0 (far apart)