As a note, this tutorial is written for bash. The only places where it really doesn't apply to csh and its derivatives are in the setting of environment variables. Setting environment variables in bash looks like
- export ENVIRONMENT_VARIABLE=some_value
Setting environment variables in csh looks like
- setenv ENVIRONMENT_VARIABLE "some_value"
If you have not set your computer up yet, and you have one of the following systems, make sure you set up your computer so you have the necessary prerequisites before trying to build Amber 14 and AmberTools 15.
Before you start building Amber 14 and AmberTools 15, make sure that you've set your computer up properly, including the necessary prerequisite packages. In particular, make sure you have
- A working Fortran compiler (gfortran, ifort, or pgf90)
- A working C compiler (gcc, icc, or pgcc)
- A working C++ compiler (g++, icpc, or pgCC)
- X11 development files (for xleap)
- patch (to apply bugfixes)
- csh (C-shell, or some variant, like tcsh, that provides a csh executable in /bin)
- GZ-compression libraries (for MTK++ and cpptraj to handle gzip-compressed files)
- BZ2-compression libraries (for cpptraj to handle bzip2-compressed files)
Most of the above pre-requisites are checked for during the configure stage, so if you don't know whether you have it or not, it's not a very big deal.
Table of Contents
Updating with Bug Fixes and Patches
Occasionally we find and fix bugs in various programs in the Amber and AmberTools suite. The utility update_amber is distributed with Amber/AmberTools in order to manage updates and bug fixes.
The configure script automatically checks for any updates that may be available and asks for permission to apply them if updates exist. We recommend you always say 'yes' to make sure you have the most up-to-date version of Amber available.
You can periodically check if there are updates available using the command
If you see that updates exist, you can simply repeat the installation procedure to make sure you have updated all parts of your code. (Don't forget to compile with the new fixes!)
You should always run this command before reporting a bug to the Amber list in case that bug has already been found and fixed.
For 99% of use-cases, updating is as easy as saying 'yes' to configure. For instances where internet access is blocked or complicated (via an authenticated proxy, for instance), visit this page for advanced instructions on using update_amber: Using update_amber.
Basic AmberTools 15 + Amber 14 install (Serial)
The following instructions will build every component that you have (AmberTools 15 and Amber 14 if you have it). Amber 14 can be added at any time.
tar jxvf AmberTools15.tar.bz2 tar jxvf Amber14.tar.bz2 cd amber14 export AMBERHOME=`pwd` ./configure gnu # We recommend you say "yes" when asked to apply updates source amber.sh # Use amber.csh if you use tcsh or csh make install echo "source $AMBERHOME/amber.sh" >> ~/.bashrc # Add Amber to your environment
The above commands will extract the AmberTools and Amber source codes into an Amber 14 directory and properly set the AMBERHOME environment variable. Make sure that AMBERHOME is always set correctly.
One change with Amber is that setting up the environment is slightly more complicated now ($AMBEHROME/lib must be added to LD_LIBRARY_PATH now). To simplify setting the environment variables for Amber, the configure script generates a set of resource scripts for either sh/bash/ksh/zsh or tcsh/csh (called amber.sh and amber.csh, respectively). These scripts will set up the environment necessary for Amber to function correctly. The last command shown above will automatically source the environment script every time a new shell is started. That step should only be done once!
If you wish to test this installation right now, follow these commands with
If you are trying to build Amber in Cygwin, there are some additional instructions. Many people (me included), think the easiest way is to use VirtualBox or some other virtual machine software to install a true Linux OS on your machine, and just run Amber on that.
If you want to use Cygwin, however, follow these commands (note the differences to above):
tar jxvf AmberTools15.tar.bz2 tar jxvf Amber14.tar.bz2 cd amber14 export AMBERHOME=`pwd` ./configure -cygwin gnu # We recommend you say "yes" when asked to apply updates source amber.sh # Use amber.csh if you use csh/tcsh make install echo "source $AMBERHOME/amber.sh" >> ~/.bashrc # Add Amber to your environment
Using a different Python
By default, configure will look for a compatible Python to use for its Python programs (ParmEd and MMPBSA.py, along with their APIs). It will look for python2.7, then python2.6, then python2.5, then python2.4, and finally settle on python if none of the others are available. If you want to use a specific Python version, you can use the --with-python </path/to/python> flag to configure to specify a particular Python version.
Note, Python 3.X is not supported by most codes currently.
Building AmberTools 15 and Amber 14 in parallel
Building in parallel requires a working MPI installation. This is the most difficult part of building Amber in parallel, and if you experience problems in this step it is likely because your MPI was either built or used incorrectly (for Amber). You must use the same compilers to build Amber that were used to build the MPI. If you are not sure which compilers were used to build the MPI, use these commands:
mpif90 -show mpicc -show
Also make sure that the mpirun and mpiexec packages come from the same place as mpif90 and mpicc.
NOTE: If you use your package manager to install your MPI, you MUST use the GNU compilers.
The sequence of commands below assumes that you have already set AMBERHOME properly.
cd $AMBERHOME ./configure -mpi gnu # cygwin users need the -cygwin flag again! make install
If you wish to test this build right now, you can set the environment variable DO_PARALLEL to specify multiple threads (e.g., export DO_PARALLEL='mpirun -np 2' or export DO_PARALLEL='mpirun -np 8') and run the command
Note, I suggest testing both 2 threads and 8 threads, since some tests require different numbers of processors. Tests with 2 and 8 threads should get almost every test. There is a section below on testing.
Building CUDA-enabled Amber 14 (pmemd.cuda Amber 14 only!)
I have never tried building pmemd.cuda or pmemd.cuda.MPI on Windows, so there will be nothing about that here. I think it is possible.
I have, however, tried building it on Mac OS X some time ago. I couldn't do it (the code has changed a lot since then, so it might be possible now). However, Apple doesn't use NVIDIA hardware much, and pmemd.cuda will not run on ATI hardware. Thus, if you are one of those few people that have a Mac with qualifying hardware, I'm sorry.
As a result of the above eliminations, this section deals with the Linux operating system only.
pmemd has been highly optimized to run very efficiently on NVIDIA hardware that supports the CUDA programming language (and has hardware double-precision support). For a summary on this capability, see http://ambermd.org/gpus/.
If you need to install the NVIDIA developer driver and CUDA toolkit, see the section dedicated to it below.
cd $AMBERHOME ./configure -cuda gnu make install
If you wish to test these programs immediately afterwards, you can run the command
which will run the CUDA tests.
Building CUDA-enabled Amber in parallel
This will allow you to run pmemd.cuda.MPI to utilize multiple GPUs for a single calculation.
Then, configure for CUDA and MPI
cd $AMBERHOME ./configure -cuda -mpi gnu make install
You should now have pmemd.cuda.MPI in $AMBERHOME/bin.
If you wish to test your installation right now, you would need to set DO_PARALLEL to specify multiple GPUs (e.g. export DO_PARALLEL='mpirun -np 2' to run on 2 GPUs), and run the command:
Testing your installation
The Amber developers have made sure that the tests all pass (or at least come close) for a variety of platforms. However, it's impossible to do an exhaustive test given the sheer number of 'compatible' operating systems (even just Linux varieties) and compilers with compiler versions. For that reason, you are strongly encouraged to run the test suite. For a modest desktop, the test suite will take roughly 1 to 1.5 hours.
You can either run the test suites as you compile, or compile everything and run the test suite later. If you are reading this, I will assume that you chose to test the installation after building everything (otherwise you have followed the full advice above when compiling).
The results from all of the tests are found in $AMBERHOME/logs/
Testing in serial
To test your installation in serial, go to $AMBERHOME and type make test.serial
Testing in parallel
These instructions are more involved than testing in serial (hard to get much easier). To test in parallel, you first need to specify how many threads you wish to test with. You do this by setting the environment variable DO_PARALLEL to contain the MPI directives to launch an MPI program. For example, common MPI implementations use the program mpirun or mpiexec.
For these systems, to test your install in parallel using 2 threads, you would go to AMBERHOME and use the commands
export DO_PARALLEL='mpirun -np 2'
You should also test with other thread counts (e.g. try 8 threads), since some tests require 4 (and even up to 8) threads to run.
Adding Amber to your Environment
Because this stage is becoming more complex as time goes on, we introduced a new environment script ($AMBERHOME/amber.sh or $AMBERHOME/amber.csh based on your shell) that will do it for you. Any necessary changes in the future will be added to this resource script so that these instructions will remain up-to-date.
Make sure the following line appears in your shell "rc" file (e.g., .bashrc or .cshrc); note that the installation instructions include a step to do this automatically
To do this in csh, put the following in your ~/.cshrc file:
Tips for Installing NVIDIA Developer Driver and CUDA Toolkit
Before installing pmemd.cuda, you need to install both the CUDA Toolkit and the CUDA developer driver for your hardware. They can be found on NVIDIA's website (http://developer.nvidia.com/cuda-downloads). As of CUDA 5.5, the driver can be installed optionally alongside the toolkit in the same package.
You may have to stop the X-server to install the driver. A quick tip to do this: press ALT-CTRL-1 to go to tty1 (this will close out the GUI, which resides on tty7). Log in, and obtain root privileges, then kill your X session. This is typically a command like one of the following:
bash$ sudo service gdm stop # For Linux distros like Ubuntu/Fedora/etc. bash$ sudo /etc/init.d/gdm stop # For OpenRC init systems bash$ sudo systemctl stop gdm # For systemd init systems
The gdm will vary from OS to OS. On Ubuntu, I think it is lightdm. For KDE, it is kdm (gdm is for GNOME). On Gentoo, it is handled by a script xdm. It is the GUI desktop manager — look for something that seems appropriate.
After you close the X-server, run the installer scripts given to you by NVIDIA. After you are done with the installer script, you can use one of the following commands:
bash$ sudo service gdm start # For Linux distros like Ubuntu/Fedora/etc. bash$ sudo /etc/init.d/gdm start # For OpenRC init systems bash$ sudo systemctl start gdm # For systemd init systems
to restart the GUI desktop manager. Alternatively, just reboot the machine.
Another common requirement for building CUDA programs is that the location of the CUDA libraries need to be made available to the linker. This is done via the LD_LIBRARY_PATH variable. Assuming you have set the CUDA_HOME environment variable (as is necessary for Amber), you should put the following line somewhere in your .bashrc file: