Actual source code: matcoloring.c

petsc-3.10.0 2018-09-12
Report Typos and Errors
  1:  #include <petsc/private/matimpl.h>

  3: PetscFunctionList MatColoringList              = 0;
  4: PetscBool         MatColoringRegisterAllCalled = PETSC_FALSE;
  5: const char *const MatColoringWeightTypes[] = {"RANDOM","LEXICAL","LF","SL","MatColoringWeightType","MAT_COLORING_WEIGHT_",0};

  7: /*@C
  8:    MatColoringRegister - Adds a new sparse matrix coloring to the  matrix package.

 10:    Not Collective

 12:    Input Parameters:
 13: +  sname - name of Coloring (for example MATCOLORINGSL)
 14: -  function - function pointer that creates the coloring

 16:    Level: developer

 18:    Sample usage:
 19: .vb
 20:    MatColoringRegister("my_color",MyColor);
 21: .ve

 23:    Then, your partitioner can be chosen with the procedural interface via
 24: $     MatColoringSetType(part,"my_color")
 25:    or at runtime via the option
 26: $     -mat_coloring_type my_color

 28: .keywords: matrix, Coloring, register

 30: .seealso: MatColoringRegisterDestroy(), MatColoringRegisterAll()
 31: @*/
 32: PetscErrorCode  MatColoringRegister(const char sname[],PetscErrorCode (*function)(MatColoring))
 33: {

 37:   PetscFunctionListAdd(&MatColoringList,sname,function);
 38:   return(0);
 39: }

 41: /*@
 42:    MatColoringCreate - Creates a matrix coloring context.

 44:    Collective on MatColoring

 46:    Input Parameters:
 47: .  comm - MPI communicator

 49:    Output Parameter:
 50: .  mcptr - the new MatColoring context

 52:    Options Database Keys:
 53: +   -mat_coloring_type - the type of coloring algorithm used
 54: .   -mat_coloring_maxcolors - the maximum number of relevant colors, all nodes not in a color are in maxcolors+1
 55: .   -mat_coloring_distance - compute a distance 1,2,... coloring.
 56: .   -mat_coloring_view - print information about the coloring and the produced index sets
 57: .   -mat_coloring_test - debugging option that prints all coloring incompatibilities
 58: -   -mat_is_coloring_test - debugging option that throws an error if MatColoringApply() generates an incorrect iscoloring

 60:    Level: beginner

 62:    Notes:
 63:     A distance one coloring is useful, for example, multi-color SOR. A distance two coloring is for the finite difference computation of Jacobians 
 64:           (see MatFDColoringCreate()).

 66:           Some coloring types only support distance two colorings

 68: .keywords: Coloring, Matrix

 70: .seealso: MatColoring, MatColoringApply(), MatFDColoringCreate()
 71: @*/
 72: PetscErrorCode MatColoringCreate(Mat m,MatColoring *mcptr)
 73: {
 74:   MatColoring    mc;

 80:   *mcptr = NULL;

 82: #if !defined(PETSC_USE_DYNAMIC_LIBRARIES)
 83:   MatInitializePackage();
 84: #endif
 85:   PetscHeaderCreate(mc, MAT_COLORING_CLASSID,"MatColoring","Matrix coloring", "MatColoring",PetscObjectComm((PetscObject)m),MatColoringDestroy, MatColoringView);
 86:   PetscObjectReference((PetscObject)m);
 87:   mc->mat       = m;
 88:   mc->dist      = 2; /* default to Jacobian computation case */
 89:   mc->maxcolors = IS_COLORING_MAX;
 90:   *mcptr        = mc;
 91:   mc->valid     = PETSC_FALSE;
 92:   mc->weight_type = MAT_COLORING_WEIGHT_RANDOM;
 93:   mc->user_weights = NULL;
 94:   mc->user_lperm = NULL;
 95:   return(0);
 96: }


 99: /*@
100:    MatColoringDestroy - Destroys the matrix coloring context

102:    Collective on MatColoring

104:    Input Parameter:
105: .  mc - the MatColoring context

107:    Level: beginner

109: .keywords: Coloring, destroy

111: .seealso: MatColoringCreate(), MatColoringApply()
112: @*/
113: PetscErrorCode MatColoringDestroy(MatColoring *mc)
114: {

118:   if (--((PetscObject)(*mc))->refct > 0) {*mc = 0; return(0);}
119:   MatDestroy(&(*mc)->mat);
120:   if ((*mc)->ops->destroy) {(*((*mc)->ops->destroy))(*mc);}
121:   if ((*mc)->user_weights) {PetscFree((*mc)->user_weights);}
122:   if ((*mc)->user_lperm) {PetscFree((*mc)->user_lperm);}
123:   PetscHeaderDestroy(mc);
124:   return(0);
125: }

