voxcity.simulator.solar.temporal

Stage 3: Time-series integration.

Functions

get_solar_positions_astral(times, lon, lat)	Compute solar azimuth and elevation for given times and location using Astral.
get_cumulative_global_solar_irradiance(voxcity, df, ...)	Integrate global horizontal irradiance over a period using EPW data.
get_cumulative_building_solar_irradiance(voxcity, ...)	Cumulative Wh/m² on building faces over a period from weather dataframe.

Module Contents

voxcity.simulator.solar.temporal.get_solar_positions_astral(times, lon, lat)

Compute solar azimuth and elevation for given times and location using Astral. Returns a DataFrame indexed by times with columns [‘azimuth’, ‘elevation’] (degrees).

voxcity.simulator.solar.temporal.get_cumulative_global_solar_irradiance(voxcity: voxcity.models.VoxCity, df, lon, lat, tz, direct_normal_irradiance_scaling=1.0, diffuse_irradiance_scaling=1.0, **kwargs)

Integrate global horizontal irradiance over a period using EPW data. Returns W/m²·hour accumulation on the ground plane.

Parameters:

• voxcity (VoxCity) – The VoxCity model.

• df (pd.DataFrame) – Weather data with ‘DNI’ and ‘DHI’ columns.

• lon (float) – Longitude and latitude for solar position calculation.

• lat (float) – Longitude and latitude for solar position calculation.

• tz (float) – Timezone offset in hours.

• direct_normal_irradiance_scaling (float) – Scaling factor for DNI.

• diffuse_irradiance_scaling (float) – Scaling factor for DHI.

• **kwargs (dict) –

  Additional options: - use_sky_patches : bool (default False)

  If True, use sky patch aggregation for efficiency. DNI is aggregated into sky patches and ray tracing is done once per patch instead of per timestep.

  • sky_discretizationstr (default “tregenza”)

    Sky discretization method: “tregenza”, “reinhart”, “uniform”, “fibonacci”

  • reinhart_mfint (default 4)

    Multiplication factor for Reinhart subdivision.

  • sky_n_patchesint (default 145)

    Number of patches for Fibonacci method.

  • progress_reportbool

    Print progress information.

Returns:

Cumulative global solar irradiance map (Wh/m²).

Return type:

np.ndarray

voxcity.simulator.solar.temporal.get_cumulative_building_solar_irradiance(voxcity: voxcity.models.VoxCity, building_svf_mesh, weather_df, lon, lat, tz, **kwargs)

Cumulative Wh/m² on building faces over a period from weather dataframe.

Parameters:

• voxcity (VoxCity) – The VoxCity model.

• building_svf_mesh (trimesh.Trimesh) – Building mesh with SVF in metadata.

• weather_df (pd.DataFrame) – Weather data with ‘DNI’ and ‘DHI’ columns.

• lon (float) – Longitude and latitude.

• lat (float) – Longitude and latitude.

• tz (float) – Timezone offset in hours.

• **kwargs (dict) –

  Additional options: - use_sky_patches : bool (default False)

  If True, use sky patch aggregation for efficiency. Reduces computation from N timesteps to M patches (M << N).

  • sky_discretizationstr (default “tregenza”)

    Method: “tregenza”, “reinhart”, “uniform”, “fibonacci”

  • reinhart_mfint (default 4)

    Multiplication factor for Reinhart subdivision.

  • fast_pathbool (default True)

    Use optimized Numba kernels.

  • progress_reportbool

    Print progress information.

Returns:

Mesh with cumulative irradiance in metadata (direct, diffuse, global in Wh/m²).

Return type:

trimesh.Trimesh