Actual source code: coarsen.c

petsc-dev 2014-02-02
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:   if (iascii) {
316:     PetscObjectPrintClassNamePrefixType((PetscObject)agg,viewer);
317:   } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_SUP,"Viewer type %s not supported for this MatCoarsen",((PetscObject)viewer)->type_name);

319:   if (agg->ops->view) {
320:     PetscViewerASCIIPushTab(viewer);
321:     (*agg->ops->view)(agg,viewer);
322:     PetscViewerASCIIPopTab(viewer);
323:   }
324:   return(0);
325: }

329: /*@C
330:    MatCoarsenSetType - Sets the type of aggregator to use

332:    Collective on MatCoarsen

334:    Input Parameter:
335: .  coarser - the coarsen context.
336: .  type - a known method

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

343:    Level: intermediate

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

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

349: @*/
350: PetscErrorCode  MatCoarsenSetType(MatCoarsen coarser, MatCoarsenType type)
351: {
352:   PetscErrorCode ierr,(*r)(MatCoarsen);
353:   PetscBool      match;


359:   PetscObjectTypeCompare((PetscObject)coarser,type,&match);
360:   if (match) return(0);

362:   if (coarser->setupcalled) {
363:      (*coarser->ops->destroy)(coarser);

365:     coarser->ops->destroy = NULL;
366:     coarser->subctx       = 0;
367:     coarser->setupcalled  = 0;
368:   }

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

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

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

377:   (*r)(coarser);

379:   PetscFree(((PetscObject)coarser)->type_name);
380:   PetscStrallocpy(type,&((PetscObject)coarser)->type_name);
381:   return(0);
382: }

386: /*@C
387:    MatCoarsenSetGreedyOrdering - Sets the weights for vertices for a coarsen.

389:    Logically Collective on Coarsen

391:    Input Parameters:
392: +  coarser - the coarsen context
393: -  perm - vertex ordering of (greedy) algorithm

395:    Level: beginner

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

400: .keywords: Coarsen

402: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
403: @*/
404: PetscErrorCode MatCoarsenSetGreedyOrdering(MatCoarsen coarser, const IS perm)
405: {
408:   coarser->perm = perm;
409:   return(0);
410: }

414: /*@C
415:    MatCoarsenGetData - Sets the weights for vertices for a coarsen.

417:    Logically Collective on Coarsen

419:    Input Parameters:
420: +  coarser - the coarsen context
421: -  mis - pointer into 'llist'
422: -  llist - linked list of aggregates

424:    Level: beginner

426:    Notes:

428: .keywords: Coarsen

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

444: /*@
445:    MatCoarsenSetFromOptions - Sets various coarsen options from the
446:         options database.

448:    Collective on MatCoarsen

450:    Input Parameter:
451: .  coarser - the coarsen context.

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

458:    Level: beginner

460: .keywords: coarsen, set, method, type
461: @*/
462: PetscErrorCode MatCoarsenSetFromOptions(MatCoarsen coarser)
463: {
465:   PetscBool      flag;
466:   char           type[256];
467:   const char     *def;

470:   PetscObjectOptionsBegin((PetscObject)coarser);
471:   if (!((PetscObject)coarser)->type_name) {
472:     def = MATCOARSENMIS;
473:   } else {
474:     def = ((PetscObject)coarser)->type_name;
475:   }

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

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