ZeoMod is a high-performance Python toolkit designed for computational chemists to automate the construction of complex mesoporous zeolite models. It aims to bridge the gap between ideal crystal structures (CIF) and realistic, functionalized catalyst models.↳

By combining geometric analysis, graph-theoretic algorithms, and automated workflows, ZeoMod efficiently generates doped structures with specific pore shapes, rational surface passivation, and strict adherence to physicochemical rules (such as Löwenstein's rule).↳

• 🧠 Intelligent Supercell Construction (Proactive Supercell V3):↳
  • Automatically calculates the minimal required supercell repetition factors based on the input unit cell geometry and target pore shape, minimizing computational cost while ensuring the pore fits perfectly.↳
• 📐 Shape-Aware Sculpting:
  • Supports cutting various parameterized geometric shapes: Sphere, Cylinder, Box/Cube, and Ellipsoid.
  • Supports generating periodic mesoporous structures or non-periodic Cluster models.
• 🛡️ Smart Cleaning & Passivation:
  • Iteratively cleans unstable, low-coordination atoms resulting from cutting.
  • Collision-Free H Placement Algorithm: Uses a rotation-matrix-based search to find optimal positions for passivating protons on dangling oxygens, ensuring reasonable bond lengths, angles, and no steric clashes.
• ⚛️ Topology-Guided Doping:
  • Strict Enforcement of Löwenstein's Rule: Utilizes matscipy and sparse matrix calculations to determine graph topological distances, ensuring absolutely no Al-O-Al linkages in large, disordered supercells.
  • Flexible Doping Modes: Supports doping by target Si/Al Ratio or explicitly specifying a Fixed Count of Al atoms.
  • Automatically adds charge-balancing protons (Brønsted acid sites) to introduced framework aluminum atoms.
• ⚙️ Flexible Workflow Control:
  • Complete pipeline design allows skipping specific stages via command-line flags (e.g., cut pores only without doping, or dope an existing mesoporous structure).
  • Supports a mixed configuration mode of "YAML config file + CLI argument overrides" for batch jobs and rapid debugging.

• Python 3.8 or higher
• Installation within a separate virtual environment (conda or venv) is recommended.

Bash

# 1. Clone the repository
git clone https://github.com/Phorbol/zeomod.git
cd zeomod

# 2. Install in editable mode (allows code updates without re-installation)
pip install -e .

Once installed, the zeomod command will be registered in your system path and can be called from any directory.

Prepare a CIF file of a pure silica zeolite (e.g., MFI.cif) in your working directory.

⚠️ Important Scientific Note: To ensure charge balance and chemical rationality, it is strongly recommended to always start building from a Pure Silica framework. ZeoMod's designed workflow is to first cut pores and passivate on pure silica, and then perform controlled doping.

If you are unsure how to write the configuration, let ZeoMod generate a template for you:

Bash

zeomod --generate-template
# This generates a 'template_config.yaml' file in the current directory.
# You can rename it to 'input.yaml' and modify it.
mv template_config.yaml input.yaml

After editing input.yaml, run:

Bash

zeomod input.yaml

The program will automatically execute the supercell creation, cutting, passivation, doping, and validation processes. Results are saved in the output/ directory.

Try different parameter combinations directly via command-line arguments without modifying the YAML file:

Bash

# Quickly test cylindrical pores with different diameters
zeomod input.yaml --shape cylinder --axis z --diameter 12.0 --output run_cyl_12

# Force doping of exactly 4 Al atoms, ignoring the ratio in the config file
zeomod input.yaml --num-al 4 --output run_fixed_al4

The configuration file (input.yaml) supports rich parameter settings.

Can be overridden via CLI using --set key=value.

The zeomod command supports three levels of configuration precedence:

CLI --set > CLI Explicit Flags (--diameter, etc.) > YAML Config File > Code Defaults

Used to skip specific stages for pipelined operations:

• --skip-supercell: Skip automatic supercell creation (assumes input is already a supercell).
• --skip-cut: Skip pore cutting and passivation (assumes input already has pores).
• --skip-doping: Skip Al doping (generates pure silica mesopore only).

Example: Generate Pure Silica Mesoporous Structure Only

Bash

zeomod input.yaml --skip-doping --output pure_silica_meso

Used to dynamically modify any configuration item, including lists or booleans.

Bash

# Force specific supercell dimensions and increase Löwenstein retry attempts
zeomod input.yaml --set supercell_dims=[3,3,3] max_doping_trials=500

This project is licensed under the MIT License - see the LICENSE file for details.

• Developed by [Geng Jianrui/XMCAO Group]
• Core topology analysis powered by matscipy and scipy.sparse.↳
• Structure manipulation built upon the ASE (Atomic Simulation Environment) library.