AtomVoxelizer 0.1.0__tar.gz

atomvoxelizer-0.1.0/.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+

atomvoxelizer-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include .readthedocs.yaml
+include README.md
+include pyproject.toml
+recursive-include benchmarks *.py
+recursive-include docs/source *.py *.rst
+recursive-include examples *.py *.cif
+recursive-include tests *.py
+

atomvoxelizer-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: AtomVoxelizer
+Version: 0.1.0
+Summary: Periodic atom-centered voxel grids for atomistic structures.
+Author: AtomVoxelizer contributors
+Project-URL: Homepage, https://gitlab.com/tgmaxson/atomvoxelizer
+Project-URL: Documentation, https://atomvoxelizer.readthedocs.io/
+Project-URL: Repository, https://gitlab.com/tgmaxson/atomvoxelizer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Provides-Extra: numba
+Requires-Dist: numba; extra == "numba"
+Provides-Extra: cupy
+Requires-Dist: cupy; extra == "cupy"
+Requires-Dist: numba; extra == "cupy"
+Provides-Extra: taichi
+Requires-Dist: taichi; extra == "taichi"
+Provides-Extra: analysis
+Requires-Dist: scikit-image; extra == "analysis"
+Provides-Extra: examples
+Requires-Dist: ase; extra == "examples"
+Requires-Dist: requests; extra == "examples"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: ase; extra == "dev"
+Requires-Dist: numba; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: requests; extra == "dev"
+Requires-Dist: scikit-image; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: taichi; extra == "dev"
+Provides-Extra: bench
+Requires-Dist: ase; extra == "bench"
+Requires-Dist: numba; extra == "bench"
+Requires-Dist: taichi; extra == "bench"
+Provides-Extra: publish
+Requires-Dist: build; extra == "publish"
+Requires-Dist: twine; extra == "publish"
+
+# 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 from this repository:
+
+```bash
+pip install .
+```
+
+Install optional acceleration backends with extras:
+
+```bash
+pip install ".[numba]"
+pip install ".[taichi]"
+pip install ".[cupy]"
+pip install ".[analysis]"
+```
+
+`VoxelGrid` is always the NumPy backend. Optional acceleration backends are
+explicit: `VoxelGridNumba`, `VoxelGridTaichi`, and `VoxelGridCuPy`.
+`VoxelGridAnalysis` provides connected-volume and marching-cubes surface-area
+analysis when the `analysis` extra is installed.
+
+For development, examples, tests, and documentation:
+
+```bash
+pip install -e ".[dev,examples]"
+```
+
+## Basic Usage
+
+```python
+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)
+```
+
+## Zeolite Example
+
+The zeolite example and CIF files live in `examples/`.
+
+```bash
+pip install -e ".[examples]"
+python examples/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 pore volume and internal surface area:
+
+```bash
+pip install -e ".[examples,analysis]"
+python examples/zeolite_analysis.py BEA --resolution 0.25
+python examples/zeolite_analysis.py BEA --convergence 1.0 0.75 0.5 --plot bea_convergence.png
+```
+
+## Tests and Benchmarks
+
+Run the correctness tests with:
+
+```bash
+pytest
+```
+
+Run the backend benchmark with:
+
+```bash
+python benchmarks/benchmark_backends.py --backends numpy numba taichi cupy
+```
+
+Run the built-in structure benchmarks for a zeolite and a roughly 1000 atom Wulff
+construction with:
+
+```bash
+python benchmarks/benchmark_structures.py
+```
+
+Backends whose optional dependencies are not installed are reported as missing.
+
+## Documentation
+
+Documentation is scaffolded with Sphinx for Read the Docs.
+
+Build it locally with:
+
+```bash
+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:
+
+```bash
+pip install -e ".[publish]"
+python -m build
+twine check dist/*
+```
+
+Upload to TestPyPI first, then PyPI:
+
+```bash
+twine upload --repository testpypi dist/*
+twine upload dist/*
+```

atomvoxelizer-0.1.0/README.md

