Actual source code: coarsen.c

petsc-3.9.3 2018-07-02
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 coarser 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:   PetscFunctionListAdd(&MatCoarsenList,sname,function);
 41:   return(0);
 42: }

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

 48:    Not collective

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

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

 56:    Level: advanced

 58:    Not Collective

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

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

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

 76:    Collective on MatCoarsen

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

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

 88:    Level: advanced

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

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

 94: .keywords: matrix, get, coarsen

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

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

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

119:    Collective on MatCoarsen and Mat

121:    Input Parameters:
122: +  agg - the coarsen context
123: -  adj - the adjacency matrix

125:    Level: advanced

127: .keywords: Coarsen, adjacency

129: .seealso: MatCoarsenCreate(), MatCoarsenApply()
130: @*/
131: PetscErrorCode  MatCoarsenSetAdjacency(MatCoarsen agg, Mat adj)
132: {
136:   agg->graph = adj;
137:   return(0);
138: }

140: /*@
141:    MatCoarsenSetStrictAggs - WHAT IS THIS?

143:    Logically Collective on MatCoarsen

145:    Input Parameters:
146: +  agg - the coarsen context
147: -  str - the adjacency matrix

149:    Level: advanced

151: .keywords: Coarsen, adjacency

153: .seealso: MatCoarsenCreate()
154: @*/
155: PetscErrorCode MatCoarsenSetStrictAggs(MatCoarsen agg, PetscBool str)
156: {
159:   agg->strict_aggs = str;
160:   return(0);
161: }

163: /*@
164:    MatCoarsenDestroy - Destroys the coarsen context.

166:    Collective on MatCoarsen

168:    Input Parameters:
169: .  agg - the coarsen context

171:    Level: advanced

173: .keywords: Coarsen, destroy, context

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

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

186:   if ((*agg)->ops->destroy) {
187:     (*(*agg)->ops->destroy)((*agg));
188:   }

190:   if ((*agg)->agg_lists) {
191:     PetscCDDestroy((*agg)->agg_lists);
192:   }

194:   PetscHeaderDestroy(agg);
195:   return(0);
196: }

198: /*@
199:    MatCoarsenCreate - Creates a coarsen context.

201:    Collective on MPI_Comm

203:    Input Parameter:
204: .   comm - MPI communicator

206:    Output Parameter:
207: .  newcrs - location to put the context

209:    Level: advanced

211: .keywords: Coarsen, create, context

213: .seealso: MatCoarsenSetType(), MatCoarsenApply(), MatCoarsenDestroy(),
214:           MatCoarsenSetAdjacency(), MatCoarsenGetData()

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

223:   *newcrs = 0;

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

228:   *newcrs = agg;
229:   return(0);
230: }

232: /*@C
233:    MatCoarsenView - Prints the coarsen data structure.

235:    Collective on MatCoarsen

237:    Input Parameters:
238: .  agg - the coarsen context
239: .  viewer - optional visualization context

241:    Level: advanced

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

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

254: .keywords: Coarsen, view

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

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

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

281: /*@C
282:    MatCoarsenSetType - Sets the type of aggregator to use

284:    Collective on MatCoarsen

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

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

295:    Level: advanced

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

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

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


311:   PetscObjectTypeCompare((PetscObject)coarser,type,&match);
312:   if (match) return(0);

314:   if (coarser->setupcalled) {
315:      (*coarser->ops->destroy)(coarser);

317:     coarser->ops->destroy = NULL;
318:     coarser->subctx       = 0;
319:     coarser->setupcalled  = 0;
320:   }

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

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

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

329:   (*r)(coarser);

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

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

339:    Logically Collective on Coarsen

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

345:    Level: advanced

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

350: .keywords: Coarsen

352: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
353: @*/
354: PetscErrorCode MatCoarsenSetGreedyOrdering(MatCoarsen coarser, const IS perm)
355: {
358:   coarser->perm = perm;
359:   return(0);
360: }

362: /*@C
363:    MatCoarsenGetData - Gets the weights for vertices for a coarsen.

365:    Logically Collective on Coarsen

367:    Input Parameter:
368: .  coarser - the coarsen context

370:    Output Parameter:
371: .  llist - linked list of aggregates

373:    Level: advanced

375: .keywords: Coarsen

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

389: /*@
390:    MatCoarsenSetFromOptions - Sets various coarsen options from the
391:         options database.

393:    Collective on MatCoarsen

395:    Input Parameter:
396: .  coarser - the coarsen context.

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

403:    Level: advanced

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

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

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

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