What are Cavities? — Definitions

In crystallography and materials science, the term „cavity” (or void, pore, channel) refers to empty space within a crystal structure that is not occupied by atoms. However, the exact definition depends on the method used to detect them:

1. Spherical Void (Mercury / PLATON)

The simplest definition: a cavity is a sphere that can fit into the empty space without overlapping any atom. The sphere radius is determined by the distance to the nearest atom surface (van der Waals surface). This approach:

• ✅ Fast and simple
• ❌ Only detects spherical voids
• ❌ Misses elongated, irregular, or interconnected pores
• ❌ Cannot detect channels (continuous pathways)
• ❌ Cannot determine true volume of non-spherical voids

2. Voronoi / Delaunay (ZEUS, VOIDOO)

The void space is partitioned using Voronoi or Delaunay tessellation. This approach:

• ✅ Better for irregular shapes
• ❌ Still approximates the void shape
• ❌ Complex implementation
• ❌ May miss channels in certain geometries

3. Voxel-Based (CIF v1.82 — Our Approach)

The crystal is divided into a 3D grid of voxels (volume elements). Each voxel is classified as either:

• Occupied — if it falls within the van der Waals radius of any atom
• Empty — if it is outside all atom van der Waals surfaces

Our definition of a cavity:

A cavity is any connected region of empty voxels within the crystal structure that lies outside the van der Waals surface of all atoms.

This includes:

• Closed cavities — isolated voids completely surrounded by atoms
• Channels (tunnels) — continuous pathways that run through the crystal, connecting one side of the unit cell to another
• Surface-connected cavities — voids that open to the crystal surface
• Interconnected networks — 3D pore systems

The voxel-based approach has several advantages:

• ✅ Accurately models the true shape of any void (spherical, elongated, irregular)
• ✅ Detects all channels regardless of shape
• ✅ Provides exact volume and surface area (not approximated)
• ✅ Works for all 230 space groups — from cubic to triclinic
• ✅ Supports skewed unit cells with full accuracy

---

Why CIF Instead of Mercury?

Mercury (even in its paid version) only displays spherical voids — it approximates cavities as spheres and does not detect or visualize channels. This is a severe limitation for materials with anisotropic porosity (e.g., zeolites, MOFs, 2D materials). The sphere approximation can significantly underestimate or completely miss elongated pores and interconnected channel networks.

CIF  is designed to detect all possible cavities using a robust voxel-based approach that accurately models the true shape of voids, including complex, non-spherical channels. The program provides a complete topological analysis with color-coded visualization and detailed quantitative data. The algorithm works for all 230 space groups — from the simplest cubic structures to the most complex triclinic systems — ensuring that no crystal symmetry is left unhandled.

---

Key Features

1. Full Channel Detection

Channels are detected using BFS (Breadth-First Search) with periodic boundary conditions applied to a crystal-aligned voxel grid. A channel is identified when a cavity touches two opposite walls of the unit cell and there is a continuous path between them without crossing the periodic boundary (no wrap-around).

Channels are classified by which axes they traverse:

• XX — channel along the X-axis (connects X⁻ and X⁺ walls)
• YY — channel along the Y-axis (connects Y⁻ and Y⁺ walls)
• ZZ — channel along the Z-axis (connects Z⁻ and Z⁺ walls)
• XXYY — channel in both X and Y directions
• XXZZ — channel in both X and Z directions
• YYZZ — channel in both Y and Z directions
• XXYYZZ — 3D interconnected network (all three axes)

Each cavity is color-coded by its channel type, making it easy to distinguish:

• Red = XX channel
• Green = YY channel
• Blue = ZZ channel
• Magenta = XXYY channel
• Cyan = XXZZ channel
• Yellow = YYZZ channel
• White = XXYYZZ (3D network)

2. Topology Classification

Each cavity is classified by the number of walls it touches, providing insight into its connectivity and accessibility:

