OpenSees Command Line Arguments

Original Post - 24 Mar 2024 - Michael H. Scott

Visit Structural Analysis Is Simple on Substack.

While graphical user interfaces are good for general purpose use, the command line remains the most versatile way to run OpenSees and other computer programs.

Passing command line arguments to an OpenSees Tcl or Python script is useful when creating standalone applications for building and analyzing specialized models. Both Tcl and Python have constructs similar to argc and argv, the command line argument count and the command line argument values, respectively, passed into a C/C++ main() function.

Tcl Command Line

When you run OpenSees Tcl from the command line, you can access the following variables within your Tcl script:

argv0 - the name of the script
argc - the number of command line arguments after the script name
argv - a list of command line arguments not including the script name

You can see the definition of these variables in SRC/tcl/tclMain.cpp.

Suppose we have a simple script for analysis of an SDF oscillator and we want to take command line arguments for the natural period and the ground motion record.

puts "Running $argv0 script"
if {$argc < 2} {
    puts stderr "Must specify period and ground motion"
}

set Tn [lindex $argv 0]
set gmFile [lindex $argv 1]
puts "Natural period $Tn, ground motion $gmFile"

#
# Define SDF model with natural period Tn
#
# Define time series with ground motion gmFile
#
# Perform analysis, do stuff
#

To call the script with natural period 0.8 and the elCentro.txt ground motion:

$ OpenSees sdf.tcl 0.8 elCentro.txt

Python Command Line

When you run a Python script from the command line, Python defines only one argv list, which you can access using the sys library:

sys.argv[0] - the name of the script
sys.argv[1:] - the command line arguments after the script name (the length of this list is argc)

All sys.argv entries are strings, so you will have to cast numeric input as either float or int in your script.

The Python version of our simple SDF analysis script is below.

import openseespy.opensees as ops
import sys

print(f"Running {sys.argv[0]} script")
argc = len(sys.argv[1:])
if argc < 2:
    print("Must specify period and ground motion",file=sys.stderr)

Tn = float(sys.argv[1]) # Cast as float
gmFile = sys.argv[2]
print(f"Natural period {Tn}, ground motion {gmFile}"

#
# Define SDF model with natural period Tn
#
# Define time series with ground motion gmFile
#
# Perform analysis, do stuff
#

To call the script with natural period 0.8 and the elCentro.txt ground motion:

$ python3 sdf.py 0.8 elCentro.txt

Error Checking

The above snippets have minimal error checking, only on the command line argument count. When taking user input–from the command line or anywhere else–you should check for consistent types. For example, you can use a try/except block to check that the user entered a floating point value for the natural period.

def isfloat(value):
    try:
        float(value)
        return True
    except ValueError:
        return False

if isfloat(sys.argv[1]):
    Tn = float(sys.argv[1])
else:
    print(f'Input period {sys.argv[1]} is not a floating point value',file=sys.stderr)

The above code should flag an error for the following command line arguments:

$ python3 sdf.py abc elCentro.txt

Also, you should check that the ground motion file exists before you pass the filename to the timeSeries command in OpenSees.

import os

if not os.path.isfile(sys.argv[2]):
    print(f'Input ground motion file {sys.argv[2]} does not exist',file=sys.stderr)

More error checking is necessary, even for this simple example. In many programs, the lines for error checking can exceed the lines for core code execution.

OpenSees Cloud

OpenSees AMI

OpenSees Command Line Arguments

Tcl Command Line

Python Command Line

Error Checking