Sandia National Laboratories Tramonto

Installation Guide

This page contains instructions for building Tramonto 4.0. Click the following links for archived build instructions: Tramonto v3.x.

Click on a link below for printer-friendly Tramonto installation guides:

# Tramonto: A molecular theory code for structured and uniform fluids
#                 Copyright (2006) Sandia Corporation
#
# Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
# license for use of this work by or on behalf of the U.S. Government.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public License
# as published by the Free Software Foundation; either version 2.1
# of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
# 02110-1301, USA.

                       How to Build Tramonto 4.0

Note:

    When accessing these instructions from the website, it is a good idea
    to verify that you have the version of the instructions that corresponds
    to your version of Tramonto.  The correct version of the instructions can
    always be found in the README file in the top level directory of a Tramonto
    tarball, or a checked out copy of the Tramonto source code repository.

Contents:
    Prerequisites
    Building Trilinos
    Building Tramonto
    Building Trilinos and Tramonto on Windows Using Visual Studio

Prerequisites:

    Tramonto depends on a number of other software packages.  Below is a 
    list of the required packages and links from which you can download 
    any packages that are not available on your system.  There is a good
    chance that BLAS, LAPACK and an MPI implementation are already installed
    on your system.  It is especially important to have a BLAS library that
    is optimized for your machine.  

        Package                       Web Reference
        BLAS                       http://www.netlib.org
        LAPACK                     http://www.netlib.org
        MPI                        http://www-unix.mcs.anl.gov/mpi/mpich2
                                   http://www.open-mpi.org
        Trilinos (10.2.0 or later) http://trilinos.sandia.gov

    While BLAS, LAPACK and MPI could be available on your system, you will
    most likely have to build Trilinos yourself.  Trilinos contains several
    packages of which Tramonto requires amesos, aztecoo, triutils, ifpack,
    epetraext, epetra, loca, ml, nox, and teuchos.

    Trilinos has a webpage for new users available at
    http://trilinos.sandia.gov/getting_started.html.
    Below you will find a brief set of instructions that focus on building
    Trilinos for use with Tramonto.  If these instructions prove insufficient,
    please visit the website listed above.
    
