Society¶

class piperabm.society.Society(average_income: float = 1000, neighbor_radius: float = 0, max_time_outside: float = 28800, activity_cycle: float = 86400, transportation_resource_rates: dict = {'energy': 1.1574074074074073e-05, 'food': 2.3148148148148147e-05, 'water': 1.1574074074074073e-05}, idle_resource_rates: dict = {'energy': 2.3148148148148147e-05, 'food': 2.3148148148148147e-05, 'water': 2.3148148148148147e-05}, speed: float = 1.3888888888888888, transportation_degradation: float = 1)¶

Bases: Query, Generate, Update, Serialize, Graphics, Stat

Represent society network

accessibility(id: int) → dict¶: Calculate accessibility for all resources

accessibility_resource(id: int, name: str)¶: Calculate accessibility for certain resource

add_agent(home_id: int = None, id: int = None, name: str = '', socioeconomic_status: float = 1, resources: dict | ~piperabm.resource.Resource = <piperabm.resource.Resource object>, enough_resources: dict | ~piperabm.resource.Resource | None = None, balance: float = 0)¶

Add an agent node to the society network.

Agents are represented as nodes in the society graph. Each agent is assigned to a home node in the infrastructure and initialized with resources and a balance. When an agent is added, family and neighbor relationships may be created automatically based on the agent’s home assignment.

Parameters:

home_id (int, optional) – ID of the home node that the agent belongs to. If None, a home is chosen at random from existing infrastructure homes.
id (int, optional) – Unique identifier of the agent node. If None, a unique ID is automatically generated. If the provided ID already exists, a new unique ID is generated instead (the existing agent is not overwritten).
name (str, optional) – Optional human-readable name for the agent.
socioeconomic_status (float, optional) – Socioeconomic status of the agent (used by the decision-making and/or behavior models). Defaults to 1.
resources (dict or Resource, optional) – Initial resource inventory for the agent. This can be provided either as a dictionary (e.g., {'food': 10, 'water': 10, 'energy': 10}) or as a piperabm.Resource instance. If a Resource object is provided, it is converted internally to a dictionary before being attached to the underlying graph representation.
enough_resources (dict or Resource or None, optional) – The per-resource “enough” thresholds used by the agent’s satisfaction/utility model. If provided as a Resource object, it is converted internally to a dictionary. If None, the system initializes the threshold for each resource to match the corresponding initial resources value.
balance (float, optional) – Initial monetary balance of the agent. Defaults to 0.

Returns:

The ID of the newly added agent node.

Return type:

int

Raises:

ModelNotBakedError – If the infrastructure has not been baked. Agents require a finalized infrastructure network (via bake()) to ensure physically consistent routing and access edges.

Notes

Internally, agent state (including resources and thresholds) is stored as plain attributes on the NetworkX society graph. The piperabm.Resource class is provided as an optional convenience wrapper for validation/readability and does not change the internal representation.

add_family(id_1: int, id_2: int)¶

Add a family relationship edge between two agents.

A family relationship is created automatically when two distinct agents are assigned to the same home. This method adds a family-typed edge between the two agent nodes in the society graph, provided that both agents share the same home_id.

Parameters:

id_1 (int) – ID of the first agent.
id_2 (int) – ID of the second agent.

Notes

A family edge is only added if id_1 and id_2 are different agents and both are associated with the same home node.
The edge is stored in the underlying NetworkX multi-graph with type='family' and includes the shared home_id as an edge attribute.
If the agents do not share the same home, no edge is added and the method exits silently.