Skip to main content

How to install AmberTools (from Source)

  • Updated

AmberTools is part of the molecular dynamics (MD) simulation package “Amber.” It provides a wide range of tools useful for molecular simulation, including molecular modeling, assignment of Amber force fields, simple MD simulations, and trajectory analysis.

There are two ways to install AmberTools: (1) building it from source, and (2) installing it via conda, the Python package manager. The simplest and most reliable method is to use conda; that procedure is described in the separate article “How to install AmberTools.”

Building from source, on the other hand, has many dependencies, and if you do not have administrator (sudo) privileges you must build all of them yourself—so it takes more effort than the conda version. This article walks through how to build AmberTools from source without conda, following the actual steps. Use it as a reference when conda is not available, or when you want to build from source.

[Disclaimer] We accept no responsibility whatsoever for any malfunction or damage to your environment that may result from following the procedures described in this article. Please proceed at your own risk, with this understanding.

About the target environment

Matlantis is a JupyterLab-style computing environment that you access from your browser. This environment has several constraints, and the procedures in this article assume the following:

  • No administrator (sudo) privileges → You build any missing dependencies yourself.
  • Outbound network access may be restricted → For files you cannot download directly, bring them in by uploading them or using git clone. For example, Homebrew (brew) cannot be used in this environment because it tries to fetch the files it needs from ghcr.io and the connection is blocked.
  • The CPU architecture is x86_64 → Use the Linux x86_64 build for any binaries or sources you download.

The runtime environment may change as the service is updated. Please verify the actual behavior in your own environment.

Before you start: assumptions for this method

AmberTools is written in C / C++ / Fortran, so building it requires C/C++/Fortran compilers (gcc / g++ / gfortran) and make / cmake, plus tools such as flex / bison / bc. In addition, cpptraj and others need the zlib / bzip2 development headers in order to handle gzip- and bzip2-compressed trajectories, and bison uses m4 internally. In an environment like Matlantis, where you have no administrator (sudo) privileges and direct downloads from the outside are restricted, keeping the following in mind will make things go smoothly:

  • Build any missing tools or libraries from source into your home directory (~/.local) rather than with sudo apt.
  • When direct downloads from external sites (curl / wget) are restricted, you can bring files in by downloading them on your local PC and dragging and dropping them into the JupyterLab file browser to upload them.
  • Install everything under your home directory. On Matlantis the home directory is persisted, so it remains even after you restart your session.

This article uses ~/software as the working directory. All commands below are assumed to be run in the JupyterLab terminal (PATH and environment variables are appended to .bashrc to make them persistent).

$ mkdir -p ~/software && cd ~/software

Step 1: Check the build tools

First, check whether the necessary tools are available.

$ for t in gcc g++ gfortran make cmake flex bison patch tcsh bc m4; do
    printf '%-10s ' "$t"; command -v "$t" || echo "NOT FOUND"
  done

Next, also check whether the zlib / bzip2 development headers can be found.

# Check whether the zlib / bzip2 development headers can be found
$ for h in zlib.h bzlib.h; do
    printf '%-10s ' "$h"
    echo "#include <$h>" | gcc -E - >/dev/null 2>&1 && echo OK || echo "NOT FOUND"
  done

If gcc / g++ / gfortran / make / cmake and so on are present, the build prerequisites are satisfied (the Fortran compiler gfortran in particular is required). If flex / bison / bc / m4 show NOT FOUND, or if zlib.h / bzlib.h show NOT FOUND, you will install them in Step 2. If everything is already present, you can skip Step 2.

This article takes the approach of building only the minimum set of tools needed to run AmberTools 26.

Step 2: Install the missing dependencies (flex / bison / bc / m4 / zlib / bzip2)

Because sudo is not available, build the missing pieces into ~/.local. Putting ~/.local/bin at the front of your PATH first makes the subsequent builds less likely to trip up (especially where bison needs to reference m4).

$ export PATH=$HOME/.local/bin:$PATH

