AtomVoxelizer

AtomVoxelizer builds periodic atom-centered voxel grids for atomistic structures. The core VoxelGrid class stores a 3D NumPy grid over a periodic cell and provides helpers for adding, setting, scaling, sampling, and plotting spherical regions.

Installation

Install the latest released package from PyPI:

pip install AtomVoxelizer

Install from the GitLab repository for development or unreleased changes:

git clone https://gitlab.com/tgmaxson/atomvoxelizer.git
cd atomvoxelizer
pip install -e ".[dev,examples]"

Install optional acceleration backends directly if you need them:

pip install numba
pip install taichi
# Choose the CuPy package matching your CUDA runtime, for example:
pip install cupy-cuda12x
pip install ".[analysis]"
pip install ".[cpp]"

VoxelGrid is always the NumPy backend. Optional acceleration backends are explicit: VoxelGridNumba, VoxelGridCpp, VoxelGridTaichi, and VoxelGridCuPy. The C++ backend is optional and only available when the pybind11 extension was built. Use the cpp extra to request the build dependency; installation can still fall back to the pure-Python package if a compiler is unavailable.

VoxelGridAnalysis uses scikit-image for connected-volume and marching-cubes analysis when the analysis extra is installed. The examples extra installs ASE for CIF loading and Wulff construction examples.

AtomVoxelizer also includes experimental field grids for scalar, vector, and matrix-valued data at each voxel. Use FieldVoxelGrid / VectorVoxelGrid for the NumPy implementation, or FieldVoxelGridNumba / VectorVoxelGridNumba when Numba is installed.

Basic Usage

import numpy as np

from atomvoxelizer import VoxelGrid

cell = np.eye(3) * 10.0
grid = VoxelGrid(cell=cell, resolution=0.25)

grid.add_sphere(center=np.array([5.0, 5.0, 5.0]), radius=1.0, value=1.0)
grid.set_sphere(center=np.array([2.0, 2.0, 2.0]), radius=0.5, value=-1.0)
grid.clamp_grid(min_val=-1.0, max_val=1.0)

Use dtype= to choose the grid storage dtype when needed. The default is np.float32; integer dtypes are useful for count-like masks, and complex dtypes support arithmetic sphere operations but not ordered operations such as min_sphere, clamp_grid, or value-range sampling.

Sphere operations accept two masks. mask="constant" writes the supplied value or factor across the sphere. mask="distance" writes the real-space distance from the sphere center at each voxel. Combining a distance mask with min_spheres gives a nearest-atom distance field:

from atomvoxelizer import VoxelGridAnalysis

grid.grid.fill(np.inf)
grid.min_spheres(atom_positions, cutoff_radii, mask="distance")

analysis = VoxelGridAnalysis(grid)
vertices, faces = analysis.mesh_at_value(2.0, periodic=True)
surface_area = analysis.mesh_surface_area(vertices, faces)

Periodic scalar meshes are clipped at the primary cell boundary so triangles that cross a periodic boundary are cut at the cell edge.

Voxel grids can be saved as compact NumPy archives and restored later:

grid.save_npz("distance_mask.npz")
restored = VoxelGrid.from_npz("distance_mask.npz")

For visualization or downstream sampling, selected voxels can be exported as a real-space point cloud:

centers, values = grid.to_point_cloud(min_value=2.5, max_value=3.5)

VoxelGridNumba and VoxelGridCpp also support ordered operation batching for compiled mask recipes:

grid.apply_sphere_operations([
    {"operation": "add", "centers": atom_positions, "radii": 1.4 * radii, "value": 1.0},
    {"operation": "set", "centers": atom_positions, "radii": 1.1 * radii, "value": 0.0},
])

Zeolite Example

The zeolite example and CIF files live in examples/zeolite/.

pip install -e ".[examples]"
python examples/zeolite/zeolite_voxel.py BEA

The script reads a framework CIF, builds voxel grids at several resolutions, plots middle XZ slices, benchmarks supercell scaling, and opens a 3D scatter plot.

The analysis example estimates geometric pore volume and geometric internal surface area:

pip install -e ".[examples,analysis]"
python examples/zeolite/zeolite_analysis.py BEA --resolution 0.25
python examples/zeolite/zeolite_analysis.py BEA --convergence 1.00 0.95 0.90 0.85 0.80 0.75 0.70 0.65 0.60 0.55 0.50 0.45 0.40 0.35 0.30 0.25 0.20 0.15 0.10 0.05 --plot bea_convergence.png

The analysis example reports geometric voxel estimates, not probe-accessible BET surface areas. It uses a fast voxel-face surface-area estimate by default. Use --surface-method marching-cubes for a smoother marching-cubes estimate on smaller grids.

Wulff Distance-Surface Example

The Wulff example builds a nanoparticle, voxelizes the nearest-atom distance field, and exports a marching-cubes mesh at a requested distance:

pip install -e ".[examples,analysis]"
python examples/wulff/distance_surface.py --symbol Pt --size 147 --distance 2.0 --output pt_surface.npz
python examples/wulff/distance_surface.py --symbol Pt --size 147 --distance 2.0 --plot pt_surface.png
python examples/wulff/distance_surface.py --symbol Pt --size 147 --distance 2.0 --show

Periodic Surface Example

The Pt(211) example traces a periodic nearest-atom distance surface for a stepped slab:

pip install -e ".[examples,analysis]"
python examples/surfaces/pt211_distance_surface.py --distance 1.8 --show

Tests and Benchmarks

Run the correctness tests with:

pytest

Run the mask-generation benchmark with:

python benchmarks/benchmark_backends.py --workloads zeolite nanoparticle surface --plot mask_generation_scaling.png
python benchmarks/benchmark_dtypes.py --backend numpy

This benchmark scales zeolite, nanoparticle, and surface systems from small models to roughly 3000 atoms and compares a direct atom-grid distance scan with VoxelGrid NumPy, VoxelGridNumba, and VoxelGridCpp when the compiled extension is available.

Run the built-in structure benchmark helper with:

python benchmarks/benchmark_structures.py

The main benchmark compares a simple direct atom-grid distance scan with VoxelGrid NumPy, VoxelGridNumba, and VoxelGridCpp. CuPy and Taichi backends are available experimentally, but they are not the focus of the default benchmark.

Documentation

The hosted documentation is available at:

https://atomvoxelizer.readthedocs.io/en/latest/index.html

Documentation is built with Sphinx for Read the Docs.

Build it locally with:

pip install -e ".[docs]"
sphinx-build -b html docs/source docs/build/html

Read the Docs can use .readthedocs.yaml directly.

Publishing

Build and check PyPI artifacts with:

pip install -e ".[publish]"
python -m build
twine check dist/*

Upload to TestPyPI first, then PyPI:

twine upload --repository testpypi dist/*
twine upload dist/*

Repository mirror

The primary development repository is hosted on GitLab. The GitHub repository is maintained as a synchronized public mirror for archival, citation, publishing, and release purposes:

https://github.com/tgmaxson/atomvoxelizer

Please submit merge requests through the GitLab repository. GitHub issues will also be monitored, but active development happens on GitLab.