Ifpack Package Browser (Single Doxygen Collection)  Development
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Euclid_dh.h
Go to the documentation of this file.
1 /*@HEADER
2 // ***********************************************************************
3 //
4 // Ifpack: Object-Oriented Algebraic Preconditioner Package
5 // Copyright (2002) Sandia Corporation
6 //
7 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
8 // license for use of this work by or on behalf of the U.S. Government.
9 //
10 // Redistribution and use in source and binary forms, with or without
11 // modification, are permitted provided that the following conditions are
12 // met:
13 //
14 // 1. Redistributions of source code must retain the above copyright
15 // notice, this list of conditions and the following disclaimer.
16 //
17 // 2. Redistributions in binary form must reproduce the above copyright
18 // notice, this list of conditions and the following disclaimer in the
19 // documentation and/or other materials provided with the distribution.
20 //
21 // 3. Neither the name of the Corporation nor the names of the
22 // contributors may be used to endorse or promote products derived from
23 // this software without specific prior written permission.
24 //
25 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
26 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
29 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
30 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
31 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
32 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
33 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
34 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
35 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 //
37 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
38 //
39 // ***********************************************************************
40 //@HEADER
41 */
42 
43 #ifndef EUCLID_MPI_INTERFACE_DH
44 #define EUCLID_MPI_INTERFACE_DH
45 
46 #define DEFAULT_DROP_TOL 0.01
47 
48 #include "euclid_common.h"
49 
50 /*======================================================================
51  * Naming convention: functions ending in _mpi are located in
52  * src/Euclid_mpi.c; those ending in _seq are in src/Euclid_seq.c;
53  * most others should be in Euclid_all.c.
54  *
55  * Exceptions: all Apply() (triangular solves) are in src/Euclid_apply.c;
56  * except for the Apply for MPI PILU, which is called
57  * Mat_dhSolve, and is in src/Mat_dh.c
58  *
59  * Users should only need to call functions with names of the form
60  * Euclid_dhXXX (public functions).
61  *
62  * Some of the functions whose names are of the form XXX_private_XXX,
63  * as could easily be static functions; similarly, the enums and
64  * structs do need to be public. They are, primarily, for ease in
65  * debugging and ready reference.
66  *
67  * Exceptions: the apply_private functions aren't listed here --- they're
68  * all static in src/Euclid_apply.c
69  *======================================================================*/
70 #ifdef __cplusplus
71 extern "C"
72 {
73 #endif
74 
75  extern void Euclid_dhCreate (Euclid_dh * ctxOUT);
76  extern void Euclid_dhDestroy (Euclid_dh ctx);
77  extern void Euclid_dhSetup (Euclid_dh ctx);
78  extern void Euclid_dhSolve (Euclid_dh ctx, Vec_dh lhs, Vec_dh rhs,
79  int *its);
80  extern void Euclid_dhApply (Euclid_dh ctx, double *lhs, double *rhs);
81 
82  extern void Euclid_dhPrintTestData (Euclid_dh ctx, FILE * fp);
83  extern void Euclid_dhPrintScaling (Euclid_dh ctx, FILE * fp);
84 
85  extern void Euclid_dhPrintStatsShort (Euclid_dh ctx, double setup,
86  double solve, FILE * fp);
87 
88 
89  extern void Euclid_dhPrintStatsShorter (Euclid_dh ctx, FILE * fp);
90  /* on-line reporting, for making quick tables */
91 
92  extern void Euclid_dhPrintHypreReport (Euclid_dh ctx, FILE * fp);
93 
94  extern void Euclid_dhPrintStats (Euclid_dh ctx, FILE * fp);
95  /* prints same info as Euclid_dhPrintParams(), but also
96  prints timing information, number of iterations, etc;
97  may be called after solve is completed.
98  */
99 
100 
101 /*----------------------------------------------------------------------
102  * Private data structures
103  *----------------------------------------------------------------------*/
104 
105 #define MAX_OPT_LEN 20
106 
107 /* for internal timing */
108 #define TIMING_BINS 10
109  enum
111  TRI_SOLVE_T, /* triangular solves */
112  SETUP_T, /* total setup */
113  SUB_GRAPH_T, /* setup SubdomainGraph_dh */
114  FACTOR_T, /* factorization */
115  SOLVE_SETUP_T, /* setup for solves */
117  /* note: SETUP_T - (FACTOR_T + SUB_GRAPH_T) should be small! */
120  };
121 
122 /* for statistical reporting */
123 #define STATS_BINS 10
124  enum
125  { NZA_STATS, /* cumulative nonzeros for all systems solved */
126  NZF_STATS, /* cumulative nonzeros for all systems solved */
127  NZA_USED_STATS, /* cumulative nonzeros NOT dropped by sparseA */
128  NZA_RATIO_STATS /* NZA_USED_STATS/NZA_STATS, over all processors */
129  };
130 
131 
132 /* primary data structure: this is monstrously long; but it works.
133  Users must ensure the following fields are initialized prior
134  to calling Euclid_dhSetup(): m, n, beg_row, A
135 */
137  {
138  bool isSetup;
139 
140  double rho_init;
141  double rho_final;
142  /* Memory allocation for factor; will initially allocate space for
143  rho_init*nzA nonzeros; rho_final is computed after factorization,
144  and is the minimum that rho_init whoulc have been to avoid
145  memory reallocation; rho_final is a maximum across all processors.
146  */
147 
148  int m; /* local rows in matrix */
149  int n; /* global rows in matrix */
150  double *rhs; /* used for debugging; this vector is not owned! */
151  void *A; /* void-pointer to Epetra_CrsMatrix */
152  Factor_dh F; /* data structure for the factor, F = L+U-I */
154 
155  REAL_DH *scale; /* row scaling vector */
156  bool isScaled; /* set at runtime, turns scaling on or off */
157 
158  /* workspace for factorization and triangular solves */
159  double *work;
160  double *work2;
161  int from, to; /* which local rows to factor or solve */
162 
163  /* runtime parameters (mostly) */
164  char algo_par[MAX_OPT_LEN]; /* parallelization strategy */
165  char algo_ilu[MAX_OPT_LEN]; /* ILU factorization method */
166  int level; /* for ILU(k) */
167  double droptol; /* for ILUT */
168  double sparseTolA; /* for sparsifying A */
169  double sparseTolF; /* for sparsifying the factors */
170  double pivotMin; /* if pivots are <= to this value, fix 'em */
171  double pivotFix; /* multiplier for adjusting small pivots */
172  double maxVal; /* largest abs. value in matrix */
173 
174  /* data structures for parallel ilu (pilu) */
177 
178  /* for use with Euclid's internal krylov solvers; */
180  int maxIts;
181  double rtol;
182  double atol;
183  int its; /* number of times preconditioner was applied since last call to Setup */
184  int itsTotal; /* cululative number of times preconditioner was applied */
185 
186  /* internal statistics */
188  int logging;
190  double stats[STATS_BINS];
192  bool printStats; /* if true, on 2nd and subsequent calls to Setup,
193  calls Euclid_dhPrintStatsShorter(). Intent is to
194  print out stats for each setup phase when
195  using Euclid, e.g, for nonlinear solves.
196  */
197  };
198 
199 #ifdef __cplusplus
200 }
201 #endif
202 #endif /* #ifndef EUCLID_MPI_INTERFACE_DH */
SortedList_dh slist
Definition: Euclid_dh.h:175
#define REAL_DH
Definition: euclid_common.h:53
REAL_DH * scale
Definition: Euclid_dh.h:155
double timing[TIMING_BINS]
Definition: Euclid_dh.h:189
SubdomainGraph_dh sg
Definition: Euclid_dh.h:153
ExternalRows_dh extRows
Definition: Euclid_dh.h:176
void Euclid_dhPrintStatsShorter(Euclid_dh ctx, FILE *fp)
Definition: Euclid_dh.c:1039
char algo_par[MAX_OPT_LEN]
Definition: Euclid_dh.h:164
void Euclid_dhPrintScaling(Euclid_dh ctx, FILE *fp)
Definition: Euclid_dh.c:1058
void Euclid_dhApply(Euclid_dh ctx, double *rhs, double *lhs)
Definition: Euclid_apply.c:60
char krylovMethod[MAX_OPT_LEN]
Definition: Euclid_dh.h:179
void Euclid_dhPrintTestData(Euclid_dh ctx, FILE *fp)
Definition: Euclid_dh.c:1177
void Euclid_dhPrintStats(Euclid_dh ctx, FILE *fp)
Definition: Euclid_dh.c:868
void Euclid_dhCreate(Euclid_dh *ctxOUT)
Definition: Euclid_dh.c:66
char algo_ilu[MAX_OPT_LEN]
Definition: Euclid_dh.h:165
double * work2
Definition: Euclid_dh.h:160
#define TIMING_BINS
Definition: Euclid_dh.h:108
Definition: Vec_dh.h:52
double stats[STATS_BINS]
Definition: Euclid_dh.h:190
void Euclid_dhDestroy(Euclid_dh ctx)
Definition: Euclid_dh.c:133
void Euclid_dhSolve(Euclid_dh ctx, Vec_dh x, Vec_dh b, int *its)
Definition: Euclid_dh.c:842
bool timingsWereReduced
Definition: Euclid_dh.h:191
#define MAX_OPT_LEN
Definition: Euclid_dh.h:105
void Euclid_dhSetup(Euclid_dh ctx)
Definition: Euclid_dh.c:199
void Euclid_dhPrintHypreReport(Euclid_dh ctx, FILE *fp)
Definition: Euclid_dh.c:1098
void Euclid_dhPrintStatsShort(Euclid_dh ctx, double setup, double solve, FILE *fp)
Definition: Euclid_dh.c:945
#define STATS_BINS
Definition: Euclid_dh.h:123