milldem 0.2.0__tar.gz

milldem-0.2.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: milldem
+Version: 0.2.0
+Summary: Cross-platform soft-sphere DEM for tumbling-mill charge motion and power (2D charge shape + thin-3D-slab power validated vs Hogg-Fuerstenau; no C++/WSL).
+Author: Felipe Santibanez-Leal
+License: MIT
+Project-URL: Homepage, https://github.com/fsantibanezleal/CAOS_MillDEM
+Project-URL: Repository, https://github.com/fsantibanezleal/CAOS_MillDEM
+Project-URL: Changelog, https://github.com/fsantibanezleal/CAOS_MillDEM/blob/main/CHANGELOG.md
+Keywords: DEM,discrete element method,tumbling mill,SAG,ball mill,comminution,charge motion,mineral processing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy<2.3,>=2.0
+Requires-Dist: scipy>=1.13
+Provides-Extra: jit
+Requires-Dist: numba>=0.61; extra == "jit"
+Provides-Extra: train
+Requires-Dist: numba>=0.61; extra == "train"
+Requires-Dist: torch-geometric>=2.5; extra == "train"
+Requires-Dist: matplotlib>=3.8; extra == "train"
+Requires-Dist: tqdm>=4.66; extra == "train"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: matplotlib>=3.8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+
+# CAOS_MillDEM
+
+A cross-platform 2D soft-sphere **discrete element method (DEM)** engine for tumbling-mill charge motion and
+power. No C++ toolchain, no WSL: pure NumPy with an optional Numba JIT and an optional Torch-CUDA path.
+
+It simulates a rotating mill disc slice (the Govender et al. 2015 reduced setup, width = one particle
+diameter) with a soft-sphere contact law (linear Hookean or Hertzian, Coulomb friction, restitution damping)
+and reports the DEM charge shape (toe/shoulder), the motion regime (cascading / cataracting / centrifuging),
+and the net power via the van Nierop (2001) torque route `P = 2*pi*T*N`.
+
+```python
+from milldem import simulate, MillConfig
+m = simulate(MillConfig(diameter_m=5.0, phi_c=0.75, fill=0.30), sim_time=2.0)
+print(m.net_power_kw, m.regime, m.toe_deg, m.shoulder_deg)
+```
+
+CLI: `milldem run --D 5 --phi 0.75 --J 0.30 --time 2.0 --json out.json`
+
+See [`docs/VALIDATION.md`](docs/VALIDATION.md) for the honest validated-scope statement, and `docs/` for the contact-model equations, the power routes, and the validation against the classical
+Hogg-Fuerstenau and Morrell power models. MIT licensed.

milldem-0.2.0/README.md

@@ -0,0 +1,20 @@
+# CAOS_MillDEM
+
+A cross-platform 2D soft-sphere **discrete element method (DEM)** engine for tumbling-mill charge motion and
+power. No C++ toolchain, no WSL: pure NumPy with an optional Numba JIT and an optional Torch-CUDA path.
+
+It simulates a rotating mill disc slice (the Govender et al. 2015 reduced setup, width = one particle
+diameter) with a soft-sphere contact law (linear Hookean or Hertzian, Coulomb friction, restitution damping)
+and reports the DEM charge shape (toe/shoulder), the motion regime (cascading / cataracting / centrifuging),
+and the net power via the van Nierop (2001) torque route `P = 2*pi*T*N`.
+
+```python
+from milldem import simulate, MillConfig
+m = simulate(MillConfig(diameter_m=5.0, phi_c=0.75, fill=0.30), sim_time=2.0)
+print(m.net_power_kw, m.regime, m.toe_deg, m.shoulder_deg)
+```
+
+CLI: `milldem run --D 5 --phi 0.75 --J 0.30 --time 2.0 --json out.json`
+
+See [`docs/VALIDATION.md`](docs/VALIDATION.md) for the honest validated-scope statement, and `docs/` for the contact-model equations, the power routes, and the validation against the classical
+Hogg-Fuerstenau and Morrell power models. MIT licensed.

milldem-0.2.0/milldem/__init__.py

