voxcity.simulator_gpu.solar.integration.caching¶

Caching infrastructure for VoxCity solar integration module.

This module provides cache dataclasses and management functions for: - RadiationModel (ground-level calculations) - Building RadiationModel (building surface calculations) - GPU Ray Tracer (simple ray-tracing) - Volumetric Flux Calculator

Classes¶

`LandCoverAlbedo`	Mapping of land cover classes to albedo values.
`VoxCityDomainResult`	Result of VoxCity to palm_solar conversion.
`CachedRadiationModel`	Cached RadiationModel with associated metadata.
`CachedBuildingRadiationModel`	Cached RadiationModel for building surface calculations.
`CachedGPURayTracer`	Cached Taichi fields for GPU ray tracing.

Functions¶

`clear_radiation_model_cache`()	Clear the cached RadiationModel to free memory or force recomputation.
`clear_building_radiation_model_cache`()	Clear the cached Building RadiationModel to free memory.
`clear_gpu_ray_tracer_cache`()	Clear the cached GPU ray tracer fields to free memory or force recomputation.
`clear_volumetric_flux_cache`()	Clear the cached VolumetricFluxCalculator to free memory.
`clear_all_caches`()	Clear all GPU caches (RadiationModel, Building RadiationModel, GPU ray tracer, Volumetric).
`clear_all_radiation_caches`()	Clear all cached RadiationModels to free GPU memory.
`reset_solar_taichi_cache`()	Reset Taichi runtime and clear all solar caches.
`get_radiation_model_cache`(→ Optional[CachedRadiationModel])	Get the current radiation model cache.
`set_radiation_model_cache`(cache)	Set the radiation model cache.
`get_building_radiation_model_cache`(...)	Get the current building radiation model cache.
`set_building_radiation_model_cache`(cache)	Set the building radiation model cache.
`get_gpu_ray_tracer_cache`(→ Optional[CachedGPURayTracer])	Get the current GPU ray tracer cache.
`set_gpu_ray_tracer_cache`(cache)	Set the GPU ray tracer cache.
`get_volumetric_flux_cache`(→ Optional[Dict])	Get the current volumetric flux cache.
`set_volumetric_flux_cache`(cache)	Set the volumetric flux cache.
`get_or_create_radiation_model`(→ Tuple[object, ...)	Get cached RadiationModel or create a new one if cache is invalid.
`get_or_create_building_radiation_model`(→ Tuple[object, ...)	Get cached RadiationModel for building surfaces or create a new one.
`get_or_create_gpu_ray_tracer`(→ CachedGPURayTracer)	Get cached GPU ray tracer or create new one if cache is invalid.
`get_or_create_volumetric_calculator`(voxcity[, ...])	Get cached VolumetricFluxCalculator or create a new one if cache is invalid.
`compute_direct_transmittance_map_gpu`(→ numpy.ndarray)	Compute direct solar transmittance map using GPU ray tracing.
`reset_solar_taichi_cache`()	Reset Taichi runtime and clear all solar caches.
`clear_all_radiation_caches`()	Clear all cached RadiationModels to free GPU memory.
`load_voxcity`(filepath)	Load VoxCity data from pickle file.
`convert_voxcity_to_domain`(→ VoxCityDomainResult)	Convert VoxCity voxel grid to palm_solar Domain with material properties.
`apply_voxcity_albedo`(→ None)	Apply VoxCity land cover-based albedo values to radiation model surfaces.
`create_radiation_config_for_voxcity`([land_cover_albedo])	Create a RadiationConfig suitable for VoxCity simulations.

Module Contents¶

voxcity.simulator_gpu.solar.integration.caching.clear_radiation_model_cache()¶: Clear the cached RadiationModel to free memory or force recomputation.

voxcity.simulator_gpu.solar.integration.caching.clear_building_radiation_model_cache()¶: Clear the cached Building RadiationModel to free memory.

voxcity.simulator_gpu.solar.integration.caching.clear_gpu_ray_tracer_cache()¶: Clear the cached GPU ray tracer fields to free memory or force recomputation.

voxcity.simulator_gpu.solar.integration.caching.clear_volumetric_flux_cache()¶: Clear the cached VolumetricFluxCalculator to free memory.

voxcity.simulator_gpu.solar.integration.caching.clear_all_caches()¶: Clear all GPU caches (RadiationModel, Building RadiationModel, GPU ray tracer, Volumetric).

voxcity.simulator_gpu.solar.integration.caching.clear_all_radiation_caches()¶: Clear all cached RadiationModels to free GPU memory.

voxcity.simulator_gpu.solar.integration.caching.reset_solar_taichi_cache()¶

Reset Taichi runtime and clear all solar caches.

Call this function when you encounter: - CUDA_ERROR_OUT_OF_MEMORY errors - TaichiRuntimeError: FieldsBuilder finalized

After calling this, the next solar calculation will create fresh Taichi fields.

voxcity.simulator_gpu.solar.integration.caching.get_radiation_model_cache() → CachedRadiationModel | None¶: Get the current radiation model cache.

voxcity.simulator_gpu.solar.integration.caching.set_radiation_model_cache(cache: CachedRadiationModel)¶: Set the radiation model cache.

voxcity.simulator_gpu.solar.integration.caching.get_building_radiation_model_cache() → CachedBuildingRadiationModel | None¶: Get the current building radiation model cache.

voxcity.simulator_gpu.solar.integration.caching.set_building_radiation_model_cache(cache: CachedBuildingRadiationModel)¶: Set the building radiation model cache.

voxcity.simulator_gpu.solar.integration.caching.get_gpu_ray_tracer_cache() → CachedGPURayTracer | None¶: Get the current GPU ray tracer cache.

voxcity.simulator_gpu.solar.integration.caching.set_gpu_ray_tracer_cache(cache: CachedGPURayTracer)¶: Set the GPU ray tracer cache.

voxcity.simulator_gpu.solar.integration.caching.get_volumetric_flux_cache() → Dict | None¶: Get the current volumetric flux cache.

voxcity.simulator_gpu.solar.integration.caching.set_volumetric_flux_cache(cache: Dict)¶: Set the volumetric flux cache.

voxcity.simulator_gpu.solar.integration.caching.get_or_create_radiation_model(voxcity, n_reflection_steps: int = 2, progress_report: bool = False, **kwargs) → Tuple[object, numpy.ndarray, numpy.ndarray]¶

Get cached RadiationModel or create a new one if cache is invalid.

The SVF and CSF matrices are O(n²) to compute and only depend on geometry, not solar position. This function caches the model for reuse.

Parameters:

voxcity – VoxCity object
n_reflection_steps – Number of reflection bounces
progress_report – Print progress messages
**kwargs – Additional RadiationConfig parameters

Returns:

Tuple of (RadiationModel, valid_ground array, ground_k array)

voxcity.simulator_gpu.solar.integration.caching.get_or_create_building_radiation_model(voxcity, n_reflection_steps: int = 2, progress_report: bool = False, building_class_id: int = -3, **kwargs) → Tuple[object, numpy.ndarray]¶

Get cached RadiationModel for building surfaces or create a new one.

Parameters:

voxcity – VoxCity object
n_reflection_steps – Number of reflection bounces
progress_report – Print progress messages
building_class_id – Building voxel class code
**kwargs – Additional RadiationConfig parameters

Returns:

Tuple of (RadiationModel, is_building_surf boolean array)

voxcity.simulator_gpu.solar.integration.caching.get_or_create_gpu_ray_tracer(voxel_data: numpy.ndarray, meshsize: float, tree_lad: float = 1.0) → CachedGPURayTracer¶: Get cached GPU ray tracer or create new one if cache is invalid.

voxcity.simulator_gpu.solar.integration.caching.get_or_create_volumetric_calculator(voxcity, n_azimuth: int = 36, n_zenith: int = 9, progress_report: bool = False, **kwargs)¶: Get cached VolumetricFluxCalculator or create a new one if cache is invalid.

voxcity.simulator_gpu.solar.integration.caching.compute_direct_transmittance_map_gpu(voxel_data: numpy.ndarray, sun_direction: Tuple[float, float, float], view_point_height: float, meshsize: float, tree_k: float = 0.6, tree_lad: float = 1.0, *, computation_mask=None) → numpy.ndarray¶: Compute direct solar transmittance map using GPU ray tracing.

voxcity.simulator_gpu.solar.integration.caching.reset_solar_taichi_cache()¶

Reset Taichi runtime and clear all solar caches.

Call this function when you encounter: - CUDA_ERROR_OUT_OF_MEMORY errors - TaichiRuntimeError: FieldsBuilder finalized

After calling this, the next solar calculation will create fresh Taichi fields.

voxcity.simulator_gpu.solar.integration.caching.clear_all_radiation_caches()¶: Clear all cached RadiationModels to free GPU memory.

voxcity.simulator_gpu.solar.integration.caching.load_voxcity(filepath)¶

Load VoxCity data from pickle file.

Attempts to use the voxcity package if available, otherwise loads as raw pickle with fallback handling.

Parameters:: filepath – Path to the VoxCity pickle file
Returns:: VoxCity object or dict containing the model data

voxcity.simulator_gpu.solar.integration.caching.convert_voxcity_to_domain(voxcity_data, default_lad: float = 2.0, land_cover_albedo: LandCoverAlbedo | None = None, origin_lat: float | None = None, origin_lon: float | None = None) → VoxCityDomainResult¶

Convert VoxCity voxel grid to palm_solar Domain with material properties.

Parameters:

voxcity_data – VoxCity object or dict from load_voxcity()
default_lad – Default Leaf Area Density for tree voxels (m²/m³)
land_cover_albedo – Custom land cover to albedo mapping
origin_lat – Override latitude (degrees)
origin_lon – Override longitude (degrees)

Returns:

VoxCityDomainResult with Domain and material information

voxcity.simulator_gpu.solar.integration.caching.apply_voxcity_albedo(model, voxcity_result: VoxCityDomainResult) → None¶

Apply VoxCity land cover-based albedo values to radiation model surfaces.

Parameters:

model – RadiationModel instance (after surface extraction)
voxcity_result – Result from convert_voxcity_to_domain()

voxcity.simulator_gpu.solar.integration.caching.create_radiation_config_for_voxcity(land_cover_albedo: LandCoverAlbedo | None = None, **kwargs)¶

Create a RadiationConfig suitable for VoxCity simulations.

Parameters:

land_cover_albedo – Land cover albedo mapping (for reference)
**kwargs – Additional RadiationConfig parameters

Returns:

RadiationConfig instance