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 kernels are factories — call them to obtain the energy function (cgr.scheduling.energy.inverse(), not cgr.scheduling.energy.inverse). The returned functions map a whole numpy distance matrix to an energy matrix, so a custom energy function must be numpy-vectorized.

Example
import capturegraph_recipes as cgr
import numpy as np

energy_fn = cgr.scheduling.energy.gaussian(sigma=2.0)
energy_fn(np.array([0.0, 2.0, 10.0]))  # [1.0, 0.368, ~0.0]