@@ -0,0 +1,121 @@
+# 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 from this repository:
+
+```bash
+pip install .
+```
+
+Install optional acceleration backends with extras:
+
+```bash
+pip install ".[numba]"
+pip install ".[taichi]"
+pip install ".[cupy]"
+pip install ".[analysis]"
+```
+
+`VoxelGrid` is always the NumPy backend. Optional acceleration backends are
+explicit: `VoxelGridNumba`, `VoxelGridTaichi`, and `VoxelGridCuPy`.
+`VoxelGridAnalysis` provides connected-volume and marching-cubes surface-area
+analysis when the `analysis` extra is installed.
+
+For development, examples, tests, and documentation:
+
+```bash
+pip install -e ".[dev,examples]"
+```
+
+## Basic Usage
+
+```python
+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)
+```
+
+## Zeolite Example
+
+The zeolite example and CIF files live in `examples/`.
+
+```bash
+pip install -e ".[examples]"
+python examples/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 pore volume and internal surface area:
+
+```bash
+pip install -e ".[examples,analysis]"
+python examples/zeolite_analysis.py BEA --resolution 0.25
+python examples/zeolite_analysis.py BEA --convergence 1.0 0.75 0.5 --plot bea_convergence.png
+```
+
+## Tests and Benchmarks
+
+Run the correctness tests with:
+
+```bash
+pytest
+```
+
+Run the backend benchmark with:
+
+```bash
+python benchmarks/benchmark_backends.py --backends numpy numba taichi cupy
+```
+
+Run the built-in structure benchmarks for a zeolite and a roughly 1000 atom Wulff
+construction with:
+
+```bash
+python benchmarks/benchmark_structures.py
+```
+
+Backends whose optional dependencies are not installed are reported as missing.
+
+## Documentation
+
+Documentation is scaffolded with Sphinx for Read the Docs.
+
+Build it locally with:
+
+```bash
+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:
+
+```bash
+pip install -e ".[publish]"
+python -m build
+twine check dist/*
+```
+
+Upload to TestPyPI first, then PyPI:
+
+```bash
+twine upload --repository testpypi dist/*
+twine upload dist/*
+```

