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 cgr.scheduling.distance module provides type-specific distance metrics that can be combined into composite functions.
Usage Pattern#
import capturegraph_recipes as cgr
from datetime import timedelta
# Single type-specific distance
solar_dist = cgr.scheduling.distance.solar(sigma_deg=2.0)
# Combine multiple distance functions via attribute names
distance_fn = cgr.scheduling.distance.combine(
solar_angle=cgr.scheduling.distance.solar(sigma_deg=2.0),
location=cgr.scheduling.distance.location(sigma_m=100.0),
)
# Mix type-specific and primitive functions
distance_fn = cgr.scheduling.distance.combine(
solar_angle=cgr.scheduling.distance.solar(sigma_deg=2.0),
weather=cgr.scheduling.distance.weather(sigma_cloud_cover_ratio=0.3),
date=cgr.scheduling.distance.time_of_day(sigma=timedelta(hours=2)),
)
Available Functions#
Type-Specific#
| Function | Operating Type | Description |
|---|---|---|
solar(sigma_deg) |
cgr.scheduling.forecast.SolarPosition |
Angular separation on celestial sphere |
shadow(sigma_heights, courtyard_heights) |
cgr.scheduling.forecast.SolarPosition |
Separation of where an upright pin's shadow ends, in pin heights; long, fast morning and evening shadows count for more. With courtyard_heights, the pin stands in a square courtyard that many pin heights wide, and a shadow that reaches a wall climbs it, so the distance stays defined through sunset and into the night |
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 the fields cg.Weather marks with a
cg.Quantity, 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_recipes as cgr
# Keys match session attribute names
distance_fn = cgr.scheduling.distance.combine(
solar_angle=cgr.scheduling.distance.solar(sigma_deg=2.0),
location=cgr.scheduling.distance.location(sigma_m=50.0),
weather=cgr.scheduling.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)
Coverage#
coverage(points, captures, weights=None)
scores how well the captures so far cover each candidate: the best weighted
Gaussian of its distance to any capture, 1 at a capture and falling off over a
sigma. It is a best rather than a sum, so a burst of captures in one place
covers it no more than one does — and 1 - coverage is what a candidate still
needs. Either argument may be values or features already extracted, such as a
grid over a chart's axes.
sun = cgr.scheduling.distance.solar(sigma_deg=4.0)
coming = cgr.scheduling.forecast.solar_position(site, cgr.scheduling.forecast.times())
need = 1.0 - sun.coverage(coming, photographed)
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_sessionsnever 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.
See Also#
- Void & Cluster — Using distance functions for scheduling
- Reservations — Handing each user a distinct capture slot