@@ -0,0 +1,46 @@
+"""CAOS_MillDEM, a cross-platform 2D soft-sphere DEM engine for tumbling-mill charge motion + power.
+
+No C++ toolchain, no WSL: pure numpy with an optional numba JIT and an optional torch-CUDA path. The engine
+simulates a rotating mill disc slice (Govender et al. 2015 reduced setup) and reports the DEM charge shape,
+motion regime, and net power via the van Nierop (2001) torque route.
+
+Quick start::
+
+    from milldem import simulate, MillConfig, ContactModel
+    m = simulate(MillConfig(diameter_m=5.0, phi_c=0.75, fill=0.30), sim_time=2.0)
+    print(m.net_power_kw, m.regime, m.toe_deg, m.shoulder_deg)
+"""
+from __future__ import annotations
+
+from .contact import ContactModel
+from .engine import G, MillConfig, MillDEM
+from .engine3d import MillDEM3D
+from .metrics import MillMetrics, compute_metrics
+
+__version__ = "0.02.000"  # X.XX.XXX display form (versioning.md)
+__all__ = ["ContactModel", "MillConfig", "MillDEM", "MillDEM3D", "MillMetrics",
+           "compute_metrics", "simulate", "simulate_power", "G"]
+
+
+def simulate_power(cfg: MillConfig, sim_time: float = 1.5, slab_thickness_m: float | None = None,
+                   seed: int = 42) -> dict:
+    """Run the thin-3D-slab DEM and return the validated net power + charge geometry.
+
+    The 3D slab (axial-periodic) captures the force chains that carry the charge lift, so the net power is
+    size-consistent and lands within ~10-20% of the classical Hogg-Fuerstenau model across speed, fill and mill
+    size (see docs/VALIDATION.md). Returns {net_power_kw, arm_m, n_particles}.
+    """
+    sim = MillDEM3D(cfg, slab_thickness_m=slab_thickness_m, seed=seed)
+    sim.run(sim_time)
+    return {"net_power_kw": sim.net_power_kw(), "arm_m": sim.arm_m(), "n_particles": sim.n}
+
+
+def simulate(cfg: MillConfig, sim_time: float = 2.0, seed: int = 42, settle_frac: float = 0.5) -> MillMetrics:
+    """Run a full mill DEM simulation and return the settled-state metrics.
+
+    ``sim_time`` seconds of simulated mill operation; the last ``1 - settle_frac`` of the run is used for the
+    metrics (the first half lets the charge settle from its initial placement into steady motion).
+    """
+    sim = MillDEM(cfg, seed=seed)
+    sim.run(sim_time, settle_frac=settle_frac)
+    return compute_metrics(sim, settle_frac=settle_frac)

milldem-0.2.0/milldem/__main__.py

@@ -0,0 +1,5 @@
+"""Enable ``python -m milldem`` as an alias for the ``milldem`` console script."""
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

milldem-0.2.0/milldem/cli.py

