batch execution for automation

In some use cases, it may be convenient to run parametric analysis of some numerical model with different parameters. A batch execution procedure may be required to automate the process. In this example, we show how to perform similar tasks. The model can be downloaded.

It must be noted that by default, all output files generated by recorders are saved under the current working folder. Only the Visualization recorder supports customized output folder name, which is again defined relative to current working folder.

Possible useful commands include: pwd , terminal. Depending on the different platform, it is always possible to use PowerShell, bash or other shells to perform automation tasks. Here, we show a Python example.

Batched Time History Analysis

Suppose we, as structural engineers, are asked to perform a series of time history analyses to find the maximum displacement of some structure under a number of different ground motions.

For simplicity, let the structure be a SDOF mass--spring system, and we want to apply all the records in the NZ Strong Motion database. Please note the provided archive only contains a few records. Please visit the corresponding page for the full database (with 700+ records).

The Model

We define a template of the model and use a placeholder named as $groundMotionRecord to be later replaced by specific record names. The analysis time is labelled as $duration. It can be changed for different records. The model script will look like the follows.

# an example of batch processing

node 1 0 0
node 2 1 0

# set modulus ==> 16\pi^2
material Elastic1D 1 157.913670417

element T2D2 1 1 2 1 1

mass 2 2 1 1

fix 1 1 1
fix 2 2 1 2

amplitude NZStrongMotion 1 $groundMotionRecord

# apply reference acceleration ==> 1m/s^2
acceleration 2 1 1.0 1 2

hdf5recorder 1 Node U1 2

step dynamic 1 $duration
set ini_step_size 1E-2
set fixed_step_size true

integrator Newmark 1

converger AbsIncreDisp 1 1E-12 10 1

analyze

exit

The above model defines a SDOF structure with a period of half a second. With PGA equals unity (ground motion record is normalised), the displacement is recorded.

Folder Structure

The template model file batch-execution.supan is placed alongside the folder NZStrongMotion which contains example NZ strong motion records.

C:\BATCH-EXECUTION
│   batch-execution.supan
│
└───NZStrongMotion
    20030821_121249_BDCS_N59E_A
    20030821_121249_BDCS_S31E_A
    20030821_121249_DCDS_N67E_A
    20030821_121249_DCDS_S23E_A
    20030821_121249_DGNS_S18W_A
    20030821_121249_DGNS_S72E_A
    20030821_121249_DKHS_N33W_A

To automate the task, we want to

1. loop over all strong motion records

2. for each record, replace placeholder $groundMotionRecord with the proper file name to load the record

3. replace $duration with proper analysis duration which can be determined by the duration of record

4. perform the response history analysis

Note the recorded displacement is stored in *.h5 file, it may be better to store them in different folder with the name of the corresponding ground motion. This can be done in two approaches:

1. Create the folder first and launch suanPan inside that folder.

2. Launch suanPan first, use terminal to create that folder, switch to that folder via pwd and perform the analysis.

Given that we are going to use Python, we can simply choose the first option.

Python Script

Load Template First

import os
import shutil

placeholder = '$groundMotionRecord'
duration = '$duration'

template_file = open("batch-execution.supan", "r")
template_model = template_file.read()

Load All Record Names

records = os.listdir('NZStrongMotion')

Loop

Now loop over each record and perform the analysis.

for record in records:
    print("Processing " + record)
    try:
        # try to create folder
        os.mkdir(record)
    except OSError:
        # if folder exists, remove it and create an empty one
        shutil.rmtree(record)
        os.mkdir(record)
    # switch to the created folder
    os.chdir(record)
    # create the model file by using the record name
    model_file = open(record + ".sp", "w")
    # write modified script to the model file
    # remember now we are in the newly created folder, the record is stored in ..\NZStrongMotion
    model_file.write(template_model.replace(placeholder, '..\\NZStrongMotion\\' + record).replace(duration, '100'))
    # remember to close before running the model
    model_file.close()
    # now invoke suanPan to run the model
    # you may need to replace suanPan with the full path to the executable file if it is not added to PATH
    os.system('suanPan -f ' + record + '.sp > log.txt')
    # need to change back to parent folder
    os.chdir('..')

Postprocessing

What if to postprocessing data? Since the output files are stored in HDF5 format, one can use h5py to operate on those results to do whatever needed.