README.md

Stochastic Finite Element Method (SFEM)

This repository contains:

• A spectral generator of random fields (RF).
• Scripts to vizualize of the random fields.
• 2 test cases of Monte-Carlo (MC) stochastic finite element simulations (SFEM).

Table of Contents

1. Dependencies and Prerequisites
2. Structure of Repository
3. Spectral Generator of RF
4. RF vizualization
5. Test Cases of MC SFEM

Dependencies and Prerequisites

• Python, pandas, matplotlib, texttabble and latextable are pre requisites for visualizing and navigating the data.

• For generating mesh and for vizualization, gmsh (www.gmsh.info) is required.

• For running simulations, cm3Libraries (http://www.ltas-cm3.ulg.ac.be/openSource.htm) is required.

Instructions using apt & pip3 package manager

Instructions for Debian/Ubuntu based workstations are as follows.

python, pandas and dependencies

 sudo apt install python3 python3-scipy libpython3-dev python3-numpy python3-pandas

matplotlib, texttabble and latextable

 pip3 install matplotlib texttable latextable

Pytorch (only for run with cm3Libraries)

 pip3 install --pre torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/nightly/cpu

Structure of Repository

• generateRF contains all the scripts used to generate and vizualize the random fields
• cellRF contains an example in which we generate a single variable random field on a lattice unit cell
• rnnRF contains an example in which we generate a correlated two-dimension random field and the siulations script to run Monte Carlo simulations on a multiscale lattice compression using a MOAMMM stochastic neural network as surrogate of the cell response.

generateRF

• generateRF.py: file used to generate the random fields
  • The RF is defined from the mean and standard deviation of the variables as well as from their correlation following for example for a 2-dimension RF:
    • meanX = np.array([0.5,10]) # mean of variables
    • stdX = np.array([0.05,0.1]) # std of variables
    • rho = 0.2
    • R0_XY = np.array([[1, rho], [rho, 1]]) #covariance matrix
  • And from a the correlation lengths along the 3 direction
    • lc = [15., 15., 15.] # correlation length
  • The number of RFs to be generated follows from
    • Nsim =10
  • The Random fields will be generated at the spatial points defined in terms of their coordinates.
    • The script tries to read a file in mechDir+'/GPData', where mechDir is the working directory, describing the list of spatial points. One example of points coordinates can be found in rnnRF/GPData/coordinate_P_ZZ_OnPhysical_11.csv stored following 3 coordinates, point number and point volume (for a FE simulation).
    • The random field number X is saved in the file mechDir+'/randomFields/RandField_X.csv', where mechDir is the working directory. The number of columns is the dimension of the random variable and the number of lines the number of spatial points. One example of generated 2-dimension RF can be found in rnnRF/randomFields/RandField_0.csv.
    • The random field number X along with the spatial points coordinates is saved in the file mechDir+'/randomFields/RandField_And_GP_X.csv', where mechDir is the working directory. The number of columns is the dimension of the random variable plus the 3 spatial coordinates and the number of lines the number of spatial points. One example of generated 2-dimension RF can be found in rnnRF/randomFields/RandField_And_GP_0.csv.
  • The variable recomputePDF=True forces the evaluation of the spectral density matrix, which will be saved in mechDir+'/randomFields/H_pdf.dat'.
  • The variable recomputePDF=False reads the spectral density matrix already saved in mechDir+'/randomFields/H_pdf.dat'
• plotRF.py: file used to vizualize the distribution of the random variables.
  • Reads the N random fields of type 'RandField_X.csv' found in mechDir+'/randomFields/', where mechDir is the working directory. Examples of generated 2-dimension RFs can be found in rnnRF/randomFields/.
  • Plot the distribution of the random variables.
• vizualizeRF.py: file used to generate a gmsh (www.gmsh.info) compatible file to vizualize the random fields
  • Reads the N random fields of type 'RandField_And_GP_X.csv' found in mechDir+'/randomFields/', where mechDir is the working directory. Examples of generated 2-dimension RFs can be found in rnnRF/randomFields/.
  • Uses the mesh structure of the considered application. The script tries to read stress file in mechDir+'/GPData', where mechDir is the working directory, describing the elements structure. One example of stress file can be found in rnnRF/GPData/stress_step1.msh.
  • The random field number X is saved in format compatible with Gmhs in the file mechDir+'/randomFields/RandField_X.msh', where mechDir is the working directory. One example of generated 2-dimension RF can be found in rnnRF/randomFields/RandField_0.msh.
• utilRF.py: set of functions used by the RF generator and vizualization files.

rnnRF

• rubics.geo: geometry file of a cube to be read by gmsh (www.gmsh.info).
• rubics.msh: mesh file of a cube generated by gmsh (www.gmsh.info).
• macro_cpp.py: multiscale lattice compression script to be run with cm3Libraries (http://www.ltas-cm3.ulg.ac.be/openSource.htm) and using a MOAMMM stochastic neural network as surrogate of the cell response.
• Bounds.dat: Bounds of the neural network model.
• model.dat: torch neural network model.
• generateGPInfo.py: generate the Gauss points coordinates and mesh structure to be used by the random field generator. It requires cm3Libraries (http://www.ltas-cm3.ulg.ac.be/openSource.htm).
  • The script write the Gauss points coordinates in the directory 'rnnRF/GPData'. One example of points coordinates can be found in rnnRF/GPData/coordinate_P_ZZ_OnPhysical_11.csv stored following 3 coordinates, point number and point volume (for a FE simulation).
  • The script write the mesh structure in the directory 'rnnRF/GPData'. One example of stress file can be found in rnnRF/GPData/stress_step1.msh.
• runMCTest.py: Monte Carlo simulations on a multiscale lattice compression using a MOAMMM stochastic neural network as surrogate of the cell response. It requires cm3Libraries (http://www.ltas-cm3.ulg.ac.be/openSource.htm).
• The script uses the N random fields of type 'RandField_And_GP_X.csv' found in rnnRF/randomFields/'. Examples of 2-dimension RFs can be found in rnnRF/randomFields/.
• The script saves the simulations results in 'rnnRF/results/RandField_And_GP_X.csv/'
• plotMC.py: vizualize the different force displacement curves of the MC simulations.
• The script reads the simulations results saved in 'rnnRF/results/RandField_And_GP_X.csv/'

cellRF

• 80017_3_128.geo: geometry file of a lattice cell to be read by gmsh (www.gmsh.info).
• 80017_3_128.msh: mesh file of a lattice cell generated by gmsh (www.gmsh.info).
• MaterialProperties.csv PA12 viscoelastic-viscoplastic properties, see MOAMMM cell simulations.
• rve_solver.py: interface with cm3Libraries (http://www.ltas-cm3.ulg.ac.be/openSource.htm).
• strainPath80017.csv: loading path applied on the cell, see MOAMMM cell simulations.
• runthread.py: script to be run to simulate the cell loading case. Deterministic in this example. It requires cm3Libraries (http://www.ltas-cm3.ulg.ac.be/openSource.htm).

Example of application

Once the parameters are defined inside of the driver script, data can be generated. This process consists of three seperate steps:

Load path generation

Load path is generated by executing the driver script with the path argument.

Executing the following will generate the loading paths based on the load path parameters defined inside driver.py.

python3 driver.py path

After execution. the load paths are generated inside the Cell<cell_type>/LoadingPath under unique subfolders using the following naming scheme:

<load_type>_R<r_max>dR<eval_step>SRate<s_rate>K<k>

Thread creation

Threads are folders that contain the randomly generated SVE's alongside their intended loading paths, whose parameters are defined inside the driver.py script. Executing a thread, generates the data by simulating the SVE response on the load paths.

Thread creation is done by executing the driver script with the thread argument.

python3 driver.py thread 

The number of threads created per each load_type equals to the variable n_split

Thread are created inside the Cell<cell_type>/DataPaths directory per the following naming scheme:

G<cell_type>Y<cell_num>L<size>Rad<radius><mat>_<load_path>

Thread execution

Threads created in the last step can be simulated using the dG3D Finite element solver available opensource (GPL) under the cm3Libraries. For access visit MOAMMM Developed software

To execute threads, run the following inside in the directory where threads are generated with thread numbers as arguments.

For example, execting the following will run thread 5 , 7 and 10.

./run.sh 5 7 10

Database and Visualization

Data and load paths are stored under their respective Cell names as per the naming convention detailed in thread creation and load path generation.

Load Path Visualization

Histograms, path reports and visual representation of randomly selected paths are computed automatically at generation time, and can be found inside the pathReports folder under the unique load path storage folder.

Chosen load paths can be visualized by specifying the unique folder and paths inside the driver scripts.

Parameter	Type	Description
vis_load_folder	String	Name of the unique load folder folder
vis_load_paths	List of strings	Names of the selected paths inside the folder

Executing the driver script with the vload argument, will generate and save the plots under the vis_load_folder.

A set of paths are specified in the example driver.py script and can be generated as follows.

python3 driver.py vload 

📘 Info
vis_load_folder only needs the name of the parent folder.
No need to append load_dir. Absolute path is determined automatically.

Data Path Visualization

Selected data paths can be visualized by specifying the unique folder and paths inside the driver scripts.

Parameter	Type	Description
vis_data_folder	String	Name of the unique data folder folder
vis_data_paths	List of strings	Names of the selected paths inside the folder

Executing the driver script with the vdata argument, will generate and save the plots under the vis_data_folder.

A set of paths are specified in the example driver.py script and can be generated as follows.

python3 driver.py vdata 

📘 Info
vis_data_folder only needs the name of the parent folder.
No need to append data_dir. Absolute path is determined automatically.

Alternate Method

This method requires appending, location ofdriver.py in your $PATH enviroment variable.

Executing driver.py with the v argument followed by the names of (load or data) paths (seperated with spaces) at the stored location will generate the visualizations and save them at (one level above the parent folder) under Plots.

For example executing the following at stored location will visualize the 4 specified loadpaths

driver.py v strainPath80001.csv strainPath80002.csv strainPath80003.csv strainPath80004.csv  

This method can be used to quickly visualize paths withoutchanging the driver.py script.

Histograms for Generated Data

Spread of generated data can be visualized by executing the driver script with the collect argument.

python3 driver.py collect 

By default this will generate histograms all data paths for the specified cell_type contained in the DataPaths and store them in the CollectedData folder

Surrogate Modelling

RNN Parameters

Parameters for Recurrent neural network are defined inside the driver.py, categorized as:

Parameter	Type	Description
Datatype	String Literal	IO (Conjugate) Pair. "GS" for Green Lagrange Strain, Second Piola Kirchoff Stress
n_pad	Int	Padding for Normalized Data
input_dim	Int	Width of FF Layers
hidden_dim	Int	RNN hidden variables
forward_layers0	Int	Depth of FF Output Layers
forward_layers	Int	Depth of FF Input Layers
default	flag	Choice of device for training/testing: "cpu", "cuda" or True (for default)
ratio	float	Training / Testing Ratio
Nt	Int	Batch iterations for training
mini_batch	float	Batch size of testing_data specified as a ratio: 1.0 selects all testing data, 0.25 selects quarter.
n_epochs1	Int	Epoch Training per batch
n_epochs2	Int	Epoch Training per batch ( Optional)
n_epochs3	Int	Epoch Training per batch ( Optional)
lr	float	learning rate
decay_factor	float	learning rate decay factor to to applied at the end of batch epoch (Optional)
Pn	Int	Print training status per epoch
Testn	Int	Print testing status per epoch
Sn	Int	Save model per epoch

Surrogate Training

Data collection

First the data for training needs to be collected for the surrogate to start training. This entails running the driver.py script with the collect argument.

python3 driver.py collect 

By default this will collect all the data availible under the DataPaths subfolder for a specified cell defined in the driver.py script, and store it as a OrigG_S.dat inside the CollectedData folder. This will also generate a Bounds.dat File that will store the upper and lower bounds of the generated data.

Training

Invoking the driver.py script with arguments train cold starts the training process (from scratch), per the RNN parameters definied in the last section.

python3 driver.py train cold 

Setting the parameter default to TRUE will automatically use GPU if (CUDA compatible) is available, however it can also be set manually by setting its value to "cpu" or "cuda".

If memory becomes a bottleneck, a mini batch of data which gets randomly shuffled per batch iteration can be used for training. The size of mini batch is given as a ratio to original size in the parameter mini_batch, where each mini_batch gets n_epochs after which a new shuffled mini_batch is sampled. This goes on Nt batch iterations.

Warm start

Invoking the driver.py script with arguments train warm resumes the training process from a previous saved state.

python3 driver.py train warm 

Surrogate Testing

Inside the RNNSurrogate folder training and testing error plots are generated whose update frequency is dictated by the variable Pn. Intermediate state for warm start is saved per the frequency defined as Sn using the folllowing naming convention.

ModelGRU_GS_0f<forward_layers0>_<input_dim>_f<forward_layers>_<hidden_dim>

Visualization

Training Plots

Executing the driver.py script with arguments pred and train followed by the index of the training paths will plot its stress-strain response alongside the surrogate prediction. e.g. executing the following will populate the comparison of data path 5, 8 and 32 in the training data set with its predicted values.

python3 driver.py pred train 5 8 32

Testing Plots

Executing the driver.py script with arguments pred and test followed by the index of the testing paths will plot its stress-strain response alongside the surrogate prediction. e.g. executing the following will populate the comparison of data path 2, 4 and 9 in the testing data set with its predicted values.

python3 driver.py pred test 2 4 9

Disclaimer

Code related to MOAMMM project This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 862015.

Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union. Neither the European Union nor the granting authority can be held responsible for them.