2.2. FEM: Finite Element Method

The FEM tab will present users with a selection of FEM applications. Currently, there are four options: OpenSees, FEAPpv, OpenSeesPy, and a custom user-specified application.

../../../../../_images/FEM.png

Fig. 2.2.1 Input for the FEM tab.

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 user will enter 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 

2.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.

  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.

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.

2.2.2. 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.

2.2.3. OpenSeesPy

For the OpenSeesPy application, 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:

The RV tab would be populated with the E, P, Ao, and Au random variables.

2.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 workflow_driver.bat on Windows and workflow_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. 2.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. 2.2.4.1 Input for Custom Analysis Application

2.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. 2.2.5.1 Input for Surrogate model FEM Application

When users select the SurrogateGP option, they are requested to provide the following files:

Note

All the required input files described below can be generated from the quoFEM. See Section 2.1.2.2 Surrogate modeling.

  1. Surrogate info file (.json): This file contains the meta-information about the surrogate model. Users can open it with a text editor to see the contents.

  2. Surrogate model file (.pkl): Surrogate model is saved in a binary format. GPy python package is required to view or use this model outside of quoFEM.

Additionally, if users want to allow alternation between the exact simulation model and surrogate model depending on the predicted error rate, an additional folder that contains the simulation information is required (See Run Exact FEM Simulation option below). Note that this folder is not explicitly specified in the input panel, but it needs to be located in the specific directory under the specific name (templatedir_SIM).

  1. Simulation template folder (templatedir_SIM): This folder contains the simulator scripts (workflow driver) and required files to run the original simulation model. Note that the folder should be located in the same directory as the Surrogate info file. If the folder is not presented in the right directory, the analysis can fail. The name of the folder should not be modified.

Once the files are 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.

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. 2.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.