1
/*$Id: shellpc.c,v 1.77 2001/08/21 21:03:18 bsmith Exp $*/
4
This provides a simple shell for Fortran (and C programmers) to
5
create their own preconditioner without writing much interface code.
8
#include "src/ksp/pc/pcimpl.h" /*I "petscpc.h" I*/
13
void *ctx,*ctxrich; /* user provided contexts for preconditioner */
15
int (*apply)(void *,Vec,Vec);
16
int (*view)(void *,PetscViewer);
17
int (*applytranspose)(void *,Vec,Vec);
18
int (*applyrich)(void *,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal,int);
24
#define __FUNCT__ "PCApply_SetUp"
25
static int PCSetUp_Shell(PC pc)
31
shell = (PC_Shell*)pc->data;
33
ierr = (*shell->setup)(shell->ctx);CHKERRQ(ierr);
35
PetscFunctionReturn(0);
39
#define __FUNCT__ "PCApply_Shell"
40
static int PCApply_Shell(PC pc,Vec x,Vec y)
46
shell = (PC_Shell*)pc->data;
47
if (!shell->apply) SETERRQ(1,"No apply() routine provided to Shell PC");
48
ierr = (*shell->apply)(shell->ctx,x,y);CHKERRQ(ierr);
49
PetscFunctionReturn(0);
53
#define __FUNCT__ "PCApplyTranspose_Shell"
54
static int PCApplyTranspose_Shell(PC pc,Vec x,Vec y)
60
shell = (PC_Shell*)pc->data;
61
if (!shell->applytranspose) SETERRQ(1,"No applytranspose() routine provided to Shell PC");
62
ierr = (*shell->applytranspose)(shell->ctx,x,y);CHKERRQ(ierr);
63
PetscFunctionReturn(0);
67
#define __FUNCT__ "PCApplyRichardson_Shell"
68
static int PCApplyRichardson_Shell(PC pc,Vec x,Vec y,Vec w,PetscReal rtol,PetscReal atol, PetscReal dtol,int it)
74
shell = (PC_Shell*)pc->data;
75
ierr = (*shell->applyrich)(shell->ctxrich,x,y,w,rtol,atol,dtol,it);CHKERRQ(ierr);
76
PetscFunctionReturn(0);
80
#define __FUNCT__ "PCDestroy_Shell"
81
static int PCDestroy_Shell(PC pc)
83
PC_Shell *shell = (PC_Shell*)pc->data;
87
if (shell->name) {ierr = PetscFree(shell->name);}
88
ierr = PetscFree(shell);CHKERRQ(ierr);
89
PetscFunctionReturn(0);
93
#define __FUNCT__ "PCView_Shell"
94
static int PCView_Shell(PC pc,PetscViewer viewer)
96
PC_Shell *shell = (PC_Shell*)pc->data;
101
ierr = PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&isascii);CHKERRQ(ierr);
103
if (shell->name) {ierr = PetscViewerASCIIPrintf(viewer," Shell: %s\n",shell->name);CHKERRQ(ierr);}
104
else {ierr = PetscViewerASCIIPrintf(viewer," Shell: no name\n");CHKERRQ(ierr);}
107
ierr = PetscViewerASCIIPushTab(viewer);CHKERRQ(ierr);
108
ierr = (*shell->view)(shell->ctx,viewer);CHKERRQ(ierr);
109
ierr = PetscViewerASCIIPopTab(viewer);CHKERRQ(ierr);
111
PetscFunctionReturn(0);
114
/* ------------------------------------------------------------------------------*/
117
#define __FUNCT__ "PCShellSetSetUp_Shell"
118
int PCShellSetSetUp_Shell(PC pc, int (*setup)(void*))
123
shell = (PC_Shell*)pc->data;
124
shell->setup = setup;
125
PetscFunctionReturn(0);
131
#define __FUNCT__ "PCShellSetApply_Shell"
132
int PCShellSetApply_Shell(PC pc,int (*apply)(void*,Vec,Vec),void *ptr)
137
shell = (PC_Shell*)pc->data;
138
shell->apply = apply;
140
PetscFunctionReturn(0);
146
#define __FUNCT__ "PCShellSetView_Shell"
147
int PCShellSetView_Shell(PC pc,int (*view)(void*,PetscViewer))
152
shell = (PC_Shell*)pc->data;
154
PetscFunctionReturn(0);
160
#define __FUNCT__ "PCShellSetApplyTranspose_Shell"
161
int PCShellSetApplyTranspose_Shell(PC pc,int (*applytranspose)(void*,Vec,Vec))
166
shell = (PC_Shell*)pc->data;
167
shell->applytranspose = applytranspose;
168
PetscFunctionReturn(0);
174
#define __FUNCT__ "PCShellSetName_Shell"
175
int PCShellSetName_Shell(PC pc,const char name[])
181
shell = (PC_Shell*)pc->data;
182
ierr = PetscStrallocpy(name,&shell->name);CHKERRQ(ierr);
183
PetscFunctionReturn(0);
189
#define __FUNCT__ "PCShellGetName_Shell"
190
int PCShellGetName_Shell(PC pc,char *name[])
195
shell = (PC_Shell*)pc->data;
197
PetscFunctionReturn(0);
203
#define __FUNCT__ "PCShellSetApplyRichardson_Shell"
204
int PCShellSetApplyRichardson_Shell(PC pc,int (*apply)(void*,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal,int),void *ptr)
209
shell = (PC_Shell*)pc->data;
210
pc->ops->applyrichardson = PCApplyRichardson_Shell;
211
shell->applyrich = apply;
212
shell->ctxrich = ptr;
213
PetscFunctionReturn(0);
217
/* -------------------------------------------------------------------------------*/
220
#define __FUNCT__ "PCShellSetSetUp"
222
PCShellSetSetUp - Sets routine to use to "setup" the preconditioner whenever the
223
matrix operator is changed.
228
+ pc - the preconditioner context
229
. setup - the application-provided setup routine
231
Calling sequence of setup:
233
int setup (void *ptr)
236
. ptr - the application context
240
.keywords: PC, shell, set, setup, user-provided
242
.seealso: PCShellSetApplyRichardson(), PCShellSetApply()
244
int PCShellSetSetUp(PC pc,int (*setup)(void*))
246
int ierr,(*f)(PC,int (*)(void*));
249
PetscValidHeaderSpecific(pc,PC_COOKIE,1);
250
ierr = PetscObjectQueryFunction((PetscObject)pc,"PCShellSetSetUp_C",(void (**)(void))&f);CHKERRQ(ierr);
252
ierr = (*f)(pc,setup);CHKERRQ(ierr);
254
PetscFunctionReturn(0);
259
#define __FUNCT__ "PCShellSetView"
261
PCShellSetView - Sets routine to use as viewer of shell preconditioner
266
+ pc - the preconditioner context
267
- view - the application-provided view routine
269
Calling sequence of apply:
271
int view(void *ptr,PetscViewer v)
274
+ ptr - the application context
279
.keywords: PC, shell, set, apply, user-provided
281
.seealso: PCShellSetApplyRichardson(), PCShellSetSetUp(), PCShellSetApplyTranspose()
283
int PCShellSetView(PC pc,int (*view)(void*,PetscViewer))
285
int ierr,(*f)(PC,int (*)(void*,PetscViewer));
288
PetscValidHeaderSpecific(pc,PC_COOKIE,1);
289
ierr = PetscObjectQueryFunction((PetscObject)pc,"PCShellSetView_C",(void (**)(void))&f);CHKERRQ(ierr);
291
ierr = (*f)(pc,view);CHKERRQ(ierr);
293
PetscFunctionReturn(0);
297
#define __FUNCT__ "PCShellSetApply"
299
PCShellSetApply - Sets routine to use as preconditioner.
304
+ pc - the preconditioner context
305
. apply - the application-provided preconditioning routine
306
- ptr - pointer to data needed by this routine
308
Calling sequence of apply:
310
int apply (void *ptr,Vec xin,Vec xout)
313
+ ptr - the application context
315
- xout - output vector
319
.keywords: PC, shell, set, apply, user-provided
321
.seealso: PCShellSetApplyRichardson(), PCShellSetSetUp(), PCShellSetApplyTranspose()
323
int PCShellSetApply(PC pc,int (*apply)(void*,Vec,Vec),void *ptr)
325
int ierr,(*f)(PC,int (*)(void*,Vec,Vec),void *);
328
PetscValidHeaderSpecific(pc,PC_COOKIE,1);
329
ierr = PetscObjectQueryFunction((PetscObject)pc,"PCShellSetApply_C",(void (**)(void))&f);CHKERRQ(ierr);
331
ierr = (*f)(pc,apply,ptr);CHKERRQ(ierr);
333
PetscFunctionReturn(0);
337
#define __FUNCT__ "PCShellSetApplyTranspose"
339
PCShellSetApplyTranspose - Sets routine to use as preconditioner transpose.
344
+ pc - the preconditioner context
345
- apply - the application-provided preconditioning transpose routine
347
Calling sequence of apply:
349
int applytranspose (void *ptr,Vec xin,Vec xout)
352
+ ptr - the application context
354
- xout - output vector
359
Uses the same context variable as PCShellSetApply().
361
.keywords: PC, shell, set, apply, user-provided
363
.seealso: PCShellSetApplyRichardson(), PCShellSetSetUp(), PCShellSetApply()
365
int PCShellSetApplyTranspose(PC pc,int (*applytranspose)(void*,Vec,Vec))
367
int ierr,(*f)(PC,int (*)(void*,Vec,Vec));
370
PetscValidHeaderSpecific(pc,PC_COOKIE,1);
371
ierr = PetscObjectQueryFunction((PetscObject)pc,"PCShellSetApplyTranspose_C",(void (**)(void))&f);CHKERRQ(ierr);
373
ierr = (*f)(pc,applytranspose);CHKERRQ(ierr);
375
PetscFunctionReturn(0);
379
#define __FUNCT__ "PCShellSetName"
381
PCShellSetName - Sets an optional name to associate with a shell
387
+ pc - the preconditioner context
388
- name - character string describing shell preconditioner
392
.keywords: PC, shell, set, name, user-provided
394
.seealso: PCShellGetName()
396
int PCShellSetName(PC pc,const char name[])
398
int ierr,(*f)(PC,const char []);
401
PetscValidHeaderSpecific(pc,PC_COOKIE,1);
402
ierr = PetscObjectQueryFunction((PetscObject)pc,"PCShellSetName_C",(void (**)(void))&f);CHKERRQ(ierr);
404
ierr = (*f)(pc,name);CHKERRQ(ierr);
406
PetscFunctionReturn(0);
410
#define __FUNCT__ "PCShellGetName"
412
PCShellGetName - Gets an optional name that the user has set for a shell
418
. pc - the preconditioner context
421
. name - character string describing shell preconditioner (you should not free this)
425
.keywords: PC, shell, get, name, user-provided
427
.seealso: PCShellSetName()
429
int PCShellGetName(PC pc,char *name[])
431
int ierr,(*f)(PC,char *[]);
434
PetscValidHeaderSpecific(pc,PC_COOKIE,1);
435
PetscValidPointer(name,2);
436
ierr = PetscObjectQueryFunction((PetscObject)pc,"PCShellGetName_C",(void (**)(void))&f);CHKERRQ(ierr);
438
ierr = (*f)(pc,name);CHKERRQ(ierr);
440
SETERRQ(1,"Not shell preconditioner, cannot get name");
442
PetscFunctionReturn(0);
446
#define __FUNCT__ "PCShellSetApplyRichardson"
448
PCShellSetApplyRichardson - Sets routine to use as preconditioner
449
in Richardson iteration.
454
+ pc - the preconditioner context
455
. apply - the application-provided preconditioning routine
456
- ptr - pointer to data needed by this routine
458
Calling sequence of apply:
460
int apply (void *ptr,Vec b,Vec x,Vec r,PetscReal rtol,PetscReal atol,PetscReal dtol,int maxits)
463
+ ptr - the application context
464
. b - right-hand-side
465
. x - current iterate
467
. rtol - relative tolerance of residual norm to stop at
468
. atol - absolute tolerance of residual norm to stop at
469
. dtol - if residual norm increases by this factor than return
470
- maxits - number of iterations to run
474
.keywords: PC, shell, set, apply, Richardson, user-provided
476
.seealso: PCShellSetApply()
478
int PCShellSetApplyRichardson(PC pc,int (*apply)(void*,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal,int),void *ptr)
480
int ierr,(*f)(PC,int (*)(void*,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal,int),void *);
483
PetscValidHeaderSpecific(pc,PC_COOKIE,1);
484
ierr = PetscObjectQueryFunction((PetscObject)pc,"PCShellSetApplyRichardson_C",(void (**)(void))&f);CHKERRQ(ierr);
486
ierr = (*f)(pc,apply,ptr);CHKERRQ(ierr);
488
PetscFunctionReturn(0);
492
PCSHELL - Creates a new preconditioner class for use with your
493
own private data storage format.
497
Concepts: providing your own preconditioner
500
$ int (*mult)(void *,Vec,Vec);
501
$ int (*setup)(void *);
502
$ PCCreate(comm,&pc);
503
$ PCSetType(pc,PCSHELL);
504
$ PCShellSetApply(pc,mult,ctx);
505
$ PCShellSetSetUp(pc,setup); (optional)
507
.seealso: PCCreate(), PCSetType(), PCType (for list of available types), PC,
508
KSPSHELL(), MATSHELL(), PCShellSetUp(), PCShellSetApply(), PCShellSetView(),
509
PCShellSetApplyTranpose(), PCShellSetName(), PCShellSetApplyRichardson(),
515
#define __FUNCT__ "PCCreate_Shell"
516
int PCCreate_Shell(PC pc)
522
pc->ops->destroy = PCDestroy_Shell;
523
ierr = PetscNew(PC_Shell,&shell);CHKERRQ(ierr);
524
PetscLogObjectMemory(pc,sizeof(PC_Shell));
526
pc->data = (void*)shell;
529
pc->ops->apply = PCApply_Shell;
530
pc->ops->view = PCView_Shell;
531
pc->ops->applytranspose = PCApplyTranspose_Shell;
532
pc->ops->applyrichardson = 0;
533
pc->ops->setup = PCSetUp_Shell;
534
pc->ops->view = PCView_Shell;
537
shell->applytranspose = 0;
539
shell->applyrich = 0;
545
ierr = PetscObjectComposeFunctionDynamic((PetscObject)pc,"PCShellSetSetUp_C","PCShellSetSetUp_Shell",
546
PCShellSetSetUp_Shell);CHKERRQ(ierr);
547
ierr = PetscObjectComposeFunctionDynamic((PetscObject)pc,"PCShellSetApply_C","PCShellSetApply_Shell",
548
PCShellSetApply_Shell);CHKERRQ(ierr);
549
ierr = PetscObjectComposeFunctionDynamic((PetscObject)pc,"PCShellSetView_C","PCShellSetView_Shell",
550
PCShellSetView_Shell);CHKERRQ(ierr);
551
ierr = PetscObjectComposeFunctionDynamic((PetscObject)pc,"PCShellSetApplyTranspose_C",
552
"PCShellSetApplyTranspose_Shell",
553
PCShellSetApplyTranspose_Shell);CHKERRQ(ierr);
554
ierr = PetscObjectComposeFunctionDynamic((PetscObject)pc,"PCShellSetName_C","PCShellSetName_Shell",
555
PCShellSetName_Shell);CHKERRQ(ierr);
556
ierr = PetscObjectComposeFunctionDynamic((PetscObject)pc,"PCShellGetName_C","PCShellGetName_Shell",
557
PCShellGetName_Shell);CHKERRQ(ierr);
558
ierr = PetscObjectComposeFunctionDynamic((PetscObject)pc,"PCShellSetApplyRichardson_C",
559
"PCShellSetApplyRichardson_Shell",
560
PCShellSetApplyRichardson_Shell);CHKERRQ(ierr);
562
PetscFunctionReturn(0);