Actual source code: coarsen.c

petsc-3.5.2 2014-09-08
Report Typos and Errors
  2: #include <petsc-private/matimpl.h>               /*I "petscmat.h" I*/

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

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

 12: /*@C
 13:    MatCoarsenRegister - Adds a new sparse matrix coarsen to the  matrix package.

 15:    Not Collective

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

 21:    Level: developer

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

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

 33: .keywords: matrix, coarsen, register

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

 42:   PetscFunctionListAdd(&MatCoarsenList,sname,function);
 43:   return(0);
 44: }

 48: /*@C
 49:    MatCoarsenGetType - Gets the Coarsen method type and name (as a string)
 50:         from the coarsen context.

 52:    Not collective

 54:    Input Parameter:
 55: .  coarsen - the coarsen context

 57:    Output Parameter:
 58: .  type - aggregator type

 60:    Level: intermediate

 62:    Not Collective

 64: .keywords: Coarsen, get, method, name, type
 65: @*/
 66: PetscErrorCode  MatCoarsenGetType(MatCoarsen coarsen,MatCoarsenType *type)
 67: {
 71:   *type = ((PetscObject)coarsen)->type_name;
 72:   return(0);
 73: }

 77: /*@
 78:    MatCoarsenApply - Gets a coarsen for a matrix.

 80:    Collective on Mat

 82:    Input Parameters:
 83: .  matp - the matrix coarsen object

 85:    Output Parameters:
 86: .   coarsen - the coarsen. For each local node this tells the aggregate
 87:                    number that that node is assigned to.

 89:    Options Database Keys:
 90:    To specify the coarsen through the options database, use one of
 91:    the following
 92: $    -mat_coarsen_type mis
 93:    To see the coarsen result
 94: $    -mat_coarsen_view

 96:    Level: beginner

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

100: .keywords: matrix, get, coarsen

102: .seealso:  MatCoarsenRegister(), MatCoarsenCreate(),
103:            MatCoarsenDestroy(), MatCoarsenSetAdjacency(), ISCoarsenToNumbering(),
104:            ISCoarsenCount()
105: @*/
106: PetscErrorCode  MatCoarsenApply(MatCoarsen coarser)
107: {

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

124: /*@
125:    MatCoarsenSetAdjacency - Sets the adjacency graph (matrix) of the thing to be
126:       partitioned.

128:    Collective on MatCoarsen and Mat

130:    Input Parameters:
131: +  agg - the coarsen context
132: -  adj - the adjacency matrix

134:    Level: beginner

136: .keywords: Coarsen, adjacency

138: .seealso: MatCoarsenCreate()
139: @*/
140: PetscErrorCode  MatCoarsenSetAdjacency(MatCoarsen agg, Mat adj)
141: {
145:   agg->graph = adj;
146:   return(0);
147: }

151: /*@
152:    MatCoarsenSetStrictAggs -

154:    Not Collective on MatCoarsen and Mat

156:    Input Parameters:
157: +  agg - the coarsen context
158: -  str - the adjacency matrix

160:    Level: beginner

162: .keywords: Coarsen, adjacency

164: .seealso: MatCoarsenCreate()
165: @*/
166: PetscErrorCode MatCoarsenSetStrictAggs(MatCoarsen agg, PetscBool str)
167: {
170:   agg->strict_aggs = str;
171:   return(0);
172: }

176: /*@
177:    MatCoarsenSetVerbose -

179:    Not Collective on MatCoarsen and Mat

181:    Input Parameters:
182: +  agg - the coarsen context
183: -  str - the adjacency matrix

185:    Level: beginner

187: .keywords: Coarsen, adjacency

189: .seealso: MatCoarsenCreate()
190: @*/
191: PetscErrorCode MatCoarsenSetVerbose(MatCoarsen agg, PetscInt vv)
192: {
195:   agg->verbose = vv;
196:   return(0);
197: }

201: /*@
202:    MatCoarsenDestroy - Destroys the coarsen context.

204:    Collective on Coarsen

206:    Input Parameters:
207: .  agg - the coarsen context

209:    Level: beginner

211: .keywords: Coarsen, destroy, context

213: .seealso: MatCoarsenCreate()
214: @*/
215: PetscErrorCode  MatCoarsenDestroy(MatCoarsen *agg)
216: {

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

224:   if ((*agg)->ops->destroy) {
225:     (*(*agg)->ops->destroy)((*agg));
226:   }

228:   if ((*agg)->agg_lists) {
229:     PetscCDDestroy((*agg)->agg_lists);
230:   }

232:   PetscHeaderDestroy(agg);
233:   return(0);
234: }

238: /*@
239:    MatCoarsenCreate - Creates a coarsen context.

241:    Collective on MPI_Comm

243:    Input Parameter:
244: .   comm - MPI communicator

246:    Output Parameter:
247: .  newcrs - location to put the context

249:    Level: beginner

251: .keywords: Coarsen, create, context

253: .seealso: MatCoarsenSetType(), MatCoarsenApply(), MatCoarsenDestroy(),
254:           MatCoarsenSetAdjacency()

256: @*/
257: PetscErrorCode  MatCoarsenCreate(MPI_Comm comm, MatCoarsen *newcrs)
258: {
259:   MatCoarsen     agg;

263:   *newcrs = 0;

265:   MatInitializePackage();
266:   PetscHeaderCreate(agg, _p_MatCoarsen, struct _MatCoarsenOps, MAT_COARSEN_CLASSID,"MatCoarsen","Matrix/graph coarsen",
267:                            "MatCoarsen", comm, MatCoarsenDestroy, MatCoarsenView);

269:   *newcrs = agg;
270:   return(0);
271: }

275: /*@C
276:    MatCoarsenView - Prints the coarsen data structure.

278:    Collective on MatCoarsen

280:    Input Parameters:
281: .  agg - the coarsen context
282: .  viewer - optional visualization context

284:    Level: intermediate

286:    Note:
287:    The available visualization contexts include
288: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
289: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
290:          output where only the first processor opens
291:          the file.  All other processors send their
292:          data to the first processor to print.

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

297: .keywords: Coarsen, view

299: .seealso: PetscViewerASCIIOpen()
300: @*/
301: PetscErrorCode  MatCoarsenView(MatCoarsen agg,PetscViewer viewer)
302: {
304:   PetscBool      iascii;

308:   if (!viewer) {
309:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)agg),&viewer);
310:   }

314:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
315:   PetscObjectPrintClassNamePrefixType((PetscObject)agg,viewer);
316:   if (agg->ops->view) {
317:     PetscViewerASCIIPushTab(viewer);
318:     (*agg->ops->view)(agg,viewer);
319:     PetscViewerASCIIPopTab(viewer);
320:   }
321:   return(0);
322: }

326: /*@C
327:    MatCoarsenSetType - Sets the type of aggregator to use

329:    Collective on MatCoarsen

331:    Input Parameter:
332: .  coarser - the coarsen context.
333: .  type - a known method

335:    Options Database Command:
336: $  -mat_coarsen_type  <type>
337: $      Use -help for a list of available methods
338: $      (for instance, mis)

340:    Level: intermediate

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

344: .seealso: MatCoarsenCreate(), MatCoarsenApply(), MatCoarsenType

346: @*/
347: PetscErrorCode  MatCoarsenSetType(MatCoarsen coarser, MatCoarsenType type)
348: {
349:   PetscErrorCode ierr,(*r)(MatCoarsen);
350:   PetscBool      match;


356:   PetscObjectTypeCompare((PetscObject)coarser,type,&match);
357:   if (match) return(0);

359:   if (coarser->setupcalled) {
360:      (*coarser->ops->destroy)(coarser);

362:     coarser->ops->destroy = NULL;
363:     coarser->subctx       = 0;
364:     coarser->setupcalled  = 0;
365:   }

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

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

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

374:   (*r)(coarser);

376:   PetscFree(((PetscObject)coarser)->type_name);
377:   PetscStrallocpy(type,&((PetscObject)coarser)->type_name);
378:   return(0);
379: }

383: /*@C
384:    MatCoarsenSetGreedyOrdering - Sets the weights for vertices for a coarsen.

386:    Logically Collective on Coarsen

388:    Input Parameters:
389: +  coarser - the coarsen context
390: -  perm - vertex ordering of (greedy) algorithm

392:    Level: beginner

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

397: .keywords: Coarsen

399: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
400: @*/
401: PetscErrorCode MatCoarsenSetGreedyOrdering(MatCoarsen coarser, const IS perm)
402: {
405:   coarser->perm = perm;
406:   return(0);
407: }

411: /*@C
412:    MatCoarsenGetData - Sets the weights for vertices for a coarsen.

414:    Logically Collective on Coarsen

416:    Input Parameters:
417: +  coarser - the coarsen context
418: -  mis - pointer into 'llist'
419: -  llist - linked list of aggregates

421:    Level: beginner

423:    Notes:

425: .keywords: Coarsen

427: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
428: @*/
429: PetscErrorCode MatCoarsenGetData(MatCoarsen coarser, PetscCoarsenData **llist)
430: {
433:   if (!coarser->agg_lists) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"No linked list - generate it or call ApplyCoarsen");
434:   *llist             = coarser->agg_lists;
435:   coarser->agg_lists = 0; /* giving up ownership */
436:   return(0);
437: }

441: /*@
442:    MatCoarsenSetFromOptions - Sets various coarsen options from the
443:         options database.

445:    Collective on MatCoarsen

447:    Input Parameter:
448: .  coarser - the coarsen context.

450:    Options Database Command:
451: $  -mat_coarsen_type  <type>
452: $      Use -help for a list of available methods
453: $      (for instance, mis)

455:    Level: beginner

457: .keywords: coarsen, set, method, type
458: @*/
459: PetscErrorCode MatCoarsenSetFromOptions(MatCoarsen coarser)
460: {
462:   PetscBool      flag;
463:   char           type[256];
464:   const char     *def;

467:   PetscObjectOptionsBegin((PetscObject)coarser);
468:   if (!((PetscObject)coarser)->type_name) {
469:     def = MATCOARSENMIS;
470:   } else {
471:     def = ((PetscObject)coarser)->type_name;
472:   }

474:   PetscOptionsFList("-mat_coarsen_type","Type of aggregator","MatCoarsenSetType",MatCoarsenList,def,type,256,&flag);
475:   if (flag) {
476:     MatCoarsenSetType(coarser,type);
477:   }
478:   /*
479:    Set the type if it was never set.
480:    */
481:   if (!((PetscObject)coarser)->type_name) {
482:     MatCoarsenSetType(coarser,def);
483:   }

485:   if (coarser->ops->setfromoptions) {
486:     (*coarser->ops->setfromoptions)(coarser);
487:   }
488:   PetscOptionsEnd();
489:   MatCoarsenViewFromOptions(coarser,NULL,"-mat_coarsen_view");
490:   return(0);
491: }