Resource¶

Resources may be provided as plain dictionaries (default) or as instances of the optional piperabm.resource.Resource helper class. This class provides a lightweight container for resource quantities (food, water, energy) with validation and arithmetic support. It is an optional convenience wrapper; internally, PiperABM stores resources as plain dictionaries attached to NetworkX graph nodes.

from piperabm.resource import Resource

model.society.add_agent(resources=Resource(food=1, water=2, energy=3))
# An alternative to:
model.society.add_agent(resources={"food":1, "water":2, "energy":3})

# Retrive resources as a Resource object
resources = model.society.get_resources(id=0, object=True)
# Retrive resources as a dictionary
resources = model.society.get_resources(id=0)

Since the Resource class supports arithmetic operations, it can be used to easily manipulate resource quantities.

# Retrive resources as a Resource object
resources = model.society.get_resources(id=0, object=True)
resources =* 2  # Multiply all resource quantities by 2
resources =+ Resource(food=1)  # Add 1 unit of food
resources =- {"water": 1}  # Subtract 1 unit of water

class piperabm.resource.Resource(food: float = 0, water: float = 0, energy: float = 0)¶

Bases: object

Container for resource quantities used in the simulation.

The Resource class provides a lightweight, validated wrapper around the default resource types used in PiperABM (food, water, energy). It supports arithmetic operations and can be converted to a plain dictionary for storage on NetworkX graph nodes.

Notes

Internally, PiperABM stores resources as dictionaries attached directly to NetworkX graph nodes. The Resource class is provided as an optional convenience wrapper for validation, readability, and arithmetic operations.

__add__(other: dict | Resource)¶

Add resources element-wise.

Parameters:: other (dict or Resource) – Resource values to add. If a dictionary is provided, missing resource keys default to zero.
Returns:: New Resource instance containing the summed values.
Return type:: Resource
Raises:: TypeError – If other is not a dict or Resource.

__mul__(other: int | float | dict)¶

Multiply resources element-wise or by a scalar.

Parameters:: other (int, float, or dict) – Scalar multiplier or dictionary of per-resource multipliers. Missing keys in dictionaries default to 1.
Returns:: New Resource instance containing the scaled values.
Return type:: Resource
Raises:: TypeError – If other is not a supported type.

__sub__(other: dict | Resource)¶

Subtract resources element-wise.

Parameters:: other (dict or Resource) – Resource values to subtract. If a dictionary is provided, missing resource keys default to zero.
Returns:: New Resource instance containing the subtracted values.
Return type:: Resource
Raises:: TypeError – If other is not a dict or Resource.

__truediv__(other: int | float | dict)¶

Divide resources element-wise or by a scalar.

Parameters:: other (int, float, or dict) – Scalar divisor or dictionary of per-resource divisors. Missing keys in dictionaries default to 1.
Returns:: New Resource instance containing the divided values.
Return type:: Resource
Raises:: TypeError – If other is not a supported type.

serialize()¶

Convert the resource object to a dictionary.

Returns:: Dictionary representation of the resource with keys 'food', 'water', and 'energy'.
Return type:: dict