jaxdem.utils.clumps

Mass properties of unions of disks and spheres with maximum overlap density.

Functions

compute_clump_properties(state, mat_table[, ...])

Compute rigid union properties for multi-member clumps in an unbatched state.

jaxdem.utils.clumps.compute_clump_properties(state: State, mat_table: MaterialTable, n_samples: int = 50000, sample_batch_size: int = 4096, clump_batch_size: int = 32) → State

Compute rigid union properties for multi-member clumps in an unbatched state.

Each member is a filled disk or ball with volumetric material density mat_table.density[state.mat_id]. The density at any covered point is the maximum density of its containing members, without double counting. Gaps and enclosed cavities outside the union stay empty. The supplied centers and radii alone define the material geometry; omit a central sphere when the clump should have no material there. Zero/negative-density members cannot be used to subtract a cavity.

Disk unions are exact. Sphere unions use analytical cases where possible and otherwise choose boundary or volume quadrature according to overlap density. The dense-volume path avoids dependence on tiny exposed boundary patches. Simultaneous triple and higher-order overlaps are supported. n_samples controls the 3D numerical budget; the two batch sizes bound intermediate memory without changing the rule. Check convergence using volume, COM, and the world-frame inertia tensor at increasing budgets. Positive finite output alone does not certify accuracy.

Principal frames use deterministic signs and handle degenerate moments. Nearly equal principal moments still make individual axes sensitive to integration error. Single-member clumps retain all existing state values.

Host grouping uses compact IDs and separate batches for each member count, so gaps in IDs or one unusually large clump do not create padded work for all other clumps. This grouping/validation step cannot be wrapped in jit; the integration itself is compiled by JAX.