Skip to content

scheduling

scheduling #

Distribution-aware capture scheduling.

This module provides the Void & Cluster importance sampling algorithm for selecting optimal capture times that maximize diversity across multiple dimensions (solar angle, weather, location, etc.).

The key pattern
  1. Forecast: Generate potential future sessions using forecast.
  2. Select: Use select_sessions with composed distance functions.
  3. Organize: Hand each user their own slot with Reservations / CoverageReservations, so a crowd spreads across the selection.
Submodules
  • distance: Measure similarity between sessions.
  • energy: Convert distances to coverage values.
  • forecast: Generate candidate future sessions.
  • organize: Multi-user slot coordination over persistent state.
Example 
from datetime import timedelta
import capturegraph as cg
import capturegraph.scheduling as cgsh

# 1. Candidate sessions over the next 24 hours, with solar angles.
potential = cg.Array(
    [
        {"date": when, "solar_angle": cgsh.forecast.solar_position(location, when)}
        for when in cgsh.forecast.times(span=timedelta(hours=24))
    ]
)

# 2. Statistical distance: the keyword names the session attribute.
distance_fn = cgsh.distance.combine(
    solar_angle=cgsh.distance.solar(sigma_deg=2.0),
)

# 3. Select sessions unlike anything already captured.
selected = cgsh.select_sessions(
    potential,
    previous_sessions,
    distance_fn,
    energy_fn=cgsh.energy.gaussian(sigma=1.0),
    selections=10,
)

# 4. One distinct time per user, self-expiring.
book = cgsh.Reservations(state.scope("schedule"), grace=timedelta(minutes=30))
chosen = book.reserve(user_id, among=[s["date"] for s in selected])
See Also
  • select_sessions: Main Void & Cluster selection function.
  • distance: Solar, weather, location distance metrics.
  • energy: Gaussian, inverse energy conversions.
  • forecast: Time slot and weather prediction.
  • organize: Reservations over persistent scheduling state.