jaxdem.material#

Interface for defining materials and the MaterialTable. The MaterialTable creates a SoA container for the materials. Different material types can be used if the force laws supports them.

Classes

`Elastic`(young, poisson)	A concrete Material implementation for elastic properties.
`ElasticFriction`(young, poisson, mu)	A concrete Material implementation for elastic properties with friction.
`Material`()	Abstract base class for defining materials.
`MaterialTable`(props, pair, matcher)	A container for material properties, organized as Structures of Arrays (SoA) and pre-computed effective pair properties.

class jaxdem.material.Material[source][source]#

Bases: Factory[Material]

Abstract base class for defining materials.

Concrete subclasses of Material should define scalar 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.

classmethod create(key: str, /, **kw: Any) → T[source]#

Creates and returns an instance of a registered subclass.

This method looks up the subclass associated with the given key in the factory’s registry and then calls its constructor with the provided arguments.

Parameters:

key (str) – The registration key of the subclass to be created.
**kw (Any) – Arbitrary keyword arguments to be passed directly to the constructor of the registered subclass.

Returns:

An instance of the registered subclass.

Return type:

Raises:

KeyError – If the provided key is not found in the factory’s registry.
TypeError – If the provided **kw arguments do not match the signature of the registered subclass’s constructor.

Example

Given Foo factory and Bar registered:

>>> bar_instance = Foo.create("bar", value=42)
>>> print(bar_instance)
Bar(value=42)

classmethod register(key: str | None = None) → Callable[[Type[T]], Type[T]][source]#

Registers a subclass with the factory’s registry.

This method returns a decorator that can be applied to a class to register it under a specific key.

Parameters:: key (str or None, optional) – The string key under which to register the subclass. If None, the lowercase name of the subclass itself will be used as the key.
Returns:: A decorator function that takes a class and registers it, returning the class unchanged.
Return type:: Callable[[Type[T]], Type[T]]
Raises:: ValueError – If the provided key (or the default class name) is already registered in the factory’s registry.

Example

>>> @MyFactory.register("mycomp")
>>> class MyComponent:
>>>     ...

>>> @MyFactory.register()
>>> class DefaultComponent:
>>>     ...

class jaxdem.material.Elastic(young: float, poisson: float)[source][source]#

Bases: Material

A concrete Material implementation for elastic properties.

This material type defines properties relevant for elastic interactions, such as Young’s modulus and Poisson’s ratio.

Example

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

young: float#

poisson: float#

classmethod create(key: str, /, **kw: Any) → T[source]#

Creates and returns an instance of a registered subclass.

This method looks up the subclass associated with the given key in the factory’s registry and then calls its constructor with the provided arguments.

Parameters:

key (str) – The registration key of the subclass to be created.
**kw (Any) – Arbitrary keyword arguments to be passed directly to the constructor of the registered subclass.

Returns:

An instance of the registered subclass.

Return type:

Raises:

KeyError – If the provided key is not found in the factory’s registry.
TypeError – If the provided **kw arguments do not match the signature of the registered subclass’s constructor.

Example

Given Foo factory and Bar registered:

>>> bar_instance = Foo.create("bar", value=42)
>>> print(bar_instance)
Bar(value=42)

classmethod register(key: str | None = None) → Callable[[Type[T]], Type[T]][source]#

Registers a subclass with the factory’s registry.

This method returns a decorator that can be applied to a class to register it under a specific key.

Parameters:: key (str or None, optional) – The string key under which to register the subclass. If None, the lowercase name of the subclass itself will be used as the key.
Returns:: A decorator function that takes a class and registers it, returning the class unchanged.
Return type:: Callable[[Type[T]], Type[T]]
Raises:: ValueError – If the provided key (or the default class name) is already registered in the factory’s registry.

Example

>>> @MyFactory.register("mycomp")
>>> class MyComponent:
>>>     ...

>>> @MyFactory.register()
>>> class DefaultComponent:
>>>     ...

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

Bases: Material

A concrete Material implementation for elastic properties with friction.

This material type extends Elastic by adding a coefficient of friction, making it suitable for models that include frictional contact.

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 create(key: str, /, **kw: Any) → T[source]#

Creates and returns an instance of a registered subclass.

This method looks up the subclass associated with the given key in the factory’s registry and then calls its constructor with the provided arguments.

Parameters:

key (str) – The registration key of the subclass to be created.
**kw (Any) – Arbitrary keyword arguments to be passed directly to the constructor of the registered subclass.

Returns:

An instance of the registered subclass.

Return type:

Raises:

KeyError – If the provided key is not found in the factory’s registry.
TypeError – If the provided **kw arguments do not match the signature of the registered subclass’s constructor.

Example

Given Foo factory and Bar registered:

>>> bar_instance = Foo.create("bar", value=42)
>>> print(bar_instance)
Bar(value=42)

classmethod register(key: str | None = None) → Callable[[Type[T]], Type[T]][source]#

Registers a subclass with the factory’s registry.

This method returns a decorator that can be applied to a class to register it under a specific key.

Parameters:: key (str or None, optional) – The string key under which to register the subclass. If None, the lowercase name of the subclass itself will be used as the key.
Returns:: A decorator function that takes a class and registers it, returning the class unchanged.
Return type:: Callable[[Type[T]], Type[T]]
Raises:: ValueError – If the provided key (or the default class name) is already registered in the factory’s registry.

Example

>>> @MyFactory.register("mycomp")
>>> class MyComponent:
>>>     ...

>>> @MyFactory.register()
>>> class DefaultComponent:
>>>     ...

class jaxdem.material.MaterialTable(props: Dict[str, Array], pair: Dict[str, Array], matcher: MaterialMatchmaker)[source][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, 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), representing the effective property for interactions between any two material types (M_i, M_j).

matcher: MaterialMatchmaker#: The 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 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.