Mastering ETABS Seismic Analysis Automation: A Python Tutorial

TL;DR: Structural engineers can automate tedious seismic analysis tasks, which typically consume up to 40% of their time, by leveraging the ETABS Open API (OAPI) accessed via Python using the win32com library. This guide provides foundational steps for scripting model initialization and result extraction, requiring ETABS version 18+ and Python 3.8+ as essential prerequisites. Implementing this ETABS seismic analysis automation serves as the main value proposition by reducing human errors by 60% and increasing overall productivity 2 - 3x.

---

Structural engineers know the drill: seismic design often requires dozens of iterative analyses, checking various load combinations, and comparing drift limits across multiple model versions. This manual, repetitive process doesn't just consume time; it dramatically increases the risk of human error. Studies suggest that engineers can spend up to 40% of their time on manual data entry and repetitive tasks, hindering overall project velocity.

The solution lies in ETABS seismic analysis automation. By leveraging the powerful ETABS Open Application Programming Interface (OAPI) alongside Python, we can transform hours of tedious clicks into minutes of automated computation. This tutorial provides a comprehensive, step-by-step guide to building a basic automation script that initializes a model, executes a seismic analysis, and extracts critical results - a foundational step toward reducing errors by 60% and increasing your productivity 2 - 3x.

Prerequisites and Setup for ETABS Automation

Before diving into the code, we must ensure our environment is correctly configured to communicate with the ETABS software. We will be using Python due to its robust libraries and excellent support for OAPI interaction via the Component Object Model (COM) interface.

Essential Tools

To begin your journey into ETABS seismic analysis automation, you will need:

• ETABS: Version 18 or newer (ensure the OAPI feature is installed).
• Python: Version 3.8+ (We recommend using Anaconda for easier package management).
• Integrated Development Environment (IDE): Visual Studio Code or PyCharm.

Establishing the OAPI Connection

The ETABS OAPI allows external programs (like our Python script) to remotely control the software. Since ETABS uses a COM interface, we must use the win32com library in Python to establish the connection.

First, install the necessary library:

pip install pywin32

Next, use the following template to initialize and attach to an existing ETABS instance.

import win32com.client
import os

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

try:
    # 1. Get the ETABS application object
    ETABSObject = win32com.client.Dispatch("CSI.ETABS.API.ETABSObject")
    
    # 2. Start ETABS (if it's not already running)
    ETABSObject.ApplicationStart()
    
    # 3. Get the helper object (used for file operations)
    Helper = ETABSObject.Helper
    
    # 4. Initialize the API
    SapModel = ETABSObject.SapModel
    
    # 5. Open the model
    ret = SapModel.File.OpenFile(model_path)
    if ret != 0:
        print(f"Error opening model: {ret}")
    else:
        print("ETABS connection successful. Model loaded.")

except Exception as e:
    print(f"An error occurred during connection: {e}")

Once this script runs successfully, you have programmatic control over your ETABS model.

Part 1: Automating Model Initialization and Load Case Definition

The first step in automating any seismic analysis is ensuring the model setup is consistent and adheres to design standards. This includes defining materials, assigning sections, and crucially, defining the dynamic analysis parameters. This is where ETABS seismic analysis automation truly saves time.

Defining Response Spectrum Functions

Manually inputting response spectrum data (e.g., from ASCE 7 or a site-specific study) is highly repetitive. We can automate the definition of these functions using the API.

In this example, we'll assume we are updating an existing ASCE 7-16 response spectrum function named "RS_ASCE7."

# Assuming SapModel is already initialized from the setup section

# Define the parameters for the response spectrum (Example: Site Class D, Ss=1.0, S1=0.4)
# Note: The exact method depends on the function type (e.g., User Defined vs. Code-based)
# We use the SetFunctionSpectrumASCE716 method for code-based spectra.

# SapModel.Func.FuncRS.SetFunctionSpectrumASCE716(
#     Name="RS_ASCE7", 
#     Ss=1.0, 
#     S1=0.4, 
#     TL=8, 
#     SiteClass="D"
# )

# For simplicity, let's ensure P-Delta settings are correct.
# PDeltaType: 1=None, 2=P-Delta Iterative, 3=P-Delta Non-Iterative
ret_pdelta = SapModel.Analyze.SetPDeltaOptions(PDeltaType=2)

if ret_pdelta == 0:
    print("P-Delta iterative analysis enabled.")

# Define the Response Spectrum Load Case (assuming we use the CQC method)
# CQC load case definition parameters:
# LCaseName, LType (Response Spectrum), ModalCase, ScaleFactor, Directionality
ret_lcase = SapModel.LoadCases.ResponseSpectrum.SetCase(
    Name="Seismic_RS_X",
    ModalCase="MODAL",  # Default modal case
    Func="RS_ASCE7",
    ScaleFactor=9.81,  # g value (m/s^2) or 386.4 (in/s^2)
    Angle=0, # X-direction
    CSys="GLOBAL",
    Dir="U1" # Global X
)

if ret_lcase == 0:
    print("Seismic Response Spectrum load case defined successfully.")

By automating this setup, you ensure every analysis run uses the exact same input parameters, eliminating the risk of accidental typos in scaling factors or site classification.

Part 2: Executing Analysis and Extracting Critical Data

The core benefit of automation is the ability to run the analysis and immediately pull the necessary output data without scrolling through tables in the ETABS interface. This drastically accelerates the review process.

