ConsumersFinalizePurchases

class bamengine.events.goods_market.ConsumersFinalizePurchases

Bases: Event

Return unspent budget to savings after shopping rounds complete.

Any budget remaining after all shopping rounds is moved back to savings. This ensures wealth conservation: no money is lost during shopping.

Algorithm

For each consumer j:

\[ \begin{align}\begin{aligned}SA_j \leftarrow SA_j + B_j\\B_j \leftarrow 0\end{aligned}\end{align} \]

where \(SA_j\) = savings, \(B_j\) = income_to_spend (remaining budget).

Examples

>>> import bamengine as be
>>> sim = be.Simulation.init(n_households=500, seed=42)
>>> # Shop first
>>> sim.get_event("goods_market_round")().execute(sim)
>>> # Track unspent
>>> unspent = sim.con.income_to_spend.copy()
>>> initial_savings = sim.con.savings.copy()
>>> # Finalize
>>> event = sim.get_event("consumers_finalize_purchases")
>>> event.execute(sim)

Verify unspent returned to savings:

>>> import numpy as np
>>> np.allclose(sim.con.savings, initial_savings + unspent)
True

Budget cleared:

>>> (sim.con.income_to_spend == 0).all()
True

Notes

This event must execute after GoodsMarketRound completes.

Wealth conservation: unspent budget → savings (no money vanishes).

Consumers with zero unspent budget are unaffected (savings unchanged).

See also

GoodsMarketRound

Spends budget during shopping

ConsumersDecideIncomeToSpend

Initially allocates budget from wealth

bamengine.events._internal.goods_market.consumers_finalize_purchases

Implementation

execute(sim)

Execute the event’s logic.

Mutates simulation state in-place. This method must be implemented by all Event subclasses.

Parameters:

sim (Simulation) – The simulation instance containing all state and configuration.

Returns:

All mutations are in-place.

Return type:

None

Examples

Implement execute in a custom event:

>>> from bamengine import event, ops
>>>
>>> @event
... class CustomPricingEvent:
...     def execute(self, sim):
...         prod = sim.get_role("Producer")
...         # Apply 10% markup to all prices
...         new_prices = ops.multiply(prod.price, 1.1)
...         ops.assign(prod.price, new_prices)

Access configuration and RNG:

>>> @event
... class StochasticEvent:
...     def execute(self, sim):
...         shock = sim.config.h_rho
...         random_values = sim.rng.uniform(0, shock, size=sim.n_firms)
...         # Use random_values in calculations

Notes

The execute method receives full Simulation access, including: - All roles: sim.get_role(“RoleName”) or sim.prod, sim.wrk, etc. - Configuration: sim.config - RNG: sim.rng - Economy state: sim.ec

__init__()

name = 'consumers_finalize_purchases'