Convergence in OpenSees: Practical Solutions for Cyclic, Pushover, and Time History Analyses

Introduction

Nonlinear static and dynamic analyses in OpenSees and OpenSeesPy often face convergence issues, especially in cyclic, pushover, and time history simulations. These problems can arise even with correctly defined models, due to solver settings, load increments, or numerical instabilities.

This blog post introduces convergence control scripts designed specifically for OpenSees (Tcl) and OpenSeesPy (Python). These tools automatically adjust key analysis parameters to help your models converge efficiently — saving time, reducing manual debugging, and improving the reliability of your results.

The Problem: Convergence Failure in Advanced Analyses

Convergence failure, or divergence, is a common issue in nonlinear and dynamic simulations, particularly in pushover and time history analyses. Even if the model is correctly built, convergence may still fail due to:

• Inappropriate time step or load increment
• Poor choice of solution algorithm or test method
• Numerical instabilities related to material or geometric nonlinearities

These issues can lead to incomplete results, increased run-time, or completely failed simulations.

The Solution: Convergence Control Scripts for OpenSees and OpenSeesPy

To streamline the analysis process and resolve convergence problems, we provide two dedicated convergence control scripts:

1. Convergence Script for Pushover and Cyclic Analysis
2. Convergence Script for Time History Analysis

These scripts automatically adjust analysis parameters — such as step size, test tolerance, and algorithm — to help achieve convergence without manual intervention.

1. Pushover and Cyclic Analysis Convergence Script

Features

• Automatically changes analysis algorithm, test type, and step size until convergence is achieved
• Supports both static pushover and cyclic loading protocols
• Reduces manual trial-and-error by automating the convergence process

Required Parameters

To use the script, define the following at the end of your model:

for {set i 1} {i <= 5} {incr i} {
  puts $x
}

for {set i 1} {i <= 5} {incr i} {
  puts $x
}

for i in range(1,n):
   puts('hello')

for i in range(1,n):
   puts('hello')

• pattern: The lateral load pattern to apply
• targetDriftList: A list of target drift values for each analysis cycle
• HBuilding: Total height of the structure. If set to 1, drift values are interpreted directly as displacements
• roofNode: Node ID at the roof level to track displacement
• incr: Displacement increment per step
• dof (optional): Degree of freedom (default = 1, typically lateral)

Tcl Usage

source analyzePush.tcl

Python Usage (OpenSeesPy)

The Python version mirrors the logic of the Tcl script. You can call the function at the end of your model script:

from analyzePush import runPushoverConvergence
runPushoverConvergence(pattern, targetDriftList, HBuilding, roofNode, incr, dof=1)

Download: Download Pushover & Cyclic Convergence Script

2. Time History Analysis Convergence Script

Features

• Automatically switches algorithms, test settings, and time steps when convergence fails
• Reverts to default time step after successful convergence to reduce total run time
• Helps ensure complete and reliable seismic response simulations

Required Parameters

Define the following inputs before sourcing the script:

• Time series and loading pattern definitions
• Tmax: Total ground motion duration
• dtInput: Time step size for input motion

Tcl Usage

tclCopyEditsource analyzeGM.tcl

Python Usage (OpenSeesPy)

pythonCopyEditfrom analyzeGM import runTimeHistoryConvergence
runTimeHistoryConvergence(Tmax, dtInput)

Download: Download Time History Convergence Script

Final Thoughts

Dealing with convergence failures in OpenSees and OpenSeesPy can be time-consuming and discouraging, especially in nonlinear and dynamic simulations. These convergence scripts are designed to automate repetitive processes, improve reliability, and save time.

Whether you’re working on seismic performance evaluation, nonlinear pushover studies, or dynamic earthquake simulations, these tools can significantly simplify your workflow and help you achieve robust results with less manual effort.