atomvoxelizer-0.1.0/benchmarks/benchmark_backends.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import argparse
+import importlib
+import time
+from pathlib import Path
+
+import numpy as np
+from ase.cluster import wulff_construction
+from ase.data import covalent_radii
+from ase.io import read
+
+from atomvoxelizer import VoxelGrid
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def load_backend(name):
+    if name == "numpy":
+        return VoxelGrid
+    if name == "numba":
+        module = importlib.import_module("atomvoxelizer.numba_backend")
+        return module.VoxelGridNumba
+    if name == "taichi":
+        module = importlib.import_module("atomvoxelizer.taichi_backend")
+        return module.VoxelGridTaichi
+    if name == "cupy":
+        module = importlib.import_module("atomvoxelizer.cupy_backend")
+        return module.VoxelGridCuPy
+    raise ValueError(f"Unknown backend: {name}")
+
+
+def make_synthetic_workload(cell_length, atom_count, seed):
+    rng = np.random.default_rng(seed)
+    centers = rng.random((atom_count, 3)) * cell_length
+    radii = rng.choice(np.array([0.55, 0.75, 1.0], dtype=np.float64), size=atom_count)
+    return np.eye(3) * cell_length, centers, radii
+
+
+def make_zeolite_workload(framework, radius_scale):
+    atoms = read(ROOT / "examples" / f"{framework.upper()}.cif")
+    centers = atoms.get_positions()
+    radii = np.array([covalent_radii[atom.number] * radius_scale for atom in atoms], dtype=np.float64)
+    return atoms.cell.array, centers, radii
+
+
+def make_wulff_workload(size, radius_scale, padding):
+    atoms = wulff_construction(
+        "Pt",
+        surfaces=[(1, 0, 0), (1, 1, 0), (1, 1, 1)],
+        energies=[1.0, 1.08, 0.92],
+        size=size,
+        structure="fcc",
+        latticeconstant=3.92,
+        rounding="closest",
+    )
+    positions = atoms.get_positions()
+    positions -= positions.min(axis=0)
+    positions += padding
+    lengths = positions.max(axis=0) + padding
+    radii = np.array([covalent_radii[atom.number] * radius_scale for atom in atoms], dtype=np.float64)
+    return np.diag(lengths), positions, radii
+
+
+def make_workload(args):
+    if args.workload == "synthetic":
+        return make_synthetic_workload(args.cell_length, args.atoms, args.seed)
+    if args.workload == "zeolite":
+        return make_zeolite_workload(args.framework, args.radius_scale)
+    if args.workload == "wulff":
+        return make_wulff_workload(args.wulff_size, args.radius_scale, args.padding)
+    raise ValueError(f"Unknown workload: {args.workload}")
+
+
+def run_once(cls, cell, resolution, centers, radii):
+    grid = cls(cell=cell, resolution=resolution)
+    grid.add_spheres(centers, radii, value=1.0)
+    grid.set_spheres(centers, radii * 0.5, value=-1.0)
+    grid.clamp_grid(-1.0, 1.0)
+    synchronize = getattr(grid, "synchronize", None)
+    if synchronize is not None:
+        synchronize()
+    return grid
+
+
+def time_backend(cls, cell, resolution, centers, radii, repeats):
+    run_once(cls, cell, resolution, centers[: min(2, len(centers))], radii[: min(2, len(radii))])
+    times = []
+    grid = None
+    for _ in range(repeats):
+        start = time.perf_counter()
+        grid = run_once(cls, cell, resolution, centers, radii)
+        times.append(time.perf_counter() - start)
+    return np.array(times), grid
+
+
+def consistency_summary(values, reference):
+    occupied = int(np.count_nonzero(values))
+    total = float(values.sum())
+    if reference is None:
+        return occupied, total, 0.0
+    return occupied, total, float(np.max(np.abs(values - reference)))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Benchmark AtomVoxelizer backends.")
+    parser.add_argument("--backends", nargs="+", default=["numpy", "numba", "taichi", "cupy"])
+    parser.add_argument("--workload", choices=["synthetic", "zeolite", "wulff"], default="zeolite")
+    parser.add_argument("--resolution", type=float, default=0.25)
+    parser.add_argument("--repeats", type=int, default=3)
+    parser.add_argument("--radius-scale", type=float, default=1.0)
+    parser.add_argument("--framework", default="BEA")
+    parser.add_argument("--wulff-size", type=int, default=1000)
+    parser.add_argument("--padding", type=float, default=5.0)
+    parser.add_argument("--cell-length", type=float, default=32.0)
+    parser.add_argument("--atoms", type=int, default=512)
+    parser.add_argument("--seed", type=int, default=123)
+    args = parser.parse_args()
+
+    cell, centers, radii = make_workload(args)
+    reference = None
+
+    print(
+        "workload,backend,backend_name,atoms,gpts,best_s,mean_s,std_s,"
+        "occupied_voxels,value_sum,max_abs_diff"
+    )
+    for backend in args.backends:
+        try:
+            cls = load_backend(backend)
+            times, grid = time_backend(cls, cell, args.resolution, centers, radii, args.repeats)
+        except ImportError as exc:
+            print(f"{args.workload},{backend},missing,{len(centers)},(),nan,nan,nan,0,nan,nan # {exc}")
+            continue
+
+        values = grid.to_numpy()
+        if reference is None:
+            reference = values
+        occupied, total, max_abs_diff = consistency_summary(values, reference)
+        print(
+            f"{args.workload},{backend},{grid.backend_name},{len(centers)},"
+            f"{tuple(int(x) for x in grid.gpts)},{times.min():.6f},{times.mean():.6f},"
+            f"{times.std():.6f},{occupied},{total:.6f},{max_abs_diff:.6g}"
+        )
+
+
+if __name__ == "__main__":
+    main()
+

atomvoxelizer-0.1.0/benchmarks/benchmark_structures.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def main():
+    commands = [
+        [
+            sys.executable,
+            "benchmarks/benchmark_backends.py",
+            "--workload",
+            "zeolite",
+            "--framework",
+            "BEA",
+            "--resolution",
+            "0.25",
+            "--repeats",
+            "3",
+        ],
+        [
+            sys.executable,
+            "benchmarks/benchmark_backends.py",
+            "--workload",
+            "wulff",
+            "--wulff-size",
+            "1000",
+            "--resolution",
+            "0.35",
+            "--repeats",
+            "3",
+        ],
+    ]
+
+    for command in commands:
+        subprocess.run(command, check=True)
+
+
+if __name__ == "__main__":
+    main()
+

atomvoxelizer-0.1.0/docs/source/analysis.rst

