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