Setup

To install/setup ASH you can either download the code from the Github repository or alternatively install via pip (see later).

ASH is 99% Python with 1 % Julia. A Python distribution (version >= 3.7 or higher) is required and you need to be able to install Python packages via package managers such as mamba/conda or pip. While primarily intended for Linux, macOS it can also run on Windows to some extent.

It is recommended to use a Miniforge/Minconda package manager to install Python and the required packages (OpenMM in particular) Some functionality (primarily the molecular crystal QM/MM part) require a Julia installation (as the Python routines will be too slow). Future versions may make the Julia interface a requirement.

Strict dependencies:

Strongly recommended (necessary for some ASH functionality):

  • geomeTRIC (Python package via pip). Required for geometry optimizations.

  • OpenMM version 7.6 or later. Required for most MM and MD functionality in ASH.

For Molecular crystal QM/MM functionality:

Recommended external QM codes (many ASH examples will use these) for basic semi-empirical and DFT calculations:

  • xTB program The semi-empirical tightbinding DFT code by Grimme and coworkers.

  • ORCA program The popular free-for-academic-use HF,DFT,WFT program by Neese and coworkers.

  • PySCF program The powerful open-source Python-based electronic structure library.

Useful libraries for specific functionality:

  • MDtraj MD trajectory analysis

  • Matplotlib library. Used to plot graphs/surfaces.

  • Scipy library. Used for interpolation routines when plotting surfaces and in molecular crystal QM/MM.

  • Plumed Plumed library

  • Parmed May be used by OpenMM interface.

  • MDAnalysis MD trajectory analysis

  • ASE Atomic Simulation Environment

A. Python environment setup

Installing Miniforge <https://github.com/conda-forge/miniforge>`_ , see also Conda-Forge downloads page is strongly recommended to handle Python and package installations (openMM in particular). This installs both the mamba and conda package manager and sets it up for use with conda-forge collection of repositories.

Here is a simple setup for a Linux x86_64 (most HPC clusters) system that you can copy-paste into your shell:

#Download Miniforge (mamba,conda)
#Sites: https://github.com/conda-forge/miniforge and https://github.com/mamba-org/mamba
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh #For Linux x86_64 version
#Install without prompt (this accepts the license). Remove -b if you want to control where it installs miniforge3
sh Miniforge3-Linux-x86_64.sh -b #creates a ~/miniforge3 directory
#Initialize mamba/conda for your shell (if desired).
~/miniforge3/bin/mamba init #This will add code to your shell-config file (.bashrc or equivalent)
#Log out and log in again to activate the new shell-config
#source-ing the shell-config file should also work:
source ~/.bashrc
#Create new environment for ASH (recommended):
mamba create --name ASH #This creates a new environment called ASH
mamba activate ASH #This activates ASH.
#Install python and numpy in the ASH environment
#Note: python 3.12 problematic at the moment
mamba config --add channels conda-forge #Add conda-forge channel
mamba install -c conda-forge python=3.11 numpy -y  #Installs approx. 50 MB of packages

Note

Note that mamba and conda are both installed by Miniforge. Mamba is a faster version of conda and is usually better behaved. They are pretty much interchangeable.

Note

If you do use a previous conda installation it is recommended to add the conda-forge channel like this : conda config --add channels conda-forge

B. The lazy/impatient way to set up ASH (easy but incomplete)

If you are impatient and want to get ASH going immediately without all features enabled. Make sure you have a suitable Python interpreter available, ideally in a conda/mamba environment (see above). For OpenMM functionality, you need to install OpenMM via conda/mamba. See section C.

Option 1:

Install ASH via pip (recommended): This will also add the Numpy and geometric dependency.

#Install ASH using pip (default main branch). Approx. 390 MB
python -m pip install git+https://github.com/RagnarB83/ash.git
#Install the NEW (development) branch of ASH. Approx. 390 MB
python -m pip install git+https://github.com/RagnarB83/ash.git@NEW

Option 2: (if you want to help develop ASH).

