Actual source code: coarsen.c

petsc-3.11.4 2019-09-28
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: .keywords: matrix, coarsen, register

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

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

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

 49:    Not collective

 51:    Input Parameter:
 52: .  coarsen - the coarsen context

 54:    Output Parameter:
 55: .  type - coarsener type

 57:    Level: advanced

 59:    Not Collective

 61: .keywords: Coarsen, get, method, name, type

 63: .seealso: MatCoarsenCreate(), MatCoarsenType, MatCoarsenSetType()
 64: @*/
 65: PetscErrorCode  MatCoarsenGetType(MatCoarsen coarsen,MatCoarsenType *type)
 66: {
 70:   *type = ((PetscObject)coarsen)->type_name;
 71:   return(0);
 72: }

 74: /*@
 75:    MatCoarsenApply - Gets a coarsen for a matrix.

 77:    Collective on MatCoarsen

 79:    Input Parameter:
 80: .   coarsen - the coarsen

 82:    Options Database Keys:
 83:    To specify the coarsen through the options database, use one of
 84:    the following
 85: $    -mat_coarsen_type mis
 86:    To see the coarsen result
 87: $    -mat_coarsen_view

 89:    Level: advanced

 91:    Notes:
 92:     Use MatCoarsenGetData() to access the results of the coarsening

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

 96: .keywords: matrix, get, coarsen

 98: .seealso:  MatCoarsenRegister(), MatCoarsenCreate(),
 99:            MatCoarsenDestroy(), MatCoarsenSetAdjacency(), ISCoarsenToNumbering(),
100:            ISCoarsenCount(), MatCoarsenGetData()
101: @*/
102: PetscErrorCode  MatCoarsenApply(MatCoarsen coarser)
103: {

109:   if (!coarser->graph->assembled) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"Not for unassembled matrix");
110:   if (coarser->graph->factortype) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"Not for factored matrix");
111:   if (!coarser->ops->apply) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"Must set type with MatCoarsenSetFromOptions() or MatCoarsenSetType()");
112:   PetscLogEventBegin(MAT_Coarsen,coarser,0,0,0);
113:   (*coarser->ops->apply)(coarser);
114:   PetscLogEventEnd(MAT_Coarsen,coarser,0,0,0);
115:   return(0);
116: }

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

121:    Collective on MatCoarsen and Mat

123:    Input Parameters:
124: +  agg - the coarsen context
125: -  adj - the adjacency matrix

127:    Level: advanced

129: .keywords: Coarsen, adjacency

131: .seealso: MatCoarsenCreate(), MatCoarsenApply()
132: @*/
133: PetscErrorCode  MatCoarsenSetAdjacency(MatCoarsen agg, Mat adj)
134: {
138:   agg->graph = adj;
139:   return(0);
140: }

142: /*@
143:    MatCoarsenSetStrictAggs - WHAT IS THIS?

145:    Logically Collective on MatCoarsen

147:    Input Parameters:
148: +  agg - the coarsen context
149: -  str - the adjacency matrix

151:    Level: advanced

153: .keywords: Coarsen, adjacency

155: .seealso: MatCoarsenCreate()
156: @*/
157: PetscErrorCode MatCoarsenSetStrictAggs(MatCoarsen agg, PetscBool str)
158: {
161:   agg->strict_aggs = str;
162:   return(0);
163: }

165: /*@
166:    MatCoarsenDestroy - Destroys the coarsen context.

168:    Collective on MatCoarsen

170:    Input Parameters:
171: .  agg - the coarsen context

173:    Level: advanced

175: .keywords: Coarsen, destroy, context

177: .seealso: MatCoarsenCreate()
178: @*/
179: PetscErrorCode  MatCoarsenDestroy(MatCoarsen *agg)
180: {

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

188:   if ((*agg)->ops->destroy) {
189:     (*(*agg)->ops->destroy)((*agg));
190:   }

192:   if ((*agg)->agg_lists) {
193:     PetscCDDestroy((*agg)->agg_lists);
194:   }

196:   PetscHeaderDestroy(agg);
197:   return(0);
198: }

200: /*@
201:    MatCoarsenCreate - Creates a coarsen context.

203:    Collective on MPI_Comm

205:    Input Parameter:
206: .   comm - MPI communicator

208:    Output Parameter:
209: .  newcrs - location to put the context

211:    Level: advanced

213: .keywords: Coarsen, create, context

215: .seealso: MatCoarsenSetType(), MatCoarsenApply(), MatCoarsenDestroy(),
216:           MatCoarsenSetAdjacency(), MatCoarsenGetData()

218: @*/
219: PetscErrorCode  MatCoarsenCreate(MPI_Comm comm, MatCoarsen *newcrs)
220: {
221:   MatCoarsen     agg;

225:   *newcrs = 0;

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

230:   *newcrs = agg;
231:   return(0);
232: }

