Examples¶

The example scripts live in the repository under examples/. Install the example and analysis dependencies before running them:

pip install "AtomVoxelizer[examples,analysis]"

For development from source:

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

Zeolite Voxelization¶

examples/zeolite/zeolite_voxel.py reads a framework CIF with ASE, voxelizes covalent-radius shells and cores, plots slices, and benchmarks supercell scaling:

python examples/zeolite/zeolite_voxel.py BEA

For a single documentation-style slice through the framework grid:

python examples/zeolite/zeolite_slice_visual.py --framework BEA \
    --resolution 0.25 --output docs/source/_static/zeolite_voxel_slice.png

BEA zeolite voxel-grid slice showing atomic cores, void space, and coordination shell voxels

Zeolite Geometric Pore Analysis¶

examples/zeolite/zeolite_analysis.py estimates geometric pore volume and geometric internal surface area from the inverse of a framework-core mask:

python examples/zeolite/zeolite_analysis.py BEA --resolution 0.25

The result is a geometric voxel estimate. It is not a probe-accessible BET surface area and is not corrected for a finite adsorbate or solvent probe. Probe methods may be added in the future in the spirit of established porosity tools such as Zeo++ and PoreBlazer.

The convergence command below samples resolutions from 1.00 to 0.05 Angstrom in 0.05 Angstrom increments. The example uses the fast voxel-faces surface estimator by default; pass --surface-method marching-cubes for a smoother triangulated estimate on smaller grids.

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

BEA geometric pore-volume and surface-area convergence

Probe Pore Volume¶

VoxelGridAnalysis.analyze_probe_accessibility estimates probe-center accessible volume from a user-supplied grid, atomic positions, radii, and probe radius. probe_accessible_surface_area estimates sampled accessible surface area from inflated atom surfaces.

See Analysis for the method and a BEA comparison against PoreBlazer, including the PoreBlazer input files, matched AtomVoxelizer setup, timing, and agreement for probe-accessible volume and surface area.

Finite Wulff Distance Surface¶

examples/wulff/distance_surface.py builds a Wulff nanoparticle, computes a nearest-atom distance field, and exports a marching-cubes mesh at a requested distance:

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 --show

Periodic Pt(211) Distance Surface¶

examples/surfaces/pt211_distance_surface.py applies the same distance-field workflow to a periodic stepped Pt(211) slab:

python examples/surfaces/pt211_distance_surface.py --distance 1.8 --show

Periodic Pt(211) nearest-atom distance isosurface

Voxel-Guided MC Trial Moves¶

examples/mc/orb_v3_wulff_mc.py builds a cube-like WulffPack nanoparticle, constructs a coordination-surface voxel mask, samples surface trial sites, and runs a minimal Monte Carlo loop. The default score is ASE EMT; pass --score orb-v3 after installing ORB to use the optional ORB-V3 scoring hook.

python examples/mc/orb_v3_wulff_mc.py --natoms 201 --resolution 0.35 --steps 50

By default the script writes examples/mc/orb_v3_wulff_mc.traj for viewing the MC path with ASE.

The step-by-step explanation is in Quickstart Tutorial.

Benchmarks¶

Run the backend benchmark with:

python benchmarks/benchmark_backends.py --backends numpy numba taichi cupy
python benchmarks/benchmark_backends.py --zeolite-scaling --framework BEA \
    --resolution 0.5 --plot zeolite_scaling.png

Run the dtype benchmark to compare grid storage types:

python benchmarks/benchmark_dtypes.py --backend numpy
python benchmarks/benchmark_dtypes.py --backend numba