Building Trilinos:

    As of April 2010, Tramonto requires Trilinos version 10.2.0 or later.

    Trilinos can be downloaded from the the Trilinos home page listed above.
    There are many options available in configuring Trilinos, some of the 
    most important one are:
    
    CMAKE_INSTALL_PREFIX:PATH=

        This option specifies where to install Trilinos.  For example,
        CMAKE_INSTALL_PREFIX:PATH=/path/TrilinosInstall will install Trilinos
        libraries in /path/TrilinosInstall/lib and Trilinos header files in
        /path/TrilinosInstall/include.

    TPL_ENABLE_MPI:BOOL=ON

        This option indicates that a parallel, rather than serial, 
        version of Trilinos should be built.

    DMPI_BASE_DIR:PATH=

        Use this option to specify the base installation directory for MPI.
        In many cases when using a standard setup, this is not necessary,
        but the option is useful when a machine contains multiple mpi
        installations, or mpi is installed in a non-standard location.  If
        /path is the base installation directory, /path/include contains mpi.h,
        /path/lib includes the mpi libraries, and /path/bin contains mpiexec
        (or equivalent mpi executable).
 
    TPL_BLAS_LIBRARIES:STRING=
    TPL_LAPACK_LIBRARIES:SRING=

        These options are used to specify the names or locations of the BLAS
        and LAPACK libraries.  If the options are not specified, Trilinos
        will attempt to find BLAS and LAPACK.  Again, it is best to 
        explicitly list the libraries you want to use if there are 
        multiple libraries available on your machine.  Example usage:
        TPL_BLAS_LIBRARIES:STRING="-lcblas;-lf77blas;-latlas;-lgfortran" or 
        TPL_BLAS_LIBRARIES:STRING=/usr/lib64/libblas.so and
        TPL_LAPACK_LIBRARIES:STRING=/usr/lib64/liblapack.so

    Trilinos_ENABLE_ALL_PACKAGES:BOOL=OFF 
    Trilinos_ENABLE_:BOOL=ON

        The best way to build only the packages that Tramonto uses is to use 
        the Trilinos_ENABLE_ALL_PACKAGES:BOOL=OFF option in conjunction with
        a Trilinos_ENABLE_:BOOL=ON option for each required
        Trilinos package.  For example Trilinos_ENABLE_AztecOO:BOOL=ON, etc.
        Note that it is not necessary to disable all of the packages that
        Tramonto does not use; this is especially useful when building Tramonto
        on a machine that has a pre-installed version of Trilinos.  It can be
        helpful to disable unneeded packages to make it easier and faster to
        build Trilinos.


    Below are examples of ways to properly configure Trilinos.  You can find
    more examples in the "sampleScripts" directory in the Trilinos
    distribution.  The configure command points up one directory because the
    preferred directory structure for building Trilinos has separate build and 
    source trees.  For example, for a build tree named "TramontoInstall",
    from the top-level Trilinos directory, type "mkdir TramontoInstall",
    then "cd TramontoInstall", and finally provide the proper configure
    arguments.  Some users prefer for the build tree to be a peer to the
    top-level Trilinos directory.  The source tree can be in any arbitrary
    location; the last argument in the configuration command simply has to
    point to the source tree with an absolute or relative path.  Often it is
    convenient to create a script (like those in the sampleScripts directory
    mentioned above) in the build directory and then simply source the script.
    If a separate build tree is not used, the configure process will terminate
    with an error.
		
    Linux 
     cmake \
     -DTPL_ENABLE_MPI:BOOL=ON \
     -DTrilinos_ENABLE_ALL_PACKAGES:BOOL=OFF \
     -DTrilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=OFF \
     -DTrilinos_ENABLE_Amesos:BOOL=ON \
     -DTrilinos_ENABLE_AztecOO:BOOL=ON \
     -DTrilinos_ENABLE_Triutils:BOOL=ON \
     -DTrilinos_ENABLE_Ifpack:BOOL=ON \
     -DTrilinos_ENABLE_EpetraExt:BOOL=ON \
     -DTrilinos_ENABLE_Epetra:BOOL=ON \
     -DNOX_ENABLE_LOCA:BOOL=ON \
     -DTrilinos_ENABLE_ML:BOOL=ON \
     -DTrilinos_ENABLE_NOX:BOOL=ON \
     -DTrilinos_ENABLE_Teuchos:BOOL=ON \
     -DTrilinos_ENABLE_TESTS:BOOL=ON \
     -DCMAKE_CXX_FLAGS:STRING="-O3" \
     -DCMAKE_C_FLAGS:STRING="-O3" \
     -DCMAKE_Fortran_FLAGS:STRING="-O5" \
     -DTPL_BLAS_LIBRARIES:STRING="-lcblas;-lf77blas;-latlas;-lgfortran" \
     -DCMAKE_INSTALL_PREFIX:PATH=/home/jmwille/TramontoTestHarness/Tri10.2 \
     ..

    Mac OSX
     cmake \
     -DTrilinos_ENABLE_ALL_PACKAGES:BOOL=OFF \
     -DTrilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=OFF \
     -DTPL_ENABLE_MPI:BOOL=ON \
     -DTrilinos_ENABLE_Amesos:BOOL=ON \
     -DTrilinos_ENABLE_AztecOO:BOOL=ON \
     -DTrilinos_ENABLE_Triutils:BOOL=ON \
     -DTrilinos_ENABLE_Ifpack:BOOL=ON \
     -DTrilinos_ENABLE_EpetraExt:BOOL=ON \
     -DTrilinos_ENABLE_Epetra:BOOL=ON \
     -DNOX_ENABLE_LOCA:BOOL=ON \
     -DTrilinos_ENABLE_ML:BOOL=ON \
     -DTrilinos_ENABLE_NOX:BOOL=ON \
     -DTrilinos_ENABLE_Teuchos:BOOL=ON \
     -DTrilinos_ENABLE_TESTS:BOOL=ON \
     -DCMAKE_CXX_FLAGS:STRING="-O3" \
     -DCMAKE_C_FLAGS:STRING="-O3" \
     -DCMAKE_Fortran_FLAGS:STRING="-O5" \
     -DMPI_BASE_DIR:PATH=/Users/jmwille/install \
     -DCMAKE_INSTALL_PREFIX:PATH=/Users/jmwille/TramontoTestHarness/Tri10.2 \
     ..

    Once you have configured Trilinos, build it by typing "make".  
    This will build the libraries, tests (if Trilinos_ENABLE_TESTS:BOOL=ON),
    and examples for the packages that were enabled at configure time.  If
    the tests were compiled, a test suite can be run by typing "ctest".
    Finally, install Trilinos using "make install".


Building Tramonto:

    Once Trilinos has been built, building Tramonto tends to be 
    straightforward because most of the options that were used to build
    Trilinos can be used automatically to build Tramonto.  As with Trilinos, 
    it is necessary to configure and then build Tramonto.  Since 
    Tramonto produces only a single executable, there is no need to 
    install it and at this time there is not a make target for testing.
    
    To configure Tramonto, it is necessary to indicate the location of the
    installed Trilinos libraries and header files.  This can be done using the
    TRILINOS_PATH option.  This option points to the base of the installed
    version of Trilinos.  For example, if Trilinos is configured with
    CMAKE_INSTALL_PREFIX:PATH=/Users/jmwille/TramontoTestHarness/Tri10.2, use

    -DTRILINOS_PATH:PATH=/Users/jmwille/TramontoTestHarness/Tri10.2

    Beginning with Trilinos 10.7, it is also possible to use the standard
    CMake option CMAKE_PREFIX_PATH:

    -DCMAKE_PREFIX_PATH:PATH=/Users/jmwille/TramontoTestHarness/Tri10.7

    Below are Tramonto configure invocations that correspond to the
    above Trilinos configure invocations.  These, as well as other,
    scripts can be found in the directory "sampleConfigs" in the Tramonto
    distribution.  Note that using a separate build tree is again
    required, as discussed in the Building Trilinos section.

    Linux
     cmake \
     -DTRILINOS_PATH=/home/jmwille/TramontoTestHarness/Tri10.2 \
     ..

    Mac OS X
     cmake \
     -DTRILINOS_PATH=/Users/jmwille/TramontoTestHarness/Tri10.2 \
     ..


    Once the configure script completes, you can type "make" to 
    build Tramonto. After make finishes, the Tramonto  binary, "dft_exec" 
    can optionally be copied to a more convenient location.

