\section{The \BS\ Computing Environment}
\label{sec:context}

In this section we describe the \BS\ computing environment.
\BS\ has an initialization routine that must be called prior
to any other \BS\ routine and a finalization routine that must
be called last.
We also introduce the most important \BS\ data
structure---{\tt BSprocinfo}---the \BS\ context.
All information about the parallel environment,
preconditioner options, and settings for the
iterative solvers is communicated to the \BS\ package
through the {\tt BSprocinfo} context data structure.

\subsection{Initializing and Finalizing the \BS\ Environment}

The first call to a \BS\ routine must be the initialization
routine {\tt BSinit()}.\findex{BSinit()}
The definition and arguments for this routine are as follows.
\begin{verbatim}
  int BSinit(int *argc, char ***args);
\end{verbatim}
The arguments {\tt argc} and {\tt argv} should be the
command line arguments as delivered in all C and C++ programs.
If you have not already done so, this routine initializes 
MPI with a call to {\tt MPI\_Init()}\findex{MPI_Init()} 
and initializes any logging routines that have 
been specified (see \S\ref{sec:misc}
for more information on logging within \BS).

The final call to a \BS\ routine must be 
the routine {\tt BSfinalize()}.\findex{BSfinalize()}
\begin{verbatim}
  int BSfinalize();
\end{verbatim}
This routine calls {\tt MPI\_Finalize()}\findex{MPI_Finalize()}
if \BS\ initialized MPI.

\subsection{The \BS\ Context {\tt BSprocinfo}}

The \BS\ context data structure, 
{\tt typedef BSprocinfo}\findex{typedef BSprocinfo},
contains all the information about the parallel environment, 
options for computing the preconditioner, and settings
for the iterative solver.
Before calling any \BS\ routines, the user must first allocate a
context of data type {\tt BSprocinfo} for \BS\ using 
the routine {\tt BScreate\_ctx()}.\findex{BScreate_ctx()}
\begin{verbatim}
  BSprocinfo  *BScreate_ctx();
\end{verbatim}
After the last \BS\ routine has been called, the context should be 
freed by calling the routine {\tt BSfree\_ctx()}. \findex{BSfree_ctx()}
\begin{verbatim}
  void  BSfree_ctx(BSprocinfo *context);
\end{verbatim}
After the call to {\tt BScreate\_ctx()}\findex{BScreate_ctx()},
you can then call one of many routines to modify the context.
We provide default settings for the context that we think will, in
general, provide the best performance, but you may benefit from
changing some of the settings.

The context options can be broken into three broad 
categories:  (1) the parallel environment, (2) options
concerning the computation of preconditioners, and
(3) settings for calls to an iterative solver.
In the following three subsections we describe the 
possible options and give the routine names that 
modify the context.

\subsubsection{Parallel Environment Options}
The following options concern the general 
parallel environment in which \BS\ operates.
The settings and routines for changing them are as follows:
\begin{itemize}

\begin{item}
{\bf Processor Set}: Definition of the processors that are participating 
in this call to \BS.  If the number of processors participating is equal
to the number of processors that are allocated to the user (this is the
default case), this value should be set to {\tt MPI\_COMM\_WORLD}.
If, for example, you wish to work on different matrices 
on different sets of processors at the same time and perhaps later 
combine the answers, you must set the procset parameter accordingly.
The program example {\tt grid2} solves two linear systems
simultaneously on a partitioned set of processors.
The default setting for this parameter is {\tt MPI\_COMM\_WORLD}.
To reset the value, call the routine 
{\tt BSctx\_set\_ps()}\findex{BSctx_set_ps()}.
\begin{verbatim}
   void  BSctx_set_ps(BSprocinfo *context,ProcSet *ps);
\end{verbatim}
You may wish to set the processor set to a duplicate 
communicator (using {\tt MPI\_Comm\_dup()}) to ensure that 
there are no message conflicts.
\end{item}

\begin{item}
{\bf Processor id}: The id number of this processor.
The default setting is given by the routine {\tt MPI\_Comm\_rank()}.
To reset the value, call the routine 
{\tt BSctx\_set\_id()}\findex{BSctx_set_id()}.
\begin{verbatim}
    void  BSctx_set_id(BSprocinfo *context,int id);
\end{verbatim}
\end{item}

\begin{item}
{\bf Number of processors}: The number of processors that
are calling \BS\ with a portion of the matrix.
The default setting is given by the routine {\tt MPI\_Comm\_size()}.
To reset the value, call the routine 
{\tt BSctx\_set\_np()}\findex{BSctx_set_np()}.
\begin{verbatim}
   void  BSctx_set_np(BSprocinfo *context,int np);
\end{verbatim}
\end{item}

\begin{item}
{\bf Error checking}: Simple error checking on the user's 
matrix structure and on some intermediate data structures.
The error checking is not very time consuming and is probably
a good option to use for the first few runs.
The default setting is \false\ (i.e., no error checking).
To change this value, call the routine
{\tt BSctx\_set\_err()}\findex{BSctx_set_err()}.
\begin{verbatim}
   void  BSctx_set_err(BSprocinfo *context,int err);
