Actual source code: coarsen.c

petsc-master 2018-06-22
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:
 91:     Use MatCoarsenGetData() to access the results of the coarsening

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

 95: .keywords: matrix, get, coarsen

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

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

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

120:    Collective on MatCoarsen and Mat

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

126:    Level: advanced

128: .keywords: Coarsen, adjacency

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

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

144:    Logically Collective on MatCoarsen

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

150:    Level: advanced

152: .keywords: Coarsen, adjacency

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

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

167:    Collective on MatCoarsen

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

172:    Level: advanced

174: .keywords: Coarsen, destroy, context

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

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

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

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

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

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

202:    Collective on MPI_Comm

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

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

210:    Level: advanced

212: .keywords: Coarsen, create, context

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

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

224:   *newcrs = 0;

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

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

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

236:    Collective on MatCoarsen

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

242:    Level: advanced

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

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

255: .keywords: Coarsen, view

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

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

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

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

285:    Collective on MatCoarsen

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

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

296:    Level: advanced

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

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

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


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

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

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

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

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

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

330:   (*r)(coarser);

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

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

340:    Logically Collective on Coarsen

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

346:    Level: advanced

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

351: .keywords: Coarsen

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

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

366:    Logically Collective on Coarsen

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

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

374:    Level: advanced

376: .keywords: Coarsen

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

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

394:    Collective on MatCoarsen

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

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

404:    Level: advanced

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

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

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

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