ConsumersDecideIncomeToSpend#

class bamengine.events.goods_market.ConsumersDecideIncomeToSpend[source]#

Bases: Event

Allocate wealth to spending budget based on propensity to consume.

Consumers combine their savings and income into total wealth, then allocate a portion to spending based on their propensity. The remainder stays as savings.

Algorithm

For each consumer j:

  1. Calculate wealth: \(W_j = SA_j + I_j\)

  2. Allocate to spending: \(B_j = W_j \times c_j\)

  3. Update savings: \(SA_j = W_j - B_j\)

  4. Reset income: \(I_j = 0\)

Mathematical Notation

\[ \begin{align}\begin{aligned}W_j = SA_j + I_j\\B_j = W_j \times c_j\\SA_j = W_j - B_j = W_j(1 - c_j)\\I_j \leftarrow 0\end{aligned}\end{align} \]

Examples

>>> import bamengine as be
>>> sim = be.Simulation.init(n_households=500, seed=42)
>>> # First set propensity
>>> sim.get_event("consumers_calc_propensity")().execute(sim)
>>> # Then allocate spending
>>> initial_wealth = sim.con.savings + sim.con.income
>>> event = sim.get_event("consumers_decide_income_to_spend")
>>> event.execute(sim)

Check spending budget:

>>> sim.con.income_to_spend.sum()
2950.0

Verify wealth conservation:

>>> import numpy as np
>>> final_wealth = sim.con.savings + sim.con.income_to_spend
>>> np.allclose(initial_wealth, final_wealth)
True

Income reset:

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

Notes

This event must execute after ConsumersCalcPropensity (need propensity values).

Wealth is conserved: initial_wealth = final_savings + spending_budget.

Income is reset to 0 after allocation (will accumulate again next period).

See also

ConsumersCalcPropensity

Calculates propensity used for allocation

GoodsMarketRound

Uses income_to_spend as shopping budget

bamengine.events._internal.goods_market.consumers_decide_income_to_spend

Implementation

execute(sim)[source]#

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_decide_income_to_spend'#