QUBEKit - Quantum Mechanical Bespoke force field toolkit

Newcastle University UK - Cole Group

| Status | | | :------ | :------ | | Foundation | | | Installation | |

Table of Contents

• What is QUBEKit?
  • Development
• Installation
  • Requirements
  • Installing as Dev
• Help
  • Config Files
  • QUBEKit Commands
    • Running Jobs
    • High Throughput
    • Custom Start and End Points
      • Single Molecules
      • Multiple Molecules
    • Checking Progress
    • Other Commands and Information

What is QUBEKit?

QUBEKit is a Python 3.7+ based force field derivation toolkit for Linux operating systems. Our aims are to allow users to quickly derive molecular mechanics parameters directly from quantum mechanical calculations. QUBEKit pulls together multiple pre-existing engines, as well as bespoke methods to produce accurate results with minimal user input. QUBEKit aims to avoid fitting to experimental data where possible while also being highly customisable.

Users who have used QUBEKit to derive force field parameters should cite the following references (also given in the CITATION.cff file):

• Exploration and validation of force field design protocols through QM-to-MM mapping
• QUBEKit: Automating the Derivation of Force Field Parameters from Quantum Mechanics
• Biomolecular Force Field Parameterization via Atoms-in-Molecule Electron Density Partitioning
• Harmonic Force Constants for Molecular Mechanics Force Fields via Hessian Matrix Projection

In Development

While QUBEKit is stable we are constantly working to improve the code and broaden its compatibilities.

We use software written by many people; if reporting a bug, please (to the best of your ability) make sure it is a bug with QUBEKit and not with a dependency. We welcome any suggestions, issues or pull requests for additions or changes.

Installation

QUBEKit is available through conda-forge; this is the recommended installation method. Github has our latest version which will likely have newer features but may not be stable.

# Recommended
conda install -c conda-forge qubekit

---

# Recommended for Developers (see below)
git clone https://github.com/qubekit/qubekit.git
cd <install location>
python setup.py develop    

Requirements

• Anaconda3

Download Anaconda from the above link and install with the linux command:

./Anaconda3<version>.sh

You may need to use chmod +x Anaconda3<version>.sh to make it executable.

We recommend you add conda to your .bashrc when prompted.

Optionally, you may choose to use Gaussian. Installation of Gaussian is likely handled by your institution. Gaussian is an option for QM optimisations, hessian calculations and density calculations. QUBEKit contains alternative approaches for these calculations.

Minimal conda packages are included in the conda-forge install with all optional engine packages left to the user to install. If there are dependency issues or version conflicts in your environment, packages can be installed individually.

conda install -c conda-forge qubekit

The following table details some optional calculation engine packages which are not included in the QUBEKit conda package and how to install them.

| Package | Conda Install | | :------ | :------ | | PSI4 >=1.4.1 | conda install -c psi4 psi4 | | Chargemol| conda install -c conda-forge chargemol | | xtb-python | conda install -c conda-forge xtb-python | | torchani | conda install -c conda-forge torchani |

Adding lots of packages can be a headache. If possible, install using Anaconda through the terminal. This is generally safest, as Anaconda should deal with versions and conflicts in your environment. Generally, conda packages will have the conda install command on their website or github. As a last resort, either git clone them and install:

git clone https://<git_address_here>
cd <location of cloned package>
python setup.py install

or follow the described steps in the respective documentation.

Installing as dev

If downloading QUBEKit to edit the latest version of the source code, the easiest method is to install via conda, then remove the conda version of qubekit and git clone. This is accomplished with a few simple commands:

# Install QUBEKit as normal
conda install -c conda-forge qubekit

# Remove ONLY the QUBEKit package itself, leaving all dependencies installed
# and on the correct version
conda remove --force qubekit

# Re-download the latest QUBEKit through github
git clone https://github.com/qubekit/qubekit.git

# Re-install QUBEKit outside of conda
cd qubekit
python setup.py develop

Help

Below is general help for most of the commands available in QUBEKit. There is some short help available through the terminal (invoked with --help). --help may be called for any command you are unsure of:

qubekit --help

---

qubekit bulk run --help

---

qubekit config create --help

All necessary long-form help is within this document.

Config files

QUBEKit has a lot of familiar settings which are used in production and changing these can result in very different force field parameters. The settings are controlled using json style config files which are easy to edit.

QUBEKit does have a full suite of defaults built in. To create a config file template with the name "example", containing default options, run the command:

qubekit config create example.json

Simply edit the sections as desired to change the method, basis set, memory, etc.

This config file can then be used to execute a QUBEKit job using the --config or -c flag in the run command.

QUBEKit Commands: Running Jobs

A single molecule job can be executed with the run command.

Some form of molecule input must also be supplied; either a file (designated with the --input-file or -i flag), or a smiles string (--smiles or -sm).

In the case of a smiles string, the molecule must also be named with the --name or -n flag.

qubekit run -i methane.pdb

qubekit run -i ethane.mol2

qubekit run -sm CO -n methanol

QUBEKit Commands: High Throughput

Bulk commands are for high throughput analyses; they are invoked with the bulk keyword. A csv file must be used when running a bulk analysis. If you would like to generate a blank csv file, simply run the command:

qubekit bulk create example.csv 

where example.csv is the name of the file you want to create. This will automatically generate a csv file with the appropriate column headers. When writing to the csv file, simply append rows after the header row with the relevant information required.*

Importantly, different config files can be supplied for each molecule in each row.

name,smiles,multiplicity