Running the Analysis

Once the model setup is complete, executing the analysis is a single API call:

print("Running analysis...")
ret_analysis = SapModel.Analyze.RunAnalysis()

if ret_analysis == 0:
    print("Analysis completed successfully.")
else:
    print(f"Analysis failed with error code: {ret_analysis}")

Automated Extraction of Story Drifts

In seismic design, story drift is often the governing criteria. We need to extract the maximum drift ratio for every story and compare it against the code limit (e.g., 0.020 or 0.015).

We use the GetStoryDrifts method to pull this data directly into Python:

# Function to extract and display story drift results
def get_story_drifts(sap_model, load_case):
    # Initialize variables for the API call
    NumberResults = 0
    StoryName = []
    LoadCase = []
    Direction = []
    Drift = []
    
    # Get the results table data
    [NumberResults, StoryName, LoadCase, Direction, Drift] = sap_model.Results.Story.GetStoryDrifts(
        load_case, 
        NumberResults, 
        StoryName, 
        LoadCase, 
        Direction, 
        Drift
    )
    
    drift_data = []
    for i in range(NumberResults):
        drift_data.append({
            "Story": StoryName[i],
            "LoadCase": LoadCase[i],
            "Direction": Direction[i],
            "DriftRatio": Drift[i]
        })
        
    return drift_data

# Extract drifts for our newly defined load case
drifts = get_story_drifts(SapModel, "Seismic_RS_X")

# Print key results
print("\n--- Extracted Story Drifts (Seismic_RS_X) ---")
for result in drifts:
    if result["Direction"] == "X":
        print(f"Story: {result['Story']}, Drift Ratio (X): {result['DriftRatio']:.5f}")

Part 3: Automated Reporting and Iterative Design Checks

Extracting raw data is only half the battle. The true power of ETABS seismic analysis automation comes from processing that data into actionable reports and integrating decision-making logic.

Generating Actionable Reports

Instead of simply printing the data, we can use Python libraries like pandas to format the drift results, base shear data, and mode shapes into a clean CSV or Excel file for documentation.

For instance, we can flag any story where the drift ratio exceeds the design limit (e.g., 0.020).

import pandas as pd

df = pd.DataFrame(drifts)
drift_limit = 0.020

# Add a column indicating if the drift limit is exceeded
df['ExceedsLimit'] = df['DriftRatio'] > drift_limit

# Filter for critical violations
violations = df[df['ExceedsLimit'] == True]

print(f"\n--- Drift Limit Violations (Limit: {drift_limit}) ---")
if not violations.empty:
    print(violations[['Story', 'Direction', 'DriftRatio']])
    # Here, you would trigger an automatic modification (e.g., increasing column size)
else:
    print("No drift limit violations found.")

# Save the full report
df.to_csv("Seismic_Analysis_Report.csv", index=False)
print("\nFull report saved to Seismic_Analysis_Report.csv")

Integrating AI for Complex Iterations

For engineers dealing with highly complex models or performance-based design, simple scripting often hits a wall when determining the optimal design modification (e.g., should I increase the shear wall thickness or change the column material?).

This is where specialized tools shine. Products like Structures AI (AI-Powered Automation for Structural Engineering) move beyond basic scripting by providing intelligent feedback. Structures AI integrates advanced machine learning models with the ETABS and SAP2000 APIs to offer AI-Powered Recommendations that optimize member sizing and material usage based on performance metrics, dramatically accelerating the iterative design cycle.

Testing and Validation

Automation is useless if the results are unreliable. Before deploying any automation script, thorough validation is mandatory.

Here are essential validation steps:

1. Manual Spot Check: Run the automated analysis and then manually open the ETABS interface. Go to Display > Show Tables > Analysis Results > Story Drifts. Compare the first five and last five story drift values against the values extracted by your Python script.
2. Base Shear Verification: Use the API to extract the base shear for the automated load case. Compare this value against a quick hand calculation or a spreadsheet summary.
3. Model State Check: Ensure that the script successfully saved the model after defining the load cases and that the P-Delta options are correctly set in the ETABS UI after the script runs.

If the automated results deviate from the manual results, the issue is almost always related to the API input parameters (e.g., incorrect units or scaling factors) rather than the ETABS solver itself. Always verify the units specified in the API documentation against your model units.

Next Steps and Resources

This tutorial provided the foundation for model setup and data extraction. To build a truly powerful automation workflow, consider these next steps:

• Automated Design Checks: Extend the script to perform concrete or steel design checks (e.g., column interaction ratios) and automatically adjust member sizes based on the results.
• Parametric Modeling: Integrate the script with geometry tools to automate the creation of entire models based on high-level parameters (e.g., number of bays, story height).
• Error Handling: Implement robust error handling (try/except blocks) to manage scenarios where the ETABS solver fails or the API call returns an unexpected error code.

For detailed documentation on specific API functions, always refer to the official CSi documentation. This resource provides definitions for every command and required input variable:

CSI ETABS API Documentation

Conclusion

Embracing ETABS seismic analysis automation is no longer optional; it is a necessity for competitive structural engineering firms. By mastering the ETABS OAPI and integrating Python, you gain the ability to execute complex, iterative analyses with speed and precision, freeing up valuable engineering time for complex problem-solving.

Start transforming your workflow today.

Download Structures AI for free to explore how AI-Powered Automation can further enhance your ETABS and SAP2000 workflows, delivering optimized designs faster than ever before.