NewtonSolver¶

TACS Nonlinear Newton Solver¶

This is a fairly standard Newton solver with a critical point (or minimum energy) line search. The convergence of the linear solution in each iteration can be controlled adaptively using the Eisenstat-Walker method (specifically variant (b) described on page 50 of this paper by An, Mo and Liu)

Options¶

Options can be set using the NewtonSolver.setOption and NewtonSolver.setOptions methods. Current option values for a class instance can be printed out using the NewtonSolver.printOptions method. The following options, their default values and descriptions are listed below:

+----------------------------------------+
|     NewtonSolver default options:      |
+----------------------------------------+
'MaxIter': 40
	 Maximum number of Newton iterations.
'ForceFirstIter': False
	 Force the solver to perform the first Newton iteration, even if the convergence criteria are satisfied at the initial point.
'AbsTol': 1e-08
	 Convergence criteria for the nonlinear residual norm.
'RelTol': 1e-08
	 Relative convergence criteria for the nonlinear residual norm, norm is measured relative to that of the external load vector.
'DivergenceTol': 10000000000.0
	 Residual norm at which the nonlinear solver is jugded to have diverged
'AbsLinTol': 1e-12
	 Linear solver residual tolerance.
'RelLinTol': 1e-12
	 Linear solver relative residual tolerance.
'MaxLinIters': 0
	 If the linear solver takes more than this number of iterations to converge, the preconditioner is updated.
'UseEW': False
	 Flag for enabling use of adaptive linear solver convergence using the Eisenstat-Walker method.
'EWMaxTol': 0.01
	 Eisenstat-Walker max allowable linear solver tolerance.
'EWGamma': 1.0
	 Eisenstat-Walker gamma parameter.
'EWAlpha': 1.618033988749895
	 Eisenstat-Walker alpha parameter.
'UseLineSearch': True
	 Flag for using line search in the nonlinear solver.
'PrintLineSearchIters': False
	 Flag for printing out line search information.
'SkipFirstNLineSearch': 0
	 Skip the first N line searches. Setting this to 1 can improve the convergence speed of Newton solver, but also decreases robustness
'LineSearchMaxIter': 25
	 Maximum number of linesearch iterations.
'LineSearchExpectedDecrease': 0.0001
	 Minimum fraction of the expected decrease in the energy gradient during the linesearch. Should be between 0 and 1. Higher values should improve robustness at the expense of solution time.
'LineSearchMaxStep': 2.0
	 Maximum step size for the linesearch, as a fraction of the Newton step
'LineSearchMinStep': 0.01
	 Minimum step size for the linesearch, as a fraction of the Newton step
'LineSearchMaxStepChange': 0.5
	 Maximum change in the step size from one linesearch iteration to the next, can be useful in cases where secant method bounces between upper and lower step bounds.
'LineSearchFallbackStepLimit': 0.9
	 Often, the value of the merit function at the Newton step (alpha = 1.0), is orders of magnitude greater than at the start point. In these situations, the linesearch then tries to evaluate a point with a very small step size, which usually meets the expected decrease criteria but results in very slow progress of the Newton solver. To combat this, this value limits how far the linesearch can backtrack on the first iteration after evaluating alpha = 1. This has the effect of encouraging the linesearch to find larger steps that meet the expected decrease criterion, which results in faster convergence of the Newton solver.
'monitorVars': ['linSolverIters', 'linSolverRes', 'lineSearchStep', 'lineSearchIters']
	 List of variables to include in nonlinear solver monitor output. Choose from 'linSolverIters', 'linSolverRes', 'lineSearchStep', 'EWTol', and 'lineSearchIters'.

API Reference¶

class tacs.solvers.NewtonSolver(assembler: Assembler, setStateFunc: Callable, resFunc: Callable, jacFunc: Callable, pcUpdateFunc: Callable, linearSolver: KSM, stateVec: Vec | None = None, resVec: Vec | None = None, options: dict | None = None, comm: Comm | None = None)[source]¶

Create a Newton solver instance

Parameters:

