DEMGen: A Standardized Particle Packing Generator for the Discrete Element Method

This code aims to achieve a standardized particle packing generation framework for granular materials. This code not only allows users to generate a series of random packings that fulfill their requirements (such as particle size distribution, porosity, and stress) but also provides a series of tools for particle packing characterization of internally or externally generated packings.

Table of Contents

• Main Features
• DEMGen Dependencies
• Instructions
  • Input and Output Files
  • Running Simulations
    • Packing Generation
    • Packing Characterization
  • Checking Results
• Examples
• Documentation
• How to Contribute
• How to Cite
• Authorship
• License

Main Features

This program can be used for DEM particle packing generation. From this point of view, it can be treated as a pre-processing tool for any 3D DEM code. Meanwhile, it can be used for quantitative packing characterization, allowing users to have a deep insight into the material properties from the view of geometry components. The main characteristics of this framework are:

• It provides a standardized framework for particle packing generation.
• Both dynamic methods and constructive methods are available for particle packing generation (The constructive method is limited to regular arrangement up to now).
• Providing a method (radius expansion method with servo control) for achieving both packing density and initial stress.
• The periodic boundary is available for boundary conditions, allowing users to clone a small RVE packing to a large one.
• Providing a series of tools for packing characterization.

DEMGen Dependencies

DEMGen is fully written in the Python programming language and adopts the Object Oriented Programming (OOP) paradigm to offer modularity and extensibility. Due to the nature of Python, this program can be run on different platforms (Windows or Linux)

Please make sure you have installed Python3.X.X on your PC. Currently, Python3.10.X is recommended, as other versions haven't been tested.

Required Python Pakage: - numpy - matplotlib - pyevtk

Environment variable setting in a Command Prompt:

set PYTHONPATH=%PYTHONPATH%;'pathtoDEMGen'

For the dynamic generation methods, DEM calculations are required. The DEM Application of the Kratos Multiphysics framework is adopted here. A compiled Kratos for Windows environment (Python 3.10.11 and Visual Studio 2022) has been attached in the source code "./src/external/kratos". For using Kratos, the following environment variable need to be set in a Command Prompt:

set PYTHONPATH=%PYTHONPATH%;'pathtoDEMGen'/src/external/kratos \ set PATH=%PATH%;'pathtoDEMGen'/src/external/kratos/libs

Tip: This compiled Kratos may not work properly due to the different system environment setting. So it is recommanded to compile your own Kratos according to the Kratos INSTALL.md.

Instructions

Input and Output Files

• Input Parameters (.json):

This JSON file is used as input for the program. For generating particle packings, at least one input file is needed: ParametersDEMGen.json. For dynamic generation methods, both MaterialsDEM.json and ProjectParametersDEM.json are needed as the Kratos DEM simulation will be run.

• Output Results (.mdpa):

This MDPA file is used for storing the particle information of a packing. Usually, you can find the generated packing in the folder "./generatedcases/cases$number$/showpacking/" (for dynamic methods) or "./showpacking/" (for constructive methods) of the working path. To visualize the results, ".vtu" format is used for Paraview and ".res" format is used for GiD.

Running Simulations

To run a simulation, launch the DEMGenframeworkmain.py inside the folder ./src. For running the file correctly, please modify the "aim_path" (at the last of the file) to your own case path (absolute one).

Packing Generation

For running the particle packing generation process using different generation methods, different parameters need to be set in the ParametersDEMGen.json. Please study the example case of different methods for futher usage.

Packing Characterization

If the related parameters in ParametersDEMGen.json are 'activated', the partcile packing characterization process will be run automatically. Those parameters are:

"packingcharcterizationoption" : true/flase,\ "regularshapeoption" : true/flase,\ "packingcharcterizationsetting": \ {\ "RVElambdainitial" : 1,\ "RVElambdaincrement" : 1,\ "measuredensityoption" : true/flase,\ "measuremeancoordinationnumberoption" : true/flase,\ "measureanisotropyoption" : true/flase \ }

Checking Results

In the case folder or in the generated case folder, there will be a folder call "show packing", there you can find the post-processing file of the generated packing. Then it can be checked in Paraview or Gid.

Examples

Examples are available inside the folder examples.

Dynamic methods

• testgravitationaldeposition_method
• testisotropiccompression_method
• testradiusexpansion_method
• testradiusexpansionwithservocontrolmethod
• testimprovedradiusexpansionwithservocontrol_method. (Important tip: To run this method properly, you need to use the branch named "fix-stress-calculation" of Kratos DEM until the development in this branch is merged to the "master".)

Constructive methods

• testcubicarrangement_method
• testhpcarrangement_method

Example cases

Case 1: Some results from example testimprovedradiusexpansionwithservocontrol_method.

Three random generated particle packings according to the PSD of weak sandstone.

Here is an example PDF file for packing characterization.

Case 2: Some results from example testgravitationaldeposition_method.

Packing generated with rigid walls as boundary conditions.

                 

The final packing.

        

Packing generated with periodic boundaries.

                 

The final packing.

        

By comparing the results of the two conditions, we could find that using periodic boundaries can help us get a particle packing with more homogeneous force chains.

                 

Case 3: Some results from example testcubicarrangement_method (left) and testhpcarrangement_method (right).

                 

Documentation

Please read this README.md for information.

How to Contribute

Please check the contribution guidelines.

How to Cite

To cite this repository, you can use the metadata from this file.

Authorship

• Chengshun Shang ^1,2 (cshang@cimne.upc.edu)

¹ International Center for Numerical Methods in Engineering (CIMNE)

² Universitat Politècnica de Catalunya (UPC)

                 

License

DEMGen is licensed under the BSD license, which allows the program to be freely used by anyone for modification, private use, commercial use, and distribution, only requiring the preservation of copyright and license notices. No liability and warranty are provided.