dirt_atom 0.1.4

Per-atom DEM data (radius, density) with pack/unpack and MaterialTable for DIRT
docs.rs failed to build dirt_atom-0.1.4
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

dirt_atom

Per-atom DEM data and material property tables for DIRT.

What it does

dirt_atom provides the core per-atom data structures, material property system, and particle insertion for Discrete Element Method (DEM) simulations on the SOIL substrate:

  • DemAtom — Per-atom extension data (radius, density, inverse inertia, orientation, angular velocity/momentum, torque, rigid-body id), registered via SOIL's AtomData derive with #[forward] / #[reverse] / #[zero] attributes controlling MPI pack/unpack and per-timestep zeroing.
  • MaterialTable — Named materials with mechanical properties (Young's modulus, Poisson's ratio, restitution, friction, cohesion/surface energy, rolling/twisting) plus precomputed per-pair mixing tables for contact-force evaluation.
  • DemAtomPlugin — Registers DemAtom and builds the MaterialTable from [[dem.materials]] config.
  • DemAtomInsertPlugin — Particle insertion from [[particles.insert]]: random placement (with overlap checking), rate-based trickle insertion, or file-based loading (CSV, LAMMPS dump, LAMMPS data).
  • RadiusSpec — Fixed radius or statistical distribution (uniform, gaussian, lognormal, discrete).

Key types and plugins

Item Kind Role
DemAtomPlugin Plugin Registers DemAtom, builds MaterialTable, sets Atom::ntypes
DemAtomInsertPlugin Plugin Setup + runtime systems for random/rate/file insertion
DemAtom AtomData Per-atom radius, density, inv_inertia, quaternion, omega, ang_mom, torque, body_id
MaterialTable Resource Per-material + per-pair (*_ij) precomputed contact properties
MaterialConfig / DemConfig Config Deserialized [[dem.materials]] / [dem]
InsertConfig / ParticlesConfig Config Deserialized [[particles.insert]] / [particles]
RadiusSpec / RadiusDistribution Config Fixed value or sampled radius distribution
same_body(dem, i, j) fn True when atoms i and j share a rigid body

AtomData attributes on DemAtom

  • #[forward] — sent from owner to ghost atoms each timestep (omega, body_id).
  • #[reverse] — ghost contributions summed back into the owner (torque).
  • #[zero] — zeroed before each force computation (torque).

Fields without attributes are communicated only during atom migration.

TOML configuration

[dem]
contact_model = "hertz"        # "hertz" (default) or "hooke"
adhesion_model = "jkr"         # "jkr" (default) or "dmt", used when surface_energy > 0
rolling_model = "constant"     # "constant" (default) or "sds"
twisting_model = "constant"    # "constant" (default) or "sds"

[[dem.materials]]
name = "glass"
youngs_mod = 8.7e9
poisson_ratio = 0.3
restitution = 0.95
friction = 0.4                 # default 0.4
# rolling_friction = 0.1       # default 0.0 (disabled)
# cohesion_energy = 0.05       # SJKR cohesion, J/m² (default 0.0)
# surface_energy = 0.05        # JKR/DMT adhesion, J/m² (default 0.0; mutually exclusive with cohesion_energy)
# twisting_friction = 0.0
# kn = 0.0 / kt = 0.0          # Hooke stiffnesses (0 = use Hertz/Mindlin)

[[particles.insert]]
material = "glass"             # must match a [[dem.materials]] name
count = 100
radius = 0.001                 # or a distribution table
density = 2500.0

Usage

use dirt_atom::{Elastic, Friction, Material, MaterialTable};

let mut table = MaterialTable::new();
let glass = table.add(Material::new("glass", Elastic::new(8.7e9, 0.3, 0.95))
    .with_friction(Friction { sliding: 0.4, rolling: 0.1, twisting: 0.0 }))?;
let steel = table.add(Material::new("steel", Elastic::new(200e9, 0.28, 0.8))
    .with_friction(Friction { sliding: 0.3, rolling: 0.05, twisting: 0.0 }))?;
table.build_pair_tables();

// Per-pair properties indexed as table_ij[i][j]:
let friction = table.friction_ij[glass.index()][steel.index()];
let e_eff = table.e_eff_ij[glass.index()][steel.index()];

Per-pair tables are mixed with geometric mean (friction, restitution, rolling/twisting friction, cohesion/surface energy, SDS damping), harmonic mean (Hooke and SDS stiffnesses), and effective-modulus formulas for Hertz (E*) and Mindlin (G*).

License

MIT OR Apache-2.0