Back to Input Deck Cards

NEWTON_SOLVER

Specifies Newton solver parameters associated with solving the nonlinear system of equations.

Required Cards:

NEWTON_SOLVER

Opens the Newton solver block.

Optional Cards:

Note: See process model cards for additional NEWTON_SOLVER cards that are process model specific.

Note: See the PETSc users manual for a more definitive explanation of the solver ATOL, DTOL, RTOL and STOL tolerances below.

Basic Settings

ATOL <float>

Declare convergence when the 2-norm of residual is less than ATOL \(\left(\|f(x_n)\|<\text{ATOL}\right)\). (default: \(10^{-50}\)).

CONVERGENCE_INFO

Opens a block for toggling ON/OFF convergence information in screen output (default: YES to all). See example below.

  • 2R, FNORM, 2NORMR - 2-norm of residual

  • 2X, XNORM, 2NORMX - 2-norm of solution

  • 2U, UNORM, 2NORMU - 2-norm of update

  • IR, INORMR - inifinity norm of residual

  • IU, INORMU - inifinity norm of update

DTOL <float>

Declare divergence (cut the time step) when the 2-norm of the residual is greater than DTOL times the 2-norm of the initial residual \(\left(\frac{\|f(x_n)\|}{\|f(x_0)\|}>\text{DTOL}\right)\). (default: \(10^{4}\)).

MAXIMUM_NUMBER_OF_ITERATIONS <int>

Maximum number of Newton iterations before reporting failed convergence.

NO_PRINT_CONVERGENCE

Toggle off printing of convergence information.

NTRDC_OPTIONS or NTR_OPTIONS

Opens a block for trust-region options and parameters (SNES_TYPE NTRDC or SNES_TYPE NTR required)

  • TR_TOL - trust-region tolerance (default: \(1.0^{-12}\))

  • ETA1 - trust-region parameter \(0.0 \le \eta_1 \le \eta_2\), \(\rho \ge \eta_1\) breaks out of the inner iteration (default: \(\eta_1=0.001\))

  • ETA2 - trust-region parameter \(0.0 \le \eta_1 \le \eta_2\), \(\rho \ge \eta_2\) shrinks the trust-region (default: \(\eta_2=0.25\))

  • ETA3 - trust-region parameter \(\eta_3 > \eta_2\), \(\rho \ge \eta_3\) expands the trust-region (default: \(\eta_3=0.75\))

  • T1 - trust-region parameter, shrinking factor of trust-region (default: 0.25)

  • T2 - trust-region parameter, initial size of trust-region, \(\Delta_0*\|x\|_2\) (default: 0.1)

  • DELTA_M - trust-region parameter, max size of trust-region, \(\Delta_M*\|x\|_2\) (default: 0.5)

  • DELTA_0 - trust-region parameter, initial size of trust-region, \(\Delta_0*\|x\|_2\) (default: 0.1)

  • AUTO_SCALE - TRUE enables solution update scaling meaning all types of unknowns are equally treated when evaluating solution update (recommended for WIPP-FLOW, TH); FALSE disables solution update scaling meaning that solution update evaluation will focus more on pressure than other unknowns (recommended for GENERAL, HYDRATE).

  • AUTO_SCALE_MAX - used with AUTO_SCALE, caps the maximum auto-scaling factor

PRINT_LINEAR_ITERATIONS

Prints the number of linear iterations for each Newton iteration to the screen.

RTOL <float>

Declare convergence when the 2-norm of the residual is less than RTOL times the 2-norm of the initial residual \(\left(\frac{\|f(x_n)\|}{\|f(x_0)\|}<\text{RTOL}\right)\). (default: \(10^{-8}\)).

SNES_TYPE <string>

The default is LINE_SEARCH (Basic, see PETSc documenetation) from PETSc which is Newton-Raphson nonlinear solver. NTRDC is the Newton Trust-Region Dogleg-Cauchy nonlinear solver, and NTR is the Newton Trust-Region nonlinear solver. The difference between NTRDC and NTR is that NTRDC adds steepest-descent solution update to the Newton solution iff it optimizes better than Newton solution alone within the trust-region. NTR only applies Newton solution update and it is truncated by the trust-region. NTRDC MAY perform better with LESS phase state change simulations for GENERAL MODE.

STOL <float>

Declare convergence when the 2-norm of the update divided by the 2-norm of the solution is less than STOL \(\left(\frac{\|x_n-x_{n-1}\|}{\|x_{n-1}\|}<\text{STOL}\right)\). (default: \(10^{-8}\)).

VERBOSE_LOGGING

Prints additional convergence information to screen.

MATRIX_TYPE <string>

Format of main solver matrix. PETSc Mat (i.e. AIJ, BAIJ, or HYPRESTRUCT).

MAXF <int>

Maximum number of function evaluations before reporting failed convergence.

MAX_NORM <float>

Declare divergence (cut the time step) when the infinity norm of the residual is greater than MAX_NORM \(\left( \| f(x_n) \|_{inf} > \text{MAX_NORM} \right)\). (default: \(10^{20}\)).

MINIMUM_NUMBER_OF_ITERATIONS <int>

Newton solver convergence requires at least MINIMUM_NUMBER_OF_ITERATIONS.

NO_FORCE_ITERATION

Toggle off the forcing of at least 1 linear iteration. The default is to force at least 1 linear iteration. In a quasi-stationary state, the initial residual may be sufficiently small for convergence, but often it is better to force at least one iteration.

NO_INFINITY_NORM

Toggle off calculation of infinity norm on residual and update vectors. The default is to calculate the infinity norm.

PRECONDITIONER_MATRIX_TYPE <string >

Format of preconditioning matrix. PETSc Mat (i.e. AIJ, BAIJ, or HYPRESTRUCT). Default is same as solver.

PRINT_DETAILED_CONVERGENCE

Toggle on printing of detailed convergence information.

Examples

NEWTON_SOLVER
  ITOL_UPDATE 1.d0
/

NEWTON_SOLVER
  PRECONDITIONER_MATRIX_TYPE AIJ
  RTOL 1.d-8
  ATOL 1.d-8
  STOL 1.d-30
  ITOL_UPDATE 1.d0
/

NEWTON_SOLVER
  PRECONDITIONER_MATRIX_TYPE AIJ
  RTOL 1.d-12
  ATOL 1.d-12
  STOL 1.d-30
  MAXIMUM_NUMBER_OF_ITERATIONS 10
  NO_INFINITY_NORM
  NO_PRINT_CONVERGENCE
/

NEWTON_SOLVER
  CONVERGENCE_INFO
    2R YES
    2X NO
    2U NO
    IR NO
    IU YES
  /
/

NEWTON_SOLVER
  MAXIMUM_NUMBER_OF_ITERATIONS  15
  SNES_TYPE NTRDC # ntrdc solver
/

NEWTON_SOLVER
  SNES_TYPE NTR # ntr solver
  NTR_OPTIONS
    AUTO_SCALE FALSE # for general mode
    ETA1 0.001 # trust-region parameter
    T1 0.25 # tr shrink factor
    T2 2.00 # tr expansion factor
  END
/