OpenSees Cloud
OpenSees AMI
Norms and Tolerance
Original Post - 28 Feb 2021 - Michael H. Scott
Visit Structural Analysis Is Simple on Substack.
Convergence tests in OpenSees measure how close the algorithm is to finding equilibrium at a time step. Several convergence tests are available, and they all operate on the linearized system of equations that is solved at every equilibrium iteration within a time step
\[{\bf K}_T \Delta {\bf U} = {\bf R}\]where \({\bf R}\) is the residual, or unbalanced force, vector (difference between external and internal forces) and \(\Delta {\bf U}\) is the vector of displacement increments. These vectors are related by the tangent stiffness matrix, \({\bf K}_T\). For dynamic equilibrium, the residual and tangent stiffness include inertial and damping terms and the displacement increment is related to the velocity and acceleration through time integration.
Equilibrium is satisfied when \({\bf R}\) is equal to the zero vector. Assuming the tangent stiffness matrix is not singular, the displacement increment, \(\Delta{\bf U}\), will also be equal to the zero vector when equilibrium is found.
However, it’s generally not possible for all components of the residual and displacement increment vectors to be exactly zero, even for linear-elastic analyses. So, when do these vectors become acceptably “small” such that the model is considered to be in equilibrium?
OpenSees offers three basic convergence tests in terms of a tolerance (tol).
- Norm of the residual vector, \(\|{\bf R}\|_2<tol\) (
NormUnbalance) - Norm of the displacement increment, \(\|\Delta {\bf U}\|_2<tol\) (
NormDispIncr) - The absolute value of the energy increment, \(\|(\Delta {\bf U})^T{\bf R}\|<tol\) (
EnergyIncr)
So, which test should you use? In my opinion, unless you have very stiff elements or you are using the penalty constraint handler, the norm of the residual vector should do the job. If you have stiff elements, use the norm of displacement increment. I’ve never seen much need to use the energy increment.
The next question is, what tolerance should you use? Let’s assume all
DOFs have the same force unit, e.g., a truss model with kips as the
basic force unit. Then a tolerance of 1e-3 on the residual norm
indicates an equilibrium error of one pound is acceptable. This becomes
one millipound, or mip, if the tolerance on the residual norm is 1e-6.
Note that the default convergence test in OpenSees of 1e-8 on the norm
of the residual. You can probably increase the tolerance a few orders of
magnitude and not have any problems because 1e-8 is so small, plus the
equilibrium error at each DOF actually will be less than the tolerance.
Consider the hypothetical case where the equilibrium error, e, is the same for all DOFs. In this case, the convergence test will look something like
\[\sqrt{\displaystyle \sum_{i=1}^N e^2} \leq tol\]This simplifies to \(\sqrt{N e^2} \leq tol\), or \(e \sqrt{N} \leq tol\). The error at each DOF is then \(e \leq tol/\sqrt{N}\).
This result indicates it’s OK to scale up the tolerance with the number
of equations in your model, i.e., you can use \(tol \sqrt{N}\). Like
the “fractions of a penny” scheme that Michael Bolton launched in Office Space, you’ll find it’s much more difficult to achieve 1e-6 tolerance on
a model with 100,000 DOFs compared to a model with 10 DOFs. Note that N
doesn’t have to be exact, just a ballpark estimate. The number of nodes
would be a suitable proxy.
Note that mixed units of force and force-length can pose scaling problems in the vector norms for frame models with rotational DOFs. But these problems rarely occur because the commonly used units of kip and ft and kN and m are congruent. Just don’t use light years as your basic length unit along with a convergence test on the norm of the displacement increment.
The convergence tests can also be relative to the initial norms in the equilibrium iteration at a time step. With a relative tolerance of 1e-6 on the norm of the residual, convergence is achieved when the residual norm decreases by 6 orders of magnitude. Relative norms may not be a good idea when the applied load changes drastically from one step to the next or when there is no applied load.
There is no “silver bullet” convergence test. If you find yourself having to fudge the convergence test to get your simulation to run, there’s likely a problem with your model, not with the analysis options.