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: `MatCoarsen`, `MatCoarsenType`, `MatCoarsenSetType()`, `MatCoarsenCreate()`, `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: `MatCoarsen`, `MatCoarsenCreate()`, `MatCoarsenType`, `MatCoarsenSetType()`, `MatCoarsenRegister()`
 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

 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|hem|misk
 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: `MatCoarsen`, `MatCoarseSetFromOptions()`, `MatCoarsenSetType()`, `MatCoarsenRegister()`, `MatCoarsenCreate()`,
 89:           `MatCoarsenDestroy()`, `MatCoarsenSetAdjacency()`
 90:           `MatCoarsenGetData()`
 91: @*/
 92: PetscErrorCode MatCoarsenApply(MatCoarsen coarser)
 93: {
 98:   PetscLogEventBegin(MAT_Coarsen, coarser, 0, 0, 0);
 99:   PetscUseTypeMethod(coarser, apply);
100:   PetscLogEventEnd(MAT_Coarsen, coarser, 0, 0, 0);
101:   return 0;
102: }

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

107:    Collective

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

113:    Level: advanced

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

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

128:    Logically Collective

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

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

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

147:    Collective

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

152:    Level: advanced

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

165:   if ((*agg)->ops->destroy) (*(*agg)->ops->destroy)((*agg));

167:   if ((*agg)->agg_lists) PetscCDDestroy((*agg)->agg_lists);

169:   PetscHeaderDestroy(agg);
170:   return 0;
171: }

173: /*@
174:    MatCoarsenCreate - Creates a coarsen context.

176:    Collective

178:    Input Parameter:
179: .   comm - MPI communicator

181:    Output Parameter:
182: .  newcrs - location to put the context

184:    Level: advanced

186: .seealso: `MatCoarsen`, `MatCoarsenSetType()`, `MatCoarsenApply()`, `MatCoarsenDestroy()`,
187:           `MatCoarsenSetAdjacency()`, `MatCoarsenGetData()`

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

194:   *newcrs = NULL;

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

199:   *newcrs = agg;
200:   return 0;
201: }

203: /*@C
204:    MatCoarsenViewFromOptions - View the coarsener from the options database

206:    Collective

208:    Input Parameters:
209: +  A - the coarsen context
210: .  obj - Optional object that provides the prefix for the option name
211: -  name - command line option (usually `-mat_coarsen_view`)

213:   Options Database:
214: .  -mat_coarsen_view [viewertype]:... - the viewer and its options

216:   Note:
217: .vb
218:     If no value is provided ascii:stdout is used
219:        ascii[:[filename][:[format][:append]]]    defaults to stdout - format can be one of ascii_info, ascii_info_detail, or ascii_matlab,
220:                                                   for example ascii::ascii_info prints just the information about the object not all details
221:                                                   unless :append is given filename opens in write mode, overwriting what was already there
222:        binary[:[filename][:[format][:append]]]   defaults to the file binaryoutput
223:        draw[:drawtype[:filename]]                for example, draw:tikz, draw:tikz:figure.tex  or draw:x
224:        socket[:port]                             defaults to the standard output port
225:        saws[:communicatorname]                    publishes object to the Scientific Application Webserver (SAWs)
226: .ve

228:    Level: intermediate

230: .seealso: `MatCoarsen`, `MatCoarsenView`, `PetscObjectViewFromOptions()`, `MatCoarsenCreate()`
231: @*/
232: PetscErrorCode MatCoarsenViewFromOptions(MatCoarsen A, PetscObject obj, const char name[])
233: {
235:   PetscObjectViewFromOptions((PetscObject)A, obj, name);
236:   return 0;
237: }

239: /*@C
240:    MatCoarsenView - Prints the coarsen data structure.

242:    Collective

244:    Input Parameters:
245: +  agg - the coarsen context
246: -  viewer - optional visualization context

248:    For viewing the options database see `MatCoarsenViewFromOptions()`

250:    Level: advanced

252: .seealso: `MatCoarsen`, `PetscViewer`, `PetscViewerASCIIOpen()`, `MatCoarsenViewFromOptions`
253: @*/
254: PetscErrorCode MatCoarsenView(MatCoarsen agg, PetscViewer viewer)
255: {
256:   PetscBool iascii;

259:   if (!viewer) PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)agg), &viewer);

263:   PetscObjectTypeCompare((PetscObject)viewer, PETSCVIEWERASCII, &iascii);
264:   PetscObjectPrintClassNamePrefixType((PetscObject)agg, viewer);
265:   if (agg->ops->view) {
266:     PetscViewerASCIIPushTab(viewer);
267:     PetscUseTypeMethod(agg, view, viewer);
268:     PetscViewerASCIIPopTab(viewer);
269:   }
270:   return 0;
271: }

273: /*@C
274:    MatCoarsenSetType - Sets the type of aggregator to use

276:    Collective

278:    Input Parameters:
279: +  coarser - the coarsen context.
280: -  type - a known coarsening method

282:    Options Database Key:
283: .  -mat_coarsen_type  <type> - (for instance, misk), use -help for a list of available methods

285:    Level: advanced

287: .seealso: `MatCoarsen`, `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:   PetscTryTypeMethod(coarser, destroy);
301:   coarser->ops->destroy = NULL;
302:   PetscMemzero(coarser->ops, sizeof(struct _MatCoarsenOps));

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

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

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

