Actual source code: coarsen.c


  2: #include <petsc/private/matimpl.h>

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

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

 10: /*@C
 11:    MatCoarsenRegister - Adds a new sparse matrix coarsening algorithm 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: .seealso: MatCoarsenRegisterDestroy(), MatCoarsenRegisterAll()
 32: @*/
 33: PetscErrorCode  MatCoarsenRegister(const char sname[],PetscErrorCode (*function)(MatCoarsen))
 34: {
 35:   MatInitializePackage();
 36:   PetscFunctionListAdd(&MatCoarsenList,sname,function);
 37:   return 0;
 38: }

 40: /*@C
 41:    MatCoarsenGetType - Gets the Coarsen method type and name (as a string)
 42:         from the coarsen context.

 44:    Not collective

 46:    Input Parameter:
 47: .  coarsen - the coarsen context

 49:    Output Parameter:
 50: .  type - coarsener type

 52:    Level: advanced

 54:    Not Collective

 56: .seealso: MatCoarsenCreate(), MatCoarsenType, MatCoarsenSetType()
 57: @*/
 58: PetscErrorCode  MatCoarsenGetType(MatCoarsen coarsen,MatCoarsenType *type)
 59: {
 62:   *type = ((PetscObject)coarsen)->type_name;
 63:   return 0;
 64: }

 66: /*@
 67:    MatCoarsenApply - Gets a coarsen for a matrix.

 69:    Collective on MatCoarsen

 71:    Input Parameter:
 72: .   coarsen - the coarsen

 74:    Options Database Keys:
 75:    To specify the coarsen through the options database, use one of
 76:    the following
 77: $    -mat_coarsen_type mis
 78:    To see the coarsen result
 79: $    -mat_coarsen_view

 81:    Level: advanced

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

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

 88: .seealso:  MatCoarsenRegister(), MatCoarsenCreate(),
 89:            MatCoarsenDestroy(), MatCoarsenSetAdjacency()
 90:            MatCoarsenGetData()
 91: @*/
 92: PetscErrorCode  MatCoarsenApply(MatCoarsen coarser)
 93: {
 99:   PetscLogEventBegin(MAT_Coarsen,coarser,0,0,0);
100:   (*coarser->ops->apply)(coarser);
101:   PetscLogEventEnd(MAT_Coarsen,coarser,0,0,0);
102:   return 0;
103: }

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

108:    Collective on MatCoarsen

110:    Input Parameters:
111: +  agg - the coarsen context
112: -  adj - the adjacency matrix

114:    Level: advanced

116: .seealso: MatCoarsenCreate(), MatCoarsenApply()
117: @*/
118: PetscErrorCode  MatCoarsenSetAdjacency(MatCoarsen agg, Mat adj)
119: {
122:   agg->graph = adj;
123:   return 0;
124: }

126: /*@
127:    MatCoarsenSetStrictAggs - Set whether to keep strict (non overlapping) aggregates in the linked list of aggregates for a coarsen context

129:    Logically Collective on MatCoarsen

131:    Input Parameters:
132: +  agg - the coarsen context
133: -  str - PETSC_TRUE keep strict aggregates, PETSC_FALSE allow overlap
134:    Level: advanced

136: .seealso: MatCoarsenCreate()
137: @*/
138: PetscErrorCode MatCoarsenSetStrictAggs(MatCoarsen agg, PetscBool str)
139: {
141:   agg->strict_aggs = str;
142:   return 0;
143: }

145: /*@
146:    MatCoarsenDestroy - Destroys the coarsen context.

148:    Collective on MatCoarsen

150:    Input Parameters:
151: .  agg - the coarsen context

153:    Level: advanced

155: .seealso: MatCoarsenCreate()
156: @*/
157: PetscErrorCode  MatCoarsenDestroy(MatCoarsen *agg)
158: {
159:   if (!*agg) return 0;
161:   if (--((PetscObject)(*agg))->refct > 0) {*agg = NULL; return 0;}

163:   if ((*agg)->ops->destroy) {
164:     (*(*agg)->ops->destroy)((*agg));
165:   }

167:   if ((*agg)->agg_lists) {
168:     PetscCDDestroy((*agg)->agg_lists);
169:   }

171:   PetscHeaderDestroy(agg);
172:   return 0;
173: }

175: /*@
176:    MatCoarsenCreate - Creates a coarsen context.

178:    Collective

180:    Input Parameter:
181: .   comm - MPI communicator

183:    Output Parameter:
184: .  newcrs - location to put the context

186:    Level: advanced

188: .seealso: MatCoarsenSetType(), MatCoarsenApply(), MatCoarsenDestroy(),
189:           MatCoarsenSetAdjacency(), MatCoarsenGetData()

191: @*/
192: PetscErrorCode  MatCoarsenCreate(MPI_Comm comm, MatCoarsen *newcrs)
193: {
194:   MatCoarsen     agg;

196:   *newcrs = NULL;

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

201:   *newcrs = agg;
202:   return 0;
203: }