127: /*@C
128:    MatColoringSetType - Sets the type of coloring algorithm used

130:    Collective on MatColoring

132:    Input Parameter:
133: +  mc - the MatColoring context
134: -  type - the type of coloring

136:    Level: beginner

138:    Notes:
139:     Possible types include the sequential types MATCOLORINGLF,
140:    MATCOLORINGSL, and MATCOLORINGID from the MINPACK package as well
141:    as a parallel MATCOLORINGMIS algorithm.

143: .keywords: Coloring, type

145: .seealso: MatColoringCreate(), MatColoringApply()
146: @*/
147: PetscErrorCode MatColoringSetType(MatColoring mc,MatColoringType type)
148: {
149:   PetscBool      match;
150:   PetscErrorCode ierr,(*r)(MatColoring);

155:   PetscObjectTypeCompare((PetscObject)mc,type,&match);
156:   if (match) return(0);
157:    PetscFunctionListFind(MatColoringList,type,&r);
158:   if (!r) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested MatColoring type %s",type);
159:   if (mc->ops->destroy) {
160:     (*(mc)->ops->destroy)(mc);
161:     mc->ops->destroy = NULL;
162:   }
163:   mc->ops->apply            = 0;
164:   mc->ops->view             = 0;
165:   mc->ops->setfromoptions   = 0;
166:   mc->ops->destroy          = 0;

168:   PetscObjectChangeTypeName((PetscObject)mc,type);
169:   (*r)(mc);
170:   return(0);
171: }

173: /*@
174:    MatColoringSetFromOptions - Sets MatColoring options from user parameters

176:    Collective on MatColoring

178:    Input Parameters:
179: .  mc - MatColoring context

181:    Options Database Keys:
182: +   -mat_coloring_type - the type of coloring algorithm used
183: .   -mat_coloring_maxcolors - the maximum number of relevant colors, all nodes not in a color are in maxcolors+1
184: .   -mat_coloring_distance - compute a distance 1,2,... coloring.
185: .   -mat_coloring_view - print information about the coloring and the produced index sets

187:    Level: beginner

189: .keywords: Coloring, Matrix

191: .seealso: MatColoring, MatColoringApply()
192: @*/
193: PetscErrorCode MatColoringSetFromOptions(MatColoring mc)
194: {
195:   PetscBool      flg;
196:   MatColoringType deft = MATCOLORINGSL;
197:   char           type[256];
199:   PetscInt       dist,maxcolors;

203:   MatColoringGetDistance(mc,&dist);
204:   if (dist == 2) deft = MATCOLORINGSL;
205:   else           deft = MATCOLORINGGREEDY;
206:   MatColoringGetMaxColors(mc,&maxcolors);
207:   MatColoringRegisterAll();
208:   PetscObjectOptionsBegin((PetscObject)mc);
209:   if (((PetscObject)mc)->type_name) deft = ((PetscObject)mc)->type_name;
210:   PetscOptionsFList("-mat_coloring_type","The coloring method used","MatColoringSetType",MatColoringList,deft,type,256,&flg);
211:   if (flg) {
212:     MatColoringSetType(mc,type);
213:   } else if (!((PetscObject)mc)->type_name) {
214:     MatColoringSetType(mc,deft);
215:   }
216:   PetscOptionsInt("-mat_coloring_distance","Distance of the coloring","MatColoringSetDistance",dist,&dist,&flg);
217:   if (flg) {MatColoringSetDistance(mc,dist);}
218:   PetscOptionsInt("-mat_coloring_maxcolors","Maximum colors returned at the end. 1 returns an independent set","MatColoringSetMaxColors",maxcolors,&maxcolors,&flg);
219:   if (flg) {MatColoringSetMaxColors(mc,maxcolors);}
220:   if (mc->ops->setfromoptions) {
221:     (*mc->ops->setfromoptions)(PetscOptionsObject,mc);
222:   }
223:   PetscOptionsBool("-mat_coloring_test","Check that a valid coloring has been produced","",mc->valid,&mc->valid,NULL);
224:   PetscOptionsBool("-mat_is_coloring_test","Check that a valid iscoloring has been produced","",mc->valid_iscoloring,&mc->valid_iscoloring,NULL);
225:   PetscOptionsEnum("-mat_coloring_weight_type","Sets the type of vertex weighting used","MatColoringSetWeightType",MatColoringWeightTypes,(PetscEnum)mc->weight_type,(PetscEnum*)&mc->weight_type,NULL);
226:   PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)mc);
227:   PetscOptionsEnd();
228:   return(0);
229: }

