The code is an ensemble of automated QM workflows that can be run through jupyter notebooks, command lines and yaml files. Some of the most popular workflows include:

• RDKit- and CREST-based conformer generator leading to ready-to-submit QM input files starting from individual files or SMILES databases
• Post-processing of QM output files to fix convergence errors, extra imaginary frequencies, unfinished jobs, duplicates and error terminations, as well as to detect spin contamination, isomerization issues, and more optimization problems
• Analysis of homogeneity of QM calculations (same level of theory, grid size, program and version, solvation models, etc)
• Generation of xTB, DFT and RDKit descriptors in json and csv files that are ready to use in machine-learning models or used to predict NMR spectra
• More other useful workflows

Don't miss out the latest hands-on tutorials from our YouTube channel

Check our AQME installation in 2 mins video for a quick installation guide. In a nutshell, AQME and its dependencies are installed as follows:

1. Create and activate the conda environment where you want to install the program. If you are not sure of what this point means, check out the "Users with no Python experience" section. This is an example for Python 3.10, but it also works for newer Python versions (i.e., 3.11 and 3.12):

conda create -n aqme python=3.10
conda activate aqme

2. Install AQME and OpenBabel using pip:

pip install aqme
conda install -c conda-forge openbabel=3.1.1

3. (Just if the installation with pip is too slow) Users might install AQME using conda and update it with pip:

conda install -c conda-forge aqme
pip install aqme --upgrade

Extra requirements if xTB or CREST are used (compatible with MacOS and Linux only):

conda install -y -c conda-forge xtb

conda install -y -c conda-forge crest

Extra requirements if CMIN is used with ANI models:

pip install ase

pip install torch torchvision torchani

You need a Python environment to install and run AQME. These are some suggested first steps:

1. Install Anaconda with Python 3 for your operating system (Windows, macOS or Linux). Alternatively, if you're familiar with conda installers, you can install Miniconda with Python 3 (requires less space than Anaconda).

2. Open an Anaconda prompt (Windows users) or a terminal (macOS and Linux).

3. Create a conda environment called "aqme" with Python (conda create -n aqme python=3.10).
This is an example for Python 3.10, but it also works for newer Python versions (i.e., 3.11 and 3.12).

4. Activate the conda environment called "aqme" (conda activate aqme).

5. Install AQME as defined in the "Installation" section (pip install aqme).

6. Install OpenBabel as defined in the "Installation" section (conda install -c conda-forge openbabel=3.1.1).

This is the recommended option, since Jupyter Notebooks can be easily shared and reused, and the resulting QM workflows become very transparent.

7. Open the Jupyter Notebook from your file browser with Visual Studio Code (then, install the Jupyter Notebook extension), Anaconda or your favorite platform.

8. Run the code blocks inside the Jupyter Notebook, selecting the "aqme" environment when prompted.

7. Open an Anaconda prompt (Windows users) or a terminal (macOS and Linux).

8. Activate the conda environment called "aqme" (conda activate aqme).

9. Go to the folder where you want to run the program and have the input files, if any (using the "cd" command, i.e. cd C:/Users/test_aqme).

10. Run AQME as explained in the Examples Command Line section.

• Python >= 3.10
• pandas
• Numpy
• PyYAML
• progress
• cclib
• cffi
• (opt) torch, torchvision and torchani

• RDKit
• Openbabel
• xTB
• CREST

The inputs to run pre-defined AQME end-to-end workflows are available in the "/Example_workflows/End-to-end_Workflows" folder. Choose the workflow and run the inputs.

Automated protocols for individual modules and tasks are provided in the "/Example_workflows" folder inside subfolders with the corresponding module names.

Requires the pytest library.

cd path/to/aqme/source/code
pytest -v

Module on charge of conformational sampling starting from multiple input types (SMILES, csv, sdf, xyz, etc). Options:

Faster sampling, suitable especially for unimolecular systems. Options:

• RDKit standard sampling
• Systematic Unbounded Multiple Minimum search (SUMM)
• FullMonte sampling

Slower sampling, suitable for all types of systems (including noncovalent complexes and constrained systems such as transition states)

Module used to refine conformers generated in CSEARCH through new geometry optimizations. Options:

