Actual source code: coarsen.c

petsc-3.7.3 2016-08-01
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 coarser to the  matrix package.

 15:    Logically 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 - coarsener 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 MatCoarsen

 82:    Input Parameter:
 83: .   coarsen - the coarsen

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

 92:    Level: beginner

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

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

 98: .keywords: matrix, get, coarsen

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

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

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

126:    Collective on MatCoarsen and Mat

128:    Input Parameters:
129: +  agg - the coarsen context
130: -  adj - the adjacency matrix

132:    Level: beginner

134: .keywords: Coarsen, adjacency

136: .seealso: MatCoarsenCreate()
137: @*/
138: PetscErrorCode  MatCoarsenSetAdjacency(MatCoarsen agg, Mat adj)
139: {
143:   agg->graph = adj;
144:   return(0);
145: }

149: /*@
150:    MatCoarsenSetStrictAggs -

152:    Logically Collective on MatCoarsen

154:    Input Parameters:
155: +  agg - the coarsen context
156: -  str - the adjacency matrix

158:    Level: beginner

160: .keywords: Coarsen, adjacency

162: .seealso: MatCoarsenCreate()
163: @*/
164: PetscErrorCode MatCoarsenSetStrictAggs(MatCoarsen agg, PetscBool str)
165: {
168:   agg->strict_aggs = str;
169:   return(0);
170: }

174: /*@
175:    MatCoarsenDestroy - Destroys the coarsen context.

177:    Collective on MatCoarsen

179:    Input Parameters:
180: .  agg - the coarsen context

182:    Level: beginner

184: .keywords: Coarsen, destroy, context

186: .seealso: MatCoarsenCreate()
187: @*/
188: PetscErrorCode  MatCoarsenDestroy(MatCoarsen *agg)
189: {

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

197:   if ((*agg)->ops->destroy) {
198:     (*(*agg)->ops->destroy)((*agg));
199:   }

201:   if ((*agg)->agg_lists) {
202:     PetscCDDestroy((*agg)->agg_lists);
203:   }

205:   PetscHeaderDestroy(agg);
206:   return(0);
207: }

211: /*@
212:    MatCoarsenCreate - Creates a coarsen context.

214:    Collective on MPI_Comm

216:    Input Parameter:
217: .   comm - MPI communicator

219:    Output Parameter:
220: .  newcrs - location to put the context

222:    Level: beginner

224: .keywords: Coarsen, create, context

226: .seealso: MatCoarsenSetType(), MatCoarsenApply(), MatCoarsenDestroy(),
227:           MatCoarsenSetAdjacency()

229: @*/
230: PetscErrorCode  MatCoarsenCreate(MPI_Comm comm, MatCoarsen *newcrs)
231: {
232:   MatCoarsen     agg;

236:   *newcrs = 0;

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

241:   *newcrs = agg;
242:   return(0);
243: }

247: /*@C
248:    MatCoarsenView - Prints the coarsen data structure.

250:    Collective on MatCoarsen

252:    Input Parameters:
253: .  agg - the coarsen context
254: .  viewer - optional visualization context

256:    Level: intermediate

258:    Note:
259:    The available visualization contexts include
260: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
261: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
262:          output where only the first processor opens
263:          the file.  All other processors send their
264:          data to the first processor to print.

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

269: .keywords: Coarsen, view

271: .seealso: PetscViewerASCIIOpen()
272: @*/
273: PetscErrorCode  MatCoarsenView(MatCoarsen agg,PetscViewer viewer)
274: {
276:   PetscBool      iascii;

280:   if (!viewer) {
281:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)agg),&viewer);
282:   }

286:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
287:   PetscObjectPrintClassNamePrefixType((PetscObject)agg,viewer);
288:   if (agg->ops->view) {
289:     PetscViewerASCIIPushTab(viewer);
290:     (*agg->ops->view)(agg,viewer);
291:     PetscViewerASCIIPopTab(viewer);
292:   }
293:   return(0);
294: }

