Installation

Requirements

System Requirements

Software requirements

Additional software requirements for PySundance

Optional Software

Building the online documentation

To build the online documentation (i.e., the web pages you're currently browsing) go to the doc directory of the Sundance distribution and run make. For example, 
<kevin@rusalka:Projects/Sundance> cd doc
<kevin@rusalka:Projects/Sundance/doc> make
The documentation will be placed in the html subdirectory of doc.

Configuring and Building Trilinos for Sundance

The installation procedure for Trilinos is well-documented here, however, it may not be obvious which options should be set to work with Sundance. Information on which Trilinos packages should be enabled plus sample configuration scripts are found on this page: Configuring Trilinos for an external build of Sundance .

Example Trilinos Installation

Here we show an example of installing Trilinos. We will configure it for use with Sundance with settings appropriate to debugging.

Trilinos is unpacked into a directory tagged by the minor version number, for example, trilinos-6.0.18. The minor version number 6.0.18 appears in all examples below; it should of course be changed to the minor version number of your Trilinos installation.

It is assumed that you have installed BLAS, LAPACK, and any optional libraries such as MPI. It is assumed you have downloaded Trilinos and unpacked the source into some directory; in this example, we will work in a Trilinos directory $HOME/Software/Math/trilinos-6.0.18. As is explained in the Trilinos installation guide, Trilinos should always be configured and built in a build directory, not in the Trilinos source directory. In this example, we work in a build directory $HOME/Software/Math/trilinos-6.0.18/LINUX-OPT.

The installation process is listed below for a case where you are using one of the Canned Scripts on the Configuring Trilinos for an external build of Sundance . 

<kevin@rusalka:Software/Math/trilinos-6.0.18> mkdir LINUX-OPT 
<kevin@rusalka:Software/Math/trilinos-6.0.18> cd LINUX-OPT 
<kevin@rusalka:Software/Math/trilinos-6.0.18/LINUX-OPT> ./sundance-linux-mpi-opt
<kevin@rusalka:Software/Math/trilinos-6.0.18/LINUX-OPT> make
<kevin@rusalka:Software/Math/trilinos-6.0.18/LINUX-OPT> make install

The final step puts libraries and headers into the installation directory specified in the configuration script; the sample script used here installs into the build directory. Thus in this example, headers and libraries are found in the include and lib subdirectories of HOME/Software/Math/trilinos-6.0.18/LINUX-OPT. The installation directory can be changed with the --prefix configure option.

Note on Concurrent Development of Trilinos and Sundance

The default installation behavior updates timestamps on header files so that if any Trilinos header file is changed, many Sundance files will have to be rebuilt. This is inconvenient for those people who use Sundance while doing Trilinos development, for instance solver researchers using Sundance as a testbed, because it forces many unnecessary rebuilds of the entire Sundance distribution. On some systems, timestamps on unchanged files can be preserved through installation, so that only those Sundance files dependent on those Trilinos files that have actually changed need be rebuilt. On Linux, timestamps can be preserved with the -p option to install, which can be imposed by adding the option --with-install="/usr/bin/install -c -p" to the configure command line. This is done in the sample scripts in the Trilinos distribution.

Configuring Sundance

Once Trilinos is built and installed, we can configure, build, and install Sundance. During the Sundance build process, configure and make must know where to find headers and libraries for Trilinos. This is done through the --with-trilinos option to configure. With the example Trilinos installation above, you would add --with-trilinos=+$+HOME/Software/Math/trilinos-6.0.18/LINUX-OPT to the configure command line. If you have installed Trilinos somewhere else, you should change your configure line accordingly.

Sundance configuration options

There are several other configure flags for enabling undocumented pre-release features.

Example configuration

There are several sample configuration script in the build-scripts subdirectory of Sundance. All of these scripts make assumptions about where you've installed Trilinos: you'll need to edit them so that --with-trilinos is set appropriately for your system. These scripts can be used as a starting point for other modes of building Sundance.

An example installation process is listed below. We use the script <t>linux-python-mpi</T> which builds the Python wrappers and parallel capabilities using optimized compiler flags. 

<kevin@rusalka:Projects/Sundance> mkdir LINUX-OPT 
<kevin@rusalka:Projects/Sundance> cd LINUX-OPT 
<kevin@rusalka:Projects/Sundance/LINUX-OPT> ../build-scripts/linux-python-mpi
<kevin@rusalka:Projects/Sundance/LINUX-OPT> make
<kevin@rusalka:Projects/Sundance/LINUX-OPT> make install

Testing your build

The regression system is currently being ported to the Trilinos test harness, and will soon have all the features of that system. In the meantime, you can run tests with 
make old-tests        # Runs all tests
make old-serialtests  # Runs serial tests only

Setting your environment to run a PySundance simulator

The easiest way to build simulators is with PySundance. You don't need to worry about makefiles, all you need to do is install (following the instructions above) and then set your Python path to the installation directory for the PySundance shared libraries. The subdirectory name will depend on your installation; it will be a subdirectory of python/src/build. For example, 
<kevin@rusalka> setenv PYTHON_PATH /home/kevin/Projects/Sundance/LINUX-OPT/python/src/build/lib.linux-i686-2.4/PySundance
You can put this in your .cshrc file to have the path automatically set when opening a new shell.

Setting up makefiles to develop a C++-based Sundance application

The previous installation steps have configured and built the Sundance libraries, tests, and examples. You are probably interested in using Sundance to develop your own application, for which you will need to write a Makefile that can access the Sundance libraries.

A simple application makefile example

A template for a simple application makefile is in Makefile.sample, found in the root directory of the Sundance distribution. For many Sundance-based applications it will be sufficient to copy this makefile and set one variable: SUNDANCE_INSTALL_DIR, which should point to the directory where you have installed Sundance.

In the following example, you are building the PostPotentialFlow simulator (described in detail below) in the directory MyApps. First put the application source (and any other required files such as meshes) in your application directory: 

<kevin@rusalka:MyApps> cp ~/Projects/Sundance/examples-tutorial/PostPotentialFlow.cpp .
<kevin@rusalka:MyApps> cp ~/Projects/Sundance/examples-tutorial/post.ncdf .
<kevin@rusalka:MyApps> cp ~/Projects/Sundance/Makefile.sample Makefile
Now, edit Makefile and set SUNDANCE_INSTALL_DIR to the location of your Sundance build. The next step is to build the application: 
<kevin@rusalka:MyApps> make PostPotentialFlow.exe
Your application is now ready to run.

If your application requires more than one source file, additional objects to be compiled and linked can be specified in the EXTRA_OBJS macro. For more complicated application structures, see the next section.

Rolling your own application Makefile

If the sample makefile described above is not sufficient for your application, you can access the make macros for Sundance directly by including in your makefile the file Makefile.export, which is written into your build subdirectory at configure time. This makefile fragment contains definitions of the Sundance and Trilinos header and library search paths, compiler options, and so on. If you are rolling your own Makefile, I assume you know enough about makefiles to set it up without further instruction from me.

Site Contact