Skip to content

Void & Cluster Algorithm#

The select_sessions function implements the Void & Cluster importance sampling algorithm to select capture times that maximize diversity.

Overview#

For captures that depend on lighting, weather, or location conditions, you want to sample times that provide good coverage of the parameter space. The Void & Cluster algorithm iteratively selects points that:

  1. Void: Find the candidate with the lowest coverage (furthest from existing data)
  2. Cluster: Remove selected points that have become redundant

Basic Usage#

from datetime import timedelta
import capturegraph.data as cg
import capturegraph.scheduling as cgsh

# 1. Generate candidate time slots
potential = cg.List()
potential.date = cgsh.forecast.times(span=timedelta(hours=24))
potential.location = location

# 2. Add derived attributes
potential.solar_angle = cgsh.forecast.solar_position(location, potential.date)

# 3. Define distance function
distance_fn = cgsh.distance.combine(
    solar_angle=cgsh.distance.solar(sigma_deg=2.0),
)

# 4. Select diverse sessions
selected = cgsh.select_sessions(
    potential,
    existing_sessions,
    distance_fn,
    energy_fn=cgsh.energy.gaussian(sigma=1.0),
    selections=10,
)

Parameters#

Parameter Type Default Description
potential_sessions cg.List — Candidates to select from
previous_sessions cg.List — Already-captured sessions
distance_fn Callable — Distance function between sessions
energy_fn Callable gaussian(sigma=1) Distance-to-energy conversion
energy_mode str "sum" How to combine energies ("sum" or "max")
selections int 10 Number of sessions to select

Forecast Utilities#

Generate candidate sessions using the forecast submodule:

import capturegraph.scheduling as cgsh

# Time slots for the next 24 hours
times = cgsh.forecast.times(span=timedelta(hours=24))

# Specific times of day
times = cgsh.forecast.times_of_day(hours=[8, 12, 17])

# Solar positions
solar = cgsh.forecast.solar_position(location, times)

# Weather forecasts (from Open-Meteo, free API)
weather = cgsh.forecast.hourly_weather(location, days=3)
nearest = cgsh.forecast.nearest_weather(weather, times)

Energy Functions#

Convert distances to coverage energy:

import capturegraph.scheduling as cgsh

# Gaussian falloff (default)
energy = cgsh.energy.gaussian(sigma=1.0)

# Inverse distance
energy = cgsh.energy.inverse

See Also#