Commit 8dd415c2 authored by Thomas Witkowski's avatar Thomas Witkowski
Browse files

Some work on the tutorial.

parent 04bcc8b4
......@@ -5,7 +5,7 @@
\input{heat.tex}
\input{vecellipt.tex}
\input{couple.tex}
\input{nonlin.tex}
%\input{nonlin.tex}
\input{neumann.tex}
\input{periodic.tex}
\input{projections.tex}
......
......@@ -42,61 +42,32 @@ To install the AMDiS library, the following steps must be performed:
optimized mode without debug support.
\item \verb+--enable-umfpack+: If this option is used, AMDiS is
compiled with support for the UMFPACK solver library.
\item \verb+--with-mpi=<MPI-DIR>+: MPI installation path. Used for
parallelization support.
\item \verb+--with-parmetis=<PARMETIS-DIR>+: ParMETIS installation
path. ParMETIS is a parallel graph partitioning library, see
\\\verb+http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview+. Used
for parallelization support.
\end{description}
If AMDiS should be compiled for parallel usage, the MPI and ParMETIS paths must be set.
\item Make the library:
\begin{verbatim}
> make install
\end{verbatim}
\end{enumerate}
If you have added a new source file or you want to change something on the automake-system, you have to rerun the following commands:
If you have added a new source file or you want to change something on the automake-system, you have to rerun the following command:
\begin{verbatim}
> libtoolize --force --copy
> aclocal
> autoconf
> automake --add-missing --copy
./autogen <CONFIGURE-OPTION>
\end{verbatim}
Then repeat steps 3 and 4.
For the additional steps \verb+libtool+, \verb+automake+ and \verb+autotools+ must be installed on your system.
Further information about the installation process can be found in the \verb+README+ file in the AMDiS source directory.
This will generate files for the configure-make-system.
\section{Compilation of an example application}
\label{s:compilation}
For the compilation of the examples, described in this section, the following steps must be executed:
\begin{enumerate}
\item Get the sources:
\begin{itemize}
\item Unpack an archive file: \\
\verb+> gunzip demo.tar.gz+\\
\verb+> tar xvf demo.tar+
or
\item CVS checkout:\\
\verb+> export CVSROOT=<CVSROOT>+\\
\verb+> cvs checkout demo+
or
\item SVN checkout:\\
\verb+> svn checkout file://<SVN-REPOSITORY-PATH>/demo+
\end{itemize}
\item Change into the demo directory:\\
\verb+> cd demo+
\item Edit the \verb+Makefile+:
\item It may be required to change the \verb+Makefile+:
\begin{itemize}
\item Set the AMDiS path and paths of other needed libraries.
\item Set user flags.
\end{itemize}
\end{itemize}
The makefile is described in Section \ref{s:application makefile} in detail.
\item Make the application example:\\
......@@ -105,15 +76,8 @@ For the compilation of the examples, described in this section, the following st
\verb+<PROG-NAME>+ is the name of the application example.
\end{enumerate}
To run the example, call:
\begin{itemize}
\item In the sequential case:\\
To run the example, call:\\
\verb+> ./<PROG-NAME> <PARAMETER-FILE>+
\item In the parallel case:\\
\verb+> mpirun <MPI-OPTIONS> ./<PROG-NAME> <PARAMETER-FILE>+\\
The \verb+<MPI-OPTIONS>+ at least should contain the number of used processes, which is given by \verb+-np <NUM-PROCS>+. For further MPI options see \verb+http://www-unix.mcs.anl.gov/mpi/+.
\end{itemize}
\input{makefile.tex}
\chapter{Application makefile}
\label{s:application makefile}
In this section, the organization of the application makefile is described which is used for the examples in this tutorial. The same organization can be used for other user applications, too.
In this section, the organization of the application makefile is
described which is used for the examples in this tutorial. The same
organization can be used for other user applications, too.
In the first block, user flags and directories are specified.
......@@ -10,110 +12,59 @@ In the first block, user flags and directories are specified.
# ===== flags and directories (to be modified by the user) ===================
# ============================================================================
USE_PARALLEL_AMDIS = 0 # 0: sequential AMDiS, 1: parallel AMDiS
DEBUG = 0 # 0: no debug, 1: debug mode
USE_PARALLEL_AMDIS = 0
USE_OPENMP = 0
USE_UMFPACK = 1
USE_MKL = 0
USE_SERVER =
USE_COMPILER = gcc
DEBUG = 0
AMDIS_DIR = <AMDIS-DIR> # fill the AMDiS installation path here
MPI_DIR = <MPI-DIR> # fill the MPI installation path here
PARMETIS_DIR = <PARMETIS-DIR> # fill the ParMETIS installation path here
AMDIS_DIR = ../AMDiS
MPI_DIR =
\end{verbatim}
If \verb+USE_PARALLEL_AMDIS+ is set to $1$, parallel applications will be supported. A necessary condition is that the AMDiS library is configured for parallelization, too (see Chapter \ref{c:amdis installation}). The \verb+DEBUG+ entry specifies, whether applications should be compiled in debug mode, or not. This entry is independent of the corresponding AMDiS settings, but if the AMDiS library was not compiled in debug mode, only application code can be debugged.
\verb+AMDIS_DIR+ stores the AMDiS installation path and must be set by the user. This is the path given to the AMDiS configure script by the \verb+--prefix+ option. The values of \verb+MPI_DIR+ and \verb+PARMETIS_DIR+ only are needed if parallelization should be supported. Here, the installation pathes of MPI and ParMETIS are stored.
In the next block, include pathes are defined.
If \verb+USE_PARALLEL_AMDIS+ is set to $1$, parallel applications will
be supported. If AMDiS is compiled with OpenMP supported,
\verb+USE_OPENMP+ must be set to $1$. If you want to make use of
UMFPACK oder Intel's Math Kernel Library, set \verb+USE_UMPFACK+ and
\verb+USE_MKL+, repsectively, to $1$. In both cases, AMDiS must be
compiled with the corresponding options. If you run your computations
on one of the high performance computers installed at the TU Dresden,
insert the name of the corresponding system to
\verb+USE_SERVER+. Using the flag \verb+USE_COMPILER+ you may decide
to use either the GNU C++ or the Intel C++ compiler. Note that your
program must be compiled with the same compiler AMDiS has been
compiled with. To the last you can enable the debuge mode in your code
setting \verb+DEBUG+ to $1$.
\verb+AMDIS_DIR+ stores the AMDiS installation path and must be set by
the user. This is the path given to the AMDiS configure script by the
\verb+--prefix+ option. If you have not changed the directory
structure of your AMDiS installation, or you do not want to use some
other AMDiS installation for the demo examples, you do not need to
change the standard value. The value of \verb+MPI_DIR+ is only
required for parallel computations. If you run your parallel
computations on the high performance computers of the TU Dresden, do
not set a value here.
Then the AMDiS makefile is included from the corresponding AMDiSinstallation:
\begin{verbatim}
# ============================================================================
# ===== includes pathes ======================================================
# ============================================================================
AMDIS_INCLUDE = -I$(AMDIS_DIR)/src
MPI_INCLUDE = -I$(MPI_DIR)/include
PARMETIS_INCLUDE = -I$(PARMETIS_DIR)
INCLUDES = -I. $(AMDIS_INCLUDE) $(MPI_INCLUDE) $(PARMETIS_INCLUDE)
#==== standard definitions and rules to compile AMDiS user programs ==========
include $(AMDIS_DIR)/other/include/Makefile_AMDiS.mk
\end{verbatim}
Now, we introduce the needed libraries.
\begin{verbatim}
# ============================================================================
# ===== libraries ============================================================
# ============================================================================
AMDIS_LIB = -L$(AMDIS_DIR)/lib -lamdis
PARMETIS_LIB = -L$(PARMETIS_DIR) -lparmetis -lmetis
LIBS = $(AMDIS_LIB)
\end{verbatim}
By default, \verb+LIBS+ contains only the AMDiS library. If \verb+USE_PARALLEL_AMDIS+ is $1$, \verb+LIBS+ is extended by the ParMETIS library. In the same way, other libraries can be added. In the sequential case, we use the GNU C++ compiler \verb-g++-, in the parallel case, the MPI C++ compiler \verb+mpiCC+.
\begin{verbatim}
# ============================================================================
# ===== parallel or sequential ? =============================================
# ============================================================================
ifeq ($(USE_PARALLEL_AMDIS), 0)
COMPILE = g++
else
COMPILE = $(MPI_DIR)/bin/mpiCC
LIBS += $(PARMETIS_LIB)
endif
\end{verbatim}
The next block sets the compile flags. In debug mode, we use no optimization (\verb+-O0+) and add symbolic debug information (\verb+-g+). Otherwise, we compile with optimazation level 2 (\verb+-O2+).
\begin{verbatim}
# ============================================================================
# ===== compile flags ========================================================
# ============================================================================
ifeq ($(DEBUG), 0)
CPPFLAGS = -O2
else
CPPFLAGS = -g -O0
endif
\end{verbatim}
We use the \verb+libtool+ in the AMDiS installation path for linking.
\begin{verbatim}
# ============================================================================
# ===== libtool linking ======================================================
# ============================================================================
LIBTOOL = $(AMDIS_DIR)/libtool
LINK = $(LIBTOOL) --mode=link $(COMPILE)
\end{verbatim}
Now, we define rules to create and delete objects files.
\begin{verbatim}
# ============================================================================
# ===== rules ================================================================
# ============================================================================
clean:
-rm -rf *.o
.cc.o: $*.cc
$(COMPILE) $(INCLUDES) $(CPPFLAGS) -c -o $*.o $^
\end{verbatim}
The second rule creates needed object files automatically using the corresponding C++ files.
Finally, we define rules for the linking of user applications. Here, we present only the rule for the \verb+ellipt+ application. Other applications can be created in an analog way.
Finally, we define rules for the linking of user applications. Here,
we present only the rule for the \verb+ellipt+ application. Other
applications can be created in an analog way.
\begin{verbatim}
# ============================================================================
# ===== user programs ========================================================
# ============================================================================
VPATH = .:./src:$(AMDIS_DIR)/src
VPATH = .:./src
# ===== myprog ===============================================================
......@@ -123,4 +74,9 @@ ellipt: $(ELLIPT_OFILES)
$(LINK) $(CPPFLAGS) -o ellipt $(ELLIPT_OFILES) $(LIBS)
\end{verbatim}
The \verb+VPATH+ variable contains all pathes, where sources can be located. The \verb+ellipt+ rule first creates all needed object files defined in \verb+ELLIPT_OFILES+. In this example, only \verb+ellipt.o+ is needed. Then all needed object files and libraries are linked together. The \verb+-o+ option specifies that the executable will be written to the file \verb+ellipt+.
The \verb+VPATH+ variable contains all pathes, where sources can be
located. The \verb+ellipt+ rule first creates all needed object files
defined in \verb+ELLIPT_OFILES+. In this example, only \verb+ellipt.o+
is needed. Then all needed object files and libraries are linked
together. The \verb+-o+ option specifies that the executable will be
written to the file \verb+ellipt+.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment