Actual source code: matcoloring.c

petsc-dev 2014-02-02
Report Typos and Errors
  1: #include <petsc-private/matimpl.h>      /*I "petscmat.h"  I*/

  3: PetscFunctionList MatColoringList              = 0;
  4: PetscBool         MatColoringRegisterAllCalled = PETSC_FALSE;

  6: PETSC_EXTERN PetscErrorCode MatColoringTestValid(MatColoring,ISColoring);

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

 13:    Not Collective

 15:    Input Parameters:
 16: +  sname - name of Coloring (for example MATCOLORINGSL)
 17: -  function - function pointer that creates the coloring

 19:    Level: developer

 21:    Sample usage:
 22: .vb
 23:    MatColoringRegister("my_color",MyColor);
 24: .ve

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

 31: .keywords: matrix, Coloring, register

 33: .seealso: MatColoringRegisterDestroy(), MatColoringRegisterAll()
 34: @*/
 35: PetscErrorCode  MatColoringRegister(const char sname[],PetscErrorCode (*function)(MatColoring))
 36: {

 40:   PetscFunctionListAdd(&MatColoringList,sname,function);
 41:   return(0);
 42: }

 46: /*@C
 47:    MatColoringCreate - Creates a matrix coloring context.

 49:    Collective on MatColoring

 51:    Input Parameters:
 52: .  comm - MPI communicator

 54:    Output Parameter:
 55: .  mcptr - the new MatColoring context

 57:    Options Database Keys:
 58: +   -mat_coloring_type - the type of coloring algorithm used
 59: .   -mat_coloring_maxcolors - the maximum number of relevant colors, all nodes not in a color are in maxcolors+1
 60: .   -mat_coloring_distance - compute a distance 1,2,... coloring.
 61: .   -mat_coloring_view - print information about the coloring and the produced index sets
 62: -   -mat_coloring_valid - debugging option that prints all coloring incompatibilities

 64:    Level: beginner

 66: .keywords: Coloring, Matrix

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

 76:   *mcptr = 0;

 78: #if !defined(PETSC_USE_DYNAMIC_LIBRARIES)
 79:   MatInitializePackage();
 80: #endif
 81:   PetscHeaderCreate(mc,_p_MatColoring, struct _MatColoringOps, MAT_COLORING_CLASSID,"MatColoring","Matrix coloring",
 82:                            "MatColoring",PetscObjectComm((PetscObject)m),MatColoringDestroy, MatColoringView);
 83:   PetscObjectReference((PetscObject)m);
 84:   mc->mat       = m;
 85:   mc->dist      = 2; /* default to Jacobian computation case */
 86:   mc->maxcolors = 0; /* no maximum */
 87:   *mcptr        = mc;
 88:   mc->valid     = PETSC_FALSE;
 89:   return(0);
 90: }


 95: /*@C
 96:    MatColoringDestroy - Destroys the matrix coloring context

 98:    Collective on MatColoring

100:    Input Parameter:
101: .  mc - the MatColoring context

103:    Level: beginner

105: .keywords: Coloring, destroy

107: .seealso: MatColoringCreate(), MatColoringApply()
108: @*/
109: PetscErrorCode MatColoringDestroy(MatColoring *mc)
110: {

114:   if (--((PetscObject)(*mc))->refct > 0) {*mc = 0; return(0);}
115:   MatDestroy(&(*mc)->mat);
116:   if ((*mc)->ops->destroy) {(*((*mc)->ops->destroy))(*mc);}
117:   PetscHeaderDestroy(mc);
118:   return(0);
119: }

123: /*@C
124:    MatColoringSetType - Sets the type of coloring algorithm used

126:    Collective on MatColoring

128:    Input Parameter:
129: +  mc - the MatColoring context
130: -  type - the type of coloring

132:    Level: beginner

134:    Notes:  Possible types include the sequential types MATCOLORINGLF,
135:    MATCOLORINGSL, and MATCOLORINGID from the MINPACK package as well
136:    as a parallel MATCOLORINGMIS algorithm.

138: .keywords: Coloring, type

140: .seealso: MatColoringCreate(), MatColoringApply()
141: @*/
142: PetscErrorCode MatColoringSetType(MatColoring mc,MatColoringType type)
143: {
144:   PetscBool      match;
145:   PetscErrorCode ierr,(*r)(MatColoring);

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

163:   PetscObjectChangeTypeName((PetscObject)mc,type);
164:   (*r)(mc);
165:   return(0);
166: }

170: /*@
171:    MatColoringSetFromOptions - Sets MatColoring options from user parameters

173:    Collective on MatColoring

175:    Input Parameters:
176: .  mc - MatColoring context

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

184:    Level: beginner

186: .keywords: Coloring, Matrix

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


201:   MatColoringGetDistance(mc,&dist);
202:   MatColoringGetMaxColors(mc,&maxcolors);
203:   if (!MatColoringRegisterAllCalled) {MatColoringRegisterAll();}
204:   PetscObjectOptionsBegin((PetscObject)mc);
205:   if (((PetscObject)mc)->type_name) deft = ((PetscObject)mc)->type_name;
206:   PetscOptionsFList("-mat_coloring_type","The coloring method used","MatColoringSetType",MatColoringList,deft,type,256,&flg);
207:   if (flg) {
208:     MatColoringSetType(mc,type);
209:   } else if (!((PetscObject)mc)->type_name) {
210:     MatColoringSetType(mc,deft);
211:   }
212:   PetscOptionsInt("-mat_coloring_distance","Distance of the coloring","MatColoringSetDistance",dist,&dist,&flg);
213:   if (flg) {MatColoringSetDistance(mc,dist);}
214:   PetscOptionsInt("-mat_coloring_maxcolors","Maximum colors returned at the end. 1 returns an independent set","MatColoringSetMaxColors",maxcolors,&maxcolors,&flg);
215:   if (flg) {MatColoringSetMaxColors(mc,maxcolors);}
216:   if (mc->ops->setfromoptions) {
217:     (*mc->ops->setfromoptions)(mc);
218:   }
219:   PetscOptionsBool("-mat_coloring_valid","Check that a valid coloring has been produced","",mc->valid,&mc->valid,NULL);
220:   PetscObjectProcessOptionsHandlers((PetscObject)mc);
221:   PetscOptionsEnd();
222:   return(0);
223: }

227: /*@
228:    MatColoringSetDistance - Sets the distance of the coloring

230:    Logically Collective on MatColoring

232:    Input Parameter:
233: .  mc - the MatColoring context
234: .  dist - the distance the coloring should compute

236:    Level: beginner

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

244: .keywords: Coloring, distance, Jacobian

246: .seealso: MatColoringGetDistance(), MatColoringApply()
247: @*/
248: PetscErrorCode MatColoringSetDistance(MatColoring mc,PetscInt dist)
249: {
252:   mc->dist = dist;
253:   return(0);
254: }

258: /*@
259:    MatColoringGetDistance - Gets the distance of the coloring

261:    Logically Collective on MatColoring

263:    Input Parameter:
264: .  mc - the MatColoring context

266:    Output Paramter:
267: .  dist - the current distance being used for the coloring.

269:    Level: beginner

271: .keywords: Coloring, distance

273: .seealso: MatColoringSetDistance(), MatColoringApply()
274: @*/
275: PetscErrorCode MatColoringGetDistance(MatColoring mc,PetscInt *dist)
276: {
279:   if (dist) *dist = mc->dist;
280:   return(0);
281: }

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

288:    Logically Collective on MatColoring

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

294:    Level: beginner

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

302: .keywords: Coloring

304: .seealso: MatColoringGetMaxColors(), MatColoringApply()
305: @*/
306: PetscErrorCode MatColoringSetMaxColors(MatColoring mc,PetscInt maxcolors)
307: {
310:   mc->maxcolors = maxcolors;
311:   return(0);
312: }

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: }

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

348:    Collective on MatColoring

350:    Input Parameters:
351: .  mc - the MatColoring context

353:    Output Parameter:
354: .  coloring - the ISColoring instance containing the coloring

356:    Level: beginner

358: .keywords: Coloring, Apply

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

372:   PetscLogEventBegin(Mat_Coloring_Apply,mc,0,0,0);
373:   (*mc->ops->apply)(mc,coloring);
374:   PetscLogEventEnd(Mat_Coloring_Apply,mc,0,0,0);
375:   /* valid */
376:   if (mc->valid) {
377:     MatColoringTestValid(mc,*coloring);
378:   }
379:   /* view */
380:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)mc),((PetscObject)mc)->prefix,"-mat_coloring_view",&viewer,&format,&flg);
381:   if (flg && !PetscPreLoadingOn) {
382:     PetscViewerPushFormat(viewer,format);
383:     MatColoringView(mc,viewer);
384:     MatGetSize(mc->mat,NULL,&nc);
385:     ISColoringGetIS(*coloring,&ncolors,NULL);
386:     PetscPrintf(PetscObjectComm((PetscObject)mc),"  Number of colors %d\n",ncolors);
387:     PetscPrintf(PetscObjectComm((PetscObject)mc),"  Number of total columns %d\n",nc);
388:     if (nc <= 1000) {ISColoringView(*coloring,viewer);}
389:     PetscViewerPopFormat(viewer);
390:     PetscViewerDestroy(&viewer);
391:   }
392:   return(0);
393: }

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

400:    Collective on MatColoring

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

406:    Level: beginner

408: .keywords: Coloring, view

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

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

425:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
426:   if (iascii) {
427:     PetscObjectPrintClassNamePrefixType((PetscObject)mc,viewer);
428:     if (mc->maxcolors > 0) {
429:       PetscViewerASCIIPrintf(viewer,"  Distance %d, Max. Colors %d\n",mc->dist,mc->maxcolors);
430:     } else {
431:       PetscViewerASCIIPrintf(viewer,"  Distance %d\n",mc->dist);
432:     }
433:   }
434:   return(0);
435: }