Some work on the tutorial.

doc/tutorial/examples.tex

@@ -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}

doc/tutorial/installation.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}
 

doc/tutorial/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+.