# Welcome to GrainLearning!
| fair-software.eu recommendations | Badges |
|:--- | :--|
| code repository | [](https://github.com/GrainLearning/grainlearning) |
| license | [](https://github.com/GrainLearning/grainlearning)|
| community registry | [](https://research-software-directory.org/projects/granular-materials) [](https://pypi.python.org/project/grainlearning/)|
| citation | [](https://doi.org/10.5281/zenodo.7123965)|
| Best practices checklist | [](https://bestpractices.coreinfrastructure.org/projects/6533)|
| howfairis | [](https://fair-software.eu)|
| Documentation | [](https://grainlearning.readthedocs.io/en/latest/?badge=latest)|
| Code Quality | [](https://sonarcloud.io/summary/new_code?id=GrainLearning_grainLearning) [](https://sonarcloud.io/summary/new_code?id=GrainLearning_grainLearning) |
| Paper | [](https://doi.org/10.21105/joss.06338) |
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](https://grainlearning.readthedocs.io/en/latest/) to get started.
## Features
- Infer and update model parameters using "time" series (sequence) data
via [Sequential Monte Carlo filtering](https://en.wikipedia.org/wiki/Particle_Filter)
- Uniform, quasi-random sampling using [low-discrepancy sequences](https://en.wikipedia.org/wiki/Halton_sequence)
- Iterative sampling by training a
nonparametric [Gaussian mixture model](https://scikit-learn.org/stable/modules/generated/sklearn.mixture.BayesianGaussianMixture.html)
- [Surrogate modeling](https://grainlearning.readthedocs.io/en/latest/rnn.html) capability for "time" series data
[//]: # (using [recurrent neural networks](https://en.wikipedia.org/wiki/Recurrent_neural_network))
[//]: # (- Hybrid physics-based and data-driven model evaluation strategy)
## Installation
### Install using poetry
1. Install poetry following [these instructions](https://python-poetry.org/docs/#installation).
1. Clone the repository: `git clone https://github.com/GrainLearning/grainLearning.git`
1. Go to the source code directory: `cd grainLearning`
1. Activate the virtual environment: `poetry shell`
1. Install GrainLearning and its dependencies: `poetry install`
### Install using pip
1. Clone the repository: `git clone https://github.com/GrainLearning/grainLearning.git`
1. Go to the source code directory: `cd grainLearning`
1. Activate the virtual environment: `conda create --name grainlearning python=3.12 && conda activate grainlearning`
1. Install GrainLearning and its dependencies: `pip install .`
__Developers__ please refer to [README.dev.md](README.dev.md).
To install GrainLearning including the RNN module capabilities check [grainlearning/rnn/README.md](grainlearning/rnn/README.md).
### For Windows users
- Installation using Windows Subsystem for Linux (WSL)
- Enable WSL1 or WSL2 according to the
instructions [here](https://learn.microsoft.com/en-us/windows/wsl/install-manual)
- Install GrainLearning using [poetry](#install-using-poetry) or [pip](#install-using-pip)
- Installation using anaconda (if no WSLs are available on your Windows system)
- Open Anaconda Prompt and install GrainLearning using [pip](#install-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`](tutorials/simple_regression/linear_regression/python_linear_regression_solve.py#L14)
callback function of the [`BayesianCalibration`](grainlearning/bayesian_calibration.py)
class,
in [python_linear_regression_solve.py](tutorials/simple_regression/linear_regression/python_linear_regression_solve.py)
2. Nonlinear, multivariate regression
3. Interact with the numerical model of your choice
via [`run_sim`](tutorials/simple_regression/linear_regression/linear_regression_solve.py#L11)
,
in [linear_regression_solve.py](main/tutorials/simple_regression/linear_regression/linear_regression_solve.py)
4. Load existing DEM simulation data and run GrainLearning for one iteration,
in [oedo_load_and_resample.py](tutorials/oedo_compression/oedo_load_and_resample.py)
5. Example of GrainLearning integration into YADE
- [Two particle collision](tutorials/physics_based/two_particle_collision)
- [Triaxial compression](tutorials/physics_based/triaxial_compression)
6. Data-driven module tutorials:
- [Train your LSTM model](tutorials/data_driven/LSTM/train_rnn.ipynb)
- [Predict using an LSTM model](tutorials/data_driven/LSTM/predict.ipynb)
- [Use an LSTM model in the calibration workflow](tutorials/data_driven/LSTM/rnn_calibration_GL.ipynb)
## Citing GrainLearning
Please choose from the following:
- [](https://doi.org/10.5281/zenodo.7123965) 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](https://doi.org/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](https://doi.org/10.1016/j.cma.2019.01.027)
## Software using GrainLearning
- [YADE](http://yade-dem.org/)
- [MercuryDPM](https://www.mercurydpm.org/)
## Community
The original development of `GrainLearning` is done by [Hongyang Cheng](https://hongyangcheng.weebly.com), in collaboration
with [Klaus Thoeni](https://www.newcastle.edu.au/profile/klaus-thoeni)
, [Philipp Hartmann](https://www.newcastle.edu.au/profile/philipp-hartmann),
and [Takayuki Shuku](https://sites.google.com/view/takayukishukuswebsite/home).
The software is currently maintained by [Hongyang Cheng](https://hongyangcheng.weebly.com) and [Stefan Luding](https://www2.msm.ctw.utwente.nl/sluding/) with the help
of [Luisa Orozco](https://www.esciencecenter.nl/team/dr-luisa-orozco/)
and [Retief Lubbe](https://tusail.eu/projects/esr-12.html).
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](https://github.com/audreyr/cookiecutter) and
the [NLeSC/python-template](https://github.com/NLeSC/python-template).
Raw data
{
"_id": null,
"home_page": "https://grainlearning.readthedocs.io/",
"name": "GrainLearning",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.9",
"maintainer_email": null,
"keywords": "Bayesian inference, Uncertainty quantification, Non-parametric Gaussian mixture, DEM, Constitutive modeling, Granular materials",
"author": "Hongyang Cheng",
"author_email": "h.cheng@utwente.nl",
"download_url": "https://files.pythonhosted.org/packages/bb/0c/65ee8733db1d80e35493070278d3b4b5cf79add870d3c6d834c4a103f731/grainlearning-2.0.4.tar.gz",
"platform": null,
"description": "# Welcome to GrainLearning!\n| fair-software.eu recommendations | Badges |\n|:--- | :--| \n| code repository | [](https://github.com/GrainLearning/grainlearning) |\n| license | [](https://github.com/GrainLearning/grainlearning)|\n| community registry | [](https://research-software-directory.org/projects/granular-materials) [](https://pypi.python.org/project/grainlearning/)|\n| citation | [](https://doi.org/10.5281/zenodo.7123965)|\n| Best practices checklist | [](https://bestpractices.coreinfrastructure.org/projects/6533)|\n| howfairis | [](https://fair-software.eu)|\n| Documentation | [](https://grainlearning.readthedocs.io/en/latest/?badge=latest)|\n| Code Quality | [](https://sonarcloud.io/summary/new_code?id=GrainLearning_grainLearning) [](https://sonarcloud.io/summary/new_code?id=GrainLearning_grainLearning) |\n| Paper | [](https://doi.org/10.21105/joss.06338) |\n\nBayesian uncertainty quantification for discrete and continuum numerical models of granular materials,\ndeveloped by various projects of the University of Twente (NL), the Netherlands eScience Center (NL), University of\nNewcastle (AU), and Hiroshima University (JP).\nBrowse to the [GrainLearning documentation](https://grainlearning.readthedocs.io/en/latest/) to get started.\n\n## Features\n\n- Infer and update model parameters using \"time\" series (sequence) data\n via [Sequential Monte Carlo filtering](https://en.wikipedia.org/wiki/Particle_Filter)\n- Uniform, quasi-random sampling using [low-discrepancy sequences](https://en.wikipedia.org/wiki/Halton_sequence)\n- Iterative sampling by training a\n nonparametric [Gaussian mixture model](https://scikit-learn.org/stable/modules/generated/sklearn.mixture.BayesianGaussianMixture.html)\n- [Surrogate modeling](https://grainlearning.readthedocs.io/en/latest/rnn.html) capability for \"time\" series data\n\n[//]: # (using [recurrent neural networks](https://en.wikipedia.org/wiki/Recurrent_neural_network))\n\n[//]: # (- Hybrid physics-based and data-driven model evaluation strategy)\n\n## Installation\n\n### Install using poetry\n\n1. Install poetry following [these instructions](https://python-poetry.org/docs/#installation).\n1. Clone the repository: `git clone https://github.com/GrainLearning/grainLearning.git`\n1. Go to the source code directory: `cd grainLearning`\n1. Activate the virtual environment: `poetry shell`\n1. Install GrainLearning and its dependencies: `poetry install`\n\n### Install using pip\n\n1. Clone the repository: `git clone https://github.com/GrainLearning/grainLearning.git`\n1. Go to the source code directory: `cd grainLearning`\n1. Activate the virtual environment: `conda create --name grainlearning python=3.12 && conda activate grainlearning`\n1. Install GrainLearning and its dependencies: `pip install .`\n\n__Developers__ please refer to [README.dev.md](README.dev.md).\n\nTo install GrainLearning including the RNN module capabilities check [grainlearning/rnn/README.md](grainlearning/rnn/README.md).\n\n### For Windows users\n\n- Installation using Windows Subsystem for Linux (WSL)\n - Enable WSL1 or WSL2 according to the\n instructions [here](https://learn.microsoft.com/en-us/windows/wsl/install-manual)\n - Install GrainLearning using [poetry](#install-using-poetry) or [pip](#install-using-pip)\n- Installation using anaconda (if no WSLs are available on your Windows system)\n - Open Anaconda Prompt and install GrainLearning using [pip](#install-using-pip). This should create a virtual\n environment, named GrainLearning.\n - Choose that environment from your anaconda navigator: click `Environments` and select `grainlearning` from the\n drop-down menu\n\n### One command installation\n\nStable versions of GrainLearning can be installed via `pip install grainlearning`\nHowever, you still need to clone the GrainLearning repository to run the tutorials.\n\n## Tutorials\n\n1. Linear regression with\n the [`run_sim`](tutorials/simple_regression/linear_regression/python_linear_regression_solve.py#L14)\n callback function of the [`BayesianCalibration`](grainlearning/bayesian_calibration.py)\n class,\n in [python_linear_regression_solve.py](tutorials/simple_regression/linear_regression/python_linear_regression_solve.py)\n\n2. Nonlinear, multivariate regression\n\n3. Interact with the numerical model of your choice\n via [`run_sim`](tutorials/simple_regression/linear_regression/linear_regression_solve.py#L11)\n ,\n in [linear_regression_solve.py](main/tutorials/simple_regression/linear_regression/linear_regression_solve.py)\n\n4. Load existing DEM simulation data and run GrainLearning for one iteration,\n in [oedo_load_and_resample.py](tutorials/oedo_compression/oedo_load_and_resample.py)\n\n5. Example of GrainLearning integration into YADE\n - [Two particle collision](tutorials/physics_based/two_particle_collision)\n - [Triaxial compression](tutorials/physics_based/triaxial_compression)\n\n6. Data-driven module tutorials:\n - [Train your LSTM model](tutorials/data_driven/LSTM/train_rnn.ipynb)\n - [Predict using an LSTM model](tutorials/data_driven/LSTM/predict.ipynb)\n - [Use an LSTM model in the calibration workflow](tutorials/data_driven/LSTM/rnn_calibration_GL.ipynb)\n\n## Citing GrainLearning\n\nPlease choose from the following:\n\n- [](https://doi.org/10.5281/zenodo.7123965) A DOI for\n citing the software.\n- 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](https://doi.org/10.21105/joss.06338)\n- H. Cheng, T. Shuku, K. Thoeni, P. Tempone, S. Luding, V. Magnanimo. **An iterative Bayesian filtering framework for\n fast and automated calibration of DEM models**. _Comput. Methods Appl. Mech. Eng.,_ 350 (2019), pp.\n 268-294, [10.1016/j.cma.2019.01.027](https://doi.org/10.1016/j.cma.2019.01.027)\n\n## Software using GrainLearning\n\n- [YADE](http://yade-dem.org/)\n- [MercuryDPM](https://www.mercurydpm.org/)\n\n## Community\n\nThe original development of `GrainLearning` is done by [Hongyang Cheng](https://hongyangcheng.weebly.com), in collaboration\nwith [Klaus Thoeni](https://www.newcastle.edu.au/profile/klaus-thoeni)\n, [Philipp Hartmann](https://www.newcastle.edu.au/profile/philipp-hartmann),\nand [Takayuki Shuku](https://sites.google.com/view/takayukishukuswebsite/home).\nThe software is currently maintained by [Hongyang Cheng](https://hongyangcheng.weebly.com) and [Stefan Luding](https://www2.msm.ctw.utwente.nl/sluding/) with the help\nof [Luisa Orozco](https://www.esciencecenter.nl/team/dr-luisa-orozco/)\nand [Retief Lubbe](https://tusail.eu/projects/esr-12.html).\nThe GrainLearning project receives contributions from students and collaborators.\n\n## Help and Support\n\nFor assistance with the GrainLearning software, please create an issue on the GitHub Issues page.\n\n## Credits\n\nThis package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and\nthe [NLeSC/python-template](https://github.com/NLeSC/python-template).\n\n",
"bugtrack_url": null,
"license": "GPLv2",
"summary": "A Bayesian uncertainty quantification toolbox for discrete and continuum numerical models of granular materials",
"version": "2.0.4",
"project_urls": {
"Homepage": "https://grainlearning.readthedocs.io/",
"Repository": "https://github.com/GrainLearning/grainLearning"
},
"split_keywords": [
"bayesian inference",
" uncertainty quantification",
" non-parametric gaussian mixture",
" dem",
" constitutive modeling",
" granular materials"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "af8a8d015480eaa916103d966970514128b2d9e9680943470daa29c41537e611",
"md5": "117efc6a897ea1f6131b930cc4689a79",
"sha256": "d882dc57bcf7e05f4bd1d631105874faa53af59f352bc09f7d8faa08f9e7d5f7"
},
"downloads": -1,
"filename": "grainlearning-2.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "117efc6a897ea1f6131b930cc4689a79",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.9",
"size": 5023026,
"upload_time": "2025-01-28T21:16:06",
"upload_time_iso_8601": "2025-01-28T21:16:06.241704Z",
"url": "https://files.pythonhosted.org/packages/af/8a/8d015480eaa916103d966970514128b2d9e9680943470daa29c41537e611/grainlearning-2.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bb0c65ee8733db1d80e35493070278d3b4b5cf79add870d3c6d834c4a103f731",
"md5": "1484ecd61d689f2637bea44736a0c314",
"sha256": "9f118bce87cb254a0d8a3c18e38daaf5736cc2c2f2c92b16ff3f9989c6c737bf"
},
"downloads": -1,
"filename": "grainlearning-2.0.4.tar.gz",
"has_sig": false,
"md5_digest": "1484ecd61d689f2637bea44736a0c314",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.9",
"size": 5020728,
"upload_time": "2025-01-28T21:16:09",
"upload_time_iso_8601": "2025-01-28T21:16:09.754010Z",
"url": "https://files.pythonhosted.org/packages/bb/0c/65ee8733db1d80e35493070278d3b4b5cf79add870d3c6d834c4a103f731/grainlearning-2.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-28 21:16:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GrainLearning",
"github_project": "grainLearning",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "grainlearning"
}
JSON