\end{verbatim}
\end{item}

\begin{item}
{\bf Print information}: Print information about the coloring,
reordering, and linear system solution options.
If set to \true\, this information is printed
during execution.
The default setting is \false.
To change this value, call the routine 
{\tt BSctx\_set\_pr()}\findex{BSctx_set_pr()}.
\begin{verbatim}
   void  BSctx_set_pr(BSprocinfo *context,int pr);
\end{verbatim}
\end{item}

\begin{item}
{\bf Print logging information}: Print logging 
information when the routine {\tt BSprint\_log()}
\findex{BSprint_log()} is called.
If set to \true\, this information is printed,
the default setting is \false.
To change this value, call the routine 
{\tt BSctx\_set\_print\_log()}\findex{BSctx_set_print_log()}.
\begin{verbatim}
   void  BSctx_set_print_log(BSprocinfo *context,int print);
\end{verbatim}
\end{item}

\begin{item}
{\bf Print current context options}: The current context 
options.  To print information on how the context
is currently set, call the function
{\tt BSctx\_print()}.\findex{BSctx_print()}
\begin{verbatim}
   void  BSctx_print(BSprocinfo *context);
\end{verbatim}
\end{item}
\end{itemize}

\subsubsection{Factorization Options}
The following options concern the computation of 
incomplete factorizations by \BS.
Calls to these routines must be made prior to calling
{\tt BSmain\_perm()}\findex{BSmain_perm()}.
The settings and routines for changing them are as follows:
\begin{itemize}
\begin{item}
{\bf Maximum clique size}: The maximum number of rows in a single clique.
You may wish to limit this value if the cliques become too large and
performance is impaired (an unlikely case in most applications and something
that requires understanding the algorithms in \BS).
The default setting is \intmax, which is defined
in the system include file {\tt limits.h}.
To change this value, call the routine 
{\tt BSctx\_set\_cs()}\findex{BSctx_set_cs()}.
\begin{verbatim}
   void  BSctx_set_cs(BSprocinfo *context,int cs);
\end{verbatim}
\end{item}
\sindex{cliques}

\begin{item}
{\bf Maximum identical node size}: The maximum number of rows
combined into an identical node. 
You may wish to limit this value if the i-nodes become too large
and performance is impaired (an unlikely case in most applications and
something that requires understanding the algorithms in \BS).
The default setting is \intmax.
To change this value, call the routine
{\tt BSctx\_set\_is()}\findex{BSctx_set_is()}.
\begin{verbatim}
   void  BSctx_set_is(BSprocinfo *context,int is);
\end{verbatim}
\end{item}
\sindex{identical nodes (i-nodes)}

\begin{item}
{\bf Type of local coloring}: The type of local coloring heuristic used.
There are two phases in obtaining a coloring of the matrix graph: a global 
phase in which the Jones/Plassmann algorithm is used and a local phase 
where either an incident degree ordering (IDO) coloring
or a saturated degree ordering (SDO) coloring is used.
In general, the SDO colorings are slightly better but take more time to find.
The default setting is IDO.
To change this value, call the routine
{\tt BSctx\_set\_ct()}\findex{BSctx_set_ct()}.
\begin{verbatim}
   void  BSctx_set_ct(BSprocinfo *context,int ct);
\end{verbatim}
\end{item}
\sindex{graph coloring}

\begin{item}
{\bf Retain data structures}: Information retained
during the reordering process.
The information saved (if the flag is set to \true)
allows a fast reordering if a matrix with the same structure 
is to be reordered later.
The default setting is \false.
To change this value, call the routine 
{\tt BSctx\_set\_rt()}\findex{BSctx_set_rt()}.
\begin{verbatim}
   void  BSctx_set_rt(BSprocinfo *context,int rt);
\end{verbatim}
\end{item}
\sindex{matrix reordering}

\begin{item}
{\bf No clique/i-node reordering}:  No attempt to find cliques
or i-nodes.
This flag should be set to \true\ (i.e., no search for i-nodes 
or cliques will be made) when you know that the i-node or clique
sizes will be 1 or very close to 1 (you may wish to experiment 
with this).
The default setting is \false.
To change this value, call the routine 
{\tt BSctx\_set\_si()}\findex{BSctx_set_si()}.
\begin{verbatim}
   void  BSctx_set_si(BSprocinfo *context,int si);
\end{verbatim}
\end{item}
\sindex{cliques}
\sindex{i-nodes}

\begin{item}
{\bf Scale linear system}: Scaling of the linear system.
The default setting is \true.
To change this value, {\tt BSctx\_set\_scaling()}
may be called.\findex{BSctx_set_scaling()}
\begin{verbatim}
   void  BSctx_set_scaling(BSprocinfo *context,int scale);
