Skip to content

solar

solar #

Solar position forecasting via the astral library.

solar_position computes the sun's altitude and azimuth for a location and instant. It is vectorized, so cg.Array arguments broadcast element-wise.

SolarPosition dataclass #

Solar position with altitude (elevation) and azimuth.

Attributes:

Name Type Description
altitude Annotated[float, Quantity('°', name='Sun altitude')]

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

azimuth Annotated[float, Quantity('°', name='Sun azimuth', span=(0.0, 360.0))]

Sun azimuth in degrees clockwise from North (0°=N, 90°=E, 180°=S, 270°=W).

Source code in capturegraph-recipes/capturegraph_recipes/scheduling/forecast/solar.py
@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: Annotated[float, cg.Quantity("°", name="Sun altitude")]
    azimuth: Annotated[float, cg.Quantity("°", name="Sun azimuth", span=(0.0, 360.0))]

    @property
    def shadow_tip(self) -> tuple[float, float] | None:
        """Where the shadow of an upright pin one unit tall ends on level ground.

        Returns:
            ``(east, north)`` from the pin's foot, in pin heights; ``None`` with
            the sun at or below the horizon.
        """
        if self.altitude <= 0.0:
            return None
        length = 1.0 / math.tan(math.radians(self.altitude))
        azimuth = math.radians(self.azimuth)
        return (-math.sin(azimuth) * length, -math.cos(azimuth) * length)

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

shadow_tip property #

Where the shadow of an upright pin one unit tall ends on level ground.

Returns:

Type Description
tuple[float, float] | None

(east, north) from the pin's foot, in pin heights; None with

tuple[float, float] | None

the sun at or below the horizon.

__repr__() #

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

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

solar_position(location, time) #

Calculate solar position for a single datetime and location.

Vectorized: passing cg.Array arguments broadcasts element-wise.

Parameters:

Name Type Description Default
location Location

Location with latitude, longitude, and altitude.

required
time datetime | datetime64

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.

Source code in capturegraph-recipes/capturegraph_recipes/scheduling/forecast/solar.py
@cg.vectorize
def solar_position(
    location: cg.Location,
    time: datetime | np.datetime64,
) -> SolarPosition:
    """Calculate solar position for a single datetime and location.

    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.
    """
    observer = Observer(
        latitude=location.latitude,
        longitude=location.longitude,
        elevation=location.altitude_meters,
    )
    instant = _as_datetime(time).astimezone(UTC)
    return SolarPosition(
        altitude=elevation(observer, instant),
        azimuth=azimuth(observer, instant),
    )