Actual source code: coarsen.c
petsc-3.7.1 2016-05-15
Report Typos and Errors

      2: #include <petsc/private/matimpl.h>               /*I "petscmat.h" I*/

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

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

     12: /*@C
     13:    MatCoarsenRegister - Adds a new sparse matrix coarser to the  matrix package.

     15:    Logically Collective

     17:    Input Parameters:
     18: +  sname - name of coarsen (for example MATCOARSENMIS)
     19: -  function - function pointer that creates the coarsen type

     21:    Level: developer

     23:    Sample usage:
     24: .vb
     25:    MatCoarsenRegister("my_agg",MyAggCreate);
     26: .ve

     28:    Then, your aggregator can be chosen with the procedural interface via
     29: $     MatCoarsenSetType(agg,"my_agg")
     30:    or at runtime via the option
     31: $     -mat_coarsen_type my_agg

     33: .keywords: matrix, coarsen, register

     35: .seealso: MatCoarsenRegisterDestroy(), MatCoarsenRegisterAll()
     36: @*/
     37: PetscErrorCode  MatCoarsenRegister(const char sname[],PetscErrorCode (*function)(MatCoarsen))
     38: {

     42:   PetscFunctionListAdd(&MatCoarsenList,sname,function);
     43:   return(0);
     44: }

     48: /*@C
     49:    MatCoarsenGetType - Gets the Coarsen method type and name (as a string)
     50:         from the coarsen context.

     52:    Not collective

     54:    Input Parameter:
     55: .  coarsen - the coarsen context

     57:    Output Parameter:
     58: .  type - coarsener type

     60:    Level: intermediate

     62:    Not Collective

     64: .keywords: Coarsen, get, method, name, type
     65: @*/
     66: PetscErrorCode  MatCoarsenGetType(MatCoarsen coarsen,MatCoarsenType *type)
     67: {
     71:   *type = ((PetscObject)coarsen)->type_name;
     72:   return(0);
     73: }

     77: /*@
     78:    MatCoarsenApply - Gets a coarsen for a matrix.

     80:    Collective on MatCoarsen

     82:    Input Parameter:
     83: .   coarsen - the coarsen

     85:    Options Database Keys:
     86:    To specify the coarsen through the options database, use one of
     87:    the following
     88: $    -mat_coarsen_type mis
     89:    To see the coarsen result
     90: $    -mat_coarsen_view

     92:    Level: beginner

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

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

     98: .keywords: matrix, get, coarsen

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

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

    122: /*@
    123:    MatCoarsenSetAdjacency - Sets the adjacency graph (matrix) of the thing to be
    124:       partitioned.

    126:    Collective on MatCoarsen and Mat

    128:    Input Parameters:
    129: +  agg - the coarsen context
    130: -  adj - the adjacency matrix

    132:    Level: beginner

    134: .keywords: Coarsen, adjacency

    136: .seealso: MatCoarsenCreate()
    137: @*/
    138: PetscErrorCode  MatCoarsenSetAdjacency(MatCoarsen agg, Mat adj)
    139: {
    143:   agg->graph = adj;
    144:   return(0);
    145: }

    149: /*@
    150:    MatCoarsenSetStrictAggs -

    152:    Logically Collective on MatCoarsen

    154:    Input Parameters:
    155: +  agg - the coarsen context
    156: -  str - the adjacency matrix

    158:    Level: beginner

    160: .keywords: Coarsen, adjacency

    162: .seealso: MatCoarsenCreate()
    163: @*/
    164: PetscErrorCode MatCoarsenSetStrictAggs(MatCoarsen agg, PetscBool str)
    165: {
    168:   agg->strict_aggs = str;
    169:   return(0);
    170: }

    174: /*@
    175:    MatCoarsenDestroy - Destroys the coarsen context.

    177:    Collective on MatCoarsen

    179:    Input Parameters:
    180: .  agg - the coarsen context

    182:    Level: beginner

    184: .keywords: Coarsen, destroy, context

    186: .seealso: MatCoarsenCreate()
    187: @*/
    188: PetscErrorCode  MatCoarsenDestroy(MatCoarsen *agg)
    189: {

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

    197:   if ((*agg)->ops->destroy) {
    198:     (*(*agg)->ops->destroy)((*agg));
    199:   }

    201:   if ((*agg)->agg_lists) {
    202:     PetscCDDestroy((*agg)->agg_lists);
    203:   }

    205:   PetscHeaderDestroy(agg);
    206:   return(0);
    207: }

    211: /*@
    212:    MatCoarsenCreate - Creates a coarsen context.

    214:    Collective on MPI_Comm

    216:    Input Parameter:
    217: .   comm - MPI communicator

    219:    Output Parameter:
    220: .  newcrs - location to put the context

    222:    Level: beginner

    224: .keywords: Coarsen, create, context

    226: .seealso: MatCoarsenSetType(), MatCoarsenApply(), MatCoarsenDestroy(),
    227:           MatCoarsenSetAdjacency()

    229: @*/
    230: PetscErrorCode  MatCoarsenCreate(MPI_Comm comm, MatCoarsen *newcrs)
    231: {
    232:   MatCoarsen     agg;

    236:   *newcrs = 0;

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

    241:   *newcrs = agg;
    242:   return(0);
    243: }

    247: /*@C
    248:    MatCoarsenView - Prints the coarsen data structure.

    250:    Collective on MatCoarsen

    252:    Input Parameters:
    253: .  agg - the coarsen context
    254: .  viewer - optional visualization context

    256:    Level: intermediate

    258:    Note:
    259:    The available visualization contexts include
    260: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
    261: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
    262:          output where only the first processor opens
    263:          the file.  All other processors send their
    264:          data to the first processor to print.

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

    269: .keywords: Coarsen, view

    271: .seealso: PetscViewerASCIIOpen()
    272: @*/
    273: PetscErrorCode  MatCoarsenView(MatCoarsen agg,PetscViewer viewer)
    274: {
    276:   PetscBool      iascii;

    280:   if (!viewer) {
    281:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)agg),&viewer);
    282:   }

    286:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
    287:   PetscObjectPrintClassNamePrefixType((PetscObject)agg,viewer);
    288:   if (agg->ops->view) {
    289:     PetscViewerASCIIPushTab(viewer);
    290:     (*agg->ops->view)(agg,viewer);
    291:     PetscViewerASCIIPopTab(viewer);
    292:   }
    293:   return(0);
    294: }

    298: /*@C
    299:    MatCoarsenSetType - Sets the type of aggregator to use

    301:    Collective on MatCoarsen

    303:    Input Parameter:
    304: +  coarser - the coarsen context.
    305: -  type - a known coarsening method

    307:    Options Database Command:
    308: $  -mat_coarsen_type  <type>
    309: $      Use -help for a list of available methods
    310: $      (for instance, mis)

    312:    Level: intermediate

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

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

    318: @*/
    319: PetscErrorCode  MatCoarsenSetType(MatCoarsen coarser, MatCoarsenType type)
    320: {
    321:   PetscErrorCode ierr,(*r)(MatCoarsen);
    322:   PetscBool      match;

    328:   PetscObjectTypeCompare((PetscObject)coarser,type,&match);
    329:   if (match) return(0);

    331:   if (coarser->setupcalled) {
    332:      (*coarser->ops->destroy)(coarser);

    334:     coarser->ops->destroy = NULL;
    335:     coarser->subctx       = 0;
    336:     coarser->setupcalled  = 0;
    337:   }

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

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

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

    346:   (*r)(coarser);

    348:   PetscFree(((PetscObject)coarser)->type_name);
    349:   PetscStrallocpy(type,&((PetscObject)coarser)->type_name);
    350:   return(0);
    351: }

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

    358:    Logically Collective on Coarsen

    360:    Input Parameters:
    361: +  coarser - the coarsen context
    362: -  perm - vertex ordering of (greedy) algorithm

    364:    Level: beginner

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

    369: .keywords: Coarsen

    371: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
    372: @*/
    373: PetscErrorCode MatCoarsenSetGreedyOrdering(MatCoarsen coarser, const IS perm)
    374: {
    377:   coarser->perm = perm;
    378:   return(0);
    379: }

    383: /*@C
    384:    MatCoarsenGetData - Gets the weights for vertices for a coarsen.

    386:    Logically Collective on Coarsen

    388:    Input Parameter:
    389: .  coarser - the coarsen context

    391:    Output Parameter:
    392: .  llist - linked list of aggregates

    394:    Level: advanced

    396: .keywords: Coarsen

    398: .seealso: MatCoarsenCreate(), MatCoarsenSetType()
    399: @*/
    400: PetscErrorCode MatCoarsenGetData(MatCoarsen coarser, PetscCoarsenData **llist)
    401: {
    404:   if (!coarser->agg_lists) SETERRQ(PetscObjectComm((PetscObject)coarser),PETSC_ERR_ARG_WRONGSTATE,"No linked list - generate it or call ApplyCoarsen");
    405:   *llist             = coarser->agg_lists;
    406:   coarser->agg_lists = 0; /* giving up ownership */
    407:   return(0);
    408: }

    412: /*@
    413:    MatCoarsenSetFromOptions - Sets various coarsen options from the
    414:         options database.

    416:    Collective on MatCoarsen

    418:    Input Parameter:
    419: .  coarser - the coarsen context.

    421:    Options Database Command:
    422: $  -mat_coarsen_type  <type>
    423: $      Use -help for a list of available methods
    424: $      (for instance, mis)

    426:    Level: beginner

    428: .keywords: coarsen, set, method, type
    429: @*/
    430: PetscErrorCode MatCoarsenSetFromOptions(MatCoarsen coarser)
    431: {
    433:   PetscBool      flag;
    434:   char           type[256];
    435:   const char     *def;

    438:   PetscObjectOptionsBegin((PetscObject)coarser);
    439:   if (!((PetscObject)coarser)->type_name) {
    440:     def = MATCOARSENMIS;
    441:   } else {
    442:     def = ((PetscObject)coarser)->type_name;
    443:   }

    445:   PetscOptionsFList("-mat_coarsen_type","Type of aggregator","MatCoarsenSetType",MatCoarsenList,def,type,256,&flag);
    446:   if (flag) {
    447:     MatCoarsenSetType(coarser,type);
    448:   }
    449:   /*
    450:    Set the type if it was never set.
    451:    */
    452:   if (!((PetscObject)coarser)->type_name) {
    453:     MatCoarsenSetType(coarser,def);
    454:   }

    456:   if (coarser->ops->setfromoptions) {
    457:     (*coarser->ops->setfromoptions)(PetscOptionsObject,coarser);
    458:   }
    459:   PetscOptionsEnd();
    460:   MatCoarsenViewFromOptions(coarser,NULL,"-mat_coarsen_view");
    461:   return(0);
    462: }