API Reference

class atomvoxelizer.VoxelGrid(cell, resolution=None, gpts=None, dtype=<class 'numpy.float32'>)

Bases: object

Periodic voxel grid implemented with NumPy only.

add_sphere(center, radius, value=1, mask='constant')

add_spheres(centers, radii, value=1, mask='constant')

backend_name = 'numpy'

clamp_grid(min_val=0.0, max_val=1.0)

div_sphere(center, radius, factor=2, mask='constant')

div_spheres(centers, radii, factor=2, mask='constant')

index_to_position(i, j, k)

Convert a grid index to the real-space voxel center.

min_sphere(center, radius, value=1, mask='distance')

min_spheres(centers, radii, value=1, mask='distance')

mul_sphere(center, radius, factor=2, mask='constant')

mul_spheres(centers, radii, factor=2, mask='constant')

plot_2D(axis='z', index=None, position=None, threshold=0.1, draw_cell=True, real_space=True)

Plot a 2D slice of the voxel grid along axis.

plot_3D(threshold=0.1, s=5, draw_cell=True)

Plot voxels with values above threshold in real space.

position_to_index(r)

Convert real-space position to voxel index using periodic wrapping.

positions_to_indices(positions)

sample_voxels_in_range(min_val=0.0, max_val=1.0, min_dist=0.0, return_indices=False, seed=None)

Yield voxel positions or indices whose values lie in [min_val, max_val].

When returning real-space positions, min_dist enforces a minimum Euclidean separation in Angstrom between yielded samples.

set_sphere(center, radius, value=1, mask='constant')

set_spheres(centers, radii, value=1, mask='constant')

to_numpy()

Return the voxel values as a NumPy array.

atomvoxelizer.VoxelGridNumPy

alias of VoxelGrid

Experimental Field Grids

These classes are experimental. The default implementation uses NumPy, and the Numba field-grid backend is available when Numba is installed. CuPy and Taichi field-grid backends are not implemented. See Concepts for the field-grid model.

class atomvoxelizer.FieldVoxelGrid(cell, resolution=None, gpts=None, dtype=<class 'numpy.float32'>, value_shape=(3, ), components=None)

Bases: VoxelGrid

Periodic voxel grid where each voxel stores an arbitrary-shaped value.

This NumPy-only prototype mirrors the geometric indexing behavior of atomvoxelizer.VoxelGrid, but stores values with shape (*gpts, *value_shape). Examples:

• value_shape=() stores scalar values.

• value_shape=(1,) stores scalar values as length-1 vectors.

• value_shape=(3,) stores real-space vectors and enables the mask="normal" sphere mask.

• value_shape=(3, 3) stores a matrix at each voxel.

add_sphere(center, radius, value=None, mask='constant')

add_spheres(centers, radii, value=None, mask='constant')

backend_name = 'numpy-field'

clamp_grid(min_val=0.0, max_val=1.0)

div_sphere(center, radius, factor=None, mask='constant')

div_spheres(centers, radii, factor=None, mask='constant')

min_sphere(center, radius, value=1, mask='constant')

min_spheres(centers, radii, value=1, mask='constant')

mul_sphere(center, radius, factor=None, mask='constant')

mul_spheres(centers, radii, factor=None, mask='constant')

normalize_values(inplace=True)

Normalize nonzero voxel values and leave zero values unchanged.

normalize_vectors(inplace=True)

Normalize nonzero voxel values.

Kept as a convenience alias for the first vector-field prototype.

plot_2D(*args, **kwargs)

Plot a 2D slice of the voxel grid along axis.

plot_3D(*args, **kwargs)

Plot voxels with values above threshold in real space.

plot_quiver_3D(stride=1, min_norm=0.0, normalize=False, ax=None, length=1.0)

Plot a sampled 3D quiver view of a three-component vector field.

plot_quiver_slice(axis='z', index=None, position=None, stride=1, min_norm=0.0, normalize=False, ax=None, scale=None)

Plot a 2D quiver slice through a three-component vector field.

quiver_3d_data(stride=1, min_norm=0.0, normalize=False)

Return 3D quiver data for a three-component vector field.

quiver_slice_data(axis='z', index=None, position=None, stride=1, min_norm=0.0, normalize=False)

Return 2D quiver data for a slice through a three-component vector field.

sample_voxels_in_range(min_val=0.0, max_val=1.0, min_dist=0.0, return_indices=False, seed=None)

Yield voxel positions or indices whose values lie in [min_val, max_val].

When returning real-space positions, min_dist enforces a minimum Euclidean separation in Angstrom between yielded samples.

scalar_values()

Return scalar values for value_shape=() or value_shape=(1,) fields.

set_sphere(center, radius, value=None, mask='constant')

set_spheres(centers, radii, value=None, mask='constant')

value_norms()

Return the Euclidean/Frobenius norm of each voxel value.

vector_norms()

Return per-voxel value norms.

Kept as a convenience alias for the first vector-field prototype.

class atomvoxelizer.VectorVoxelGrid(cell, resolution=None, gpts=None, dtype=<class 'numpy.float32'>, components=3, value_shape=None)

Bases: FieldVoxelGrid

Convenience field grid with a three-component vector value by default.

Optional Backends

These classes require their optional backend packages to be installed in the documentation/build environment.

