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. In this case, use setenv instead of export (and omit the = sign)
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 12 and AmberTools 12 (or AmberTools 13).
Note, AmberTools 13 was released on April 22, 2013. It is fully compatible with Amber 12, and is the recommended package to use. For instructions on upgrading AmberTools 12 to AmberTools 13 if you already have AmberTools 12 unpacked, see the information here.
Before you start building Amber 12 and AmberTools 12, 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)
- flex
- X11 development files (for xleap)
- Python (for MMPBSA.py and other various utilities)
- Tkinter (for xparmed.py GUI to work)
- 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.
For those of you that have been used to Amber 11 and AmberTools 1.5 or earlier, the building process for Amber 12 and AmberTools 12, along with the patching process, should be considerably easier.
|
Table of Contents
|
Updating with Bug Fixes and Patches
It is impossible to develop a program suite as extensive as Amber and AmberTools that is guaranteed to be devoid of bugs. In reality, because Amber can do so many things, it's impossible to truly test all of its capabilities (and to catch all illegal combinations of input options). Therefore, bug fixes to the source code (analogous to Updates to other softwares like Mac OS X, Windows, etc.) are periodically released.
We recommend that you run update_amber periodically to check if new bug fixes have been issued.
All patching is handled by the update_amber script located in $AMBERHOME now. It will check the Amber website for bug fixes, download any that may be needed, and apply them. It will keep track of the patches that have been applied so you can easily find them.
By default, the configure script will check for any updates if/when you run it, and it will ask you if you want to download and apply any new updates that may be available.
Alternatively, you can use update_amber directly to interact with patches.
See which patches have already been applied
To see which patches have been applied, run
cd $AMBERHOME
./update_amber --version # was `./patch_amber.py --patch-level' for AmberTools12
And it will return the latest patches that have been applied to Amber / AmberTools 13 (or 12).
Check for updates
To check and see if any updates are available (without actually downloading and applying them), use
cd $AMBERHOME
./update_amber --check-updates [--verbose #]
This will give you information about any updates that are available. If only one or two updates are available, it will print all of the information about them. The more updates that have not yet been applied, the less information will be printed (to avoid flooding you with text). You can manually set the amount of information you get regardless of the total number of available updates by using the --verbose flag. The available numbers are
- 0 — Just show the name of the update files
- 1 — Also show the name of the programs affected
- 2 — Also show the description of what the update does
- 3 — Also prints the name of the update creator and when it was created
- 4 — Also prints the name of every modified file
Download and apply patches
To download and apply patches that are available, use
cd $AMBERHOME
./update_amber --update
This will go online, download any patches that may be available and apply them each one by one.
Note: If any updates patch update_amber or any of the modules in updateutils/, it stops applying patches so that future patches can be applied with the fixed version. If this happens, a message will be printed after it quits, describing what to do. Therefore, you should continue to run
update_amber --update
until it reports that AmberTools13 and Amber12 is up-to-date.
After applying any or all updates, AmberTools and Amber must be recompiled.
Advanced uses
There are advanced options to track patches and work with bug fixes (including non-Amber created patches). These are advanced uses of update_amber, however, so I won't get into them here.
Suffice it to say, you can use the command
update_amber --full-help
for a full statement of the program usage. If you provide no arguments, then it will print a short list of common options instead.
Working around a firewall
In some instances, computers that you wish to install Amber on may be behind a firewall that blocks access of patch_amber.py to ambermd.org.
Do you connect via Proxy Server?
If you connect via a proxy server, you need to tell update_amber that it should connect via Proxy. Furthermore, if this is an authenticated Proxy that requires a user name and password, you will also need to set up the user name of the proxy. The password is not stored anywhere for security reasons—you will simply be asked for it when update_amber tries to connect to the internet. If there is no password, just press enter when asked for your password.
See below for an example:
cd $AMBERHOME
./update_amber --proxy <proxy address>
./update_amber --proxy-user <username>
If update_amber CANNOT access the internet
To work around a firewall, you will have to set up a mirror of the bugfix website in a site that you can access (it can even just be a folder on the same machine). You can do this easily with update_amber like so:
cd $AMBERHOME
./update_amber --amber-updates=/path/to/amber/updates # you can also use another URL
./update_amber --ambertools-updates=/path/to/ambertools/updates # You can also use another URL
You can undo this by running the command
./update_amber --reset-remotes
To set up a local mirror, you must download all of the bugfix files and place them in /path/to/amber(tools)/updates/ on your local machine.
Self-congratulations
If you like this new method for working with and tracking patches, then here is where I will claim the credit for coming up with the idea and actually writing update_amber (and patch_amber.py). Ben Roberts and Tyler Luchko provided very helpful feedback and advice regarding its interface.
(There aren't too many places I can take the glory for this, so I suppose I'll take advantage of my Wiki for that purpose :) )
Basic AmberTools 12 + Amber 12 install (Serial)
Installing Amber 12 and AmberTools 12 is very easy now. It's only a single step for both AmberTools 12 and Amber 12. The instructions for building just AmberTools 12 are the same.
tar jxvf AmberTools12.tar.bz2
tar jxvf Amber12.tar.bz2
cd amber12
export AMBERHOME=`pwd`
./patch_amber.py --update-tree
./configure gnu
# If there were any updates, see the section above about applying
# updates to make sure you apply all of them.
make install
The above commands will extract the AmberTools and Amber source codes into an Amber 12 directory and properly set the AMBERHOME environment variable. Make sure that AMBERHOME is always set correctly. You can add that to your ~/.bashrc file if you want. (I typically do.)
If you wish to test this installation right now, follow these commands with
make test
For advanced users:
Also, you can use parallel make to get the installation to finish faster by using make -j. If you don't know what I'm talking about, just ignore it. For those that do, this now works, though it didn't for Amber 11 and AmberTools 1.5.
You can specify the python distribution to use via the --with-python /path/to/python command-line flag (there must be a space between them).
You can specify the NetCDF distribution to use via the --with-netcdf /path/to/netcdf/prefix command-line flag (there must be a space between them). Also, the NetCDF module file must be made with a compatible compiler. If it's not, the configure step will fail. This is due to the use of the netcdf.mod file which is compiler dependent.
Building AmberTools 12 and Amber 12 in parallel
Building in parallel requires a working MPI installation. AmberTools includes a configure_openmpi and a configure_mpich2 script to help with this, although it may be better to just let your package manager deal with it (or build your own if you know what you're doing). Remember that Amber needs the Fortran MPI libraries and routines. NOTE: If you use your package manager to install your MPI, you MUST use the GNU compilers.
If you use configure_openmpi or configure_mpich2 to build an MPI, you will need to set the LD_LIBRARY_PATH environment variable so the linker can find the MPI libraries. Somewhere in your .bashrc file, you should put the line
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH\:$AMBERHOME/lib
Common sources of error: Make sure that your MPI installation uses the same compilers that you used to build the serial versions. You can use the commands mpif90 -show and mpicc -show to see which compilers are being used. Later, you'll need to make sure that the mpirun or mpiexec you are using to run MPI versions of Amber programs are from the same package as the MPI compilers you're about to use now.
The sequence of commands below assumes that you have already set AMBERHOME properly.
cd $AMBERHOME
./configure -mpi gnu
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
make test
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 12 (pmemd.cuda Amber 12 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 this 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. And likewise, since this only deals with pmemd.cuda.
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 run-down on this capability, see http://ambermd.org/gpus/).
If you need to install the NVIDIA developer driver, 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
make test
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:
make test
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'
make test.parallel
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.
Building sander.APBS (Amber 12 only!)
Robert Konecny has written an API to provide an interface between APBS (Adaptive Poisson Boltzmann Solver — a program used to solve the Poisson Boltzmann Equation) and other molecular dynamics codes. This interface is called iAPBS.
To build sander.APBS, you first have to build apbs and iAPBS from source. You cannot use the pre-built binaries for APBS. If you have not done this yet, see the next two sub-sections, Building APBS and Building iAPBS.
After you have done that (and you have the $APBS_PREFIX environment variable set, as described in those tutorials), continue on.
Go to $AMBERHOME/src/sander and build sander.APBS
- cd $AMBERHOME/src/sander
- make clean
- make -e AMBERBUILDFLAGS="-DAPBS -lz" -e APBS_LIB=$APBS_PREFIX/lib sander.APBS
Building APBS
Make sure you follow these directions carefully, since there are a couple changes to the standard procedure.
You'll need to start by obtaining the source code for APBS (not the pre-compiled binaries, which is the first available download on the APBS Sourceforge page). You can get the latest version as of 1/1/2012 here.
You'll also need the latest iAPBS source code, which you can find here.
This assumes that you have apbs-1.3-source.tar.gz in your current directory, and that you want to install this software in ./iapbs_build
Make the iapbs_build directory and change to it, store it in a variable (since that's where we are installing apbs and iapbs), then extract the apbs source code
- mkdir iapbs_build
- cd iapbs_build
- export APBS_PREFIX=`pwd`
- tar zxvf ../apbs-1.3-source.tar.gz
Now, go to the apbs-1.3-source/ directory and run configure with the given arguments. Make sure you use all of the same arguments I use here:
- cd apbs-1.3-source/
- ./configure CC=gcc FC=gfortran F77=gfortran CFLAGS="$CFLAGS -DVAPBSQUIET" --prefix=$APBS_PREFIX --enable-apbs-quiet --disable-openmp
You can substitute ifort and icc for gfortran and gcc, respectively, if you wish to use the Intel C and Fortran compilers instead of the GNU compilers. Or you can substitute pgf77 and pgcc for gfortran and gcc, respectively, if you wish to use the PGI compilers.
Now build apbs and go back to $APBS_PREFIX to get ready for building iAPBS.
- make && make install
- cd ../
Now go on to iAPBS
Building iAPBS
Make sure you've installed APBS first, according to the instructions above. I will pick up from the last step in the APBS build (which assumes that you are in $APBS_PREFIX with $APBS_PREFIX still set)
The first thing we have to do is copy over some necessary libraries from the APBS install into the main prefix folders (particularly some libraries and some header files).
- cd $APBS_PREFIX/include
- ln -s $APBS_PREFIX/apbs-1.3-source/contrib/include/maloc
- cd $APBS_PREFIX/lib
- cp $APBS_PREFIX/apbs-1.3-source/contrib/lib/libmaloc.a .
- cp $APBS_PREFIX/apbs-1.3-source/contrib/blas/.libs/libapbsblas.a .
Next, extract iapbs-1.2.0.tgz and go to the directory it unpacks to
- cd $APBS_PREFIX
- tar zxvf iapbs-1.2.0.tgz
- cd iapbs-1.2.0/
Set up and configure iAPBS
- ./setup.sh
- ./configure CC=gcc FC=gfortran F77=gfortran CFLAGS="$CFLAGS -DVAPBSQUIET" --prefix=$APBS_PREFIX --disable-openmp
Likewise with the APBS build above, you can use icc or pgcc instead of gcc and ifort or pgf77 instead of gfortran.
Build iAPBS
- make && make install
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). Make sure you download and install the driver, too.
You may have to stop the X-server to install it. 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. Then run the installer scripts given to you by NVIDIA.
bash$ sudo /etc/init.d/gdm stop
The above should work for Ubuntu (or anything running GNOME, really, since gdm is the Gnome Desktop Manager). If you have Kubuntu (or something running KDE), you may need to use kdm instead of gdm. If you have an /etc/init.d/xdm script, you can try using that instead of gdm instead.
After this is done, you can re-open gdm/kdm/xdm if you want, or just reboot.
bash$ sudo /etc/init.d/gdm start
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:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CUDA_HOME/lib:$CUDA_HOME/lib64
Adding Amber to your Environment
This step assumes that you have already compiled every part of AmberTools and Amber that you want to use. Many programs in AmberTools require that the AMBERHOME environment variable be set, which you can do in your shell resource file (e.g. .cshrc or .bashrc).
To do this in bash, put the following in your ~/.bashrc file:
export AMBERHOME=/path/to/amber12
To do this in csh, put the following in your ~/.cshrc file:
setenv AMBERHOME "/path/to/amber12"
Furthermore, if you want to load the Amber and AmberTools programs into your current path (so that you can run pmemd by the command pmemd rather than $AMBERHOME/bin/pmemd), then add the following commands to your:
~/.bashrc (for bash, sh, etc.):
export PATH=$PATH\:$AMBERHOME/bin
~/.cshrc (for csh, tcsh, etc.):
setenv PATH "$PATH:$AMBERHOME/bin"
