====== Managing N.-R. Iterations ======

Mechanical iterations parameters are imposed by functions associated to ''metafor.getMechanicalIterationManager()'', when thermal iterations parameters are imposed by functions associated to  ''metafor.getThermalIterationManager()''.

    mim = metafor.getMechanicalIterationManager() 
    tim = metafor.getThermalIterationManager()
    
    mim/tim.setResidualComputationMethod(meth)    
    mim/tim.setVerbose()     
    mim/tim.setResidualTolerance(prec)
    mim/tim.setMaxNbOfIterations(itma)
    mim/tim.setNbOfIterationsForStiffUpdate(irea)
    mim/tim.setMaxNbOfLineSearchIterations(lsma)
    mim/tim.setLineSearchTolerance1(lsp1)
    mim/tim.setLineSearchTolerance2(lsp2)
    mim.setPredictorComputationMethod(predMeth)
    mim.setConstrainedDofsVAComputationMethod(VACMeth)
    mim/tim.setPreviousResidualsDecreaseCriterion()
    mim/tim.setCpuDependency(cpuDep)
    mim/tim.setForceOneIte(bool)  
where ''meth'' defines the method used to compute the $Residual$.

=== Method1ResidualComputation(limitNormFactor) ===
<note important>important : since revision 2946 Method1ResidualComputation is **not anymore** the default value</note>

The residual is adimensionalized by the norm of external forces and internal reactions .
First :

$$Rmin = \frac{||FreeExternalForces|| + ||CstrInternalForces||+||CstrInertialForces||}{nreac}  $$

If 
$$ Rmin < limitNormFactor $$

$Rmin$ is set to
$$ Rmin = limitNormFactor $$

and the residual is adimensionalized :

$$Residual = \frac{||FreeResidual||}{ndofs*Rmin}$$

where

$ndofs$ : total number of degrees of freedom

$nreac$ : number of fixed degrees of freedom (having an associated reaction)

=== Method2ResidualComputation(limitNormFactor) ===

The residual is adimensionalized by the square of the norm of external forces and internal reactions. First:

$$Rmin = \frac{\sqrt{||FreeExternalForces||^2 + ||CstrInternalForces||^2+||CstrInertialForces||^2}}{nreac}$$

If
$$ Rmin < limitNormFactor $$
then 
$$ Rmin = limitNormFactor $$

and the residual is adimensionalized :

$$Residual = \frac{||FreeResidual||}{ndofs*Rmin}$$

where

$ndofs$ : total number of degrees of freedom

$nreac$ : number of fixed degrees of freedom (having an associated reaction)

=== Method3ResidualComputation(limitNormFactor) ===

The residual is adimensionalized by the norm of external and inertial forces, and internal reactions (**value to use preferentially for thermal simulations. Careful, the user must define it**). 

If 
$$ ||FreeExternalForces|| < limitNormFactor $$
then 
$$ Residual = max(|FreeResidual|) $$
Else,
$$Rmin = ||FreeExternalForces|| + ||CstrInternalForces||+||CstrInertialForces|| $$
and
$$Residual = \frac{||FreeResidual||}{ndofs*Rmin}$$

=== Method4ResidualComputation(limitNormFactor) (**default value**) ===
<note important>important : since revision 2946 Method4ResidualComputation is the new **default value**</note>
This method is the same as ''Method1ResidualComputation()'' but without dividing by the number of dofs nor nreac, so

$$Rmin = ||FreeExternalForces|| + ||CstrInternalForces||+||CstrInertialForces|| $$

If
$$ Rmin < limitNormFactor$$
then 
$$ Rmin = limitNormFactor $$

and the residual is adimensionalized :

$$Residual = \frac{||FreeResidual||}{Rmin}$$

=== Method5ResidualComputation(adimFactor) ===

The residual is adimensionalized by the factor ''adimFactor'', given by the user, without dividing by the number of dofs.

$$Residual = \frac{||FreeResidual||}{adimFactor }$$

=== Method6ResidualComputation(adimFactor) ===

The residual is adimensionalized by the factor ''adimFactor'', given by the user, and by the number of dofs.
$$Residual = \frac{||FreeResidual||}{ndofs * adimFactor }$$

where

$ndofs$ : total number of dofs

=== Parameters ===
^ Parameter ^ Default value ^  Description  ^ 
| ''limitNormFactor'' |  1.0  | Value from which the residual is no longer divided by $$Rmin$$ (to adjust as a function of the loading using verbose output)|
| ''adimFactor'' |  -  | Fixed adimensionalization factor for methods #5 and 6 (no default value, the factor must be defined for these methods)|
| ''prec'' |  1.0E-4  | accuracy that the residual must reach |
| ''itma'' |  7  | maximal number of Newton-Raphson iterations (this number if corrected internally if the automatic criterion is used to update the matrix). Iterations are stopped if the residual does not decrease over 6 iterations|
| ''irea'' |  1  |= 1 : stiffness matrix updated for each iteration|
|  	   |     | > 1 : stiffness matrix is updated automatically if the iteration number is lower than ''irea''. The criterion is based on a convergence speed and a CPU time ratio (requires ''MDE_ICPU=1'')|
| ''lsma'' |  0  | maximal line-search iteration number|
| ''lsp1'' |  1.0  | accuracy that the line-search residual must reach  |
| ''lsp2'' |  1.E-8  | stop criterion when the line search parameter is not updated enough  |
| ''predMeth'' |  ''EXTRAPOLATION_DEFAULT''  | ''EXTRAPOLATION_DEFAULT'' = Extrapolation of the scheme by default (for example method to compute the displacement predictor by Newmark formula in the case of  [[doc:user:integration:scheme:dynimpl#la_famille_alpha-generalisee|alpha-generalized scheme]])  |
|              |                        | ''EXTRAPOLATION_MRUA'' = method to compute the displacement predictor by MRUA formula (for now only possible for [[doc:user:integration:scheme:dynimpl#la_famille_alpha-generalisee|alpha-generalized algorithms]]) |
|              |                        | ''EXTRAPOLATION_ZERO'' = New positions are equal to the old ones, speed (and acceleration for dynamic schemes) equal to zero (for now only possible for  [[doc:user:integration:scheme:quasistatique|quasi-static algorithms]] and [[doc:user:integration:scheme:dynimpl#la_famille_alpha-generalisee|alpha-generalized algorithms]]) . |
| ''VACMeth'' | ''VAC_SCHEMECONSISTANT'' | ''VAC_SCHEMECONSISTANT'' : Calculation of speed and acceleration with Newmark formula | 
|             | | ''VAC_BACKWARDEULER'' : Calculation of speed and acceleration using Backward Euler (to stabilize Newmark with dofs with a non zero fixed displacement. See JPP's thesis pg VIII.28) |
| ''cpuDep'' | ''False'' | Specify if the criterion for updating the stiffness matrix (irea > 1) depends on the User CPU time. (Metafor Version > 2422). | 
| ''forceOneIte'' | ''False'' | If True, Force the resolution of at least one iteration (mechanical or thermal according to the iteration manager even if the tolerance is allready met at iteration 0. |