# CLUMP
## Description
CLUMP is a collection of scripts to generate multi-sphere particles of overlapping or non-overlapping spheres, which approximate target
geometries. Multi-spheres (a.k.a. clumps) are popular in numerical simulations using the Discrete Element Method (DEM), but these geometric
object can find applications in a wider perspective, past numerical modelling. The motivation behind developing CLUMP stemmed from the need
to compare different clump-generation techniques, both in terms of particle morphology and mechanical performance using the DEM. To this
end, CLUMP offers two existing and well established clump-generation techniques and proposes a new one. The generated clumps can be
exported in various formats, compatible with some of the most prominent DEM codes. Last, the surface of each generated clump can be extracted
as a triangulated mesh and saved as an stl file, allowing for a full characterisation of particle morphology, using tools like SHAPE or 3D-printing of
physical particle replicas. CLUMP was initially developed in MATLAB and has now been fully translated in Python. Both implementations will
continue to be developed in parallel as the software evolves.
## Architectural Features
CLUMP performs the following functions:
- __GenerateClump__
- Favier et al (1999)
- Ferellec and McDowell (2010)
- Euclidean 3D (2021) and Extended Euclidean 3D (proposed in this code)
- __ExportClump__
- YADE
- MercuryDPM
- LAMMPS
- EDEM
- PFC3D
- __CharacteriseClump__
- Surface extraction
## Installation
Running the following code in the terminal (for Linux and macOS) or in the Command Prompt (for Windows) will automatically set up the module along with its corresponding dependencies.
```bash
pip install clump-python
```
## Quick Start
After the installation using ```pip install clump-python```, CLUMP can easily be imported as
```python
import CLUMP
```
This following examples demonstrate different approaches to generate clumps for the different target geometry. The variables below are documented within each function.
```python
from CLUMP.examples import Example_Euclidean_3D
```
```python
from CLUMP.examples import Example_Euclidean_3D_Extended
```
```python
from CLUMP.examples import Example_Ferellec_McDowell
```
```python
from CLUMP.examples import Example_Favier
```
The following example demonstrates the surface extraction method.
```python
from CLUMP.examples import Example_ExtractSurface
```
## Simple Examples
Here is an example of generating a clump from an STL file using __Euclidean Distance Transform__ method.
```python
from CLUMP import GenerateClump_Euclidean_3D
inputGeom = "path_of_STL.stl"
N = 21
rMin = 0
div = 102
overlap = 0.6
output = 'path_of_clump_output.txt'
outputVTK = 'path_of_clump_vtk.vtk'
visualise = True
GenerateClump_Euclidean_3D(inputGeom, N, rMin, div, overlap, output=output, outputVTK=outputVTK, visualise=visualise)
```
To run the __Extended Euclidean Transform__, one needs to specify the maximum sphere radius which will trigger the extended version. The example is as follows:
```python
from CLUMP import GenerateClump_Euclidean_3D
inputGeom = "path_of_STL.stl"
N = 21
rMin = 0
div = 102
overlap = 0.6
output = 'path_of_clump_output.txt'
outputVTK = 'path_of_clump_vtk.vtk'
visualise = True
rMax_ratio = 0.3 # Parameter to trigger the Extended Euclidean method
GenerateClump_Euclidean_3D(inputGeom, N, rMin, div, overlap, output=output, outputVTK=outputVTK, visualise=visualise, rMax_ratio=rMax_ratio)
```
Here is an example for the __Ferellec-McDowell__ clump generation method:
```python
from CLUMP import GenerateClump_Ferellec_McDowell
inputGeom = "path_of_STL.stl"
dmin = 0.1
rmin = 0.01
rstep = 0.01
pmax = 1.0
seed = 5
output = 'path_of_clump_output.txt'
outputVTK = 'path_of_clump_vtk.vtk'
visualise = True
mesh,clump=GenerateClump_Ferellec_McDowell(inputGeom=inputGeom, dmin=dmin, rmin=rmin, rstep=rstep, pmax=pmax, seed=seed, output=output, outputVTK=outputVTK, visualise=visualise)
```
To generate a clump using the __Favier__ method, you can use the following example:
```python
from CLUMP import GenerateClump_Favier
inputGeom = "path_of_STL.stl"
N = 10
chooseDistance = 'min'
output = 'path_of_clump_output.txt'
outputVTK = 'path_of_clump_vtk.vtk'
visualise = True
mesh,clump=GenerateClump_Favier(inputGeom=inputGeom, N=N, chooseDistance=chooseDistance, output=output, outputVTK=outputVTK, visualise=visualise)
```
Consider a clump defined as follows:
```python
import numpy as np
clump = np.array([[1, 0, 0, 1.1],
[2, 1, 0, 1.1],
[3, 0, 0, 1.2],
[1, 0, 1, 1.2]])
```
To extract the surface of the clump, you can use __ExtractSurface__ function as follows:
```python
from CLUMP import ExtractSurface
N_sphere = 200
N_circle = 100
visualise = True
faces, vertices = ExtractSurface(clump, N_sphere, N_circle, visualise)
```
## BYOS (Bring Your Own Scripts)!
If you enjoy using CLUMP, you are welcome to require the implementation of new clump-generation approaches and features or even better contribute and share your implementations. CLUMP was created to provide a comparison of different methods, by collecting them in one place and we share this tool hoping that members of the community will find it useful. So, feel free to expand the code, propose improvements and report issues.
Raw data
{
"_id": null,
"home_page": "https://github.com/vsangelidakis/CLUMP",
"name": "clump-python",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Clump, Clump Generation, Euclidean Distance Transform, Favier, Ferellec-McDowell, Surface Extraction",
"author": "Utku Canbolat, Vasileios Angelidakis",
"author_email": "utku.canbolat@fau.de",
"download_url": "https://files.pythonhosted.org/packages/5e/db/3216a9df9c911b3f0b82494f336d4ef77e42c734ca34be4a6eb321f2102f/clump-python-0.3.2.tar.gz",
"platform": null,
"description": "\n# CLUMP\n\n## Description\n\nCLUMP is a collection of scripts to generate multi-sphere particles of overlapping or non-overlapping spheres, which approximate target\ngeometries. Multi-spheres (a.k.a. clumps) are popular in numerical simulations using the Discrete Element Method (DEM), but these geometric\nobject can find applications in a wider perspective, past numerical modelling. The motivation behind developing CLUMP stemmed from the need\nto compare different clump-generation techniques, both in terms of particle morphology and mechanical performance using the DEM. To this\nend, CLUMP offers two existing and well established clump-generation techniques and proposes a new one. The generated clumps can be\nexported in various formats, compatible with some of the most prominent DEM codes. Last, the surface of each generated clump can be extracted\nas a triangulated mesh and saved as an stl file, allowing for a full characterisation of particle morphology, using tools like SHAPE or 3D-printing of\nphysical particle replicas. CLUMP was initially developed in MATLAB and has now been fully translated in Python. Both implementations will\ncontinue to be developed in parallel as the software evolves.\n\n\n## Architectural Features\nCLUMP performs the following functions:\n\n- __GenerateClump__\n - Favier et al (1999)\n - Ferellec and McDowell (2010)\n - Euclidean 3D (2021) and Extended Euclidean 3D (proposed in this code)\n\n- __ExportClump__\n - YADE\n - MercuryDPM\n - LAMMPS\n - EDEM\n - PFC3D\n\n- __CharacteriseClump__\n - Surface extraction\n\n\n\n## Installation\n\nRunning the following code in the terminal (for Linux and macOS) or in the Command Prompt (for Windows) will automatically set up the module along with its corresponding dependencies.\n\n```bash \npip install clump-python\n```\n\n\n## Quick Start\n\nAfter the installation using ```pip install clump-python```, CLUMP can easily be imported as\n\n```python\nimport CLUMP\n```\n\nThis following examples demonstrate different approaches to generate clumps for the different target geometry. The variables below are documented within each function. \n\n```python\nfrom CLUMP.examples import Example_Euclidean_3D\n```\n\n```python\nfrom CLUMP.examples import Example_Euclidean_3D_Extended\n```\n\n```python\nfrom CLUMP.examples import Example_Ferellec_McDowell\n```\n\n```python\nfrom CLUMP.examples import Example_Favier\n```\n\nThe following example demonstrates the surface extraction method.\n\n```python\nfrom CLUMP.examples import Example_ExtractSurface\n```\n\n## Simple Examples\n\nHere is an example of generating a clump from an STL file using __Euclidean Distance Transform__ method.\n\n```python\nfrom CLUMP import GenerateClump_Euclidean_3D \n \ninputGeom = \"path_of_STL.stl\" \nN = 21 \nrMin = 0 \ndiv = 102 \noverlap = 0.6 \noutput = 'path_of_clump_output.txt' \noutputVTK = 'path_of_clump_vtk.vtk' \nvisualise = True \n \nGenerateClump_Euclidean_3D(inputGeom, N, rMin, div, overlap, output=output, outputVTK=outputVTK, visualise=visualise)\n```\n\nTo run the __Extended Euclidean Transform__, one needs to specify the maximum sphere radius which will trigger the extended version. The example is as follows:\n\n```python\nfrom CLUMP import GenerateClump_Euclidean_3D \n \ninputGeom = \"path_of_STL.stl\" \nN = 21 \nrMin = 0 \ndiv = 102 \noverlap = 0.6 \noutput = 'path_of_clump_output.txt' \noutputVTK = 'path_of_clump_vtk.vtk' \nvisualise = True\nrMax_ratio = 0.3 # Parameter to trigger the Extended Euclidean method\n \nGenerateClump_Euclidean_3D(inputGeom, N, rMin, div, overlap, output=output, outputVTK=outputVTK, visualise=visualise, rMax_ratio=rMax_ratio)\n```\n\nHere is an example for the __Ferellec-McDowell__ clump generation method:\n\n```python\nfrom CLUMP import GenerateClump_Ferellec_McDowell\n\ninputGeom = \"path_of_STL.stl\" \ndmin = 0.1 \nrmin = 0.01 \nrstep = 0.01 \npmax = 1.0 \nseed = 5 \noutput = 'path_of_clump_output.txt' \noutputVTK = 'path_of_clump_vtk.vtk' \nvisualise = True \n \nmesh,clump=GenerateClump_Ferellec_McDowell(inputGeom=inputGeom, dmin=dmin, rmin=rmin, rstep=rstep, pmax=pmax, seed=seed, output=output, outputVTK=outputVTK, visualise=visualise)\n```\n\nTo generate a clump using the __Favier__ method, you can use the following example:\n\n```python\nfrom CLUMP import GenerateClump_Favier\n\ninputGeom = \"path_of_STL.stl\" \nN = 10 \nchooseDistance = 'min' \noutput = 'path_of_clump_output.txt' \noutputVTK = 'path_of_clump_vtk.vtk' \nvisualise = True \n \nmesh,clump=GenerateClump_Favier(inputGeom=inputGeom, N=N, chooseDistance=chooseDistance, output=output, outputVTK=outputVTK, visualise=visualise)\n```\n\nConsider a clump defined as follows:\n\n```python\nimport numpy as np\n\nclump = np.array([[1, 0, 0, 1.1], \n [2, 1, 0, 1.1], \n [3, 0, 0, 1.2], \n [1, 0, 1, 1.2]])\n```\n\nTo extract the surface of the clump, you can use __ExtractSurface__ function as follows:\n\n```python\nfrom CLUMP import ExtractSurface\n\nN_sphere = 200 \nN_circle = 100 \nvisualise = True \n \nfaces, vertices = ExtractSurface(clump, N_sphere, N_circle, visualise)\n```\n\n ## BYOS (Bring Your Own Scripts)!\n\nIf you enjoy using CLUMP, you are welcome to require the implementation of new clump-generation approaches and features or even better contribute and share your implementations. CLUMP was created to provide a comparison of different methods, by collecting them in one place and we share this tool hoping that members of the community will find it useful. So, feel free to expand the code, propose improvements and report issues.\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "This Python library provides tools for creating and examining clumps using techniques: the Euclidean Distance Transform, Favier, and Ferellec-McDowell. It allows for the efficient generation of clumps and the extraction of their surfaces.",
"version": "0.3.2",
"project_urls": {
"Homepage": "https://github.com/vsangelidakis/CLUMP"
},
"split_keywords": [
"clump",
" clump generation",
" euclidean distance transform",
" favier",
" ferellec-mcdowell",
" surface extraction"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5dbcef5bf504947ce101ebf7e799b6f59c02efb820b4e225b2c10573901215f8",
"md5": "4afcb5d42e1de79d52693595b3eeb4b2",
"sha256": "0481116a85ae420a85f354f9010ec1532a5461a3f38a2c6aa89283ae2fed300a"
},
"downloads": -1,
"filename": "clump_python-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4afcb5d42e1de79d52693595b3eeb4b2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1878973,
"upload_time": "2024-05-05T20:09:58",
"upload_time_iso_8601": "2024-05-05T20:09:58.911483Z",
"url": "https://files.pythonhosted.org/packages/5d/bc/ef5bf504947ce101ebf7e799b6f59c02efb820b4e225b2c10573901215f8/clump_python-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5edb3216a9df9c911b3f0b82494f336d4ef77e42c734ca34be4a6eb321f2102f",
"md5": "e5783dea21fe07e7d3e86267730ca6da",
"sha256": "8090e864ca23bd501e9278a313fbdb1897b522914724f6afbb8c41bb7b6e9fbd"
},
"downloads": -1,
"filename": "clump-python-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "e5783dea21fe07e7d3e86267730ca6da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 1859544,
"upload_time": "2024-05-05T20:10:02",
"upload_time_iso_8601": "2024-05-05T20:10:02.675144Z",
"url": "https://files.pythonhosted.org/packages/5e/db/3216a9df9c911b3f0b82494f336d4ef77e42c734ca34be4a6eb321f2102f/clump-python-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-05 20:10:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vsangelidakis",
"github_project": "CLUMP",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "clump-python"
}
JSON
