jaxdem.materials#

Interface for defining materials and the MaterialTable.

Classes

Material(density)

Abstract base class for materials.

class jaxdem.materials.Elastic(density: float, young: float, poisson: float)#

Bases: Material

Example:#

>>> import jaxdem as jdem
>>> elastic_steel = jdem.Material.create("elastic", density=7850.0, young=2.0e11, poisson=0.3)

young: float#

poisson: float#

class jaxdem.materials.ElasticFriction(density: float, young: float, poisson: float, mu: float, e: float, mu_r: float = 0.0)#

Bases: Material

Example:#

>>> import jaxdem as jdem
>>> frictional_rubber = jdem.Material.create("elasticfrict", density=1100.0, young=1.0e7, poisson=0.49, mu=0.5, e=1.0)
>>> geared_sphere = jdem.Material.create("elasticfrict", density=1100.0, young=1.0e7, poisson=0.49, mu=0.5, e=1.0, mu_r=0.3)

young: float#

poisson: float#

mu: float#

e: float#

mu_r: float#: Rolling friction coefficient. It creates a resistive torque \(-\mu_r R_{\text{eff}} F_n \hat{\omega}_{\text{rel}}\) that opposes the relative angular velocity at the contact.

class jaxdem.materials.LJMaterial(density: float, epsilon: float)#

Bases: Material

Material for LJ/WCA interactions.

Notes

The LJ and WCA force laws use epsilon_eff from MaterialTable and derive sigma from particle radii, so this material only needs epsilon (plus density for mass calculations).

epsilon: float#

class jaxdem.materials.Material(density: float)#

Bases: Factory

Abstract base class for materials.

Concrete subclasses of Material define scalar or vector fields (e.g., young, poisson, mu) for the physical properties of a material. The MaterialTable collects and manages these fields.

Notes:#

Each field of a concrete Material subclass becomes a named property in the MaterialTable.props dictionary.

Example:#

To define a custom material, inherit from Material

>>> @Material.register("my_custom_material")
>>> @jax.tree_util.register_dataclass
>>> @dataclass(slots=True)
>>> class MyCustomMaterial(Material):
        ...

density: float#

class jaxdem.materials.MaterialTable(props: dict[str, Array], pair: dict[str, Array], matcher: MaterialMatchmaker)#

Bases: object

A container for material properties, organized as Structures of Arrays (SoA) and pre-computed effective pair properties.

The table gives direct access to the scalar properties of each material and to the pre-computed effective properties for material pairs.

Notes:#

Access scalar properties directly with dot notation (e.g., material_table.young).
Access effective pair properties directly with dot notation (e.g., material_table.young_eff).

Example:#

Creating a MaterialTable from multiple material types:

>>> import jax.numpy as jnp
>>> import jaxdem as jdem
>>>
>>> # Define different material instances
>>> mat1 = jdem.Material.create("elastic", density=2500.0, young=1.0e4, poisson=0.3)
>>> mat2 = jdem.Material.create("elasticfrict", density=7800.0, young=2.0e4, poisson=0.4, mu=0.5, e=1.0)
>>>
>>> # Create a MaterialTable using a linear matcher
>>> matcher_instance = jdem.MaterialMatchmaker.create("linear")
>>> mat_table = jdem.MaterialTable.from_materials(
>>>     [mat1, mat2],
>>>     matcher=matcher_instance
>>> )

props: dict[str, Array]#: A dictionary mapping scalar material property names (e.g., “young”, “poisson”, “mu”) to JAX arrays. Each array has shape (M,), where M is the total number of distinct material types present in the table.

pair: dict[str, Array]#: A dictionary mapping effective pair property names (e.g., “young_eff”, “mu_eff”) to JAX arrays. Each array has shape (M, M) and holds the effective property for interactions between any two material types (M_i, M_j).

matcher: MaterialMatchmaker#: The jaxdem.MaterialMatchmaker instance that computed the effective pair properties stored in the pair dictionary.

static from_materials(mats: Sequence[Material], *, matcher: MaterialMatchmaker | None = None, fill: float = 0.0) → MaterialTable[source]#

Construct a MaterialTable from a sequence of Material instances.

Parameters:

mats (Sequence[Material]) – A sequence of concrete Material instances. Each instance represents a distinct material type in the simulation. The order in this sequence defines their material IDs (0 to len(mats)-1).
matcher (MaterialMatchmaker) – The jaxdem.MaterialMatchmaker instance used to compute effective pair properties (e.g., harmonic mean, arithmetic mean). If None, defaults to the harmonic matchmaker.
fill (float, optional) – Fill value for material properties that a Material subclass does not define. For example, if an Elastic material appears with an ElasticFriction material, mu takes this value. Defaults to 0.0.

Returns:

A new MaterialTable instance containing the scalar properties and pre-computed effective pair properties for all provided materials.

Return type:

MaterialTable

Raises:

TypeError – If mats is not a sequence of Material instances.

property metadata: dict[str, Any][source]#: MaterialTable configuration parameters for serialization and restoration.

Modules

`elastic_mats`	Elastic material variants.
`lj_mats`	Material definitions for Lennard-Jones / WCA-style interactions.
`material_table`	The MaterialTable stores materials in a structure of arrays (SoA).