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, rocks, pharmaceutical 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 tackle inverse or data assimilation problems, with two meanings behind its name: (1) physical particle properties are learned from limited observations, and (2) statistical “particles” are used to achieve inference via sequential Monte Carlo filtering. GrainLearning can be also used with other empirical, numerical, or data-driven models that are strongly nonlinear in time.

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 continuum constitutive models. However, the modular design of GrainLearning allows for the implementation of other inference algorithms. The following figure shows the main modules of GrainLearning and their interconnections.

GrainLearning modules

Linking an external “software” model to GrainLearning can be done either in Python or via the callback function of the dynamic system class. Examples of such integration have been implemented for the DEM software packages, e.g., YADE, and MercuryDPM. For more information on how to integrate a model into GrainLearning, see dynamic systems.

While reading this documentation, please 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.

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