Building Trilinos and Tramonto on Windows Using Visual Studio

    Beginning with Tramonto 4.0, it is possible to build Tramonto on Windows
    using Microsoft Visual Studio.  The below instructions assume some
    familiarity with Visual Studio.  The Windows build process is not as
    polished as the process for Linux or Mac.  Feedback for building on
    Windows, including improvements or additions for the information below
    can be sent to tramonto-help@software.sandia.gov.

    1.  Install CMake, CLAPACK (or other BLAS & LAPACK implementations), and
        MPICH2 (or another MPI implementation)

      CMake: http://www.cmake.org/cmake/resources/software.html

        Download the latest 32-bit Windows installer (even if using a 64-bit
        machine.  Follow the instructions for the self-extracting installer.

      CLAPACK: http://www.netlib.org/clapack

        Download the latest Visual Studio prebuilt zip file.  Extract the
        contents of the zip file and note the directory where CLAPACK was
        extracted.  Alternatively, use the CMake-aware version and build
        (and optionally install) CLAPACK through visual studio.

      MPICH2: http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads

        Download the latest Windows installer from the above website.  Follow
        the instructions for the self-extracting installer.

    2.  Build Trilinos

        Open the CMake GUI, select Trilinos source and build trees.  Configure
        once.

        Set the following variables (Note that safety and clarity were the
        primary considerations for these instructions, not efficiency):

        TPL_ENABLE_MPI -> ON
        Trilinos_ENABLE_ALL_PACKAGES -> Leave box unchecked
        Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES -> Uncheck box
        Trilinos_ENABLE_Amesos -> ON
        Trilinos_ENABLE_AztecOO -> ON
        Trilinos_ENABLE_Triutils -> ON
        Trilinos_ENABLE_Ifpack -> ON
        Trilinos_ENABLE_EpetraExt -> ON
        Trilinos_ENABLE_Epetra -> ON
        Trilinos_ENABLE_ML -> ON
        Trilinos_ENABLE_NOX -> ON
        Trilinos_ENABLE_Teuchos -> ON
        TPL_ENABLE_BLAS -> ON
        TPL_ENABLE_LAPACK -> ON
        CMAKE_INSTALL_PREFIX -> Set to Trilinos installation path

        Configure again, switch to "Advanced View"

        MPI_BASE_DIR -> Set to top level of MPI installation 
            (ex C:/Program Files/MPICH2)
        TPL_BLAS_LIBRARIES -> Set to find BLAS 
            (ex (this is all one line) - C:/Program Files/CLAPACK 3.2.1/lib/
             blas.lib;C:/Program Files/CLAPACK 3.2.1/lib/libf2c.lib )

        configure again

        TPL_LAPACK_LIBRARIES -> Set to find LAPACK
            (ex C:/Program Files/CLAPACK 3.2.1/lib/lapack.lib )

        configure again
        configure again
        generate

        Open the 'Trilinos.snl' file created during the generation process
        from the 'File' menu in Visual Studio.  Right click on Solution
        'Trilinos' and click 'Build Solution'.

    3.  Build Tramonto

        Next, open the CMake GUI again.  Select Tramonto source and build trees. 
        Configure once.

        Trilinos_DIR -> delete the pre-filled value (if applicable)
        TRILINOS_PATH -> Set to the same value used for CMAKE_INSTALL_PREFIX
        for Trilinos.

        configure again
        generate

        Open the 'Tramonto.snl' file created during the generation process from
        the 'File' menu in Visual Studio.  Right click on Solution 'Tramonto'
        and click 'Build Solution'.

    Notes for Windows build: 

        - These instructions were created using Microsoft Visual Studio 2008.

        - Depending on the version of Trilinos used, the ML build may fail with
          an error indicating that 'unistd.h' cannot be found.  Remove the
          reference to this file from 'ml_utils.h' and build again.

        - If the Tramonto build fails with an error indicating that LAPACK or
          BLAS cannot be found, do the following inside Visual Studio:

            Right-click the dft_exec target -> properties
            Under the C/C++ tab, add to the additional include directories the
            proper directories for the lapack and blas header files.

            Under the Linker tab, add to the additional library directories the
            proper directories for the lapack and blas library files.

            Under Linker->Input, add lapack.lib, blas.lib, and (if using
            clapack) libf2c.lib to the additional dependencies list.