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

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:
  • 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 tge 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 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:

cellRF

Loading paths are generated for three types of loadings:

1. Random Walk paths with rate variant data points (RW).
2. Random Cyclic paths with rate variant data points (CR).
3. Random Cyclic paths with constant rate data points (CC).

rnnRF

Random SVEs are generated for a selected lattice by varying either,the strut radius or the volume fraction. Geometrical parameters for lattices along with their description are as:

Parameter	Type	Description
typeRand	String literal	Generation parameter for the selected lattice: 'a' for volume fraction, 'b' for radius
vf	List of floats	Bounds of volume fraction
rad	Int	Bounds for radius in mm
size	List of int	Bounds for cell size in mm.
cell_num	list if int	Periodicity of thr Cell. eg a 1x1x1 cell will be specified as [1, 1, 1]

Material Properties

A visco-elastic - visco-plastic constitutive model ¹ is adopted for data generation. 32 Material Parameters (Incorporating 8 Maxwell Branches) are identified using Bayesian Inference (BI) ² for polyamide 12 (PA-12) polymer.

A realization of BI identified material properties, that are provides reliable numerical convergence is used for data generation. These Material parameters are specified in the last row of PA.csv and can be selected using the following parameters:

Parameter	Type	Value
mat	String literal	"PA"
mat_ver	Int	6

Micro-Solver

dG3D micro-solver routines for a macro cauchy continuum or strain gradient continuum can be selected by assigning solver the value of 'rve_solver' or 'HO_rve_solver' respectively. Furthermore if using higher order kinematics the HO flag must be set True.

Storage Directories

By default, the data is stored as specified in the Structure of repository. However these paths can be changed using load_dir and data_dir

Data Generation

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.

1. The finite-strain visco-elastic visco-plastic model follows:
   "Nguyen, V. D., Lani, F., Pardoen, T., Morelle, X., & Noels, L. (01 October 2016). A large strain hyperelastic viscoelastic-viscoplastic-damage constitutive model based on a multi-mechanism non-local damage continuum for amorphous glassy polymers. International Journal of Solids and Structures, 96, 192-216. doi:10.1016/j.ijsolstr.2016.06.008" which can be downloaded here. We would be grateful if you could cite this publication in case you use the files. ↩

2. "Wu, L., Anglade, C., Cobian, L., Monclus, M., Segurado, J., Karayagiz, F., Freitas, U., & Noels, L. (23 November 2023). Bayesian inference of high-dimensional finite-strain visco-elastic-visco-plastic model parameters for additive manufactured polymers and neural network based material parameters generator. International Journal of Solids and Structures, 283, 112470. doi:10.1016/j.ijsolstr.2023.112470" which can be downloaded here. We would be grateful if you could cite this publication in case you use the files. ↩