Automated Configurational Sampling and Topological Screening of Molecular Clusters
Bridging the gap between stochastic chaos and ordered chemical insight.
Manuel Gómez • Sara Gómez • Albeiro Restrepo
Química Física Teórica, Instituto de Química
Universidad de Antioquia, Colombia
ASCEC (Annealing Simulado Con Energía Cuántica) is a Python tool designed to automatically sample molecular configurational PES and perform screening of topological features.
Acting as an intelligent computational orchestrator, it pairs robust stochastic sampling (Simulated Annealing) with the COSMIC topological clustering module to automate the discovery of low-energy molecular conformations. It eliminates the tedious manual processing of thousands of configurations by automatically filtering redundancies, correcting imaginary frequencies, and refining unique minima using high-level quantum mechanical (QM) evaluations.
| Feature | Description |
|---|---|
| 🤖 Fully Automated Workflows | Execute multi-stage pipelines (Annealing → Pre-optimization → Clustering → Refinement) with a single command. |
| 🧠 Intelligent Recovery | Automatically handles calculation crashes and perturbs structures to eliminate imaginary frequencies (transition states). |
| 📊 Hierarchical Clustering | Identifies representative structures using continuous physicochemical feature vectors, with optional RMSD secondary refinement. |
| ⚡ Multi-Backend QM Support | Seamlessly interfaces with ORCA (v5.0.x and v6.1+) and Gaussian (09/16). |
| 🌐 Web Interface | Interactive browser tool to fetch molecules via PubChem, visualize the simulation box, and build input files effortlessly. |
For a comprehensive guide covering the theoretical background, detailed parameter explanations, calculation setups, and advanced tutorials (e.g., Water Hexamer and Formic Acid Dimer workflows), please consult the official User Manual:
Note
We highly recommend reviewing the Optimization Strategy and COSMIC Clustering sections in the manual to understand how to correctly select thresholds (
ASCEC requires Python 3.9+ (3.11 recommended) and utilizes an external electronic structure package (ORCA or Gaussian) as a backend.
Warning
ORCA 6.0 is not supported due to parser limitations. Please use ORCA v5.0.x or upgrade to v6.1+.
We provide a unified shell script that automates the entire setup. It will install Miniconda (if missing), set up a dedicated Python 3.11 environment (py11), install all dependencies (cclib, orca-pi, openbabel), and configure your terminal aliases. The aliases point directly to the environment's Python binary, so no manual conda activate is needed to run ascec or cosmic.
wget https://raw.githubusercontent.com/manuel2gl/qft-cosmic-ascec/main/install.shbash install.sh
source ~/.bashrcIf you prefer to manage your environments manually, you can set up ASCEC using Conda:
1. Clone the repository:
mkdir -p ~/software/ascec04
git clone https://github.com/manuel2gl/qft-cosmic-ascec.git ~/software/ascec04/2. Create and activate a clean environment:
conda create -n py11 python=3.11 -y
conda activate py113. Install dependencies:
conda install numpy scipy matplotlib scikit-learn -y
conda install -c conda-forge cclib openbabel -y
pip install orca-pi4. Set up aliases:
Add the following lines to your ~/.bashrc (or ~/.zshrc) to make the commands globally available. Use the full path to the environment's Python binary so no activation is needed:
# Replace <conda_base> with the output of: conda info --base
alias ascec='<conda_base>/envs/py11/bin/python $HOME/software/ascec04/ascec-v04.py'
alias cosmic='<conda_base>/envs/py11/bin/python $HOME/software/ascec04/cosmic-v01.py'Run source ~/.bashrc to apply the changes.
Use the ASCEC Web Generator with built-in PubChem integration to instantly get 3D coordinates and visualize your simulation box.
Alternatively, launch it directly from your terminal:
ascec inputOnce your input file (e.g., system.asc) is generated, you can validate the simulation box and launch the annealing process:
# Analyze simulation box requirements
ascec system.asc box
# Run in triplicate (r3) using a 10% effective packing box
ascec system.asc r3 --box10
# Execute the generated launcher
./launcher_ascec.shASCEC truly shines when automating the tedious optimization and clustering cycles. Define a multi-stage workflow in your input file and launch it with a single command:
ascec system.ascThe workflow will autonomously manage:
Annealing ➔ Pre-optimization (e.g., GFN2-xTB) ➔ Topological Clustering ➔ High-level DFT Refinement ➔ Final Boltzmann Analysis.
ASCEC automatically organizes your data and generates publication-ready analytics:
- 📉
tvse_*.dat / .png: Energy evolution profiles across Monte Carlo steps. - 💧
result_*.xyz: Complete trajectory files ready for visualization in Avogadro, GaussView, or IQmol. - 🌳 Dendrograms: Beautiful hierarchical tree plots (
.png) visually detailing the clustering distances of distinct structural families. - 🧮 Boltzmann Distribution: A concise
.txtsummary ranking unique configurations by their Gibbs Free Energy populations.
COSMIC ASCEC is free software distributed under the GNU General Public License (GPL) version 3. See the license file for more details.
If you use ASCEC or COSMIC in your research, please acknowledge the software and the developers. The theoretical implementation of the Modified Metropolis test and topological clustering is based on extensive prior structural studies. Please refer to the User Manual's bibliography for specific literature pertaining to the utilized algorithms.