Euclid_dh.h

00001 /*@HEADER
00002 // ***********************************************************************
00003 //
00004 //       Ifpack: Object-Oriented Algebraic Preconditioner Package
00005 //                 Copyright (2009) Sandia Corporation
00006 //
00007 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
00008 // license for use of this work by or on behalf of the U.S. Government.
00009 //
00010 // This library is free software; you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as
00012 // published by the Free Software Foundation; either version 2.1 of the
00013 // License, or (at your option) any later version.
00014 //
00015 // This library is distributed in the hope that it will be useful, but
00016 // WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00018 // Lesser General Public License for more details.
00019 //
00020 // You should have received a copy of the GNU Lesser General Public
00021 // License along with this library; if not, write to the Free Software
00022 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
00023 // USA
00024 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
00025 //
00026 // ***********************************************************************
00027 //@HEADER
00028 */
00029 
00030 #ifndef EUCLID_MPI_INTERFACE_DH
00031 #define EUCLID_MPI_INTERFACE_DH
00032 
00033 #define DEFAULT_DROP_TOL 0.01
00034 
00035 #include "euclid_common.h"
00036 
00037 /*======================================================================
00038  * Naming convention: functions ending in _mpi are located in
00039  * src/Euclid_mpi.c; those ending in _seq are in src/Euclid_seq.c;
00040  * most others should be in Euclid_all.c.
00041  *
00042  * Exceptions: all Apply() (triangular solves) are in src/Euclid_apply.c;
00043  *             except for the Apply for MPI PILU, which is called
00044  *             Mat_dhSolve, and is in src/Mat_dh.c
00045  *
00046  * Users should only need to call functions with names of the form
00047  * Euclid_dhXXX (public functions). 
00048  *
00049  * Some of the functions whose names are of the form XXX_private_XXX,
00050  * as could easily be static functions; similarly, the enums and
00051  * structs do need to be public.  They are, primarily, for ease in
00052  * debugging and ready reference.
00053  *
00054  * Exceptions: the apply_private functions aren't listed here --- they're
00055  * all static in src/Euclid_apply.c
00056  *======================================================================*/
00057 #ifdef __cplusplus
00058 extern "C"
00059 {
00060 #endif
00061 
00062   extern void Euclid_dhCreate (Euclid_dh * ctxOUT);
00063   extern void Euclid_dhDestroy (Euclid_dh ctx);
00064   extern void Euclid_dhSetup (Euclid_dh ctx);
00065   extern void Euclid_dhSolve (Euclid_dh ctx, Vec_dh lhs, Vec_dh rhs,
00066                   int *its);
00067   extern void Euclid_dhApply (Euclid_dh ctx, double *lhs, double *rhs);
00068 
00069   extern void Euclid_dhPrintTestData (Euclid_dh ctx, FILE * fp);
00070   extern void Euclid_dhPrintScaling (Euclid_dh ctx, FILE * fp);
00071 
00072   extern void Euclid_dhPrintStatsShort (Euclid_dh ctx, double setup,
00073                     double solve, FILE * fp);
00074 
00075 
00076   extern void Euclid_dhPrintStatsShorter (Euclid_dh ctx, FILE * fp);
00077   /* on-line reporting, for making quick tables */
00078 
00079   extern void Euclid_dhPrintHypreReport (Euclid_dh ctx, FILE * fp);
00080 
00081   extern void Euclid_dhPrintStats (Euclid_dh ctx, FILE * fp);
00082   /* prints same info as Euclid_dhPrintParams(), but also
00083      prints timing information, number of iterations, etc;
00084      may be called after solve is completed.
00085    */
00086 
00087 
00088 /*----------------------------------------------------------------------
00089  * Private data structures
00090  *----------------------------------------------------------------------*/
00091 
00092 #define MAX_OPT_LEN 20
00093 
00094 /* for internal timing */
00095 #define TIMING_BINS 10
00096   enum
00097   { SOLVE_START_T,
00098     TRI_SOLVE_T,        /* triangular solves */
00099     SETUP_T,            /* total setup */
00100     SUB_GRAPH_T,        /* setup SubdomainGraph_dh */
00101     FACTOR_T,           /* factorization */
00102     SOLVE_SETUP_T,      /* setup for solves */
00103     COMPUTE_RHO_T,
00104     /* note: SETUP_T - (FACTOR_T + SUB_GRAPH_T) should be small! */
00105     TOTAL_SOLVE_TEMP_T,
00106     TOTAL_SOLVE_T
00107   };
00108 
00109 /* for statistical reporting */
00110 #define STATS_BINS 10
00111   enum
00112   { NZA_STATS,          /* cumulative nonzeros for all systems solved */
00113     NZF_STATS,          /* cumulative nonzeros for all systems solved */
00114     NZA_USED_STATS,     /* cumulative nonzeros NOT dropped by sparseA */
00115     NZA_RATIO_STATS     /* NZA_USED_STATS/NZA_STATS, over all processors */
00116   };
00117 
00118 
00119 /* primary data structure: this is monstrously long; but it works. 
00120    Users must ensure the following fields are initialized prior
00121    to calling Euclid_dhSetup(): m, n, beg_row, A
00122 */
00123   struct _mpi_interface_dh
00124   {
00125     bool isSetup;
00126 
00127     double rho_init;
00128     double rho_final;
00129     /* Memory allocation for factor; will initially allocate space for 
00130        rho_init*nzA nonzeros; rho_final is computed after factorization,
00131        and is the minimum that rho_init whoulc have been to avoid
00132        memory reallocation; rho_final is a maximum across all processors.
00133      */
00134 
00135     int m;          /* local rows in matrix */
00136     int n;          /* global rows in matrix */
00137     double *rhs;        /* used for debugging; this vector is not owned! */
00138     void *A;            /*  void-pointer to Epetra_CrsMatrix */
00139     Factor_dh F;        /* data structure for the factor, F = L+U-I */
00140     SubdomainGraph_dh sg;
00141 
00142     REAL_DH *scale;     /* row scaling vector */
00143     bool isScaled;      /* set at runtime, turns scaling on or off */
00144 
00145     /* workspace for factorization and triangular solves */
00146     double *work;
00147     double *work2;
00148     int from, to;       /* which local rows to factor or solve */
00149 
00150     /* runtime parameters (mostly) */
00151     char algo_par[MAX_OPT_LEN]; /* parallelization strategy */
00152     char algo_ilu[MAX_OPT_LEN]; /* ILU factorization method */
00153     int level;          /* for ILU(k) */
00154     double droptol;     /* for ILUT */
00155     double sparseTolA;      /* for sparsifying A */
00156     double sparseTolF;      /* for sparsifying the factors */
00157     double pivotMin;        /* if pivots are <= to this value, fix 'em */
00158     double pivotFix;        /* multiplier for adjusting small pivots */
00159     double maxVal;      /* largest abs. value in matrix */
00160 
00161     /* data structures for parallel ilu (pilu) */
00162     SortedList_dh slist;
00163     ExternalRows_dh extRows;
00164 
00165     /* for use with Euclid's internal krylov solvers; */
00166     char krylovMethod[MAX_OPT_LEN];
00167     int maxIts;
00168     double rtol;
00169     double atol;
00170     int its;            /* number of times preconditioner was applied since last call to Setup */
00171     int itsTotal;       /* cululative number of times preconditioner was applied */
00172 
00173     /* internal statistics */
00174     int setupCount;
00175     int logging;
00176     double timing[TIMING_BINS];
00177     double stats[STATS_BINS];
00178     bool timingsWereReduced;
00179     bool printStats;        /* if true, on 2nd and subsequent calls to Setup,
00180                    calls Euclid_dhPrintStatsShorter().  Intent is to
00181                    print out stats for each setup phase when 
00182                    using Euclid, e.g, for nonlinear solves.
00183                  */
00184   };
00185 
00186 #ifdef __cplusplus
00187 }
00188 #endif
00189 #endif              /*  #ifndef EUCLID_MPI_INTERFACE_DH */

Generated on Wed May 12 21:30:17 2010 for IFPACK by  doxygen 1.4.7