\end{verbatim}
Note that if this function is set, the routine
{\tt BSscale\_diag()}\findex{BSscale_diag()} must be
called to do the scaling.
We recommend using the matrix diagonal for scaling
so that the absolute value of the diagonal of the 
scaled system is set to one.
\end{item}
\end{itemize}
\sindex{diagonal scaling}

\subsubsection{Solver Options}
The following options concern the solution of
linear systems by \BS.
Calls to these routines must be made prior to calling
{\tt BSpar\_solve()}\findex{BSpar_solve()} 
or {\tt BSpar\_isolve()}\findex{BSpar_isolve()}.
The settings and routines for changing them are as follows:
\begin{itemize}
\begin{item}
{\bf Maximum number of iterations}: The maximum number of iterations
allowed the iterative solver.
The default setting is 100.
To change this value, call the routine
{\tt BSctx\_set\_max\_it()}\findex{BSctx_set_max_it()}.
\begin{verbatim}
   void  BSctx_set_max_it(BSprocinfo *context,int max_it)
\end{verbatim}
\end{item}

\begin{item}
{\bf GMRES restart value}:  The maximum number of vectors allowed
GMRES before~restarting.
The default setting is 20.
To change this value, call the routine
{\tt BSctx\_set\_restart()}\findex{BSctx_set_restart()}.
\begin{verbatim}
   void  BSctx_set_restart(BSprocinfo *context,int restart);
\end{verbatim}
\end{item}
\sindex{GMRES}

\begin{item}
{\bf Initial guess for iterative method}:
The initial vector used by the iterative method.
If this flag is \true, the initial guess is the zero vector.
If \false, the iterative method uses the vector passed to it.
This option is useful if a good estimate of the solution
is available.
The default setting is \true.
To change this value, call the routine 
{\tt BSctx\_set\_guess()}\findex{BSctx_set_guess()}.
\begin{verbatim}
   void  BSctx_set_guess(BSprocinfo *context,int guess);
\end{verbatim}
\end{item}

\begin{item}
{\bf Convergence tolerance}:  The relative residual tolerance
requested from the iterative solver.
The default setting is {\tt 1.0e-5}.
To change this value, call the routine
{\tt BSctx\_set\_tol()}\findex{BSctx_set_tol()}.
\begin{verbatim}
   void  BSctx_set_tol(BSprocinfo *context,FLOAT tol);
\end{verbatim}
If the linear system being solved is $Ax = b$, the relative
residual is $\| Ax - b \| / \|b \|$.
\end{item}
\sindex{convergence testing}

\begin{item}
{\bf Number of RHS vectors}:  The number of right-hand side (RHS) 
vectors to be input to the linear solver.
The iterative solvers in \BS\ can solve for multiple RHS simultaneously.
The default setting is 1.
This routine should not have to be called by the user because it is
set to the correct value if the routine 
{\tt BSsetup\_block()}\findex{BSsetup_block()} is called.
The program example {\tt grid5} demonstrates how to solve
for various numbers of RHS vectors.
To change this value, call the routine
{\tt BSctx\_set\_num\_rhs()}\findex{BSctx_set_num_rhs()}.
\begin{verbatim}
   void  BSctx_set_num_rhs(BSprocinfo *context,int num_rhs);
\end{verbatim}
\end{item}
\sindex{multiple right-hand sides}

\begin{item}
{\bf Preconditioner}:  The preconditioner to be 
used by the iterative solver.
The choices are incomplete Cholesky 
(\preicc),\sindex{incomplete Cholesky} incomplete
LU (\preilu),\sindex{incomplete LU} SSOR (\pressor),\sindex{SSOR}
or block Jacobi (\prejacobi).\sindex{Jacobi preconditioning}
The default setting is \preicc.
Note that the preconditioner specified must agree with the 
preconditioner computed.
For example, if \preicc\ is specified but an ILU preconditioner
is passed to the solver, a \BS\ error will be returned.
To change this value, call the routine
{\tt BSctx\_set\_pre()}\findex{BSctx_set_pre()}.
\begin{verbatim}
   void  BSctx_set_pre(BSprocinfo *context,int pre);
\end{verbatim}
\end{item}
\sindex{incomplete Cholesky}
\sindex{incomplete LU}
\sindex{SSOR}
\sindex{block Jacobi}

\begin{item}
{\bf Iterative method}:  The iterative method to be used.
The choices are conjugate gradients (\cg),\sindex{conjugate gradients}
GMRES (\gmres),\sindex{GMRES} or SYMMLQ (\symmlq).\sindex{SYMMLQ}
The default setting is \cg.
To change this value, call the routine
{\tt BSctx\_set\_method()}\findex{BSctx_set_method()}.
\begin{verbatim}
   void  BSctx_set_method(BSprocinfo *context,int method);
\end{verbatim}
\end{item}
\end{itemize}
\sindex{GMRES}
\sindex{conjugate gradients}
\sindex{SYMMLQ}

\newpage
