> For the complete documentation index, see [llms.txt](https://tlcfem.gitbook.io/suanpan-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tlcfem.gitbook.io/suanpan-manual/example/miscellaneous/batch-execution.md).

# 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](https://github.com/TLCFEM/suanPan-manual/blob/dev/docs/Example/Miscellaneous/batch-execution.zip).

It must be noted that by default, all output files generated by recorders are saved under the current working folder. Only the [Visualization](/suanpan-manual/recorder/recorder.md) recorder supports customized output folder name, which is again defined relative to current working folder.

Possible useful commands include: [`pwd`](/suanpan-manual/command-collection/process/pwd.md) , [`terminal`](https://github.com/TLCFEM/suanPan-manual/blob/dev/docs/Collection/Process/terminal.md). 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](/suanpan-manual/amplitude/special/nzstrongmotion.md) 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.

```ps
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

```py
import os
import shutil

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

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

#### Load All Record Names

```py
records = os.listdir('NZStrongMotion')
```

#### Loop

Now loop over each record and perform the analysis.

```py
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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tlcfem.gitbook.io/suanpan-manual/example/miscellaneous/batch-execution.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.