234: /*@C
235:    MatCoarsenView - Prints the coarsen data structure.

237:    Collective on MatCoarsen

239:    Input Parameters:
240: .  agg - the coarsen context
241: .  viewer - optional visualization context

243:    Level: advanced

245:    Note:
246:    The available visualization contexts include
247: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
248: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
249:          output where only the first processor opens
250:          the file.  All other processors send their
251:          data to the first processor to print.

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

256: .keywords: Coarsen, view

258: .seealso: PetscViewerASCIIOpen()
259: @*/
260: PetscErrorCode  MatCoarsenView(MatCoarsen agg,PetscViewer viewer)
261: {
263:   PetscBool      iascii;

267:   if (!viewer) {
268:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)agg),&viewer);
269:   }

273:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
274:   PetscObjectPrintClassNamePrefixType((PetscObject)agg,viewer);
275:   if (agg->ops->view) {
276:     PetscViewerASCIIPushTab(viewer);
277:     (*agg->ops->view)(agg,viewer);
278:     PetscViewerASCIIPopTab(viewer);
279:   }
280:   return(0);
281: }

283: /*@C
284:    MatCoarsenSetType - Sets the type of aggregator to use

286:    Collective on MatCoarsen

288:    Input Parameter:
289: +  coarser - the coarsen context.
290: -  type - a known coarsening method

292:    Options Database Command:
293: $  -mat_coarsen_type  <type>
294: $      Use -help for a list of available methods
295: $      (for instance, mis)

297:    Level: advanced

299: .keywords: coarsen, set, method, type

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

303: @*/
304: PetscErrorCode  MatCoarsenSetType(MatCoarsen coarser, MatCoarsenType type)
305: {
306:   PetscErrorCode ierr,(*r)(MatCoarsen);
307:   PetscBool      match;


313:   PetscObjectTypeCompare((PetscObject)coarser,type,&match);
314:   if (match) return(0);

316:   if (coarser->setupcalled) {
317:      (*coarser->ops->destroy)(coarser);

319:     coarser->ops->destroy = NULL;
320:     coarser->subctx       = 0;
321:     coarser->setupcalled  = 0;
322:   }

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

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

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

331:   (*r)(coarser);

333:   PetscFree(((PetscObject)coarser)->type_name);
334:   PetscStrallocpy(type,&((PetscObject)coarser)->type_name);
335:   return(0);
336: }

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

341:    Logically Collective on Coarsen

343:    Input Parameters:
344: +  coarser - the coarsen context
345: -  perm - vertex ordering of (greedy) algorithm

347:    Level: advanced

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

352: .keywords: Coarsen

354: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
355: @*/
356: PetscErrorCode MatCoarsenSetGreedyOrdering(MatCoarsen coarser, const IS perm)
357: {
360:   coarser->perm = perm;
361:   return(0);
362: }

364: /*@C
365:    MatCoarsenGetData - Gets the weights for vertices for a coarsen.

367:    Logically Collective on Coarsen

369:    Input Parameter:
370: .  coarser - the coarsen context

372:    Output Parameter:
373: .  llist - linked list of aggregates

375:    Level: advanced

377: .keywords: Coarsen

379: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
380: @*/
381: PetscErrorCode MatCoarsenGetData(MatCoarsen coarser, PetscCoarsenData **llist)
382: {
385:   if (!coarser->agg_lists) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"No linked list - generate it or call ApplyCoarsen");
386:   *llist             = coarser->agg_lists;
387:   coarser->agg_lists = 0; /* giving up ownership */
388:   return(0);
389: }

391: /*@
392:    MatCoarsenSetFromOptions - Sets various coarsen options from the
393:         options database.

395:    Collective on MatCoarsen

397:    Input Parameter:
398: .  coarser - the coarsen context.

400:    Options Database Command:
401: $  -mat_coarsen_type  <type>
402: $      Use -help for a list of available methods
403: $      (for instance, mis)

405:    Level: advanced

407: .keywords: coarsen, set, method, type
408: @*/
409: PetscErrorCode MatCoarsenSetFromOptions(MatCoarsen coarser)
410: {
412:   PetscBool      flag;
413:   char           type[256];
414:   const char     *def;

417:   PetscObjectOptionsBegin((PetscObject)coarser);
418:   if (!((PetscObject)coarser)->type_name) {
419:     def = MATCOARSENMIS;
420:   } else {
421:     def = ((PetscObject)coarser)->type_name;
422:   }

424:   PetscOptionsFList("-mat_coarsen_type","Type of aggregator","MatCoarsenSetType",MatCoarsenList,def,type,256,&flag);
425:   if (flag) {
426:     MatCoarsenSetType(coarser,type);
427:   }
428:   /*
429:    Set the type if it was never set.
430:    */
431:   if (!((PetscObject)coarser)->type_name) {
432:     MatCoarsenSetType(coarser,def);
433:   }

435:   if (coarser->ops->setfromoptions) {
436:     (*coarser->ops->setfromoptions)(PetscOptionsObject,coarser);
437:   }
438:   PetscOptionsEnd();
439:   MatCoarsenViewFromOptions(coarser,NULL,"-mat_coarsen_view");
440:   return(0);
441: }