231: /*@
232:    MatColoringSetDistance - Sets the distance of the coloring

234:    Logically Collective on MatColoring

236:    Input Parameter:
237: .  mc - the MatColoring context
238: .  dist - the distance the coloring should compute

240:    Level: beginner

242:    Notes:
243:     The distance of the coloring denotes the minimum number
244:    of edges in the graph induced by the matrix any two vertices
245:    of the same color are.  Distance-1 colorings are the classical
246:    coloring, where no two vertices of the same color are adjacent.
247:    distance-2 colorings are useful for the computation of Jacobians.

249: .keywords: Coloring, distance, Jacobian

251: .seealso: MatColoringGetDistance(), MatColoringApply()
252: @*/
253: PetscErrorCode MatColoringSetDistance(MatColoring mc,PetscInt dist)
254: {
257:   mc->dist = dist;
258:   return(0);
259: }

261: /*@
262:    MatColoringGetDistance - Gets the distance of the coloring

264:    Logically Collective on MatColoring

266:    Input Parameter:
267: .  mc - the MatColoring context

269:    Output Paramter:
270: .  dist - the current distance being used for the coloring.

272:    Level: beginner

274: .keywords: Coloring, distance

276: .seealso: MatColoringSetDistance(), MatColoringApply()
277: @*/
278: PetscErrorCode MatColoringGetDistance(MatColoring mc,PetscInt *dist)
279: {
282:   if (dist) *dist = mc->dist;
283:   return(0);
284: }

286: /*@
287:    MatColoringSetMaxColors - Sets the maximum number of colors

289:    Logically Collective on MatColoring

291:    Input Parameter:
292: +  mc - the MatColoring context
293: -  maxcolors - the maximum number of colors to produce

295:    Level: beginner

297:    Notes:
298:     This may be used to compute a certain number of
299:    independent sets from the graph.  For instance, while using
300:    MATCOLORINGMIS and maxcolors = 1, one gets out an MIS.  Vertices
301:    not in a color are set to have color maxcolors+1, which is not
302:    a valid color as they may be adjacent.

304: .keywords: Coloring

306: .seealso: MatColoringGetMaxColors(), MatColoringApply()
307: @*/
308: PetscErrorCode MatColoringSetMaxColors(MatColoring mc,PetscInt maxcolors)
309: {
312:   mc->maxcolors = maxcolors;
313:   return(0);
314: }

316: /*@
317:    MatColoringGetMaxColors - Gets the maximum number of colors

319:    Logically Collective on MatColoring

321:    Input Parameter:
322: .  mc - the MatColoring context

324:    Output Paramter:
325: .  maxcolors - the current maximum number of colors to produce

327:    Level: beginner

329: .keywords: Coloring

331: .seealso: MatColoringSetMaxColors(), MatColoringApply()
332: @*/
333: PetscErrorCode MatColoringGetMaxColors(MatColoring mc,PetscInt *maxcolors)
334: {
337:   if (maxcolors) *maxcolors = mc->maxcolors;
338:   return(0);
339: }

