jaxdem.forces.deformable_particle#

Implementation of the deformable particle container.

Functions

`angle_between_normals`(n1, n2)	Computes the angle between two normals.
`compute_body_centers_from_elements`(vertices, ...)
`compute_element_properties_2D`(simplex)	Computes normal, length, and signed partial area for a single simplex.
`compute_element_properties_3D`(simplex)	Computes normal, area, and signed partial volume for a single simplex.
`compute_inverse_reference_shape`(simplex)	Computes the inverse of the reference shape matrix (mapping local edge basis to reference coordinates).
`compute_inverse_reference_shape_tet`(tet)
`compute_tetra_volume`(tet)

Classes

DeformableParticleContainer(elements, edges, ...)

Registry holding topology and reference configuration for deformable particles.

Bases: object

Registry holding topology and reference configuration for deformable particles.

This container manages the mesh connectivity (elements, edges, etc.) and reference properties (initial measures, contents, lengths, angles) required to compute forces. It supports both 3D (volumetric bodies bounded by triangles) and 2D (planar bodies bounded by line segments).

Indices in elements, edges, etc. correspond to the ID of particles in State.

The general form of the deformable particle potential energy per particle is:

\[&E_K = E_{K,measure} + E_{K,content} + E_{K,bending} + E_{K,edge} + E_{K,strain}\]

Definitions per Dimension:

3D: Measure ($mathcal{M}$) is Face Area; Content ($mathcal{C}$) is Volume; Elements are Triangles.
2D: Measure ($mathcal{M}$) is Segment Length; Content ($mathcal{C}$) is Enclosed Area; Elements are Segments.

Strain Energy (StVK) on Elements (Triangles): .. math:

W = A_0 \cdot \left( \mu \mathrm{tr}(E^2) + \frac{\lambda}{2} (\mathrm{tr} E)^2 \right)

All mesh properties are concatenated along axis=0.

elements: Array | None#: Array of vertex indices forming the boundary elements. Shape: (M, 3) for 3D (Triangles) or (M, 2) for 2D (Segments). Indices refer to the particle unique ID corresponding to the State.pos array.

edges: Array | None#

(E, 2). Each row contains the indices of the two vertices forming the edge. Note: In 2D, the set of edges often overlaps with the set of elements (segments).

Type:: Array of vertex indices forming the unique edges (wireframe). Shape

element_adjacency: Array | None#

(A, 2). Each row contains the indices of the two elements sharing a connection.

Type:: Array of element adjacency pairs (for bending/dihedral angles). Shape

element_adjacency_edges: Array | None#: Array of vertex IDs forming the shared edge for each adjacency. Shape: (A, 2).

elements_ID: Array | None#

(M,). elements_ID[i] == k means element i belongs to body k.

Type:: Array of body IDs for each boundary element. Shape

edges_ID: Array | None#

(E,). edges_ID[e] == k means edge e belongs to body k.

Type:: Array of body IDs for each unique edge. Shape

element_adjacency_ID: Array | None#

(A,). element_adjacency_ID[a] == k means adjacency a belongs to body k.

Type:: Array of body IDs for each adjacency (bending hinge). Shape

num_bodies: int#

(K,).

Type:: Total number of distinct deformable bodies in the container. Shape

initial_body_contents: Array | None#

(K,). Represents Volume in 3D or Area in 2D.

Type:: Array of reference (stress-free) bulk content for each body. Shape

initial_element_measures: Array | None#

(M,). Represents Area in 3D or Length in 2D.

Type:: Array of reference (stress-free) measures for each element. Shape

initial_edge_lengths: Array | None#

(E,).

Type:: Array of reference (stress-free) lengths for each unique edge. Shape

initial_bending: Array | None#

(A,). Represents Dihedral Angle in 3D or Vertex Angle in 2D.

Type:: Array of reference (stress-free) bending angles for each adjacency. Shape

inv_ref_shape: Array | None#: Inverse of the reference shape matrix for each element. Shape: (M, 2, 2) for triangles, or (M, 1, 1) for segments. Used to compute the deformation gradient F or Green strain E.

inv_ref_tet_shape: Array | None#: Inverse of the reference shape matrix for tetrahedra formed by each boundary triangle and the corresponding body center. Shape: (M, 3, 3).

initial_tet_volumes: Array | None#: Reference volumes for tetrahedra formed by each boundary triangle and the corresponding body center. Shape: (M,).

em: Array | None#

