Skip to content

Sun Vectors

Computes solar position vectors for specified dates and times using Ladybug's sunpath model. Used by the time-based carving mode.

  • get_sun_vectors -- returns unit direction vectors pointing toward the sun for each hour in the analysis period, filtered by a minimum altitude threshold (to exclude hours when the sun is too low to matter).
  • warm_up -- pre-loads the EPW file and sunpath data into memory to reduce latency on the first real call. Called automatically by the daemon on startup.

urbansolarcarver.sun

UrbanSolarCarver Solar Vector Module

This module handles solar position computations and caching for the UrbanSolarCarver pipeline. It converts meteorological data and date-time information into normalized sun direction vectors suitable for voxel carving or ray tracing.

Core Responsibilities

  1. EPW Loading and Caching • _load_epw(epw_file: str) → EPW

    • Validates and reads an EnergyPlus weather (EPW) file.
    • Caches the EPW object to avoid repeated disk and parse overhead.

  2. Sunpath Initialization and Caching • _get_sunpath(latitude: float, longitude: float, time_zone: float) → Sunpath

    • Creates a Ladybug Sunpath instance for the site location.
    • Caches the Sunpath to reuse across multiple calls.

  3. Cache Pre-Warming • warm_up(epw_file: str) → None

    • Loads EPW and Sunpath caches on demand to improve the first-call latency.

  4. Sun Vector Computation • get_sun_vectors( epw_file: str, datetimes: Sequence[DateTime], min_altitude: float, device: torch.device ) → torch.Tensor

    • Validates inputs: EPW path, Ladybug DateTime sequence, and altitude threshold.
    • Computes sun position for each DateTime.
    • Filters out sun positions below the minimum solar altitude.
    • Returns an Nx3 tensor of unit vectors (x, y, z) pointing toward the sun.
Key Data Structures

• EPW - Ladybug class representing weather data. • Sunpath - Ladybug class for solar geometry calculations. • torch.Tensor - Used to return GPU- or CPU-ready arrays of sun vectors. • Ladybug DateTime - Input time stamps for sun position queries.

Usage Context

Import this module when you need to translate a series of date-times into sun direction vectors for carving routines. The caching mechanisms ensure that repeated calls reuse loaded EPW and Sunpath objects, minimizing I/O and initialization overhead during high-throughput analyses.

warm_up(epw_file)

Load weather and sunpath data into memory to reduce latency on first real call. Ensures that subsequent calls to get_sun_vectors are faster.

get_sun_vectors(epw_file, date_list, min_altitude=5.0, device=torch.device('cpu'))

Determine the sun's unit direction vectors at specified times.

Explanation: 1. Read location and climate data from an EPW file. 2. For each datetime in the list, compute sun position. 3. Filter out moments when the sun is below a minimum elevation angle. 4. Return a list of 3D vectors pointing toward the sun for each valid time.

Args: epw_file : File path to the climate data (EPW format). date_list : Collection of Ladybug DateTime objects to evaluate. min_altitude: Minimum sun elevation (degrees) to include. device : Torch device to store result (CPU or GPU).

Returns: A torch.Tensor of shape (N,3), dtype float32, where each row is a normalized vector pointing from origin toward the sun.

Raises: ValueError: If inputs are of incorrect type or empty. RuntimeError: If sun position calculation fails.