moonbit-granular (MoonBit 颗粒介质离散元库)

moonbit-granular 是基于 MoonBit 语言纯原生实现的颗粒介质离散元（Discrete Element Method, DEM）物理仿真与微宏观统计分析库。与通用的刚体碰撞引擎（如 Box2D/PhysX）不同，本库专注于散体材料（土壤、砂石、矿粉、粮食、药品颗粒）的非线性接触力学、粘结破坏、侧壁伺服控制以及微宏观力学特征统计。

---

🌟 核心特性

• 非线性接触力学模型：
  • Hertz-Mindlin 非线性力学：考虑法向 ${\delta }_n^{3\mathrm{/}2}\backslash delta\_n^\{3/2\}$ 非线性弹性弹簧、接触切向 Mindlin 增量摩擦与库仑滑动阈值。
  • 粘性阻尼与转动摩擦：基于等效恢复系数 $ee$ 的赫兹黏性阻尼与方向恒力矩（EPSD）滚动摩擦阻尼。
  • **平行粘结模型 (Parallel Bond)**：支持胶结颗粒、岩石与烧结材料的抗拉与抗剪断裂破坏仿真。
  • **线性粘弹性模型 (Hooke Viscoelastic)**：提供对比标定的线性弹簧-阻尼接触模型。
• 空间加速与邻域搜索：
  • **3D 均匀空间哈希网格 (Spatial Hash Grid)**：实现 $O(N)O(N)$ 复杂度的碰撞候选检测。
  • **Verlet 蒙皮邻域表 (Verlet Neighbor List)**：基于累积位移阈值增量更新，大幅提升密集堆积下的步进效率。
• 时间积分与自适应步长：
  • Velocity-Verlet 积分器：平动与基于四元数 Quat 的转动运动学同步二阶积分。
  • Rayleigh 瑞利波临界步长估算：依据弹性介质波速自动计算DEM数值稳定时间步长。
• 边界条件与伺服控制：
  • 刚性平面/圆柱容器边界：支持旋转鼓、漏斗、粮仓侧壁。
  • **伺服控制壁面 (Servo Controller)**：比例-积分 (PI) 反馈调节壁面移动速度，保持设定围压（用于直剪与三轴剪切试验）。
  • Periodic 周期性边界：支持 Lees-Edwards 简单剪切流场。
• 微宏观统计与力链分析：
  • 爱因斯坦-洛夫-韦伯 (Love-Weber) 微观应力张量 Homogenization：${\sigma }_{ij}=\frac{1}{V}\sum f_i{x}_j\backslash sigma\_\{ij\}\; =\; \backslash frac\{1\}\{V\}\; \backslash sum\; f\_i\; x\_j$。
  • 织构张量 (Fabric Tensor) 与异向性：接触法向分布异向性指数计算。
  • **力链网络 (Force Network)**：强力链与弱力链分解统计。
  • **配位数 (Coordination Number)**：平均配位数与排除游离颗粒的机械配位数 $Z_{m}Z\_m$。
  • 堆积密度与孔隙比：容重、堆积密度 $\mathrm{\Phi }\backslash Phi$ 与孔隙比 $ee$。

---

📁 架构与包设计

src/
├── math/        # 3D向量(Vec3)、矩阵张量(Mat3)、四元数(Quat)、确定性PRNG
├── particle/    # 颗粒3D表示(Particle3D)、材料属性(MaterialProps)、PSD颗粒级配生成器
├── contact/     # Hertz-Mindlin、Hooke、ParallelBond平行粘结模型
├── boundary/    # 平面壁、圆柱壁、Servo伺服壁面控制器、Periodic周期边界
├── spatial/     # 3D空间哈希网格(SpatialHashGrid)、Verlet邻域表
├── integrator/  # Velocity-Verlet时间积分器、Rayleigh瑞利波步长估算
├── simulation/  # SimulationWorld求解器主引擎、TrajectoryRecorder轨迹导出器
├── stats/       # Love-Weber应力张量、Fabric织构张量、力链网络、配位数与孔隙比
├── app/         # 典型应用: 直剪盒(DirectShearBox)、漏斗下料(Hopper)、三轴剪切(Triaxial)、粮仓沉积(Silo)
├── bench/       # 性能基准测试套件
└── main/        # CLI 演示主入口

---

🚀 快速开始

依赖环境

• MoonBit 工具链 (>= 0.10.3 / 2026.07+)

构建与测试

# 检查项目与依赖
moon check

# 运行单元测试套件
moon test

# 运行 CLI 演示程序
moon run src/main

# 格式化与接口检查
moon fmt
moon info

---

💡 使用示例

import "ssqzerz/moonbit-granular/src/math" @math
import "ssqzerz/moonbit-granular/src/particle" @particle
import "ssqzerz/moonbit-granular/src/boundary" @boundary
import "ssqzerz/moonbit-granular/src/simulation" @simulation
import "ssqzerz/moonbit-granular/src/stats" @stats

fn example() {
  // 1. 创建 DEM 仿真世界
  let world = @simulation.SimulationWorld::new(
    0.02, 512, 0.005, 0.0001, @math.Vec3::new(0.0, -9.81, 0.0)
  )

  // 2. 添加底壁与颗粒
  let wall = @boundary.PlaneWall3D::new(0, @math.Vec3::zero(), @math.Vec3::new(0.0, 1.0, 0.0), 0)
  world.add_plane_wall(wall)

  let p1 = @particle.Particle3D::new(1, @math.Vec3::new(0.0, 0.01, 0.0), 0.005, 2650.0, 0)
  world.add_particle(p1)

  // 3. 推进仿真
  for step = 0; step < 100; step = step + 1 {
    world.step()
  }

  // 4. 统计 Love-Weber 应力张量
  let stress = @stats.compute_love_weber_stress(world, 0.001)
  println("Mean stress p = " + stress.hydrostatic_mean().to_string())
}

---

📜 开源许可证

本项目基于 Apache License 2.0 许可证开源。