(K,). (Controls Area stiffness in 3D; Length stiffness in 2D).

Type:: Measure elasticity coefficient (Modulus) for each body. Shape

ec: Array | None#

(K,). (Controls Volume stiffness in 3D; Area stiffness in 2D).

Type:: Content elasticity coefficient (Modulus) for each body. Shape

eb: Array | None#

(K,).

Type:: Bending elasticity coefficient (Rigidity) for each body. Shape

el: Array | None#

(K,).

Type:: Edge length elasticity coefficient (Modulus) for each body. Shape

gamma: Array | None#

(K,).

Type:: Surface/Line tension coefficient for each body. Shape

lame_lambda: Array | None#

(K,).

Type:: First Lamé parameter for StVK model. Shape

lame_mu: Array | None#

(K,).

Type:: Second Lamé parameter (Shear Modulus) for StVK model. Shape

use_tetrahedral_svk: bool#: If True, compute StVK strain energy on tetrahedra formed by each boundary triangle and the mesh center of its body (3D only). If False, use the existing shell-like element StVK model.

Factory method to create a new DeformableParticleContainer.

Calculates initial geometric properties (areas, volumes, bending angles, and edge lengths) from the provided vertices if they are not explicitly provided.

static merge(c1: DeformableParticleContainer, c2: DeformableParticleContainer) → DeformableParticleContainer[source][source]#: Merges two DeformableParticleContainer instances.

static add(container: DeformableParticleContainer, vertices: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray, *, elements_ID: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, elements: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, initial_element_measures: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, element_adjacency_ID: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, element_adjacency: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, initial_bending: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, edges_ID: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, edges: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, initial_edge_lengths: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, initial_body_contents: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, em: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, ec: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, eb: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, el: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, gamma: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, lame_lambda: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, lame_mu: Array | ndarray | bool | number | bool | int | float | complex | TypedNdArray | None = None, use_tetrahedral_svk: bool = False) → DeformableParticleContainer[source][source]#: Factory method to add bodies to a container.

static compute_potential_energy(pos: jax.Array, state: State, _system: System, container: DeformableParticleContainer) → Tuple[jax.Array, Dict[str, jax.Array]][source][source]#

static create_force_function(container: DeformableParticleContainer) → ForceFunction[source][source]#

static create_force_energy_functions(container: DeformableParticleContainer) → Tuple[ForceFunction, EnergyFunction][source][source]#

jaxdem.forces.deformable_particle.angle_between_normals(n1: Array, n2: Array) → Array[source][source]#

Computes the angle between two normals.

Parameters:

n1 (jax.Array) – First normal vector.
n2 (jax.Array) – Second normal vector.

Returns:

Angle between the two normals in radians.

Return type:

jax.Array

jaxdem.forces.deformable_particle.compute_element_properties_3D(simplex: Array) → Tuple[Array, Array, Array][source][source]#

Computes normal, area, and signed partial volume for a single simplex.

Parameters:: simplex (jax.Array) – Shape (3, 3) representing the coordinates of the 3 vertices.
Returns:: (unit_normal, area, partial_volume)
Return type:: Tuple[jax.Array, jax.Array, jax.Array]

jaxdem.forces.deformable_particle.compute_element_properties_2D(simplex: Array) → Tuple[Array, Array, Array][source][source]#

Computes normal, length, and signed partial area for a single simplex.

Parameters:: simplex (jax.Array) – Shape (2, 2) representing the coordinates of the 2 vertices.
Returns:: (unit_normal, length, partial_area)
Return type:: Tuple[jax.Array, jax.Array, jax.Array]

jaxdem.forces.deformable_particle.compute_inverse_reference_shape(simplex: Array) → Array[source][source]#

Computes the inverse of the reference shape matrix (mapping local edge basis to reference coordinates).

For a triangle (3 verts), constructs a local 2D basis and inverts the mapping [X2-X1, X3-X1]. For a segment (2 verts), inverts the length.

Returns:: (2, 2) matrix for triangles, or (1, 1) for segments.

jaxdem.forces.deformable_particle.compute_body_centers_from_elements(vertices: Array, elements: Array, elements_ID: Array, num_bodies: int) → Array[source][source]#

jaxdem.forces.deformable_particle.compute_inverse_reference_shape_tet(tet: Array) → Array[source][source]#

jaxdem.forces.deformable_particle.compute_tetra_volume(tet: Array) → Array[source][source]#