Trilinos 101: Getting Started with Trilinos

November 7, 2006

8:30-9:30 a.m.

Mike HerouxJim Willenbring

Overview

• Trilinos Web Page• Obtaining Trilinos• Tools for Users

– Mailman– Bugzilla

• Configuring

– General configure options– Platform and machine specific configure options– Troubleshooting

• Building and Installing• Testing• Improving Efficiency (of the build process)• Linking to Trilinos Libraries

The Trilinos Home Page

http://software.sandia.gov/trilinos/

• Highlights of the web page– Download page– User documentation

• Getting started page• Installation guide• User guide• FAQ• Individual package documentation• ‘runtests’ make target documentation• External package capability

• Instructions for obtaining Trilinos are available in– the Trilinos User Guide

http://software.sandia.gov/trilinos/publications.html

– the Installation Guidehttp://software.sandia.gov/trilinos/

installation_manual.html

• Download from the websitehttp://software.sandia.gov/trilinos/downloads.html

• Obtain a copy from the CVS repository• Not available for all users

Obtaining Trilinos

Tools for Users

• Mailman– Users are encouraged to sign up for

• Users lists for Trilinos and individual packages of interest

• Announce lists for Trilinos and individual packages of interest

– See http://software.sandia.gov/mailman/listinfo for the complete list of mail lists

• For general questionstrilinos-help@software.sandia.gov

Tools for Users (cont.)

• Bugzilla

http://software.sandia.gov/bugzilla/– Issue tracking tool

– An account is required to file a “bug”

– Can be used to report bugs or request new features

– Please provide as much detail as possible (For example: Platform, OS, compiler versions, configure options, version of Trilinos, etc.)

Configuring Trilinos

• Find an in depth discussion in the Trilinos User Guide

http://software.sandia.gov/trilinos/trilinosUserGuide.pdf

• Trilinos Installation manualhttp://software.sandia.gov/trilinos/installation_manual.html

Configuring Trilinos (cont.)

• Trilinos uses Autoconf and Automake

• Don’t just try “configure, make, make install”– Most platforms need more options

– Even if the build is successful, the default set of packages and options probably will not suit your needs

• If you don’t want to build everything, then don’t– Takes a long time to configure and build

– Run into problems while building a package that is not needed

Configuring Trilinos (cont.)

•To see all Trilinos options type– ./configure --help=recursive

• General Configure options

–Determine which Trilinos packages should be built (--enable-<package_name>)

–Consider using --disable-default-packages

–Serial or MPI?

Configuring Trilinos (cont.)

• Platform and machine specific options– Common options online

http://software.sandia.gov/trilinos/configuration_manual.html

– Example configure invocation scripts• Examples only – customizations will be necessary• Can be found in the Trilinos directory structure in the

Trilinos/sampleScripts/ directory

• For example redstorm_mpi_reddish1• Users are encouraged to submit their scripts

Configuring Trilinos (cont.)

• Example invoke configure file for reddish:

module load PrgEnv-pgimodule load mpich../configure --enable-mpi \CXX=mpicxx CC=mpicc F77=mpif77 \CPPFLAGS="-tp k8-64 -lacml -lpgmp -lpgthread" \--with-blas="-L/usr/pgi-6.0/linux86-64/6.0/lib -lacml -lpgmp -lpgthread" \--with-lapack="-L/usr/pgi-6.0/linux86-64/6.0/lib -lacml" \--enable-ml \--disable-default-packages#The lines before ../configure load the proper environment

Configuring Trilinos (cont.)

• Platform and machine specific options

module load PrgEnv-pgimodule load mpich../configure --enable-mpi \CXX=mpicxx CC=mpicc F77=mpif77 \CPPFLAGS="-tp k8-64 -lacml -lpgmp -lpgthread" \--with-blas="-L/usr/pgi-6.0/linux86-64/6.0/lib -lacml -lpgmp -lpgthread" \--with-lapack="-L/usr/pgi-6.0/linux86-64/6.0/lib -lacml" \--enable-ml \--disable-default-packages

Configuring Trilinos (cont.)

• Troubleshooting– Most errors are due to system configurations– Look for errors in the invoke-configure

– Autoconf is not able to detect spelling errors.– Line continuation problems (ex --enable-mpi \ ))

