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["Foo"], ABC):
>>>   ...

Register a concrete subclass of Foo:

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

To create an instance of the subclass:

>>> Foo.create("bar", **bar_kw)

classmethod registry_name() → str

Return the registry key of this class.

property type_name: str

Return the registry key of the class of this instance.

property metadata: dict[str, Any]

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

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

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. 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:
>>>     ...

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

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

classmethod create(key: str, /, **kw: Any) → RootT

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.

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 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)