Type	Name	Walls Touched	Description
0	Closed	0	Isolated void, no connection to surface or other cavities
1	Surface	1	Connected to one wall (open to surface)
2	Corridor	2	Connected to two walls (passage through the cell)
3	Corner	3	Connected to three walls (corner void)
4	Tunnel	4	Connected to four walls (through-hole)
5	Pore	5	Connected to five walls
6	Through	6	Connected to all six walls (full through-channel)

3. Skewed Voxel Grid — The Key Innovation

Unlike traditional voxel approaches that use a Cartesian grid (which introduces significant errors in non-orthogonal cells), CIF uses a crystal-aligned voxel grid where each voxel is defined directly in fractional coordinates along the actual unit cell vectors (a, b, c).

Why this matters:

In a Cartesian grid, voxels are defined by fixed X, Y, Z steps. For a triclinic cell (α ≠ β ≠ γ ≠ 90°), this creates a mismatch between the voxel grid and the actual crystal geometry. The voxel boundaries do not align with the cell walls, causing:

1. Inaccurate wall detection — voxels near skewed walls may be misclassified
2. Volume errors — the simple stepX × stepY × stepZ formula assumes orthogonality
3. False channel detection — periodic boundary wrapping fails at skewed boundaries

The CIF solution:

The voxel grid is constructed using the actual cell vectors:

Position = origin + fx × vecA + fy × vecB + fz × vecC

Where fx, fy, fz are fractional coordinates (0 to 1) and vecA, vecB, vecC are the unit cell vectors.

This ensures that:

• Voxel faces perfectly align with the cell walls — accurate wall detection
• Proper periodic wrapping — correct channel detection
• Accurate volume calculation with skew correction

The voxel volume is calculated as:

Voxel_volume = (stepX × a) × (stepY × b) × (stepZ × c) × sin(α) × sin(β) × sin(γ)

Where stepX, stepY, stepZ are the fractional steps along each axis.

4. Volume and Surface Area Calculation

Volume

The volume of each cavity is calculated as:

Volume = Number_of_voxels × Voxel_volume 

This is accurate because each voxel represents a fixed volume in fractional space, and the skew correction is already applied to the voxel volume formula.

Surface Area

Surface area is calculated from the Marching Cubes mesh using the triangle area sum:

Area = Σ(½ × |(v₁ - v₀) × (v₂ - v₀)|)

The mesh is generated from the SDF (Signed Distance Function) with a user-defined iso-level (default: 0.0). The SDF is defined as the distance from each voxel to the nearest atom surface, with negative values inside atoms and positive values in the void space.

Normal direction: The surface normals are computed from the SDF gradient and point from the cavity into the surrounding atoms (i.e., from empty space to the material), ensuring correct lighting and visual appearance.

5. Error Estimation

Volume error:

Volume_error = ½ × √(Volume × Voxel_volume)

This represents the discretization uncertainty — the error decreases with finer voxel resolution.

Surface area error:

Surface_error = 0.3 × √(Surface_area × Voxel_volume)

The surface area error is slightly larger than the volume error because it depends on the orientation of the surface relative to the voxel grid.

Error display format:
Errors are displayed in parentheses after the value (e.g., 152.17(12) means 152.17 ± 0.12). The number of digits in the parentheses matches the precision of the error.

6. Normalized Values

To enable direct comparison between different crystal structures with varying numbers of molecules per unit cell, the program calculates normalized values:

• V/N = Volume per molecule (Volume ÷ Z)
• S/N = Surface area per molecule (Surface ÷ Z)

Where Z is the number of formula units per unit cell (read directly from the CIF file). This is essential for comparing porosity across different materials.

7. Sphericity

Sphericity is a measure of how close the cavity shape is to a perfect sphere:

Sphericity = (36π × V²)^(⅓) / S

• 1.0 = perfect sphere
• < 1.0 = less spherical (elongated, irregular, or channel-like)

This parameter is useful for:

• Distinguishing between closed cavities (high sphericity) and channels (low sphericity)
• Characterizing the anisotropy of porosity
• Identifying potentially useful pore shapes for specific applications

---

Display Options

CIF v1.82 offers multiple visualization modes to suit different analysis needs:

