Skip to content

Distance Functions#

Distance functions measure how "different" two sessions are along a specific dimension. The Void & Cluster algorithm uses these to select captures that maximize diversity.

Overview#

The capturegraph.scheduling.distance module provides type-specific distance metrics that can be combined into composite functions.

Usage Pattern#

import capturegraph.scheduling as cgsh
from datetime import timedelta

# Single type-specific distance
solar_dist = cgsh.distance.solar(sigma_deg=2.0)

# Combine multiple distance functions via attribute paths
distance_fn = cgsh.distance.combine(
    solar_angle=cgsh.distance.solar(sigma_deg=2.0),
    location=cgsh.distance.location(sigma_m=100.0),
)

# Mix type-specific and primitive functions
distance_fn = cgsh.distance.combine(
    solar_angle=cgsh.distance.solar(sigma_deg=2.0),
    weather=cgsh.distance.weather(sigma_cloud_cover_pct=30.0),
    date=cgsh.distance.time_of_day(sigma=timedelta(hours=2)),
)

Available Functions#

Type-Specific#

Function Operating Type Description
solar(sigma_deg) cg.SolarPosition Angular separation on celestial sphere
location(sigma_m) cg.Location Geographic separation in meters
weather(...) cg.Weather Multi-dimensional weather difference

Primitive#

Function Operating Type Description
scalar(sigma) float Simple absolute difference
angle_degrees(sigma_deg) float Circular difference (0-360°)
angle_radians(sigma_rad) float Circular difference (0-2π)
time_of_day(sigma) datetime Circular 24-hour difference

Combining Functions#

The combine() function creates a Euclidean combination of distance functions. The keyword argument specifies which session attribute to extract:

import capturegraph.scheduling as cgsh

# Keys match session attribute paths
distance_fn = cgsh.distance.combine(
    solar_angle=cgsh.distance.solar(sigma_deg=2.0),
    location=cgsh.distance.location(sigma_m=50.0),
    weather=cgsh.distance.weather(sigma_cloud_cover_pct=30.0),
)

# Use with sessions
d = distance_fn(session_a, session_b)

See Also#