– Look at the correct config.log file (created at configure time)

• Default error output is very, very poor – often misleading• The config.log at the Trilinos level is not the correct config.log file.

Go to the package level config.log file. For example:configure: error: /bin/sh '../../../packages/epetra/configure' failed for packages/epetra

indicates that one should look at packages/epetra/config.log

Troubleshooting using config.log

• The config.log file is very long– To find what you need, search for the string

“Cache”

## ------------------------ #### Cache variables. #### ----------------------- ##

– The error that caused the configure failure can be found above this point, but typically not directly above

Working Through a config.log File

• Here is a common configure error– error: Cannot find lapack library, specify a path

using --with-ldflags=-I<DIR> (ex. --with-dlflags=-I/usr/path/lib) or a specific library using --with-lapack=DIR/LIB (ex. --with-lapack=/usr/path/lib/libcxml.a)

• Look for last successful configure check– In this case it would be a BLAS check– Directly beneath that check will be the failed check– Could be

• Missing library (undefined symbol)• Incorrect path• ??

Building and Installing Trilinos

• To build Trilinos type

make• To install Trilinos type

make install

Testing

• Tests can be run individually after compilation• ‘runtests’ make targets

http://software.sandia.gov/trilinos/developer/test_harness/runtests_make_target.html

– To run the test suite (the tool will only attempt to run tests that were built), after "make“, type

make runtests-serial

– Can run tests for individual packages

Testing

• ‘runtests’ make targets– For MPI use make runtests-mpi

• Must specify TRILINOS_MPI_GO in the environment or as an argument to make

make runtests-mpi TRILINOS_MPI_GO="'mpiexec -np 2'"

– Trilinos/commonTools/test/utilities/runtests –help

• Installation Tests– Make a good “linking” test– <prefix>/examples– Not all of these work yet

Improving Efficiency

• All of these techniques are discussed in the Trilinos User Guide

– Build only the packages that are needed– After Trilinos has been ported to a machine

• --disable-tests --disable-examples ---disable-libcheck– Cannot use --disable-libcheck with makefile.export

– make –j n• n is the number of jobs to create• Not supported by all versions of “make”

– --cache-file=config.cache• Be sure to blow away if errors occur• Can put removal command in invoke-configure

Linking to Trilinos Libraries

• Makefile.export system makes linking easy– Files created in the include directory during install

– Makefile.export.<package_name> files • Useful macros

<PACKAGE_NAME>_INCLUDES<PACKAGE_NAME>_LIBS

– Makefile.export.<package_name>.macros files• More macros including

<PACKAGE_NAME>_CXXFLAGS<PACKAGE_NAME>_CXX

– Use the macros in application makefiles

Linking to Trilinos Libraries

• Example:

TRILINOS_PREFIX=/common/Trilinos/7.0.2include $(TRILINOS_PREFIX)/include/Makefile.export.epetra.macrosinclude $(TRILINOS_PREFIX)/include/Makefile.export.epetra

INCDIR=$(EPETRA_INCLUDES)LIBDIR=$(EPETRA_LIBS)CXXFLAGS=$(INCDIR) $(EPETRA_CXXFLAGS) $(EPETRA_DEFS)CXX= $(EPETRA_CXX)

• Typically must include several Makefile.export files

Common Pitfalls

• --with-gnumake• Compiler/library version mismatches

– __gxx__personality

– gfortran or g77

– Upgrading system and not recompiling 3PL’s

• Linking to BLAS/LAPACK• Typo’s in configure arguments

Where to Find Help

• Getting started link

http://software.sandia.gov/trilinos/getting_started.html

• Help link from Trilinos home page

http://software.sandia.gov/Trilinos/help.html• Online FAQ section

http://software.sandia.gov/trilinos/faq.html• Trilinos User Guide

http://software.sandia.gov/trilinos/publications.html

Where to Find Help (cont.)

• Submitting a bug report– Please provide as much detail as possible– Attach the appropriate config.log

http://software.sandia.gov/trilinos/bug_reports.html• For general questions

trilinos-help@software.sandia.gov

• Trilinos Home Page

http://software.sandia.gov/trilinos

Discussion

• Questions, comments?