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 scriptargc
– the number of command line arguments after the script nameargv
– 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 scriptsys.argv[1:]
– the command line arguments after the script name (the length of this list isargc
)
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:
error("Must specify period and ground motion")
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:
error(f'Input period {sys.argv[1]} is not a floating point value')
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]):
error(f'Input ground motion file {sys.argv[2]} does not exist')
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.