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__()#