Actual source code: coarsen.c

petsc-3.12.0 2019-09-29
Report Typos and Errors

  2:  #include <petsc/private/matimpl.h>

  4: /* Logging support */
  5: PetscClassId MAT_COARSEN_CLASSID;

  7: PetscFunctionList MatCoarsenList              = 0;
  8: PetscBool         MatCoarsenRegisterAllCalled = PETSC_FALSE;

 10: /*@C
 11:    MatCoarsenRegister - Adds a new sparse matrix coarsening algorithm to the matrix package.

 13:    Logically Collective

 15:    Input Parameters:
 16: +  sname - name of coarsen (for example MATCOARSENMIS)
 17: -  function - function pointer that creates the coarsen type

 19:    Level: developer

 21:    Sample usage:
 22: .vb
 23:    MatCoarsenRegister("my_agg",MyAggCreate);
 24: .ve

 26:    Then, your aggregator can be chosen with the procedural interface via
 27: $     MatCoarsenSetType(agg,"my_agg")
 28:    or at runtime via the option
 29: $     -mat_coarsen_type my_agg

 31: .seealso: MatCoarsenRegisterDestroy(), MatCoarsenRegisterAll()
 32: @*/
 33: PetscErrorCode  MatCoarsenRegister(const char sname[],PetscErrorCode (*function)(MatCoarsen))
 34: {

 38:   MatInitializePackage();
 39:   PetscFunctionListAdd(&MatCoarsenList,sname,function);
 40:   return(0);
 41: }

 43: /*@C
 44:    MatCoarsenGetType - Gets the Coarsen method type and name (as a string)
 45:         from the coarsen context.

 47:    Not collective

 49:    Input Parameter:
 50: .  coarsen - the coarsen context

 52:    Output Parameter:
 53: .  type - coarsener type

 55:    Level: advanced

 57:    Not Collective

 59: .seealso: MatCoarsenCreate(), MatCoarsenType, MatCoarsenSetType()
 60: @*/
 61: PetscErrorCode  MatCoarsenGetType(MatCoarsen coarsen,MatCoarsenType *type)
 62: {
 66:   *type = ((PetscObject)coarsen)->type_name;
 67:   return(0);
 68: }

 70: /*@
 71:    MatCoarsenApply - Gets a coarsen for a matrix.

 73:    Collective on MatCoarsen

 75:    Input Parameter:
 76: .   coarsen - the coarsen

 78:    Options Database Keys:
 79:    To specify the coarsen through the options database, use one of
 80:    the following
 81: $    -mat_coarsen_type mis
 82:    To see the coarsen result
 83: $    -mat_coarsen_view

 85:    Level: advanced

 87:    Notes:
 88:     Use MatCoarsenGetData() to access the results of the coarsening

 90:    The user can define additional coarsens; see MatCoarsenRegister().

 92: .seealso:  MatCoarsenRegister(), MatCoarsenCreate(),
 93:            MatCoarsenDestroy(), MatCoarsenSetAdjacency(), ISCoarsenToNumbering(),
 94:            ISCoarsenCount(), MatCoarsenGetData()
 95: @*/
 96: PetscErrorCode  MatCoarsenApply(MatCoarsen coarser)
 97: {

103:   if (!coarser->graph->assembled) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
104:   if (coarser->graph->factortype) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
105:   if (!coarser->ops->apply) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"Must set type with MatCoarsenSetFromOptions() or MatCoarsenSetType()");
106:   PetscLogEventBegin(MAT_Coarsen,coarser,0,0,0);
107:   (*coarser->ops->apply)(coarser);
108:   PetscLogEventEnd(MAT_Coarsen,coarser,0,0,0);
109:   return(0);
110: }

112: /*@
113:    MatCoarsenSetAdjacency - Sets the adjacency graph (matrix) of the thing to be coarsened.

115:    Collective on MatCoarsen

117:    Input Parameters:
118: +  agg - the coarsen context
119: -  adj - the adjacency matrix

121:    Level: advanced

123: .seealso: MatCoarsenCreate(), MatCoarsenApply()
124: @*/
125: PetscErrorCode  MatCoarsenSetAdjacency(MatCoarsen agg, Mat adj)
126: {
130:   agg->graph = adj;
131:   return(0);
132: }

