goods_market#

Goods market events for consumption decisions and shopping.

This module defines the goods market phase events that execute after production. Households calculate consumption propensity, allocate income to spending, select firms to visit, and purchase goods through sequential shopping.

Event Sequence#

The goods market events execute in this order:

  1. ConsumersCalcPropensity - Calculate propensity to consume based on savings

  2. ConsumersDecideIncomeToSpend - Allocate income to spending budget

  3. ConsumersDecideFirmsToVisit - Select firms to visit (sorted by price)

  4. GoodsMarketRound - Batch-sequential shopping (handles all Z rounds internally)

  5. ConsumersFinalizePurchases - Move unspent budget back to savings

Design Notes#

  • Events operate on consumer and producer roles (Consumer, Producer)

  • Propensity to consume: c = 1 / (1 + tanh(SA/SA_avg)^β)

  • Loyalty rule: consumers visit previous largest producer first (if inventory available)

  • Remaining Z-1 firms selected randomly (preferential attachment mechanism)

  • Batch-sequential processing: consumers are shuffled and divided into batches, each completing all Z visits before the next batch starts, preserving sequential depletion dynamics while using vectorized NumPy operations within each batch

Examples

Execute goods market events:

>>> import bamengine as be
>>> sim = be.Simulation.init(n_firms=100, n_households=500, seed=42)
>>> # Goods market events run as part of default pipeline
>>> sim.step()

Execute individual goods market event:

>>> event = sim.get_event("consumers_calc_propensity")
>>> event.execute(sim)
>>> sim.con.propensity.mean()
0.65

Check consumption:

>>> total_spent = sim.con.total_spent.sum()
>>> total_spent
2850.0

See also

bamengine.events._internal.goods_market

System function implementations

Consumer

Consumption state

Producer

Production state with inventory

Event Classes#

ConsumersCalcPropensity

Calculate marginal propensity to consume based on relative savings.

ConsumersDecideIncomeToSpend

Allocate wealth to spending budget based on propensity to consume.

ConsumersDecideFirmsToVisit

Consumers select firms to visit and set loyalty BEFORE shopping.

GoodsMarketRound

Sequential goods market matching.

ConsumersFinalizePurchases

Return unspent budget to savings after shopping rounds complete.