General Notes

All examples are for running ug in parallel with <NP> processors and $UGARGS as arguments, where <NP> is a placeholder for the number of MPI processes and $UGARGS is an Unix environment variable which for example is defined by (Bash syntax; just to shorten command lines):

UGARGS="-ex ../scripts/tests/modular_scalability_test.lua -dim 2 -grid ../data/grids/unit_square_01/unit_square_01_quads_8x8.ugx"

Warning: Except for your own computer/workstation or explicitly stated, do NOT EVER use mpirun -np <NP> ugshell $UGARGS to start your job on a cluster! The node you are logging into is only a login node, and you don't want to run your job on these.

Setting up your cluster

We have included a automatic configuration: It is called ugconfig, and is in ug4/scripts/shell/ugconfig. So for your .bashrc, we suggest

source $HOME/ug4/trunk/scripts/shell/ugbash % for completion etc.

source $HOME/ug4/trunk/scripts/shell/ugconfig % for configuration

boost::source

size_t source(SM_edge< typename T::value_type > const &e, ug::BidirectionalMatrix< T > const &)

Definition: bidirectional_boost.h:94

ug::trunk

static vector2 trunk(const vector2 &v, number smallestVal)

Definition: file_io_tikz.cpp:59

ugconfig then automatically detects you cluster and loads standard modules like cmake, LAPACK or compilers. With this, you can also use the next tool to help you set up: Instead of using cmake, you can use ugcmake-start, e.g.

ugcmake-start -DDIM=2 -DCPU=1 -Damg=ON ..

This will again automatically detect your cluster, and call cmake with the appropriate toolchain file and flags (see also CMake, Toolchains, Compilers).

The aim of ugconfig and ugcmake-start is to make your life easier, so if they do not work, please tell, so we can fix that problem for you and others.

CMake, Toolchains, Compilers

Toolchain File

On some systems (especially when the software is built for a different system than the one which does the build) it is necessary to change some configuration settings done by CMake (like compilers or flags to use) by a so called "toolchain file" (cf. for example CMake Cross Compiling).

In this case run CMake like this

cmake -DCMAKE_TOOLCHAIN_FILE=<TOOLCHAINFILE> ..

Toolchain files are located in cmake/toolchain.

Note: if you already set other cmake settings before or e.g. tipped "cmake .." you first need to remove all files in your build-directory by the command "rm -rf *" and then call cmake with the toolchainfile by "cmake -DCMAKE_TOOLCHAIN_FILE=<TOOLCHAINFILE> .."!

Static Builds

ug4 is using external libraries and distributes some of its own codes into libraries (e.g. plugins). There are two ways of dealing with libraries:

dynamic linking: When the program is started, the library code is loaded out of another file. Those other files are called shared libraries. They usually end on .so or .so*.
static linking: The library code is written into the program binary when linking is done. When the program is started, all code is already loaded, since it is in the program itself. Static libraries usually end on '.a'. See also Static Libraries.

Although its possible on most clusters to create shared libraries and run dynamically linked executables this is in general not recommended, since loading of shared libraries can delay the startup of such an application considerably, especially when using large partitions (8 racks or more). See for example Shared Libraries and Dynamic Executables on Juqueen.

Start CMake like this

cmake -DSTATIC_BUILD=ON -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchain/juqueen.cmake ..

cmake

Definition: unit_tests.doxygen:198

If you're using a Toolchain File, use

cmake -DSTATIC_BUILD=ON -DCMAKE_TOOLCHAIN_FILE=<TOOLCHAINFILE> ..

Warning: You must use this line in a clean directory, without previous cmake files. Otherwise you will have linking problems with some files like MPI (error "attempted static link of dynamic object").

Setting compilers to use

You can specify other compilers than detected by CMake from the command line with

cmake -DCMAKE_C_COMPILER=cc -DCMAKE_CXX_COMPILER=CC ..

Please see for compiler troubleshooting Known Internal Compiler Errors .

If you need to choose another compiler, please consider writing your own toolchain file, so others can benefit from your knowledge.

Installation of Additional Software

Unfortunately on some systems it turned out that especially the build tool CMake, absolutely necessary to configure ug4 (cf. Prerequisites and Recommended Tools, Installation of CMake (required)), was not available. In such cases you have to install the required software yourself (typically locally). For some installation instructions — including those for CMake — see Prerequisites and Recommendend Tools .

Windows

MacOSX

After installation of a MPI implementation (e.g. OpenMPI, for example via MacPorts: sudo port install openmpi) you can use

mpirun -np <NP> ugshell $UGARGS

to run ug4.

Table of Contents