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

Some work on the tutorial.

parent 04bcc8b4
...@@ -5,7 +5,7 @@ ...@@ -5,7 +5,7 @@
\input{heat.tex} \input{heat.tex}
\input{vecellipt.tex} \input{vecellipt.tex}
\input{couple.tex} \input{couple.tex}
\input{nonlin.tex} %\input{nonlin.tex}
\input{neumann.tex} \input{neumann.tex}
\input{periodic.tex} \input{periodic.tex}
\input{projections.tex} \input{projections.tex}
......
...@@ -42,61 +42,32 @@ To install the AMDiS library, the following steps must be performed: ...@@ -42,61 +42,32 @@ To install the AMDiS library, the following steps must be performed:
optimized mode without debug support. optimized mode without debug support.
\item \verb+--enable-umfpack+: If this option is used, AMDiS is \item \verb+--enable-umfpack+: If this option is used, AMDiS is
compiled with support for the UMFPACK solver library. 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} \end{description}
If AMDiS should be compiled for parallel usage, the MPI and ParMETIS paths must be set.
\item Make the library: \item Make the library:
\begin{verbatim} \begin{verbatim}
> make install > make install
\end{verbatim} \end{verbatim}
\end{enumerate} \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} \begin{verbatim}
> libtoolize --force --copy ./autogen <CONFIGURE-OPTION>
> aclocal
> autoconf
> automake --add-missing --copy
\end{verbatim} \end{verbatim}
Then repeat steps 3 and 4. This will generate files for the configure-make-system.
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.
\section{Compilation of an example application} \section{Compilation of an example application}
\label{s:compilation} \label{s:compilation}
For the compilation of the examples, described in this section, the following steps must be executed: For the compilation of the examples, described in this section, the following steps must be executed:
\begin{enumerate} \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:\\ \item Change into the demo directory:\\
\verb+> cd demo+ \verb+> cd demo+
\item Edit the \verb+Makefile+: \item It may be required to change the \verb+Makefile+:
\begin{itemize} \begin{itemize}
\item Set the AMDiS path and paths of other needed libraries. \item Set the AMDiS path and paths of other needed libraries.
\item Set user flags. \item Set user flags.
\end{itemize} \end{itemize}
The makefile is described in Section \ref{s:application makefile} in detail. The makefile is described in Section \ref{s:application makefile} in detail.
\item Make the application example:\\ \item Make the application example:\\
...@@ -105,15 +76,8 @@ For the compilation of the examples, described in this section, the following st ...@@ -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. \verb+<PROG-NAME>+ is the name of the application example.
\end{enumerate} \end{enumerate}
To run the example, call: To run the example, call:\\
\begin{itemize}
\item In the sequential case:\\
\verb+> ./<PROG-NAME> <PARAMETER-FILE>+ \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} \input{makefile.tex}
\chapter{Application makefile} \chapter{Application makefile}
\label{s: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. In the first block, user flags and directories are specified.
...@@ -10,110 +12,59 @@ 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) =================== # ===== flags and directories (to be modified by the user) ===================
# ============================================================================ # ============================================================================
USE_PARALLEL_AMDIS = 0 # 0: sequential AMDiS, 1: parallel AMDiS USE_PARALLEL_AMDIS = 0
DEBUG = 0 # 0: no debug, 1: debug mode 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 AMDIS_DIR = ../AMDiS
MPI_DIR = <MPI-DIR> # fill the MPI installation path here MPI_DIR =
PARMETIS_DIR = <PARMETIS-DIR> # fill the ParMETIS installation path here
\end{verbatim} \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. If \verb+USE_PARALLEL_AMDIS+ is set to $1$, parallel applications will
be supported. If AMDiS is compiled with OpenMP supported,
\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. \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
In the next block, include pathes are defined. \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} \begin{verbatim}
# ============================================================================ #==== standard definitions and rules to compile AMDiS user programs ==========
# ===== includes pathes ====================================================== include $(AMDIS_DIR)/other/include/Makefile_AMDiS.mk
# ============================================================================
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)
\end{verbatim} \end{verbatim}
Now, we introduce the needed libraries. Finally, we define rules for the linking of user applications. Here,
we present only the rule for the \verb+ellipt+ application. Other
\begin{verbatim} applications can be created in an analog way.
# ============================================================================
# ===== 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.
\begin{verbatim} \begin{verbatim}
# ============================================================================ # ============================================================================
# ===== user programs ======================================================== # ===== user programs ========================================================
# ============================================================================ # ============================================================================
VPATH = .:./src:$(AMDIS_DIR)/src VPATH = .:./src
# ===== myprog =============================================================== # ===== myprog ===============================================================
...@@ -123,4 +74,9 @@ ellipt: $(ELLIPT_OFILES) ...@@ -123,4 +74,9 @@ ellipt: $(ELLIPT_OFILES)
$(LINK) $(CPPFLAGS) -o ellipt $(ELLIPT_OFILES) $(LIBS) $(LINK) $(CPPFLAGS) -o ellipt $(ELLIPT_OFILES) $(LIBS)
\end{verbatim} \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