1 #ifdef PETSC_RCS_HEADER 2 static char vcid[] = "$Id: snes.c,v 1.190 1999/06/30 22:51:49 bsmith Exp balay $"; 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);CHKERRQ(ierr); 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 /*@C 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 snes->jacobian = J; 1353 if (snes->method_class == SNES_NONLINEAR_EQUATIONS) { 1354 PLogInfo(snes,"SNESSetUp: Setting default matrix-free operator Jacobian routines\n"); 1355 } else if (snes->method_class == SNES_UNCONSTRAINED_MINIMIZATION) { 1356 PLogInfo(snes,"SNESSetUp: Setting default matrix-free operator Hessian routines\n"); 1357 } else { 1358 SETERRQ(PETSC_ERR_SUP,0,"Method class doesn't support matrix-free operator option"); 1359 } 1360 ierr = MatSNESMFSetFromOptions(J);CHKERRQ(ierr); 1361 } 1362 ierr = OptionsHasName(snes->prefix,"-snes_mf", &flg);CHKERRQ(ierr); 1363 /* 1364 This version replaces both the user-provided Jacobian and the user- 1365 provided preconditioner matrix with the default matrix free version. 1366 */ 1367 if (flg) { 1368 Mat J; 1369 ierr = MatCreateSNESMF(snes,snes->vec_sol,&J);CHKERRQ(ierr); 1370 PLogObjectParent(snes,J); 1371 snes->mfshell = J; 1372 if (snes->method_class == SNES_NONLINEAR_EQUATIONS) { 1373 ierr = SNESSetJacobian(snes,J,J,0,snes->funP);CHKERRQ(ierr); 1374 PLogInfo(snes,"SNESSetUp: Setting default matrix-free Jacobian routines\n"); 1375 } else if (snes->method_class == SNES_UNCONSTRAINED_MINIMIZATION) { 1376 ierr = SNESSetHessian(snes,J,J,0,snes->funP);CHKERRQ(ierr); 1377 PLogInfo(snes,"SNESSetUp: Setting default matrix-free Hessian routines\n"); 1378 } else { 1379 SETERRQ(PETSC_ERR_SUP,0,"Method class doesn't support matrix-free option"); 1380 } 1381 ierr = MatSNESMFSetFromOptions(J);CHKERRQ(ierr); 1382 } 1383 if ((snes->method_class == SNES_NONLINEAR_EQUATIONS)) { 1384 if (!snes->vec_func) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,0,"Must call SNESSetFunction() first"); 1385 if (!snes->computefunction) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,0,"Must call SNESSetFunction() first"); 1386 if (!snes->jacobian) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,0,"Must call SNESSetJacobian() first \n or use -snes_mf option"); 1387 if (snes->vec_func == snes->vec_sol) { 1388 SETERRQ(PETSC_ERR_ARG_IDN,0,"Solution vector cannot be function vector"); 1389 } 1390 1391 /* Set the KSP stopping criterion to use the Eisenstat-Walker method */ 1392 if (snes->ksp_ewconv && PetscStrcmp(snes->type_name,SNES_EQ_TR)) { 1393 SLES sles; KSP ksp; 1394 ierr = SNESGetSLES(snes,&sles);CHKERRQ(ierr); 1395 ierr = SLESGetKSP(sles,&ksp);CHKERRQ(ierr); 1396 ierr = KSPSetConvergenceTest(ksp,SNES_KSP_EW_Converged_Private,(void *)snes);CHKERRQ(ierr); 1397 } 1398 } else if ((snes->method_class == SNES_UNCONSTRAINED_MINIMIZATION)) { 1399 if (!snes->vec_func) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,0,"Must call SNESSetGradient() first"); 1400 if (!snes->computefunction) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,0,"Must call SNESSetGradient() first"); 1401 if (!snes->computeumfunction) { 1402 SETERRQ(PETSC_ERR_ARG_WRONGSTATE,0,"Must call SNESSetMinimizationFunction() first"); 1403 } 1404 if (!snes->jacobian) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,0,"Must call SNESSetHessian()"); 1405 } else { 1406 SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,0,"Unknown method class"); 1407 } 1408 if (snes->setup) {ierr = (*snes->setup)(snes);CHKERRQ(ierr);} 1409 snes->setupcalled = 1; 1410 PetscFunctionReturn(0); 1411 } 1412 1413 #undef __FUNC__ 1414 #define __FUNC__ "SNESDestroy" 1415 /*@C 1416 SNESDestroy - Destroys the nonlinear solver context that was created 1417 with SNESCreate(). 1418 1419 Collective on SNES 1420 1421 Input Parameter: 1422 . snes - the SNES context 1423 1424 Level: beginner 1425 1426 .keywords: SNES, nonlinear, destroy 1427 1428 .seealso: SNESCreate(), SNESSolve() 1429 @*/ 1430 int SNESDestroy(SNES snes) 1431 { 1432 int i,ierr; 1433 1434 PetscFunctionBegin; 1435 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1436 if (--snes->refct > 0) PetscFunctionReturn(0); 1437 1438 if (snes->destroy) {ierr = (*(snes)->destroy)(snes);CHKERRQ(ierr);} 1439 if (snes->kspconvctx) {ierr = PetscFree(snes->kspconvctx);CHKERRQ(ierr);} 1440 if (snes->mfshell) {ierr = MatDestroy(snes->mfshell);CHKERRQ(ierr);} 1441 ierr = SLESDestroy(snes->sles);CHKERRQ(ierr); 1442 if (snes->vwork) {ierr = VecDestroyVecs(snes->vwork,snes->nvwork);CHKERRQ(ierr);} 1443 for (i=0; i<snes->numbermonitors; i++ ) { 1444 if (snes->monitordestroy[i]) { 1445 ierr = (*snes->monitordestroy[i])(snes->monitorcontext[i]);CHKERRQ(ierr); 1446 } 1447 } 1448 PLogObjectDestroy((PetscObject)snes); 1449 PetscHeaderDestroy((PetscObject)snes); 1450 PetscFunctionReturn(0); 1451 } 1452 1453 /* ----------- Routines to set solver parameters ---------- */ 1454 1455 #undef __FUNC__ 1456 #define __FUNC__ "SNESSetTolerances" 1457 /*@ 1458 SNESSetTolerances - Sets various parameters used in convergence tests. 1459 1460 Collective on SNES 1461 1462 Input Parameters: 1463 + snes - the SNES context 1464 . atol - absolute convergence tolerance 1465 . rtol - relative convergence tolerance 1466 . stol - convergence tolerance in terms of the norm 1467 of the change in the solution between steps 1468 . maxit - maximum number of iterations 1469 - maxf - maximum number of function evaluations 1470 1471 Options Database Keys: 1472 + -snes_atol <atol> - Sets atol 1473 . -snes_rtol <rtol> - Sets rtol 1474 . -snes_stol <stol> - Sets stol 1475 . -snes_max_it <maxit> - Sets maxit 1476 - -snes_max_funcs <maxf> - Sets maxf 1477 1478 Notes: 1479 The default maximum number of iterations is 50. 1480 The default maximum number of function evaluations is 1000. 1481 1482 Level: intermediate 1483 1484 .keywords: SNES, nonlinear, set, convergence, tolerances 1485 1486 .seealso: SNESSetTrustRegionTolerance(), SNESSetMinimizationFunctionTolerance() 1487 @*/ 1488 int SNESSetTolerances(SNES snes,double atol,double rtol,double stol,int maxit,int maxf) 1489 { 1490 PetscFunctionBegin; 1491 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1492 if (atol != PETSC_DEFAULT) snes->atol = atol; 1493 if (rtol != PETSC_DEFAULT) snes->rtol = rtol; 1494 if (stol != PETSC_DEFAULT) snes->xtol = stol; 1495 if (maxit != PETSC_DEFAULT) snes->max_its = maxit; 1496 if (maxf != PETSC_DEFAULT) snes->max_funcs = maxf; 1497 PetscFunctionReturn(0); 1498 } 1499 1500 #undef __FUNC__ 1501 #define __FUNC__ "SNESGetTolerances" 1502 /*@ 1503 SNESGetTolerances - Gets various parameters used in convergence tests. 1504 1505 Not Collective 1506 1507 Input Parameters: 1508 + snes - the SNES context 1509 . atol - absolute convergence tolerance 1510 . rtol - relative convergence tolerance 1511 . stol - convergence tolerance in terms of the norm 1512 of the change in the solution between steps 1513 . maxit - maximum number of iterations 1514 - maxf - maximum number of function evaluations 1515 1516 Notes: 1517 The user can specify PETSC_NULL for any parameter that is not needed. 1518 1519 Level: intermediate 1520 1521 .keywords: SNES, nonlinear, get, convergence, tolerances 1522 1523 .seealso: SNESSetTolerances() 1524 @*/ 1525 int SNESGetTolerances(SNES snes,double *atol,double *rtol,double *stol,int *maxit,int *maxf) 1526 { 1527 PetscFunctionBegin; 1528 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1529 if (atol) *atol = snes->atol; 1530 if (rtol) *rtol = snes->rtol; 1531 if (stol) *stol = snes->xtol; 1532 if (maxit) *maxit = snes->max_its; 1533 if (maxf) *maxf = snes->max_funcs; 1534 PetscFunctionReturn(0); 1535 } 1536 1537 #undef __FUNC__ 1538 #define __FUNC__ "SNESSetTrustRegionTolerance" 1539 /*@ 1540 SNESSetTrustRegionTolerance - Sets the trust region parameter tolerance. 1541 1542 Collective on SNES 1543 1544 Input Parameters: 1545 + snes - the SNES context 1546 - tol - tolerance 1547 1548 Options Database Key: 1549 . -snes_trtol <tol> - Sets tol 1550 1551 Level: intermediate 1552 1553 .keywords: SNES, nonlinear, set, trust region, tolerance 1554 1555 .seealso: SNESSetTolerances(), SNESSetMinimizationFunctionTolerance() 1556 @*/ 1557 int SNESSetTrustRegionTolerance(SNES snes,double tol) 1558 { 1559 PetscFunctionBegin; 1560 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1561 snes->deltatol = tol; 1562 PetscFunctionReturn(0); 1563 } 1564 1565 #undef __FUNC__ 1566 #define __FUNC__ "SNESSetMinimizationFunctionTolerance" 1567 /*@ 1568 SNESSetMinimizationFunctionTolerance - Sets the minimum allowable function tolerance 1569 for unconstrained minimization solvers. 1570 1571 Collective on SNES 1572 1573 Input Parameters: 1574 + snes - the SNES context 1575 - ftol - minimum function tolerance 1576 1577 Options Database Key: 1578 . -snes_fmin <ftol> - Sets ftol 1579 1580 Note: 1581 SNESSetMinimizationFunctionTolerance() is valid for SNES_UNCONSTRAINED_MINIMIZATION 1582 methods only. 1583 1584 Level: intermediate 1585 1586 .keywords: SNES, nonlinear, set, minimum, convergence, function, tolerance 1587 1588 .seealso: SNESSetTolerances(), SNESSetTrustRegionTolerance() 1589 @*/ 1590 int SNESSetMinimizationFunctionTolerance(SNES snes,double ftol) 1591 { 1592 PetscFunctionBegin; 1593 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1594 snes->fmin = ftol; 1595 PetscFunctionReturn(0); 1596 } 1597 /* 1598 Duplicate the lg monitors for SNES from KSP; for some reason with 1599 dynamic libraries things don't work under Sun4 if we just use 1600 macros instead of functions 1601 */ 1602 #undef __FUNC__ 1603 #define __FUNC__ "SNESLGMonitor" 1604 int SNESLGMonitor(SNES snes,int it,double norm,void *ctx) 1605 { 1606 int ierr; 1607 1608 PetscFunctionBegin; 1609 ierr = KSPLGMonitor((KSP)snes,it,norm,ctx);CHKERRQ(ierr); 1610 PetscFunctionReturn(0); 1611 } 1612 1613 #undef __FUNC__ 1614 #define __FUNC__ "SNESLGMonitorCreate" 1615 int SNESLGMonitorCreate(char *host,char *label,int x,int y,int m,int n, DrawLG *draw) 1616 { 1617 int ierr; 1618 1619 PetscFunctionBegin; 1620 ierr = KSPLGMonitorCreate(host,label,x,y,m,n,draw);CHKERRQ(ierr); 1621 PetscFunctionReturn(0); 1622 } 1623 1624 #undef __FUNC__ 1625 #define __FUNC__ "SNESLGMonitorDestroy" 1626 int SNESLGMonitorDestroy(DrawLG draw) 1627 { 1628 int ierr; 1629 1630 PetscFunctionBegin; 1631 ierr = KSPLGMonitorDestroy(draw);CHKERRQ(ierr); 1632 PetscFunctionReturn(0); 1633 } 1634 1635 /* ------------ Routines to set performance monitoring options ----------- */ 1636 1637 #undef __FUNC__ 1638 #define __FUNC__ "SNESSetMonitor" 1639 /*@C 1640 SNESSetMonitor - Sets an ADDITIONAL function that is to be used at every 1641 iteration of the nonlinear solver to display the iteration's 1642 progress. 1643 1644 Collective on SNES 1645 1646 Input Parameters: 1647 + snes - the SNES context 1648 . func - monitoring routine 1649 . mctx - [optional] user-defined context for private data for the 1650 monitor routine (may be PETSC_NULL) 1651 - monitordestroy - options routine that frees monitor context 1652 1653 Calling sequence of func: 1654 $ int func(SNES snes,int its, double norm,void *mctx) 1655 1656 + snes - the SNES context 1657 . its - iteration number 1658 . norm - 2-norm function value (may be estimated) 1659 for SNES_NONLINEAR_EQUATIONS methods 1660 . norm - 2-norm gradient value (may be estimated) 1661 for SNES_UNCONSTRAINED_MINIMIZATION methods 1662 - mctx - [optional] monitoring context 1663 1664 Options Database Keys: 1665 + -snes_monitor - sets SNESDefaultMonitor() 1666 . -snes_xmonitor - sets line graph monitor, 1667 uses SNESLGMonitorCreate() 1668 _ -snes_cancelmonitors - cancels all monitors that have 1669 been hardwired into a code by 1670 calls to SNESSetMonitor(), but 1671 does not cancel those set via 1672 the options database. 1673 1674 Notes: 1675 Several different monitoring routines may be set by calling 1676 SNESSetMonitor() multiple times; all will be called in the 1677 order in which they were set. 1678 1679 Level: intermediate 1680 1681 .keywords: SNES, nonlinear, set, monitor 1682 1683 .seealso: SNESDefaultMonitor(), SNESClearMonitor() 1684 @*/ 1685 int SNESSetMonitor( SNES snes, int (*func)(SNES,int,double,void*),void *mctx,int (*monitordestroy)(void *)) 1686 { 1687 PetscFunctionBegin; 1688 if (snes->numbermonitors >= MAXSNESMONITORS) { 1689 SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,0,"Too many monitors set"); 1690 } 1691 1692 snes->monitor[snes->numbermonitors] = func; 1693 snes->monitordestroy[snes->numbermonitors] = monitordestroy; 1694 snes->monitorcontext[snes->numbermonitors++] = (void*)mctx; 1695 PetscFunctionReturn(0); 1696 } 1697 1698 #undef __FUNC__ 1699 #define __FUNC__ "SNESClearMonitor" 1700 /*@C 1701 SNESClearMonitor - Clears all the monitor functions for a SNES object. 1702 1703 Collective on SNES 1704 1705 Input Parameters: 1706 . snes - the SNES context 1707 1708 Options Database: 1709 . -snes_cancelmonitors - cancels all monitors that have been hardwired 1710 into a code by calls to SNESSetMonitor(), but does not cancel those 1711 set via the options database 1712 1713 Notes: 1714 There is no way to clear one specific monitor from a SNES object. 1715 1716 Level: intermediate 1717 1718 .keywords: SNES, nonlinear, set, monitor 1719 1720 .seealso: SNESDefaultMonitor(), SNESSetMonitor() 1721 @*/ 1722 int SNESClearMonitor( SNES snes ) 1723 { 1724 PetscFunctionBegin; 1725 snes->numbermonitors = 0; 1726 PetscFunctionReturn(0); 1727 } 1728 1729 #undef __FUNC__ 1730 #define __FUNC__ "SNESSetConvergenceTest" 1731 /*@C 1732 SNESSetConvergenceTest - Sets the function that is to be used 1733 to test for convergence of the nonlinear iterative solution. 1734 1735 Collective on SNES 1736 1737 Input Parameters: 1738 + snes - the SNES context 1739 . func - routine to test for convergence 1740 - cctx - [optional] context for private data for the convergence routine 1741 (may be PETSC_NULL) 1742 1743 Calling sequence of func: 1744 $ int func (SNES snes,double xnorm,double gnorm,double f,void *cctx) 1745 1746 + snes - the SNES context 1747 . cctx - [optional] convergence context 1748 . xnorm - 2-norm of current iterate 1749 . gnorm - 2-norm of current step (SNES_NONLINEAR_EQUATIONS methods) 1750 . f - 2-norm of function (SNES_NONLINEAR_EQUATIONS methods) 1751 . gnorm - 2-norm of current gradient (SNES_UNCONSTRAINED_MINIMIZATION methods) 1752 - f - function value (SNES_UNCONSTRAINED_MINIMIZATION methods) 1753 1754 Level: advanced 1755 1756 .keywords: SNES, nonlinear, set, convergence, test 1757 1758 .seealso: SNESConverged_EQ_LS(), SNESConverged_EQ_TR(), 1759 SNESConverged_UM_LS(), SNESConverged_UM_TR() 1760 @*/ 1761 int SNESSetConvergenceTest(SNES snes,int (*func)(SNES,double,double,double,void*),void *cctx) 1762 { 1763 PetscFunctionBegin; 1764 (snes)->converged = func; 1765 (snes)->cnvP = cctx; 1766 PetscFunctionReturn(0); 1767 } 1768 1769 #undef __FUNC__ 1770 #define __FUNC__ "SNESSetConvergenceHistory" 1771 /*@ 1772 SNESSetConvergenceHistory - Sets the array used to hold the convergence history. 1773 1774 Collective on SNES 1775 1776 Input Parameters: 1777 + snes - iterative context obtained from SNESCreate() 1778 . a - array to hold history 1779 . its - integer array holds the number of linear iterations (or 1780 negative if not converged) for each solve. 1781 . na - size of a and its 1782 - reset - PETSC_TRUTH indicates each new nonlinear solve resets the history counter to zero, 1783 else it continues storing new values for new nonlinear solves after the old ones 1784 1785 Notes: 1786 If set, this array will contain the function norms (for 1787 SNES_NONLINEAR_EQUATIONS methods) or gradient norms 1788 (for SNES_UNCONSTRAINED_MINIMIZATION methods) computed 1789 at each step. 1790 1791 This routine is useful, e.g., when running a code for purposes 1792 of accurate performance monitoring, when no I/O should be done 1793 during the section of code that is being timed. 1794 1795 Level: intermediate 1796 1797 .keywords: SNES, set, convergence, history 1798 1799 .seealso: SNESGetConvergenceHistory() 1800 1801 @*/ 1802 int SNESSetConvergenceHistory(SNES snes, double *a, int *its,int na,PetscTruth reset) 1803 { 1804 PetscFunctionBegin; 1805 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1806 if (na) PetscValidScalarPointer(a); 1807 snes->conv_hist = a; 1808 snes->conv_hist_its = its; 1809 snes->conv_hist_max = na; 1810 snes->conv_hist_reset = reset; 1811 PetscFunctionReturn(0); 1812 } 1813 1814 #undef __FUNC__ 1815 #define __FUNC__ "SNESGetConvergenceHistory" 1816 /*@C 1817 SNESGetConvergenceHistory - Gets the array used to hold the convergence history. 1818 1819 Collective on SNES 1820 1821 Input Parameter: 1822 . snes - iterative context obtained from SNESCreate() 1823 1824 Output Parameters: 1825 . a - array to hold history 1826 . its - integer array holds the number of linear iterations (or 1827 negative if not converged) for each solve. 1828 - na - size of a and its 1829 1830 Notes: 1831 The calling sequence for this routine in Fortran is 1832 $ call SNESGetConvergenceHistory(SNES snes, integer na, integer ierr) 1833 1834 This routine is useful, e.g., when running a code for purposes 1835 of accurate performance monitoring, when no I/O should be done 1836 during the section of code that is being timed. 1837 1838 Level: intermediate 1839 1840 .keywords: SNES, get, convergence, history 1841 1842 .seealso: SNESSetConvergencHistory() 1843 1844 @*/ 1845 int SNESGetConvergenceHistory(SNES snes, double **a, int **its,int *na) 1846 { 1847 PetscFunctionBegin; 1848 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1849 if (a) *a = snes->conv_hist; 1850 if (its) *its = snes->conv_hist_its; 1851 if (na) *na = snes->conv_hist_len; 1852 PetscFunctionReturn(0); 1853 } 1854 1855 #undef __FUNC__ 1856 #define __FUNC__ "SNESScaleStep_Private" 1857 /* 1858 SNESScaleStep_Private - Scales a step so that its length is less than the 1859 positive parameter delta. 1860 1861 Input Parameters: 1862 + snes - the SNES context 1863 . y - approximate solution of linear system 1864 . fnorm - 2-norm of current function 1865 - delta - trust region size 1866 1867 Output Parameters: 1868 + gpnorm - predicted function norm at the new point, assuming local 1869 linearization. The value is zero if the step lies within the trust 1870 region, and exceeds zero otherwise. 1871 - ynorm - 2-norm of the step 1872 1873 Note: 1874 For non-trust region methods such as SNES_EQ_LS, the parameter delta 1875 is set to be the maximum allowable step size. 1876 1877 .keywords: SNES, nonlinear, scale, step 1878 */ 1879 int SNESScaleStep_Private(SNES snes,Vec y,double *fnorm,double *delta, 1880 double *gpnorm,double *ynorm) 1881 { 1882 double norm; 1883 Scalar cnorm; 1884 int ierr; 1885 1886 PetscFunctionBegin; 1887 ierr = VecNorm(y,NORM_2, &norm );CHKERRQ(ierr); 1888 if (norm > *delta) { 1889 norm = *delta/norm; 1890 *gpnorm = (1.0 - norm)*(*fnorm); 1891 cnorm = norm; 1892 VecScale( &cnorm, y ); 1893 *ynorm = *delta; 1894 } else { 1895 *gpnorm = 0.0; 1896 *ynorm = norm; 1897 } 1898 PetscFunctionReturn(0); 1899 } 1900 1901 #undef __FUNC__ 1902 #define __FUNC__ "SNESSolve" 1903 /*@ 1904 SNESSolve - Solves a nonlinear system. Call SNESSolve after calling 1905 SNESCreate() and optional routines of the form SNESSetXXX(). 1906 1907 Collective on SNES 1908 1909 Input Parameters: 1910 + snes - the SNES context 1911 - x - the solution vector 1912 1913 Output Parameter: 1914 . its - number of iterations until termination 1915 1916 Notes: 1917 The user should initialize the vector, x, with the initial guess 1918 for the nonlinear solve prior to calling SNESSolve. In particular, 1919 to employ an initial guess of zero, the user should explicitly set 1920 this vector to zero by calling VecSet(). 1921 1922 Level: beginner 1923 1924 .keywords: SNES, nonlinear, solve 1925 1926 .seealso: SNESCreate(), SNESDestroy() 1927 @*/ 1928 int SNESSolve(SNES snes,Vec x,int *its) 1929 { 1930 int ierr, flg; 1931 1932 PetscFunctionBegin; 1933 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1934 PetscValidIntPointer(its); 1935 if (!snes->setupcalled) {ierr = SNESSetUp(snes,x);CHKERRQ(ierr);} 1936 else {snes->vec_sol = snes->vec_sol_always = x;} 1937 if (snes->conv_hist_reset == PETSC_TRUE) snes->conv_hist_len = 0; 1938 PLogEventBegin(SNES_Solve,snes,0,0,0); 1939 snes->nfuncs = 0; snes->linear_its = 0; snes->nfailures = 0; 1940 ierr = (*(snes)->solve)(snes,its);CHKERRQ(ierr); 1941 PLogEventEnd(SNES_Solve,snes,0,0,0); 1942 ierr = OptionsHasName(PETSC_NULL,"-snes_view", &flg);CHKERRQ(ierr); 1943 if (flg) { ierr = SNESView(snes,VIEWER_STDOUT_WORLD);CHKERRQ(ierr); } 1944 PetscFunctionReturn(0); 1945 } 1946 1947 /* --------- Internal routines for SNES Package --------- */ 1948 1949 #undef __FUNC__ 1950 #define __FUNC__ "SNESSetType" 1951 /*@C 1952 SNESSetType - Sets the method for the nonlinear solver. 1953 1954 Collective on SNES 1955 1956 Input Parameters: 1957 + snes - the SNES context 1958 - method - a known method 1959 1960 Options Database Key: 1961 . -snes_type <method> - Sets the method; use -help for a list 1962 of available methods (for instance, ls or tr) 1963 1964 Notes: 1965 See "petsc/include/snes.h" for available methods (for instance) 1966 + SNES_EQ_LS - Newton's method with line search 1967 (systems of nonlinear equations) 1968 . SNES_EQ_TR - Newton's method with trust region 1969 (systems of nonlinear equations) 1970 . SNES_UM_TR - Newton's method with trust region 1971 (unconstrained minimization) 1972 - SNES_UM_LS - Newton's method with line search 1973 (unconstrained minimization) 1974 1975 Normally, it is best to use the SNESSetFromOptions() command and then 1976 set the SNES solver type from the options database rather than by using 1977 this routine. Using the options database provides the user with 1978 maximum flexibility in evaluating the many nonlinear solvers. 1979 The SNESSetType() routine is provided for those situations where it 1980 is necessary to set the nonlinear solver independently of the command 1981 line or options database. This might be the case, for example, when 1982 the choice of solver changes during the execution of the program, 1983 and the user's application is taking responsibility for choosing the 1984 appropriate method. In other words, this routine is not for beginners. 1985 1986 Level: intermediate 1987 1988 .keywords: SNES, set, method 1989 @*/ 1990 int SNESSetType(SNES snes,SNESType method) 1991 { 1992 int ierr; 1993 int (*r)(SNES); 1994 1995 PetscFunctionBegin; 1996 PetscValidHeaderSpecific(snes,SNES_COOKIE); 1997 1998 if (PetscTypeCompare(snes->type_name,method)) PetscFunctionReturn(0); 1999 2000 if (snes->setupcalled) { 2001 ierr = (*(snes)->destroy)(snes);CHKERRQ(ierr); 2002 snes->data = 0; 2003 } 2004 2005 /* Get the function pointers for the iterative method requested */ 2006 if (!SNESRegisterAllCalled) {ierr = SNESRegisterAll(PETSC_NULL);CHKERRQ(ierr);} 2007 2008 ierr = FListFind(snes->comm, SNESList, method,(int (**)(void *)) &r );CHKERRQ(ierr); 2009 2010 if (!r) SETERRQ1(1,1,"Unable to find requested SNES type %s",method); 2011 2012 if (snes->data) {ierr = PetscFree(snes->data);CHKERRQ(ierr);} 2013 snes->data = 0; 2014 ierr = (*r)(snes);CHKERRQ(ierr); 2015 2016 if (snes->type_name) {ierr = PetscFree(snes->type_name);CHKERRQ(ierr);} 2017 snes->type_name = (char *) PetscMalloc((PetscStrlen(method)+1)*sizeof(char));CHKPTRQ(snes->type_name); 2018 ierr = PetscStrcpy(snes->type_name,method);CHKERRQ(ierr); 2019 snes->set_method_called = 1; 2020 2021 PetscFunctionReturn(0); 2022 } 2023 2024 2025 /* --------------------------------------------------------------------- */ 2026 #undef __FUNC__ 2027 #define __FUNC__ "SNESRegisterDestroy" 2028 /*@C 2029 SNESRegisterDestroy - Frees the list of nonlinear solvers that were 2030 registered by SNESRegister(). 2031 2032 Not Collective 2033 2034 Level: advanced 2035 2036 .keywords: SNES, nonlinear, register, destroy 2037 2038 .seealso: SNESRegisterAll(), SNESRegisterAll() 2039 @*/ 2040 int SNESRegisterDestroy(void) 2041 { 2042 int ierr; 2043 2044 PetscFunctionBegin; 2045 if (SNESList) { 2046 ierr = FListDestroy( SNESList );CHKERRQ(ierr); 2047 SNESList = 0; 2048 } 2049 SNESRegisterAllCalled = 0; 2050 PetscFunctionReturn(0); 2051 } 2052 2053 #undef __FUNC__ 2054 #define __FUNC__ "SNESGetType" 2055 /*@C 2056 SNESGetType - Gets the SNES method type and name (as a string). 2057 2058 Not Collective 2059 2060 Input Parameter: 2061 . snes - nonlinear solver context 2062 2063 Output Parameter: 2064 . method - SNES method (a charactor string) 2065 2066 Level: intermediate 2067 2068 .keywords: SNES, nonlinear, get, method, name 2069 @*/ 2070 int SNESGetType(SNES snes, SNESType *method) 2071 { 2072 PetscFunctionBegin; 2073 *method = snes->type_name; 2074 PetscFunctionReturn(0); 2075 } 2076 2077 #undef __FUNC__ 2078 #define __FUNC__ "SNESGetSolution" 2079 /*@C 2080 SNESGetSolution - Returns the vector where the approximate solution is 2081 stored. 2082 2083 Not Collective, but Vec is parallel if SNES is parallel 2084 2085 Input Parameter: 2086 . snes - the SNES context 2087 2088 Output Parameter: 2089 . x - the solution 2090 2091 Level: advanced 2092 2093 .keywords: SNES, nonlinear, get, solution 2094 2095 .seealso: SNESGetFunction(), SNESGetGradient(), SNESGetSolutionUpdate() 2096 @*/ 2097 int SNESGetSolution(SNES snes,Vec *x) 2098 { 2099 PetscFunctionBegin; 2100 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2101 *x = snes->vec_sol_always; 2102 PetscFunctionReturn(0); 2103 } 2104 2105 #undef __FUNC__ 2106 #define __FUNC__ "SNESGetSolutionUpdate" 2107 /*@C 2108 SNESGetSolutionUpdate - Returns the vector where the solution update is 2109 stored. 2110 2111 Not Collective, but Vec is parallel if SNES is parallel 2112 2113 Input Parameter: 2114 . snes - the SNES context 2115 2116 Output Parameter: 2117 . x - the solution update 2118 2119 Level: advanced 2120 2121 .keywords: SNES, nonlinear, get, solution, update 2122 2123 .seealso: SNESGetSolution(), SNESGetFunction 2124 @*/ 2125 int SNESGetSolutionUpdate(SNES snes,Vec *x) 2126 { 2127 PetscFunctionBegin; 2128 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2129 *x = snes->vec_sol_update_always; 2130 PetscFunctionReturn(0); 2131 } 2132 2133 #undef __FUNC__ 2134 #define __FUNC__ "SNESGetFunction" 2135 /*@C 2136 SNESGetFunction - Returns the vector where the function is stored. 2137 2138 Not Collective, but Vec is parallel if SNES is parallel 2139 2140 Input Parameter: 2141 . snes - the SNES context 2142 2143 Output Parameter: 2144 . r - the function 2145 2146 Notes: 2147 SNESGetFunction() is valid for SNES_NONLINEAR_EQUATIONS methods only 2148 Analogous routines for SNES_UNCONSTRAINED_MINIMIZATION methods are 2149 SNESGetMinimizationFunction() and SNESGetGradient(); 2150 2151 Level: advanced 2152 2153 .keywords: SNES, nonlinear, get, function 2154 2155 .seealso: SNESSetFunction(), SNESGetSolution(), SNESGetMinimizationFunction(), 2156 SNESGetGradient() 2157 @*/ 2158 int SNESGetFunction(SNES snes,Vec *r) 2159 { 2160 PetscFunctionBegin; 2161 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2162 if (snes->method_class != SNES_NONLINEAR_EQUATIONS) { 2163 SETERRQ(PETSC_ERR_ARG_WRONG,0,"For SNES_NONLINEAR_EQUATIONS only"); 2164 } 2165 *r = snes->vec_func_always; 2166 PetscFunctionReturn(0); 2167 } 2168 2169 #undef __FUNC__ 2170 #define __FUNC__ "SNESGetGradient" 2171 /*@C 2172 SNESGetGradient - Returns the vector where the gradient is stored. 2173 2174 Not Collective, but Vec is parallel if SNES is parallel 2175 2176 Input Parameter: 2177 . snes - the SNES context 2178 2179 Output Parameter: 2180 . r - the gradient 2181 2182 Notes: 2183 SNESGetGradient() is valid for SNES_UNCONSTRAINED_MINIMIZATION methods 2184 only. An analogous routine for SNES_NONLINEAR_EQUATIONS methods is 2185 SNESGetFunction(). 2186 2187 Level: advanced 2188 2189 .keywords: SNES, nonlinear, get, gradient 2190 2191 .seealso: SNESGetMinimizationFunction(), SNESGetSolution(), SNESGetFunction() 2192 @*/ 2193 int SNESGetGradient(SNES snes,Vec *r) 2194 { 2195 PetscFunctionBegin; 2196 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2197 if (snes->method_class != SNES_UNCONSTRAINED_MINIMIZATION) { 2198 SETERRQ(PETSC_ERR_ARG_WRONG,0,"For SNES_UNCONSTRAINED_MINIMIZATION only"); 2199 } 2200 *r = snes->vec_func_always; 2201 PetscFunctionReturn(0); 2202 } 2203 2204 #undef __FUNC__ 2205 #define __FUNC__ "SNESGetMinimizationFunction" 2206 /*@ 2207 SNESGetMinimizationFunction - Returns the scalar function value for 2208 unconstrained minimization problems. 2209 2210 Not Collective 2211 2212 Input Parameter: 2213 . snes - the SNES context 2214 2215 Output Parameter: 2216 . r - the function 2217 2218 Notes: 2219 SNESGetMinimizationFunction() is valid for SNES_UNCONSTRAINED_MINIMIZATION 2220 methods only. An analogous routine for SNES_NONLINEAR_EQUATIONS methods is 2221 SNESGetFunction(). 2222 2223 Level: advanced 2224 2225 .keywords: SNES, nonlinear, get, function 2226 2227 .seealso: SNESGetGradient(), SNESGetSolution(), SNESGetFunction() 2228 @*/ 2229 int SNESGetMinimizationFunction(SNES snes,double *r) 2230 { 2231 PetscFunctionBegin; 2232 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2233 PetscValidScalarPointer(r); 2234 if (snes->method_class != SNES_UNCONSTRAINED_MINIMIZATION) { 2235 SETERRQ(PETSC_ERR_ARG_WRONG,0,"For SNES_UNCONSTRAINED_MINIMIZATION only"); 2236 } 2237 *r = snes->fc; 2238 PetscFunctionReturn(0); 2239 } 2240 2241 #undef __FUNC__ 2242 #define __FUNC__ "SNESSetOptionsPrefix" 2243 /*@C 2244 SNESSetOptionsPrefix - Sets the prefix used for searching for all 2245 SNES options in the database. 2246 2247 Collective on SNES 2248 2249 Input Parameter: 2250 + snes - the SNES context 2251 - prefix - the prefix to prepend to all option names 2252 2253 Notes: 2254 A hyphen (-) must NOT be given at the beginning of the prefix name. 2255 The first character of all runtime options is AUTOMATICALLY the hyphen. 2256 2257 Level: advanced 2258 2259 .keywords: SNES, set, options, prefix, database 2260 2261 .seealso: SNESSetFromOptions() 2262 @*/ 2263 int SNESSetOptionsPrefix(SNES snes,char *prefix) 2264 { 2265 int ierr; 2266 2267 PetscFunctionBegin; 2268 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2269 ierr = PetscObjectSetOptionsPrefix((PetscObject)snes, prefix);CHKERRQ(ierr); 2270 ierr = SLESSetOptionsPrefix(snes->sles,prefix);CHKERRQ(ierr); 2271 PetscFunctionReturn(0); 2272 } 2273 2274 #undef __FUNC__ 2275 #define __FUNC__ "SNESAppendOptionsPrefix" 2276 /*@C 2277 SNESAppendOptionsPrefix - Appends to the prefix used for searching for all 2278 SNES options in the database. 2279 2280 Collective on SNES 2281 2282 Input Parameters: 2283 + snes - the SNES context 2284 - prefix - the prefix to prepend to all option names 2285 2286 Notes: 2287 A hyphen (-) must NOT be given at the beginning of the prefix name. 2288 The first character of all runtime options is AUTOMATICALLY the hyphen. 2289 2290 Level: advanced 2291 2292 .keywords: SNES, append, options, prefix, database 2293 2294 .seealso: SNESGetOptionsPrefix() 2295 @*/ 2296 int SNESAppendOptionsPrefix(SNES snes,char *prefix) 2297 { 2298 int ierr; 2299 2300 PetscFunctionBegin; 2301 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2302 ierr = PetscObjectAppendOptionsPrefix((PetscObject)snes, prefix);CHKERRQ(ierr); 2303 ierr = SLESAppendOptionsPrefix(snes->sles,prefix);CHKERRQ(ierr); 2304 PetscFunctionReturn(0); 2305 } 2306 2307 #undef __FUNC__ 2308 #define __FUNC__ "SNESGetOptionsPrefix" 2309 /*@C 2310 SNESGetOptionsPrefix - Sets the prefix used for searching for all 2311 SNES options in the database. 2312 2313 Not Collective 2314 2315 Input Parameter: 2316 . snes - the SNES context 2317 2318 Output Parameter: 2319 . prefix - pointer to the prefix string used 2320 2321 Notes: On the fortran side, the user should pass in a string 'prifix' of 2322 sufficient length to hold the prefix. 2323 2324 Level: advanced 2325 2326 .keywords: SNES, get, options, prefix, database 2327 2328 .seealso: SNESAppendOptionsPrefix() 2329 @*/ 2330 int SNESGetOptionsPrefix(SNES snes,char **prefix) 2331 { 2332 int ierr; 2333 2334 PetscFunctionBegin; 2335 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2336 ierr = PetscObjectGetOptionsPrefix((PetscObject)snes, prefix);CHKERRQ(ierr); 2337 PetscFunctionReturn(0); 2338 } 2339 2340 #undef __FUNC__ 2341 #define __FUNC__ "SNESPrintHelp" 2342 /*@ 2343 SNESPrintHelp - Prints all options for the SNES component. 2344 2345 Collective on SNES 2346 2347 Input Parameter: 2348 . snes - the SNES context 2349 2350 Options Database Keys: 2351 + -help - Prints SNES options 2352 - -h - Prints SNES options 2353 2354 Level: beginner 2355 2356 .keywords: SNES, nonlinear, help 2357 2358 .seealso: SNESSetFromOptions() 2359 @*/ 2360 int SNESPrintHelp(SNES snes) 2361 { 2362 char p[64]; 2363 SNES_KSP_EW_ConvCtx *kctx; 2364 int ierr; 2365 2366 PetscFunctionBegin; 2367 PetscValidHeaderSpecific(snes,SNES_COOKIE); 2368 2369 ierr = PetscStrcpy(p,"-");CHKERRQ(ierr); 2370 if (snes->prefix) PetscStrcat(p, snes->prefix); 2371 2372 kctx = (SNES_KSP_EW_ConvCtx *)snes->kspconvctx; 2373 2374 if (!SNESRegisterAllCalled) {ierr = SNESRegisterAll(PETSC_NULL);CHKERRQ(ierr);} 2375 ierr = (*PetscHelpPrintf)(snes->comm,"SNES options ------------------------------------------------\n");CHKERRQ(ierr); 2376 ierr = FListPrintTypes(snes->comm,stdout,snes->prefix,"snes_type",SNESList);CHKERRQ(ierr); 2377 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_view: view SNES info after each nonlinear solve\n",p);CHKERRQ(ierr); 2378 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_max_it <its>: max iterations (default %d)\n",p,snes->max_its);CHKERRQ(ierr); 2379 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_max_funcs <maxf>: max function evals (default %d)\n",p,snes->max_funcs);CHKERRQ(ierr); 2380 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_stol <stol>: successive step tolerance (default %g)\n",p,snes->xtol);CHKERRQ(ierr); 2381 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_atol <atol>: absolute tolerance (default %g)\n",p,snes->atol);CHKERRQ(ierr); 2382 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_rtol <rtol>: relative tolerance (default %g)\n",p,snes->rtol);CHKERRQ(ierr); 2383 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_trtol <trtol>: trust region parameter tolerance (default %g)\n",p,snes->deltatol);CHKERRQ(ierr); 2384 ierr = (*PetscHelpPrintf)(snes->comm," SNES Monitoring Options: Choose any of the following\n");CHKERRQ(ierr); 2385 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_cancelmonitors: cancels all monitors hardwired in code\n",p);CHKERRQ(ierr); 2386 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_monitor: use default SNES convergence monitor, prints\n\ 2387 residual norm at each iteration.\n",p);CHKERRQ(ierr); 2388 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_smonitor: same as the above, but prints fewer digits of the\n\ 2389 residual norm for small residual norms. This is useful to conceal\n\ 2390 meaningless digits that may be different on different machines.\n",p);CHKERRQ(ierr); 2391 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_xmonitor [x,y,w,h]: use X graphics convergence monitor\n",p);CHKERRQ(ierr); 2392 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_vecmonitor: plots solution at each iteration \n",p);CHKERRQ(ierr); 2393 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_vecmonitor_update: plots update to solution at each iteration \n",p);CHKERRQ(ierr); 2394 if (snes->type == SNES_NONLINEAR_EQUATIONS) { 2395 ierr = (*PetscHelpPrintf)(snes->comm, 2396 " Options for solving systems of nonlinear equations only:\n");CHKERRQ(ierr); 2397 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_fd: use finite differences for Jacobian\n",p);CHKERRQ(ierr); 2398 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_mf: use matrix-free Jacobian\n",p);CHKERRQ(ierr); 2399 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_mf_operator:use matrix-free Jacobian and user-provided preconditioning matrix\n",p);CHKERRQ(ierr); 2400 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_mf_ksp_monitor - if using matrix-free multiply then prints h at each KSP iteration\n",p);CHKERRQ(ierr); 2401 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_no_convergence_test: Do not test for convergence, always run to SNES max its\n",p);CHKERRQ(ierr); 2402 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_ksp_ew_conv: use Eisenstat-Walker computation of KSP rtol. Params are:\n",p);CHKERRQ(ierr); 2403 ierr = (*PetscHelpPrintf)(snes->comm, 2404 " %ssnes_ksp_ew_version <version> (1 or 2, default is %d)\n",p,kctx->version);CHKERRQ(ierr); 2405 ierr = (*PetscHelpPrintf)(snes->comm, 2406 " %ssnes_ksp_ew_rtol0 <rtol0> (0 <= rtol0 < 1, default %g)\n",p,kctx->rtol_0);CHKERRQ(ierr); 2407 ierr = (*PetscHelpPrintf)(snes->comm, 2408 " %ssnes_ksp_ew_rtolmax <rtolmax> (0 <= rtolmax < 1, default %g)\n",p,kctx->rtol_max);CHKERRQ(ierr); 2409 ierr = (*PetscHelpPrintf)(snes->comm, 2410 " %ssnes_ksp_ew_gamma <gamma> (0 <= gamma <= 1, default %g)\n",p,kctx->gamma);CHKERRQ(ierr); 2411 ierr = (*PetscHelpPrintf)(snes->comm, 2412 " %ssnes_ksp_ew_alpha <alpha> (1 < alpha <= 2, default %g)\n",p,kctx->alpha);CHKERRQ(ierr); 2413 ierr = (*PetscHelpPrintf)(snes->comm, 2414 " %ssnes_ksp_ew_alpha2 <alpha2> (default %g)\n",p,kctx->alpha2);CHKERRQ(ierr); 2415 ierr = (*PetscHelpPrintf)(snes->comm, 2416 " %ssnes_ksp_ew_threshold <threshold> (0 < threshold < 1, default %g)\n",p,kctx->threshold);CHKERRQ(ierr); 2417 } else if (snes->type == SNES_UNCONSTRAINED_MINIMIZATION) { 2418 ierr = (*PetscHelpPrintf)(snes->comm," Options for solving unconstrained minimization problems only:\n");CHKERRQ(ierr); 2419 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_fmin <ftol>: minimum function tolerance (default %g)\n",p,snes->fmin);CHKERRQ(ierr); 2420 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_fd: use finite differences for Hessian\n",p);CHKERRQ(ierr); 2421 ierr = (*PetscHelpPrintf)(snes->comm," %ssnes_mf: use matrix-free Hessian\n",p);CHKERRQ(ierr); 2422 } 2423 ierr = (*PetscHelpPrintf)(snes->comm," Run program with -help %ssnes_type <method> for help on ",p);CHKERRQ(ierr); 2424 ierr = (*PetscHelpPrintf)(snes->comm,"a particular method\n");CHKERRQ(ierr); 2425 if (snes->printhelp) { 2426 ierr = (*snes->printhelp)(snes,p);CHKERRQ(ierr); 2427 } 2428 PetscFunctionReturn(0); 2429 } 2430 2431 /*MC 2432 SNESRegister - Adds a method to the nonlinear solver package. 2433 2434 Synopsis: 2435 SNESRegister(char *name_solver,char *path,char *name_create,int (*routine_create)(SNES)) 2436 2437 Not collective 2438 2439 Input Parameters: 2440 + name_solver - name of a new user-defined solver 2441 . path - path (either absolute or relative) the library containing this solver 2442 . name_create - name of routine to create method context 2443 - routine_create - routine to create method context 2444 2445 Notes: 2446 SNESRegister() may be called multiple times to add several user-defined solvers. 2447 2448 If dynamic libraries are used, then the fourth input argument (routine_create) 2449 is ignored. 2450 2451 Sample usage: 2452 .vb 2453 SNESRegister("my_solver",/home/username/my_lib/lib/libg/solaris/mylib.a, 2454 "MySolverCreate",MySolverCreate); 2455 .ve 2456 2457 Then, your solver can be chosen with the procedural interface via 2458 $ SNESSetType(snes,"my_solver") 2459 or at runtime via the option 2460 $ -snes_type my_solver 2461 2462 Level: advanced 2463 2464 $PETSC_ARCH, $PETSC_DIR, $PETSC_LDIR, and $BOPT occuring in pathname will be replaced with appropriate values. 2465 2466 .keywords: SNES, nonlinear, register 2467 2468 .seealso: SNESRegisterAll(), SNESRegisterDestroy() 2469 M*/ 2470 2471 #undef __FUNC__ 2472 #define __FUNC__ "SNESRegister_Private" 2473 int SNESRegister_Private(char *sname,char *path,char *name,int (*function)(SNES)) 2474 { 2475 char fullname[256]; 2476 int ierr; 2477 2478 PetscFunctionBegin; 2479 ierr = PetscStrcpy(fullname,path);CHKERRQ(ierr); 2480 PetscStrcat(fullname,":");PetscStrcat(fullname,name); 2481 ierr = FListAdd_Private(&SNESList,sname,fullname, (int (*)(void*))function);CHKERRQ(ierr); 2482 PetscFunctionReturn(0); 2483 } 2484