134: /*@
135:    MatCoarsenSetStrictAggs - WHAT IS THIS?

137:    Logically Collective on MatCoarsen

139:    Input Parameters:
140: +  agg - the coarsen context
141: -  str - the adjacency matrix

143:    Level: advanced

145: .seealso: MatCoarsenCreate()
146: @*/
147: PetscErrorCode MatCoarsenSetStrictAggs(MatCoarsen agg, PetscBool str)
148: {
151:   agg->strict_aggs = str;
152:   return(0);
153: }

155: /*@
156:    MatCoarsenDestroy - Destroys the coarsen context.

158:    Collective on MatCoarsen

160:    Input Parameters:
161: .  agg - the coarsen context

163:    Level: advanced

165: .seealso: MatCoarsenCreate()
166: @*/
167: PetscErrorCode  MatCoarsenDestroy(MatCoarsen *agg)
168: {

172:   if (!*agg) return(0);
174:   if (--((PetscObject)(*agg))->refct > 0) {*agg = 0; return(0);}

176:   if ((*agg)->ops->destroy) {
177:     (*(*agg)->ops->destroy)((*agg));
178:   }

180:   if ((*agg)->agg_lists) {
181:     PetscCDDestroy((*agg)->agg_lists);
182:   }

184:   PetscHeaderDestroy(agg);
185:   return(0);
186: }

188: /*@
189:    MatCoarsenCreate - Creates a coarsen context.

191:    Collective

193:    Input Parameter:
194: .   comm - MPI communicator

196:    Output Parameter:
197: .  newcrs - location to put the context

199:    Level: advanced

201: .seealso: MatCoarsenSetType(), MatCoarsenApply(), MatCoarsenDestroy(),
202:           MatCoarsenSetAdjacency(), MatCoarsenGetData()

204: @*/
205: PetscErrorCode  MatCoarsenCreate(MPI_Comm comm, MatCoarsen *newcrs)
206: {
207:   MatCoarsen     agg;

211:   *newcrs = 0;

213:   MatInitializePackage();
214:   PetscHeaderCreate(agg, MAT_COARSEN_CLASSID,"MatCoarsen","Matrix/graph coarsen", "MatCoarsen", comm, MatCoarsenDestroy, MatCoarsenView);

216:   *newcrs = agg;
217:   return(0);
218: }

220: /*@C
221:    MatCoarsenView - Prints the coarsen data structure.

223:    Collective on MatCoarsen

225:    Input Parameters:
226: +  agg - the coarsen context
227: -  viewer - optional visualization context

229:    Level: advanced

231:    Note:
232:    The available visualization contexts include
233: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
234: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
235:          output where only the first processor opens
236:          the file.  All other processors send their
237:          data to the first processor to print.

239:    The user can open alternative visualization contexts with
240: .     PetscViewerASCIIOpen() - output to a specified file

242: .seealso: PetscViewerASCIIOpen()
243: @*/
244: PetscErrorCode  MatCoarsenView(MatCoarsen agg,PetscViewer viewer)
245: {
247:   PetscBool      iascii;

251:   if (!viewer) {
252:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)agg),&viewer);
253:   }

257:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
258:   PetscObjectPrintClassNamePrefixType((PetscObject)agg,viewer);
259:   if (agg->ops->view) {
260:     PetscViewerASCIIPushTab(viewer);
261:     (*agg->ops->view)(agg,viewer);
262:     PetscViewerASCIIPopTab(viewer);
263:   }
264:   return(0);
265: }