Below, you only need to install the items that were NOT FOUND in Step 1.

Installing bc

Fetch a low-dependency implementation with git clone and build it.

$ cd ~/software    # move to the working directory
$ git clone https://github.com/gavinhoward/bc.git
$ cd bc
$ PREFIX="$HOME/.local" ./configure.sh
$ make -j2 && make install

Note: A locale warning appears, but you can ignore it for this installation. Be aware, however, that multilingual display features are expected to be unavailable as a result.

Installing bison / flex

Use the release tarballs (which include configure). If you cannot download them directly, download the following on your local PC and upload them to ~/software via JupyterLab. Because bison requires m4 at runtime, prepare m4 first.

  • bison: https://ftp.gnu.org/gnu/bison/bison-3.8.2.tar.gz
  • flex: https://github.com/westes/flex/releases/download/v2.6.4/flex-2.6.4.tar.gz

Once they are uploaded, extract and build them.

$ cd ~/software         # move to the working directory
$ ls -lh bison*.tar.gz  # confirm the upload
$ tar xvzf bison-3.8.2.tar.gz && cd bison-3.8.2
$ ./configure --prefix=$HOME/.local && make -j2 && make install
 
$ cd ~/software         # move to the working directory
$ ls -lh flex*.tar.gz   # confirm the upload
$ tar xvzf flex-2.6.4.tar.gz && cd flex-2.6.4
$ ./configure --prefix=$HOME/.local && make -j2 && make install

Installing m4 (only if NOT FOUND)

m4 is a tool that bison uses internally. Only if it was NOT FOUND, download the release tarball on your local PC, upload it to ~/software, and then build it.

  • m4: https://ftp.gnu.org/gnu/m4/m4-1.4.19.tar.gz 
$ cd ~/software         # move to the working directory
$ ls -lh m4*.tar.gz     # confirm the upload
$ tar xzf m4-1.4.19.tar.gz && cd m4-1.4.19
$ ./configure --prefix=$HOME/.local && make -j2 && make install

Installing zlib / bzip2 (only if NOT FOUND)

These are used by cpptraj and others to handle gzip- and bzip2-compressed trajectories. Only if the header check in Step 1 returned NOT FOUND, download the following on your local PC, upload them to ~/software, and build them.

  • zlib: https://zlib.net/zlib-1.3.1.tar.gz
  • bzip2: https://sourceware.org/pub/bzip2/bzip2-1.0.8.tar.gz 
$ cd ~/software         # move to the working directory
$ ls -lh zlib*.tar.gz   # confirm the upload
$ tar xvzf zlib-1.3.1.tar.gz && cd zlib-1.3.1
$ ./configure --prefix=$HOME/.local && make -j2 && make install
 
$ cd ~/software         # move to the working directory
$ ls -lh bzip*.tar.gz   # confirm the upload
$ tar xvzf bzip2-1.0.8.tar.gz && cd bzip2-1.0.8
$ make -j2 && make install PREFIX=$HOME/.local

Setting PATH / LD_LIBRARY_PATH

Add ~/.local/bin to PATH and ~/.local/lib to LD_LIBRARY_PATH, and write the settings into .bashrc as well (if you built zlib / bzip2 into ~/.local, set LD_LIBRARY_PATH too, so that the shared libraries can be found at runtime).

$ export PATH=$HOME/.local/bin:$PATH
$ export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
$ echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
$ echo 'export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH' >> ~/.bashrc
$ hash -r
 
# OK if ~/.local/bin/... is shown
$ for t in flex bison bc; do printf '%-8s ' "$t"; command -v "$t" || echo "NOT FOUND"; done

Step 3: Get the AmberTools source

You can download the AmberTools source from the official site after registering (name, email address, affiliation, and so on). Download the AmberTools tar.bz2 (e.g., AmberTools26.tar.bz2) on your local PC and upload it to ~/software using the JupyterLab file browser.

Confirm the upload and extract it.

