3.2. FEM: Finite Element Method

The FEM tab will present users with a selection of FEM applications. Currently, there are six options: OpenSees, Python, FEAPpv, SurrogateGP (using a surrogate model trained in quoFEM in place of a numerical simulation model), Custom (user-specified application), Multi Model (using more than one model in an analysis), along with the option of specifying no simulation model.

../../../../../_images/FEM4.png

Note

Because the UQ engines treat the FEM applications as a black box, when the UQ engine runs each deterministic simulation it expects the FEM application to output a single file. This file must be named results.out and be placed in the same directory as the main input file. The results.out file must contain a single line. That line must contain as many QoI values as the sum of the length of all the EDPs defined by the user in the QoI panel. Each value must be separated by a space. An example results.out file for a problem specifying four response QoI values is as shown:

63.8314 43.312 0.846004 0.00587503 

3.2.1. OpenSees

When the choice of FEM application is OpenSees (the default application), the user is presented with the input panel shown in figure above and there are two entry fields for filenames:

  1. Input Script: The user must specify a main input script. When entered the application will parse this file looking for variables set with the pset option (a unique set command to the OpenSees interpreter that is used to identify parameter values). For each variable whose value is set with pset, the program will auto populate the variable in the RV tab.

# units kN & mm

#
# set some parameters
#

pset E 205
pset P 25
pset Au 500
pset Ao 250

#
# build the model
#

model Basic -ndm 2 -ndf 2

node 1     0    0
node 2  4000    0
node 3  8000    0
node 4 12000    0
node 5  4000 4000
node 6  8000 4000

fix 1 1 1
fix 4 0 1

uniaxialMaterial Elastic 1 $E

element truss 1 1 2 $Ao 1
element truss 2 2 3 $Ao 1
element truss 3 3 4 $Ao 1
element truss 4 1 5 $Au 1
element truss 5 5 6 $Au 1
element truss 6 6 4 $Au 1
element truss 7 2 5 $Ao 1
element truss 8 3 6 $Ao 1
element truss 9 5 3 $Ao 1
timeSeries Linear 1
pattern Plain 1 1 {
    load 2 0 [expr -$P]
    load 3 0 [expr -$P]
}

#
# create a recorder
#

recorder Node -file node.out -scientific -precision 10 -node 1 2 3 4 5 6 -dof 1 2 disp

#
# build and perform the analysis
#

algorithm Linear
integrator LoadControl 1.0
system ProfileSPD
numberer RCM
constraints Plain
analysis Static
analyze 1

#
# remove the recorders
#

remove recorders
  1. Postprocess Script (optional): This is an optional entry where the user has the option of specifying either a tcl script or a Python script that will be used to postprocess the results and create a results.out file after the main script runs. See for instance, example 1.

Note

The postprocess file can be either a tcl script or a Python script and the file extensions must be either .py or .tcl.

Warning

If a tcl script file and the user is reading results from files created with OpenSees recorder commands, the user must ensure there is a wipe recorders command at the end of the main script or at the start of the postprocessing script.

3.2.2. Python

The user provides a main script and has the option to provide 2 other scripts:

../../../../../_images/openseespyFEM.png
  1. Postprocess Script (Optional): This must be a Python script which is provided the QoI variable names when started. This entry can be left blank if the main script creates a results.out file with a single line as described for the OpenSees application.

  2. Parameters File: This file allows for the automatic population of the RV tab with any variables found in the file. For example if the file contained the following:

# set some parameters

E = 205
P = 25
Ao = 250
Au = 500

The RV tab would be populated with the E, P, Ao, and Au random variables. See example 2 for more. For the Windows users, see the below important warning.

Caution

Python on Windows. On Windows, quoFEM is bundled with its own python.exe, with the essential packages (including numpy, scipy, openseespy) already installed. By default, this python.exe is used to (1) run SimCenter workflow; and (2) run the user-provided python model. Therefore, please make sure to test your model using the “correct” python.exe before running in quoFEM.

../../../../../_images/step1_preference_default1.svg

Fig. 3.2.2.1 Windows Default Python Path found in File-Preference

  • “Pip install” Python packages

    If your model requires additional python packages, use the following command to install them.

    {$PythonExePath} -m pip install {$PackageName}
    

    where {$PythonExePath} is the (default) python path shown in the preference window and {$PackageName} is the name of the python package.

  • Use custom Python

    ../../../../../_images/step1_preference_custom.svg

    Fig. 3.2.2.2 Custom Python Path

    If you would like to use other version of python in quoFEM, use the custom option in File-Preference. Then you will need to manually install the packages required to run SimCenter workflow using.

    {$NewPythonExePath} -m pip install nheri_simcenter --upgrade
    

    where {$NewPythonExePath} is the new python path specified in the preference window.

3.2.3. FEAPpv

FEAPpv is another FEM engine used by the quoFEM app that is publicly available from the FEAPpv page. FEAPpv is a general purpose finite element analysis program which is designed for research and educational use. To install FEAPpv you must download the source code and follow the build instructions on the Source Code Download and Compile Instructions section of the FEAPpv page.

Similar to the OpenSees application, when the user selects FEAPpv the user is requested to provide two files.