298: /*@C
299:    MatCoarsenSetType - Sets the type of aggregator to use

301:    Collective on MatCoarsen

303:    Input Parameter:
304: +  coarser - the coarsen context.
305: -  type - a known coarsening method

307:    Options Database Command:
308: $  -mat_coarsen_type  <type>
309: $      Use -help for a list of available methods
310: $      (for instance, mis)

312:    Level: intermediate

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

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

318: @*/
319: PetscErrorCode  MatCoarsenSetType(MatCoarsen coarser, MatCoarsenType type)
320: {
321:   PetscErrorCode ierr,(*r)(MatCoarsen);
322:   PetscBool      match;


328:   PetscObjectTypeCompare((PetscObject)coarser,type,&match);
329:   if (match) return(0);

331:   if (coarser->setupcalled) {
332:      (*coarser->ops->destroy)(coarser);

334:     coarser->ops->destroy = NULL;
335:     coarser->subctx       = 0;
336:     coarser->setupcalled  = 0;
337:   }

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

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

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

346:   (*r)(coarser);

348:   PetscFree(((PetscObject)coarser)->type_name);
349:   PetscStrallocpy(type,&((PetscObject)coarser)->type_name);
350:   return(0);
351: }

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

358:    Logically Collective on Coarsen

360:    Input Parameters:
361: +  coarser - the coarsen context
362: -  perm - vertex ordering of (greedy) algorithm

364:    Level: beginner

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

369: .keywords: Coarsen

371: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
372: @*/
373: PetscErrorCode MatCoarsenSetGreedyOrdering(MatCoarsen coarser, const IS perm)
374: {
377:   coarser->perm = perm;
378:   return(0);
379: }

383: /*@C
384:    MatCoarsenGetData - Gets the weights for vertices for a coarsen.

386:    Logically Collective on Coarsen

388:    Input Parameter:
389: .  coarser - the coarsen context

391:    Output Parameter:
392: .  llist - linked list of aggregates

394:    Level: advanced

396: .keywords: Coarsen

398: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
399: @*/
400: PetscErrorCode MatCoarsenGetData(MatCoarsen coarser, PetscCoarsenData **llist)
401: {
404:   if (!coarser->agg_lists) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"No linked list - generate it or call ApplyCoarsen");
405:   *llist             = coarser->agg_lists;
406:   coarser->agg_lists = 0; /* giving up ownership */
407:   return(0);
408: }

412: /*@
413:    MatCoarsenSetFromOptions - Sets various coarsen options from the
414:         options database.

416:    Collective on MatCoarsen

418:    Input Parameter:
419: .  coarser - the coarsen context.

421:    Options Database Command:
422: $  -mat_coarsen_type  <type>
423: $      Use -help for a list of available methods
424: $      (for instance, mis)

426:    Level: beginner

428: .keywords: coarsen, set, method, type
429: @*/
430: PetscErrorCode MatCoarsenSetFromOptions(MatCoarsen coarser)
431: {
433:   PetscBool      flag;
434:   char           type[256];
435:   const char     *def;

438:   PetscObjectOptionsBegin((PetscObject)coarser);
439:   if (!((PetscObject)coarser)->type_name) {
440:     def = MATCOARSENMIS;
441:   } else {
442:     def = ((PetscObject)coarser)->type_name;
443:   }

445:   PetscOptionsFList("-mat_coarsen_type","Type of aggregator","MatCoarsenSetType",MatCoarsenList,def,type,256,&flag);
446:   if (flag) {
447:     MatCoarsenSetType(coarser,type);
448:   }
449:   /*
450:    Set the type if it was never set.
451:    */
452:   if (!((PetscObject)coarser)->type_name) {
453:     MatCoarsenSetType(coarser,def);
454:   }

456:   if (coarser->ops->setfromoptions) {
457:     (*coarser->ops->setfromoptions)(PetscOptionsObject,coarser);
458:   }
459:   PetscOptionsEnd();
460:   MatCoarsenViewFromOptions(coarser,NULL,"-mat_coarsen_view");
461:   return(0);
462: }