Introduction

Welcome to GrainLearning!

GrainLearning is a toolbox for Bayesian calibration and uncertainty quantification of computer simulations of granular materials. It is designed to make uncertainty quantification, sensitivity analysis, and calibration simple, for computational models of granular materials, such as soils, powders, and food grains. GrainLearning is written in Python and is built on top of the NumPy and SciPy libraries.

GrainLearning was initially developed for inferring particle- or microstructure-scale parameters in discrete element method (DEM) simulations of granular materials. It is designed to solve inverse or data assimilation problems, with two meanings behind its name:

  1. physical particle properties are learned from limited observations,

  2. statistical “particles” are used to achieve inference via sequential Monte Carlo filtering.

GrainLearning is non-intrusive. Computer models used by GrainLearning are blackboxes and therefore can be theoretical, numerical, or data-driven.

The most important modules of GrainLearning are dynamic systems, inference, and sampling. An unique feature of GrainLearning is the machine learning (ML) capabilities of the samplers to learn complex probability distributions and the data-driven emulators to learn the physics. Users can combine different classes in these modules to create a variety of Bayesian calibration tools. Currently, only the iterative Bayesian filter has been implemented, and tested with DEM models and theoretical constitutive models. The available data-driven emulator is Long Short-Term Memory (LSTM) networks widely used for predicting time series. However, the modular design of GrainLearning allows for the implementation of other inference algorithms and models. The following figure shows the main modules of GrainLearning and their interconnections.

GrainLearning modules

Users only need to write a callback function and pass it to BayesianCalibration where parameter samples are sent to an external “software” or Python model. Examples of this can be found for YADE (Yet Another Dynamic Engine). For more information on how to integrate a predictive model into GrainLearning, see dynamic systems.

Note

While reading this documentation, keep in mind the following definitions, as they will appear frequently in various sections.

  • Prior: the initial knowledge about model state and/or parameter before any data is taken into account, expressed as a probability distribution.

  • Posterior: the updated knowledge after the evidence is taken into account via Bayes’ theorem.

  • Proposal: the distribution from which we draw new samples. It can be assumed or learned.

  • Samples: the combination of model parameters drawn from a distribution, leading to certain “randomly” distributed model states.

  • Model evaluation: the execution of the model at the sample points.

  • Ensemble: the probability distribution of the model state, represented as a collection of state vectors and their associated weights.

  • Filtering: the process of updating the ensemble as new data is taken into account.

We draw inspiration from the UQpy and MUSCLE3 libraries when designing the GrainLearning software and its documentation.