Skip to content

Scheduling Library#

The capturegraph.scheduling module provides a Void & Cluster-inspired importance sampling algorithm for selecting optimal capture times that maximize diversity across multiple dimensions.

Overview#

The scheduling library handles when to prompt users to capture data:

Procedure DSL → @cgserver.intercept(...) notification hook → Scheduling Library → User Prompt

Scheduling code runs on the server, inside a target's interceptor functions — typically @cgserver.intercept(Schema, lambda s: s._metadata._next_notification), which returns the next capture time for a user. See Server Targets for how interceptors are declared in __capture_target__.py.

Key features:

  • Void & Cluster importance sampling for optimal coverage
  • Forecast utilities for generating candidate sessions
  • Distance functions for measuring session similarity
  • Reservations handing each user a distinct, self-expiring slot

Quick Start#

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 select_sessions for the full signature.

Section Contents#

Hand each user a distinct, self-expiring slot and prevent duplicate prompts

The importance sampling algorithm for scheduling captures

Define metrics for measuring similarity between sessions