assembler (tacs.TACS.Assembler) -- TACS assembler object related to the problem being solved, required in order for the solver to create it's own vectors
setStateFunc (function) -- Function to set the state vector, with signature setStateFunc(stateVec: tacs.TACS.Vec) -> None
resFunc (function) -- Function to evaluate the residual at the current state, with signature resFunc(resVec: tacs.TACS.Vec) -> None
jacFunc (function) -- Function to update the residual Jacobian at the current state, with signature jacFunc() -> None
pcUpdateFunc (function) -- Function to update the residual Jacobian preconditioner at the current state, with signature pcUpdateFunc() -> None
linearSolver (tacs.TACS.KSM) -- TACS linear solver object to use for the Newton solve, the linear solver owns the matrix and preconditioner
stateVec (tacs.TACS.Vec, optional) -- Vector to store the state in, by default the solver will create it's own but these can be passed to save additional allocations
resVec (tacs.TACS.Vec, optional) -- Vector to store the residual in, by default the solver will create it's own but these can be passed to save additional allocations
options (dict, optional) -- Dictionary holding solver-specific option parameters (case-insensitive)., by default None
comm (mpi4py.MPI.Intracomm, optional) -- The comm object on which to create the pyTACS object., by default mpi4py.MPI.COMM_WORLD

setOption(name, value)[source]¶

A thin wrapper around the base setOption method that makes necessary changes when certain options are changed

Parameters:

name (str) -- Name of option to modify
value (depends on option) -- New option value to set

getHistoryVariables() → Dict[str, Dict][source]¶

Get the variables to be stored in the solver history

This method allows for implementation of any logic that dictates any changes in the stored variables depending on the current options.

Returns:: Dictionary of solver variables, keys are the variable names, value is another dictionary with keys "type" and "print", where "type" is the data type of the variable and "print" is a boolean indicating whether or not to print the variable to the screen
Return type:: Dict[str, Dict]

setConvergenceTolerance(absTol: float | None = None, relTol: float | None = None) → None[source]¶

Set the convergence tolerance of the solver

Parameters:

absTol (float, optional) -- Absolute tolerance, not changed if no value is provided
relTol (float, optional) -- Relative tolerance, not changed if no value is provided

solve(u0: Vec | None = None, result: Vec | None = None) → None[source]¶

Solve the residual equations r(u) = 0

Parameters:

u0 (TACS vector, optional) -- Initial guess, by default uses the current state
result (TACS vector, optional) -- Vector in which to store the solution, by default None. The problem's state is updated with the solution whether or not this is provided.

dtype¶: alias of float64

property fatalFailure: bool¶

Whether the solver has failed, set as a property rather than an attribute so that it is read-only

Note that a fatalFailure is not the same as not converging, this flag is meant to reflect that there has been a fatal failure in the solver which requires a full reset

getOption(name)¶

Get a solver option value. The name is not case sensitive.

Parameters:: name (str) -- Name of option to get

property hasConverged: bool¶: Whether the solver has converged, set as a property rather than an attribute so that it is read-only

initializeSolve(u0: Vec | None = None) → None¶

Perform any initialization required before the solve

Parameters:: u0 (TACS vector, optional) -- Initial guess, by default uses the current state

property iterationCount: int¶: Number of iterations performed, set as a property rather than an attribute so that it is read-only

classmethod printDefaultOptions()¶: Prints a nicely formatted dictionary of all the default solver options to the stdout

printModifiedOptions()¶: Prints a nicely formatted table of all the options that have been modified from their defaults

printOptions()¶: Prints a nicely formatted dictionary of all the current solver options to the stdout on the root processor

reset() → None¶

Reset the solver

Currently this just zeros out the state vector, but more functionality may be added in future

setCallback(callback: Callable) → None¶

Set a callback function to be called at each iteration

Parameters:: callback (callable, optional) -- Callback function, should have the following signature: callback(solver: tacs.solver, u: tacs.TACS.Vec, res: tacs.TACS.Vec, monitorVars: dict) -> None Where: - solver is the solver object - u is the current state vector - res is the current residual vector - monitorVars is a dictionary of variables to monitor, which can be specified through the "nonlinearSolverMonitorVars" option

setOptions(options)¶

Set multiple solver options at once. The names are not case sensitive.

Parameters:: options (dict) -- Dictionary of option names and values to set

setRefNorm(norm: float) → None¶

Set the reference norm used to compute relative convergence measures

Parameters:: norm (float) -- Reference norm

NewtonSolver¶

TACS Nonlinear Newton Solver¶

Options¶

API Reference¶

Table of Contents

Previous topic

Next topic