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 names
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_ratio=0.3),
    date=cgsh.distance.time_of_day(sigma=timedelta(hours=2)),
)

Available Functions#

Type-Specific#

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

Weather dimensions are opt-in: pass one sigma_<field> per cg.Weather field you care about — for example weather(sigma_cloud_cover_ratio=0.3). The keywords are checked against cg.Weather's own numeric fields, so a typo raises instead of silently measuring nothing. Cloud cover and humidity are expressed as 0–1 ratios, not percentages.

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 names
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_ratio=0.3),
)

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

# Or every pair at once
matrix = distance_fn.matrix(potential_sessions, previous_sessions)

Missing data#

One rule covers absence, wherever it comes from — a session that never recorded a field, a forecast a provider does not report, a nan reading:

A term whose value is missing on either side drops out of the combination, so the pair is scored on the dimensions it does have.
A pair with no term left has no distance, and select_sessions never offers such a candidate — it cannot be compared to anything, so it is not a slot worth prompting for.

A metric that fails is not missing data: the error surfaces rather than scoring the pair as identical.