Skip to content

angle

angle #

Circular angular distance between two angles, where 359° is close to 1°.

CircularAngleDistanceFunction #

Bases: DistanceFunction[float]

Shortest angular separation on a circle, normalized by sigma.

Degrees and radians differ only in sigma and period.

Source code in capturegraph-lib/capturegraph/scheduling/distance/angle.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
class CircularAngleDistanceFunction(DistanceFunction[float]):
    """Shortest angular separation on a circle, normalized by ``sigma``.

    Degrees and radians differ only in ``sigma`` and ``period``.
    """

    def __init__(self, sigma: float, period: float) -> None:
        """Normalize by ``sigma``, wrapping angles at ``period``."""
        self.sigma = sigma
        self.period = period

    def extract(self, values: cg.Array) -> np.ndarray:
        """Each angle as a single feature column."""
        return numeric(values)

    def pairwise(self, features_a: np.ndarray, features_b: np.ndarray) -> np.ndarray:
        """The shortest separations between two sets of angles."""
        gap = np.abs(features_a[:, 0][:, None] - features_b[:, 0][None, :]) % self.period
        return np.minimum(gap, self.period - gap) / self.sigma

__init__(sigma, period) #

Normalize by sigma, wrapping angles at period.

Source code in capturegraph-lib/capturegraph/scheduling/distance/angle.py 
17
18
19
20
def __init__(self, sigma: float, period: float) -> None:
    """Normalize by ``sigma``, wrapping angles at ``period``."""
    self.sigma = sigma
    self.period = period

extract(values) #

Each angle as a single feature column.

Source code in capturegraph-lib/capturegraph/scheduling/distance/angle.py 
22
23
24
def extract(self, values: cg.Array) -> np.ndarray:
    """Each angle as a single feature column."""
    return numeric(values)

pairwise(features_a, features_b) #

The shortest separations between two sets of angles.

Source code in capturegraph-lib/capturegraph/scheduling/distance/angle.py 
26
27
28
29
def pairwise(self, features_a: np.ndarray, features_b: np.ndarray) -> np.ndarray:
    """The shortest separations between two sets of angles."""
    gap = np.abs(features_a[:, 0][:, None] - features_b[:, 0][None, :]) % self.period
    return np.minimum(gap, self.period - gap) / self.sigma

angle_degrees(sigma_deg=10.0, period=360.0) #

Create a circular angular distance function for degrees.

Parameters:

Name Type Description Default
sigma_deg float

Normalization factor in degrees. Angles within sigma_deg apart have distance < 1.0. Default is 10°.

 10.0
period float

The period of the angle in degrees. Default is 360° (full circle). Use 180° for angles that wrap at ±90° (like latitude).

 360.0

Returns:

Type Description
CircularAngleDistanceFunction

A distance function (angle_a, angle_b) -> float.
Example 
import capturegraph.scheduling as cgsh

combined = cgsh.distance.combine(azimuth=cgsh.distance.angle_degrees(sigma_deg=10.0))
Source code in capturegraph-lib/capturegraph/scheduling/distance/angle.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def angle_degrees(
    sigma_deg: float = 10.0,
    period: float = 360.0,
) -> CircularAngleDistanceFunction:
    """Create a circular angular distance function for degrees.

    Args:
        sigma_deg: Normalization factor in degrees. Angles within `sigma_deg`
            apart have distance < 1.0. Default is 10°.
        period: The period of the angle in degrees. Default is 360° (full circle).
            Use 180° for angles that wrap at ±90° (like latitude).

    Returns:
        A distance function `(angle_a, angle_b) -> float`.

    Example:
        ```python
        import capturegraph.scheduling as cgsh

        combined = cgsh.distance.combine(azimuth=cgsh.distance.angle_degrees(sigma_deg=10.0))
        ```
    """
    return CircularAngleDistanceFunction(sigma_deg, period)

angle_radians(sigma_rad=np.pi / 18, period=2 * np.pi) #

Create a circular angular distance function for radians.

Parameters:

Name Type Description Default
sigma_rad float

Normalization factor in radians. Angles within sigma_rad apart have distance < 1.0. Default is π/18 (~10°).

 pi / 18
period float

The period of the angle in radians. Default is 2π (full circle).

 2 * pi

Returns:

Type Description
CircularAngleDistanceFunction

A distance function (angle_a, angle_b) -> float.
Example 
import capturegraph.scheduling as cgsh
import numpy as np

dist_fn = cgsh.distance.angle_radians(sigma_rad=np.pi / 6)  # 30°
Source code in capturegraph-lib/capturegraph/scheduling/distance/angle.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def angle_radians(
    sigma_rad: float = np.pi / 18,
    period: float = 2 * np.pi,
) -> CircularAngleDistanceFunction:
    """Create a circular angular distance function for radians.

    Args:
        sigma_rad: Normalization factor in radians. Angles within `sigma_rad`
            apart have distance < 1.0. Default is π/18 (~10°).
        period: The period of the angle in radians. Default is 2π (full circle).

    Returns:
        A distance function `(angle_a, angle_b) -> float`.

    Example:
        ```python
        import capturegraph.scheduling as cgsh
        import numpy as np

        dist_fn = cgsh.distance.angle_radians(sigma_rad=np.pi / 6)  # 30°
        ```
    """
    return CircularAngleDistanceFunction(sigma_rad, period)