MACE: Mendoza Automated CRYSTAL Engine

End-to-end HPC workflow automation and 3D interactive visualization suite for periodic quantum-chemistry and multiscale simulations

• An advanced automation framework designed to streamline, scale, and standardize high-throughput periodic quantum-chemistry (CRYSTAL23, Quantum ESPRESSO, PySCF) and multiscale atomistic/molecular dynamics (FF/UFF4MOF, xTB, DFTB+, MLIPs including MACE-MLIP, ORB-v3, and MatterSim, AIMD) calculations on high-performance computing clusters.

• Eliminates manual script repetition by automating the complete lifecycle: raw CIF curation, non-3D vacuum padding (slabs, polymers, molecules), symmetry analysis, supercell expansion, basis-set/functional mapping, SLURM queue optimization, automated restart/error recovery, SQLite database provenance tracking, and standardized post-processing.

• Features a dual interface: a robust Command Line Interface (CLI) for headless HPC batch automation and a high-performance 3D Graphical User Interface (GUI) (mace gui connect) for interactive structural inspection, 2D UVW plane slicing, vibrational normal-mode animation, and property analysis.

• Developers: M. Djokic, D. Maldonado-Lopez, B. Lewis, W. P. Comaskey, and J. L. Mendoza-Cortés

• Links: GitHub Repository (DjokicMa/MACE) | Zenodo Software Archive (DOI: 10.5281/zenodo.18635426)

Where to Start (Installation & Environment Setup)

• 1. Requirements: Python 3.10+, NumPy, ASE, and SciPy.

• 2. Repository Setup & Dependencies: Clone the repository and install dependencies in your user environment:
  git clone https://github.com/DjokicMa/MACE.git
  cd MACE
  pip install --user -r requirements.txt

• 3. Documentation & Tutorials: Explore detailed step-by-step workflow guides in the repository's docs/ directory.

• 4. Built-in Test Datasets: MACE includes pre-configured input/output test datasets covering porous frameworks (MOFs/COFs), dense 3D crystals, 2D slabs, 1D polymers, and molecules. (Massive raw CRYSTAL output archives and shared group wavefunctions are maintained in the Group Dropbox and Zenodo).

MACE Command Line Interface (CLI)

MACE provides an intuitive command-line parser (mace) for managing batch calculations, inspecting databases, and executing headless HPC pipelines without launching the GUI.

• Initialize a New Project / Workspace: mace init --name <project_name> --path /path/to/workspace

• Run Structure Curation & Input Generation: mace setup --cif input.cif --code crystal23 --calc opt --basis pob-TZVP

• Submit and Monitor HPCC Jobs: mace submit --job <job_name> --scheduler slurm --partition mendoza_q --exclude amr-163,amr-178,amr-179

• Execute Post-Processing & Property Extraction: mace extract --dir <output_dir> --properties bands,dos,phonons,elastic,zeo++

MACE 3D Graphical User Interface (GUI)

For interactive analysis, structural editing, and remote HPC visualization, MACE includes an advanced PyQt/OpenGL 3D workspace.

• Launch the Interactive GUI (with secure remote HPCC port-forwarding / tunnel handling): mace gui connect

• Core GUI Capabilities:

  • AutoCAD-Style 3D Inspector & Editing Tools: Interactive 3D rotation, translation, scaling, manual angle/bond length input, snap modifiers, and robust heavy-element bonding support.

  • Flexible Vacuum Configuration: Dedicated panels for configuring vacuum padding on non-3D systems (2D slabs, 1D polymers, and isolated molecules) replacing non-functional toggles.

  • Supercell & Basis Management: Flexible supercell selection dropdowns (replacing rigid 2x2x2 buttons) across geometry optimization and general property modules.

  • 2D Iso-Surface Slicing: Interactive slicing of charge density, spin density, and electrostatic potential across arbitrary UVW planes with theme visibility enhancements.

  • Vibrational Mode Analyzer: Visual inspection of vibrational normal modes with real-time amplitude scaling and built-in Animation-to-GIF Exporting.

  • Vesta-Like Powder XRD & Diffraction: Simulated PXRD patterns and structural refinement tools.

  • Pagination & Navigation: High-performance plot gallery pagination supporting over 200 items smoothly.

Detailed Pipeline Architecture (1.1.6 Workflow)

• Structure Curation & Cleaning: Automatically cleans raw CIFs, handles non-3D topologies, and manages basis set library paths with high legibility.

• Execution & Provenance: Automatically generates SLURM scripts, handles multi-user HPC port/SSH conflicts, manages scratch directories safely, and executes automated SCF/geometry error recovery and SQLite provenance tracking.

• Property & Analysis Pipelines:

  • Electronic Structure: Band structures (with automatic SeeK-path defaults) and Projected Density of States (PDOS) with clear .DAT vs .out file labeling.

  • Vibrational & Thermodynamic: Harmonic frequencies, IR/Raman intensities, and phonopy finite-displacement phonon dispersion curves.

  • Mechanical Properties: Automated calculation of elastic constants and mechanical property tensors.

  • Porous Materials Characterization: Integrated zeo++ pore-size and void-fraction calculations for MOFs and COFs.

Citing MACE

• Software: M. Djokic, D. Maldonado-Lopez, B. Lewis, W. P. Comaskey, and J. L. Mendoza-Cortés, MACE: Mendoza Automated CRYSTAL Engine, version 1.1.6, Zenodo (2026). https://doi.org/10.5281/zenodo.18635426.