205: /*@C
206:    MatCoarsenViewFromOptions - View from Options

208:    Collective on MatCoarsen

210:    Input Parameters:
211: +  A - the coarsen context
212: .  obj - Optional object
213: -  name - command line option

215:    Level: intermediate
216: .seealso:  MatCoarsen, MatCoarsenView, PetscObjectViewFromOptions(), MatCoarsenCreate()
217: @*/
218: PetscErrorCode  MatCoarsenViewFromOptions(MatCoarsen A,PetscObject obj,const char name[])
219: {
221:   PetscObjectViewFromOptions((PetscObject)A,obj,name);
222:   return 0;
223: }

225: /*@C
226:    MatCoarsenView - Prints the coarsen data structure.

228:    Collective on MatCoarsen

230:    Input Parameters:
231: +  agg - the coarsen context
232: -  viewer - optional visualization context

234:    Level: advanced

236:    Note:
237:    The available visualization contexts include
238: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
239: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
240:          output where only the first processor opens
241:          the file.  All other processors send their
242:          data to the first processor to print.

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

247: .seealso: PetscViewerASCIIOpen()
248: @*/
249: PetscErrorCode  MatCoarsenView(MatCoarsen agg,PetscViewer viewer)
250: {
251:   PetscBool      iascii;

254:   if (!viewer) {
255:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)agg),&viewer);
256:   }

260:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
261:   PetscObjectPrintClassNamePrefixType((PetscObject)agg,viewer);
262:   if (agg->ops->view) {
263:     PetscViewerASCIIPushTab(viewer);
264:     (*agg->ops->view)(agg,viewer);
265:     PetscViewerASCIIPopTab(viewer);
266:   }
267:   return 0;
268: }

270: /*@C
271:    MatCoarsenSetType - Sets the type of aggregator to use

273:    Collective on MatCoarsen

275:    Input Parameters:
276: +  coarser - the coarsen context.
277: -  type - a known coarsening method

279:    Options Database Command:
280: $  -mat_coarsen_type  <type>
281: $      Use -help for a list of available methods
282: $      (for instance, mis)

284:    Level: advanced

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

288: @*/
289: PetscErrorCode  MatCoarsenSetType(MatCoarsen coarser, MatCoarsenType type)
290: {
291:   PetscBool      match;
292:   PetscErrorCode (*r)(MatCoarsen);


297:   PetscObjectTypeCompare((PetscObject)coarser,type,&match);
298:   if (match) return 0;

300:   if (coarser->ops->destroy) {
301:     (*coarser->ops->destroy)(coarser);
302:     coarser->ops->destroy = NULL;
303:   }
304:   PetscMemzero(coarser->ops,sizeof(struct _MatCoarsenOps));

306:   PetscFunctionListFind(MatCoarsenList,type,&r);
308:   (*r)(coarser);

310:   PetscFree(((PetscObject)coarser)->type_name);
311:   PetscStrallocpy(type,&((PetscObject)coarser)->type_name);
312:   return 0;
313: }

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

318:    Logically Collective on Coarsen

320:    Input Parameters:
321: +  coarser - the coarsen context
322: -  perm - vertex ordering of (greedy) algorithm

324:    Level: advanced

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

329: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
330: @*/
331: PetscErrorCode MatCoarsenSetGreedyOrdering(MatCoarsen coarser, const IS perm)
332: {
334:   coarser->perm = perm;
335:   return 0;
336: }

338: /*@C
339:    MatCoarsenGetData - Gets the weights for vertices for a coarsen.

341:    Logically Collective on Coarsen

343:    Input Parameter:
344: .  coarser - the coarsen context

346:    Output Parameter:
347: .  llist - linked list of aggregates

349:    Level: advanced

351: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
352: @*/
353: PetscErrorCode MatCoarsenGetData(MatCoarsen coarser, PetscCoarsenData **llist)
354: {
357:   *llist             = coarser->agg_lists;
358:   coarser->agg_lists = NULL; /* giving up ownership */
359:   return 0;
360: }

362: /*@
363:    MatCoarsenSetFromOptions - Sets various coarsen options from the
364:         options database.

366:    Collective on MatCoarsen

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

371:    Options Database Command:
372: $  -mat_coarsen_type  <type>
373: $      Use -help for a list of available methods
374: $      (for instance, mis)

376:    Level: advanced

378: @*/
379: PetscErrorCode MatCoarsenSetFromOptions(MatCoarsen coarser)
380: {
382:   PetscBool      flag;
383:   char           type[256];
384:   const char     *def;

386:   PetscObjectOptionsBegin((PetscObject)coarser);
387:   if (!((PetscObject)coarser)->type_name) {
388:     def = MATCOARSENMIS;
389:   } else {
390:     def = ((PetscObject)coarser)->type_name;
391:   }

393:   PetscOptionsFList("-mat_coarsen_type","Type of aggregator","MatCoarsenSetType",MatCoarsenList,def,type,256,&flag);
394:   if (flag) {
395:     MatCoarsenSetType(coarser,type);
396:   }
397:   /*
398:    Set the type if it was never set.
399:    */
400:   if (!((PetscObject)coarser)->type_name) {
401:     MatCoarsenSetType(coarser,def);
402:   }

404:   if (coarser->ops->setfromoptions) {
405:     (*coarser->ops->setfromoptions)(PetscOptionsObject,coarser);
406:   }
407:   PetscOptionsEnd();
408:   MatCoarsenViewFromOptions(coarser,NULL,"-mat_coarsen_view");
409:   return 0;
410: }