OpenSees Convergence Problems

Convergence Problems often occur when nonlinear analyses are run with OpenSees. In this article, a tcl program package is provided. This package helps OpenSees model to converge faster. This package is named SmartAnalyze.

You can download this package from GitHub: SmartAnalyze

When the OpenSees model fails to converge, the console will print

1
2
3
4
5
6
WARNING: CTest*::test() - failed to converge
after * iterations
 current EnergyIncr: * Norm deltaX: *, Norm deltaR: *
*::solveCurrentStep() - The ConvergenceTest object failed in test()
StaticAnalysis::analyze() - the Algorithm failed at iteration: * with domain at load factor *
OpenSees > analyze failed, returned: -3 error flag

In general, if -3 error flag is returned, the convergence failure was encountered. In this time, users could try SmartAnalyze.

How does SmartAnalyze Work

SmartAnalyze is a reusable program package. It has two analysis types, transient analysis and static analysis. The usage and methodology is introduced, respectively.

Converge OpenSees Transient Analysis with SmartAnalyze

Create models as usual. Do not call algorithm and test. Then replace the analyze line with the following code

1
2
3
4
5
6
source SmartAnalyze.tcl
constraints Transformation
numberer Plain
system BandGeneral
integrator Newmark 0.5 0.25
SmartAnalyzeTransient $dt $npts

Where, $dt is the time step for each analyzing step, npts is the number of points.

SmartAnalyze take the following strategies to help the OpenSees model to converge.

  1. If the test norm is not too large, the number of iteration times in test will be increased;
  2. If step 1 does not work, algorithm will be changed according to the parameters given by users. For each algorithm, try the strategy in step 1;
  3. If all the algorithm do not work, shorten the time step, and iterate again;
  4. If the time step is smaller then the tolerance, users can config to enlarge the test tolerance, and iterate from the initial time step again.
  5. If the model still do not converge, return an error message.

Note that trying to use algorithm Linear to force converge in version 3.0 is deprecated, because the results are always bad.

Several initial configuration parameters are defined in SmartAnalyze. Users can change these configurations in the model without changing the code in the package. For example,

1
2
3
4
set control(printPer) 20 ;# Print progress information every 20 steps.
set control(tryAlterAlgoTypes) True ;# Try to alternate algorithm if not converge.
set control(algoTypes) {20 30} ;# Specify algorithm to be used with flags.
SmartAnalyzeTransient $dt $npts control ;# Pass control array to analyze.

The detailed usage of these control parameters are put in the code. Users are encouraged read it by themselves.

Converge OpenSees Static Analysis with SmartAnalyze

The usage is similar to transient analysis. Do not call algorithm, test, and integrator. The program will use DisplacementControl as the algorithm.

SmartAnalyze reads a user specified list as the loading protocol. It helps users to finish the whole protocol automatically. For example

1
2
3
4
5
6
source SmartAnalyze.tcl
constraints Transformation
numberer Plain
system BandGeneral
set protocol {1 -1 1 -1 0}
SmartAnalyzeStatic $node $dof $maxStep $protocol

This code will run a cyclic loading protocol. In this code, $node is the node tag, dof is the loading dof, $step is the maximum time step, $protocol is the loading protocol. Every item in the list is the target displacement of the $node in the dof.

Note that the first element of the protocol must be positive.

Similarly, the controlling configuration parameters can be set in the user’s model.

Updates for version 4.0+

I have tried a lot of routines similar to SmartAnalyze since I started to use OpenSees. SmartAnalyze 2.2 is the first published code version. In this version, the routine is designed with recurrent procedures. The problem is that the code is complicated, and hard to read and maintain. Another problem is that for Transient analyses, if the step is shortened, the procedure will no longer run on the sampling points of the earthquake, which makes very small errors to the results. Before the first published version, I also tried to design the routine with recursive functions. However, a big problem is that the TCL interpreter do not support too many recursive calls. It will stop interpreting.

In the 4+ version, I refactored the routine with mixed recurrent and recursive functions. The basic idea is: First, divide the whole routine into several segments with fixed length. Then, run within the segment recursively, and run outside the segment recurrently. For Transient analyses, every step is the length of the segment. For Static analyses, the control parameter maxStep defines the maximum length of the segment. In this way, the recursive functions will not stack too much, and the code is more beautiful.

Another change is that for the parameters defined in control, the data structure dict was used. This data structure is very similar to the dicts in other languages, so I used it without hesitation. However, in practice, I found that the control value cannot directly be got with pointer. Instead, a procedure dict get $var key must be called, which makes the code ugly. Later, I found another data structure array. This array is different from the array of other languages. Users can define array with keys. The value can be get directly with $. This is much easier. Therefore, I moved to array in new versions. Users are suggested to pay attention if they move from 3+ versions to 4+ versions.

SmartAnalyze for python users

Mr. Difang Huang from South China University of Technology has created a python file using identical algorithm. OpenSees python interpreter users can use it directly.

The tcl file and the python file can be downloaded from the same repository SmartAnalyze. Pull requests are welcome.