Mode	Description	Best For
Voxel Points	Shows individual voxels as white points	Quick overview, checking detection quality
Marching Cubes Wireframe	Wireframe mesh overlay	Examining geometry, checking mesh quality
Marching Cubes Mesh	Solid mesh with full lighting	Publication-quality visualization
Cavity Color Map	Color-coded by cavity ID	Distinguishing adjacent cavities
Topology Color Map	Color-coded by topology type	Understanding connectivity and accessibility

---

Performance Optimizations

The Cavity Detector is highly optimized for speed, enabling interactive analysis of large structures:

• Parallel processing: All cavities are processed simultaneously using multi-core CPU (up to 8x speedup)
• Fast atom rejection: Binary search + 3D culling reduces atom checks by 85–95%
• Voxel hash cache: Precomputed voxel indices for O(1) access
• bool[] instead of HashSet: 3–5x faster BFS in channel detection
• Stack allocation in Marching Cubes: Reduces GC pressure by 30–50%
• Dictionary with long keys: Faster vertex merging in mesh generation

---

Supported Crystal Systems

CIF v1.82 supports all 7 crystal systems with full accuracy:

1. Cubic (a=b=c, α=β=γ=90°)
2. Tetragonal (a=b≠c, α=β=γ=90°)
3. Orthorhombic (a≠b≠c, α=β=γ=90°)
4. Hexagonal (a=b≠c, α=β=90°, γ=120°)
5. Monoclinic (a≠b≠c, α=γ=90°, β≠90°)
6. Triclinic (a≠b≠c, α≠β≠γ≠90°)
7. Rhombohedral (a=b=c, α=β=γ≠90°)

The skewed voxel grid ensures accurate results for all systems, including the most challenging triclinic cells.

---

Workflow

1. Load CIF file — The program reads the crystal structure, space group, and atom positions
2. Symmetry expansion — All symmetry-equivalent atoms are generated
3. Voxel grid creation — A crystal-aligned grid is built with user-defined resolution
4. SDF computation — The signed distance function is calculated for each voxel
5. Periodic density extraction — The central part of the grid is copied with proper periodic boundary conditions
6. Flood fill detection — Connected void regions are identified
7. Channel detection — BFS is used to find continuous paths between walls
8. Marching Cubes — Triangle meshes are generated for each cavity
9. Visualization — Cavities are displayed in 3D with full interactivity

---

Summary of Quantitative Data

For each cavity, the program provides:

Parameter	Description	Units
Volume	Total volume of the void	ų
Volume error	Discretization uncertainty	ų
Surface area	Area of the void surface	Ų
Surface error	Discretization uncertainty	Ų
V/N	Volume normalized by Z	ų/molecule
S/N	Surface area normalized by Z	Ų/molecule
Sphericity	Shape factor (1.0 = sphere)	dimensionless
Channels	Which axes are traversed	XX, YY, ZZ, etc.
Topology	Number of walls touched	0–6
Walls touched	Which walls are touched	X⁻, X⁺, Y⁻, Y⁺, Z⁻, Z⁺

---

Integration with CIF Program

The Cavity Detector is fully integrated into the CIF program:

Export-ready data: All values formatted for publication (with errors in parentheses)

Seamless workflow: CIF → Cavity Detection → Visualization

Interactive 3D view: Rotation, zoom, and selection

Real-time info panel: All cavity statistics displayed instantly

Repeat cells: Visualize cavities in supercells with arbitrary repeats

Expert 1 review:

The landscape of cavity detection is witnessing a paradigm shift, as the limitations of legacy methods—namely Voronoi and Delaunay tessellation—become increasingly apparent in the face of complex, non-orthogonal crystal systems. While traditional geometric approaches struggle to maintain both accuracy and speed in triclinic environments, this new Voxel-Based Cavity Detection Pipeline introduces a refreshing and highly efficient alternative. By employing a high-resolution grid (down to 0.1 Å) coupled with a skew-aware mapping system, the pipeline achieves an exceptional level of structural fidelity that renders classical approximations essentially obsolete.

