• Main Page
  • Related Pages
  • Namespaces
  • Classes
  • Files
  • File List
  • File Members

ml_operator.h

Go to the documentation of this file.
00001 /* ******************************************************************** */
00002 /* See the file COPYRIGHT for a complete copyright notice, contact      */
00003 /* person and disclaimer.                                               */        
00004 /* ******************************************************************** */
00005 
00006 /* ******************************************************************** */
00007 /* Declaration of the ML_Operator structure                             */
00008 /* ******************************************************************** */
00009 /* Author        : Charles Tong (LLNL) and Raymond Tuminaro (SNL)       */
00010 /* Date          : March, 1999                                          */
00011 /* ******************************************************************** */
00012 
00013 #ifndef __MLOPERATOR__
00014 #define __MLOPERATOR__
00015 
00016 /* ******************************************************************** */
00017 /* data structure type definition                                       */
00018 /* ******************************************************************** */
00019 
00020 typedef struct ML_Operator_Subspace_Struct ML_Operator_Subspace;
00021 typedef struct ML_Operator_Struct ML_Operator;
00022 typedef struct ML_Function_Struct ML_Function;
00023 typedef struct ML_GetrowFunc_Struct ML_GetrowFunc;
00024 
00025 /* ******************************************************************** */
00026 /* local include files                                                  */
00027 /* ******************************************************************** */
00028 
00029 #include "ml_common.h"
00030 #include "ml_defs.h"
00031 #include "ml_memory.h"
00032 #include "ml_bdrypts.h"
00033 #include "ml_1level.h"
00034 #include "ml_operatoragx.h"
00035 #include "ml_vec.h"
00036 #include "ml_gridagx.h"
00037 #include "ml_mls.h"
00038 #include "ml_utils.h"
00039 #include "ml_op_utils.h"
00040 
00041 #ifdef WKC
00042 #include <Epetra_Comm.h>
00043 #include <Epetra_MultiVector.h>
00044 #endif
00045 
00046 /* -------------------------------------------------------------------- */
00047 /*  data structure used to store pointers to functions such as matvec   
00048     used by the operator class.                                         */
00049 /* -------------------------------------------------------------------- */
00050 
00051 struct ML_Function_Struct {
00052    int ML_id;
00053    int Nrows;
00054    int (*func_ptr)(ML_Operator *, int, double *, int, double *);
00055 };
00056 
00057 /* -------------------------------------------------------------------- */
00058 /*  This data structure stores all information pertaining to performing  
00059     the Getrow function on an operator object.                          */
00060 /* -------------------------------------------------------------------- */
00061 
00062 struct ML_GetrowFunc_Struct {
00063    int           ML_id; 
00064    int           Nrows; /*used for all point rows even VBR point getrows*/
00065    int           N_block_rows; /*used to store number of block rows for VBR matrices*/
00066    ML_CommInfoOP *pre_comm; /*This is for all normal cases*/
00067    ML_CommInfoOP *post_comm; /*This is only used for the weird matvec/transpose*/
00068    int           (*func_ptr)(ML_Operator *,int,int*,int,int*,double*,int*);
00069    void          *data;
00070    int           use_loc_glob_map; /*If global when a point getrow is performed local indices are returned*/
00071    int           columns_loc_glob; /*Set to ML_LOCAL_INDICES if local or ML_GLOBAL_INDICES if global*/
00072    int           *loc_glob_map;
00073    int           *row_map;
00074 };
00075 
00076 /* -------------------------------------------------------------------- */
00077 /*  This data structure stores all information necessary to be able to   
00078     project out a subspace (e.g., a known nullspace).                   */
00079 /* -------------------------------------------------------------------- */
00080 
00081 struct ML_Operator_Subspace_Struct {
00082    double **basis_vectors;
00083    int    dimension;                
00084    int    vecleng;                  
00085    void   (*data_destroy)(void *);
00086    double *VAV;                     
00087    int    *pivots;                  
00088    int    VAVdone;                  
00089    double *res1,*res2,*vec1,*vec2;      /* work vectors */
00090 };
00091 
00092 typedef struct {
00093   double    threshold;
00094   int       (*aux_func_ptr)(ML_Operator *,int,int*,int,int*,double*,int*);
00095   int       enable;
00096   int       max_level;
00097   int**     filter;
00098   int       filter_size;
00099 } ML_Aux_Data;
00100 
00101 void ML_Aux_Data_Create(ML_Aux_Data** ptr);
00102 
00103 void ML_Aux_Data_Destroy(ML_Aux_Data** ptr);
00104 
00105 ML_Aux_Data* ML_Aux_Data_Clone(ML_Aux_Data* original);
00106 
00107 #define ML_TYPE_UNKNOWN 0
00108 #define ML_TYPE_ROW_MATRIX 1
00109 #define ML_TYPE_CRS_MATRIX 2
00110 #define ML_TYPE_VBR_MATRIX 3
00111 
00112 /* -------------------------------------------------------------------- */
00116 /* -------------------------------------------------------------------- */
00117 
00118 struct ML_Operator_Struct {
00119    int           ML_id; /*this and the getrow are not the pid that lives in comm
00120                            ML_id is used as the pid for communication in the
00121                            neighbor list however*/
00122    ML_Comm       *comm;
00123    ML_1Level     *to, *from;
00124    int           invec_leng, outvec_leng;
00125    void          *data;
00126    void          (*data_destroy)(void *);
00127    ML_Function   *matvec;
00128    ML_GetrowFunc *getrow;
00129    ML_DVector    *diagonal;      
00130    int           N_nonzeros;
00131    int           max_nz_per_row;
00132    int           blocks; /*only used for VBR matrices to say number of blocks*/
00133    int           from_an_ml_operator;
00134    ML_Operator   *sub_matrix;
00135    ML_BdryPts    *BCs;
00136    char          *DirichletRows; /* simple array of length outvec_leng
00137                                     to record Dirichlet rows */
00138    double        build_time, apply_time;
00139    double        apply_without_comm_time;
00140    int           ntimes, nflop;
00141    char          *label; 
00142    int           num_PDEs, num_rigid;
00143    double        lambda_max, lambda_min, lambda_max_img;
00144    int           N_total_cols_est;
00145    int           halfclone;
00146    int           spectral_radius_scheme, spectral_radius_max_iters;
00147    ML_Operator_Subspace *subspace;
00148                 /* This is just a hook into modes that we want to project out
00149                    before (after) invoking a MG cycle.  I couldn't think of
00150                    a more appropriate spot for these, especially as they need
00151                    to be available when ML is used as a preconditioner to a
00152                    Krylov method. */
00153    ML_Aux_Data   *aux_data;     
00155    int           type; /* simple ID that specifies the actual storage
00156                           used in data. It can be:
00157                           - ML_TYPE_UNKNOWN (default)
00158                           - ML_TYPE_ROW_MATRIX
00159                           - ML_TYPE_CRS_MATRIX
00160                           - ML_TYPE_VBR_MATRIX
00161                           By using this, we can same some wrapping, at least
00162                           for the finest-level operator.
00163                         */
00164 };
00165 
00166 
00167 /* -------------------------------------------------------------------- */
00168 /*  This structure is used to implement both drop tolerances and matrix  
00169     amalgamation (used in ML_aggregateCoarsenMIS()). The idea is to wrap 
00170     the getrow() of the original matrix such that it handles the blocking
00171     and the dropping.                                                   */ 
00172 /* -------------------------------------------------------------------- */
00173 
00174 struct amalg_drop {
00175    void                 *original_data;
00176    struct ML_GetrowFunc_Struct *original_getrow;
00177    double               *scaled_diag;
00178    int                  block_size;
00179    double               drop_tolerance;
00180    ML_Operator          *Amat;
00181    int                  *blk_inds;
00182    /* used by ML_Operator_AmalgamateAndDropWeak_VBlocks */
00183    void                 *vblock_data;  
00184 };
00185 
00186 /* -------------------------------------------------------------------- */
00187 /*  This structure is used to implicitly scale a matrix. The idea is to wrap 
00188     the getrow() of the original matrix such that it handles the blocking
00189     and the dropping.                                                   */ 
00190 /* -------------------------------------------------------------------- */
00191 
00192 struct ml_matscale {
00193   ML_Operator *Amat;
00194   double      scalar;
00195   int         destroy_child;
00196 };
00197 
00198 /* -------------------------------------------------------------------- */
00199 /*  This structure is used to implicitly scale a matrix with a vector.  *
00200  *  It extends ml_matscale.                                             */
00201 /* -------------------------------------------------------------------- */
00202 
00203 struct ml_matvscale {
00204   ML_Operator *Amat;
00205   double*     scale;
00206   int         destroy_child;
00207 };
00208 
00209 /* ******************************************************************** */
00210 /* ******************************************************************** */
00211 /*      User Interface Proto-types                                      */
00212 /* ******************************************************************** */
00213 /* ******************************************************************** */
00214 
00215 #ifndef ML_CPP
00216 #ifdef __cplusplus
00217 extern "C" {
00218 #endif
00219 #endif
00220 
00221 extern int ML_Operator_BlockPartition(ML_Operator *matrix, int n, int *nblks,
00222                           int *pnode_part, ML_Partitioner which_partitioner, 
00223               double *x_coord, double *y_coord, double *z_coord,int num_PDE_eqns);
00224 
00225 extern ML_Operator *ML_Operator_Create(ML_Comm *comm);
00226 extern int ML_Operator_Destroy(ML_Operator **);
00227 
00228 extern ML_Operator *ML_Operator_halfClone( ML_Operator *original);
00229 extern int ML_Operator_halfClone_Init(ML_Operator *mat,
00230              ML_Operator *original);
00231 
00232 extern int ML_Operator_halfClone_Clean( ML_Operator *mat);
00233 extern int ML_Operator_halfClone_Destroy( ML_Operator **mat);
00234 
00235 
00236 extern int ML_Operator_Init(ML_Operator *, ML_Comm *comm);
00237 extern int ML_Operator_Clean(ML_Operator *);
00238 extern int ML_Operator_Dump(ML_Operator *Ke, double *, double *,
00239           char *str, int);
00240 
00241 extern int ML_Operator_Set_Label(ML_Operator *, char *str);
00242 extern int ML_Operator_Set_1Levels(ML_Operator *, ML_1Level*, ML_1Level*);
00243 extern int ML_Operator_Set_BdryPts(ML_Operator *, ML_BdryPts *);
00244 extern int ML_Operator_Set_ApplyFuncData(ML_Operator *, int, int, void*,
00245                       int,int (*func)(ML_Operator *,int,double*,int,double*),int);
00246 extern int ML_Operator_Set_ApplyFunc(ML_Operator *, 
00247                        int (*func)(ML_Operator *, int, double *, int, double *));
00248 extern int ML_Operator_Set_Diag(ML_Operator *, int, double *);
00249 extern int ML_Operator_Set_Getrow(ML_Operator *, int, 
00250                        int (*func)(ML_Operator *,int,int*,int,int*,double*,int*));
00251 
00252 extern int ML_Operator_Getrow(ML_Operator *, int, int *, int, int *, 
00253                               double *, int*);
00254 extern int ML_Operator_Get_Diag(ML_Operator *Amat, int length, double **diag);
00255 
00256 extern int ML_Operator_Apply(ML_Operator *, int, double *, int, double *);
00257 
00258 #ifdef WKC
00259 /* WKC -- ADDED HEADER */
00260 extern int ML_Operator_Apply(ML_Operator *, int, Epetra_MultiVector &, 
00261                              int, Epetra_MultiVector & );
00262 #endif
00263 
00264 
00265 extern int ML_Operator_ApplyAndResetBdryPts(ML_Operator *, int, double *,
00266                                             int olen, double *);
00267 extern int ML_Operator_Add(ML_Operator *A, ML_Operator *B, ML_Operator *C,
00268          int matrix_type, double scalar);
00269 #ifdef WKC
00270 /* WKC -- ADDED HEADER */
00271 extern int ML_Operator_ApplyAndResetBdryPts(ML_Operator *, int, 
00272                      Epetra_MultiVector &, int olen, Epetra_MultiVector &);
00273 #endif
00274 extern int ML_Operator_MoveFromHierarchyAndClean(ML_Operator *newmat, 
00275              ML_Operator *hier);
00276 
00277 extern int ML_Operator_Move2HierarchyAndDestroy(ML_Operator **newmat, 
00278             ML_Operator *hier);
00279 
00280 extern int ML_Operator_Transpose(ML_Operator *Amat, ML_Operator *Amat_trans );
00281 
00282 extern int ML_Operator_Check_Getrow(ML_Operator *, int, char*);
00283 extern double ML_Operator_MaxNorm(ML_Operator *matrix, int divide_diag);
00284 extern int ML_Operator_Print(ML_Operator *matrix, const char label[]);
00285 extern int ML_Operator_ComputeNumNzs(ML_Operator *matrix);
00286 /* Operator Scaling */
00287 extern int ML_implicitscale_Getrow(ML_Operator *data, int N_requested_rows, 
00288            int requested_rows[], int allocated_space, 
00289            int columns[], double values[], 
00290            int row_lengths[]);
00291 extern int ML_implicitscale_Matvec(ML_Operator *Amat_in, int ilen, double p[], 
00292            int olen, double ap[]);
00293 extern ML_Operator *ML_Operator_ImplicitlyScale(ML_Operator *Amat, 
00294             double scalar,
00295             int OnDestroy_FreeChild);
00296 extern void ML_implicitscale_Destroy(void *data);
00297 /* Operator Scaling with a vector */
00298 extern int ML_implicitvscale_Getrow(ML_Operator *data, int N_requested_rows, 
00299            int requested_rows[], int allocated_space, 
00300            int columns[], double values[], 
00301            int row_lengths[]);
00302 extern int ML_implicitvscale_Matvec(ML_Operator *Amat_in, int ilen, double p[], 
00303            int olen, double ap[]);
00304 extern ML_Operator *ML_Operator_ImplicitlyVScale(ML_Operator *Amat, 
00305                                                  double* scale,
00306                                                  int OnDestroy_FreeChild);
00307 extern int ML_Operator_ExplicitDinvA(int BlockSize, 
00308               struct MLSthing *Dinv, ML_Operator *A);
00309 
00310 extern ML_Operator *ML_Operator_ImplicitlyBlockDinvScale(ML_Operator *Amat);
00311 extern void ML_implicitvscale_Destroy(void *data);
00312 extern int ML_implicitvcscale_Getrow(ML_Operator *data, int N_requested_rows, 
00313            int requested_rows[], int allocated_space, 
00314            int columns[], double values[], 
00315            int row_lengths[]);
00316 extern ML_Operator *ML_Operator_ImplicitlyVCScale(ML_Operator *Amat, 
00317                                                  double* scale,
00318                                                  int OnDestroy_FreeChild);
00319 extern int ML_CSR_DropSmall(ML_Operator *Pe, double AbsoluteDrop,
00320           double RelativeRowDrop, double RelativeColDrop);
00321 extern ML_Operator *ML_CSRmatrix_ColumnSubset(ML_Operator *Amat, int Nsubset,
00322                 int subset[]);
00323 extern int ML_Operator_Set_SpectralNormScheme_Calc(       ML_Operator *mat);
00324 extern int ML_Operator_Set_SpectralNormScheme_Anorm(      ML_Operator *mat);
00325 extern int ML_Operator_Set_SpectralNormScheme_Anasazi(    ML_Operator *mat);
00326 extern int ML_Operator_Set_SpectralNormScheme_PowerMethod(ML_Operator *mat);
00327 extern int ML_Operator_Set_SpectralNorm_Iterations(ML_Operator *mat, int its);
00328 
00329 
00330 
00331 /* amalagamation routines */
00332 extern int ML_Operator_AmalgamateAndDropWeak(ML_Operator *Amat, int block_size, 
00333                double drop_tolerance);
00334 
00335 extern int ML_Operator_UnAmalgamateAndDropWeak(ML_Operator *Amat, 
00336     int block_size, double drop_tolerance);
00337 
00338 extern int ML_amalg_drop_getrow(ML_Operator *data, int N_requested_rows, 
00339     int requested_rows[], int allocated_space, int columns[], 
00340                 double values[], int row_lengths[]);
00341 
00342 extern int ML_Operator_GetDistributedDiagBlocks(ML_Operator *mat, int *blkinfo,
00343                                                 int **new_ja, double **new_aa);
00344 
00345 extern double ML_Operator_GetMaxEig(ML_Operator *Amat);
00346 
00347 extern ML_Operator **ML_Operator_ArrayCreate( int length);
00348 extern int ML_Operator_ArrayDestroy( ML_Operator **array, int length);
00349 extern int ML_Operator_SetSubspace(ML *ml, double **vectors, int numvecs,
00350                                    int vecleng);
00351 extern int ML_Operator_Amalgamate_Vec_Trans(ML_Operator *Amat, int *blocked, 
00352                                             int **unblocked, int *size);
00353 extern int AZ_get_MSR_arrays(ML_Operator *, int **bindx, double **val);
00354      /* define this here so we don't have to include ml_aztec_utils.h */
00355      /* in ml_struct.c and ml_smoother.c                              */ 
00356 int ML_Operator_GetFlops(ML_Operator *mat);
00357 void ML_Operator_GetGlobalDimensions(ML_Operator *A,int *nrows,int *ncols);
00358 
00359 extern int ML_Operator_MisRootPts( ML_Operator *Amatrix,  int num_PDE_eqns,
00360              int **);
00361 
00362 #ifdef ML_WITH_EPETRA
00363 extern int ML_Epetra_CRSinsert(ML_Operator *, int, int *, double *, int);
00364 #endif
00365 
00366 #ifndef ML_CPP
00367 #ifdef __cplusplus
00368 }
00369 #endif
00370 #endif
00371 
00372 #endif