CFD/hypre
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
a69f5777a2
hypre/docs/usr_misc.tex

555 lines
25 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}
In this, and the following several sections we discuss the steps to install
and use \hypre{} on a Unix-like operating system, such as Linux, AIX and Mac
OS X. Information on using \hypre{} under Windows is given in Section
\ref{sec-windows}.
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-partition 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}.
As an example of linking with \hypre{}, a user may refer to the \kbd{Makefile}
in the \file{examples} sub-directory. 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{Building and Using the Library Under Windows} \label{sec-windows}
The \hypre{} installation system is based on Makefiles, which are not
straightforward to use under Windows. Nevertheless, the library can be built and
linked to in a Windows environment with the help of the following tools:
\begin{itemize}
\item Cygwin {\bf (required)} - a Unix-like environment for Windows that can be
downloaded from \url{http://www.cygwin.com/}. Make sure to select the
Development Tools checkbox during installation.
\item MPICH2 {\bf (optional)} - an MPI implementation for Windows that can be
downloaded from
\url{http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads}.
Other MPI implementations for Windows should also work with appropriate
modifications. {\em For simplicity we will assume below that MPICH2 was
installed in \verb|C:\MPICH2|}.
\item Microsoft Visual Studio C++ {\bf (optional)} - a popular C++ compiler
environment with a freely available Express Edition that can be downloaded
from \url{http://www.microsoft.com/express/download/}. Visual C++ includes the
command-line compiler \kbd{CL.exe}.
\end{itemize}
After downloading the \hypre{} distribution, make sure to unpack it using
tar/gunzip under Cygwin, instead of a Windows tool such as WinZip which will
save the text files in DOS format. In general Cygwin does not handle very well
filenames with spaces, so it is a good idea to do your Cygwin work in a
directory path that does not contain spaces.
Below we outline several options for building and using \hypre{} depending on
your needs. Using Cygwin is central to all of them, but they differ by the
amount they rely on the Cygwin-provided GNU compiler (GCC) for the compilation
and the linking of the Library.
\subsection{Building and Using the Library Exclusively Under Cygwin}
This is the most straightforward option, as the Cygwin environment is
essentially compatible with Unix and the build system in \hypre{} should work
with minimal modifications.
If you don't need MPI, just change into \hypre{}'s \kbd{src} directory and type
\verb|./configure --without-MPI| followed by \verb|make|. Now you should be able
to build the non-MPI examples as well as the drivers in the \kbd{test} directory
and run them directly.
If you have MPICH2 installed in \verb|C:\MPICH2|, then configure and build
\hypre{} with:
\begin{verbatim}
./configure CC=gcc CXX=g++ \
CFLAGS="-O2 -I/cygdrive/c/MPICH2/include/" \
CXXFLAGS="-O2 -I/cygdrive/c/MPICH2/include" \
LDFLAGS="-L/cygdrive/c/MPICH2/lib/ -lmpi"
make
\end{verbatim}
The example codes (in the \kbd{examples} directory) and the test drivers in the
\kbd{test} directory can now be built using the above include and link options,
and can be run in parallel, for example, as follows:
\begin{verbatim}
/cygdrive/c/MPICH2/bin/mpiexec.exe -localonly 4 examples/ex5.exe
\end{verbatim}
\subsection{Building and Using a Static Windows Library With GCC Under Cygwin}
This is the recommended way to link an existing Visual C++ project with
\hypre{}. The build line (with MPICH2) is:
\begin{verbatim}
./configure CC=gcc CXX=g++ \
CFLAGS="-mno-cygwin -O2 -I/cygdrive/c/MPICH2/include" \
CXXFLAGS="-mno-cygwin -O2 -I/cygdrive/c/MPICH2/include" \
LDFLAGS="-mno-cygwin -L/cygdrive/c/MPICH2/lib -lmpi"
make
\end{verbatim}
The \kbd{-mno-cygwin} flag ensures that the static library will not depend on
the Cygwin-specific library \kbd{cygwin1.dll}, and therefore can be moved to a
different Windows box.
\subsubsection{Building an Example Code Under Cygwin}
\begin{enumerate}
\item
\begin{verbatim}
gcc -mno-cygwin -DMPICH_SKIP_MPICXX -I../hypre/include \
-I/cygdrive/c/MPICH2/include -c ex5.c
\end{verbatim}
\item
\begin{verbatim}
gcc -o ex5 ex5.o -mno-cygwin -L../hypre/lib -lHYPRE \
-L/cygdrive/c/MPICH2/lib -lmpi
\end{verbatim}
\item
The resulting executable can now be run on machines without a Cygwin
installation.
\end{enumerate}
\subsubsection{Building an Example Code with \kbd{CL.exe} (outside of Cygwin)}
\begin{enumerate}
\item Start Visual Studio command prompt (from the Start menu).
\item Make sure that the environment variables are correct. For example, is
\kbd{CL.exe} in the path (\verb|echo %PATH%|)? Is \kbd{kernel32.lib} in the
library path (\verb|echo %LIB%|)? When using \kbd{CL.exe}, you may need to
add, e.g.
\verb|\Program Files\Microsoft SDKs\Windows\v6.0A\Lib| to the \verb|%LIB%|
variable by right-clicking on \kbd{My Computer} and pressing the
\kbd{Environment Variables} button from the \kbd{Advanced} tab of
\kbd{Properties}.
\item \kbd{cd} into \hypre{}'s \verb|hypre\lib| directory
\item \verb|copy libHYPRE.a HYPRE.lib|
\item \verb|copy \cygwin\lib\gcc\i686-pc-mingw32\3.4.4\libgcc.a gcc.lib|
\item \kbd{cd} into \hypre{}'s \kbd{examples} directory
\item
\begin{verbatim}
cl ex5.c -nologo -MD -I..\hypre\include -I\MPICH2\include \
HYPRE.lib gcc.lib mpi.lib \
-link /libpath:..\hypre\lib /libpath:\MPICH2\lib
\end{verbatim}
\end{enumerate}
\subsubsection{Building an Example Code in the Visual C++ GUI}
\begin{enumerate}
\item Create an empty Win32 console application with no precompiled headers: \\
\verb| New project -> Win32 -> Win32 Console Application -> Application Settings|.
\item Add a driver source file, e.g. ex5.c, to the project.
\item Make sure \kbd{HYPRE.lib} and \kbd{gcc.lib} are in the \verb|hypre\lib|
directory (see Steps 4 and 5 in the \kbd{CL.exe} list above).
\item Select \kbd{Project -> Properties} from the Menu (or press \kbd{Alt-F7}).
\begin{itemize}
\item
Add \verb|hypre\include| and \verb|MPICH2\include| in \\
\verb|C/C++ -> General -> Additional Include Directories|.
\item
Add \verb|hypre\lib| and \verb|MPICH2\lib| in \\
\verb|Linker -> General -> Additional Library Directories|.
\item
Add \kbd{HYPRE.lib}, \kbd{gcc.lib} and \kbd{mpi.lib} in \\
\verb|Linker -> Input -> Additional Dependencies|.
\end{itemize}
\item Select \verb|Build -> Build Solution| from the Menu (or press \kbd{F7}).
\item Executable will be in the project's \kbd{Debug} sub-directory.
\end{enumerate}
\subsection{Building and Using a Static Windows Library With CL.exe Under Cygwin}
In some cases, it may be preferable to build \hypre{} using the native Visual
C++ compiler instead of GCC. The procedure for doing this is outlined in the
steps below:
\begin{enumerate}
\item Open a Visual Studio command prompt (from the Start menu) and run
\kbd{cygwin.bat} in it. Make sure that the compilers you need (e.g. a non-GCC
Fortran compiler) are in the Cygwin \verb\$PATH\ variable.
\item
\begin{verbatim}
./configure CC=cl CXX=cl \
CFLAGS="-nologo -DWIN32 -O2 -I/MPICH2/include" \
CXXFLAGS="-nologo -DWIN32 -O2 -I/MPICH2/include"
\end{verbatim}
\item If the above step fails with a ``cannot create executable'' error, make
sure that \kbd{kernel32.lib} is in the library path as discussed in the
\kbd{CL.exe} from the previous subsection.
%% \item \kbd{cd} into the top-level \kbd{src} directory.
\item Run \verb|config/windows.sh|
\item \verb|make|
\item Now you should be able to link with \hypre{} as in the previous section,
but without the need for the MD switch:
\begin{verbatim}
cl ex5.c -nologo -I..\hypre\include -I\MPICH2\include \
HYPRE.lib gcc.lib mpi.lib \
-link /libpath:..\hypre\lib /libpath:\MPICH2\lib
\end{verbatim}
\item You can also tell Visual Studio's linker to ignore the default library
\verb|libcmt.lib|.
\end{enumerate}
%-----------------------------------------------------------------------------
\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 flag
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. 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