What is truly impressive is the underlying performance architecture. By utilizing a Signed Distance Function (SDF) paired with an intelligent Fast Rejection system, the engine effectively culls 95% of redundant atom computations, allowing it to process even complex structures with the lightning-fast responsiveness seen in modern video games. The system goes beyond basic volume calculations, leveraging parallelized BFS-based Fill & Spread algorithms to provide a complete, deep-dive analysis of channel topology, connectivity, and sphericity in mere seconds. This toolset represents a clear leap forward; it successfully trades the cumbersome, graph-building overhead of legacy software for a streamlined, highly parallelized voxel grid, setting a new benchmark for speed and precision in modern crystallographic research.

Expert 2 review:

This is a remarkably well-engineered, high-performance tool for detecting cavities, voids, pores, and channels in crystallographic structures from CIF files. Written in C# and optimized for Android (as a compact APK), the project stands out as a solo-developer effort that successfully combines deep domain knowledge in crystallography with modern, performance-conscious software engineering practices.

The core innovation lies in the crystal-aligned skewed voxel grid. Instead of forcing a Cartesian grid onto potentially triclinic or monoclinic cells (which introduces significant errors in wall detection, periodic boundaries, and volume calculation), the system builds the voxel lattice directly along the unit cell vectors (a, b, c) in fractional coordinates. This, combined with proper trigonometric corrections for voxel volume, gives the tool a real advantage over many existing voxel-based or spherical-approximation solutions, especially for non-orthogonal systems. The pipeline — SDF computation, periodic flood-fill with BFS, channel topology detection, and Marching Cubes meshing — is thoughtfully designed and correctly handles periodic boundary conditions by using two separate grids (one with artificial walls for clean rendering, one open for accurate detection).

Performance is excellent. The code is full of careful optimizations: fast atom rejection using binary search and 3D culling (eliminating ~95% of checks), struct-based FastAtom arrays sorted by coordinate, stackalloc, Parallel.For with sensible Android thread limits, bool[] instead of heavier collections, and cache-friendly data layouts. As a result, even at 0.1 Å voxel resolution, the full analysis (including high-quality Marching Cubes surfaces) finishes in just a few seconds for structures with around 100 atoms on a regular phone. This level of mobile performance for such a computationally intensive scientific task is genuinely impressive and rare.

The architecture is clean and modular: VoxelScanner handles grid creation and atom preparation, CavityFillAndSpread manages flood-fill and channel detection with proper wall-touching logic, MarchingCubesMeshGenerator produces publication-ready meshes with smoothing and normal calculation, and the renderer integrates everything nicely with MonoGame-style effects. Features like automatic topology classification (0–6 walls), channel typing (XX, YY, ZZ and combinations), sphericity, normalized volumes/surfaces, and error estimation show strong scientific awareness. The color-coded visualization and supercell repeating (with correct skew transforms) make the tool very practical.

Of course, no project is perfect. There is some code duplication between modules (especially around symmetry handling and fractional normalization) that could be refactored into shared utilities. Memory management is generally good but still allocates lists and arrays in hot paths — object pooling could push performance even further on lower-end devices. Error handling and robustness for malformed CIF files could be strengthened, and while the debug logging is helpful during development, a production build would benefit from cleaner conditional compilation. Automated tests for edge cases (especially tricky periodic channels in triclinic cells) would increase confidence. Finally, the heavy dependence on MonoGame/XNA types is understandable but slightly limits easy porting to pure .NET environments.

Overall, Cavity Detector in CIF v1.82 is a high-quality, focused scientific instrument that outperforms many desktop tools in its specific strengths — particularly skewed-cell accuracy and mobile usability. The combination of correct crystallographic mathematics, game-engine-inspired rendering pipeline, and obsessive performance tuning makes it a genuinely valuable contribution to the materials science and crystallography community. For researchers working with MOFs, zeolites, or other porous materials (especially on the go), this tool can be a real game-changer.

With a bit more polishing — better documentation, public API cleanup, and open-sourcing — it has strong potential to become a respected reference implementation in the field. Respect to the author for delivering something this capable as a solo project.