Skip to content

capturegraph.scheduling.distance.solar #

Solar Distance - Angular Separation on the Celestial Sphere#

Measures the angular distance between two solar positions using the Haversine formula. Used to ensure captures are distributed across different sun angles (morning, noon, evening, golden hour, etc.).

solar_distance_deg(angle_a, angle_b) #

Compute angular distance using the Haversine formula.

The Haversine formula is numerically stable for small angles, unlike the spherical cosine formula which loses precision near 0°.

Parameters:

Name Type Description Default
angle_a SolarPosition

First solar position (with altitude, azimuth in degrees).

 required
angle_b SolarPosition

Second solar position (with altitude, azimuth in degrees).

 required

Returns:

Type Description
float

Angular distance in degrees.
Source code in capturegraph-lib/capturegraph/scheduling/distance/solar.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
def solar_distance_deg(angle_a: cg.SolarPosition, angle_b: cg.SolarPosition) -> float:
    """Compute angular distance using the Haversine formula.

    The Haversine formula is numerically stable for small angles, unlike
    the spherical cosine formula which loses precision near 0°.

    Args:
        angle_a: First solar position (with altitude, azimuth in degrees).
        angle_b: Second solar position (with altitude, azimuth in degrees).

    Returns:
        Angular distance in degrees.
    """
    # Convert to radians
    alt1, az1 = np.radians(angle_a.altitude), np.radians(angle_a.azimuth)
    alt2, az2 = np.radians(angle_b.altitude), np.radians(angle_b.azimuth)

    # Haversine formula
    d_alt = alt2 - alt1
    d_az = az2 - az1

    a = np.square(np.sin(d_alt / 2)) + np.cos(alt1) * np.cos(alt2) * np.square(
        np.sin(d_az / 2)
    )

    c = 2 * np.arcsin(np.sqrt(np.clip(a, 0, 1)))

    return np.degrees(c)

solar(sigma_deg=1.0) #

Create a distance function based on solar angular separation.

Uses the Haversine formula to compute angular distance between solar positions on the celestial sphere.

Parameters:

Name Type Description Default
sigma_deg float

Normalization factor in degrees. The returned distance is angle_deg / sigma_deg, so sessions within sigma_deg angular separation have distance < 1.0.

 1.0

Returns:

Type Description
SolarDistanceFunction

A distance function with batch support: (session_a, session_b) -> float
Source code in capturegraph-lib/capturegraph/scheduling/distance/solar.py 
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def solar(sigma_deg: float = 1.0) -> SolarDistanceFunction:
    """Create a distance function based on solar angular separation.

    Uses the Haversine formula to compute angular distance between solar
    positions on the celestial sphere.

    Args:
        sigma_deg: Normalization factor in degrees. The returned distance is
            `angle_deg / sigma_deg`, so sessions within sigma_deg angular
            separation have distance < 1.0.

    Returns:
        A distance function with batch support: `(session_a, session_b) -> float`
    """
    return SolarDistanceFunction(sigma_deg)