Mastering ETABS Seismic Analysis Automation with Python

TL;DR: This tutorial guides structural engineers in automating ETABS seismic analysis by leveraging the ETABS API with Python (v3.8+), specifically utilizing the comtypes and pandas libraries. This automation addresses the 40% of time engineers spend on manual setup by allowing scripts to automatically initialize models, define load cases, and extract results. The key benefit is accelerating the design cycle and reducing design errors by up to 60%.

---

Structural engineering workflows are increasingly complex. Did you know that engineers spend up to 40% of their time on repetitive data entry and analysis setup? This manual effort not only slows project delivery but significantly increases the risk of human error. Modern practice demands efficiency, and the key to unlocking massive productivity gains is ETABS seismic analysis automation.

This comprehensive tutorial will guide structural engineers through leveraging the powerful ETABS API (Application Programming Interface) using Python. By the end of this guide, you will be able to write scripts that automatically initialize models, define seismic load cases, run the analysis, and extract critical results, accelerating your design cycle and reducing errors by up to 60%.

Prerequisites and Setup: Accessing the CSI API

Before we dive into the automation scripts, ensure you have the necessary tools installed and configured. This tutorial uses Python, which is ideal due to its readability and extensive libraries.

Required Software and Components:

• ETABS (v18 or newer): The primary analysis software. Ensure the licensing allows for API access.
• Python (v3.8+): We recommend installing the Anaconda distribution for easy management of necessary libraries.
• Python Libraries: comtypes (for interacting with the Windows COM interface) and pandas (for result handling).

# Install required libraries via pip
pip install comtypes pandas

Enabling the ETABS API Connection

ETABS uses the Component Object Model (COM) interface to allow external programs to communicate with and control the software. You must ensure ETABS is running (or ready to be launched) and that your script can find the correct program path.

The first step in any automation script is establishing a reliable connection to the ETABS application instance.

Part 1: Initializing the ETABS Model and Defining Load Cases

The foundation of ETABS seismic analysis automation is the ability to programmatically open or create a model and define the basic analysis parameters without manual clicks.

We will focus on connecting to a running instance of ETABS and opening a pre-existing model file (e.g., Project_Tower.edb).

Connecting Python to ETABS

We use the comtypes library to handle the communication with the ETABS object model. This snippet attempts to connect to a running instance or launch a new one if necessary.

import comtypes.client

# Define the path to the model file
model_path = r"C:\ETABS_Projects\Project_Tower.edb" 

try:
    # 1. Get the ETABS object
    ETABSObject = comtypes.client.GetActiveObject("CSI.ETABS.API.ETABSObject")
    
except Exception:
    # 2. If no active instance, launch ETABS
    ETABSPath = "C:\Program Files\Computers and Structures\ETABS 20\ETABS.exe"
    helper = comtypes.client.CreateObject('ETABSv1.Helper')
    ETABSObject = helper.CreateObject(ETABSPath)

# 3. Initialize the model and get the SapModel interface
ETABSObject.ApplicationStart()
SapModel = ETABSObject.SapModel

# Open the specific model file
SapModel.File.OpenFile(model_path)
print(f"Successfully connected to ETABS and opened: {model_path}")

# Unlock the model to make changes
SapModel.SetModelIsLocked(False)

Defining Seismic Parameters

Once the model is open and unlocked, the next step in the automation process is defining the specific seismic load patterns and load cases required by local building codes (e.g., ASCE 7, Eurocode 8). This usually involves defining mass sources, diaphragm definitions, and the initial modal analysis case.

For instance, we can ensure the standard modal case is set up correctly:

# Define the Modal Case Name and Type
ModalCaseName = "MODAL_RITZ"
ModalCaseType = 1 # 1 for Ritz vectors, 2 for Eigen vectors

# Set the modal analysis case parameters (using the default properties)
ret = SapModel.LoadCases.ModalRitz.SetCase(ModalCaseName)

if ret == 0:
    print(f"Modal Case '{ModalCaseName}' defined successfully.")

Part 2: Automating Response Spectrum Definition and Application

Defining Response Spectrum Functions is often tedious, requiring manual input of periods ($T_a$) and corresponding spectral acceleration values ($S_a$). This section focuses on automating the definition of these functions based on site-specific parameters.

This is a crucial area for advanced ETABS seismic analysis automation, ensuring compliance and consistency across multiple projects.

Defining the Response Spectrum Function

We will use the SapModel.Func.ResponseSpectrum methods. Although ETABS includes built-in functions for various codes, defining custom functions allows for precise control based on detailed geotechnical reports.

Assume we need to define a user-defined function named "Custom_RS" using the following data points (Period, Acceleration): (0.0, 0.1g), (0.2, 0.5g), (1.0, 0.5g), (4.0, 0.1g).

# Define the Response Spectrum Function
FuncType = 0 # 0 for User Defined
FuncName = "Custom_RS"
NumberPoints = 4
Periods = [0.0, 0.2, 1.0, 4.0]
Accelerations = [0.1, 0.5, 0.5, 0.1]
DampingRatio = 0.05 # 5% Damping

# Set the function data
ret = SapModel.Func.ResponseSpectrum.SetUser(
    FuncName, NumberPoints, Periods, Accelerations, DampingRatio)

