Skip to content

location

location #

Geographic separation between two locations.

Measures the geographic distance between two locations using the Haversine formula. Used to ensure captures are distributed across different locations.

LocationDistanceFunction #

Bases: BatchedDistanceFunction[Location]

Haversine great-circle distance between locations, normalized by sigma_m.

Source code in capturegraph-lib/capturegraph/scheduling/distance/location.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
class LocationDistanceFunction(BatchedDistanceFunction[cg.Location]):
    """Haversine great-circle distance between locations, normalized by ``sigma_m``."""

    def __init__(self, sigma_m: float = 50.0) -> None:
        """Normalize the great-circle distance by ``sigma_m`` meters."""
        self.sigma_km = sigma_m / 1000.0

    def __call__(self, a: cg.Location, b: cg.Location) -> float:
        """Haversine great-circle distance between two locations, normalized."""
        return location_distance_km(a, b) / self.sigma_km

    def extract(self, items: cg.Array[Any]) -> np.ndarray:
        """Extract longitude/latitude (in radians) as a two-column feature array."""
        lons = np.radians(np.array(items.longitude, dtype=np.float64))
        lats = np.radians(np.array(items.latitude, dtype=np.float64))
        return np.column_stack([lons, lats])

    def pairwise(self, features_a: np.ndarray, features_b: np.ndarray) -> np.ndarray:
        """Compute pairwise Haversine distances from extracted location features."""
        lon1, lat1 = features_a[:, 0], features_a[:, 1]
        lon2, lat2 = features_b[:, 0], features_b[:, 1]

        return (
            _haversine_km_vectorized(
                lat1,
                lon1,
                lat2,
                lon2,
            )
            / self.sigma_km
        )

__call__(a, b) #

Haversine great-circle distance between two locations, normalized.

Source code in capturegraph-lib/capturegraph/scheduling/distance/location.py 
69
70
71
def __call__(self, a: cg.Location, b: cg.Location) -> float:
    """Haversine great-circle distance between two locations, normalized."""
    return location_distance_km(a, b) / self.sigma_km

__init__(sigma_m=50.0) #

Normalize the great-circle distance by sigma_m meters.

Source code in capturegraph-lib/capturegraph/scheduling/distance/location.py 
65
66
67
def __init__(self, sigma_m: float = 50.0) -> None:
    """Normalize the great-circle distance by ``sigma_m`` meters."""
    self.sigma_km = sigma_m / 1000.0

extract(items) #

Extract longitude/latitude (in radians) as a two-column feature array.

Source code in capturegraph-lib/capturegraph/scheduling/distance/location.py 
73
74
75
76
77
def extract(self, items: cg.Array[Any]) -> np.ndarray:
    """Extract longitude/latitude (in radians) as a two-column feature array."""
    lons = np.radians(np.array(items.longitude, dtype=np.float64))
    lats = np.radians(np.array(items.latitude, dtype=np.float64))
    return np.column_stack([lons, lats])

pairwise(features_a, features_b) #

Compute pairwise Haversine distances from extracted location features.

Source code in capturegraph-lib/capturegraph/scheduling/distance/location.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def pairwise(self, features_a: np.ndarray, features_b: np.ndarray) -> np.ndarray:
    """Compute pairwise Haversine distances from extracted location features."""
    lon1, lat1 = features_a[:, 0], features_a[:, 1]
    lon2, lat2 = features_b[:, 0], features_b[:, 1]

    return (
        _haversine_km_vectorized(
            lat1,
            lon1,
            lat2,
            lon2,
        )
        / self.sigma_km
    )

location(sigma_m=50.0) #

Create a distance function based on geographic separation.

Uses the Haversine formula to compute great-circle distance between locations on Earth.

Parameters:

Name Type Description Default
sigma_m float

Normalization factor in meters. The returned distance is distance_m / sigma_m, so sessions within sigma_m have distance < 1.0. Default is 50m.

 50.0

Returns:

Type Description
LocationDistanceFunction

A distance function with batch support: (session_a, session_b) -> float
Source code in capturegraph-lib/capturegraph/scheduling/distance/location.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def location(sigma_m: float = 50.0) -> LocationDistanceFunction:
    """Create a distance function based on geographic separation.

    Uses the Haversine formula to compute great-circle distance between
    locations on Earth.

    Args:
        sigma_m: Normalization factor in meters. The returned distance is
            `distance_m / sigma_m`, so sessions within sigma_m have
            distance < 1.0. Default is 50m.

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

location_distance_km(loc_a, loc_b) #

Compute great-circle distance using the Haversine formula.

Parameters:

Name Type Description Default
loc_a Location

First location with longitude and latitude attributes.

 required
loc_b Location

Second location with longitude and latitude attributes.

 required

Returns:

Type Description
float

Distance in kilometers.
Source code in capturegraph-lib/capturegraph/scheduling/distance/location.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def location_distance_km(loc_a: cg.Location, loc_b: cg.Location) -> float:
    """Compute great-circle distance using the Haversine formula.

    Args:
        loc_a: First location with longitude and latitude attributes.
        loc_b: Second location with longitude and latitude attributes.

    Returns:
        Distance in kilometers.
    """
    # Convert to radians
    lon1, lat1 = np.radians(loc_a.longitude), np.radians(loc_a.latitude)
    lon2, lat2 = np.radians(loc_b.longitude), np.radians(loc_b.latitude)

    # Haversine formula
    d_lat = lat2 - lat1
    d_lon = lon2 - lon1

    a = np.square(np.sin(d_lat / 2)) + np.cos(lat1) * np.cos(lat2) * np.square(np.sin(d_lon / 2))
    c = 2 * np.arcsin(np.sqrt(np.clip(a, 0, 1)))

    return EARTH_RADIUS_KM * c