jaxdem.factory

The factory defines and instantiates specific simulation components.

Classes

Factory()

Base factory class for pluggable components.

class jaxdem.factory.Factory

Bases: ABC, Generic[T]

Base factory class for pluggable components. This abstract base class provides a mechanism for registering and creating subclasses based on a string key.

Notes

Each concrete subclass gets its own private registry. Keys are strings and not case sensitive.

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 instantiate the subclass instance:

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

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

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

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

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:

T

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)