341: /*@
342:    MatColoringApply - Apply the coloring to the matrix, producing index
343:    sets corresponding to a number of independent sets in the induced
344:    graph.

346:    Collective on MatColoring

348:    Input Parameters:
349: .  mc - the MatColoring context

351:    Output Parameter:
352: .  coloring - the ISColoring instance containing the coloring

354:    Level: beginner

356: .keywords: Coloring, Apply

358: .seealso: MatColoring, MatColoringCreate()
359: @*/
360: PetscErrorCode MatColoringApply(MatColoring mc,ISColoring *coloring)
361: {
362:   PetscErrorCode    ierr;
363:   PetscBool         flg;
364:   PetscViewerFormat format;
365:   PetscViewer       viewer;
366:   PetscInt          nc,ncolors;

370:   PetscLogEventBegin(MATCOLORING_Apply,mc,0,0,0);
371:   (*mc->ops->apply)(mc,coloring);
372:   PetscLogEventEnd(MATCOLORING_Apply,mc,0,0,0);

374:   /* valid */
375:   if (mc->valid) {
376:     MatColoringTest(mc,*coloring);
377:   }
378:   if (mc->valid_iscoloring) {
379:     MatISColoringTest(mc->mat,*coloring);
380:   }

382:   /* view */
383:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)mc),((PetscObject)mc)->prefix,"-mat_coloring_view",&viewer,&format,&flg);
384:   if (flg && !PetscPreLoadingOn) {
385:     PetscViewerPushFormat(viewer,format);
386:     MatColoringView(mc,viewer);
387:     MatGetSize(mc->mat,NULL,&nc);
388:     ISColoringGetIS(*coloring,&ncolors,NULL);
389:     PetscViewerASCIIPrintf(viewer,"  Number of colors %d\n",ncolors);
390:     PetscViewerASCIIPrintf(viewer,"  Number of total columns %d\n",nc);
391:     if (nc <= 1000) {ISColoringView(*coloring,viewer);}
392:     PetscViewerPopFormat(viewer);
393:     PetscViewerDestroy(&viewer);
394:   }
395:   return(0);
396: }

398: /*@
399:    MatColoringView - Output details about the MatColoring.

401:    Collective on MatColoring

403:    Input Parameters:
404: -  mc - the MatColoring context
405: +  viewer - the Viewer context

407:    Level: beginner

409: .keywords: Coloring, view

411: .seealso: MatColoring, MatColoringApply()
412: @*/
413: PetscErrorCode MatColoringView(MatColoring mc,PetscViewer viewer)
414: {
416:   PetscBool      iascii;

420:   if (!viewer) {
421:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)mc),&viewer);
422:   }

426:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
427:   if (iascii) {
428:     PetscObjectPrintClassNamePrefixType((PetscObject)mc,viewer);
429:     PetscViewerASCIIPrintf(viewer,"  Weight type: %s\n",MatColoringWeightTypes[mc->weight_type]);
430:     if (mc->maxcolors > 0) {
431:       PetscViewerASCIIPrintf(viewer,"  Distance %D, Max. Colors %D\n",mc->dist,mc->maxcolors);
432:     } else {
433:       PetscViewerASCIIPrintf(viewer,"  Distance %d\n",mc->dist);
434:     }
435:   }
436:   return(0);
437: }

439: /*@
440:    MatColoringSetWeightType - Set the type of weight computation used.

442:    Logically collective on MatColoring

444:    Input Parameters:
445: -  mc - the MatColoring context
446: +  wt - the weight type

448:    Level: beginner

450: .keywords: Coloring, view

452: .seealso: MatColoring, MatColoringWeightType
453: @*/
454: PetscErrorCode MatColoringSetWeightType(MatColoring mc,MatColoringWeightType wt)
455: {
457:   mc->weight_type = wt;
458:   return(0);

460: }