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.
Files changed (54) hide show
  1. crushdem-0.5.0/LICENSE +21 -0
  2. crushdem-0.5.0/PKG-INFO +214 -0
  3. crushdem-0.5.0/README.md +173 -0
  4. crushdem-0.5.0/crushdem/__init__.py +36 -0
  5. crushdem-0.5.0/crushdem/_version.py +2 -0
  6. crushdem-0.5.0/crushdem/backends/__init__.py +51 -0
  7. crushdem-0.5.0/crushdem/backends/errors.py +9 -0
  8. crushdem-0.5.0/crushdem/backends/numba_cpu.py +484 -0
  9. crushdem-0.5.0/crushdem/backends/warp_cuda.py +594 -0
  10. crushdem-0.5.0/crushdem/breakage/__init__.py +18 -0
  11. crushdem-0.5.0/crushdem/breakage/progeny.py +199 -0
  12. crushdem-0.5.0/crushdem/breakage/replacement.py +460 -0
  13. crushdem-0.5.0/crushdem/breakage/tavares.py +183 -0
  14. crushdem-0.5.0/crushdem/comparison.py +360 -0
  15. crushdem-0.5.0/crushdem/core/__init__.py +1 -0
  16. crushdem-0.5.0/crushdem/core/_jit.py +27 -0
  17. crushdem-0.5.0/crushdem/core/contact.py +101 -0
  18. crushdem-0.5.0/crushdem/core/materials.py +162 -0
  19. crushdem-0.5.0/crushdem/core/scenarios.py +56 -0
  20. crushdem-0.5.0/crushdem/core/state.py +103 -0
  21. crushdem-0.5.0/crushdem/flow.py +326 -0
  22. crushdem-0.5.0/crushdem/machines/__init__.py +8 -0
  23. crushdem-0.5.0/crushdem/machines/cone.py +93 -0
  24. crushdem-0.5.0/crushdem/machines/jaw.py +198 -0
  25. crushdem-0.5.0/crushdem/machines/machine.py +44 -0
  26. crushdem-0.5.0/crushdem/neighbours/__init__.py +4 -0
  27. crushdem-0.5.0/crushdem/neighbours/hash_grid.py +107 -0
  28. crushdem-0.5.0/crushdem/simulation.py +324 -0
  29. crushdem-0.5.0/crushdem/walls/__init__.py +8 -0
  30. crushdem-0.5.0/crushdem/walls/geometry.py +206 -0
  31. crushdem-0.5.0/crushdem/walls/motion.py +120 -0
  32. crushdem-0.5.0/crushdem.egg-info/PKG-INFO +214 -0
  33. crushdem-0.5.0/crushdem.egg-info/SOURCES.txt +52 -0
  34. crushdem-0.5.0/crushdem.egg-info/dependency_links.txt +1 -0
  35. crushdem-0.5.0/crushdem.egg-info/requires.txt +16 -0
  36. crushdem-0.5.0/crushdem.egg-info/top_level.txt +1 -0
  37. crushdem-0.5.0/pyproject.toml +52 -0
  38. crushdem-0.5.0/setup.cfg +4 -0
  39. crushdem-0.5.0/tests/test_breakage.py +604 -0
  40. crushdem-0.5.0/tests/test_comparison.py +268 -0
  41. crushdem-0.5.0/tests/test_contact.py +184 -0
  42. crushdem-0.5.0/tests/test_determinism.py +47 -0
  43. crushdem-0.5.0/tests/test_evaluate.py +155 -0
  44. crushdem-0.5.0/tests/test_flow.py +135 -0
  45. crushdem-0.5.0/tests/test_integrator.py +48 -0
  46. crushdem-0.5.0/tests/test_machines.py +141 -0
  47. crushdem-0.5.0/tests/test_neighbours.py +60 -0
  48. crushdem-0.5.0/tests/test_notebooks.py +107 -0
  49. crushdem-0.5.0/tests/test_packaging.py +51 -0
  50. crushdem-0.5.0/tests/test_parity.py +87 -0
  51. crushdem-0.5.0/tests/test_readme.py +38 -0
  52. crushdem-0.5.0/tests/test_result.py +71 -0
  53. crushdem-0.5.0/tests/test_validation_record.py +291 -0
  54. 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.
@@ -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).
@@ -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,2 @@
1
+ """The package version in the display form X.XX.XXX (VERSION is the single source; tests/test_packaging.py keeps both in step)."""
2
+ __version__ = "0.05.000"
@@ -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."""