jaxdem.materials#

Interface for defining materials and the MaterialTable.

Classes

Material()

Abstract base class for defining materials.

class jaxdem.materials.Material[source]#

Bases: Factory

Abstract base class for defining materials.

Concrete subclasses of Material should define scalar or vector fields (e.g., young, poisson, mu) that represent specific physical properties of a material. These fields are then collected and managed by the MaterialTable.

Notes

  • Each field defined in a concrete Material subclass will become 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, frozen=True)
>>> class MyCustomMaterial(Material):
        ...
class jaxdem.materials.MaterialTable(props: Dict[str, jax.Array], pair: Dict[str, jax.Array], matcher: MaterialMatchmaker)[source]#

Bases: object

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

This class centralizes material data, allowing efficient access to scalar properties for individual materials and pre-calculated effective properties for material-pair interactions.

Notes

  • Scalar properties can be accessed directly using dot notation (e.g., material_table.young).

  • Effective pair properties can also be accessed directly using 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", young=1.0e4, poisson=0.3)
>>> mat2 = jdem.Material.create("elasticfrict", young=2.0e4, poisson=0.4, mu=0.5)
>>>
>>> # Create a MaterialTable using a linear matcher
>>> matcher_instance = jdem.MaterialMatchmaker.create("linear")
>>> mat_table = matcher_instance.from_materials(
>>>     [mat1, mat2],
>>>     matcher=matcher_instance
>>> )
props: Dict[str, jax.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, jax.Array]#

A dictionary mapping effective pair property names (e.g., “young_eff”, “mu_eff”) to JAX arrays. Each array has shape (M, M), representing the effective property for interactions between any two material types (M_i, M_j).

matcher: MaterialMatchmaker#

The jaxdem.MaterialMatchmaker instance that was used to compute the effective pair properties stored in the pair dictionary.

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

Constructs 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 to be used for computing effective pair properties (e.g., harmonic mean, arithmetic mean).

  • fill (float, optional) – A fill value used for material properties that are not defined in a specific Material subclass (e.g., if an Elastic material is provided when an ElasticFriction is expected, mu would be filled with 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.

class jaxdem.materials.ElasticFriction(young: float, poisson: float, mu: float)[source]#

Bases: Material

Example

>>> import jaxdem as jdem
>>> frictional_rubber = jdem.Material.create("elasticfrict", young=1.0e7, poisson=0.49, mu=0.5)
young: float#
poisson: float#
mu: float#
classmethod registry_name() str[source]#
property type_name: str[source]#
class jaxdem.materials.Elastic(young: float, poisson: float)[source]#

Bases: Material

Example

>>> import jaxdem as jdem
>>> elastic_steel = jdem.Material.create("elastic", young=2.0e11, poisson=0.3)
young: float#
poisson: float#
classmethod registry_name() str[source]#
property type_name: str[source]#

Modules

elasticMats

Implementation of some variations of elastic materials.

materialTable

The MaterialTable creates a SoA container for the materials.