1 /*$Id: snes.c,v 1.235 2001/08/21 21:03:49 bsmith Exp $*/ 2 3 #include "src/snes/snesimpl.h" /*I "petscsnes.h" I*/ 4 5 PetscTruth SNESRegisterAllCalled = PETSC_FALSE; 6 PetscFList SNESList = PETSC_NULL; 7 8 /* Logging support */ 9 int SNES_COOKIE; 10 int MATSNESMFCTX_COOKIE; 11 int SNESEvents[SNES_MAX_EVENTS]; 12 13 #undef __FUNCT__ 14 #define __FUNCT__ "SNESGetProblemType" 15 /*@C 16 SNESGetProblemType -Indicates if SNES is solving a nonlinear system or a minimization 17 18 Not Collective 19 20 Input Parameter: 21 . SNES - the SNES context 22 23 Output Parameter: 24 . type - SNES_NONLINEAR_EQUATIONS (for systems of nonlinear equations) 25 or SNES_UNCONSTRAINED_MINIMIZATION (for unconstrained minimization) 26 27 Level: intermediate 28 29 .keywords: SNES, problem type 30 31 .seealso: SNESCreate() 32 @*/ 33 int SNESGetProblemType(SNES snes,SNESProblemType *type) 34 { 35 PetscFunctionBegin; 36 PetscValidHeaderSpecific(snes,SNES_COOKIE); 37 *type = snes->method_class; 38 PetscFunctionReturn(0); 39 } 40 41 #undef __FUNCT__ 42 #define __FUNCT__ "SNESView" 43 /*@C 44 SNESView - Prints the SNES data structure. 45 46 Collective on SNES 47 48 Input Parameters: 49 + SNES - the SNES context 50 - viewer - visualization context 51 52 Options Database Key: 53 . -snes_view - Calls SNESView() at end of SNESSolve() 54 55 Notes: 56 The available visualization contexts include 57 + PETSC_VIEWER_STDOUT_SELF - standard output (default) 58 - PETSC_VIEWER_STDOUT_WORLD - synchronized standard 59 output where only the first processor opens 60 the file. All other processors send their 61 data to the first processor to print. 62 63 The user can open an alternative visualization context with 64 PetscViewerASCIIOpen() - output to a specified file. 65 66 Level: beginner 67 68 .keywords: SNES, view 69 70 .seealso: PetscViewerASCIIOpen() 71 @*/ 72 int SNESView(SNES snes,PetscViewer viewer) 73 { 74 SNES_KSP_EW_ConvCtx *kctx; 75 int ierr; 76 SLES sles; 77 char *type; 78 PetscTruth isascii,isstring; 79 80 PetscFunctionBegin; 81 PetscValidHeaderSpecific(snes,SNES_COOKIE); 82 if (!viewer) viewer = PETSC_VIEWER_STDOUT_(snes->comm); 83 PetscValidHeaderSpecific(viewer,PETSC_VIEWER_COOKIE); 84 PetscCheckSameComm(snes,viewer); 85 86 ierr = PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&isascii);CHKERRQ(ierr); 87 ierr = PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_STRING,&isstring);CHKERRQ(ierr); 88 if (isascii) { 89 if (snes->prefix) { 90 ierr = PetscViewerASCIIPrintf(viewer,"SNES Object:(%s)\n",snes->prefix);CHKERRQ(ierr); 91 } else { 92 ierr = PetscViewerASCIIPrintf(viewer,"SNES Object:\n");CHKERRQ(ierr); 93 } 94 ierr = SNESGetType(snes,&type);CHKERRQ(ierr); 95 if (type) { 96 ierr = PetscViewerASCIIPrintf(viewer," type: %s\n",type);CHKERRQ(ierr); 97 } else { 98 ierr = PetscViewerASCIIPrintf(viewer," type: not set yet\n");CHKERRQ(ierr); 99 } 100 if (snes->view) { 101 ierr = PetscViewerASCIIPushTab(viewer);CHKERRQ(ierr); 102 ierr = (*snes->view)(snes,viewer);CHKERRQ(ierr); 103 ierr = PetscViewerASCIIPopTab(viewer);CHKERRQ(ierr); 104 } 105 ierr = PetscViewerASCIIPrintf(viewer," maximum iterations=%d, maximum function evaluations=%d\n",snes->max_its,snes->max_funcs);CHKERRQ(ierr); 106 ierr = PetscViewerASCIIPrintf(viewer," tolerances: relative=%g, absolute=%g, solution=%g\n", 107 snes->rtol,snes->atol,snes->xtol);CHKERRQ(ierr); 108 ierr = PetscViewerASCIIPrintf(viewer," total number of linear solver iterations=%d\n",snes->linear_its);CHKERRQ(ierr); 109 ierr = PetscViewerASCIIPrintf(viewer," total number of function evaluations=%d\n",snes->nfuncs);CHKERRQ(ierr); 110 if (snes->method_class == SNES_UNCONSTRAINED_MINIMIZATION) { 111 ierr = PetscViewerASCIIPrintf(viewer," min function tolerance=%g\n",snes->fmin);CHKERRQ(ierr); 112 } 113 if (snes->ksp_ewconv) { 114 kctx = (SNES_KSP_EW_ConvCtx *)snes->kspconvctx; 115 if (kctx) { 116 ierr = PetscViewerASCIIPrintf(viewer," Eisenstat-Walker computation of KSP relative tolerance (version %d)\n",kctx->version);CHKERRQ(ierr); 117 ierr = PetscViewerASCIIPrintf(viewer," rtol_0=%g, rtol_max=%g, threshold=%g\n",kctx->rtol_0,kctx->rtol_max,kctx->threshold);CHKERRQ(ierr); 118 ierr = PetscViewerASCIIPrintf(viewer," gamma=%g, alpha=%g, alpha2=%g\n",kctx->gamma,kctx->alpha,kctx->alpha2);CHKERRQ(ierr); 119 } 120 } 121 } else if (isstring) { 122 ierr = SNESGetType(snes,&type);CHKERRQ(ierr); 123 ierr = PetscViewerStringSPrintf(viewer," %-3.3s",type);CHKERRQ(ierr); 124 } 125 ierr = SNESGetSLES(snes,&sles);CHKERRQ(ierr); 126 ierr = PetscViewerASCIIPushTab(viewer);CHKERRQ(ierr); 127 ierr = SLESView(sles,viewer);CHKERRQ(ierr); 128 ierr = PetscViewerASCIIPopTab(viewer);CHKERRQ(ierr); 129 PetscFunctionReturn(0); 130 } 131 132 /* 133 We retain a list of functions that also take SNES command 134 line options. These are called at the end SNESSetFromOptions() 135 */ 136 #define MAXSETFROMOPTIONS 5 137 static int numberofsetfromoptions; 138 static int (*othersetfromoptions[MAXSETFROMOPTIONS])(SNES); 139 140 #undef __FUNCT__ 141 #define __FUNCT__ "SNESAddOptionsChecker" 142 /*@ 143 SNESAddOptionsChecker - Adds an additional function to check for SNES options. 144 145 Not Collective 146 147 Input Parameter: 148 . snescheck - function that checks for options 149 150 Level: developer 151 152 .seealso: SNESSetFromOptions() 153 @*/ 154 int SNESAddOptionsChecker(int (*snescheck)(SNES)) 155 { 156 PetscFunctionBegin; 157 if (numberofsetfromoptions >= MAXSETFROMOPTIONS) { 158 SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE, "Too many options checkers, only %d allowed", MAXSETFROMOPTIONS); 159 } 160 161 othersetfromoptions[numberofsetfromoptions++] = snescheck; 162 PetscFunctionReturn(0); 163 } 164 165 #undef __FUNCT__ 166 #define __FUNCT__ "SNESSetFromOptions" 167 /*@ 168 SNESSetFromOptions - Sets various SNES and SLES parameters from user options. 169 170 Collective on SNES 171 172 Input Parameter: 173 . snes - the SNES context 174 175 Options Database Keys: 176 + -snes_type <type> - ls, tr, umls, umtr, test 177 . -snes_stol - convergence tolerance in terms of the norm 178 of the change in the solution between steps 179 . -snes_atol <atol> - absolute tolerance of residual norm 180 . -snes_rtol <rtol> - relative decrease in tolerance norm from initial 181 . -snes_max_it <max_it> - maximum number of iterations 182 . -snes_max_funcs <max_funcs> - maximum number of function evaluations 183 . -snes_trtol <trtol> - trust region tolerance 184 . -snes_no_convergence_test - skip convergence test in nonlinear or minimization 185 solver; hence iterations will continue until max_it 186 or some other criterion is reached. Saves expense 187 of convergence test 188 . -snes_monitor - prints residual norm at each iteration 189 . -snes_vecmonitor - plots solution at each iteration 190 . -snes_vecmonitor_update - plots update to solution at each iteration 191 . -snes_xmonitor - plots residual norm at each iteration 192 . -snes_fd - use finite differences to compute Jacobian; very slow, only for testing 193 - -snes_mf_ksp_monitor - if using matrix-free multiply then print h at each KSP iteration 194 195 Options Database for Eisenstat-Walker method: 196 + -snes_ksp_eq_conv - use Eisenstat-Walker method for determining linear system convergence 197 . -snes_ksp_eq_version ver - version of Eisenstat-Walker method 198 . -snes_ksp_ew_rtol0 <rtol0> - Sets rtol0 199 . -snes_ksp_ew_rtolmax <rtolmax> - Sets rtolmax 200 . -snes_ksp_ew_gamma <gamma> - Sets gamma 201 . -snes_ksp_ew_alpha <alpha> - Sets alpha 202 . -snes_ksp_ew_alpha2 <alpha2> - Sets alpha2 203 - -snes_ksp_ew_threshold <threshold> - Sets threshold 204 205 Notes: 206 To see all options, run your program with the -help option or consult 207 the users manual. 208 209 Level: beginner 210 211 .keywords: SNES, nonlinear, set, options, database 212 213 .seealso: SNESSetOptionsPrefix() 214 @*/ 215 int SNESSetFromOptions(SNES snes) 216 { 217 SLES sles; 218 SNES_KSP_EW_ConvCtx *kctx = (SNES_KSP_EW_ConvCtx *)snes->kspconvctx; 219 PetscTruth flg; 220 int ierr, i; 221 char *deft,type[256]; 222 223 PetscFunctionBegin; 224 PetscValidHeaderSpecific(snes,SNES_COOKIE); 225 226 ierr = PetscOptionsBegin(snes->comm,snes->prefix,"Nonlinear solver (SNES) options","SNES");CHKERRQ(ierr); 227 if (snes->type_name) { 228 deft = snes->type_name; 229 } else { 230 if (snes->method_class == SNES_NONLINEAR_EQUATIONS) { 231 deft = SNESEQLS; 232 } else { 233 deft = SNESUMTR; 234 } 235 } 236 237 if (!SNESRegisterAllCalled) {ierr = SNESRegisterAll(PETSC_NULL);CHKERRQ(ierr);} 238 ierr = PetscOptionsList("-snes_type","Nonlinear solver method","SNESSetType",SNESList,deft,type,256,&flg);CHKERRQ(ierr); 239 if (flg) { 240 ierr = SNESSetType(snes,type);CHKERRQ(ierr); 241 } else if (!snes->type_name) { 242 ierr = SNESSetType(snes,deft);CHKERRQ(ierr); 243 } 244 245 ierr = PetscOptionsReal("-snes_stol","Stop if step length less then","SNESSetTolerances",snes->xtol,&snes->xtol,0);CHKERRQ(ierr); 246 ierr = PetscOptionsReal("-snes_atol","Stop if function norm less then","SNESSetTolerances",snes->atol,&snes->atol,0);CHKERRQ(ierr); 247 248 ierr = PetscOptionsReal("-snes_rtol","Stop if decrease in function norm less then","SNESSetTolerances",snes->rtol,&snes->rtol,0);CHKERRQ(ierr); 249 ierr = PetscOptionsInt("-snes_max_it","Maximum iterations","SNESSetTolerances",snes->max_its,&snes->max_its,PETSC_NULL);CHKERRQ(ierr); 250 ierr = PetscOptionsInt("-snes_max_funcs","Maximum function evaluations","SNESSetTolerances",snes->max_funcs,&snes->max_funcs,PETSC_NULL);CHKERRQ(ierr); 251 ierr = PetscOptionsReal("-snes_fmin","Minimization function tolerance","SNESSetMinimizationFunctionTolerance",snes->fmin,&snes->fmin,0);CHKERRQ(ierr); 252 253 ierr = PetscOptionsName("-snes_ksp_ew_conv","Use Eisentat-Walker linear system convergence test","SNES_KSP_SetParametersEW",&snes->ksp_ewconv);CHKERRQ(ierr); 254 255 ierr = PetscOptionsInt("-snes_ksp_ew_version","Version 1 or 2","SNES_KSP_SetParametersEW",kctx->version,&kctx->version,0);CHKERRQ(ierr); 256 ierr = PetscOptionsReal("-snes_ksp_ew_rtol0","0 <= rtol0 < 1","SNES_KSP_SetParametersEW",kctx->rtol_0,&kctx->rtol_0,0);CHKERRQ(ierr); 257 ierr = PetscOptionsReal("-snes_ksp_ew_rtolmax","0 <= rtolmax < 1","SNES_KSP_SetParametersEW",kctx->rtol_max,&kctx->rtol_max,0);CHKERRQ(ierr); 258 ierr = PetscOptionsReal("-snes_ksp_ew_gamma","0 <= gamma <= 1","SNES_KSP_SetParametersEW",kctx->gamma,&kctx->gamma,0);CHKERRQ(ierr); 259 ierr = PetscOptionsReal("-snes_ksp_ew_alpha","1 < alpha <= 2","SNES_KSP_SetParametersEW",kctx->alpha,&kctx->alpha,0);CHKERRQ(ierr); 260 ierr = PetscOptionsReal("-snes_ksp_ew_alpha2","alpha2","SNES_KSP_SetParametersEW",kctx->alpha2,&kctx->alpha2,0);CHKERRQ(ierr); 261 ierr = PetscOptionsReal("-snes_ksp_ew_threshold","0 < threshold < 1","SNES_KSP_SetParametersEW",kctx->threshold,&kctx->threshold,0);CHKERRQ(ierr); 262 263 ierr = PetscOptionsName("-snes_no_convergence_test","Don't test for convergence","None",&flg);CHKERRQ(ierr); 264 if (flg) {snes->converged = 0;} 265 ierr = PetscOptionsName("-snes_cancelmonitors","Remove all monitors","SNESClearMonitor",&flg);CHKERRQ(ierr); 266 if (flg) {ierr = SNESClearMonitor(snes);CHKERRQ(ierr);} 267 ierr = PetscOptionsName("-snes_monitor","Monitor norm of function","SNESDefaultMonitor",&flg);CHKERRQ(ierr); 268 if (flg) {ierr = SNESSetMonitor(snes,SNESDefaultMonitor,0,0);CHKERRQ(ierr);} 269 ierr = PetscOptionsName("-snes_ratiomonitor","Monitor norm of function","SNESSetRatioMonitor",&flg);CHKERRQ(ierr); 270 if (flg) {ierr = SNESSetRatioMonitor(snes);CHKERRQ(ierr);} 271 ierr = PetscOptionsName("-snes_smonitor","Monitor norm of function (fewer digits)","SNESDefaultSMonitor",&flg);CHKERRQ(ierr); 272 if (flg) {ierr = SNESSetMonitor(snes,SNESDefaultSMonitor,0,0);CHKERRQ(ierr);} 273 ierr = PetscOptionsName("-snes_vecmonitor","Plot solution at each iteration","SNESVecViewMonitor",&flg);CHKERRQ(ierr); 274 if (flg) {ierr = SNESSetMonitor(snes,SNESVecViewMonitor,0,0);CHKERRQ(ierr);} 275 ierr = PetscOptionsName("-snes_vecmonitor_update","Plot correction at each iteration","SNESVecViewUpdateMonitor",&flg);CHKERRQ(ierr); 276 if (flg) {ierr = SNESSetMonitor(snes,SNESVecViewUpdateMonitor,0,0);CHKERRQ(ierr);} 277 ierr = PetscOptionsName("-snes_xmonitor","Plot function norm at each iteration","SNESLGMonitor",&flg);CHKERRQ(ierr); 278 if (flg) {ierr = SNESSetMonitor(snes,SNESLGMonitor,PETSC_NULL,PETSC_NULL);CHKERRQ(ierr);} 279 280 ierr = PetscOptionsName("-snes_fd","Use finite differences (slow) to compute Jacobian","SNESDefaultComputeJacobian",&flg);CHKERRQ(ierr); 281 if (flg && snes->method_class == SNES_NONLINEAR_EQUATIONS) { 282 ierr = SNESSetJacobian(snes,snes->jacobian,snes->jacobian_pre,SNESDefaultComputeJacobian,snes->funP);CHKERRQ(ierr); 283 PetscLogInfo(snes,"SNESSetFromOptions: Setting default finite difference Jacobian matrix\n"); 284 } else if (flg && snes->method_class == SNES_UNCONSTRAINED_MINIMIZATION) { 285 ierr = SNESSetHessian(snes,snes->jacobian,snes->jacobian_pre,SNESDefaultComputeHessian,snes->funP);CHKERRQ(ierr); 286 PetscLogInfo(snes,"SNESSetFromOptions: Setting default finite difference Hessian matrix\n"); 287 } 288 289 for(i = 0; i < numberofsetfromoptions; i++) { 290 ierr = (*othersetfromoptions[i])(snes); CHKERRQ(ierr); 291 } 292 293 if (snes->setfromoptions) { 294 ierr = (*snes->setfromoptions)(snes);CHKERRQ(ierr); 295 } 296 297 ierr = PetscOptionsEnd();CHKERRQ(ierr); 298 299 ierr = SNESGetSLES(snes,&sles);CHKERRQ(ierr); 300 ierr = SLESSetFromOptions(sles);CHKERRQ(ierr); 301 302 PetscFunctionReturn(0); 303 } 304 305 306 #undef __FUNCT__ 307 #define __FUNCT__ "SNESSetApplicationContext" 308 /*@ 309 SNESSetApplicationContext - Sets the optional user-defined context for 310 the nonlinear solvers. 311 312 Collective on SNES 313 314 Input Parameters: 315 + snes - the SNES context 316 - usrP - optional user context 317 318 Level: intermediate 319 320 .keywords: SNES, nonlinear, set, application, context 321 322 .seealso: SNESGetApplicationContext() 323 @*/ 324 int SNESSetApplicationContext(SNES snes,void *usrP) 325 { 326 PetscFunctionBegin; 327 PetscValidHeaderSpecific(snes,SNES_COOKIE); 328 snes->user = usrP; 329 PetscFunctionReturn(0); 330 } 331 332 #undef __FUNCT__ 333 #define __FUNCT__ "SNESGetApplicationContext" 334 /*@C 335 SNESGetApplicationContext - Gets the user-defined context for the 336 nonlinear solvers. 337 338 Not Collective 339 340 Input Parameter: 341 . snes - SNES context 342 343 Output Parameter: 344 . usrP - user context 345 346 Level: intermediate 347 348 .keywords: SNES, nonlinear, get, application, context 349 350 .seealso: SNESSetApplicationContext() 351 @*/ 352 int SNESGetApplicationContext(SNES snes,void **usrP) 353 { 354 PetscFunctionBegin; 355 PetscValidHeaderSpecific(snes,SNES_COOKIE); 356 *usrP = snes->user; 357 PetscFunctionReturn(0); 358 } 359 360 #undef __FUNCT__ 361 #define __FUNCT__ "SNESGetIterationNumber" 362 /*@ 363 SNESGetIterationNumber - Gets the number of nonlinear iterations completed 364 at this time. 365 366 Not Collective 367 368 Input Parameter: 369 . snes - SNES context 370 371 Output Parameter: 372 . iter - iteration number 373 374 Notes: 375 For example, during the computation of iteration 2 this would return 1. 376 377 This is useful for using lagged Jacobians (where one does not recompute the 378 Jacobian at each SNES iteration). For example, the code 379 .vb 380 ierr = SNESGetIterationNumber(snes,&it); 381 if (!(it % 2)) { 382 [compute Jacobian here] 383 } 384 .ve 385 can be used in your ComputeJacobian() function to cause the Jacobian to be 386 recomputed every second SNES iteration. 387 388 Level: intermediate 389 390 .keywords: SNES, nonlinear, get, iteration, number 391 @*/ 392 int SNESGetIterationNumber(SNES snes,int* iter) 393 { 394 PetscFunctionBegin; 395 PetscValidHeaderSpecific(snes,SNES_COOKIE); 396 PetscValidIntPointer(iter); 397 *iter = snes->iter; 398 PetscFunctionReturn(0); 399 } 400 401 #undef __FUNCT__ 402 #define __FUNCT__ "SNESGetFunctionNorm" 403 /*@ 404 SNESGetFunctionNorm - Gets the norm of the current function that was set 405 with SNESSSetFunction(). 406 407 Collective on SNES 408 409 Input Parameter: 410 . snes - SNES context 411 412 Output Parameter: 413 . fnorm - 2-norm of function 414 415 Note: 416 SNESGetFunctionNorm() is valid for SNES_NONLINEAR_EQUATIONS methods only. 417 A related routine for SNES_UNCONSTRAINED_MINIMIZATION methods is 418 SNESGetGradientNorm(). 419 420 Level: intermediate 421 422 .keywords: SNES, nonlinear, get, function, norm 423 424 .seealso: SNESGetFunction() 425 @*/ 426 int SNESGetFunctionNorm(SNES snes,PetscScalar *fnorm) 427 { 428 PetscFunctionBegin; 429 PetscValidHeaderSpecific(snes,SNES_COOKIE); 430 PetscValidScalarPointer(fnorm); 431 if (snes->method_class != SNES_NONLINEAR_EQUATIONS) { 432 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"For SNES_NONLINEAR_EQUATIONS only"); 433 } 434 *fnorm = snes->norm; 435 PetscFunctionReturn(0); 436 } 437 438 #undef __FUNCT__ 439 #define __FUNCT__ "SNESGetGradientNorm" 440 /*@ 441 SNESGetGradientNorm - Gets the norm of the current gradient that was set 442 with SNESSSetGradient(). 443 444 Collective on SNES 445 446 Input Parameter: 447 . snes - SNES context 448 449 Output Parameter: 450 . fnorm - 2-norm of gradient 451 452 Note: 453 SNESGetGradientNorm() is valid for SNES_UNCONSTRAINED_MINIMIZATION 454 methods only. A related routine for SNES_NONLINEAR_EQUATIONS methods 455 is SNESGetFunctionNorm(). 456 457 Level: intermediate 458 459 .keywords: SNES, nonlinear, get, gradient, norm 460 461 .seelso: SNESSetGradient() 462 @*/ 463 int SNESGetGradientNorm(SNES snes,PetscScalar *gnorm) 464 { 465 PetscFunctionBegin; 466 PetscValidHeaderSpecific(snes,SNES_COOKIE); 467 PetscValidScalarPointer(gnorm); 468 if (snes->method_class != SNES_UNCONSTRAINED_MINIMIZATION) { 469 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"For SNES_UNCONSTRAINED_MINIMIZATION only"); 470 } 471 *gnorm = snes->norm; 472 PetscFunctionReturn(0); 473 } 474 475 #undef __FUNCT__ 476 #define __FUNCT__ "SNESGetNumberUnsuccessfulSteps" 477 /*@ 478 SNESGetNumberUnsuccessfulSteps - Gets the number of unsuccessful steps 479 attempted by the nonlinear solver. 480 481 Not Collective 482 483 Input Parameter: 484 . snes - SNES context 485 486 Output Parameter: 487 . nfails - number of unsuccessful steps attempted 488 489 Notes: 490 This counter is reset to zero for each successive call to SNESSolve(). 491 492 Level: intermediate 493 494 .keywords: SNES, nonlinear, get, number, unsuccessful, steps 495 @*/ 496 int SNESGetNumberUnsuccessfulSteps(SNES snes,int* nfails) 497 { 498 PetscFunctionBegin; 499 PetscValidHeaderSpecific(snes,SNES_COOKIE); 500 PetscValidIntPointer(nfails); 501 *nfails = snes->nfailures; 502 PetscFunctionReturn(0); 503 } 504 505 #undef __FUNCT__ 506 #define __FUNCT__ "SNESGetNumberLinearIterations" 507 /*@ 508 SNESGetNumberLinearIterations - Gets the total number of linear iterations 509 used by the nonlinear solver. 510 511 Not Collective 512 513 Input Parameter: 514 . snes - SNES context 515 516 Output Parameter: 517 . lits - number of linear iterations 518 519 Notes: 520 This counter is reset to zero for each successive call to SNESSolve(). 521 522 Level: intermediate 523 524 .keywords: SNES, nonlinear, get, number, linear, iterations 525 @*/ 526 int SNESGetNumberLinearIterations(SNES snes,int* lits) 527 { 528 PetscFunctionBegin; 529 PetscValidHeaderSpecific(snes,SNES_COOKIE); 530 PetscValidIntPointer(lits); 531 *lits = snes->linear_its; 532 PetscFunctionReturn(0); 533 } 534 535 #undef __FUNCT__ 536 #define __FUNCT__ "SNESGetSLES" 537 /*@C 538 SNESGetSLES - Returns the SLES context for a SNES solver. 539 540 Not Collective, but if SNES object is parallel, then SLES object is parallel 541 542 Input Parameter: 543 . snes - the SNES context 544 545 Output Parameter: 546 . sles - the SLES context 547 548 Notes: 549 The user can then directly manipulate the SLES context to set various 550 options, etc. Likewise, the user can then extract and manipulate the 551 KSP and PC contexts as well. 552 553 Level: beginner 554 555 .keywords: SNES, nonlinear, get, SLES, context 556 557 .seealso: SLESGetPC(), SLESGetKSP() 558 @*/ 559 int SNESGetSLES(SNES snes,SLES *sles) 560 { 561 PetscFunctionBegin; 562 PetscValidHeaderSpecific(snes,SNES_COOKIE); 563 *sles = snes->sles; 564 PetscFunctionReturn(0); 565 } 566 567 #undef __FUNCT__ 568 #define __FUNCT__ "SNESPublish_Petsc" 569 static int SNESPublish_Petsc(PetscObject obj) 570 { 571 #if defined(PETSC_HAVE_AMS) 572 SNES v = (SNES) obj; 573 int ierr; 574 #endif 575 576 PetscFunctionBegin; 577 578 #if defined(PETSC_HAVE_AMS) 579 /* if it is already published then return */ 580 if (v->amem >=0) PetscFunctionReturn(0); 581 582 ierr = PetscObjectPublishBaseBegin(obj);CHKERRQ(ierr); 583 ierr = AMS_Memory_add_field((AMS_Memory)v->amem,"Iteration",&v->iter,1,AMS_INT,AMS_READ, 584 AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRQ(ierr); 585 ierr = AMS_Memory_add_field((AMS_Memory)v->amem,"Residual",&v->norm,1,AMS_DOUBLE,AMS_READ, 586 AMS_COMMON,AMS_REDUCT_UNDEF);CHKERRQ(ierr); 587 ierr = PetscObjectPublishBaseEnd(obj);CHKERRQ(ierr); 588 #endif 589 PetscFunctionReturn(0); 590 } 591 592 /* -----------------------------------------------------------*/ 593 #undef __FUNCT__ 594 #define __FUNCT__ "SNESCreate" 595 /*@C 596 SNESCreate - Creates a nonlinear solver context. 597 598 Collective on MPI_Comm 599 600 Input Parameters: 601 + comm - MPI communicator 602 - type - type of method, either 603 SNES_NONLINEAR_EQUATIONS (for systems of nonlinear equations) 604 or SNES_UNCONSTRAINED_MINIMIZATION (for unconstrained minimization) 605 606 Output Parameter: 607 . outsnes - the new SNES context 608 609 Options Database Keys: 610 + -snes_mf - Activates default matrix-free Jacobian-vector products, 611 and no preconditioning matrix 612 . -snes_mf_operator - Activates default matrix-free Jacobian-vector 613 products, and a user-provided preconditioning matrix 614 as set by SNESSetJacobian() 615 - -snes_fd - Uses (slow!) finite differences to compute Jacobian 616 617 Level: beginner 618 619 .keywords: SNES, nonlinear, create, context 620 621 .seealso: SNESSolve(), SNESDestroy(), SNESProblemType, SNES 622 @*/ 623 int SNESCreate(MPI_Comm comm,SNESProblemType type,SNES *outsnes) 624 { 625 int ierr; 626 SNES snes; 627 SNES_KSP_EW_ConvCtx *kctx; 628 629 PetscFunctionBegin; 630 PetscValidPointer(outsnes); 631 *outsnes = PETSC_NULL; 632 #ifndef PETSC_USE_DYNAMIC_LIBRARIES 633 ierr = SNESInitializePackage(PETSC_NULL); CHKERRQ(ierr); 634 #endif 635 636 if (type != SNES_UNCONSTRAINED_MINIMIZATION && type != SNES_NONLINEAR_EQUATIONS){ 637 SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"incorrect method type"); 638 } 639 PetscHeaderCreate(snes,_p_SNES,int,SNES_COOKIE,0,"SNES",comm,SNESDestroy,SNESView); 640 PetscLogObjectCreate(snes); 641 snes->bops->publish = SNESPublish_Petsc; 642 snes->max_its = 50; 643 snes->max_funcs = 10000; 644 snes->norm = 0.0; 645 if (type == SNES_UNCONSTRAINED_MINIMIZATION) { 646 snes->rtol = 1.e-8; 647 snes->ttol = 0.0; 648 snes->atol = 1.e-10; 649 } else { 650 snes->rtol = 1.e-8; 651 snes->ttol = 0.0; 652 snes->atol = 1.e-50; 653 } 654 snes->xtol = 1.e-8; 655 snes->nfuncs = 0; 656 snes->nfailures = 0; 657 snes->linear_its = 0; 658 snes->numbermonitors = 0; 659 snes->data = 0; 660 snes->view = 0; 661 snes->computeumfunction = 0; 662 snes->umfunP = 0; 663 snes->fc = 0; 664 snes->deltatol = 1.e-12; 665 snes->fmin = -1.e30; 666 snes->method_class = type; 667 snes->set_method_called = 0; 668 snes->setupcalled = 0; 669 snes->ksp_ewconv = PETSC_FALSE; 670 snes->vwork = 0; 671 snes->nwork = 0; 672 snes->conv_hist_len = 0; 673 snes->conv_hist_max = 0; 674 snes->conv_hist = PETSC_NULL; 675 snes->conv_hist_its = PETSC_NULL; 676 snes->conv_hist_reset = PETSC_TRUE; 677 snes->reason = SNES_CONVERGED_ITERATING; 678 679 /* Create context to compute Eisenstat-Walker relative tolerance for KSP */ 680 ierr = PetscNew(SNES_KSP_EW_ConvCtx,&kctx);CHKERRQ(ierr); 681 PetscLogObjectMemory(snes,sizeof(SNES_KSP_EW_ConvCtx)); 682 snes->kspconvctx = (void*)kctx; 683 kctx->version = 2; 684 kctx->rtol_0 = .3; /* Eisenstat and Walker suggest rtol_0=.5, but 685 this was too large for some test cases */ 686 kctx->rtol_last = 0; 687 kctx->rtol_max = .9; 688 kctx->gamma = 1.0; 689 kctx->alpha2 = .5*(1.0 + sqrt(5.0)); 690 kctx->alpha = kctx->alpha2; 691 kctx->threshold = .1; 692 kctx->lresid_last = 0; 693 kctx->norm_last = 0; 694 695 ierr = SLESCreate(comm,&snes->sles);CHKERRQ(ierr); 696 PetscLogObjectParent(snes,snes->sles) 697 698 *outsnes = snes; 699 ierr = PetscPublishAll(snes);CHKERRQ(ierr); 700 PetscFunctionReturn(0); 701 } 702 703 /* --------------------------------------------------------------- */ 704 #undef __FUNCT__ 705 #define __FUNCT__ "SNESSetFunction" 706 /*@C 707 SNESSetFunction - Sets the function evaluation routine and function 708 vector for use by the SNES routines in solving systems of nonlinear 709 equations. 710 711 Collective on SNES 712 713 Input Parameters: 714 + snes - the SNES context 715 . func - function evaluation routine 716 . r - vector to store function value 717 - ctx - [optional] user-defined context for private data for the 718 function evaluation routine (may be PETSC_NULL) 719 720 Calling sequence of func: 721 $ func (SNES snes,Vec x,Vec f,void *ctx); 722 723 . f - function vector 724 - ctx - optional user-defined function context 725 726 Notes: 727 The Newton-like methods typically solve linear systems of the form 728 $ f'(x) x = -f(x), 729 where f'(x) denotes the Jacobian matrix and f(x) is the function. 730 731 SNESSetFunction() is valid for SNES_NONLINEAR_EQUATIONS methods only. 732 Analogous routines for SNES_UNCONSTRAINED_MINIMIZATION methods are 733 SNESSetMinimizationFunction() and SNESSetGradient(); 734 735 Level: beginner 736 737 .keywords: SNES, nonlinear, set, function 738 739 .seealso: SNESGetFunction(), SNESComputeFunction(), SNESSetJacobian() 740 @*/ 741 int SNESSetFunction(SNES snes,Vec r,int (*func)(SNES,Vec,Vec,void*),void *ctx) 742 { 743 PetscFunctionBegin; 744 PetscValidHeaderSpecific(snes,SNES_COOKIE); 745 PetscValidHeaderSpecific(r,VEC_COOKIE); 746 PetscCheckSameComm(snes,r); 747 if (snes->method_class != SNES_NONLINEAR_EQUATIONS) { 748 SETERRQ(PETSC_ERR_ARG_WRONG,"For SNES_NONLINEAR_EQUATIONS only"); 749 } 750 751 snes->computefunction = func; 752 snes->vec_func = snes->vec_func_always = r; 753 snes->funP = ctx; 754 PetscFunctionReturn(0); 755 } 756 757 #undef __FUNCT__ 758 #define __FUNCT__ "SNESComputeFunction" 759 /*@ 760 SNESComputeFunction - Calls the function that has been set with 761 SNESSetFunction(). 762 763 Collective on SNES 764 765 Input Parameters: 766 + snes - the SNES context 767 - x - input vector 768 769 Output Parameter: 770 . y - function vector, as set by SNESSetFunction() 771 772 Notes: 773 SNESComputeFunction() is valid for SNES_NONLINEAR_EQUATIONS methods only. 774 Analogous routines for SNES_UNCONSTRAINED_MINIMIZATION methods are 775 SNESComputeMinimizationFunction() and SNESComputeGradient(); 776 777 SNESComputeFunction() is typically used within nonlinear solvers 778 implementations, so most users would not generally call this routine 779 themselves. 780 781 Level: developer 782 783 .keywords: SNES, nonlinear, compute, function 784 785 .seealso: SNESSetFunction(), SNESGetFunction() 786 @*/ 787 int SNESComputeFunction(SNES snes,Vec x,Vec y) 788 { 789 int ierr; 790 791 PetscFunctionBegin; 792 PetscValidHeaderSpecific(snes,SNES_COOKIE); 793 PetscValidHeaderSpecific(x,VEC_COOKIE); 794 PetscValidHeaderSpecific(y,VEC_COOKIE); 795 PetscCheckSameComm(snes,x); 796 PetscCheckSameComm(snes,y); 797 if (snes->method_class != SNES_NONLINEAR_EQUATIONS) { 798 SETERRQ(PETSC_ERR_ARG_WRONG,"For SNES_NONLINEAR_EQUATIONS only"); 799 } 800 801 ierr = SNESLogEventBegin(SNES_FunctionEval,snes,x,y,0);CHKERRQ(ierr); 802 PetscStackPush("SNES user function"); 803 ierr = (*snes->computefunction)(snes,x,y,snes->funP);CHKERRQ(ierr); 804 PetscStackPop; 805 snes->nfuncs++; 806 ierr = SNESLogEventEnd(SNES_FunctionEval,snes,x,y,0);CHKERRQ(ierr); 807 PetscFunctionReturn(0); 808 } 809 810 #undef __FUNCT__ 811 #define __FUNCT__ "SNESSetMinimizationFunction" 812 /*@C 813 SNESSetMinimizationFunction - Sets the function evaluation routine for 814 unconstrained minimization. 815 816 Collective on SNES 817 818 Input Parameters: 819 + snes - the SNES context 820 . func - function evaluation routine 821 - ctx - [optional] user-defined context for private data for the 822 function evaluation routine (may be PETSC_NULL) 823 824 Calling sequence of func: 825 $ func (SNES snes,Vec x,PetscReal *f,void *ctx); 826 827 + x - input vector 828 . f - function 829 - ctx - [optional] user-defined function context 830 831 Level: beginner 832 833 Notes: 834 SNESSetMinimizationFunction() is valid for SNES_UNCONSTRAINED_MINIMIZATION 835 methods only. An analogous routine for SNES_NONLINEAR_EQUATIONS methods is 836 SNESSetFunction(). 837 838 .keywords: SNES, nonlinear, set, minimization, function 839 840 .seealso: SNESGetMinimizationFunction(), SNESComputeMinimizationFunction(), 841 SNESSetHessian(), SNESSetGradient() 842 @*/ 843 int SNESSetMinimizationFunction(SNES snes,int (*func)(SNES,Vec,PetscReal*,void*),void *ctx) 844 { 845 PetscFunctionBegin; 846 PetscValidHeaderSpecific(snes,SNES_COOKIE); 847 if (snes->method_class != SNES_UNCONSTRAINED_MINIMIZATION) { 848 SETERRQ(PETSC_ERR_ARG_WRONG,"Only for SNES_UNCONSTRAINED_MINIMIZATION"); 849 } 850 snes->computeumfunction = func; 851 snes->umfunP = ctx; 852 PetscFunctionReturn(0); 853 } 854 855 #undef __FUNCT__ 856 #define __FUNCT__ "SNESComputeMinimizationFunction" 857 /*@ 858 SNESComputeMinimizationFunction - Computes the function that has been 859 set with SNESSetMinimizationFunction(). 860 861 Collective on SNES 862 863 Input Parameters: 864 + snes - the SNES context 865 - x - input vector 866 867 Output Parameter: 868 . y - function value 869 870 Notes: 871 SNESComputeMinimizationFunction() is valid only for 872 SNES_UNCONSTRAINED_MINIMIZATION methods. An analogous routine for 873 SNES_NONLINEAR_EQUATIONS methods is SNESComputeFunction(). 874 875 SNESComputeMinimizationFunction() is typically used within minimization 876 implementations, so most users would not generally call this routine 877 themselves. 878 879 Level: developer 880 881 .keywords: SNES, nonlinear, compute, minimization, function 882 883 .seealso: SNESSetMinimizationFunction(), SNESGetMinimizationFunction(), 884 SNESComputeGradient(), SNESComputeHessian() 885 @*/ 886 int SNESComputeMinimizationFunction(SNES snes,Vec x,PetscReal *y) 887 { 888 int ierr; 889 890 PetscFunctionBegin; 891 PetscValidHeaderSpecific(snes,SNES_COOKIE); 892 PetscValidHeaderSpecific(x,VEC_COOKIE); 893 PetscCheckSameComm(snes,x); 894 if (snes->method_class != SNES_UNCONSTRAINED_MINIMIZATION) { 895 SETERRQ(PETSC_ERR_ARG_WRONG,"Only for SNES_UNCONSTRAINED_MINIMIZATION"); 896 } 897 898 ierr = SNESLogEventBegin(SNES_MinimizationFunctionEval,snes,x,y,0);CHKERRQ(ierr); 899 PetscStackPush("SNES user minimzation function"); 900 ierr = (*snes->computeumfunction)(snes,x,y,snes->umfunP);CHKERRQ(ierr); 901 PetscStackPop; 902 snes->nfuncs++; 903 ierr = SNESLogEventEnd(SNES_MinimizationFunctionEval,snes,x,y,0);CHKERRQ(ierr); 904 PetscFunctionReturn(0); 905 } 906 907 #undef __FUNCT__ 908 #define __FUNCT__ "SNESSetGradient" 909 /*@C 910 SNESSetGradient - Sets the gradient evaluation routine and gradient 911 vector for use by the SNES routines. 912 913 Collective on SNES 914 915 Input Parameters: 916 + snes - the SNES context 917 . func - function evaluation routine 918 . ctx - optional user-defined context for private data for the 919 gradient evaluation routine (may be PETSC_NULL) 920 - r - vector to store gradient value 921 922 Calling sequence of func: 923 $ func (SNES, Vec x, Vec g, void *ctx); 924 925 + x - input vector 926 . g - gradient vector 927 - ctx - optional user-defined gradient context 928 929 Notes: 930 SNESSetMinimizationFunction() is valid for SNES_UNCONSTRAINED_MINIMIZATION 931 methods only. An analogous routine for SNES_NONLINEAR_EQUATIONS methods is 932 SNESSetFunction(). 933 934 Level: beginner 935 936 .keywords: SNES, nonlinear, set, function 937 938 .seealso: SNESGetGradient(), SNESComputeGradient(), SNESSetHessian(), 939 SNESSetMinimizationFunction(), 940 @*/ 941 int SNESSetGradient(SNES snes,Vec r,int (*func)(SNES,Vec,Vec,void*),void *ctx) 942 { 943 PetscFunctionBegin; 944 PetscValidHeaderSpecific(snes,SNES_COOKIE); 945 PetscValidHeaderSpecific(r,VEC_COOKIE); 946 PetscCheckSameComm(snes,r); 947 if (snes->method_class != SNES_UNCONSTRAINED_MINIMIZATION) { 948 SETERRQ(PETSC_ERR_ARG_WRONG,"For SNES_UNCONSTRAINED_MINIMIZATION only"); 949 } 950 snes->computefunction = func; 951 snes->vec_func = snes->vec_func_always = r; 952 snes->funP = ctx; 953 PetscFunctionReturn(0); 954 } 955 956 #undef __FUNCT__ 957 #define __FUNCT__ "SNESComputeGradient" 958 /*@ 959 SNESComputeGradient - Computes the gradient that has been set with 960 SNESSetGradient(). 961 962 Collective on SNES 963 964 Input Parameters: 965 + snes - the SNES context 966 - x - input vector 967 968 Output Parameter: 969 . y - gradient vector 970 971 Notes: 972 SNESComputeGradient() is valid only for 973 SNES_UNCONSTRAINED_MINIMIZATION methods. An analogous routine for 974 SNES_NONLINEAR_EQUATIONS methods is SNESComputeFunction(). 975 976 SNESComputeGradient() is typically used within minimization 977 implementations, so most users would not generally call this routine 978 themselves. 979 980 Level: developer 981 982 .keywords: SNES, nonlinear, compute, gradient 983 984 .seealso: SNESSetGradient(), SNESGetGradient(), 985 SNESComputeMinimizationFunction(), SNESComputeHessian() 986 @*/ 987 int SNESComputeGradient(SNES snes,Vec x,Vec y) 988 { 989 int ierr; 990 991 PetscFunctionBegin; 992 PetscValidHeaderSpecific(snes,SNES_COOKIE); 993 PetscValidHeaderSpecific(x,VEC_COOKIE); 994 PetscValidHeaderSpecific(y,VEC_COOKIE); 995 PetscCheckSameComm(snes,x); 996 PetscCheckSameComm(snes,y); 997 if (snes->method_class != SNES_UNCONSTRAINED_MINIMIZATION) { 998 SETERRQ(PETSC_ERR_ARG_WRONG,"For SNES_UNCONSTRAINED_MINIMIZATION only"); 999 } 1000 ierr = SNESLogEventBegin(SNES_GradientEval,snes,x,y,0);CHKERRQ(ierr); 1001 PetscStackPush("SNES user gradient function"); 1002 ierr = (*snes->computefunction)(snes,x,y,snes->funP);CHKERRQ(ierr); 1003 PetscStackPop; 1004 ierr = SNESLogEventEnd(SNES_GradientEval,snes,x,y,0);CHKERRQ(ierr); 1005 PetscFunctionReturn(0); 1006 } 1007 1008 #undef __FUNCT__ 1009 #define __FUNCT__ "SNESComputeJacobian" 1010 /*@ 1011 SNESComputeJacobian - Computes the Jacobian matrix that has been 1012 set with SNESSetJacobian(). 1013 1014 Collective on SNES and Mat 1015 1016 Input Parameters: 1017 + snes - the SNES context 1018 - x - input vector 1019 1020 Output Parameters: 1021 + A - Jacobian matrix 1022 . B - optional preconditioning matrix 1023 - flag - flag indicating matrix structure 1024 1025 Notes: 1026 Most users should not need to explicitly call this routine, as it 1027 is used internally within the nonlinear solvers. 1028 1029 See SLESSetOperators() for important information about setting the 1030 flag parameter. 1031 1032 SNESComputeJacobian() is valid only for SNES_NONLINEAR_EQUATIONS 1033 methods. An analogous routine for SNES_UNCONSTRAINED_MINIMIZATION 1034 methods is SNESComputeHessian(). 1035 1036 Level: developer 1037 1038 .keywords: SNES, compute, Jacobian, matrix 1039 1040 .seealso: SNESSetJacobian(), SLESSetOperators() 1041 @*/ 1042 int SNESComputeJacobian(SNES snes,Vec X,Mat *A,Mat *B,MatStructure *flg) 1043 { 1044 int ierr; 1045 1046 PetscFunctionBegin; 1047 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1048 PetscValidHeaderSpecific(X,VEC_COOKIE); 1049 PetscCheckSameComm(snes,X); 1050 if (snes->method_class != SNES_NONLINEAR_EQUATIONS) { 1051 SETERRQ(PETSC_ERR_ARG_WRONG,"For SNES_NONLINEAR_EQUATIONS only"); 1052 } 1053 if (!snes->computejacobian) PetscFunctionReturn(0); 1054 ierr = SNESLogEventBegin(SNES_JacobianEval,snes,X,*A,*B);CHKERRQ(ierr); 1055 *flg = DIFFERENT_NONZERO_PATTERN; 1056 PetscStackPush("SNES user Jacobian function"); 1057 ierr = (*snes->computejacobian)(snes,X,A,B,flg,snes->jacP);CHKERRQ(ierr); 1058 PetscStackPop; 1059 ierr = SNESLogEventEnd(SNES_JacobianEval,snes,X,*A,*B);CHKERRQ(ierr); 1060 /* make sure user returned a correct Jacobian and preconditioner */ 1061 PetscValidHeaderSpecific(*A,MAT_COOKIE); 1062 PetscValidHeaderSpecific(*B,MAT_COOKIE); 1063 PetscFunctionReturn(0); 1064 } 1065 1066 #undef __FUNCT__ 1067 #define __FUNCT__ "SNESComputeHessian" 1068 /*@ 1069 SNESComputeHessian - Computes the Hessian matrix that has been 1070 set with SNESSetHessian(). 1071 1072 Collective on SNES and Mat 1073 1074 Input Parameters: 1075 + snes - the SNES context 1076 - x - input vector 1077 1078 Output Parameters: 1079 + A - Hessian matrix 1080 . B - optional preconditioning matrix 1081 - flag - flag indicating matrix structure 1082 1083 Notes: 1084 Most users should not need to explicitly call this routine, as it 1085 is used internally within the nonlinear solvers. 1086 1087 See SLESSetOperators() for important information about setting the 1088 flag parameter. 1089 1090 SNESComputeHessian() is valid only for 1091 SNES_UNCONSTRAINED_MINIMIZATION methods. An analogous routine for 1092 SNES_NONLINEAR_EQUATIONS methods is SNESComputeJacobian(). 1093 1094 SNESComputeHessian() is typically used within minimization 1095 implementations, so most users would not generally call this routine 1096 themselves. 1097 1098 Level: developer 1099 1100 .keywords: SNES, compute, Hessian, matrix 1101 1102 .seealso: SNESSetHessian(), SLESSetOperators(), SNESComputeGradient(), 1103 SNESComputeMinimizationFunction() 1104 @*/ 1105 int SNESComputeHessian(SNES snes,Vec x,Mat *A,Mat *B,MatStructure *flag) 1106 { 1107 int ierr; 1108 1109 PetscFunctionBegin; 1110 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1111 PetscValidHeaderSpecific(x,VEC_COOKIE); 1112 PetscCheckSameComm(snes,x); 1113 if (snes->method_class != SNES_UNCONSTRAINED_MINIMIZATION) { 1114 SETERRQ(PETSC_ERR_ARG_WRONG,"For SNES_UNCONSTRAINED_MINIMIZATION only"); 1115 } 1116 if (!snes->computejacobian) PetscFunctionReturn(0); 1117 ierr = SNESLogEventBegin(SNES_HessianEval,snes,x,*A,*B);CHKERRQ(ierr); 1118 *flag = DIFFERENT_NONZERO_PATTERN; 1119 PetscStackPush("SNES user Hessian function"); 1120 ierr = (*snes->computejacobian)(snes,x,A,B,flag,snes->jacP);CHKERRQ(ierr); 1121 PetscStackPop; 1122 ierr = SNESLogEventEnd(SNES_HessianEval,snes,x,*A,*B);CHKERRQ(ierr); 1123 /* make sure user returned a correct Jacobian and preconditioner */ 1124 PetscValidHeaderSpecific(*A,MAT_COOKIE); 1125 PetscValidHeaderSpecific(*B,MAT_COOKIE); 1126 PetscFunctionReturn(0); 1127 } 1128 1129 #undef __FUNCT__ 1130 #define __FUNCT__ "SNESSetJacobian" 1131 /*@C 1132 SNESSetJacobian - Sets the function to compute Jacobian as well as the 1133 location to store the matrix. 1134 1135 Collective on SNES and Mat 1136 1137 Input Parameters: 1138 + snes - the SNES context 1139 . A - Jacobian matrix 1140 . B - preconditioner matrix (usually same as the Jacobian) 1141 . func - Jacobian evaluation routine 1142 - ctx - [optional] user-defined context for private data for the 1143 Jacobian evaluation routine (may be PETSC_NULL) 1144 1145 Calling sequence of func: 1146 $ func (SNES snes,Vec x,Mat *A,Mat *B,int *flag,void *ctx); 1147 1148 + x - input vector 1149 . A - Jacobian matrix 1150 . B - preconditioner matrix, usually the same as A 1151 . flag - flag indicating information about the preconditioner matrix 1152 structure (same as flag in SLESSetOperators()) 1153 - ctx - [optional] user-defined Jacobian context 1154 1155 Notes: 1156 See SLESSetOperators() for important information about setting the flag 1157 output parameter in the routine func(). Be sure to read this information! 1158 1159 The routine func() takes Mat * as the matrix arguments rather than Mat. 1160 This allows the Jacobian evaluation routine to replace A and/or B with a 1161 completely new new matrix structure (not just different matrix elements) 1162 when appropriate, for instance, if the nonzero structure is changing 1163 throughout the global iterations. 1164 1165 Level: beginner 1166 1167 .keywords: SNES, nonlinear, set, Jacobian, matrix 1168 1169 .seealso: SLESSetOperators(), SNESSetFunction() 1170 @*/ 1171 int SNESSetJacobian(SNES snes,Mat A,Mat B,int (*func)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *ctx) 1172 { 1173 int ierr; 1174 1175 PetscFunctionBegin; 1176 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1177 if (A) PetscValidHeaderSpecific(A,MAT_COOKIE); 1178 if (B) PetscValidHeaderSpecific(B,MAT_COOKIE); 1179 if (A) PetscCheckSameComm(snes,A); 1180 if (B) PetscCheckSameComm(snes,B); 1181 if (snes->method_class != SNES_NONLINEAR_EQUATIONS) { 1182 SETERRQ(PETSC_ERR_ARG_WRONG,"For SNES_NONLINEAR_EQUATIONS only"); 1183 } 1184 1185 if (func) snes->computejacobian = func; 1186 if (ctx) snes->jacP = ctx; 1187 if (A) { 1188 if (snes->jacobian) {ierr = MatDestroy(snes->jacobian);CHKERRQ(ierr);} 1189 snes->jacobian = A; 1190 ierr = PetscObjectReference((PetscObject)A);CHKERRQ(ierr); 1191 } 1192 if (B) { 1193 if (snes->jacobian_pre) {ierr = MatDestroy(snes->jacobian_pre);CHKERRQ(ierr);} 1194 snes->jacobian_pre = B; 1195 ierr = PetscObjectReference((PetscObject)B);CHKERRQ(ierr); 1196 } 1197 PetscFunctionReturn(0); 1198 } 1199 1200 #undef __FUNCT__ 1201 #define __FUNCT__ "SNESGetJacobian" 1202 /*@C 1203 SNESGetJacobian - Returns the Jacobian matrix and optionally the user 1204 provided context for evaluating the Jacobian. 1205 1206 Not Collective, but Mat object will be parallel if SNES object is 1207 1208 Input Parameter: 1209 . snes - the nonlinear solver context 1210 1211 Output Parameters: 1212 + A - location to stash Jacobian matrix (or PETSC_NULL) 1213 . B - location to stash preconditioner matrix (or PETSC_NULL) 1214 . ctx - location to stash Jacobian ctx (or PETSC_NULL) 1215 - func - location to put Jacobian function (or PETSC_NULL) 1216 1217 Level: advanced 1218 1219 .seealso: SNESSetJacobian(), SNESComputeJacobian() 1220 @*/ 1221 int SNESGetJacobian(SNES snes,Mat *A,Mat *B,void **ctx,int (**func)(SNES,Vec,Mat*,Mat*,MatStructure*,void*)) 1222 { 1223 PetscFunctionBegin; 1224 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1225 if (snes->method_class != SNES_NONLINEAR_EQUATIONS) { 1226 SETERRQ(PETSC_ERR_ARG_WRONG,"For SNES_NONLINEAR_EQUATIONS only"); 1227 } 1228 if (A) *A = snes->jacobian; 1229 if (B) *B = snes->jacobian_pre; 1230 if (ctx) *ctx = snes->jacP; 1231 if (func) *func = snes->computejacobian; 1232 PetscFunctionReturn(0); 1233 } 1234 1235 #undef __FUNCT__ 1236 #define __FUNCT__ "SNESSetHessian" 1237 /*@C 1238 SNESSetHessian - Sets the function to compute Hessian as well as the 1239 location to store the matrix. 1240 1241 Collective on SNES and Mat 1242 1243 Input Parameters: 1244 + snes - the SNES context 1245 . A - Hessian matrix 1246 . B - preconditioner matrix (usually same as the Hessian) 1247 . func - Jacobian evaluation routine 1248 - ctx - [optional] user-defined context for private data for the 1249 Hessian evaluation routine (may be PETSC_NULL) 1250 1251 Calling sequence of func: 1252 $ func (SNES snes,Vec x,Mat *A,Mat *B,int *flag,void *ctx); 1253 1254 + x - input vector 1255 . A - Hessian matrix 1256 . B - preconditioner matrix, usually the same as A 1257 . flag - flag indicating information about the preconditioner matrix 1258 structure (same as flag in SLESSetOperators()) 1259 - ctx - [optional] user-defined Hessian context 1260 1261 Notes: 1262 See SLESSetOperators() for important information about setting the flag 1263 output parameter in the routine func(). Be sure to read this information! 1264 1265 The function func() takes Mat * as the matrix arguments rather than Mat. 1266 This allows the Hessian evaluation routine to replace A and/or B with a 1267 completely new new matrix structure (not just different matrix elements) 1268 when appropriate, for instance, if the nonzero structure is changing 1269 throughout the global iterations. 1270 1271 Level: beginner 1272 1273 .keywords: SNES, nonlinear, set, Hessian, matrix 1274 1275 .seealso: SNESSetMinimizationFunction(), SNESSetGradient(), SLESSetOperators() 1276 @*/ 1277 int SNESSetHessian(SNES snes,Mat A,Mat B,int (*func)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *ctx) 1278 { 1279 int ierr; 1280 1281 PetscFunctionBegin; 1282 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1283 PetscValidHeaderSpecific(A,MAT_COOKIE); 1284 PetscValidHeaderSpecific(B,MAT_COOKIE); 1285 PetscCheckSameComm(snes,A); 1286 PetscCheckSameComm(snes,B); 1287 if (snes->method_class != SNES_UNCONSTRAINED_MINIMIZATION) { 1288 SETERRQ(PETSC_ERR_ARG_WRONG,"For SNES_UNCONSTRAINED_MINIMIZATION only"); 1289 } 1290 if (func) snes->computejacobian = func; 1291 if (ctx) snes->jacP = ctx; 1292 if (A) { 1293 if (snes->jacobian) {ierr = MatDestroy(snes->jacobian);CHKERRQ(ierr);} 1294 snes->jacobian = A; 1295 ierr = PetscObjectReference((PetscObject)A);CHKERRQ(ierr); 1296 } 1297 if (B) { 1298 if (snes->jacobian_pre) {ierr = MatDestroy(snes->jacobian_pre);CHKERRQ(ierr);} 1299 snes->jacobian_pre = B; 1300 ierr = PetscObjectReference((PetscObject)B);CHKERRQ(ierr); 1301 } 1302 PetscFunctionReturn(0); 1303 } 1304 1305 #undef __FUNCT__ 1306 #define __FUNCT__ "SNESGetHessian" 1307 /*@ 1308 SNESGetHessian - Returns the Hessian matrix and optionally the user 1309 provided context for evaluating the Hessian. 1310 1311 Not Collective, but Mat object is parallel if SNES object is parallel 1312 1313 Input Parameter: 1314 . snes - the nonlinear solver context 1315 1316 Output Parameters: 1317 + A - location to stash Hessian matrix (or PETSC_NULL) 1318 . B - location to stash preconditioner matrix (or PETSC_NULL) 1319 - ctx - location to stash Hessian ctx (or PETSC_NULL) 1320 1321 Level: advanced 1322 1323 .seealso: SNESSetHessian(), SNESComputeHessian() 1324 1325 .keywords: SNES, get, Hessian 1326 @*/ 1327 int SNESGetHessian(SNES snes,Mat *A,Mat *B,void **ctx) 1328 { 1329 PetscFunctionBegin; 1330 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1331 if (snes->method_class != SNES_UNCONSTRAINED_MINIMIZATION){ 1332 SETERRQ(PETSC_ERR_ARG_WRONG,"For SNES_UNCONSTRAINED_MINIMIZATION only"); 1333 } 1334 if (A) *A = snes->jacobian; 1335 if (B) *B = snes->jacobian_pre; 1336 if (ctx) *ctx = snes->jacP; 1337 PetscFunctionReturn(0); 1338 } 1339 1340 /* ----- Routines to initialize and destroy a nonlinear solver ---- */ 1341 1342 #undef __FUNCT__ 1343 #define __FUNCT__ "SNESSetUp" 1344 /*@ 1345 SNESSetUp - Sets up the internal data structures for the later use 1346 of a nonlinear solver. 1347 1348 Collective on SNES 1349 1350 Input Parameters: 1351 + snes - the SNES context 1352 - x - the solution vector 1353 1354 Notes: 1355 For basic use of the SNES solvers the user need not explicitly call 1356 SNESSetUp(), since these actions will automatically occur during 1357 the call to SNESSolve(). However, if one wishes to control this 1358 phase separately, SNESSetUp() should be called after SNESCreate() 1359 and optional routines of the form SNESSetXXX(), but before SNESSolve(). 1360 1361 Level: advanced 1362 1363 .keywords: SNES, nonlinear, setup 1364 1365 .seealso: SNESCreate(), SNESSolve(), SNESDestroy() 1366 @*/ 1367 int SNESSetUp(SNES snes,Vec x) 1368 { 1369 int ierr; 1370 PetscTruth flg; 1371 1372 PetscFunctionBegin; 1373 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1374 PetscValidHeaderSpecific(x,VEC_COOKIE); 1375 PetscCheckSameComm(snes,x); 1376 snes->vec_sol = snes->vec_sol_always = x; 1377 1378 ierr = PetscOptionsHasName(snes->prefix,"-snes_mf_operator",&flg);CHKERRQ(ierr); 1379 /* 1380 This version replaces the user provided Jacobian matrix with a 1381 matrix-free version but still employs the user-provided preconditioner matrix 1382 */ 1383 if (flg) { 1384 Mat J; 1385 ierr = MatCreateSNESMF(snes,snes->vec_sol,&J);CHKERRQ(ierr); 1386 ierr = MatSNESMFSetFromOptions(J);CHKERRQ(ierr); 1387 PetscLogInfo(snes,"SNESSetUp: Setting default matrix-free operator routines\n"); 1388 ierr = SNESSetJacobian(snes,J,0,0,0);CHKERRQ(ierr); 1389 ierr = MatDestroy(J);CHKERRQ(ierr); 1390 } 1391 ierr = PetscOptionsHasName(snes->prefix,"-snes_mf",&flg);CHKERRQ(ierr); 1392 /* 1393 This version replaces both the user-provided Jacobian and the user- 1394 provided preconditioner matrix with the default matrix free version. 1395 */ 1396 if (flg) { 1397 Mat J; 1398 SLES sles; 1399 PC pc; 1400 1401 ierr = MatCreateSNESMF(snes,snes->vec_sol,&J);CHKERRQ(ierr); 1402 ierr = MatSNESMFSetFromOptions(J);CHKERRQ(ierr); 1403 PetscLogInfo(snes,"SNESSetUp: Setting default matrix-free operator and preconditioner routines\n"); 1404 if (snes->method_class == SNES_NONLINEAR_EQUATIONS) { 1405 ierr = SNESSetJacobian(snes,J,J,MatSNESMFComputeJacobian,snes->funP);CHKERRQ(ierr); 1406 } else if (snes->method_class == SNES_UNCONSTRAINED_MINIMIZATION) { 1407 ierr = SNESSetHessian(snes,J,J,MatSNESMFComputeJacobian,snes->funP);CHKERRQ(ierr); 1408 } else { 1409 SETERRQ(PETSC_ERR_SUP,"Method class doesn't support matrix-free option"); 1410 } 1411 ierr = MatDestroy(J);CHKERRQ(ierr); 1412 1413 /* force no preconditioner */ 1414 ierr = SNESGetSLES(snes,&sles);CHKERRQ(ierr); 1415 ierr = SLESGetPC(sles,&pc);CHKERRQ(ierr); 1416 ierr = PCSetType(pc,PCNONE);CHKERRQ(ierr); 1417 } 1418 1419 if ((snes->method_class == SNES_NONLINEAR_EQUATIONS)) { 1420 PetscTruth iseqtr; 1421 1422 if (!snes->vec_func) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call SNESSetFunction() first"); 1423 if (!snes->computefunction) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call SNESSetFunction() first"); 1424 if (!snes->jacobian) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call SNESSetJacobian() first \n or use -snes_mf option"); 1425 if (snes->vec_func == snes->vec_sol) { 1426 SETERRQ(PETSC_ERR_ARG_IDN,"Solution vector cannot be function vector"); 1427 } 1428 1429 /* Set the KSP stopping criterion to use the Eisenstat-Walker method */ 1430 ierr = PetscTypeCompare((PetscObject)snes,SNESEQTR,&iseqtr);CHKERRQ(ierr); 1431 if (snes->ksp_ewconv && !iseqtr) { 1432 SLES sles; KSP ksp; 1433 ierr = SNESGetSLES(snes,&sles);CHKERRQ(ierr); 1434 ierr = SLESGetKSP(sles,&ksp);CHKERRQ(ierr); 1435 ierr = KSPSetConvergenceTest(ksp,SNES_KSP_EW_Converged_Private,snes);CHKERRQ(ierr); 1436 } 1437 } else if ((snes->method_class == SNES_UNCONSTRAINED_MINIMIZATION)) { 1438 if (!snes->vec_func) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call SNESSetGradient() first"); 1439 if (!snes->computefunction) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call SNESSetGradient() first"); 1440 if (!snes->computeumfunction) { 1441 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call SNESSetMinimizationFunction() first"); 1442 } 1443 if (!snes->jacobian) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call SNESSetHessian()"); 1444 } else { 1445 SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Unknown method class"); 1446 } 1447 if (snes->setup) {ierr = (*snes->setup)(snes);CHKERRQ(ierr);} 1448 snes->setupcalled = 1; 1449 PetscFunctionReturn(0); 1450 } 1451 1452 #undef __FUNCT__ 1453 #define __FUNCT__ "SNESDestroy" 1454 /*@C 1455 SNESDestroy - Destroys the nonlinear solver context that was created 1456 with SNESCreate(). 1457 1458 Collective on SNES 1459 1460 Input Parameter: 1461 . snes - the SNES context 1462 1463 Level: beginner 1464 1465 .keywords: SNES, nonlinear, destroy 1466 1467 .seealso: SNESCreate(), SNESSolve() 1468 @*/ 1469 int SNESDestroy(SNES snes) 1470 { 1471 int i,ierr; 1472 1473 PetscFunctionBegin; 1474 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1475 if (--snes->refct > 0) PetscFunctionReturn(0); 1476 1477 /* if memory was published with AMS then destroy it */ 1478 ierr = PetscObjectDepublish(snes);CHKERRQ(ierr); 1479 1480 if (snes->destroy) {ierr = (*(snes)->destroy)(snes);CHKERRQ(ierr);} 1481 if (snes->kspconvctx) {ierr = PetscFree(snes->kspconvctx);CHKERRQ(ierr);} 1482 if (snes->jacobian) {ierr = MatDestroy(snes->jacobian);CHKERRQ(ierr);} 1483 if (snes->jacobian_pre) {ierr = MatDestroy(snes->jacobian_pre);CHKERRQ(ierr);} 1484 ierr = SLESDestroy(snes->sles);CHKERRQ(ierr); 1485 if (snes->vwork) {ierr = VecDestroyVecs(snes->vwork,snes->nvwork);CHKERRQ(ierr);} 1486 for (i=0; i<snes->numbermonitors; i++) { 1487 if (snes->monitordestroy[i]) { 1488 ierr = (*snes->monitordestroy[i])(snes->monitorcontext[i]);CHKERRQ(ierr); 1489 } 1490 } 1491 PetscLogObjectDestroy((PetscObject)snes); 1492 PetscHeaderDestroy((PetscObject)snes); 1493 PetscFunctionReturn(0); 1494 } 1495 1496 /* ----------- Routines to set solver parameters ---------- */ 1497 1498 #undef __FUNCT__ 1499 #define __FUNCT__ "SNESSetTolerances" 1500 /*@ 1501 SNESSetTolerances - Sets various parameters used in convergence tests. 1502 1503 Collective on SNES 1504 1505 Input Parameters: 1506 + snes - the SNES context 1507 . atol - absolute convergence tolerance 1508 . rtol - relative convergence tolerance 1509 . stol - convergence tolerance in terms of the norm 1510 of the change in the solution between steps 1511 . maxit - maximum number of iterations 1512 - maxf - maximum number of function evaluations 1513 1514 Options Database Keys: 1515 + -snes_atol <atol> - Sets atol 1516 . -snes_rtol <rtol> - Sets rtol 1517 . -snes_stol <stol> - Sets stol 1518 . -snes_max_it <maxit> - Sets maxit 1519 - -snes_max_funcs <maxf> - Sets maxf 1520 1521 Notes: 1522 The default maximum number of iterations is 50. 1523 The default maximum number of function evaluations is 1000. 1524 1525 Level: intermediate 1526 1527 .keywords: SNES, nonlinear, set, convergence, tolerances 1528 1529 .seealso: SNESSetTrustRegionTolerance(), SNESSetMinimizationFunctionTolerance() 1530 @*/ 1531 int SNESSetTolerances(SNES snes,PetscReal atol,PetscReal rtol,PetscReal stol,int maxit,int maxf) 1532 { 1533 PetscFunctionBegin; 1534 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1535 if (atol != PETSC_DEFAULT) snes->atol = atol; 1536 if (rtol != PETSC_DEFAULT) snes->rtol = rtol; 1537 if (stol != PETSC_DEFAULT) snes->xtol = stol; 1538 if (maxit != PETSC_DEFAULT) snes->max_its = maxit; 1539 if (maxf != PETSC_DEFAULT) snes->max_funcs = maxf; 1540 PetscFunctionReturn(0); 1541 } 1542 1543 #undef __FUNCT__ 1544 #define __FUNCT__ "SNESGetTolerances" 1545 /*@ 1546 SNESGetTolerances - Gets various parameters used in convergence tests. 1547 1548 Not Collective 1549 1550 Input Parameters: 1551 + snes - the SNES context 1552 . atol - absolute convergence tolerance 1553 . rtol - relative convergence tolerance 1554 . stol - convergence tolerance in terms of the norm 1555 of the change in the solution between steps 1556 . maxit - maximum number of iterations 1557 - maxf - maximum number of function evaluations 1558 1559 Notes: 1560 The user can specify PETSC_NULL for any parameter that is not needed. 1561 1562 Level: intermediate 1563 1564 .keywords: SNES, nonlinear, get, convergence, tolerances 1565 1566 .seealso: SNESSetTolerances() 1567 @*/ 1568 int SNESGetTolerances(SNES snes,PetscReal *atol,PetscReal *rtol,PetscReal *stol,int *maxit,int *maxf) 1569 { 1570 PetscFunctionBegin; 1571 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1572 if (atol) *atol = snes->atol; 1573 if (rtol) *rtol = snes->rtol; 1574 if (stol) *stol = snes->xtol; 1575 if (maxit) *maxit = snes->max_its; 1576 if (maxf) *maxf = snes->max_funcs; 1577 PetscFunctionReturn(0); 1578 } 1579 1580 #undef __FUNCT__ 1581 #define __FUNCT__ "SNESSetTrustRegionTolerance" 1582 /*@ 1583 SNESSetTrustRegionTolerance - Sets the trust region parameter tolerance. 1584 1585 Collective on SNES 1586 1587 Input Parameters: 1588 + snes - the SNES context 1589 - tol - tolerance 1590 1591 Options Database Key: 1592 . -snes_trtol <tol> - Sets tol 1593 1594 Level: intermediate 1595 1596 .keywords: SNES, nonlinear, set, trust region, tolerance 1597 1598 .seealso: SNESSetTolerances(), SNESSetMinimizationFunctionTolerance() 1599 @*/ 1600 int SNESSetTrustRegionTolerance(SNES snes,PetscReal tol) 1601 { 1602 PetscFunctionBegin; 1603 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1604 snes->deltatol = tol; 1605 PetscFunctionReturn(0); 1606 } 1607 1608 #undef __FUNCT__ 1609 #define __FUNCT__ "SNESSetMinimizationFunctionTolerance" 1610 /*@ 1611 SNESSetMinimizationFunctionTolerance - Sets the minimum allowable function tolerance 1612 for unconstrained minimization solvers. 1613 1614 Collective on SNES 1615 1616 Input Parameters: 1617 + snes - the SNES context 1618 - ftol - minimum function tolerance 1619 1620 Options Database Key: 1621 . -snes_fmin <ftol> - Sets ftol 1622 1623 Note: 1624 SNESSetMinimizationFunctionTolerance() is valid for SNES_UNCONSTRAINED_MINIMIZATION 1625 methods only. 1626 1627 Level: intermediate 1628 1629 .keywords: SNES, nonlinear, set, minimum, convergence, function, tolerance 1630 1631 .seealso: SNESSetTolerances(), SNESSetTrustRegionTolerance() 1632 @*/ 1633 int SNESSetMinimizationFunctionTolerance(SNES snes,PetscReal ftol) 1634 { 1635 PetscFunctionBegin; 1636 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1637 snes->fmin = ftol; 1638 PetscFunctionReturn(0); 1639 } 1640 /* 1641 Duplicate the lg monitors for SNES from KSP; for some reason with 1642 dynamic libraries things don't work under Sun4 if we just use 1643 macros instead of functions 1644 */ 1645 #undef __FUNCT__ 1646 #define __FUNCT__ "SNESLGMonitor" 1647 int SNESLGMonitor(SNES snes,int it,PetscReal norm,void *ctx) 1648 { 1649 int ierr; 1650 1651 PetscFunctionBegin; 1652 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1653 ierr = KSPLGMonitor((KSP)snes,it,norm,ctx);CHKERRQ(ierr); 1654 PetscFunctionReturn(0); 1655 } 1656 1657 #undef __FUNCT__ 1658 #define __FUNCT__ "SNESLGMonitorCreate" 1659 int SNESLGMonitorCreate(char *host,char *label,int x,int y,int m,int n,PetscDrawLG *draw) 1660 { 1661 int ierr; 1662 1663 PetscFunctionBegin; 1664 ierr = KSPLGMonitorCreate(host,label,x,y,m,n,draw);CHKERRQ(ierr); 1665 PetscFunctionReturn(0); 1666 } 1667 1668 #undef __FUNCT__ 1669 #define __FUNCT__ "SNESLGMonitorDestroy" 1670 int SNESLGMonitorDestroy(PetscDrawLG draw) 1671 { 1672 int ierr; 1673 1674 PetscFunctionBegin; 1675 ierr = KSPLGMonitorDestroy(draw);CHKERRQ(ierr); 1676 PetscFunctionReturn(0); 1677 } 1678 1679 /* ------------ Routines to set performance monitoring options ----------- */ 1680 1681 #undef __FUNCT__ 1682 #define __FUNCT__ "SNESSetMonitor" 1683 /*@C 1684 SNESSetMonitor - Sets an ADDITIONAL function that is to be used at every 1685 iteration of the nonlinear solver to display the iteration's 1686 progress. 1687 1688 Collective on SNES 1689 1690 Input Parameters: 1691 + snes - the SNES context 1692 . func - monitoring routine 1693 . mctx - [optional] user-defined context for private data for the 1694 monitor routine (use PETSC_NULL if no context is desitre) 1695 - monitordestroy - [optional] routine that frees monitor context 1696 (may be PETSC_NULL) 1697 1698 Calling sequence of func: 1699 $ int func(SNES snes,int its, PetscReal norm,void *mctx) 1700 1701 + snes - the SNES context 1702 . its - iteration number 1703 . norm - 2-norm function value (may be estimated) 1704 for SNES_NONLINEAR_EQUATIONS methods 1705 . norm - 2-norm gradient value (may be estimated) 1706 for SNES_UNCONSTRAINED_MINIMIZATION methods 1707 - mctx - [optional] monitoring context 1708 1709 Options Database Keys: 1710 + -snes_monitor - sets SNESDefaultMonitor() 1711 . -snes_xmonitor - sets line graph monitor, 1712 uses SNESLGMonitorCreate() 1713 _ -snes_cancelmonitors - cancels all monitors that have 1714 been hardwired into a code by 1715 calls to SNESSetMonitor(), but 1716 does not cancel those set via 1717 the options database. 1718 1719 Notes: 1720 Several different monitoring routines may be set by calling 1721 SNESSetMonitor() multiple times; all will be called in the 1722 order in which they were set. 1723 1724 Level: intermediate 1725 1726 .keywords: SNES, nonlinear, set, monitor 1727 1728 .seealso: SNESDefaultMonitor(), SNESClearMonitor() 1729 @*/ 1730 int SNESSetMonitor(SNES snes,int (*func)(SNES,int,PetscReal,void*),void *mctx,int (*monitordestroy)(void *)) 1731 { 1732 PetscFunctionBegin; 1733 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1734 if (snes->numbermonitors >= MAXSNESMONITORS) { 1735 SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many monitors set"); 1736 } 1737 1738 snes->monitor[snes->numbermonitors] = func; 1739 snes->monitordestroy[snes->numbermonitors] = monitordestroy; 1740 snes->monitorcontext[snes->numbermonitors++] = (void*)mctx; 1741 PetscFunctionReturn(0); 1742 } 1743 1744 #undef __FUNCT__ 1745 #define __FUNCT__ "SNESClearMonitor" 1746 /*@C 1747 SNESClearMonitor - Clears all the monitor functions for a SNES object. 1748 1749 Collective on SNES 1750 1751 Input Parameters: 1752 . snes - the SNES context 1753 1754 Options Database: 1755 . -snes_cancelmonitors - cancels all monitors that have been hardwired 1756 into a code by calls to SNESSetMonitor(), but does not cancel those 1757 set via the options database 1758 1759 Notes: 1760 There is no way to clear one specific monitor from a SNES object. 1761 1762 Level: intermediate 1763 1764 .keywords: SNES, nonlinear, set, monitor 1765 1766 .seealso: SNESDefaultMonitor(), SNESSetMonitor() 1767 @*/ 1768 int SNESClearMonitor(SNES snes) 1769 { 1770 PetscFunctionBegin; 1771 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1772 snes->numbermonitors = 0; 1773 PetscFunctionReturn(0); 1774 } 1775 1776 #undef __FUNCT__ 1777 #define __FUNCT__ "SNESSetConvergenceTest" 1778 /*@C 1779 SNESSetConvergenceTest - Sets the function that is to be used 1780 to test for convergence of the nonlinear iterative solution. 1781 1782 Collective on SNES 1783 1784 Input Parameters: 1785 + snes - the SNES context 1786 . func - routine to test for convergence 1787 - cctx - [optional] context for private data for the convergence routine 1788 (may be PETSC_NULL) 1789 1790 Calling sequence of func: 1791 $ int func (SNES snes,PetscReal xnorm,PetscReal gnorm,PetscReal f,SNESConvergedReason *reason,void *cctx) 1792 1793 + snes - the SNES context 1794 . cctx - [optional] convergence context 1795 . reason - reason for convergence/divergence 1796 . xnorm - 2-norm of current iterate 1797 . gnorm - 2-norm of current step (SNES_NONLINEAR_EQUATIONS methods) 1798 . f - 2-norm of function (SNES_NONLINEAR_EQUATIONS methods) 1799 . gnorm - 2-norm of current gradient (SNES_UNCONSTRAINED_MINIMIZATION methods) 1800 - f - function value (SNES_UNCONSTRAINED_MINIMIZATION methods) 1801 1802 Level: advanced 1803 1804 .keywords: SNES, nonlinear, set, convergence, test 1805 1806 .seealso: SNESConverged_EQ_LS(), SNESConverged_EQ_TR(), 1807 SNESConverged_UM_LS(), SNESConverged_UM_TR() 1808 @*/ 1809 int SNESSetConvergenceTest(SNES snes,int (*func)(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void *cctx) 1810 { 1811 PetscFunctionBegin; 1812 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1813 (snes)->converged = func; 1814 (snes)->cnvP = cctx; 1815 PetscFunctionReturn(0); 1816 } 1817 1818 #undef __FUNCT__ 1819 #define __FUNCT__ "SNESGetConvergedReason" 1820 /*@C 1821 SNESGetConvergedReason - Gets the reason the SNES iteration was stopped. 1822 1823 Not Collective 1824 1825 Input Parameter: 1826 . snes - the SNES context 1827 1828 Output Parameter: 1829 . reason - negative value indicates diverged, positive value converged, see petscsnes.h or the 1830 manual pages for the individual convergence tests for complete lists 1831 1832 Level: intermediate 1833 1834 Notes: Can only be called after the call the SNESSolve() is complete. 1835 1836 .keywords: SNES, nonlinear, set, convergence, test 1837 1838 .seealso: SNESSetConvergenceTest(), SNESConverged_EQ_LS(), SNESConverged_EQ_TR(), 1839 SNESConverged_UM_LS(), SNESConverged_UM_TR(), SNESConvergedReason 1840 @*/ 1841 int SNESGetConvergedReason(SNES snes,SNESConvergedReason *reason) 1842 { 1843 PetscFunctionBegin; 1844 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1845 *reason = snes->reason; 1846 PetscFunctionReturn(0); 1847 } 1848 1849 #undef __FUNCT__ 1850 #define __FUNCT__ "SNESSetConvergenceHistory" 1851 /*@ 1852 SNESSetConvergenceHistory - Sets the array used to hold the convergence history. 1853 1854 Collective on SNES 1855 1856 Input Parameters: 1857 + snes - iterative context obtained from SNESCreate() 1858 . a - array to hold history 1859 . its - integer array holds the number of linear iterations for each solve. 1860 . na - size of a and its 1861 - reset - PETSC_TRUE indicates each new nonlinear solve resets the history counter to zero, 1862 else it continues storing new values for new nonlinear solves after the old ones 1863 1864 Notes: 1865 If set, this array will contain the function norms (for 1866 SNES_NONLINEAR_EQUATIONS methods) or gradient norms 1867 (for SNES_UNCONSTRAINED_MINIMIZATION methods) computed 1868 at each step. 1869 1870 This routine is useful, e.g., when running a code for purposes 1871 of accurate performance monitoring, when no I/O should be done 1872 during the section of code that is being timed. 1873 1874 Level: intermediate 1875 1876 .keywords: SNES, set, convergence, history 1877 1878 .seealso: SNESGetConvergenceHistory() 1879 1880 @*/ 1881 int SNESSetConvergenceHistory(SNES snes,PetscReal *a,int *its,int na,PetscTruth reset) 1882 { 1883 PetscFunctionBegin; 1884 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1885 if (na) PetscValidScalarPointer(a); 1886 snes->conv_hist = a; 1887 snes->conv_hist_its = its; 1888 snes->conv_hist_max = na; 1889 snes->conv_hist_reset = reset; 1890 PetscFunctionReturn(0); 1891 } 1892 1893 #undef __FUNCT__ 1894 #define __FUNCT__ "SNESGetConvergenceHistory" 1895 /*@C 1896 SNESGetConvergenceHistory - Gets the array used to hold the convergence history. 1897 1898 Collective on SNES 1899 1900 Input Parameter: 1901 . snes - iterative context obtained from SNESCreate() 1902 1903 Output Parameters: 1904 . a - array to hold history 1905 . its - integer array holds the number of linear iterations (or 1906 negative if not converged) for each solve. 1907 - na - size of a and its 1908 1909 Notes: 1910 The calling sequence for this routine in Fortran is 1911 $ call SNESGetConvergenceHistory(SNES snes, integer na, integer ierr) 1912 1913 This routine is useful, e.g., when running a code for purposes 1914 of accurate performance monitoring, when no I/O should be done 1915 during the section of code that is being timed. 1916 1917 Level: intermediate 1918 1919 .keywords: SNES, get, convergence, history 1920 1921 .seealso: SNESSetConvergencHistory() 1922 1923 @*/ 1924 int SNESGetConvergenceHistory(SNES snes,PetscReal **a,int **its,int *na) 1925 { 1926 PetscFunctionBegin; 1927 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1928 if (a) *a = snes->conv_hist; 1929 if (its) *its = snes->conv_hist_its; 1930 if (na) *na = snes->conv_hist_len; 1931 PetscFunctionReturn(0); 1932 } 1933 1934 #undef __FUNCT__ 1935 #define __FUNCT__ "SNESSetRhsBC" 1936 /*@ 1937 SNESSetRhsBC - Sets the function which applies boundary conditions 1938 to the Rhs of each system. 1939 1940 Collective on SNES 1941 1942 Input Parameters: 1943 . snes - The nonlinear solver context 1944 . func - The function 1945 1946 Calling sequence of func: 1947 . func (SNES snes, Vec rhs, void *ctx); 1948 1949 . rhs - The current rhs vector 1950 . ctx - The user-context 1951 1952 Level: intermediate 1953 1954 .keywords: SNES, Rhs, boundary conditions 1955 .seealso SNESDefaultRhsBC(), SNESSetSolutionBC(), SNESSetUpdate() 1956 @*/ 1957 int SNESSetRhsBC(SNES snes, int (*func)(SNES, Vec, void *)) 1958 { 1959 PetscFunctionBegin; 1960 PetscValidHeaderSpecific(snes, SNES_COOKIE); 1961 snes->applyrhsbc = func; 1962 PetscFunctionReturn(0); 1963 } 1964 1965 #undef __FUNCT__ 1966 #define __FUNCT__ "SNESDefaultRhsBC" 1967 /*@ 1968 SNESDefaultRhsBC - The default boundary condition function which does nothing. 1969 1970 Not collective 1971 1972 Input Parameters: 1973 . snes - The nonlinear solver context 1974 . rhs - The Rhs 1975 . ctx - The user-context 1976 1977 Level: beginner 1978 1979 .keywords: SNES, Rhs, boundary conditions 1980 .seealso SNESSetRhsBC(), SNESDefaultSolutionBC(), SNESDefaultUpdate() 1981 @*/ 1982 int SNESDefaultRhsBC(SNES snes, Vec rhs, void *ctx) 1983 { 1984 PetscFunctionBegin; 1985 PetscFunctionReturn(0); 1986 } 1987 1988 #undef __FUNCT__ 1989 #define __FUNCT__ "SNESSetSolutionBC" 1990 /*@ 1991 SNESSetSolutionBC - Sets the function which applies boundary conditions 1992 to the solution of each system. 1993 1994 Collective on SNES 1995 1996 Input Parameters: 1997 . snes - The nonlinear solver context 1998 . func - The function 1999 2000 Calling sequence of func: 2001 . func (TS ts, Vec rsol, void *ctx); 2002 2003 . sol - The current solution vector 2004 . ctx - The user-context 2005 2006 Level: intermediate 2007 2008 .keywords: SNES, solution, boundary conditions 2009 .seealso SNESDefaultSolutionBC(), SNESSetRhsBC(), SNESSetUpdate() 2010 @*/ 2011 int SNESSetSolutionBC(SNES snes, int (*func)(SNES, Vec, void *)) 2012 { 2013 PetscFunctionBegin; 2014 PetscValidHeaderSpecific(snes, SNES_COOKIE); 2015 snes->applysolbc = func; 2016 PetscFunctionReturn(0); 2017 } 2018 2019 #undef __FUNCT__ 2020 #define __FUNCT__ "SNESDefaultSolutionBC" 2021 /*@ 2022 SNESDefaultSolutionBC - The default boundary condition function which does nothing. 2023 2024 Not collective 2025 2026 Input Parameters: 2027 . snes - The nonlinear solver context 2028 . sol - The solution 2029 . ctx - The user-context 2030 2031 Level: beginner 2032 2033 .keywords: SNES, solution, boundary conditions 2034 .seealso SNESSetSolutionBC(), SNESDefaultRhsBC(), SNESDefaultUpdate() 2035 @*/ 2036 int SNESDefaultSolutionBC(SNES snes, Vec sol, void *ctx) 2037 { 2038 PetscFunctionBegin; 2039 PetscFunctionReturn(0); 2040 } 2041 2042 #undef __FUNCT__ 2043 #define __FUNCT__ "SNESSetUpdate" 2044 /*@ 2045 SNESSetUpdate - Sets the general-purpose update function called 2046 at the beginning of every step of the iteration. 2047 2048 Collective on SNES 2049 2050 Input Parameters: 2051 . snes - The nonlinear solver context 2052 . func - The function 2053 2054 Calling sequence of func: 2055 . func (TS ts, int step); 2056 2057 . step - The current step of the iteration 2058 2059 Level: intermediate 2060 2061 .keywords: SNES, update 2062 .seealso SNESDefaultUpdate(), SNESSetRhsBC(), SNESSetSolutionBC() 2063 @*/ 2064 int SNESSetUpdate(SNES snes, int (*func)(SNES, int)) 2065 { 2066 PetscFunctionBegin; 2067 PetscValidHeaderSpecific(snes, SNES_COOKIE); 2068 snes->update = func; 2069 PetscFunctionReturn(0); 2070 } 2071 2072 #undef __FUNCT__ 2073 #define __FUNCT__ "SNESDefaultUpdate" 2074 /*@ 2075 SNESDefaultUpdate - The default update function which does nothing. 2076 2077 Not collective 2078 2079 Input Parameters: 2080 . snes - The nonlinear solver context 2081 . step - The current step of the iteration 2082 2083 .keywords: SNES, update 2084 .seealso SNESSetUpdate(), SNESDefaultRhsBC(), SNESDefaultSolutionBC() 2085 @*/ 2086 int SNESDefaultUpdate(SNES snes, int step) 2087 { 2088 PetscFunctionBegin; 2089 PetscFunctionReturn(0); 2090 } 2091 2092 #undef __FUNCT__ 2093 #define __FUNCT__ "SNESScaleStep_Private" 2094 /* 2095 SNESScaleStep_Private - Scales a step so that its length is less than the 2096 positive parameter delta. 2097 2098 Input Parameters: 2099 + snes - the SNES context 2100 . y - approximate solution of linear system 2101 . fnorm - 2-norm of current function 2102 - delta - trust region size 2103 2104 Output Parameters: 2105 + gpnorm - predicted function norm at the new point, assuming local 2106 linearization. The value is zero if the step lies within the trust 2107 region, and exceeds zero otherwise. 2108 - ynorm - 2-norm of the step 2109 2110 Note: 2111 For non-trust region methods such as SNESEQLS, the parameter delta 2112 is set to be the maximum allowable step size. 2113 2114 .keywords: SNES, nonlinear, scale, step 2115 */ 2116 int SNESScaleStep_Private(SNES snes,Vec y,PetscReal *fnorm,PetscReal *delta, 2117 PetscReal *gpnorm,PetscReal *ynorm) 2118 { 2119 PetscReal norm; 2120 PetscScalar cnorm; 2121 int ierr; 2122 2123 PetscFunctionBegin; 2124 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2125 PetscValidHeaderSpecific(y,VEC_COOKIE); 2126 PetscCheckSameComm(snes,y); 2127 2128 ierr = VecNorm(y,NORM_2,&norm);CHKERRQ(ierr); 2129 if (norm > *delta) { 2130 norm = *delta/norm; 2131 *gpnorm = (1.0 - norm)*(*fnorm); 2132 cnorm = norm; 2133 ierr = VecScale(&cnorm,y);CHKERRQ(ierr); 2134 *ynorm = *delta; 2135 } else { 2136 *gpnorm = 0.0; 2137 *ynorm = norm; 2138 } 2139 PetscFunctionReturn(0); 2140 } 2141 2142 #undef __FUNCT__ 2143 #define __FUNCT__ "SNESSolve" 2144 /*@ 2145 SNESSolve - Solves a nonlinear system. Call SNESSolve after calling 2146 SNESCreate() and optional routines of the form SNESSetXXX(). 2147 2148 Collective on SNES 2149 2150 Input Parameters: 2151 + snes - the SNES context 2152 - x - the solution vector 2153 2154 Output Parameter: 2155 . its - number of iterations until termination 2156 2157 Notes: 2158 The user should initialize the vector,x, with the initial guess 2159 for the nonlinear solve prior to calling SNESSolve. In particular, 2160 to employ an initial guess of zero, the user should explicitly set 2161 this vector to zero by calling VecSet(). 2162 2163 Level: beginner 2164 2165 .keywords: SNES, nonlinear, solve 2166 2167 .seealso: SNESCreate(), SNESDestroy() 2168 @*/ 2169 int SNESSolve(SNES snes,Vec x,int *its) 2170 { 2171 int ierr; 2172 PetscTruth flg; 2173 2174 PetscFunctionBegin; 2175 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2176 PetscValidHeaderSpecific(x,VEC_COOKIE); 2177 PetscCheckSameComm(snes,x); 2178 PetscValidIntPointer(its); 2179 if (!snes->solve) SETERRQ(1,"SNESSetType() or SNESSetFromOptions() must be called before SNESSolve()"); 2180 2181 if (!snes->setupcalled) {ierr = SNESSetUp(snes,x);CHKERRQ(ierr);} 2182 else {snes->vec_sol = snes->vec_sol_always = x;} 2183 if (snes->conv_hist_reset == PETSC_TRUE) snes->conv_hist_len = 0; 2184 ierr = SNESLogEventBegin(SNES_Solve,snes,0,0,0);CHKERRQ(ierr); 2185 snes->nfuncs = 0; snes->linear_its = 0; snes->nfailures = 0; 2186 ierr = (*(snes)->solve)(snes,its);CHKERRQ(ierr); 2187 ierr = SNESLogEventEnd(SNES_Solve,snes,0,0,0);CHKERRQ(ierr); 2188 ierr = PetscOptionsHasName(snes->prefix,"-snes_view",&flg);CHKERRQ(ierr); 2189 if (flg && !PetscPreLoadingOn) { ierr = SNESView(snes,PETSC_VIEWER_STDOUT_WORLD);CHKERRQ(ierr); } 2190 PetscFunctionReturn(0); 2191 } 2192 2193 /* --------- Internal routines for SNES Package --------- */ 2194 2195 #undef __FUNCT__ 2196 #define __FUNCT__ "SNESSetType" 2197 /*@C 2198 SNESSetType - Sets the method for the nonlinear solver. 2199 2200 Collective on SNES 2201 2202 Input Parameters: 2203 + snes - the SNES context 2204 - type - a known method 2205 2206 Options Database Key: 2207 . -snes_type <type> - Sets the method; use -help for a list 2208 of available methods (for instance, ls or tr) 2209 2210 Notes: 2211 See "petsc/include/petscsnes.h" for available methods (for instance) 2212 + SNESEQLS - Newton's method with line search 2213 (systems of nonlinear equations) 2214 . SNESEQTR - Newton's method with trust region 2215 (systems of nonlinear equations) 2216 . SNESUMTR - Newton's method with trust region 2217 (unconstrained minimization) 2218 - SNESUMLS - Newton's method with line search 2219 (unconstrained minimization) 2220 2221 Normally, it is best to use the SNESSetFromOptions() command and then 2222 set the SNES solver type from the options database rather than by using 2223 this routine. Using the options database provides the user with 2224 maximum flexibility in evaluating the many nonlinear solvers. 2225 The SNESSetType() routine is provided for those situations where it 2226 is necessary to set the nonlinear solver independently of the command 2227 line or options database. This might be the case, for example, when 2228 the choice of solver changes during the execution of the program, 2229 and the user's application is taking responsibility for choosing the 2230 appropriate method. 2231 2232 Level: intermediate 2233 2234 .keywords: SNES, set, type 2235 2236 .seealso: SNESType, SNESCreate() 2237 2238 @*/ 2239 int SNESSetType(SNES snes,SNESType type) 2240 { 2241 int ierr,(*r)(SNES); 2242 PetscTruth match; 2243 2244 PetscFunctionBegin; 2245 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2246 PetscValidCharPointer(type); 2247 2248 ierr = PetscTypeCompare((PetscObject)snes,type,&match);CHKERRQ(ierr); 2249 if (match) PetscFunctionReturn(0); 2250 2251 if (snes->setupcalled) { 2252 ierr = (*(snes)->destroy)(snes);CHKERRQ(ierr); 2253 snes->data = 0; 2254 } 2255 2256 /* Get the function pointers for the iterative method requested */ 2257 if (!SNESRegisterAllCalled) {ierr = SNESRegisterAll(PETSC_NULL);CHKERRQ(ierr);} 2258 2259 ierr = PetscFListFind(snes->comm,SNESList,type,(void (**)(void)) &r);CHKERRQ(ierr); 2260 2261 if (!r) SETERRQ1(1,"Unable to find requested SNES type %s",type); 2262 2263 if (snes->data) {ierr = PetscFree(snes->data);CHKERRQ(ierr);} 2264 snes->data = 0; 2265 ierr = (*r)(snes);CHKERRQ(ierr); 2266 2267 ierr = PetscObjectChangeTypeName((PetscObject)snes,type);CHKERRQ(ierr); 2268 snes->set_method_called = 1; 2269 2270 PetscFunctionReturn(0); 2271 } 2272 2273 2274 /* --------------------------------------------------------------------- */ 2275 #undef __FUNCT__ 2276 #define __FUNCT__ "SNESRegisterDestroy" 2277 /*@C 2278 SNESRegisterDestroy - Frees the list of nonlinear solvers that were 2279 registered by SNESRegisterDynamic(). 2280 2281 Not Collective 2282 2283 Level: advanced 2284 2285 .keywords: SNES, nonlinear, register, destroy 2286 2287 .seealso: SNESRegisterAll(), SNESRegisterAll() 2288 @*/ 2289 int SNESRegisterDestroy(void) 2290 { 2291 int ierr; 2292 2293 PetscFunctionBegin; 2294 if (SNESList) { 2295 ierr = PetscFListDestroy(&SNESList);CHKERRQ(ierr); 2296 SNESList = 0; 2297 } 2298 SNESRegisterAllCalled = PETSC_FALSE; 2299 PetscFunctionReturn(0); 2300 } 2301 2302 #undef __FUNCT__ 2303 #define __FUNCT__ "SNESGetType" 2304 /*@C 2305 SNESGetType - Gets the SNES method type and name (as a string). 2306 2307 Not Collective 2308 2309 Input Parameter: 2310 . snes - nonlinear solver context 2311 2312 Output Parameter: 2313 . type - SNES method (a character string) 2314 2315 Level: intermediate 2316 2317 .keywords: SNES, nonlinear, get, type, name 2318 @*/ 2319 int SNESGetType(SNES snes,SNESType *type) 2320 { 2321 PetscFunctionBegin; 2322 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2323 *type = snes->type_name; 2324 PetscFunctionReturn(0); 2325 } 2326 2327 #undef __FUNCT__ 2328 #define __FUNCT__ "SNESGetSolution" 2329 /*@C 2330 SNESGetSolution - Returns the vector where the approximate solution is 2331 stored. 2332 2333 Not Collective, but Vec is parallel if SNES is parallel 2334 2335 Input Parameter: 2336 . snes - the SNES context 2337 2338 Output Parameter: 2339 . x - the solution 2340 2341 Level: advanced 2342 2343 .keywords: SNES, nonlinear, get, solution 2344 2345 .seealso: SNESGetFunction(), SNESGetGradient(), SNESGetSolutionUpdate() 2346 @*/ 2347 int SNESGetSolution(SNES snes,Vec *x) 2348 { 2349 PetscFunctionBegin; 2350 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2351 *x = snes->vec_sol_always; 2352 PetscFunctionReturn(0); 2353 } 2354 2355 #undef __FUNCT__ 2356 #define __FUNCT__ "SNESGetSolutionUpdate" 2357 /*@C 2358 SNESGetSolutionUpdate - Returns the vector where the solution update is 2359 stored. 2360 2361 Not Collective, but Vec is parallel if SNES is parallel 2362 2363 Input Parameter: 2364 . snes - the SNES context 2365 2366 Output Parameter: 2367 . x - the solution update 2368 2369 Level: advanced 2370 2371 .keywords: SNES, nonlinear, get, solution, update 2372 2373 .seealso: SNESGetSolution(), SNESGetFunction 2374 @*/ 2375 int SNESGetSolutionUpdate(SNES snes,Vec *x) 2376 { 2377 PetscFunctionBegin; 2378 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2379 *x = snes->vec_sol_update_always; 2380 PetscFunctionReturn(0); 2381 } 2382 2383 #undef __FUNCT__ 2384 #define __FUNCT__ "SNESGetFunction" 2385 /*@C 2386 SNESGetFunction - Returns the vector where the function is stored. 2387 2388 Not Collective, but Vec is parallel if SNES is parallel 2389 2390 Input Parameter: 2391 . snes - the SNES context 2392 2393 Output Parameter: 2394 + r - the function (or PETSC_NULL) 2395 . ctx - the function context (or PETSC_NULL) 2396 - func - the function (or PETSC_NULL) 2397 2398 Notes: 2399 SNESGetFunction() is valid for SNES_NONLINEAR_EQUATIONS methods only 2400 Analogous routines for SNES_UNCONSTRAINED_MINIMIZATION methods are 2401 SNESGetMinimizationFunction() and SNESGetGradient(); 2402 2403 Level: advanced 2404 2405 .keywords: SNES, nonlinear, get, function 2406 2407 .seealso: SNESSetFunction(), SNESGetSolution(), SNESGetMinimizationFunction(), 2408 SNESGetGradient() 2409 2410 @*/ 2411 int SNESGetFunction(SNES snes,Vec *r,void **ctx,int (**func)(SNES,Vec,Vec,void*)) 2412 { 2413 PetscFunctionBegin; 2414 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2415 if (snes->method_class != SNES_NONLINEAR_EQUATIONS) { 2416 SETERRQ(PETSC_ERR_ARG_WRONG,"For SNES_NONLINEAR_EQUATIONS only"); 2417 } 2418 if (r) *r = snes->vec_func_always; 2419 if (ctx) *ctx = snes->funP; 2420 if (func) *func = snes->computefunction; 2421 PetscFunctionReturn(0); 2422 } 2423 2424 #undef __FUNCT__ 2425 #define __FUNCT__ "SNESGetGradient" 2426 /*@C 2427 SNESGetGradient - Returns the vector where the gradient is stored. 2428 2429 Not Collective, but Vec is parallel if SNES is parallel 2430 2431 Input Parameter: 2432 . snes - the SNES context 2433 2434 Output Parameter: 2435 + r - the gradient (or PETSC_NULL) 2436 - ctx - the gradient context (or PETSC_NULL) 2437 2438 Notes: 2439 SNESGetGradient() is valid for SNES_UNCONSTRAINED_MINIMIZATION methods 2440 only. An analogous routine for SNES_NONLINEAR_EQUATIONS methods is 2441 SNESGetFunction(). 2442 2443 Level: advanced 2444 2445 .keywords: SNES, nonlinear, get, gradient 2446 2447 .seealso: SNESGetMinimizationFunction(), SNESGetSolution(), SNESGetFunction(), 2448 SNESSetGradient(), SNESSetFunction() 2449 2450 @*/ 2451 int SNESGetGradient(SNES snes,Vec *r,void **ctx) 2452 { 2453 PetscFunctionBegin; 2454 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2455 if (snes->method_class != SNES_UNCONSTRAINED_MINIMIZATION) { 2456 SETERRQ(PETSC_ERR_ARG_WRONG,"For SNES_UNCONSTRAINED_MINIMIZATION only"); 2457 } 2458 if (r) *r = snes->vec_func_always; 2459 if (ctx) *ctx = snes->funP; 2460 PetscFunctionReturn(0); 2461 } 2462 2463 #undef __FUNCT__ 2464 #define __FUNCT__ "SNESGetMinimizationFunction" 2465 /*@C 2466 SNESGetMinimizationFunction - Returns the scalar function value for 2467 unconstrained minimization problems. 2468 2469 Not Collective 2470 2471 Input Parameter: 2472 . snes - the SNES context 2473 2474 Output Parameter: 2475 + r - the function (or PETSC_NULL) 2476 - ctx - the function context (or PETSC_NULL) 2477 2478 Notes: 2479 SNESGetMinimizationFunction() is valid for SNES_UNCONSTRAINED_MINIMIZATION 2480 methods only. An analogous routine for SNES_NONLINEAR_EQUATIONS methods is 2481 SNESGetFunction(). 2482 2483 Level: advanced 2484 2485 .keywords: SNES, nonlinear, get, function 2486 2487 .seealso: SNESGetGradient(), SNESGetSolution(), SNESGetFunction(), SNESSetFunction() 2488 2489 @*/ 2490 int SNESGetMinimizationFunction(SNES snes,PetscReal *r,void **ctx) 2491 { 2492 PetscFunctionBegin; 2493 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2494 PetscValidScalarPointer(r); 2495 if (snes->method_class != SNES_UNCONSTRAINED_MINIMIZATION) { 2496 SETERRQ(PETSC_ERR_ARG_WRONG,"For SNES_UNCONSTRAINED_MINIMIZATION only"); 2497 } 2498 if (r) *r = snes->fc; 2499 if (ctx) *ctx = snes->umfunP; 2500 PetscFunctionReturn(0); 2501 } 2502 2503 #undef __FUNCT__ 2504 #define __FUNCT__ "SNESSetOptionsPrefix" 2505 /*@C 2506 SNESSetOptionsPrefix - Sets the prefix used for searching for all 2507 SNES options in the database. 2508 2509 Collective on SNES 2510 2511 Input Parameter: 2512 + snes - the SNES context 2513 - prefix - the prefix to prepend to all option names 2514 2515 Notes: 2516 A hyphen (-) must NOT be given at the beginning of the prefix name. 2517 The first character of all runtime options is AUTOMATICALLY the hyphen. 2518 2519 Level: advanced 2520 2521 .keywords: SNES, set, options, prefix, database 2522 2523 .seealso: SNESSetFromOptions() 2524 @*/ 2525 int SNESSetOptionsPrefix(SNES snes,char *prefix) 2526 { 2527 int ierr; 2528 2529 PetscFunctionBegin; 2530 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2531 ierr = PetscObjectSetOptionsPrefix((PetscObject)snes,prefix);CHKERRQ(ierr); 2532 ierr = SLESSetOptionsPrefix(snes->sles,prefix);CHKERRQ(ierr); 2533 PetscFunctionReturn(0); 2534 } 2535 2536 #undef __FUNCT__ 2537 #define __FUNCT__ "SNESAppendOptionsPrefix" 2538 /*@C 2539 SNESAppendOptionsPrefix - Appends to the prefix used for searching for all 2540 SNES options in the database. 2541 2542 Collective on SNES 2543 2544 Input Parameters: 2545 + snes - the SNES context 2546 - prefix - the prefix to prepend to all option names 2547 2548 Notes: 2549 A hyphen (-) must NOT be given at the beginning of the prefix name. 2550 The first character of all runtime options is AUTOMATICALLY the hyphen. 2551 2552 Level: advanced 2553 2554 .keywords: SNES, append, options, prefix, database 2555 2556 .seealso: SNESGetOptionsPrefix() 2557 @*/ 2558 int SNESAppendOptionsPrefix(SNES snes,char *prefix) 2559 { 2560 int ierr; 2561 2562 PetscFunctionBegin; 2563 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2564 ierr = PetscObjectAppendOptionsPrefix((PetscObject)snes,prefix);CHKERRQ(ierr); 2565 ierr = SLESAppendOptionsPrefix(snes->sles,prefix);CHKERRQ(ierr); 2566 PetscFunctionReturn(0); 2567 } 2568 2569 #undef __FUNCT__ 2570 #define __FUNCT__ "SNESGetOptionsPrefix" 2571 /*@C 2572 SNESGetOptionsPrefix - Sets the prefix used for searching for all 2573 SNES options in the database. 2574 2575 Not Collective 2576 2577 Input Parameter: 2578 . snes - the SNES context 2579 2580 Output Parameter: 2581 . prefix - pointer to the prefix string used 2582 2583 Notes: On the fortran side, the user should pass in a string 'prifix' of 2584 sufficient length to hold the prefix. 2585 2586 Level: advanced 2587 2588 .keywords: SNES, get, options, prefix, database 2589 2590 .seealso: SNESAppendOptionsPrefix() 2591 @*/ 2592 int SNESGetOptionsPrefix(SNES snes,char **prefix) 2593 { 2594 int ierr; 2595 2596 PetscFunctionBegin; 2597 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2598 ierr = PetscObjectGetOptionsPrefix((PetscObject)snes,prefix);CHKERRQ(ierr); 2599 PetscFunctionReturn(0); 2600 } 2601 2602 /*MC 2603 SNESRegisterDynamic - Adds a method to the nonlinear solver package. 2604 2605 Synopsis: 2606 int SNESRegisterDynamic(char *name_solver,char *path,char *name_create,int (*routine_create)(SNES)) 2607 2608 Not collective 2609 2610 Input Parameters: 2611 + name_solver - name of a new user-defined solver 2612 . path - path (either absolute or relative) the library containing this solver 2613 . name_create - name of routine to create method context 2614 - routine_create - routine to create method context 2615 2616 Notes: 2617 SNESRegisterDynamic() may be called multiple times to add several user-defined solvers. 2618 2619 If dynamic libraries are used, then the fourth input argument (routine_create) 2620 is ignored. 2621 2622 Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR}, ${BOPT}, 2623 and others of the form ${any_environmental_variable} occuring in pathname will be 2624 replaced with appropriate values. 2625 2626 Sample usage: 2627 .vb 2628 SNESRegisterDynamic("my_solver",/home/username/my_lib/lib/libg/solaris/mylib.a, 2629 "MySolverCreate",MySolverCreate); 2630 .ve 2631 2632 Then, your solver can be chosen with the procedural interface via 2633 $ SNESSetType(snes,"my_solver") 2634 or at runtime via the option 2635 $ -snes_type my_solver 2636 2637 Level: advanced 2638 2639 .keywords: SNES, nonlinear, register 2640 2641 .seealso: SNESRegisterAll(), SNESRegisterDestroy() 2642 M*/ 2643 2644 #undef __FUNCT__ 2645 #define __FUNCT__ "SNESRegister" 2646 int SNESRegister(char *sname,char *path,char *name,int (*function)(SNES)) 2647 { 2648 char fullname[256]; 2649 int ierr; 2650 2651 PetscFunctionBegin; 2652 ierr = PetscFListConcat(path,name,fullname);CHKERRQ(ierr); 2653 ierr = PetscFListAdd(&SNESList,sname,fullname,(void (*)(void))function);CHKERRQ(ierr); 2654 PetscFunctionReturn(0); 2655 } 2656