Download ASH from Github and set PYTHONPATH. (Don't do this if you did Option 1 above!)

#Download ASH from Github
git clone https://github.com/RagnarB83/ash.git
#Do next: git checkout NEW if you want the development branch
#Set PYTHONPATH to the ASH directory
export PYTHONPATH=/path/to/ash:$PYTHONPATH   (where /path/to/ash is the directory containing README.md)

After that (either Option 1 or 2 above), you can test ASH immediately by launching:

python # Use same python as used above! Do: which python   in shell if you are unsure

from ash import *
create_ash_env_file()  #This creates a file: set_environment_ash.sh

You can then do the following to activate the ASH environment for future shell sessions (this is easier than loading conda/mamba environment each time):

source ~/set_environment_ash.sh

Note

ASH will complain when you try to use features that require additional installations (e.g. OpenMM, julia, etc). You then have to install them via conda/mamba or pip. Note that OpenMM installation requires a conda/mamba environment. See below.

See Basic usage for information on how to use ASH, including how to submit ASH jobs to a cluster (e.g. using the subash submission script).

D. Install External Programs

See ASH-packages.sh in ASH source code directory!

Step 1. Install desired QM program(s):

Warning

Don't try to install everything all at once. Chances are you only need a select few of the QM-programs.

Examples:

  • ORCA is a recommended QM code (flexible interface in ASH). See installation instructions on the ORCA Input Library. The path to ORCA needs to be in PATH and LD_LIBRARY_PATH of your shell and later your jobscript.

  • pySCF

  • xTB

  • psi4

Some of these QM-programs are packages installable via either pip or conda/mamba:

#pySCF
python -m pip install pyscf       #PySCF QM program: http://www.pyscf.org
#xtb: semi-empirical QM
mamba install -c conda-forge xtb
#Psi4
mamba install -c psi4 psi4 #Psi4 QM program: https://psicode.org

E. Test ASH

Example ASH script to try out with an external QM code (geometry optimization of H2O using ORCA):

python first-ash-job.py

first-ash-job.py:

from ash import *

#Create H2O fragment
coords="""
O       -1.377626260      0.000000000     -1.740199718
H       -1.377626260      0.759337000     -1.144156718
H       -1.377626260     -0.759337000     -1.144156718
"""
H2O=Fragment(coordsstring=coords, charge=0, mult=1)

#Defining ORCA-related variables
orcasimpleinput="! BP86 def2-SVP def2/J tightscf"
ORCAcalc = ORCATheory(orcasimpleinput=orcasimpleinput)

#Geometry optimization
Optimizer(fragment=H2O, theory=ORCAcalc, coordsystem='tric')

This will only work if ORCA is available in the shell session. It is usually best to add PATH and LD_LIBRARY_PATH definitions for ORCA to your ~/set_environment_ash.sh file.

F. Installation problems

ASH library not found by Python interpreter

Error message:

ModuleNotFoundError: No module named 'ash'

This means that you have not correctly told your Python environment where ASH exists. If you downloaded or cloned the code you need to either do:

#Option 1: Set PYTHONPATH
export PYTHONPATH=/path/to/ash:$PYTHONPATH

#Option 2: Locally install using pip
cd /path/to/ash #Where the README.md file is located
python -m pip install .

However, it is usually better to install directly from the repository:

python -m pip install git+https://github.com/RagnarB83/ash.git

Module numpy not found

Error message:

ModuleNotFoundError: No module named 'numpy'

Your Python environment requires the numpy library to be installed. Install either via mamba/conda or pip. Make sure that you have activated your ASH environment (mamba activate ASH or conda activate ash).

OpenMM or QM/MM or MD is not working in ASH

For general MM, QM/MM and MD functionality in ASH, the OpenMM program must be available. It can be installed using mamba/conda.

mamba install -c conda-forge openmm
#or :
conda install -c conda-forge openmm

Julia-Python interface not working

ASH requires a Python-Julia library in order to enable communication between Python and Julia. The recommended option is: PythonCall/julicall

It is best to have PythonCall handle the Julia installation.

python -m pip install juliacall

Once juliacall is installed, check that it is working correctly by:

  1. Launch python interactive session :

python # in shell

  1. Run in python session:

import juliacall   #This will try to import the PythonCall/Juliacall interface, will check for Julia availability etc.
#This may take a while. Once done:
juliacall.Main.sin(34.5) #This will call the Julia sin function.

If no errors then things should be good to go for ASH.