316:    Logically Collective

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

322:    Level: advanced

324:    Note:
325:    The `IS` weights is freed by PETSc, the user should not destroy it or change it after this call

327: .seealso: `MatCoarsen`, `MatCoarsenType`, `MatCoarsenCreate()`, `MatCoarsenSetType()`
328: @*/
329: PetscErrorCode MatCoarsenSetGreedyOrdering(MatCoarsen coarser, const IS perm)
330: {
332:   coarser->perm = perm;
333:   return 0;
334: }

336: /*@C
337:    MatCoarsenGetData - Gets the weights for vertices for a coarsener.

339:    Logically Collective

341:    Input Parameter:
342: .  coarser - the coarsen context

344:    Output Parameter:
345: .  llist - linked list of aggregates

347:    Level: advanced

349: .seealso: `MatCoarsen`, `MatCoarsenApply()`, `MatCoarsenCreate()`, `MatCoarsenSetType()`
350: @*/
351: PetscErrorCode MatCoarsenGetData(MatCoarsen coarser, PetscCoarsenData **llist)
352: {
355:   *llist             = coarser->agg_lists;
356:   coarser->agg_lists = NULL; /* giving up ownership */
357:   return 0;
358: }

360: /*@
361:    MatCoarsenSetFromOptions - Sets various coarsen options from the options database.

363:    Collective

365:    Input Parameter:
366: .  coarser - the coarsen context.

368:    Options Database Key:
369: .  -mat_coarsen_type  <type> - (for instance, mis), use -help for a list of available methods

371:    Level: advanced

373:    Note:
374:    Sets the `MatCoarsenType` to `MATCOARSENMISK` if has not been set previously

376: .seealso: `MatCoarsen`, `MatCoarsenType`, `MatCoarsenApply()`, `MatCoarsenCreate()`, `MatCoarsenSetType()`
377: @*/
378: PetscErrorCode MatCoarsenSetFromOptions(MatCoarsen coarser)
379: {
380:   PetscBool   flag;
381:   char        type[256];
382:   const char *def;

384:   PetscObjectOptionsBegin((PetscObject)coarser);
385:   if (!((PetscObject)coarser)->type_name) {
386:     def = MATCOARSENMISK;
387:   } else {
388:     def = ((PetscObject)coarser)->type_name;
389:   }

391:   PetscOptionsFList("-mat_coarsen_type", "Type of aggregator", "MatCoarsenSetType", MatCoarsenList, def, type, 256, &flag);
392:   if (flag) MatCoarsenSetType(coarser, type);
393:   /*
394:    Set the type if it was never set.
395:    */
396:   if (!((PetscObject)coarser)->type_name) MatCoarsenSetType(coarser, def);

398:   PetscTryTypeMethod(coarser, setfromoptions, PetscOptionsObject);
399:   PetscOptionsEnd();

401:   return 0;
402: }