DEMLab is a MATLAB program for performing numerical simulations of particle systems using the Discrete Element Method (DEM).
Its purpose is to offer a modular and extensible environment that allows immediate implementation and testing of several DEM models and formulations in small to medium-scale problems. It targets researchers, who can use it as a numerical laboratory, and students who want to learn the DEM.
- Main Features
- Implementation Aspects
- Instructions
- Examples
- Documentation
- How to Contribute
- How to Cite
- Authorship
- Acknowledgement
- License
This program deals with the classical soft-sphere approach of the DEM. The main characteristics of this method are:
- It is assumed that the contact between the particles occurs through a small overlap between them.
- Each contact is evaluated through several time steps in an explicit integration scheme.
- Contact models relate the amount of overlap between neighboring particles to the forces between them.
- Other physical interactions (e.g. thermal) may also be related to the overlap between particles.
- The shape of the particles is kept unchanged during and after contacts.
The program allows multiphysics simulations, counting on several interaction models in the following analysis types:
- Mechanical (solves the kinetics and kinematics of particles).
- Thermal (solves the temperature and heat flux of stationary particles).
- Thermo-mechanical (solves both mechanical and thermal analysis together).
Only two-dimensional (2D) models are handled by the program, with the following element types:
- Spherical particle (assuming that all spheres move on the same plane).
- Cylindrical particle (assuming an out-of-plane length).
- Rigid walls (straight and circular).
Almost all variables involved in the simulation process can be exported in one of the following result types:
- Text file.
- Graphs (plots and tables).
- Animations (scalar and vector results).
DEMLab is fully written in the MATLAB programming language, and adopts the Object Oriented Programming (OOP) paradigm to offer modularity and extensibility.
The source code can run in any operating system where MATLAB can be installed (the program is tested for version 2019b of MATLAB).
Because it is developed with a high-level interpreted programming language using serial processing, code efficiency is not a priority and therefore only small to medium-scale problems should be simulated.
For large-scale problems, it is recommended to check the DEM Application and the Thermal DEM Application of the Kratos Multiphysics framework.
There are three types of files that may be used as input for the program:
- Model Parts (.txt):
This text file is necessary for running a simulation and must always be accompanied by a Project Parameters file. Its name must be indicated in the Project Parameters file.
It contains all the elements of the model (particles and walls) with their initial coordinates and geometry, as well as their grouping into model parts.
A tutorial on this file can be found on its Wiki page. Moreover, a template of this file, with all the possible input options, is available.
- Project Parameters (.json):
This JSON file is necessary for running a simulation and must always be accompanied by a Model Parts file. The name of the Model Parts file must be indicated in the Input Group "ProblemData" of this file.
It contains all the parameters and options for the analysis and outputs, as well as the conditions applied to the model.
A tutorial explaining each input field of this file can be found on its Wiki page. Moreover, a template of this file, with all the possible input options, is available.
- Results Storage (.mat):
This binary file stores the results of a simulation. It is generated only if requested in the Input Group "Output" of the Project Parameters file.
It can be loaded to show the results of previously run simulations, or used to restart a simulation from a saved stage.
To run a simulation, launch MATLAB and execute the script file main.m located inside the folder src.
A dialog box will pop up to select an appropriate Project Parameters file. Multiple Project Parameters files can be selected to run simulations sequentially, as long as they are located in the same directory.
If the models and parameters are read correctly, the simulations are started and their progresses are printed in the MATLAB command window.
Sub-folders with the names of the simulations, plus the suffix "out", are created to receive the output files with the requested results of each simulation.
To load and show the results from previously run simulations, launch MATLAB and execute the script file main.m located inside the folder src.
A dialog box will pop up to select an appropriate Results Storage file. Multiple Results Storage files can be selected to load and show results sequentially, as long as they are located in the same directory.
To restart a simulation from the stored results, place its Results Storage file in the same directory of the Project Parameters file and run the simulation. The name of the Results Storage file must be the same of the simulation name indicated in the Project Parameters file.
Recursive tests are available to verify that the program is working correctly and that the current results are matching with the reference results. The reference results are stored in files with a .pos extension.
To run the tests, launch MATLAB and execute the script file run_tests.m located inside the folder tests.
A dialog box will pop up to select the Project Parameters files of the tests to be run, located inside the sub-folder test_models. The result of each test is then printed in the MATLAB command window.
To generate or update the reference results, execute the script file update_results.m located inside the folder tests and select the Project Parameters files of the tests to be updated, located inside the sub-folder test_models. It will run the selected tests and overwrite existing reference results.
Sample models are available inside the folder examples.
They are separated into different sub-folders according to their analysis type, and each example has its Project Parameters and Model Parts files, as well as some results in the output sub-folders.
Presentations on theoretical aspects of the DEM, showing the contact force models and the heat transfer models implemented in the program, are available inside the folder help.
The OOP classes of the program are documented in UML diagrams and their codes in HTML files, located inside the folder html. These files can be browsed on their Wiki page.
Tutorials explaining all the options of the program that can be added to the input files (Model Parts and Project Parameters) can also be found on the Wiki page.
Please check the contribution guidelines.
If you use this software, please cite it through this article:
R.L. Rangel, "DEMLab: A Discrete Element Method development environment". Software Impacts, Vol. 21, 100670, 2024.
- Rafael Rangel ([email protected])
International Center for Numerical Methods in Engineering (CIMNE) and Polytechnic University of Catalonia (UPC BarcelonaTech)
The program was initially developed under the context of the MATHEGRAM project, a Marie Sklodowska-Curie Innovative Training Network of the European Union’s Horizon 2020 Programme H2020 under REA grant agreement No. 813202.
DEMLab is licensed under the MIT license, which allows the program to be freely used by anyone for modification, private use, commercial use, and distribution, only requiring preservation of copyright and license notices. No liability and warranty are provided.