class atomvoxelizer.VoxelGridCuPy(cell, resolution=None, gpts=None, dtype=<class 'numpy.float32'>)

Bases: VoxelGrid

CuPy-backed voxel grid.

The class keeps the same public API as atomvoxelizer.VoxelGrid, uses the Numba backend as its base when available, stores grid as a CuPy array, and overrides the mutating sphere operations.

add_sphere(center, radius, value=1, mask='constant')

add_spheres(centers, radii, value=1, mask='constant')

property backend_name

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

clamp_grid(min_val=0.0, max_val=1.0)

div_sphere(center, radius, factor=2, mask='constant')

div_spheres(centers, radii, factor=2, mask='constant')

min_sphere(center, radius, value=1, mask='distance')

min_spheres(centers, radii, value=1, mask='distance')

mul_sphere(center, radius, factor=2, mask='constant')

mul_spheres(centers, radii, factor=2, mask='constant')

set_sphere(center, radius, value=1, mask='constant')

set_spheres(centers, radii, value=1, mask='constant')

synchronize()

Synchronize the current CuPy device.

to_numpy()

Return the voxel values as a NumPy array.

Analysis

class atomvoxelizer.VoxelGridAnalysis(voxel_grid)

Bases: object

Analyze connected voxel volumes and their surfaces.

analyze_mask(selected, connectivity=1, periodic=True, surface_method='marching-cubes')

Return volume and surface area for connected regions in a boolean mask.

analyze_probe_accessibility(positions, radii, probe_radius, connectivity=1, periodic=True, surface_method='voxel-faces', write_grid=False)

Analyze probe-center accessible volume and surface area.

This is a probe-center analysis: atom exclusion radii are inflated by probe_radius and accessible voxels are positions where the probe center fits. Volumes therefore describe the region available to the probe center. Surface areas describe the boundary of that accessible center region.

analyze_regions(min_value=None, max_value=None, threshold=None, above=True, connectivity=1, periodic=True, surface_method='marching-cubes')

Return volume and marching-cubes area for each connected region.

static area_angstrom2_to_m2_per_g(area_angstrom2, mass_amu)

Convert a cell/supercell area from Angstrom^2 to m^2/g.

property cell

connected_components(selected, connectivity=1, periodic=True)

Label connected components in a boolean mask.

property gpts

property grid

mask(min_value=None, max_value=None, threshold=None, above=True)

Build a boolean mask from voxel values.

mesh_at_value(level, periodic=True, clip_periodic=True)

Return a marching-cubes mesh for a scalar voxel value.

level is interpreted in the units stored in the voxel grid. For a distance-mask grid this traces the surface at a fixed distance from the nearest atom. Vertices are returned in real-space coordinates and faces index into that vertex array. Periodic meshes are clipped to the primary cell by default so boundary-crossing triangles are cut at the cell edge instead of being wrapped across the cell.

static mesh_surface_area(vertices, faces)

Return the area of a triangular mesh.

probe_accessible_mask(positions, radii, probe_radius, write_grid=False)

Return voxels accessible to the center of a spherical probe.

positions must have shape (N, 3) and radii must contain one atom radius per position. A voxel is accessible when a probe center at that voxel does not overlap any atom, so atoms are excluded with radius radii + probe_radius.

The input voxel grid is used as the geometry template. By default, the existing grid values are not modified. Set write_grid=True to store the binary accessible mask in self.voxel_grid.grid as 1 for accessible voxels and 0 for excluded voxels.

probe_accessible_surface_area(positions, radii, probe_radius, samples_per_atom=1000, surface_radius_scale=1.0)

Estimate probe-accessible surface area by sampling inflated atom surfaces.

Points are placed deterministically on each sphere with a Fibonacci sphere rule. A sampled point contributes to the area when it does not overlap the inflated sphere around any other atom under periodic boundary conditions.

surface_radius_scale defaults to 1.0 for a hard-sphere contact surface. PoreBlazer uses 1.122 for its nitrogen accessible surface area calculation.

region_volume(selected)

Return the volume represented by a boolean mask.

surface_area(selected, periodic=True)

Estimate the surface area of a boolean region with marching cubes.

surface_area_at_value(level, periodic=True, clip_periodic=True)

Estimate the area of a scalar isosurface at level.

surface_area_voxel_faces(selected, periodic=True)

Estimate surface area by counting exposed voxel faces.

This is faster than marching cubes and avoids tiled periodic volumes. It is a grid-face estimate rather than a smoothed triangular surface, so it is most useful for fast convergence scans or large grids.

static volume_angstrom3_to_cm3_per_g(volume_angstrom3, mass_amu)

Convert a cell/supercell volume from Angstrom^3 to cm^3/g.

property voxel_volume

class atomvoxelizer.ProbeAccessibleResult(probe_radius, accessible_voxel_count, accessible_volume, accessible_surface_area, regions, accessible_mask)

Bases: object

Probe-center accessible volume and surface summary.

Parameters:

• probe_radius (float)

• accessible_voxel_count (int)

• accessible_volume (float)

• accessible_surface_area (float)

• regions (list[VoxelRegion])

• accessible_mask (ndarray)

accessible_mask: ndarray

accessible_surface_area: float

accessible_volume: float

accessible_voxel_count: int

probe_radius: float

regions: list[VoxelRegion]