Installation

AutoSolvate can be installed with from source code or conda

For either approach, you want to make sure to have git and conda installed on your computer.

Dependencies

Note

Windows users: AmberTools cannot be installed from conda, and therefore cannot be automatically installed with the following approaches. AmberTools is the only dependency for Windows Users and needs separate installation.

Mac/Linux users: No dependency as long as you follow the instructions below.

  • If you install AutoSolvate from source code, you can install all dependencies automatically, which we will explain later in this document.

  • If you choose to install AutoSolvate from conda, you don’t need to worry about the dependencies of AutoSolvate because they are automatically installed.

However, if you are curious about the dependencies of AutoSolvate, please take a look at devtools/conda-envs/test_env.yaml in the AutoSolvate source code directory. This YAML file summarizes all dependencies of AutoSolvate. These packages will allow you to use most functionalities of AutoSolvate.

However, to use all functionalities of AutoSolvate, one needs to install a few other packages not included in AutoSolvate installation:

  1. If you want to solvate open-shell molecules (spin-multiplicity > 1), RESP charge fitting is needed, which uses Gaussian. Gaussian is a commercial quantum chemistry package, so you need to purchase and install separately.

  2. If you’d like to use AutoSolvate to directly drive QM/MM calculations, you need to install TeraChem. TeraChem is a commercial quantum chemistry package, so you need to purchase and install separately.

  3. AutoSolvate uses the AmberTools to run classical MD simulations without GPU acceleration. If you’d like to use the GPU accelerated version of Amber, please refer to Amber website.

From source

We recommend installing AutoSolvate from source code because of its good compatability cross operating systems, except for some Windows, which needs some extra care (more info below).

Clone the source code from github.:

>>> git clone https://github.com/Liu-group/AutoSolvate

First set up a conda environment for AutoSolvate with the needed dependencies. Go inside the AutoSolvate source code directory.

Mac/Linux users should run:

>>> conda env create -f devtools/conda-envs/test_env.yaml

Windows users should run:

>>> conda env create -f devtools/conda-envs/test_env_WIN.yaml

This will automatically create a conda environment called autosolvate. Now activate this environment:

>>> conda activate autosolvate

Stay in the AutoSolvate directory and install it:

>>> python setup.py install

Warning

Window users: Since conda installation of AmberTools is not directly available on Windnows, you will need to install AmberTools sperately from source following the instructions on Amber Documentation.

Alternatively, we may install Windows 10/11 “subsystem for Linux” (WSL/WSL2) as instructed on this Amber webpage. Once you have WSL/WSL2, you should be able to directly install AutoSolvate (including AmberTools dependencies) with the procedure described above for Linux systems.

Conda install

Note

There are known issues about conda installation of AutoSolvate on Mac with M1 chips and Windows, and one needs to take extra steps after doing the conda installation. Therefore, you are recommended to install from source

Alternative to installing from source is conda install. This works for Linux or old Mac without M1 chips. Install autosolvate as following from the commandline:

>>> conda install -c liugroupemory -c conda-forge autosolvate

To check out more about the AutoSolvate conda package, please visit this page on Anaconda.org.

Following are workarounds for Mac with M1 chips and Windows.

Mac with M1 chips:

To make the conda installation of AutoSolvate work on Mac with the M1 chip, one needs to take care of two things:

  1. Download mini-forge. Then do conda install -c liugroupemory -c conda-forge autosolvate. See more info https://stackoverflow.com/questions/65534042/anaconda-and-upgrading-to-new-m1-mac or https://towardsdatascience.com/using-conda-on-an-m1-mac-b2df5608a141.

  2. You need to do conda installation of AmberTools again by typing conda install -c conda-forge ambertools.

Windows:

You can still do conda installation of AutoSolvate on Windows, but AmberTools does not get automatically installed after you run:

>>> conda install -c liugroupemory -c conda-forge autosolvate

So you need to install AmberTools separately. You can follow the instructions here.

Check

Check your python installation. These commands in python shouldn’t give any errors:

import autosolvate
from openbabel import pybel
from openbabel import openbabel as ob

Check your ambertools and packmol installation as well:

>>> which packmol
>>> which tleap

Trouble shooting

Here we summarize some common errors reported by users and potential solutions. Please don’t hesitate to directly contact us if you find any unexpected behavior of AutoSolvate in installation or production runs.

  1. imolecule visualization problem

    We have tested the imolecule visualization functionality of AutoSolvate installed from source code and from conda, on Linux, Mac OS, and Windows 10, and expect it to work on all these platforms. However, some users have reported errors of imolecule during runtime. One potential reason for the reported imolecule problem is that imolecule is not a conda package. For installation from source, imolcule is included in the environment YAML file AutoSolvate/devtools/conda-envs/test_envs.yaml, and will be automatically downloaded without problem. However, to build it into a conda package, imolecule cannot be directly included in the conda recipe. To solve the problem, we included imolecule in setup.py as a required package, which made it automatically installed in our test cases. However, this may not work well on some operating systems.

    Possible solution: In the same conda environment where AutoSolvate is installed, please manually install imolecule by running:

    pip install imolecule