if ret == 0:
    print(f"Response Spectrum Function '{FuncName}' defined.")

Applying the Spectrum to the Load Case

Next, we create the Response Spectrum Load Case (e.g., "RS_X" and "RS_Y") and assign the newly defined function. We must also specify the direction of application and scale factors (like the $I/R$ factor).

R_Factor = 8.0 # Example R factor
I_Factor = 1.0 # Example Importance Factor
ScaleFactor = (386.4 * I_Factor) / R_Factor # g conversion * I / R

# Create the Response Spectrum Load Case (e.g., in the X direction)
RSCaseName_X = "RS_X"
ModalCase = ModalCaseName

# Set the load case type (1 = Response Spectrum)
ret = SapModel.LoadCases.ResponseSpectrum.SetCase(RSCaseName_X)

# Assign the acceleration load components (U1 = X direction)
ret = SapModel.LoadCases.ResponseSpectrum.SetLoads(
    RSCaseName_X, 1, ["U1"], [FuncName], [ScaleFactor], [0.0], [0.0], [0.0])

if ret == 0:
    print(f"Response Spectrum Load Case '{RSCaseName_X}' defined with Scale Factor: {ScaleFactor:.4f}")

For engineers dealing with complex jurisdictional requirements or performance-based design, tools that go beyond simple scripting are necessary. While custom scripts handle repetitive setup, sophisticated platforms like Structures AI (AI-Powered Automation for Structural Engineering) provide seamless, enterprise-level automation. Its key features, including ETABS Integration, SAP2000 Automation, and AI-Powered Recommendations, can significantly increase productivity 2-3x by automating code-checking and design optimization based on analysis results.

Part 3: Running the Analysis and Extracting Key Seismic Results

The final stage of the automation script involves running the analysis and harvesting the critical output data. Manually sorting through output tables is time-consuming; automation allows instant data validation.

Executing the Analysis

Running the analysis is a single, straightforward command using the SapModel object. Since seismic analysis can be time-consuming, the script will wait until the process is complete.

print("Running the analysis...")
ret = SapModel.Analyze.RunAnalysis()

if ret == 0:
    print("Analysis complete.")
else:
    print("Error during analysis.")
    # Stop execution if analysis fails
    exit()

Extracting Base Shear and Story Drifts

We can now extract key results, such as the total base shear for our defined seismic cases. The SapModel.Results.BaseReactions function is used for this purpose.

import pandas as pd

# Prepare lists to store results
results_data = []

# Get Base Reactions for the RS_X case
NumberResults = 0
LoadCase = "RS_X"
ret, NumberResults, LoadCase, StepType, StepNum, Fx, Fy, Fz, Mx, My, Mz = \
    SapModel.Results.BaseReactions.GetBaseReactions(LoadCase, 0, 0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0)

if ret == 0 and NumberResults > 0:
    # Fx is the base shear in the X direction
    results_data.append({
        'Load Case': LoadCase,
        'Base Shear (Fx)': Fx[0] 
    })

# Convert results to a clean Pandas DataFrame for easy viewing/export
df_results = pd.DataFrame(results_data)
print("\n--- Extracted Base Shear Results ---")
print(df_results)

# Optional: Export to CSV
# df_results.to_csv("seismic_base_shear.csv", index=False)

By completing this process, you have achieved full ETABS seismic analysis automation from model setup to key result extraction.

Testing and Validation: Ensuring Accuracy and Compliance

Automation reduces errors, but it does not eliminate the need for thorough checking. After running your script, validation is essential.

Critical Validation Steps:

1. Base Shear Comparison: Manually verify that the automated base shear (Fx, Fy) matches the expected code-minimum static base shear ($V = C_s W$). A significant discrepancy suggests an error in the scale factor or mass definition.
2. Load Case Integrity: Open the ETABS model and confirm that the "Custom_RS" function and the "RS_X" load case were correctly defined with the specified parameters and scale factors.
3. Modal Mass Participation: Ensure that the modal analysis case utilized in the response spectrum analysis achieves the required mass participation (typically 90% or greater).

Remember, automated tools are only as good as the inputs they receive. Rigorous validation ensures both efficiency and structural safety.

Next Steps and Resources for Advanced Automation

This tutorial provided the foundation for seismic analysis automation. To take your skills further, explore:

• Automated Report Generation: Use Python to pull results and automatically format them into client-ready reports.
• Design Optimization Loops: Create scripts that modify member sizes based on demand-capacity ratios and re-run the analysis iteratively.
• Advanced Result Handling: Utilize the API to extract story drifts and automatically check them against code limits.

For detailed documentation on all available methods and objects within the ETABS API, consult the official CSI Developer Network documentation.

Conclusion: The Future of Structural Engineering

The move toward programmatic control over analysis software is non-negotiable for modern structural engineering firms. By implementing ETABS seismic analysis automation, you not only save substantial time but fundamentally improve the quality and consistency of your work. Automation allows engineers to focus on complex design decisions rather than repetitive setup tasks.

Embrace the power of scripting and AI-driven tools to redefine your workflow. Ready to see the future of structural analysis?

Download Structures AI for free and start automating your most demanding ETABS projects today.