@@ -0,0 +1,113 @@
+Analysis
+========
+
+``VoxelGridAnalysis`` provides post-processing helpers for voxel grids. The
+analysis dependency is optional because marching cubes and connected-component
+labeling use scikit-image:
+
+.. code-block:: bash
+
+   pip install ".[analysis]"
+
+Connected Volumes
+-----------------
+
+The analysis class can select voxel regions by value, label connected
+components, and convert voxel counts to physical volumes using the determinant
+of the periodic cell:
+
+.. code-block:: python
+
+   from atomvoxelizer import VoxelGridAnalysis
+
+   analysis = VoxelGridAnalysis(grid)
+   regions = analysis.analyze_regions(threshold=0.5)
+
+   for region in regions:
+       print(region.voxel_count, region.volume, region.surface_area)
+
+``volume`` is reported in cubic Angstrom when the input cell is in Angstrom.
+``surface_area`` is estimated by applying marching cubes to the selected voxel
+mask and transforming mesh vertices into real-space coordinates. By default,
+connected-component labeling and surface-area estimation apply periodic boundary
+conditions. Periodic connected components are merged across opposite cell faces;
+periodic surface areas are measured from a tiled mask and counted only for the
+central periodic image.
+
+Zeolite Pore Volume And Surface Area
+------------------------------------
+
+For zeolites, a common workflow is:
+
+1. Build an occupied framework mask from atomic cores.
+2. Analyze the inverse mask as the pore space.
+3. Sum connected-region volumes to estimate accessible pore volume.
+4. Sum marching-cubes surface areas to estimate internal surface area.
+
+Example:
+
+.. code-block:: python
+
+   from atomvoxelizer import VoxelGridAnalysis
+
+   analysis = VoxelGridAnalysis(voxel_grid)
+   pore_regions = analysis.analyze_regions(max_value=0.0)
+   pore_volume_a3 = sum(region.volume for region in pore_regions)
+   pore_area_a2 = sum(region.surface_area for region in pore_regions)
+
+   mass_amu = sum(atoms.get_masses())
+   pore_volume_cm3_g = analysis.volume_angstrom3_to_cm3_per_g(pore_volume_a3, mass_amu)
+   internal_area_m2_g = analysis.area_angstrom2_to_m2_per_g(pore_area_a2, mass_amu)
+
+The same workflow is provided as ``examples/zeolite_analysis.py``:
+
+.. code-block:: bash
+
+   python examples/zeolite_analysis.py BEA --resolution 0.25
+
+The example can also run a resolution-convergence study and save a plot:
+
+.. code-block:: bash
+
+   python examples/zeolite_analysis.py BEA --convergence 1.0 0.75 0.5 0.35 --plot bea_convergence.png
+
+Experimental Comparison
+-----------------------
+
+Experimental BET surface area and pore volume are usually reported as
+``m^2/g`` and ``cm^3/g``. Direct comparison to a geometric voxel model requires
+normalizing by the mass represented by the simulated unit cell or supercell and
+matching the experimental assumptions: framework composition, extra-framework
+cations, adsorbate probe size, activation state, defects, and whether the
+reported pore volume is micropore, mesopore, or total pore volume.
+
+AtomVoxelizer provides unit-conversion helpers once you know the mass represented
+by the simulated structure:
+
+.. code-block:: python
+
+   mass_amu = sum(atoms.get_masses())
+   pore_volume_cm3_g = analysis.volume_angstrom3_to_cm3_per_g(pore_volume_a3, mass_amu)
+   area_m2_g = analysis.area_angstrom2_to_m2_per_g(pore_area_a2, mass_amu)
+
+The comparison table should be filled with values from the specific material
+and synthesis route being modeled:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Framework
+     - Experimental BET surface area
+     - Experimental pore volume
+     - Notes
+   * - BEA
+     - source-specific
+     - source-specific
+     - Zeolite beta values depend strongly on Si/Al ratio and activation.
+   * - MWW/MCM-22
+     - source-specific
+     - source-specific
+     - MCM-22 reports often distinguish micropore and external surface area.
+
+Use the voxel result as a geometric internal-surface estimate, not as a direct
+replacement for adsorbate-specific BET analysis.

atomvoxelizer-0.1.0/docs/source/api.rst

@@ -0,0 +1,17 @@
+API Reference
+=============
+
+.. autoclass:: atomvoxelizer.VoxelGrid
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: atomvoxelizer.VoxelGridNumPy
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: atomvoxelizer.VoxelGridAnalysis
+   :members:
+   :undoc-members:
+   :show-inheritance: