Test
The convergence test decides when an iteration within a step is close enough to stop.
🔧 Grasshopper component
EnergyIncr, NormUnbalance, NormDispIncr, RelativeNormUnbalance, RelativeNormDispIncr, RelativeTotalNormDispIncr and RelativeEnergyIncr.
0 nothing, 1 each time, 2 on success, 4 each step, 5 error message.0 max, 1 one-norm, 2 two-norm.There is no maxIncr input: OpenSees reads a fifth number as a divergence guard, maxTol, rather than as maxIncr, so any value given there would cut analyses short.
Converged when both the displacement increment and the residual are within their tolerances.
No Norm here: OpenSees reads this test's trailing numbers back over the iteration limit and the print flag, so a norm would overwrite them. To choose the norm, use NormDispOrUnbalance.
Converged when either the displacement increment or the residual is within its tolerance.
Runs exactly Iteration iterations at every step, without checking convergence.
A switcher component with ten units, one per OpenSees test: pick the unit in the drop-down under it, or right-click it ▸ Units. It starts on EnergyIncr.
📈 When to use it
Use it when you are running anything through Run Analysis. Every analysis needs a convergence test, even a linear one.
Do not use it when you only want modes → Natural Vibration has nothing to converge.
💡 Which test
| Unit | Measures | Use for |
|---|---|---|
| NormDispIncr | The size of the displacement increment. | The general default. |
| NormUnbalance | The size of the residual force. | When equilibrium is what matters — you care that forces balance, not that the model stopped moving. |
| EnergyIncr | The product of the two. | Well-conditioned for problems mixing very stiff and very flexible parts. |
| NormDispAndUnbalance | Both displacement and residual. | Strict, when you do not trust either alone. |
| NormDispOrUnbalance | Displacement or residual, whichever converges first. | Lenient: a run that stalls on one criterion while the other is met. |
| RelativeNormUnbalance, RelativeNormDispIncr, RelativeEnergyIncr | The same as the plain tests, as a fraction of their value at the first iteration of the step. | A model whose absolute numbers are hard to set a tolerance for, such as one with very different load levels. |
| RelativeTotalNormDispIncr | The displacement increment as a fraction of the sum of all increments of the step. | As above, when the first increment is a poor yardstick. |
| FixedNumIter | Nothing: it stops after Iteration iterations. | A set number of iterations, converged or not. |
Note
1e-8 is tight. A model in kN and metres with a displacement test will usually converge, but a stiff model, or one with a badly scaled unit system, may need 1e-6 or looser. Raising Iteration to 100 costs little and rescues many runs.
If a run fails to converge, turn Flag to 1 and read the log — it will show whether the residual is falling slowly or diverging outright, which are different problems.
🔗 Relation to OpenSees
test $type $tol $iter $flag $norm ;# the tests on one tolerance
test NormDispAndUnbalance $tolIncr $tolR $iter $flag
test NormDispOrUnbalance $tolIncr $tolR $iter $flag $norm
test FixedNumIter $iter $flag $norm