Model

class piperabm.Model(name: str = '', prices: dict = {'energy': 1, 'food': 1, 'water': 1}, path=None, seed: int = None)

Bases: Serialize, File, Update, Graphics

Main class of simulation.

Parameters:

  • name (str, optional) – A label to distinguish this model and its results when running multiple instances. In single runs, this can left empty.

  • prices (dict, optional) – Mapping of resource names to unit costs. FEWS Nexus framework expects ‘food’, ‘water’, ‘energy’.

  • path (str, optional) – Directory for saving/loading simulation.

  • seed (int, optional) – Integer seed for reproducibility.

animate()
append_delta(delta) → None

Append the new delta to file

append_transactions(transactions) → None

Append the new delta to file

apply_delta(delta) → None

Update model by applying a delta

apply_deltas(deltas: list = None) → None

Update model by applying all deltas

bake(save: bool = False, proximity_radius: float = 2.220446049250313e-16, search_radius: float = None, report: bool = False)

Prepare the model for the first simulation step. This will generate nodes/edges, and compute any necessary initial calculations to create a physically sensinble network.

Parameters:

  • save (bool, default=False) – If True, immediately serialize the infrastructure state to disk.

  • proximity_radius (float, default=0) – The grammar rules use this value (in model units) to determine how close the elements should be to each other to impact each other, such as getting merged or split.

  • search_radius (float or None, default=None) – Home and market nodes need to get connected to the street network. This is done using “Neighborhood access” edges. The grammar rule for this process is computationally expensive therefore setting a search radius can speed up the process specially in large and intricate networks. If set to None, all possible elements are network are evaluated.

  • report (bool, default=False) – If True, reports the steps taken during the baking process, which can be useful for debugging or understanding the model.

property baked

Return whether the model is baked or not.

deserialize(data: dict) → None

Deserialize

deserialize_state(state)

Deserialize numpy random generator state

fig(relationships=False, clf=True)

Add model elements to plt fig ax

load(name: str) → None

Load model from file

load_deltas(_from: int = None, _to: int = None) → list

Load all detlas from file

load_final() → None

Load final state of model from file

load_initial() → None

Load initial state of model from file

push(steps: int = 1) → None

Push model forward using deltas

property resource_names

Return name of resources in the model.

property result_directory

Return result directory

run(n: int = None, step_size: float = 3600, save: bool = False, save_transactions: bool = False, resume: bool = False, report: bool = False)

Run model for multiple steps.

Parameters:

  • n (int or None) – Number of steps to run the model. If set to None, model keeps running until no agents remain alive in the society.

  • step_size (float) – Time increment for each step (e.g. seconds). If set to large values, the model runs faster but the model may not be able to capture some of the interactions.

  • save (bool) – If True, saves the results buy serializing state snapshots and creating deltas and recording them to disk. The initial state of model (named initial.json), the final state of the model (named final.json) as well as the changes (deltas) during each step (named simulation.json) can be found in the result folder in the working directory.

  • save_transactions (bool) – If True, record all transactions to disk. The file will be named transaction.csv and will be located in the result folder in the working directory.

  • resume (bool) – If True, attempt to resume from last saved state instead of starting fresh.

  • report (bool) – If True, print progress for n-step runs.

save(name: str) → None

Save model to file

save_final() → None

Save final state of model to file

save_initial() → None

Save initial state of model to file

serialize() → dict

Serialize

serialize_state()

Serialize numpy random generator state

set_seed(seed: int = None)

Set random generator seed for result reproducability.

show(relationships=False)

Show model elements

trade(agents: list = [], markets: list = [])

Trade

type = 'model'
update(duration: float, save: bool = False, save_transactions: bool = False)

Update model for a single step.

Steps performed: 1. (If save) snapshot current state for delta comparison. 2. Execute trades in each market and household. 3. Update agent behaviors and infrastructure effects. 4. Reset market balances and refill resources. 5. Increment time and step counters. 6. (If save) compute & append state delta, save final state. 7. (If save_transactions) append transaction list to log.