../../../../../_images/feapFEM.png
  1. Input File: The user must specify a main input file. A part of this file may contain variables set in the PARA section. The variables in this section will be read by the UI when the file is entered and will be autopopulated in the RV tab. For example if a file containing the following code was specified:

  1. Postprocess Script: The user must provide the name of the Python script that will run when FEAPpv has finished executing. This Python script must load the output file from FEAPpv and create the results.out file. Currently the user has no control over the name of the output file created by FEAPpv, SimCenterOut.txt. It is this file the post-process script must open and use to create the results.out file.

3.2.4. Custom

This option allows users to specify custom simulation applications which do not necessarily need to be limited to only Finite Element Method software. With this option all users need to do is provide a driver script that takes the input file generated by the UQ engine, parses and passes the inputs to the custom analysis engine, and processes the results to meet the format requirements specified for results.out. The inputs generated by the UQ engine will be provided in a file named params.in and will always follow the format shown in the example params.in file below. The first line specifies the number of random variables while the subsequent lines first contain the name of the random variable and the value of the current realization separated by a space.

2
randomVariable 2.719191180014362e+02
anotherRandomVariable 7.518852020241320e+01

For the custom simulation application, the user provides at least two inputs:

  • The script that drives the simulations which must be named driver.bat on Windows and driver on MacOS and Linux

  • The script that post-processes the simulation results and writes them to results.out in the required format

Additionally, users can specify as many additional files and binaries as required by the application by increasing the number of input slots, as shown in Fig. 3.2.4.1. By specifying these files here, they will be copied to the correct location for quoFEM to access them during analyses. Users also have the option to simply place all the required files in the same location as the provided workflow driver script – quoFEM will automatically copy any files in this directory. This is particularly helpful if several different applications with numerous inputs are all being called by the workflow driver script and avoids the need to explicitly input each one of these files.

../../../../../_images/customFEM.png

Fig. 3.2.4.1 Input for Custom Analysis Application

3.2.5. SurrogateGP

In place of the physical simulation models, the Gaussian process surrogate model trained in quoFEM can be imported for UQ/Optimization analyses.

../../../../../_images/SurrogateFEM1.png

Fig. 3.2.5.1 Input for Surrogate model FEM Application

When users select the SurrogateGP option, they are requested to provide Surrogate info file (.json) that contains the information about the surrogate model. Users can open it with a text editor to see the contents. Once the file is loaded, users may choose the tolerance level of the predictive variance.

  • Maximum Allowable Normalized Variance: Prediction variance divided by the variance level of the training dataset. If more than one QoIs is introduced, only the highest normalized variance value will be considered.

Warning

  • It is important to understand that the predictive variance does not necessarily imply the error level of the model.

  • The provided percentage ratio of the out-of-tolerance samples is only a rough guideline since it assumed that the samples are uniformly populated throughout the range user provided during the training session. Therefore, if user selects other distribution types and ranges, the percentage estimation will not be correct anymore.

Users may either stop the analysis, continue, or run exact FEM simulations whenever the tolerance limit is exceeded.

  • Stop Analysis: The analysis is immediately terminated. quoFEM will show the error (eg. dakota engine gives “No dakotaTab.out file” error)

  • Continue: The tolerance level is ignored and the analysis is continued. This option is not recommended.

  • Run Exact FEM Simulation: The program will run the exact FEM simulation user provided in the training session. In case the surrogate model is constructed purely based on the data and without any model information (case 3 in section 2.1.2.2), this option will be disabled. To allow this option, an additional folder that contains the simulation information is required. This folder, called Simulation template folder (templatedir_SIM), contains the simulator scripts (workflow driver) and required files to run the original simulation model. This file can be obtained by

Note

The surrogate model file (.json) and Simulation template folder (templatedir_SIM) can be generated from the quoFEM. See Gaussian Process (GP) Surrogate Modeling.

Additionally, GP output can be set as either the median prediction or a random sample generated from the normal distribution (or lognormal distribution if the user used log-transform when training) with the predictive median and variance. NOTE: the random generator does not account for the Gaussian process correlation, and each realization of QoI given RVs is independent of each other. Only users familiar with GP modeling and who understand the limitation are recommended to use the random sample option.

If the user wants to inspect the simulation status or check error/warning messages related to the surrogate model, they can refer to the messages written at: {Local Jobs Directory}/tmp.SimCenter/surrogateLog.err. (Note: {Local Jobs Directory} is specified from the file-preference in the menu bar.)

../../../../../_images/SurrogateFEM2.png

Fig. 3.2.5.2 Example of surrogateLog.err file

Note

Once the surrogate model is imported, RV and QoI tab will be auto-populated. Users are allowed to remove some of the QoIs if not interested but may not add new QoIs or modify the names of existing QoIs.

3.2.6. Multi Model

By selecting this option, users can define multiple numerical simulation models for use in their UQ analysis. The Add and Remove buttons allow users to control the number of models they want to use in the analysis.

../../../../../_images/multiModel1.png

Fig. 3.2.6.1 Input for Multi Model FEM Application

By adding a model, a new tab is created in the FEM panel where users can choose one of the FEM applications described in the sections above and provide the inputs necessary to define the model. Users also need to specify their belief about the credibility of the model in the tab corresponding to that model. The beliefs are expressed as non-negative numerical values. The belief value for each model is defined relative to the other models, and the beliefs do not need to sum to 1.

../../../../../_images/multiModel2.png

Fig. 3.2.6.2 Selecting a FEM application within a model tab

Note

If a Multi Model application is selected, at least 2 models must be defined.

3.2.6.1. Video Resources

Recorded in tool training, 2022.