• xTB (GFN0-xTB, GFN1-xTB, GFN2-xTB, GFN-FF, etc.)
• ANI (ANI-1x, ANI-1ccx, ANI-2x, etc.)

Generator of input files for QM calculations. Options:

• Gaussian
• ORCA
• pySCF (loading parameters in jupyter notebook)

cclib-based analyzer of output files from multiple QM programs. This module:

• Separates normally terminated files with no errors, extra imaginary frequencies, duplicates, isomerization to other systems and spin contamination
• Automatically generates new com files to "fix" the different issues of the calculations with strategies that are optimal for each type of issue (Gaussian and ORCA)
• Checks that all the calculations are homogeneous (i.e. using the same level of theory, same grid size, same program and version, solvation model, etc)

Descriptor generator from multiple input types such as SMILES, log files, xyz, etc. Descriptors generated with:

• RDKit descriptors (i.e. number of polar H, number of aromatic rings, etc)
• xTB (i.e. atomic charges, molecular dipole, solvation energy, etc)
• QM programs (i.e. descriptors from cclib)

There are multiple ready-to-use workflows presented as jupyter notebooks in the in the aqme repository in Example_Workflows folder. Some examples are:

• CSEARCH_CMIN_conformer_generation folder --> CSEARCH/CMIN conformational sampling from SMILES and creation of QM input files
• QCORR_processing_QM_outputs --> QCORR analysis of Gaussian output files, generation of JSON files with all the information and creation of new QM input files
• QPREP_generating_input_files --> QPREP preparation of input files for Gaussian, ORCA and PySCF from LOG/OUT, SDF and JSON files

Conformer generation with one SMILES and name using RDKit or CREST (use rdkit or crest in --program):

python -m aqme --csearch --program rdkit --smi "CCC" --name proprane

Conformer generation with multiple SMILES and names (i.e. from a database in CSV format):

python -m aqme --csearch --program rdkit --input FILENAME.csv

Geometry optimization with xTB or ANI (use xtb or ani in --program; use sdf, xyz, com/gjf or pdb in --files):

python -m aqme --cmin --program xtb --files "*.sdf"

Input file generation from SDF, JSON and LOG/OUT files (replace "*.sdf" for the corresponding format):

python -m aqme --qprep --program gaussian --qm_input "M062x def2tzvp opt freq" --files "*.sdf"

Analysis of Gaussian output files and JSON file generation:

python -m aqme --qcorr --program gaussian --freq_conv "opt=(calcfc,maxstep=5)" --files "*.log"

More detailed examples, an API reference and the extended list of currently avaliable parameters can be found at https://aqme.readthedocs.io

List of main developers and contact emails:

• Juan V. Alegre-Requena [ ORCID , Github , email ] main developer of the CSEARCH, CMIN, QCORR, QPREP and QDESCP modules.
• Shree Sowndarya S. V. [ ORCID , Github , email] main developer of the CSEARCH, CMIN and QDESCP modules.
• Raúl Pérez-Soto [ ORCID , Github , email ] worked in refactoring the code and creating the documentation.
• Brenda Manzanilla [ webpage , Github , email] developer of the QDESCP module.
• Turki Alturaifi [ webpage , Github , email] worked in benchmarking the parameters for RDKit-based conformer generation.
• Robert S. Paton [ ORCID , Github , email] research group supervisor and code advisor.

For suggestions and improvements of the code (greatly appreciated!), please reach out through the issues and pull requests options of Github.

AQME is freely available under an MIT License

If you use any of the AQME modules, please include this citation:

• AQME v1.5, Alegre-Requena, J. V.; Sowndarya, S.; Pérez-Soto, R.; Alturaifi, T.; Paton, R. AQME: Automated Quantum Mechanical Environments for Researchers and Educators. Wiley Interdiscip. Rev. Comput. Mol. Sci. 2023, 13, e1663. (DOI: 10.1002/wcms.1663.)

Additionally, please include the corresponding references for the following programs:

• If you used CSEARCH with RDKit methods: RDKit
• If you used CSEARCH with CREST methods: CREST
• If you used CMIN with xTB: xTB
• If you used CMIN with ANI: ANI
• If you used QCORR: cclib
• If you used QDESCP with xTB: xTB