crushdem 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- crushdem-0.5.0/LICENSE +21 -0
- crushdem-0.5.0/PKG-INFO +214 -0
- crushdem-0.5.0/README.md +173 -0
- crushdem-0.5.0/crushdem/__init__.py +36 -0
- crushdem-0.5.0/crushdem/_version.py +2 -0
- crushdem-0.5.0/crushdem/backends/__init__.py +51 -0
- crushdem-0.5.0/crushdem/backends/errors.py +9 -0
- crushdem-0.5.0/crushdem/backends/numba_cpu.py +484 -0
- crushdem-0.5.0/crushdem/backends/warp_cuda.py +594 -0
- crushdem-0.5.0/crushdem/breakage/__init__.py +18 -0
- crushdem-0.5.0/crushdem/breakage/progeny.py +199 -0
- crushdem-0.5.0/crushdem/breakage/replacement.py +460 -0
- crushdem-0.5.0/crushdem/breakage/tavares.py +183 -0
- crushdem-0.5.0/crushdem/comparison.py +360 -0
- crushdem-0.5.0/crushdem/core/__init__.py +1 -0
- crushdem-0.5.0/crushdem/core/_jit.py +27 -0
- crushdem-0.5.0/crushdem/core/contact.py +101 -0
- crushdem-0.5.0/crushdem/core/materials.py +162 -0
- crushdem-0.5.0/crushdem/core/scenarios.py +56 -0
- crushdem-0.5.0/crushdem/core/state.py +103 -0
- crushdem-0.5.0/crushdem/flow.py +326 -0
- crushdem-0.5.0/crushdem/machines/__init__.py +8 -0
- crushdem-0.5.0/crushdem/machines/cone.py +93 -0
- crushdem-0.5.0/crushdem/machines/jaw.py +198 -0
- crushdem-0.5.0/crushdem/machines/machine.py +44 -0
- crushdem-0.5.0/crushdem/neighbours/__init__.py +4 -0
- crushdem-0.5.0/crushdem/neighbours/hash_grid.py +107 -0
- crushdem-0.5.0/crushdem/simulation.py +324 -0
- crushdem-0.5.0/crushdem/walls/__init__.py +8 -0
- crushdem-0.5.0/crushdem/walls/geometry.py +206 -0
- crushdem-0.5.0/crushdem/walls/motion.py +120 -0
- crushdem-0.5.0/crushdem.egg-info/PKG-INFO +214 -0
- crushdem-0.5.0/crushdem.egg-info/SOURCES.txt +52 -0
- crushdem-0.5.0/crushdem.egg-info/dependency_links.txt +1 -0
- crushdem-0.5.0/crushdem.egg-info/requires.txt +16 -0
- crushdem-0.5.0/crushdem.egg-info/top_level.txt +1 -0
- crushdem-0.5.0/pyproject.toml +52 -0
- crushdem-0.5.0/setup.cfg +4 -0
- crushdem-0.5.0/tests/test_breakage.py +604 -0
- crushdem-0.5.0/tests/test_comparison.py +268 -0
- crushdem-0.5.0/tests/test_contact.py +184 -0
- crushdem-0.5.0/tests/test_determinism.py +47 -0
- crushdem-0.5.0/tests/test_evaluate.py +155 -0
- crushdem-0.5.0/tests/test_flow.py +135 -0
- crushdem-0.5.0/tests/test_integrator.py +48 -0
- crushdem-0.5.0/tests/test_machines.py +141 -0
- crushdem-0.5.0/tests/test_neighbours.py +60 -0
- crushdem-0.5.0/tests/test_notebooks.py +107 -0
- crushdem-0.5.0/tests/test_packaging.py +51 -0
- crushdem-0.5.0/tests/test_parity.py +87 -0
- crushdem-0.5.0/tests/test_readme.py +38 -0
- crushdem-0.5.0/tests/test_result.py +71 -0
- crushdem-0.5.0/tests/test_validation_record.py +291 -0
- crushdem-0.5.0/tests/test_walls.py +298 -0
crushdem-0.5.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Felipe Santibáñez-Leal
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
crushdem-0.5.0/PKG-INFO
ADDED
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: crushdem
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: Soft-sphere discrete element method for crushers: Hertz-Mindlin contacts with tangential history, a numba CPU reference and a Warp CUDA path, pip-installable on Windows.
|
|
5
|
+
Author: Felipe Santibanez-Leal
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/fsantibanezleal/CAOS_CrushDEM
|
|
8
|
+
Project-URL: Repository, https://github.com/fsantibanezleal/CAOS_CrushDEM
|
|
9
|
+
Project-URL: Documentation, https://github.com/fsantibanezleal/CAOS_CrushDEM/tree/main/docs
|
|
10
|
+
Project-URL: Issues, https://github.com/fsantibanezleal/CAOS_CrushDEM/issues
|
|
11
|
+
Project-URL: Changelog, https://github.com/fsantibanezleal/CAOS_CrushDEM/blob/main/CHANGELOG.md
|
|
12
|
+
Keywords: DEM,discrete element method,crusher,comminution,Hertz-Mindlin,mineral processing,Warp,numba
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Natural Language :: English
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering
|
|
24
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
25
|
+
Classifier: Operating System :: OS Independent
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
License-File: LICENSE
|
|
29
|
+
Requires-Dist: numpy>=1.26
|
|
30
|
+
Provides-Extra: jit
|
|
31
|
+
Requires-Dist: numba>=0.60; extra == "jit"
|
|
32
|
+
Provides-Extra: gpu
|
|
33
|
+
Requires-Dist: warp-lang>=1.5; extra == "gpu"
|
|
34
|
+
Provides-Extra: dev
|
|
35
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
36
|
+
Requires-Dist: jsonschema>=4.20; extra == "dev"
|
|
37
|
+
Requires-Dist: build>=1.0; extra == "dev"
|
|
38
|
+
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
|
|
39
|
+
Requires-Dist: numba>=0.60; extra == "dev"
|
|
40
|
+
Dynamic: license-file
|
|
41
|
+
|
|
42
|
+
# crushdem
|
|
43
|
+
|
|
44
|
+
A soft-sphere discrete element method (DEM) with particle breakage for crushers: Hertz-Mindlin contacts with tangential
|
|
45
|
+
history, analytic walls with prescribed motion (a jaw's swing plate, a cone's gyrating mantle), and particle replacement
|
|
46
|
+
driven by the Tavares breakage model and the t10 progeny law. It installs with pip on Windows, Linux and macOS, runs on any
|
|
47
|
+
CPU (numba) and on NVIDIA GPUs (Warp), and needs no C++ toolchain, WSL or MPI.
|
|
48
|
+
|
|
49
|
+
## Status
|
|
50
|
+
|
|
51
|
+
Version 0.05.000, the first release on PyPI. The engine is implemented and tested: the soft-sphere core (particle state,
|
|
52
|
+
velocity-Verlet integration, the Hertz-Mindlin contact with tangential history, Coulomb sliding and Tsuji damping, rolling
|
|
53
|
+
resistance, the uniform hash grid), analytic walls with prescribed motion and their power, feed and discharge with a closing
|
|
54
|
+
mass balance, the machines built from them (the laboratory jaw of Barrios et al. 2020 and a parametric cone) and
|
|
55
|
+
particle-replacement breakage (the Tavares breakage model with damage, t10 and incomplete-beta progeny, a mass-conserving
|
|
56
|
+
replacement with bounded injected energy), on a numba CPU reference and a Warp CUDA path held equal by tests. The requirements
|
|
57
|
+
and the validation plan are in [`docs/design/SDD.md`](docs/design/SDD.md).
|
|
58
|
+
|
|
59
|
+
**Validation: the laboratory jaw is not reproduced.** Against the jaw crusher of Barrios et al. 2020
|
|
60
|
+
(https://doi.org/10.3390/min10080717) the throughput band set before the run is not met. The power band is met in the
|
|
61
|
+
steady-state window, but the energy per kilogram is a third of the measured one, so that verdict is not a sign that the energy
|
|
62
|
+
balance is right. The record states it as it is ([`docs/VALIDATION.md`](docs/VALIDATION.md),
|
|
63
|
+
[`validation/results/jaw_barrios2020.json`](validation/results/jaw_barrios2020.json)):
|
|
64
|
+
|
|
65
|
+
| Quantity, 63/52 mm feed, 6 Hz | Measured | crushdem (record of 0.04.000, model unchanged since) | Error | Band |
|
|
66
|
+
|---|---|---|---|---|
|
|
67
|
+
| Mean net power, steady-state window | 0.34 kW | 0.301 kW | -11.5 percent | 30 percent: met in the window |
|
|
68
|
+
| Mean net power, whole run | 0.34 kW (no window stated) | 0.228 kW | -32.8 percent | reported |
|
|
69
|
+
| Throughput | 798.7 kg/h | 2167 kg/h | +171 percent | 10 percent: not met |
|
|
70
|
+
| Specific energy (net power over throughput) | 1533 J/kg (derived) | 500 J/kg (window), 526 J/kg (whole run) | -67 and -66 percent | no band: reported |
|
|
71
|
+
| Product, median size d50 | 4.5 mm | 11.1 mm | about 2.5 times coarser | no band: reported |
|
|
72
|
+
|
|
73
|
+
The machine passes the batch about 2.7 times faster than the experiment and delivers about a third of the energy per kilogram;
|
|
74
|
+
the window power lands near the paper because the two errors offset. The ore is derived from the paper's single-particle tests
|
|
75
|
+
(all 30 particles of each Fig. 6b class, the paper's median); it was changed once, after the first review, from the paper's data
|
|
76
|
+
and text, never from the jaw result, and no ore property is tuned. The paper's own calibrated sphere (Fig. 6a) is about six
|
|
77
|
+
times stiffer than the Table 3 contact the case uses. The overlap limit was relaxed from 0.3 to 0.5 of the smaller radius on the
|
|
78
|
+
paper-ore runs, and 18 of the 29 window strokes exceed 0.3; one seed was run; the 3 and 9 Hz runs and a comparison ore stopped
|
|
79
|
+
with the engine's overlap error (a jammed bed or a too-large time step: the record does not show which), and the 3 and 9 Hz
|
|
80
|
+
points have no measurement. Seven candidate causes are listed in the record (the contact stiffness, the throw, the swing law and
|
|
81
|
+
the nip angle, flat smooth plates, the progeny law, the extrapolated size effect, spheres passing the gap by diameter); none has
|
|
82
|
+
been tested and none was tuned to reach a band.
|
|
83
|
+
Treat the engine as a research tool whose contact, wall and breakage mechanics are tested and whose agreement with a real
|
|
84
|
+
crusher is an open result. The cone case follows when its results are confirmed in an open text.
|
|
85
|
+
|
|
86
|
+
## Install
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
pip install crushdem # numpy only: the core, on plain Python (correct, slow)
|
|
90
|
+
pip install "crushdem[jit]" # + numba: the CPU reference path
|
|
91
|
+
pip install "crushdem[gpu]" # + warp-lang: the CUDA path (NVIDIA GPU)
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Python 3.10 to 3.13; Windows, Linux and macOS; no C++ toolchain, WSL or MPI. The extras are optional: the wheel imports and
|
|
95
|
+
runs with numpy alone.
|
|
96
|
+
|
|
97
|
+
## Minimal example
|
|
98
|
+
|
|
99
|
+
Two rock spheres collide head-on with a coefficient of restitution of 0.5, and the engine returns the speed they leave with.
|
|
100
|
+
It runs in about two seconds with numpy only, no extra needed.
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
from crushdem import ContactTable, Material, PairParams, ParticleState, Simulation, stable_time_step
|
|
104
|
+
|
|
105
|
+
rock = Material("rock", youngs_modulus=1.0e8, poisson=0.25, density=2700.0)
|
|
106
|
+
table = ContactTable.build([rock], default=PairParams(restitution=0.5, friction=0.0))
|
|
107
|
+
state = ParticleState.from_arrays([[0.0, 0.0, 0.0], [0.010001, 0.0, 0.0]], [0.005, 0.005], table,
|
|
108
|
+
vel=[[0.5, 0.0, 0.0], [-0.5, 0.0, 0.0]])
|
|
109
|
+
sim = Simulation(state, table, dt=stable_time_step(state, table, 0.05), gravity=(0.0, 0.0, 0.0))
|
|
110
|
+
sim.run(2000)
|
|
111
|
+
after = sim.state()
|
|
112
|
+
print(f"rebound ratio {(after.vel[1, 0] - after.vel[0, 0]) / 1.0:.4f} for a restitution of 0.5")
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
It prints `rebound ratio 0.4999 for a restitution of 0.5`. The notebooks in [`notebooks/`](notebooks/README.md) take this
|
|
116
|
+
contact apart and build up to the jaw.
|
|
117
|
+
|
|
118
|
+
### A bed that settles
|
|
119
|
+
|
|
120
|
+
A column of 2000 spheres falls onto a floor of frozen spheres and settles (with the `jit` extra: on plain Python this takes
|
|
121
|
+
hours); the same call runs on the GPU with `backend="warp"` (check `crushdem.available_backends()`).
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
import crushdem
|
|
125
|
+
from crushdem import Simulation, stable_time_step
|
|
126
|
+
from crushdem.core.scenarios import settling_column
|
|
127
|
+
|
|
128
|
+
state, table = settling_column(2000, seed=1, initial_speed=1.0) # spheres, and their material/contact table
|
|
129
|
+
dt = stable_time_step(state, table, fraction=0.1) # 0.1 of the Rayleigh time of the smallest sphere
|
|
130
|
+
sim = Simulation(state, table, dt=dt, backend="numba", seed=1)
|
|
131
|
+
sim.run(1000)
|
|
132
|
+
result = sim.result()
|
|
133
|
+
print(result["state"]["n_contacts"], "contacts,", f"{result['performance']['particle_steps_per_second']:.2e}", "particle-steps/s")
|
|
134
|
+
Simulation.write_result(result, "run.json") # validates against schemas/run.schema.json
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### A jaw crusher
|
|
138
|
+
|
|
139
|
+
The laboratory jaw of Barrios et al. 2020, fed a batch of one narrow size class (without breakage coarse rock is trapped by
|
|
140
|
+
the gap, fine rock passes). Every machine dimension and where it comes from is in `machine.provenance`
|
|
141
|
+
([`docs/machines.md`](docs/machines.md)).
|
|
142
|
+
|
|
143
|
+
```python
|
|
144
|
+
import numpy as np
|
|
145
|
+
from crushdem import ParticleState, Simulation, stable_time_step
|
|
146
|
+
from crushdem.machines import BARRIOS_FEED_CLASSES, barrios_contact_table, jaw_barrios2020
|
|
147
|
+
|
|
148
|
+
machine, table = jaw_barrios2020(), barrios_contact_table()
|
|
149
|
+
feed = machine.feed([BARRIOS_FEED_CLASSES["16/13.2"]], batch_mass=0.05, seed=1)
|
|
150
|
+
probe = ParticleState.from_arrays([[0, 0, 0]], [feed.min_radius], table)
|
|
151
|
+
empty = ParticleState.from_arrays(np.zeros((0, 3)), np.zeros(0), table)
|
|
152
|
+
jaw = Simulation(empty, table, dt=stable_time_step(probe, table, 0.1), feed=feed, capacity=30, seed=1,
|
|
153
|
+
**machine.simulation_kwargs())
|
|
154
|
+
jaw.run_cycles(2, machine.period_s)
|
|
155
|
+
swing = next(w for w in jaw.wall_report() if w["name"] == "swing_plate")
|
|
156
|
+
print(f"swing plate {swing['mean_power_w']:.1f} W,", jaw.flow()["n_out"], "spheres out")
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### The same jaw with breakage
|
|
160
|
+
|
|
161
|
+
Give the run an ore and its spheres break by the Tavares model and are replaced by progeny drawn from the pool of
|
|
162
|
+
`capacity` slots, which is the particle cap. The ore parameters of the jaw case, each with its source, are
|
|
163
|
+
`jaw_ore_barrios2020()`; the model, its bounds and what the result reports are in [`docs/breakage.md`](docs/breakage.md).
|
|
164
|
+
|
|
165
|
+
```python
|
|
166
|
+
from crushdem.machines import jaw_ore_barrios2020
|
|
167
|
+
|
|
168
|
+
ore = jaw_ore_barrios2020()
|
|
169
|
+
feed = machine.feed([BARRIOS_FEED_CLASSES["31.5/26.5"]], batch_mass=0.15, seed=1)
|
|
170
|
+
probe = ParticleState.from_arrays([[0, 0, 0]], [0.5 * ore.min_diameter], table) # the smallest sphere sets the time step
|
|
171
|
+
crusher = Simulation(empty, table, dt=stable_time_step(probe, table, 0.1), feed=feed, capacity=400, ore=ore, seed=1,
|
|
172
|
+
**machine.simulation_kwargs())
|
|
173
|
+
crusher.run_cycles(1, machine.period_s)
|
|
174
|
+
b = crusher.breakage_report()
|
|
175
|
+
print(b["n_events"], "breakages,", b["n_progeny"], "progeny,", f"{crusher.flow()['fines_kg'] * 1000:.1f} g of fines")
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Your own spheres: `ContactTable.build([Material(...)], default=PairParams(restitution, friction))` and
|
|
179
|
+
`ParticleState.from_arrays(positions, radii, table, vel=...)`. The contact law and its sources are in
|
|
180
|
+
[`docs/contact.md`](docs/contact.md); measured speeds in [`docs/performance.md`](docs/performance.md); the benchmark is
|
|
181
|
+
`python bench/settle.py`; the jaw batch is `python bench/jaw_batch.py`.
|
|
182
|
+
|
|
183
|
+
## Areas
|
|
184
|
+
|
|
185
|
+
| Area | Where | State |
|
|
186
|
+
|---|---|---|
|
|
187
|
+
| Core (state, materials, contact law, scenarios) | `crushdem/core/` | active, tested |
|
|
188
|
+
| Neighbour search (hash grid) | `crushdem/neighbours/` | active, tested |
|
|
189
|
+
| Walls, their motion laws and power | `crushdem/walls/` | active, tested |
|
|
190
|
+
| Feed, discharge, mass balance | `crushdem/flow.py` | active, tested |
|
|
191
|
+
| Machines (Barrios jaw, parametric cone) | `crushdem/machines/` | active; the jaw is not reproduced, see Status |
|
|
192
|
+
| Breakage (Tavares model, t10 progeny, replacement) | `crushdem/breakage/` | active, tested |
|
|
193
|
+
| Backends (numba reference, Warp CUDA) | `crushdem/backends/` | active; the CPU path carries the release |
|
|
194
|
+
| Run loop and result | `crushdem/simulation.py`, `schemas/run.schema.json` | active |
|
|
195
|
+
| Comparison protocol (band, steady-state window, window statistics and the resolved-verdict rule, product passing sizes) | `crushdem/comparison.py` (`crushdem.comparison`, used by the validation case and the comparison notebook; functions and units in [`docs/design/SDD.md`](docs/design/SDD.md), Validation) | active, tested |
|
|
196
|
+
| Notebooks (five, English and Spanish, level 2; the comparison notebook imports `crushdem.comparison`) | [`notebooks/`](notebooks/README.md) | active |
|
|
197
|
+
| Validation | [`validation/`](validation/), [`docs/VALIDATION.md`](docs/VALIDATION.md) | the jaw case, a negative result |
|
|
198
|
+
| Documentation | [`docs/`](docs/) (contact, machines, breakage, performance, design) | active |
|
|
199
|
+
| Tests and benchmarks | `tests/`, `bench/`, `scripts/run_notebooks.py` | `python -m pytest -q` |
|
|
200
|
+
| Deploy | `.github/workflows/publish.yml` | PyPI Trusted Publishing from a GitHub release |
|
|
201
|
+
|
|
202
|
+
Consumed by [CAOS_ChancaDEM](https://github.com/fsantibanezleal/CAOS_ChancaDEM), which bakes its runs offline.
|
|
203
|
+
|
|
204
|
+
## How to cite
|
|
205
|
+
|
|
206
|
+
Cite the software by its release and the methods by their sources. Software: Santibanez-Leal, F., crushdem, version 0.5.0,
|
|
207
|
+
https://github.com/fsantibanezleal/CAOS_CrushDEM (see [`CITATION.cff`](CITATION.cff)). Methods: the breakage model is
|
|
208
|
+
Tavares, L. M. (2022), KONA Powder and Particle Journal 39, 62-83, https://doi.org/10.14356/kona.2022012; the laboratory jaw
|
|
209
|
+
and its measurements are Barrios et al. (2020), Minerals 10(8), 717, https://doi.org/10.3390/min10080717; the contact damping
|
|
210
|
+
is Tsuji, Tanaka and Ishida (1992), Powder Technology 71, 239-250, https://doi.org/10.1016/0032-5910(92)88030-L.
|
|
211
|
+
|
|
212
|
+
## Licence
|
|
213
|
+
|
|
214
|
+
MIT, see [LICENSE](LICENSE).
|
crushdem-0.5.0/README.md
ADDED
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# crushdem
|
|
2
|
+
|
|
3
|
+
A soft-sphere discrete element method (DEM) with particle breakage for crushers: Hertz-Mindlin contacts with tangential
|
|
4
|
+
history, analytic walls with prescribed motion (a jaw's swing plate, a cone's gyrating mantle), and particle replacement
|
|
5
|
+
driven by the Tavares breakage model and the t10 progeny law. It installs with pip on Windows, Linux and macOS, runs on any
|
|
6
|
+
CPU (numba) and on NVIDIA GPUs (Warp), and needs no C++ toolchain, WSL or MPI.
|
|
7
|
+
|
|
8
|
+
## Status
|
|
9
|
+
|
|
10
|
+
Version 0.05.000, the first release on PyPI. The engine is implemented and tested: the soft-sphere core (particle state,
|
|
11
|
+
velocity-Verlet integration, the Hertz-Mindlin contact with tangential history, Coulomb sliding and Tsuji damping, rolling
|
|
12
|
+
resistance, the uniform hash grid), analytic walls with prescribed motion and their power, feed and discharge with a closing
|
|
13
|
+
mass balance, the machines built from them (the laboratory jaw of Barrios et al. 2020 and a parametric cone) and
|
|
14
|
+
particle-replacement breakage (the Tavares breakage model with damage, t10 and incomplete-beta progeny, a mass-conserving
|
|
15
|
+
replacement with bounded injected energy), on a numba CPU reference and a Warp CUDA path held equal by tests. The requirements
|
|
16
|
+
and the validation plan are in [`docs/design/SDD.md`](docs/design/SDD.md).
|
|
17
|
+
|
|
18
|
+
**Validation: the laboratory jaw is not reproduced.** Against the jaw crusher of Barrios et al. 2020
|
|
19
|
+
(https://doi.org/10.3390/min10080717) the throughput band set before the run is not met. The power band is met in the
|
|
20
|
+
steady-state window, but the energy per kilogram is a third of the measured one, so that verdict is not a sign that the energy
|
|
21
|
+
balance is right. The record states it as it is ([`docs/VALIDATION.md`](docs/VALIDATION.md),
|
|
22
|
+
[`validation/results/jaw_barrios2020.json`](validation/results/jaw_barrios2020.json)):
|
|
23
|
+
|
|
24
|
+
| Quantity, 63/52 mm feed, 6 Hz | Measured | crushdem (record of 0.04.000, model unchanged since) | Error | Band |
|
|
25
|
+
|---|---|---|---|---|
|
|
26
|
+
| Mean net power, steady-state window | 0.34 kW | 0.301 kW | -11.5 percent | 30 percent: met in the window |
|
|
27
|
+
| Mean net power, whole run | 0.34 kW (no window stated) | 0.228 kW | -32.8 percent | reported |
|
|
28
|
+
| Throughput | 798.7 kg/h | 2167 kg/h | +171 percent | 10 percent: not met |
|
|
29
|
+
| Specific energy (net power over throughput) | 1533 J/kg (derived) | 500 J/kg (window), 526 J/kg (whole run) | -67 and -66 percent | no band: reported |
|
|
30
|
+
| Product, median size d50 | 4.5 mm | 11.1 mm | about 2.5 times coarser | no band: reported |
|
|
31
|
+
|
|
32
|
+
The machine passes the batch about 2.7 times faster than the experiment and delivers about a third of the energy per kilogram;
|
|
33
|
+
the window power lands near the paper because the two errors offset. The ore is derived from the paper's single-particle tests
|
|
34
|
+
(all 30 particles of each Fig. 6b class, the paper's median); it was changed once, after the first review, from the paper's data
|
|
35
|
+
and text, never from the jaw result, and no ore property is tuned. The paper's own calibrated sphere (Fig. 6a) is about six
|
|
36
|
+
times stiffer than the Table 3 contact the case uses. The overlap limit was relaxed from 0.3 to 0.5 of the smaller radius on the
|
|
37
|
+
paper-ore runs, and 18 of the 29 window strokes exceed 0.3; one seed was run; the 3 and 9 Hz runs and a comparison ore stopped
|
|
38
|
+
with the engine's overlap error (a jammed bed or a too-large time step: the record does not show which), and the 3 and 9 Hz
|
|
39
|
+
points have no measurement. Seven candidate causes are listed in the record (the contact stiffness, the throw, the swing law and
|
|
40
|
+
the nip angle, flat smooth plates, the progeny law, the extrapolated size effect, spheres passing the gap by diameter); none has
|
|
41
|
+
been tested and none was tuned to reach a band.
|
|
42
|
+
Treat the engine as a research tool whose contact, wall and breakage mechanics are tested and whose agreement with a real
|
|
43
|
+
crusher is an open result. The cone case follows when its results are confirmed in an open text.
|
|
44
|
+
|
|
45
|
+
## Install
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
pip install crushdem # numpy only: the core, on plain Python (correct, slow)
|
|
49
|
+
pip install "crushdem[jit]" # + numba: the CPU reference path
|
|
50
|
+
pip install "crushdem[gpu]" # + warp-lang: the CUDA path (NVIDIA GPU)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Python 3.10 to 3.13; Windows, Linux and macOS; no C++ toolchain, WSL or MPI. The extras are optional: the wheel imports and
|
|
54
|
+
runs with numpy alone.
|
|
55
|
+
|
|
56
|
+
## Minimal example
|
|
57
|
+
|
|
58
|
+
Two rock spheres collide head-on with a coefficient of restitution of 0.5, and the engine returns the speed they leave with.
|
|
59
|
+
It runs in about two seconds with numpy only, no extra needed.
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
from crushdem import ContactTable, Material, PairParams, ParticleState, Simulation, stable_time_step
|
|
63
|
+
|
|
64
|
+
rock = Material("rock", youngs_modulus=1.0e8, poisson=0.25, density=2700.0)
|
|
65
|
+
table = ContactTable.build([rock], default=PairParams(restitution=0.5, friction=0.0))
|
|
66
|
+
state = ParticleState.from_arrays([[0.0, 0.0, 0.0], [0.010001, 0.0, 0.0]], [0.005, 0.005], table,
|
|
67
|
+
vel=[[0.5, 0.0, 0.0], [-0.5, 0.0, 0.0]])
|
|
68
|
+
sim = Simulation(state, table, dt=stable_time_step(state, table, 0.05), gravity=(0.0, 0.0, 0.0))
|
|
69
|
+
sim.run(2000)
|
|
70
|
+
after = sim.state()
|
|
71
|
+
print(f"rebound ratio {(after.vel[1, 0] - after.vel[0, 0]) / 1.0:.4f} for a restitution of 0.5")
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
It prints `rebound ratio 0.4999 for a restitution of 0.5`. The notebooks in [`notebooks/`](notebooks/README.md) take this
|
|
75
|
+
contact apart and build up to the jaw.
|
|
76
|
+
|
|
77
|
+
### A bed that settles
|
|
78
|
+
|
|
79
|
+
A column of 2000 spheres falls onto a floor of frozen spheres and settles (with the `jit` extra: on plain Python this takes
|
|
80
|
+
hours); the same call runs on the GPU with `backend="warp"` (check `crushdem.available_backends()`).
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
import crushdem
|
|
84
|
+
from crushdem import Simulation, stable_time_step
|
|
85
|
+
from crushdem.core.scenarios import settling_column
|
|
86
|
+
|
|
87
|
+
state, table = settling_column(2000, seed=1, initial_speed=1.0) # spheres, and their material/contact table
|
|
88
|
+
dt = stable_time_step(state, table, fraction=0.1) # 0.1 of the Rayleigh time of the smallest sphere
|
|
89
|
+
sim = Simulation(state, table, dt=dt, backend="numba", seed=1)
|
|
90
|
+
sim.run(1000)
|
|
91
|
+
result = sim.result()
|
|
92
|
+
print(result["state"]["n_contacts"], "contacts,", f"{result['performance']['particle_steps_per_second']:.2e}", "particle-steps/s")
|
|
93
|
+
Simulation.write_result(result, "run.json") # validates against schemas/run.schema.json
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### A jaw crusher
|
|
97
|
+
|
|
98
|
+
The laboratory jaw of Barrios et al. 2020, fed a batch of one narrow size class (without breakage coarse rock is trapped by
|
|
99
|
+
the gap, fine rock passes). Every machine dimension and where it comes from is in `machine.provenance`
|
|
100
|
+
([`docs/machines.md`](docs/machines.md)).
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
import numpy as np
|
|
104
|
+
from crushdem import ParticleState, Simulation, stable_time_step
|
|
105
|
+
from crushdem.machines import BARRIOS_FEED_CLASSES, barrios_contact_table, jaw_barrios2020
|
|
106
|
+
|
|
107
|
+
machine, table = jaw_barrios2020(), barrios_contact_table()
|
|
108
|
+
feed = machine.feed([BARRIOS_FEED_CLASSES["16/13.2"]], batch_mass=0.05, seed=1)
|
|
109
|
+
probe = ParticleState.from_arrays([[0, 0, 0]], [feed.min_radius], table)
|
|
110
|
+
empty = ParticleState.from_arrays(np.zeros((0, 3)), np.zeros(0), table)
|
|
111
|
+
jaw = Simulation(empty, table, dt=stable_time_step(probe, table, 0.1), feed=feed, capacity=30, seed=1,
|
|
112
|
+
**machine.simulation_kwargs())
|
|
113
|
+
jaw.run_cycles(2, machine.period_s)
|
|
114
|
+
swing = next(w for w in jaw.wall_report() if w["name"] == "swing_plate")
|
|
115
|
+
print(f"swing plate {swing['mean_power_w']:.1f} W,", jaw.flow()["n_out"], "spheres out")
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### The same jaw with breakage
|
|
119
|
+
|
|
120
|
+
Give the run an ore and its spheres break by the Tavares model and are replaced by progeny drawn from the pool of
|
|
121
|
+
`capacity` slots, which is the particle cap. The ore parameters of the jaw case, each with its source, are
|
|
122
|
+
`jaw_ore_barrios2020()`; the model, its bounds and what the result reports are in [`docs/breakage.md`](docs/breakage.md).
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
from crushdem.machines import jaw_ore_barrios2020
|
|
126
|
+
|
|
127
|
+
ore = jaw_ore_barrios2020()
|
|
128
|
+
feed = machine.feed([BARRIOS_FEED_CLASSES["31.5/26.5"]], batch_mass=0.15, seed=1)
|
|
129
|
+
probe = ParticleState.from_arrays([[0, 0, 0]], [0.5 * ore.min_diameter], table) # the smallest sphere sets the time step
|
|
130
|
+
crusher = Simulation(empty, table, dt=stable_time_step(probe, table, 0.1), feed=feed, capacity=400, ore=ore, seed=1,
|
|
131
|
+
**machine.simulation_kwargs())
|
|
132
|
+
crusher.run_cycles(1, machine.period_s)
|
|
133
|
+
b = crusher.breakage_report()
|
|
134
|
+
print(b["n_events"], "breakages,", b["n_progeny"], "progeny,", f"{crusher.flow()['fines_kg'] * 1000:.1f} g of fines")
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Your own spheres: `ContactTable.build([Material(...)], default=PairParams(restitution, friction))` and
|
|
138
|
+
`ParticleState.from_arrays(positions, radii, table, vel=...)`. The contact law and its sources are in
|
|
139
|
+
[`docs/contact.md`](docs/contact.md); measured speeds in [`docs/performance.md`](docs/performance.md); the benchmark is
|
|
140
|
+
`python bench/settle.py`; the jaw batch is `python bench/jaw_batch.py`.
|
|
141
|
+
|
|
142
|
+
## Areas
|
|
143
|
+
|
|
144
|
+
| Area | Where | State |
|
|
145
|
+
|---|---|---|
|
|
146
|
+
| Core (state, materials, contact law, scenarios) | `crushdem/core/` | active, tested |
|
|
147
|
+
| Neighbour search (hash grid) | `crushdem/neighbours/` | active, tested |
|
|
148
|
+
| Walls, their motion laws and power | `crushdem/walls/` | active, tested |
|
|
149
|
+
| Feed, discharge, mass balance | `crushdem/flow.py` | active, tested |
|
|
150
|
+
| Machines (Barrios jaw, parametric cone) | `crushdem/machines/` | active; the jaw is not reproduced, see Status |
|
|
151
|
+
| Breakage (Tavares model, t10 progeny, replacement) | `crushdem/breakage/` | active, tested |
|
|
152
|
+
| Backends (numba reference, Warp CUDA) | `crushdem/backends/` | active; the CPU path carries the release |
|
|
153
|
+
| Run loop and result | `crushdem/simulation.py`, `schemas/run.schema.json` | active |
|
|
154
|
+
| Comparison protocol (band, steady-state window, window statistics and the resolved-verdict rule, product passing sizes) | `crushdem/comparison.py` (`crushdem.comparison`, used by the validation case and the comparison notebook; functions and units in [`docs/design/SDD.md`](docs/design/SDD.md), Validation) | active, tested |
|
|
155
|
+
| Notebooks (five, English and Spanish, level 2; the comparison notebook imports `crushdem.comparison`) | [`notebooks/`](notebooks/README.md) | active |
|
|
156
|
+
| Validation | [`validation/`](validation/), [`docs/VALIDATION.md`](docs/VALIDATION.md) | the jaw case, a negative result |
|
|
157
|
+
| Documentation | [`docs/`](docs/) (contact, machines, breakage, performance, design) | active |
|
|
158
|
+
| Tests and benchmarks | `tests/`, `bench/`, `scripts/run_notebooks.py` | `python -m pytest -q` |
|
|
159
|
+
| Deploy | `.github/workflows/publish.yml` | PyPI Trusted Publishing from a GitHub release |
|
|
160
|
+
|
|
161
|
+
Consumed by [CAOS_ChancaDEM](https://github.com/fsantibanezleal/CAOS_ChancaDEM), which bakes its runs offline.
|
|
162
|
+
|
|
163
|
+
## How to cite
|
|
164
|
+
|
|
165
|
+
Cite the software by its release and the methods by their sources. Software: Santibanez-Leal, F., crushdem, version 0.5.0,
|
|
166
|
+
https://github.com/fsantibanezleal/CAOS_CrushDEM (see [`CITATION.cff`](CITATION.cff)). Methods: the breakage model is
|
|
167
|
+
Tavares, L. M. (2022), KONA Powder and Particle Journal 39, 62-83, https://doi.org/10.14356/kona.2022012; the laboratory jaw
|
|
168
|
+
and its measurements are Barrios et al. (2020), Minerals 10(8), 717, https://doi.org/10.3390/min10080717; the contact damping
|
|
169
|
+
is Tsuji, Tanaka and Ishida (1992), Powder Technology 71, 239-250, https://doi.org/10.1016/0032-5910(92)88030-L.
|
|
170
|
+
|
|
171
|
+
## Licence
|
|
172
|
+
|
|
173
|
+
MIT, see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
"""crushdem: a soft-sphere discrete element method for crushers (numba CPU reference, Warp CUDA path)."""
|
|
2
|
+
from . import comparison
|
|
3
|
+
from ._version import __version__
|
|
4
|
+
from .backends import OverlapError, available_backends, backend_unavailable_reason
|
|
5
|
+
from .backends.errors import ContactOverflowError
|
|
6
|
+
from .core.materials import ContactTable, Material, PairParams, tsuji_alpha
|
|
7
|
+
from .core.state import ParticleState, rayleigh_time_step, stable_time_step
|
|
8
|
+
from .flow import DischargePlane, Feed, SizeClass
|
|
9
|
+
from .simulation import Simulation
|
|
10
|
+
from .walls import FrustumWall, Gyration, PlaneWall, Rocking, Static, Translation
|
|
11
|
+
|
|
12
|
+
__all__ = [
|
|
13
|
+
"ContactOverflowError",
|
|
14
|
+
"ContactTable",
|
|
15
|
+
"DischargePlane",
|
|
16
|
+
"Feed",
|
|
17
|
+
"FrustumWall",
|
|
18
|
+
"Gyration",
|
|
19
|
+
"Material",
|
|
20
|
+
"OverlapError",
|
|
21
|
+
"PairParams",
|
|
22
|
+
"ParticleState",
|
|
23
|
+
"PlaneWall",
|
|
24
|
+
"Rocking",
|
|
25
|
+
"Simulation",
|
|
26
|
+
"SizeClass",
|
|
27
|
+
"Static",
|
|
28
|
+
"Translation",
|
|
29
|
+
"__version__",
|
|
30
|
+
"comparison",
|
|
31
|
+
"available_backends",
|
|
32
|
+
"backend_unavailable_reason",
|
|
33
|
+
"rayleigh_time_step",
|
|
34
|
+
"stable_time_step",
|
|
35
|
+
"tsuji_alpha",
|
|
36
|
+
]
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"""Backends: one kernel set per device, the same call surface, chosen by name at run time (numba is the reference)."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from .errors import ContactOverflowError, OverlapError
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
def backend_unavailable_reason(name: str):
|
|
8
|
+
"""``None`` when backend ``name`` can run on this machine, else the reason it cannot."""
|
|
9
|
+
if name == "numba":
|
|
10
|
+
return None # always runnable: without numba the same kernels run as plain Python (slow; install crushdem[jit])
|
|
11
|
+
if name == "warp":
|
|
12
|
+
try:
|
|
13
|
+
import warp as wp
|
|
14
|
+
|
|
15
|
+
wp.config.quiet = True
|
|
16
|
+
wp.init()
|
|
17
|
+
if wp.get_cuda_device_count() == 0:
|
|
18
|
+
return "no CUDA device is present"
|
|
19
|
+
return None
|
|
20
|
+
except Exception as exc: # noqa: BLE001 - any failure to load or initialise Warp means unavailable
|
|
21
|
+
return f"warp-lang is unusable here ({exc}); install crushdem[gpu] on a machine with an NVIDIA GPU"
|
|
22
|
+
raise ValueError(f"unknown backend {name!r}; choose 'numba' or 'warp'")
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def available_backends():
|
|
26
|
+
return [n for n in ("numba", "warp") if backend_unavailable_reason(n) is None]
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def get_backend(name: str):
|
|
30
|
+
"""The backend class of ``name``; raises ``RuntimeError`` with the reason when it cannot run here."""
|
|
31
|
+
if name not in ("numba", "warp"):
|
|
32
|
+
raise ValueError(f"unknown backend {name!r}; choose 'numba' or 'warp'")
|
|
33
|
+
if name == "warp":
|
|
34
|
+
reason = backend_unavailable_reason("warp")
|
|
35
|
+
if reason is not None:
|
|
36
|
+
raise RuntimeError(f"the warp backend is unavailable: {reason}")
|
|
37
|
+
from .warp_cuda import WarpBackend
|
|
38
|
+
|
|
39
|
+
return WarpBackend
|
|
40
|
+
from .numba_cpu import NumbaBackend
|
|
41
|
+
|
|
42
|
+
return NumbaBackend
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
__all__ = [
|
|
46
|
+
"ContactOverflowError",
|
|
47
|
+
"OverlapError",
|
|
48
|
+
"available_backends",
|
|
49
|
+
"backend_unavailable_reason",
|
|
50
|
+
"get_backend",
|
|
51
|
+
]
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"""Errors every backend raises in the same words: an exploded or mis-sized run is never silent."""
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
class OverlapError(RuntimeError):
|
|
5
|
+
"""A contact overlap exceeded the stated fraction of the smaller radius (an unstable run)."""
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class ContactOverflowError(RuntimeError):
|
|
9
|
+
"""A sphere had more simultaneous contacts than the history table holds."""
|