@@ -0,0 +1,97 @@
+"""``milldem`` command-line interface.
+
+    milldem run   --D 5.0 --phi 0.75 --J 0.30 --ball 0.10 --time 2.0 [--json out.json] [--frames frames.npz]
+    milldem power --D 5.0 --phi 0.75 --J 0.30 --ball 0.10 --L 6.0 [--time 1.5] [--json out.json]
+
+``run`` gives the fast 2D qualitative charge-shape / regime read; ``power`` runs the validated thin-3D slab and
+reports the size-consistent net power (within ~10-20% of Hogg-Fuerstenau, see docs/VALIDATION.md).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+
+import numpy as np
+
+from . import ContactModel, MillConfig, MillDEM, __version__, compute_metrics, simulate_power
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="milldem", description="Soft-sphere tumbling-mill DEM (2D charge shape + "
+                                                            "validated thin-3D-slab power).")
+    p.add_argument("--version", action="version", version=f"milldem {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    r = sub.add_parser("run", help="run a 2D simulation and report the settled charge-shape / regime metrics")
+    r.add_argument("--D", type=float, default=5.0, help="mill diameter [m]")
+    r.add_argument("--L", type=float, default=6.0, help="mill length [m] (for net-power scaling)")
+    r.add_argument("--phi", type=float, default=0.75, help="fraction of critical speed")
+    r.add_argument("--J", type=float, default=0.30, help="fractional filling")
+    r.add_argument("--ball", type=float, default=0.10, help="top ball diameter [m]")
+    r.add_argument("--size-ratio", type=float, default=1.0, help="min/max ball diameter (1 = mono)")
+    r.add_argument("--lifters", type=int, default=8, help="number of lifter bars")
+    r.add_argument("--e", type=float, default=0.6, help="coefficient of restitution")
+    r.add_argument("--mu", type=float, default=0.5, help="sliding friction")
+    r.add_argument("--model", choices=["hooke", "hertz"], default="hooke")
+    r.add_argument("--time", type=float, default=2.0, help="simulated time [s]")
+    r.add_argument("--seed", type=int, default=42)
+    r.add_argument("--json", type=str, default=None, help="write the metrics to this JSON path")
+    r.add_argument("--frames", type=str, default=None, help="write a compact frame series (npz) to this path")
+    r.add_argument("--frame-stride", type=int, default=200, help="record one frame every N steps")
+
+    pw = sub.add_parser("power", help="run the validated thin-3D slab and report the net power [kW]")
+    pw.add_argument("--D", type=float, default=5.0, help="mill diameter [m]")
+    pw.add_argument("--L", type=float, default=6.0, help="mill length [m]")
+    pw.add_argument("--phi", type=float, default=0.75, help="fraction of critical speed")
+    pw.add_argument("--J", type=float, default=0.30, help="fractional filling")
+    pw.add_argument("--ball", type=float, default=0.24, help="top ball diameter [m]")
+    pw.add_argument("--size-ratio", type=float, default=1.0, help="min/max ball diameter (1 = mono)")
+    pw.add_argument("--slab", type=float, default=None, help="slab thickness [m] (default 4 ball diameters)")
+    pw.add_argument("--time", type=float, default=1.5, help="simulated time [s] after settling")
+    pw.add_argument("--seed", type=int, default=42)
+    pw.add_argument("--json", type=str, default=None, help="write the result to this JSON path")
+
+    a = p.parse_args(argv)
+    if a.cmd == "power":
+        cfg = MillConfig(diameter_m=a.D, length_m=a.L, phi_c=a.phi, fill=a.J, ball_diameter_m=a.ball,
+                         size_ratio=a.size_ratio)
+        res = simulate_power(cfg, sim_time=a.time, slab_thickness_m=a.slab, seed=a.seed)
+        out = {"config": {"D": a.D, "L": a.L, "phi_c": a.phi, "J": a.J, "ball": a.ball, "seed": a.seed},
+               "net_power_kw": res["net_power_kw"], "arm_m": res["arm_m"], "n_particles": res["n_particles"]}
+        print(json.dumps(out, indent=2))
+        if a.json:
+            with open(a.json, "w", encoding="utf-8") as f:
+                json.dump(out, f, indent=2)
+        return 0
+    if a.cmd == "run":
+        cfg = MillConfig(
+            diameter_m=a.D, length_m=a.L, phi_c=a.phi, fill=a.J, ball_diameter_m=a.ball,
+            size_ratio=a.size_ratio, n_lifters=a.lifters,
+            contact=ContactModel(model=a.model, e=a.e, mu=a.mu),
+        )
+        sim = MillDEM(cfg, seed=a.seed)
+        n_steps = int(a.time / sim.dt)
+        frames = []
+        for i in range(n_steps):
+            sim.step()
+            if a.frames and (i % a.frame_stride == 0):
+                frames.append(np.stack([sim.px, sim.py], axis=1).astype(np.float32))
+        m = compute_metrics(sim)
+        md = asdict(m)
+        print(json.dumps(md, indent=2))
+        if a.json:
+            with open(a.json, "w", encoding="utf-8") as f:
+                json.dump({"config": {"D": a.D, "L": a.L, "phi_c": a.phi, "J": a.J, "ball": a.ball,
+                                       "model": a.model, "e": a.e, "mu": a.mu, "seed": a.seed},
+                           "metrics": md}, f, indent=2)
+        if a.frames and frames:
+            np.savez_compressed(a.frames, frames=np.stack(frames), radii=sim.r.astype(np.float32),
+                                R=sim.R, n_frames=len(frames))
+            print(f"wrote {len(frames)} frames to {a.frames}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

milldem-0.2.0/milldem/contact.py

@@ -0,0 +1,89 @@
+"""Soft-sphere contact force models for DEM.
+
+Two force laws behind one interface, both verified verbatim against the LAMMPS granular pair-style docs
+(docs.lammps.org/pair_gran.html) and the Golpayegani & Rezai (2022) review (Eqs 23-25):
+
+Linear Hookean (``gran/hooke``)::
+
+    F_n = k_n * delta       - m_eff * gamma_n * v_n      (normal:   spring - dashpot)
+    F_t = -(k_t * ds_t)     - m_eff * gamma_t * v_t      (tangent:  shear spring - dashpot)
+    |F_t| <= mu * |F_n|                                  (Coulomb friction truncation)
+
+Hertzian (``gran/hertz/history``): the Hookean force scaled by ``sqrt(delta) * sqrt(R_i R_j / (R_i + R_j))``.
+
+Damping is not free: the dashpot constant ``gamma_n`` is set from a target coefficient of restitution ``e``.
+For the linear model the closed form is exact::
+
+    gamma_n = -2 * ln(e) * sqrt(k_n / m_eff) / sqrt(pi**2 + ln(e)**2)
+
+(the standard linear-spring-dashpot restitution relation). For Hertz the Tsuji (1992) velocity-independent
+form is used. References: Cundall & Strack 1979 (DOI 10.1680/geot.1979.29.1.47); Tsuji, Tanaka & Ishida 1992
+(DOI 10.1016/0032-5910(92)88030-L); LAMMPS granular docs.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ContactModel:
+    """Contact parameters. ``model`` is ``"hooke"`` (linear) or ``"hertz"``.
+
+    ``kn``/``kt`` are the normal/tangential stiffnesses (N/m for Hooke; the Hertz prefactor for hertz),
+    ``e`` the coefficient of restitution (0..1), ``mu`` the sliding-friction coefficient, ``mu_r`` the
+    rolling-friction coefficient (a resistive moment, 0 disables it).
+    """
+
+    model: str = "hooke"
+    kn: float = 1.0e5          # normal stiffness FLOOR [N/m] (the engine auto-scales up for stable integration)
+    kt_ratio: float = 2.0 / 7  # kt = kt_ratio * kn (the standard 2/7 shear-to-normal ratio)
+    e: float = 0.5             # coefficient of restitution (0.45-0.90 typical for mill media)
+    mu: float = 0.25           # sliding friction (calibrated so the charge holds a stable lifted crescent;
+                               # too high fluidizes the bed, too low lets it slump)
+    mu_r: float = 0.05         # rolling friction (resistive-moment coefficient)
+
+    def kt(self) -> float:
+        return self.kt_ratio * self.kn
+
+    def normal_damping(self, m_eff: float) -> float:
+        """The normal dashpot constant gamma_n [1/s] giving the target restitution e, linear model."""
+        e = min(max(self.e, 1e-4), 0.999)
+        lne = math.log(e)
+        # gamma_n such that the linear spring-dashpot yields restitution e (Antypov & Elliott 2011 form)
+        return -2.0 * lne * math.sqrt(self.kn / m_eff) / math.sqrt(math.pi ** 2 + lne ** 2)
+
+    def contact_time(self, m_eff: float) -> float:
+        """The linear contact half-period t_c = pi * sqrt(m_eff / kn) [s]; dt must be a fraction of this."""
+        return math.pi * math.sqrt(m_eff / self.kn)
+
+
+def effective_mass(m_i: float, m_j: float) -> float:
+    """m_eff = m_i m_j / (m_i + m_j); for a particle-wall contact pass m_j = inf (returns m_i)."""
+    if math.isinf(m_j):
+        return m_i
+    return m_i * m_j / (m_i + m_j)
+
+
+def normal_force(model: ContactModel, delta: float, v_n: float, m_eff: float, r_eff: float) -> float:
+    """Scalar normal contact force [N] (positive = repulsive) for overlap ``delta`` >= 0 and normal
+    approach velocity ``v_n`` (positive when the bodies approach). ``r_eff`` = R_i R_j /(R_i + R_j)."""
+    if delta <= 0.0:
+        return 0.0
+    gamma_n = model.normal_damping(m_eff)
+    if model.model == "hertz":
+        scale = math.sqrt(delta) * math.sqrt(max(r_eff, 1e-12))
+        return scale * (model.kn * delta + m_eff * gamma_n * v_n)
+    # linear Hooke: spring + dashpot (damping opposes approach; v_n>0 approaching)
+    return model.kn * delta + m_eff * gamma_n * v_n
+
+
+def tangential_force(model: ContactModel, ds_t: float, v_t: float, fn: float, m_eff: float) -> float:
+    """Scalar tangential force [N], Coulomb-truncated to |F_t| <= mu*|F_n|. ``ds_t`` is the accumulated
+    elastic tangential displacement, ``v_t`` the tangential relative velocity."""
+    gamma_t = model.normal_damping(m_eff) * 0.5  # tangential damping ~ half normal (common choice)
+    ft = -(model.kt() * ds_t) - m_eff * gamma_t * v_t
+    cap = model.mu * abs(fn)
+    if abs(ft) > cap:
+        ft = math.copysign(cap, ft)
+    return ft