Actual source code: pf.c
petsc-3.13.6 2020-09-29
Report Typos and Errors

      1: /*
      2:     The PF mathematical functions interface routines, callable by users.
      3: */
      4:  #include <../src/vec/pf/pfimpl.h>

      6: PetscClassId      PF_CLASSID          = 0;
      7: PetscFunctionList PFList              = NULL;   /* list of all registered PD functions */
      8: PetscBool         PFRegisterAllCalled = PETSC_FALSE;

     10: /*@C
     11:    PFSet - Sets the C/C++/Fortran functions to be used by the PF function

     13:    Collective on PF

     15:    Input Parameter:
     16: +  pf - the function context
     17: .  apply - function to apply to an array
     18: .  applyvec - function to apply to a Vec
     19: .  view - function that prints information about the PF
     20: .  destroy - function to free the private function context
     21: -  ctx - private function context

     23:    Level: beginner

     25: .seealso: PFCreate(), PFDestroy(), PFSetType(), PFApply(), PFApplyVec()
     26: @*/
     27: PetscErrorCode  PFSet(PF pf,PetscErrorCode (*apply)(void*,PetscInt,const PetscScalar*,PetscScalar*),PetscErrorCode (*applyvec)(void*,Vec,Vec),PetscErrorCode (*view)(void*,PetscViewer),PetscErrorCode (*destroy)(void*),void*ctx)
     28: {
     31:   pf->data          = ctx;
     32:   pf->ops->destroy  = destroy;
     33:   pf->ops->apply    = apply;
     34:   pf->ops->applyvec = applyvec;
     35:   pf->ops->view     = view;
     36:   return(0);
     37: }

     39: /*@C
     40:    PFDestroy - Destroys PF context that was created with PFCreate().

     42:    Collective on PF

     44:    Input Parameter:
     45: .  pf - the function context

     47:    Level: beginner

     49: .seealso: PFCreate(), PFSet(), PFSetType()
     50: @*/
     51: PetscErrorCode  PFDestroy(PF *pf)
     52: {

     56:   if (!*pf) return(0);
     58:   if (--((PetscObject)(*pf))->refct > 0) return(0);

     60:   PFViewFromOptions(*pf,NULL,"-pf_view");
     61:   /* if memory was published with SAWs then destroy it */
     62:   PetscObjectSAWsViewOff((PetscObject)*pf);

     64:   if ((*pf)->ops->destroy) { (*(*pf)->ops->destroy)((*pf)->data);}
     65:   PetscHeaderDestroy(pf);
     66:   return(0);
     67: }

     69: /*@C
     70:    PFCreate - Creates a mathematical function context.

     72:    Collective

     74:    Input Parameter:
     75: +  comm - MPI communicator
     76: .  dimin - dimension of the space you are mapping from
     77: -  dimout - dimension of the space you are mapping to

     79:    Output Parameter:
     80: .  pf - the function context

     82:    Level: developer

     84: .seealso: PFSet(), PFApply(), PFDestroy(), PFApplyVec()
     85: @*/
     86: PetscErrorCode  PFCreate(MPI_Comm comm,PetscInt dimin,PetscInt dimout,PF *pf)
     87: {
     88:   PF             newpf;

     93:   *pf = NULL;
     94:   PFInitializePackage();

     96:   PetscHeaderCreate(newpf,PF_CLASSID,"PF","Mathematical functions","Vec",comm,PFDestroy,PFView);
     97:   newpf->data          = 0;
     98:   newpf->ops->destroy  = 0;
     99:   newpf->ops->apply    = 0;
    100:   newpf->ops->applyvec = 0;
    101:   newpf->ops->view     = 0;
    102:   newpf->dimin         = dimin;
    103:   newpf->dimout        = dimout;

    105:   *pf                  = newpf;
    106:   return(0);

    108: }

    110: /* -------------------------------------------------------------------------------*/

    112: /*@
    113:    PFApplyVec - Applies the mathematical function to a vector

    115:    Collective on PF

    117:    Input Parameters:
    118: +  pf - the function context
    119: -  x - input vector (or NULL for the vector (0,1, .... N-1)

    121:    Output Parameter:
    122: .  y - output vector

    124:    Level: beginner

    126: .seealso: PFApply(), PFCreate(), PFDestroy(), PFSetType(), PFSet()
    127: @*/
    128: PetscErrorCode  PFApplyVec(PF pf,Vec x,Vec y)
    129: {
    131:   PetscInt       i,rstart,rend,n,p;
    132:   PetscBool      nox = PETSC_FALSE;

    137:   if (x) {
    139:     if (x == y) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_IDN,"x and y must be different vectors");
    140:   } else {
    141:     PetscScalar *xx;
    142:     PetscInt    lsize;

    144:     VecGetLocalSize(y,&lsize);
    145:     lsize = pf->dimin*lsize/pf->dimout;
    146:     VecCreateMPI(PetscObjectComm((PetscObject)y),lsize,PETSC_DETERMINE,&x);
    147:     nox   = PETSC_TRUE;
    148:     VecGetOwnershipRange(x,&rstart,&rend);
    149:     VecGetArray(x,&xx);
    150:     for (i=rstart; i<rend; i++) xx[i-rstart] = (PetscScalar)i;
    151:     VecRestoreArray(x,&xx);
    152:   }

    154:   VecGetLocalSize(x,&n);
    155:   VecGetLocalSize(y,&p);
    156:   if ((pf->dimin*(n/pf->dimin)) != n) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"Local input vector length %D not divisible by dimin %D of function",n,pf->dimin);
    157:   if ((pf->dimout*(p/pf->dimout)) != p) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"Local output vector length %D not divisible by dimout %D of function",p,pf->dimout);
    158:   if ((n/pf->dimin) != (p/pf->dimout)) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_ARG_SIZ,"Local vector lengths %D %D are wrong for dimin and dimout %D %D of function",n,p,pf->dimin,pf->dimout);

    160:   if (pf->ops->applyvec) {
    161:     (*pf->ops->applyvec)(pf->data,x,y);
    162:   } else {
    163:     PetscScalar *xx,*yy;

    165:     VecGetLocalSize(x,&n);
    166:     n    = n/pf->dimin;
    167:     VecGetArray(x,&xx);
    168:     VecGetArray(y,&yy);
    169:     if (!pf->ops->apply) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"No function has been provided for this PF");
    170:     (*pf->ops->apply)(pf->data,n,xx,yy);
    171:     VecRestoreArray(x,&xx);
    172:     VecRestoreArray(y,&yy);
    173:   }
    174:   if (nox) {
    175:     VecDestroy(&x);
    176:   }
    177:   return(0);
    178: }

    180: /*@
    181:    PFApply - Applies the mathematical function to an array of values.

    183:    Collective on PF

    185:    Input Parameters:
    186: +  pf - the function context
    187: .  n - number of pointwise function evaluations to perform, each pointwise function evaluation
    188:        is a function of dimin variables and computes dimout variables where dimin and dimout are defined
    189:        in the call to PFCreate()
    190: -  x - input array

    192:    Output Parameter:
    193: .  y - output array

    195:    Level: beginner

    197:    Notes:

    199: .seealso: PFApplyVec(), PFCreate(), PFDestroy(), PFSetType(), PFSet()
    200: @*/
    201: PetscErrorCode  PFApply(PF pf,PetscInt n,const PetscScalar *x,PetscScalar *y)
    202: {

    209:   if (x == y) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_IDN,"x and y must be different arrays");
    210:   if (!pf->ops->apply) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"No function has been provided for this PF");

    212:   (*pf->ops->apply)(pf->data,n,x,y);
    213:   return(0);
    214: }

    216: /*@C
    217:    PFViewFromOptions - View from Options

    219:    Collective on PF

    221:    Input Parameters:
    222: +  A - the PF context
    223: .  obj - Optional object
    224: -  name - command line option

    226:    Level: intermediate
    227: .seealso:  PF, PFView, PetscObjectViewFromOptions(), PFCreate()
    228: @*/
    229: PetscErrorCode  PFViewFromOptions(PF A,PetscObject obj,const char name[])
    230: {

    235:   PetscObjectViewFromOptions((PetscObject)A,obj,name);
    236:   return(0);
    237: }

    239: /*@
    240:    PFView - Prints information about a mathematical function

    242:    Collective on PF unless PetscViewer is PETSC_VIEWER_STDOUT_SELF

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

    248:    Note:
    249:    The available visualization contexts include
    250: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
    251: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
    252:          output where only the first processor opens
    253:          the file.  All other processors send their
    254:          data to the first processor to print.

    256:    The user can open an alternative visualization contexts with
    257:    PetscViewerASCIIOpen() (output to a specified file).

    259:    Level: developer

    261: .seealso: PetscViewerCreate(), PetscViewerASCIIOpen()
    262: @*/
    263: PetscErrorCode  PFView(PF pf,PetscViewer viewer)
    264: {
    265:   PetscErrorCode    ierr;
    266:   PetscBool         iascii;
    267:   PetscViewerFormat format;

    271:   if (!viewer) {
    272:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)pf),&viewer);
    273:   }

    277:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
    278:   if (iascii) {
    279:     PetscViewerGetFormat(viewer,&format);
    280:     PetscObjectPrintClassNamePrefixType((PetscObject)pf,viewer);
    281:     if (pf->ops->view) {
    282:       PetscViewerASCIIPushTab(viewer);
    283:       (*pf->ops->view)(pf->data,viewer);
    284:       PetscViewerASCIIPopTab(viewer);
    285:     }
    286:   }
    287:   return(0);
    288: }

    291: /*@C
    292:    PFRegister - Adds a method to the mathematical function package.

    294:    Not collective

    296:    Input Parameters:
    297: +  name_solver - name of a new user-defined solver
    298: -  routine_create - routine to create method context

    300:    Notes:
    301:    PFRegister() may be called multiple times to add several user-defined functions

    303:    Sample usage:
    304: .vb
    305:    PFRegister("my_function",MyFunctionSetCreate);
    306: .ve

    308:    Then, your solver can be chosen with the procedural interface via
    309: $     PFSetType(pf,"my_function")
    310:    or at runtime via the option
    311: $     -pf_type my_function

    313:    Level: advanced

    315: .seealso: PFRegisterAll(), PFRegisterDestroy(), PFRegister()
    316: @*/
    317: PetscErrorCode  PFRegister(const char sname[],PetscErrorCode (*function)(PF,void*))
    318: {

    322:   PFInitializePackage();
    323:   PetscFunctionListAdd(&PFList,sname,function);
    324:   return(0);
    325: }

    327: /*@C
    328:    PFGetType - Gets the PF method type and name (as a string) from the PF
    329:    context.

    331:    Not Collective

    333:    Input Parameter:
    334: .  pf - the function context

    336:    Output Parameter:
    337: .  type - name of function

    339:    Level: intermediate

    341: .seealso: PFSetType()

    343: @*/
    344: PetscErrorCode  PFGetType(PF pf,PFType *type)
    345: {
    349:   *type = ((PetscObject)pf)->type_name;
    350:   return(0);
    351: }

    354: /*@C
    355:    PFSetType - Builds PF for a particular function

    357:    Collective on PF

    359:    Input Parameter:
    360: +  pf - the function context.
    361: .  type - a known method
    362: -  ctx - optional type dependent context

    364:    Options Database Key:
    365: .  -pf_type <type> - Sets PF type

    368:   Notes:
    369:   See "petsc/include/petscpf.h" for available methods (for instance,
    370:   PFCONSTANT)

    372:   Level: intermediate

    374: .seealso: PFSet(), PFRegister(), PFCreate(), DMDACreatePF()

    376: @*/
    377: PetscErrorCode  PFSetType(PF pf,PFType type,void *ctx)
    378: {
    379:   PetscErrorCode ierr,(*r)(PF,void*);
    380:   PetscBool      match;

    386:   PetscObjectTypeCompare((PetscObject)pf,type,&match);
    387:   if (match) return(0);

    389:   if (pf->ops->destroy) { (*pf->ops->destroy)(pf);}
    390:   pf->data = 0;

    392:   /* Determine the PFCreateXXX routine for a particular function */
    393:   PetscFunctionListFind(PFList,type,&r);
    394:   if (!r) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested PF type %s",type);
    395:   pf->ops->destroy  = 0;
    396:   pf->ops->view     = 0;
    397:   pf->ops->apply    = 0;
    398:   pf->ops->applyvec = 0;

    400:   /* Call the PFCreateXXX routine for this particular function */
    401:   (*r)(pf,ctx);

    403:   PetscObjectChangeTypeName((PetscObject)pf,type);
    404:   return(0);
    405: }

    407: /*@
    408:    PFSetFromOptions - Sets PF options from the options database.

    410:    Collective on PF

    412:    Input Parameters:
    413: .  pf - the mathematical function context

    415:    Options Database Keys:

    417:    Notes:
    418:    To see all options, run your program with the -help option
    419:    or consult the users manual.

    421:    Level: intermediate

    423: .seealso:
    424: @*/
    425: PetscErrorCode  PFSetFromOptions(PF pf)
    426: {
    428:   char           type[256];
    429:   PetscBool      flg;

    434:   PetscObjectOptionsBegin((PetscObject)pf);
    435:   PetscOptionsFList("-pf_type","Type of function","PFSetType",PFList,0,type,256,&flg);
    436:   if (flg) {
    437:     PFSetType(pf,type,NULL);
    438:   }
    439:   if (pf->ops->setfromoptions) {
    440:     (*pf->ops->setfromoptions)(PetscOptionsObject,pf);
    441:   }

    443:   /* process any options handlers added with PetscObjectAddOptionsHandler() */
    444:   PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)pf);
    445:   PetscOptionsEnd();
    446:   return(0);
    447: }

    449: static PetscBool PFPackageInitialized = PETSC_FALSE;
    450: /*@C
    451:   PFFinalizePackage - This function destroys everything in the Petsc interface to Mathematica. It is
    452:   called from PetscFinalize().

    454:   Level: developer

    456: .seealso: PetscFinalize()
    457: @*/
    458: PetscErrorCode  PFFinalizePackage(void)
    459: {

    463:   PetscFunctionListDestroy(&PFList);
    464:   PFPackageInitialized = PETSC_FALSE;
    465:   PFRegisterAllCalled  = PETSC_FALSE;
    466:   return(0);
    467: }

    469: /*@C
    470:   PFInitializePackage - This function initializes everything in the PF package. It is called
    471:   from PetscDLLibraryRegister_petscvec() when using dynamic libraries, and on the first call to PFCreate()
    472:   when using shared or static libraries.

    474:   Level: developer

    476: .seealso: PetscInitialize()
    477: @*/
    478: PetscErrorCode  PFInitializePackage(void)
    479: {
    480:   char           logList[256];
    481:   PetscBool      opt,pkg;

    485:   if (PFPackageInitialized) return(0);
    486:   PFPackageInitialized = PETSC_TRUE;
    487:   /* Register Classes */
    488:   PetscClassIdRegister("PointFunction",&PF_CLASSID);
    489:   /* Register Constructors */
    490:   PFRegisterAll();
    491:   /* Process Info */
    492:   {
    493:     PetscClassId  classids[1];

    495:     classids[0] = PF_CLASSID;
    496:     PetscInfoProcessClass("pf", 1, classids);
    497:   }
    498:   /* Process summary exclusions */
    499:   PetscOptionsGetString(NULL,NULL,"-log_exclude",logList,sizeof(logList),&opt);
    500:   if (opt) {
    501:     PetscStrInList("pf",logList,',',&pkg);
    502:     if (pkg) {PetscLogEventExcludeClass(PF_CLASSID);}
    503:   }
    504:   /* Register package finalizer */
    505:   PetscRegisterFinalize(PFFinalizePackage);
    506:   return(0);
    507: }