CFD/hypre
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
a2cc04a6a0
hypre/docs/usr_misc.tex
ulrikey baa12be137 changed small letter to capital
2006-12-14 16:14:23 +00:00

382 lines
17 KiB
TeX
Raw Blame History

%=============================================================================
%=============================================================================
\chapter{General Information}
%-----------------------------------------------------------------------------
\section{Getting the Source Code}
The \hypre{} distribution tar file is available from the Software link of the
\hypre{} web page, \url{http://www.llnl.gov/CASC/hypre/}. The \hypre{} Software
distribution page allows access to the tar files of the latest and previous
general and beta distributions as well as documentation.
%-----------------------------
\section{Building the Library}
After unpacking the \hypre{} tar file, the source code will be in the ``src''
sub-directory of a directory named hypre-VERSION, where VERSION is the current
version number (e.g., hypre-1.8.4, with a ``b'' appended for a beta release).
Move to the ``src'' sub-directory to build \hypre{} for the host platform. The
simplest method is to configure, compile and install the libraries in
\file{./hypre/lib} and \file{./hypre/include} directories, which is accomplished
by:
\begin{verbatim}
./configure
make
\end{verbatim}
NOTE: when executing on an IBM platform \file{configure} must be executed under
the nopoe script (\file{./nopoe ./configure <option> ...<option>}) to force a
single task to be run on the log-in node.
There are many options to \file{configure} and \file{make} to customize such
things as installation directories, compilers used, compile and load flags, etc.
Executing \file{configure} results in the creation of platform specific files
that are used when building the library. The information may include such things
as the system type being used for building and executing, compilers being used,
libraries being searched, option flags being set, etc. When all of the
searching is done two files are left in the \file{src} directory;
\file{config.status} contains information to recreate the current configuration
and \file{config.log} contains compiler messages which may help in debugging
\file{configure} errors.
Upon successful completion of \file{configure} the file
\file{config/Makefile.config} is created from its template
\file{config/Makefile.config.in} and \hypre{} is ready to be built.
Executing \file{make}, with or without targets being specified, in the
\file{src} directory initiates compiling of all of the source code and building
of the \hypre{} library. If any errors occur while compiling, the user can edit
the file \file{config/Makefile.config} directly then run \file{make} again;
without having to re-run configure.
When building \hypre{} without the install target, the libraries and include
files will be copied into the default directories, \file{src/hypre/lib} and
\file{src/hypre/include}, respectively.
When building \hypre{} using the install target, the libraries and include files
will be copied into the directories that the user specified in the options to
\file{configure}, e.g. \file{--prefix=/usr/apps}. If none were specified the
default directories, \file{src/hypre/lib} and \file{src/hypre/include}, are
used.
%-----------------------------
\subsection{Configure Options}\label{config_options}
There are many options to \file{configure} to allow the user to override and
refine the defaults for any system. The best way to find out what options are
available is to display the help package, by executing \file{./configure
--help}, which also includes the usage information. The user can mix and match
the configure options and variable settings to meet their needs.
Some of the commonly used options include:
\begin{verbatim}
--enable-debug Sets compiler flags to generate information
needed for debugging.
--enable-shared Build shared libraries.
NOTE: in order to use the resulting shared
libraries the user MUST have the path to
the libraries defined in the environment
variable LD_LIBRARY_PATH.
--with-print-errors Print HYPRE errors
--with-no-global-partitioning Do NOT store a global partition of the data
NOTE: this option reduces storage and improves
performance when using many thousands of
processors (not recommended for < 1000
processors).
\end{verbatim}
The user can mix and match the configure options and variable settings to meet
their needs. It should be noted that \hypre{} can be configured with external
BLAS and LAPACK libraries, which can be combined with any other option. This is
done as follows (currently, both libraries must be configured as external
together):
\begin{verbatim}
./configure --with-blas-lib="blas-lib-name" --with-blas-lib-dirs="path-to-blas-lib" \
--with-lapack-lib="lapack-lib-name" --with-lapack-lib-dirs="path-to-lapack-lib"
\end{verbatim}
The output from \file{configure} is several pages long. It reports the system
type being used for building and executing, compilers being used, libraries
being searched, option flags being set, etc.
%-----------------------------
\subsection{Make Targets}
The make step in building \hypre{} is where the compiling, loading and creation
of libraries occurs. Make has several options that are called targets. These
include:
\begin{verbatim}
help prints the details of each target
all default target in all directories
compile the entire library
does NOT rebuild documentation
clean deletes all files from the current directory that are
created by building the library
distclean deletes all files from the current directory that are created
by configuring or building the library
install compile the source code, build the library and copy executables,
libraries, etc to the appropriate directories for user access
uninstall deletes all files that the install target created
tags runs etags to create a tags table
file is named TAGS and is saved in the top-level directory
test depends on the all target to be completed
removes existing temporary installation directories
creates temporary installation directories
copies all libHYPRE* and *.h files to the temporary locations
builds the test drivers; linking to the temporary locations to
simulate how application codes will link to HYPRE
\end{verbatim}
%-----------------------------------------------------------------------------
\section{Testing the Library}
The \kbd{examples} subdirectory contains several codes that can be used to test
the newly created \hypre{} library. To create the executable versions, move
into the \kbd{examples} subdirectory, enter \kbd{make} then execute the codes as
described in the initial comments section of each source code.
%-----------------------------
\section{Linking to the Library}
An application code linking with \hypre{} must be compiled with
\kbd{-I\$PREFIX/include} and linked with \kbd{-L\$PREFIX/lib -lHYPRE}, where
\kbd{\$PREFIX} is the directory where \hypre{} is installed, default is
\kbd{hypre}, or as defined by the configure option \kbd{--prefix=PREFIX}. As
noted above, if \hypre{} was built as a shared library the user MUST have its
location defined in the environment variable \kbd{LD\_LIBRARY\_PATH}.
We strongly recommend that users link with \kbd{libHYPRE.a} rather than
specifying each of the separate \hypre{} libraries, i.e.
\kbd{libHYPRE\_krylov.a}, \kbd{libHYPRE\_parcsr\_mv.a}, etc. By using
\kbd{libHYPRE.a} the user is guaranteed to have all capabilities without having
to change their link flags.
As an example of linking with \hypre{}, a user may refer to the \kbd{Makefile}
in the \file{examples} subdirectory. It is designed to build codes similar to
user applications that link with and call \hypre{}. All include and linking
flags are defined in the \file{Makefile.config} file by \file{configure}.
%-----------------------------------------------------------------------------
\section{Error Flags}
Every \hypre{} function returns an integer, which is used to indicate errors
during execution. Note that the error flag returned by a given function
reflects the errors from {\em all} previous calls to \hypre{} functions. In
particular, a value of zero means that all \hypre{} functions up to (and
including) the current one have completed successfully. This new error flags
system is being implemented throughout the library, but currently there are
still functions that do not support it. The error flag value is a combination
of one or a few of the following error codes:
\begin{enumerate}
\item \code{HYPRE\_ERROR\_GENERIC} -- describes a generic error
\item \code{HYPRE\_ERROR\_MEMORY} -- \hypre{} was unable to allocate memory
\item \code{HYPRE\_ERROR\_ARG} -- error in one of the arguments of a \hypre{} function
\item \code{HYPRE\_ERROR\_CONV} -- a \hypre{} solver did not converge as expected
\end{enumerate}
One can use the \code{HYPRE\_CheckError} function to determine exactly which
errors have occurred:
\begin{display} \begin{verbatim}
/* call some HYPRE functions */
hypre_ierr = HYPRE_Function();
/* check if the previously called hypre functions returned error(s) */
if (hypre_ierr)
/* check if the error with code HYPRE_ERROR_CODE has occurred */
if (HYPRE_CheckError(hypre_ierr,HYPRE_ERROR_CODE))
\end{verbatim} \end{display}
The corresponding FORTRAN code is
\begin{display} \begin{verbatim}
C header file with hypre error codes
include 'HYPRE_error_f.h'
C call some HYPRE functions
call HYPRE_Function(..., hypre_ierr);
C check if the previously called hypre functions returned error(s)
if (hypre_ierr .ne. 0) then
C check if the error with code HYPRE_ERROR_CODE has occurred
HYPRE_CheckError(hypre_ierr,HYPRE_ERROR_CODE,check)
if (check .ne. 0) then
\end{verbatim} \end{display}
The global error flag can also be obtained directly, between calls to other
\hypre{} functions, by calling \code{HYPRE\_GetError()}. If an argument error
(\code{HYPRE\_ERROR\_ARG}) has occurred, the argument index (counting from 1)
can be obtained from \code{HYPRE\_GetErrorArg()}. To get a character string
with a description of all errors in a given error flag, use
\begin{display} \begin{verbatim}
HYPRE_DescribeError(int hypre_ierr, char *descr);
\end{verbatim} \end{display}
Finally, if \hypre{} was configured with \code{--with-print-errors}, additional
error information will be printed to the standard error during execution.
%-----------------------------------------------------------------------------
\section{Bug Reporting and General Support}
Simply send and email to \kbd{hypre-support@llnl.gov} to report bugs, request
features, or ask general usage questions. An {\em issue number} will be
assigned to your email so that we can track progress (we are using an issue
tracking tool called Roundup to do this).
Users should include as much relevant information as possible in their issue
emails, including at a minimum, the \hypre{} version number being used. For
compile and runtime problems, please also include the machine type, operating
system, MPI implementation, compiler, and any error messages produced.
%-----------------------------------------------------------------------------
\section{Using HYPRE in External FEI Implementations}
\label{LSI_install}
To set up \hypre{} for use in external, e.g. Sandia's, {\tt FEI} implementations
one needs to follow the following steps:
\begin{enumerate}
\item obtain the \hypre{} and Sandia's {\tt FEI} source codes,
\item compile Sandia's {\tt FEI} (fei-2.5.0) to create the
{\tt fei\_base} library.
\item compile \hypre{}
\begin{enumerate}
\item unpack the archive and go into the \code{src} directory
\item do a 'configure' with the {\tt --with-fei-inc-dir} option set to
the {\tt FEI} include directory plus other compile options
\item compile with {\tt make install} to create the
{\tt HYPRE\_LSI} library in {\tt hypre/lib}.
\end{enumerate}
\item call the {\tt FEI} functions in your application code (as shown in
Chapters \ref{ch-FEI} and \ref{ch-Solvers})
\begin{enumerate}
\item include {\tt cfei-hypre.h} in your file
\item include {\tt FEI\_Implementation.h} in your file
\end{enumerate}
\item Modify your \code{Makefile}
\begin{enumerate}
\item include \hypre{}'s {\tt include} and {\tt lib} directories in the search paths.
\item Link with \code{-lfei_base -lHYPRE_LSI}.
Note that the order in which the libraries are listed may be important.
\end{enumerate}
\end{enumerate}
Building an application executable often requires linking with many different
software packages, and many software packages use some LAPACK and/or BLAS
functions. In order to alleviate the problem of multiply defined functions
at link time, it is recommended that all software libraries are stripped of
all LAPACK and BLAS function definitions. These LAPACK and BLAS functions
should then be resolved at link time by linking with the system LAPACK and
BLAS libraries (e.g. dxml on DEC cluster). Both \hypre{} and SuperLU were
built with this in mind. However, some other software library files needed
may have the BLAS functions defined in them. To avoid the problem of
multiply defined functions, it is recommended that the offending library
files be stripped of the BLAS functions.
%Comments about \hypre{}'s finite element interface can be directed
%to Charles Tong (925-422-3411, chtong@llnl.gov).
%-----------------------------------------------------------------------------
\section{Calling HYPRE from Other Languages}
The \hypre{} library can be called from a variety of languages. This is
currently provided through two basic mechanisms:
\begin{itemize}
\item The Babel interfaces described in Chapter~\ref{ch-babel} utilize the Babel
tool to provide the most extensive language support (note that the \hypre{}
library is moving towards using the Babel tool as its primary means of getting
language interoperability).
\item A Fortran interface is manually supported to mirror the ``native'' C
interface used throughout most of this manual. We describe this interface next.
\end{itemize}
Typically, the Fortran subroutine name is the same as the C name, unless it is
longer than 31 characters. In these situations, the name is condensed to 31
characters, usually by simple truncation. For now, users should look at the
Fortran test drivers (*.f codes) in the \code{test} directory for the correct
condensed names. In the future, this aspect of the interface conversion will be
made consistent and straightforward.
The Fortran subroutine argument list is always the same as the corresponding C
routine, except that the error return code \code{ierr} is always last.
Conversion from C parameter types to Fortran argument type is summarized in
Table \ref{table-fortran-interface-types}.
\begin{table}
\center
\begin{tabular}{|l|l|}
\hline
C parameter & Fortran argument \\
\hline\hline
\code{int i} & \code{integer i} \\
\code{double d} & \code{double precision d} \\
\code{int *array} & \code{integer array(*)} \\
\code{double *array} & \code{double precision array(*)} \\
\code{char *string} & \code{character string(*)} \\
\code{HYPRE\_Type object} & \code{integer*8 object} \\
\code{HYPRE\_Type *object} & \code{integer*8 object} \\
\hline
\end{tabular}
\caption{%
Conversion from C parameters to Fortran arguments
}
\label{table-fortran-interface-types}
\end{table}
Array arguments in \hypre{} are always of type \code{(int *)} or \code{(double
*)}, and the corresponding Fortran types are simply \code{integer} or
\code{double precision} arrays. Note that the Fortran arrays may be indexed in
any manner. For example, an integer array of length \code{N} may be declared in
fortran as either of the following:
\begin{display}
\begin{verbatim}
integer array(N)
integer array(0:N-1)
\end{verbatim}
\end{display}
\hypre{} objects can usually be declared as in the table because
\code{integer*8} usually corresponds to the length of a pointer. However, there
may be some machines where this is not the case (although we are not aware of
any at this time). On such machines, the Fortran type for a \hypre{} object
should be an \code{integer} of the appropriate length.
This simple example illustrates the above information:
C prototype:
\begin{display}
\begin{verbatim}
int HYPRE_IJMatrixSetValues(HYPRE_IJMatrix matrix,
int nrows, int *ncols,
const int *rows, const int *cols,
const double *values);
\end{verbatim}
\end{display}
The corresponding Fortran code for calling this routine is as follows:
\begin{display}
\begin{verbatim}
integer*8 matrix,
integer nrows, ncols(MAX_NCOLS)
integer rows(MAX_ROWS), cols(MAX_COLS)
double precision values(MAX_COLS)
integer ierr
call HYPRE_IJMatrixSetValues(matrix, nrows, ncols, rows, cols,
& values, ierr)
\end{verbatim}
\end{display}
Reference in New Issue View Git Blame Copy Permalink