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