Skip to content

solar

solar #

Solar position forecasting via the astral library.

Computes the sun's altitude and azimuth for a location and time using the astral library. The main entry point, solar_position, is vectorized so cg.Array arguments broadcast element-wise.

SolarPosition dataclass #

Solar position with altitude (elevation) and azimuth.

Attributes:

Name Type Description
altitude float

Sun elevation in degrees above the horizon (-90° to 90°; negative is below the horizon).
azimuth float

Sun azimuth in degrees clockwise from North (0°=N, 90°=E, 180°=S, 270°=W).
Source code in capturegraph-lib/capturegraph/scheduling/forecast/solar.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
@dataclass
class SolarPosition:
    """Solar position with altitude (elevation) and azimuth.

    Attributes:
        altitude: Sun elevation in degrees above the horizon (-90° to 90°;
            negative is below the horizon).
        azimuth: Sun azimuth in degrees clockwise from North (0°=N, 90°=E,
            180°=S, 270°=W).
    """

    altitude: float
    azimuth: float

    def __repr__(self) -> str:
        """Render as ``SolarPosition(alt=…°, az=…°)`` with one decimal place."""
        return f"SolarPosition(alt={self.altitude:.1f}°, az={self.azimuth:.1f}°)"

    def to_json(self) -> dict:
        """Convert to a dict with 'altitude' and 'azimuth' keys."""
        return {"altitude": self.altitude, "azimuth": self.azimuth}

    @classmethod
    def from_json(cls, obj: dict) -> SolarPosition:
        """Create a SolarPosition from a dict with 'altitude' and 'azimuth' keys."""
        return cls(altitude=obj["altitude"], azimuth=obj["azimuth"])

__repr__() #

Render as SolarPosition(alt=…°, az=…°) with one decimal place.

Source code in capturegraph-lib/capturegraph/scheduling/forecast/solar.py 
37
38
39
def __repr__(self) -> str:
    """Render as ``SolarPosition(alt=…°, az=…°)`` with one decimal place."""
    return f"SolarPosition(alt={self.altitude:.1f}°, az={self.azimuth:.1f}°)"

from_json(obj) classmethod #

Create a SolarPosition from a dict with 'altitude' and 'azimuth' keys.

Source code in capturegraph-lib/capturegraph/scheduling/forecast/solar.py 
45
46
47
48
@classmethod
def from_json(cls, obj: dict) -> SolarPosition:
    """Create a SolarPosition from a dict with 'altitude' and 'azimuth' keys."""
    return cls(altitude=obj["altitude"], azimuth=obj["azimuth"])

to_json() #

Convert to a dict with 'altitude' and 'azimuth' keys.

Source code in capturegraph-lib/capturegraph/scheduling/forecast/solar.py 
41
42
43
def to_json(self) -> dict:
    """Convert to a dict with 'altitude' and 'azimuth' keys."""
    return {"altitude": self.altitude, "azimuth": self.azimuth}

solar_position(location, time) #

Calculate solar position for a single datetime and location.

Uses the astral library for accurate calculations. Vectorized: passing cg.Array arguments broadcasts element-wise.

Parameters:

Name Type Description Default
location Location

Location with latitude, longitude, and altitude.

 required
time datetime

Date and time. Timezone-aware datetimes are converted to UTC; naive datetimes are interpreted as system-local time.

 required

Returns:

Type Description
SolarPosition

SolarPosition with altitude and azimuth in degrees.

Raises:

Type Description
ImportError

If astral is not installed.
Source code in capturegraph-lib/capturegraph/scheduling/forecast/solar.py 
51
52
53
54
55
56
57
58
59
60
61
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
93
94
@vectorize
def solar_position(
    location: Location,
    time: datetime,
) -> SolarPosition:
    """Calculate solar position for a single datetime and location.

    Uses the astral library for accurate calculations. Vectorized: passing
    cg.Array arguments broadcasts element-wise.

    Args:
        location: Location with latitude, longitude, and altitude.
        time: Date and time. Timezone-aware datetimes are converted to UTC;
            naive datetimes are interpreted as system-local time.

    Returns:
        SolarPosition with altitude and azimuth in degrees.

    Raises:
        ImportError: If astral is not installed.
    """
    try:
        from astral import Observer
        from astral.sun import azimuth, elevation
    except ImportError as e:
        raise ImportError("solar_position requires astral. Install with: pip install astral") from e

    observer = Observer(
        latitude=location.latitude,
        longitude=location.longitude,
        elevation=location.altitude_meters,
    )

    # check for numpy dt and convert to datetime
    if isinstance(time, np.datetime64):
        time = time.item()

    # normalize dt to UTC
    time = time.astimezone(UTC)

    alt = elevation(observer, time)
    az = azimuth(observer, time)

    return SolarPosition(altitude=alt, azimuth=az)