jaxdem.factory#

The factory registers and creates simulation components.

Classes

Factory()

Base class for components that register and create subclasses by a string key.
class jaxdem.factory.Factory#

Bases: ABC

Base class for components that register and create subclasses by a string key.

Notes

Each concrete subclass gets its own private registry. The factory normalizes keys before use: lookup is case-insensitive and ignores spaces, underscores, and hyphens ("CellList", "cell_list", and "celllist" are the same key).

Example

Use Factory as a base class for a specific component type (e.g., Foo):

>>> class Foo(Factory, ABC):
...     ...

Register a concrete subclass of Foo:

>>> @Foo.register("bar")
... class Bar(Foo):
...     ...

To create an instance of the subclass:

>>> component = Foo.create("bar")
classmethod registry_name() → str[source]#

Return the registry key of this class.

property type_name: str[source]#

Return the registry key of the class of this instance.

property metadata: dict[str, Any][source]#

Serialize the component’s dataclass fields for checkpointing and restoration.

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

Register a subclass in the factory’s registry.

This method returns a decorator that registers a class under a specific key.

Parameters:

key (str or None, optional) – The string key under which to register the subclass. If None, the method uses the lowercase subclass name as the key. The method normalizes keys (lowercase, without spaces, underscores, and hyphens), so "CellList", "cell_list", and "celllist" all denote the same key.

Returns:

A decorator that registers the class and returns it 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 for a different class, or the subclass already declares a different registry name. Registering the same class under the same key again (for example when you re-run a notebook cell) works and is idempotent.

Example

Register a class named “MyComponent” under the key “mycomp”:

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

Register a class named “DefaultComponent” using its own name as the key:

>>> @MyFactory.register()
... class DefaultComponent(MyFactory):
...     ...
classmethod create(key: str, /, **kw: Any) → RootT[source]#

Create and return an instance of a registered subclass.

This method looks up the subclass registered under the given key and calls its constructor with the provided arguments. If the subclass defines a Create method (capitalized), the factory calls that method instead of the constructor. This lets subclasses validate or preprocess arguments before the factory creates the instance.

Parameters:

  • key (str) – The registration key of the subclass to create.

  • **kw (Any) – Keyword arguments passed to the constructor of the registered subclass. Unknown names are warned about and dropped for fixed signatures.

Returns:

An instance of the registered subclass.

Return type:

T

Raises:

  • KeyError – If the factory’s registry does not contain the provided key.

  • TypeError – If required constructor arguments are missing or the selected constructor rejects an argument.

Example

Given Foo factory and Bar registered:

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