capturegraph.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. Enrich: Add derived attributes (solar_angle, weather) via broadcasting.
3. Select: Use select_sessions with composed distance functions.

Submodules

• distance: Measure similarity between sessions.
• energy: Convert distances to coverage values.
• forecast: Generate candidate future sessions.
• organize: Multi-user slot assignment and coordination.

Example

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

# 1. Create potential sessions from time slots
potential = cg.List()
potential.date = cgsh.forecast.times(span=timedelta(hours=24))
potential.location = location  # scalar broadcast

# 2. Add solar angles (element-wise broadcasting)
potential.solar_angle = cgsh.forecast.solar_position(location, potential.date)

# 3. Define statistical distance using combine()
# The keyword argument specifies which session attribute to extract.
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,
)

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.

Modules:

Name	Description
distance	Distance - Statistical Similarity Between Sessions
energy	Energy - Distance to Coverage Conversion
forecast	Forecast - Generate Potential Future Sessions
organize	Organize - Multi-User Slot Assignment
void_and_cluster	Void & Cluster Scheduling Algorithm