267: /*@C
268:    MatCoarsenSetType - Sets the type of aggregator to use

270:    Collective on MatCoarsen

272:    Input Parameter:
273: +  coarser - the coarsen context.
274: -  type - a known coarsening method

276:    Options Database Command:
277: $  -mat_coarsen_type  <type>
278: $      Use -help for a list of available methods
279: $      (for instance, mis)

281:    Level: advanced

283: .seealso: MatCoarsenCreate(), MatCoarsenApply(), MatCoarsenType, MatCoarsenGetType()

285: @*/
286: PetscErrorCode  MatCoarsenSetType(MatCoarsen coarser, MatCoarsenType type)
287: {
288:   PetscErrorCode ierr,(*r)(MatCoarsen);
289:   PetscBool      match;


295:   PetscObjectTypeCompare((PetscObject)coarser,type,&match);
296:   if (match) return(0);

298:   if (coarser->setupcalled) {
299:      (*coarser->ops->destroy)(coarser);

301:     coarser->ops->destroy = NULL;
302:     coarser->subctx       = 0;
303:     coarser->setupcalled  = 0;
304:   }

306:    PetscFunctionListFind(MatCoarsenList,type,&r);

308:   if (!r) SETERRQ1(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown coarsen type %s",type);

310:   coarser->ops->destroy = (PetscErrorCode (*)(MatCoarsen)) 0;
311:   coarser->ops->view    = (PetscErrorCode (*)(MatCoarsen,PetscViewer)) 0;

313:   (*r)(coarser);

315:   PetscFree(((PetscObject)coarser)->type_name);
316:   PetscStrallocpy(type,&((PetscObject)coarser)->type_name);
317:   return(0);
318: }

320: /*@C
321:    MatCoarsenSetGreedyOrdering - Sets the ordering of the vertices to use with a greedy coarsening method

323:    Logically Collective on Coarsen

325:    Input Parameters:
326: +  coarser - the coarsen context
327: -  perm - vertex ordering of (greedy) algorithm

329:    Level: advanced

331:    Notes:
332:       The IS weights is freed by PETSc, so user has given this to us

334: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
335: @*/
336: PetscErrorCode MatCoarsenSetGreedyOrdering(MatCoarsen coarser, const IS perm)
337: {
340:   coarser->perm = perm;
341:   return(0);
342: }

344: /*@C
345:    MatCoarsenGetData - Gets the weights for vertices for a coarsen.

347:    Logically Collective on Coarsen

349:    Input Parameter:
350: .  coarser - the coarsen context

352:    Output Parameter:
353: .  llist - linked list of aggregates

355:    Level: advanced

357: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
358: @*/
359: PetscErrorCode MatCoarsenGetData(MatCoarsen coarser, PetscCoarsenData **llist)
360: {
363:   if (!coarser->agg_lists) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"No linked list - generate it or call ApplyCoarsen");
364:   *llist             = coarser->agg_lists;
365:   coarser->agg_lists = 0; /* giving up ownership */
366:   return(0);
367: }

369: /*@
370:    MatCoarsenSetFromOptions - Sets various coarsen options from the
371:         options database.

373:    Collective on MatCoarsen

375:    Input Parameter:
376: .  coarser - the coarsen context.

378:    Options Database Command:
379: $  -mat_coarsen_type  <type>
380: $      Use -help for a list of available methods
381: $      (for instance, mis)

383:    Level: advanced

385: @*/
386: PetscErrorCode MatCoarsenSetFromOptions(MatCoarsen coarser)
387: {
389:   PetscBool      flag;
390:   char           type[256];
391:   const char     *def;

394:   PetscObjectOptionsBegin((PetscObject)coarser);
395:   if (!((PetscObject)coarser)->type_name) {
396:     def = MATCOARSENMIS;
397:   } else {
398:     def = ((PetscObject)coarser)->type_name;
399:   }

401:   PetscOptionsFList("-mat_coarsen_type","Type of aggregator","MatCoarsenSetType",MatCoarsenList,def,type,256,&flag);
402:   if (flag) {
403:     MatCoarsenSetType(coarser,type);
404:   }
405:   /*
406:    Set the type if it was never set.
407:    */
408:   if (!((PetscObject)coarser)->type_name) {
409:     MatCoarsenSetType(coarser,def);
410:   }

412:   if (coarser->ops->setfromoptions) {
413:     (*coarser->ops->setfromoptions)(PetscOptionsObject,coarser);
414:   }
415:   PetscOptionsEnd();
416:   MatCoarsenViewFromOptions(coarser,NULL,"-mat_coarsen_view");
417:   return(0);
418: }