Role#

class bamengine.core.role.Role[source]#

Bases: ABC

Base class for all roles (components) in the BAM-ECS architecture.

A Role is a dataclass containing NumPy arrays representing state variables for a specific aspect of agent behavior (e.g., Producer, Worker, Lender). Each array index corresponds to an agent ID.

Class Attributes:: name (str) – Role name, automatically set to class name if not provided.

Design Guidelines

All state variables should be NumPy arrays (Float, Int, Bool types)
Scratch buffers (optional fields) can be added for performance
Avoid methods that mutate state; use system functions instead
Use @role decorator for simplified role definition

Examples

Define a role using traditional syntax:

>>> from dataclasses import dataclass
>>> from bamengine.core import Role
>>> from bamengine import Float
>>> import numpy as np
>>>
>>> @dataclass(slots=True)
... class Producer(Role):
...     price: Float
...     production: Float
>>> # Producer is now auto-registered!

Define a role using the @role decorator (simplified):

>>> from bamengine import role, Float
>>>
>>> @role
... class MyRole:
...     value: Float
>>> # MyRole is now auto-registered!

Access registered roles:

>>> from bamengine.core.registry import get_role
>>> prod_cls = get_role("Producer")
>>> instance = prod_cls(
...     price=np.array([1.0, 1.2]), production=np.array([100.0, 120.0])
... )

Notes

The __init_subclass__ hook automatically registers roles in the global registry and sets the role name. This eliminates manual registration boilerplate.

For example, if there are 100 firms, Producer.price would be a 1D NumPy array of length 100, where index i corresponds to firm i.

See also

Event: Base class for events (systems) in BAM-ECS
role(): Simplified @role decorator
get_role(): Retrieve role by name

name = None#

classmethod __init_subclass__(name=None, **kwargs)[source]#

Auto-register Role subclasses in the global registry.

This hook is called automatically when a class inherits from Role. It handles role registration and name assignment.

Parameters:

name (str, optional) – Custom name for the role. If not provided, uses the class name.
**kwargs (Any) – Additional keyword arguments passed to parent __init_subclass__.

Notes

This method is called twice when using @dataclass(slots=True): once during class definition and once when dataclass creates the final class. The name preservation logic handles this correctly.

Examples

Normal usage (automatic):

>>> from bamengine.typing import Float
>>> from dataclasses import dataclass
>>> @dataclass(slots=True)
... class MyRole(Role):
...     value: Float

Custom name:

>>> @dataclass(slots=True)
... class MyRole(Role, name="CustomName"):
...     value: Float

__repr__()[source]#

Provide informative repr showing role name and field count.

Returns:: String representation in format “RoleName(fields=N)”.
Return type:: str

Examples

>>> from bamengine.roles import Producer
>>> import numpy as np
>>> prod = Producer(
...     price=np.array([1.0]),
...     production=np.array([100.0]),
...     inventory=np.array([0.0]),
...     labor_productivity=np.array([2.0]),
... )
>>> repr(prod)
'Producer(fields=4)'

__init__()#

Role#

This Page