Relationship#

class bamengine.core.relationship.Relationship(source_ids, target_ids, size, capacity)[source]#

Bases: ABC

Base class for defining relationships between roles.

Relationships store edges (connections) between agents in different roles, along with edge-specific data. Internally uses COO (Coordinate List) sparse format for efficient storage and querying.

Example

Define a loan relationship between borrowers and lenders:

@relationship(source=Borrower, target=Lender, cardinality="many-to-many")
class LoanBook:
    principal: Float1D
    rate: Float1D
    interest: Float1D
    debt: Float1D
Parameters:

  • source_ids (Idx1D) – Array of source agent IDs

  • target_ids (Idx1D) – Array of target agent IDs

  • size (int) – Current number of active edges

  • capacity (int) – Maximum number of edges that can be stored

Notes

  • Edges are stored in COO format with parallel arrays

  • Empty slots are filled with sentinels (-1 for indices)

  • Subclasses define edge-specific data as additional fields

  • Query methods use NumPy operations for vectorized performance

  • The __init_subclass__ hook automatically registers relationships

name = None#
source_role = None#
target_role = None#
cardinality = 'many-to-many'#
source_ids#
target_ids#
size#
capacity#
classmethod __init_subclass__(name=None, source=None, target=None, cardinality='many-to-many', **kwargs)[source]#

Auto-register Relationship subclasses in the global registry.

This hook is called automatically when a class inherits from Relationship.

Parameters:

  • name (str, optional) – Custom name for the relationship. If not provided, uses the class name.

  • source (type[Role], optional) – Source role class for the relationship

  • target (type[Role], optional) – Target role class for the relationship

  • cardinality ({"many-to-many", "one-to-many", "many-to-one"},) – optional, default “many-to-many”, Cardinality constraint for the relationship

  • **kwargs – Additional keyword arguments passed to parent __init_subclass__.

__repr__()[source]#

Provide informative repr showing relationship metadata and state.

query_sources(source_id)[source]#

Get indices of all edges originating from a source.

Parameters:

source_id (int) – Source agent ID to query

Returns:

Array of edge indices where source_ids == source_id

Return type:

Idx1D

query_targets(target_id)[source]#

Get indices of all edges pointing to a target.

Parameters:

target_id (int) – Target agent ID to query

Returns:

Array of edge indices where target_ids == target_id

Return type:

Idx1D

aggregate_by_source(component, *, func='sum', n_sources=None, out=None)[source]#

Aggregate component values grouped by source.

Parameters:

  • component (np.ndarray) – Array of component values to aggregate (length = size)

  • func ({"sum", "mean", "count"}, default "sum") – Aggregation function

  • n_sources (int, optional) – Number of source agents (for output array size). If None, inferred from max source_id + 1.

  • out (Float1D, optional) – Pre-allocated output array

Returns:

Aggregated values per source (length = n_sources)

Return type:

Float1D

aggregate_by_target(component, *, func='sum', n_targets=None, out=None)[source]#

Aggregate component values grouped by target.

Parameters:

  • component (np.ndarray) – Array of component values to aggregate (length = size)

  • func ({"sum", "mean", "count"}, default "sum") – Aggregation function

  • n_targets (int, optional) – Number of target agents (for output array size). If None, inferred from max target_id + 1.

  • out (Float1D, optional) – Pre-allocated output array

Returns:

Aggregated values per target (length = n_targets)

Return type:

Float1D

drop_rows(mask)[source]#

Remove edges matching a boolean mask.

Parameters:

mask (np.ndarray) – Boolean array (length = size) indicating which edges to remove

Returns:

Number of edges removed

Return type:

int

purge_sources(source_ids)[source]#

Remove all edges originating from given source IDs.

Parameters:

source_ids (Idx1D) – Array of source IDs to purge

Returns:

Number of edges removed

Return type:

int

purge_targets(target_ids)[source]#

Remove all edges pointing to given target IDs.

Parameters:

target_ids (Idx1D) – Array of target IDs to purge

Returns:

Number of edges removed

Return type:

int

append_edges(source_ids, target_ids, **component_arrays)[source]#

Append new edges with given source/target IDs and component values.

Parameters:

  • source_ids (Idx1D) – Array of source IDs for new edges

  • target_ids (Idx1D) – Array of target IDs for new edges

  • **component_arrays – Component arrays (must match subclass fields)

Raises:

ValueError – If arrays have mismatched lengths or exceed capacity

__init__(source_ids, target_ids, size, capacity)#