voxcity.simulator_gpu.solar.integration.caching =============================================== .. py:module:: voxcity.simulator_gpu.solar.integration.caching .. autoapi-nested-parse:: 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 ------- .. toctree:: :hidden: /autoapi/voxcity/simulator_gpu/solar/integration/caching/LandCoverAlbedo /autoapi/voxcity/simulator_gpu/solar/integration/caching/VoxCityDomainResult /autoapi/voxcity/simulator_gpu/solar/integration/caching/CachedRadiationModel /autoapi/voxcity/simulator_gpu/solar/integration/caching/CachedBuildingRadiationModel /autoapi/voxcity/simulator_gpu/solar/integration/caching/CachedGPURayTracer .. autoapisummary:: voxcity.simulator_gpu.solar.integration.caching.LandCoverAlbedo voxcity.simulator_gpu.solar.integration.caching.VoxCityDomainResult voxcity.simulator_gpu.solar.integration.caching.CachedRadiationModel voxcity.simulator_gpu.solar.integration.caching.CachedBuildingRadiationModel voxcity.simulator_gpu.solar.integration.caching.CachedGPURayTracer Functions --------- .. autoapisummary:: voxcity.simulator_gpu.solar.integration.caching.clear_radiation_model_cache voxcity.simulator_gpu.solar.integration.caching.clear_building_radiation_model_cache voxcity.simulator_gpu.solar.integration.caching.clear_gpu_ray_tracer_cache voxcity.simulator_gpu.solar.integration.caching.clear_volumetric_flux_cache voxcity.simulator_gpu.solar.integration.caching.clear_all_caches voxcity.simulator_gpu.solar.integration.caching.clear_all_radiation_caches voxcity.simulator_gpu.solar.integration.caching.reset_solar_taichi_cache voxcity.simulator_gpu.solar.integration.caching.get_radiation_model_cache voxcity.simulator_gpu.solar.integration.caching.set_radiation_model_cache voxcity.simulator_gpu.solar.integration.caching.get_building_radiation_model_cache voxcity.simulator_gpu.solar.integration.caching.set_building_radiation_model_cache voxcity.simulator_gpu.solar.integration.caching.get_gpu_ray_tracer_cache voxcity.simulator_gpu.solar.integration.caching.set_gpu_ray_tracer_cache voxcity.simulator_gpu.solar.integration.caching.get_volumetric_flux_cache voxcity.simulator_gpu.solar.integration.caching.set_volumetric_flux_cache voxcity.simulator_gpu.solar.integration.caching.get_or_create_radiation_model voxcity.simulator_gpu.solar.integration.caching.get_or_create_building_radiation_model voxcity.simulator_gpu.solar.integration.caching.get_or_create_gpu_ray_tracer voxcity.simulator_gpu.solar.integration.caching.get_or_create_volumetric_calculator voxcity.simulator_gpu.solar.integration.caching.compute_direct_transmittance_map_gpu voxcity.simulator_gpu.solar.integration.caching.reset_solar_taichi_cache voxcity.simulator_gpu.solar.integration.caching.clear_all_radiation_caches voxcity.simulator_gpu.solar.integration.caching.load_voxcity voxcity.simulator_gpu.solar.integration.caching.convert_voxcity_to_domain voxcity.simulator_gpu.solar.integration.caching.apply_voxcity_albedo voxcity.simulator_gpu.solar.integration.caching.create_radiation_config_for_voxcity Module Contents --------------- .. py:function:: clear_radiation_model_cache() Clear the cached RadiationModel to free memory or force recomputation. .. py:function:: clear_building_radiation_model_cache() Clear the cached Building RadiationModel to free memory. .. py:function:: clear_gpu_ray_tracer_cache() Clear the cached GPU ray tracer fields to free memory or force recomputation. .. py:function:: clear_volumetric_flux_cache() Clear the cached VolumetricFluxCalculator to free memory. .. py:function:: clear_all_caches() Clear all GPU caches (RadiationModel, Building RadiationModel, GPU ray tracer, Volumetric). .. py:function:: clear_all_radiation_caches() Clear all cached RadiationModels to free GPU memory. .. py:function:: 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. .. py:function:: get_radiation_model_cache() -> Optional[CachedRadiationModel] Get the current radiation model cache. .. py:function:: set_radiation_model_cache(cache: CachedRadiationModel) Set the radiation model cache. .. py:function:: get_building_radiation_model_cache() -> Optional[CachedBuildingRadiationModel] Get the current building radiation model cache. .. py:function:: set_building_radiation_model_cache(cache: CachedBuildingRadiationModel) Set the building radiation model cache. .. py:function:: get_gpu_ray_tracer_cache() -> Optional[CachedGPURayTracer] Get the current GPU ray tracer cache. .. py:function:: set_gpu_ray_tracer_cache(cache: CachedGPURayTracer) Set the GPU ray tracer cache. .. py:function:: get_volumetric_flux_cache() -> Optional[Dict] Get the current volumetric flux cache. .. py:function:: set_volumetric_flux_cache(cache: Dict) Set the volumetric flux cache. .. py:function:: 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. :param voxcity: VoxCity object :param n_reflection_steps: Number of reflection bounces :param progress_report: Print progress messages :param \*\*kwargs: Additional RadiationConfig parameters :returns: Tuple of (RadiationModel, valid_ground array, ground_k array) .. py:function:: 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. :param voxcity: VoxCity object :param n_reflection_steps: Number of reflection bounces :param progress_report: Print progress messages :param building_class_id: Building voxel class code :param \*\*kwargs: Additional RadiationConfig parameters :returns: Tuple of (RadiationModel, is_building_surf boolean array) .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. .. py:function:: clear_all_radiation_caches() Clear all cached RadiationModels to free GPU memory. .. py:function:: 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. :param filepath: Path to the VoxCity pickle file :returns: VoxCity object or dict containing the model data .. py:function:: convert_voxcity_to_domain(voxcity_data, default_lad: float = 2.0, land_cover_albedo: Optional[LandCoverAlbedo] = None, origin_lat: Optional[float] = None, origin_lon: Optional[float] = None) -> VoxCityDomainResult Convert VoxCity voxel grid to palm_solar Domain with material properties. :param voxcity_data: VoxCity object or dict from load_voxcity() :param default_lad: Default Leaf Area Density for tree voxels (m²/m³) :param land_cover_albedo: Custom land cover to albedo mapping :param origin_lat: Override latitude (degrees) :param origin_lon: Override longitude (degrees) :returns: VoxCityDomainResult with Domain and material information .. py:function:: apply_voxcity_albedo(model, voxcity_result: VoxCityDomainResult) -> None Apply VoxCity land cover-based albedo values to radiation model surfaces. :param model: RadiationModel instance (after surface extraction) :param voxcity_result: Result from convert_voxcity_to_domain() .. py:function:: create_radiation_config_for_voxcity(land_cover_albedo: Optional[LandCoverAlbedo] = None, **kwargs) Create a RadiationConfig suitable for VoxCity simulations. :param land_cover_albedo: Land cover albedo mapping (for reference) :param \*\*kwargs: Additional RadiationConfig parameters :returns: RadiationConfig instance