voxcity.io¶

Persistence functions for VoxCity models and simulation results.

Provides: - save_voxcity / load_voxcity – pickle-based VoxCity model I/O - save_h5 / load_h5 – HDF5-based VoxCity model I/O (recommended) - save_results_h5 / load_results_h5 – HDF5-based combined model + results I/O

Functions¶

`load_voxcity`(input_path, *[, trusted])	Load a VoxCity instance from a file.
`save_voxcity`(output_path, city)	Save a VoxCity instance to disk.
`save_h5`(output_path, city)	Save a VoxCity model to an HDF5 file (no simulation results).
`load_h5`(input_path)	Load a VoxCity model from an HDF5 file.
`save_results_h5`(output_path, city[, ground_results, ...])	Save a VoxCity model and simulation results to an HDF5 file.
`load_results_h5`(input_path)	Load a VoxCity model and simulation results from an HDF5 file.

Module Contents¶

voxcity.io.load_voxcity(input_path, *, trusted: bool = False)[source]¶

Load a VoxCity instance from a file.

The format is detected automatically based on the file extension:

.h5 / .hdf5 → safe HDF5 format (no warning).
Anything else (e.g. .pkl) → legacy pickle format.

Warning

Pickle files can execute arbitrary code on load. Only load files you created yourself or received from a trusted source. Pass trusted=True to suppress this warning.

Parameters:

input_path (str or Path) – Path to the file.
trusted (bool, default False) – (Pickle only) Set to True to acknowledge the security implications of loading a pickle file and suppress the warning.

Return type:

VoxCity

voxcity.io.save_voxcity(output_path, city)[source]¶

Save a VoxCity instance to disk.

The format is chosen automatically based on the file extension:

.h5 / .hdf5 → safe HDF5 format (recommended).
Anything else (e.g. .pkl) → legacy pickle format.

Parameters:

output_path (str or Path) – Destination file path.
city (VoxCity) – The model to save.

voxcity.io.save_h5(output_path, city)[source]¶

Save a VoxCity model to an HDF5 file (no simulation results).

This is the recommended alternative to save_voxcity() (pickle-based) because HDF5 files cannot execute arbitrary code on load.

Parameters:

output_path (str or Path) – Destination file path (e.g. "model.h5").
city (VoxCity) – The VoxCity model instance.

See also

save_h5: Save a VoxCity model to an HDF5 file.
load_results_h5: Load a VoxCity model together with simulation results.

voxcity.io.save_results_h5(output_path, city, ground_results=None, building_results=None, simulation_results=None)[source]¶

Save a VoxCity model and simulation results to an HDF5 file.

Parameters:

output_path (str) – Destination file path (e.g. "results.h5").
city (VoxCity) – The VoxCity model instance.
ground_results (dict, optional) –
Ground-level simulation results. Keys whose values are numpy.ndarray are stored as HDF5 datasets (with gzip compression); all other JSON-serializable values are stored as group attributes.

Typical keys produced by the GPU solar integration module:
```
{
    'sunlight_hours':    np.ndarray (ny, nx),
    'cumulative_global': np.ndarray (ny, nx),
    'svf':               np.ndarray (ny, nx),
    'potential_sunlight_hours': float,
    'mode':              str,
    ...
}
```
If the input numpy array carries a .metadata dict (e.g. ArrayWithMetadata), those metadata entries are also persisted as sub-attributes.
building_results (dict, optional) –
Building-surface simulation results. The dict must contain a 'mesh' key whose value is a Trimesh object. Per-face data arrays are taken either from the 'metadata' sub-dict or directly from the Trimesh’s .metadata attribute.

Typical keys produced by the GPU solar integration module:
```
{
    'mesh': trimesh.Trimesh,
    'metadata': {
        'irradiance_direct':  np.ndarray (n_faces,),
        'irradiance_diffuse': np.ndarray (n_faces,),
        'sunlight_hours':     np.ndarray (n_faces,),
        'potential_sunlight_hours': float,
        ...
    },
}
```
If 'metadata' is not provided explicitly, the function falls back to mesh.metadata.

simulation_results (dict, optional) –

Multiple named simulation results grouped by simulation type. The recommended structure is:

{
    'ground': {
        'solar_cumulative': {'cumulative_global': array, ...},
        'sunlight_hours_dsh': {'sunlight_hours': array, ...},
    },
    'building_surface': {
        'solar_cumulative': trimesh_obj,
        'sky_view_factor': {'mesh': trimesh_obj, 'metadata': {...}},
    },
}

Supported simulation types are 'ground' and 'building_surface'. The legacy ground_results and building_results arguments remain supported for saving one unnamed/default result of each type.

Notes

Requires the h5py package (pip install h5py).
The file is self-contained – no pickle dependency at load time.
Datasets use compression='gzip' by default for compact files.

voxcity.io.load_results_h5(input_path)[source]¶

Load a VoxCity model and simulation results from an HDF5 file.

Parameters:

input_path (str) – Path to the HDF5 file created by save_results_h5().

Returns:

A dictionary with the following keys:

'voxcity': The reconstructed VoxCity instance.
'ground' (if present): dict mapping dataset names to numpy arrays, plus scalar metadata entries.
'building' (if present): dict with 'mesh_vertices', 'mesh_faces', 'mesh_face_normals' (numpy arrays) and per-face data arrays / scalar metadata.
'simulations' (if present): nested dict of named simulation results grouped by simulation type, e.g. data['simulations']['ground']['solar_cumulative'] or data['simulations']['building_surface']['sky_view_factor']. Legacy top-level 'ground' and 'building' groups are also exposed as 'default' entries in this nested structure.
'meta': dict with 'crs', 'meshsize', 'bounds'.

Return type:

dict

Notes

The returned 'voxcity' object is a fully reconstructed VoxCity dataclass – it can be passed directly to any simulator or visualizer function.