$ cd ~/software                     # move to the working directory
$ ls -lh *.tar.bz2                  # confirm the upload
$ tar xvjf AmberTools26.tar.bz2     # → expands into ambertools26_src/
$ ls -d */                          # check the extracted folder name

Step 4: Build and install

Run CMake in the build/ directory of the extracted source. Here the install destination is ~/software/amber26 (any location is fine).

$ cd ~/software/ambertools26_src/build
 
$ cmake .. \
    -DCMAKE_INSTALL_PREFIX=$HOME/software/amber26 \
    -DCMAKE_PREFIX_PATH=$HOME/.local \
    -DCOMPILER=GNU \
    -DMPI=FALSE \
    -DCUDA=FALSE \
    -DINSTALL_TESTS=FALSE \
    -DDOWNLOAD_MINICONDA=FALSE \
    -DBUILD_PYTHON=FALSE
 
$ make -j2 install

There are three key points:

  • -DDOWNLOAD_MINICONDA=FALSE: If you leave this as TRUE (the default), the build will try to download Miniconda from the outside partway through, and it will fail in a network-restricted environment. Be sure to set it to FALSE.
  • -DBUILD_PYTHON=FALSE: Building without the Python tools first is more reliable and less likely to trip over dependencies. If you need Python tools such as pytraj, parmed, or MMPBSA.py, see the note below.
  • -DCMAKE_PREFIX_PATH=$HOME/.local: This tells CMake to reliably reference the bison / flex / zlib / bzip2 that you built into ~/.local in Step 2. If CMake cannot find bison / flex, additionally specify -DBISON_EXECUTABLE=$HOME/.local/bin/bison and -DFLEX_EXECUTABLE=$HOME/.local/bin/flex.

Once the build and install are complete, load the environment settings and append them to .bashrc as well.

$ source $HOME/software/amber26/amber.sh
$ echo 'source $HOME/software/amber26/amber.sh' >> ~/.bashrc

Note: If you want to change the install destination (prefix) later, you cannot move or rename the folder with mv (because absolute paths are written into files such as amber.sh). Instead, change -DCMAKE_INSTALL_PREFIX and re-run cmake → make install. Recompilation is not required—it is mainly relinking and copying, so it finishes quickly.

Note (if you need the Python tools): If you want to use pytraj, parmed, MMPBSA.py, and so on, build with -DBUILD_PYTHON=TRUE. Even then, keep -DDOWNLOAD_MINICONDA=FALSE, and have the build use an existing Python that already has numpy / cython and the like installed (specify it explicitly, e.g., -DPYTHON_EXECUTABLE=$(which python)). However, because dependency resolution on the Python side tends to be error-prone, if the Python tools are your main goal, using the conda version of AmberTools is more reliable.

Step 5: Verify the installation

To confirm that the installation completed correctly, run a few representative commands.

# Check that AMBERHOME is set correctly
$ echo $AMBERHOME
 
# Show the tleap help
$ tleap -h
 
# Show the cpptraj version
$ cpptraj --version

If the commands above run without errors and display help messages or version information (for example, CPPTRAJ: Version V7.6.2 (AmberTools)), the installation was successful.

Note that tleap and xleap are wrapper scripts that call the underlying teLeap, so it is not abnormal for them to be only a few hundred bytes in size (they are working correctly as long as -h shows help). On the other hand, antechamber, parmchk2, sqm, and cpptraj are compiled executables and should normally be of a correspondingly larger size. If any of these are only a few hundred bytes, the build or linking may have failed, so check whether -h or --version works correctly.

Summary

  • Install destination: ~/software/amber26 (AMBERHOME)
  • Build tools / libraries (flex / bison / bc, plus m4 / zlib / bzip2 as needed): built yourself into ~/.local
  • Key build settings: DOWNLOAD_MINICONDA=FALSE / BUILD_PYTHON=FALSE / COMPILER=GNU / CMAKE_PREFIX_PATH=~/.local
  • If you cannot download directly: download on your local PC → upload via JupyterLab, or use git clone

Related to

Related articles