Welcome to GrainLearning!

fair-software.eu recommendations	Badges
code repository
license
community registry
citation
Best practices checklist
howfairis
Documentation
Code Quality
Paper

Bayesian uncertainty quantification for discrete and continuum numerical models of granular materials, developed by various projects of the University of Twente (NL), the Netherlands eScience Center (NL), University of Newcastle (AU), and Hiroshima University (JP). Browse to the GrainLearning documentation to get started.

Features

• Infer and update model parameters using "time" series (sequence) data via Sequential Monte Carlo filtering
• Uniform, quasi-random sampling using low-discrepancy sequences
• Iterative sampling by training a nonparametric Gaussian mixture model
• Surrogate modeling capability for "time" series data

Installation

Install using poetry

1. Install poetry following these instructions.
2. Clone the repository: git clone https://github.com/GrainLearning/grainLearning.git
3. Go to the source code directory: cd grainLearning
4. Activate the virtual environment: poetry shell
5. Install GrainLearning and its dependencies: poetry install

Install using pip

1. Clone the repository: git clone https://github.com/GrainLearning/grainLearning.git
2. Go to the source code directory: cd grainLearning
3. Activate the virtual environment: conda create --name grainlearning python=3.12 && conda activate grainlearning
4. Install GrainLearning and its dependencies: pip install .

Developers please refer to README.dev.md.

To install GrainLearning including the RNN module capabilities check grainlearning/rnn/README.md.

For Windows users

• Installation using Windows Subsystem for Linux (WSL)
  • Enable WSL1 or WSL2 according to the instructions here
  • Install GrainLearning using poetry or pip
• Installation using anaconda (if no WSLs are available on your Windows system)
  • Open Anaconda Prompt and install GrainLearning using pip. This should create a virtual environment, named GrainLearning.
  • Choose that environment from your anaconda navigator: click Environments and select grainlearning from the drop-down menu

One command installation

Stable versions of GrainLearning can be installed via pip install grainlearning However, you still need to clone the GrainLearning repository to run the tutorials.

Tutorials

1. Linear regression with the run_sim callback function of the BayesianCalibration class, in python_linear_regression_solve.py

2. Nonlinear, multivariate regression

3. Interact with the numerical model of your choice via run_sim , in linear_regression_solve.py

4. Load existing DEM simulation data and run GrainLearning for one iteration, in oedo_load_and_resample.py

5. Example of GrainLearning integration into YADE

   • Two particle collision
   • Triaxial compression

6. Data-driven module tutorials:

   • Train your LSTM model
   • Predict using an LSTM model
   • Use an LSTM model in the calibration workflow

Citing GrainLearning

Please choose from the following:

• A DOI for citing the software.
• The software paper: Cheng et al., (2024). GrainLearning: A Bayesian uncertainty quantification toolbox for discrete and continuum numerical models of granular materials. Journal of Open Source Software, 9(97), 6338, 10.21105/joss.06338
• H. Cheng, T. Shuku, K. Thoeni, P. Tempone, S. Luding, V. Magnanimo. An iterative Bayesian filtering framework for fast and automated calibration of DEM models. Comput. Methods Appl. Mech. Eng., 350 (2019), pp. 268-294, 10.1016/j.cma.2019.01.027

Software using GrainLearning

• YADE
• MercuryDPM

Community

The original development of GrainLearning is done by Hongyang Cheng, in collaboration with Klaus Thoeni , Philipp Hartmann, and Takayuki Shuku. The software is currently maintained by Hongyang Cheng and Stefan Luding with the help of Luisa Orozco and Retief Lubbe. The GrainLearning project receives contributions from students and collaborators.

Help and Support

For assistance with the GrainLearning software, please create an issue on the GitHub Issues page.

Credits

This package was created with Cookiecutter and the NLeSC/python-template.