Agent

Base agent module.

This module provides the foundational Agent class that defines common functionality shared by all economic agents in the model. It includes:

1. Base Agent Interface:
2. Common attributes and methods
3. State management
4. Time series tracking

5. Market interaction protocols

6. Agent Utilities:

7. Helper functions
8. Common calculations
9. Shared behaviors

All specific agent types (households, firms, etc.) inherit from and extend this base functionality.

Agent

Base class for all economic agents in the simulation.

This class provides core functionality for economic agents, particularly focused on goods market participation and state tracking. It manages both buying and selling activities, maintaining transaction records and time series data for various economic variables.

Attributes:

Name	Type	Description
country_name	str	Country the agent belongs to
all_country_names	list[str]	All countries in the simulation
n_industries	int	Number of industries in the economy
n_transactors_sell	int	Number of selling entities for this agent
n_transactors_buy	int	Number of buying entities for this agent
states	dict[str, Any]	Current state variables for the agent
initial_states	dict[str, Any]	Initial state variables (for resets)
transactor_settings	dict[str, Any]	Settings for market transactions
transactor_buyer_states	dict	Current state for buying activities
transactor_seller_states	dict	Current state for selling activities
exchange_rate_usd_to_lcu	float	Exchange rate from USD to local currency
ts	TimeSeries	Time series data for the agent's variables

country_name = country_name instance-attribute

all_country_names = all_country_names instance-attribute

n_industries = n_industries instance-attribute

n_transactors_sell = n_transactors_sell instance-attribute

n_transactors_buy = n_transactors_buy instance-attribute

states = states instance-attribute

initial_states = deepcopy(states) instance-attribute

transactor_settings = transactor_settings if transactor_settings else {} instance-attribute

transactor_buyer_states = {} instance-attribute

transactor_seller_states = {} instance-attribute

exchange_rate_usd_to_lcu = None instance-attribute

ts = ts instance-attribute

__init__(country_name: str, all_country_names: list[str], n_industries: int, n_transactors_sell: int, n_transactors_buy: int, ts: TimeSeries, states: dict[str, Any], transactor_settings: Optional[dict[str, Any]] = None)

Initialize a new economic agent.

Parameters:

Name	Type	Description	Default
country_name	str	Country the agent belongs to	required
all_country_names	list[str]	All countries in the simulation	required
n_industries	int	Number of industries in the economy	required
n_transactors_sell	int	Number of selling entities for this agent	required
n_transactors_buy	int	Number of buying entities for this agent	required
ts	TimeSeries	Time series container for the agent's variables	required
states	dict[str, Any]	Initial state variables	required
transactor_settings	Optional[dict[str, Any]]	Settings for market transactions	None

initiate_ts() -> None

Initialize time series variables for goods market transactions.

Sets up tracking for: - Sales amounts (real and nominal) by country - Purchase amounts (real and nominal) by country - Excess demand

__str__()

Get string representation of the agent.

Returns:

Name	Type	Description
str		Agent class name and country

set_goods_to_buy(buy_init: np.ndarray) -> None

Set initial goods quantities to buy.

Parameters:

Name	Type	Description	Default
buy_init	ndarray	Initial quantities to buy	required

set_goods_to_sell(sell_init: np.ndarray) -> None

Set initial goods quantities to sell.

Parameters:

Name	Type	Description	Default
sell_init	ndarray	Initial quantities to sell	required

set_maximum_excess_demand(max_excess_demand: np.ndarray) -> None

Set maximum allowed excess demand.

Parameters:

Name	Type	Description	Default
max_excess_demand	ndarray	Maximum excess demand values	required

set_prices(sell_price: np.ndarray) -> None

Set selling prices for goods.

Parameters:

Name	Type	Description	Default
sell_price	ndarray	Prices for goods to sell	required

set_seller_industries(industries: np.ndarray) -> None

Set industry assignments for sellers.

Parameters:

Name	Type	Description	Default
industries	ndarray	Industry IDs for sellers	required

set_exchange_rate(exchange_rate_usd_to_lcu: float) -> None

Set the exchange rate from USD to local currency.

Parameters:

Name	Type	Description	Default
exchange_rate_usd_to_lcu	float	Exchange rate value	required

prepare() -> None

Prepare the agent for goods market transactions.

This method initializes all necessary states for participation in the goods market. It sets up both buying and selling states, including:

Buyer States: - Value Type: How values are interpreted (e.g., nominal vs real) - Priority: Transaction priority in the market clearing process - Remaining Goods: Copy of initial goods to track unfulfilled purchases - Nominal Amount spent: Tracks spending by industry - Real Amount bought: Tracks quantities bought by industry

Seller States: - Value Type: How values are interpreted (e.g., nominal vs real) - Priority: Transaction priority in the market clearing process - Remaining Goods: Copy of initial goods to track unsold inventory - Real Amount sold: Tracks quantities sold - Real Excess Demand: Tracks excess demand for goods

All transaction amounts are tracked separately for each country to enable detailed international trade analysis.

record(rounding: int = 16) -> None

Record current transaction states to time series.

This method processes and stores the results of goods market transactions, handling both domestic and international trade flows. It performs the following:

1. Rounds all transaction values for numerical stability:
2. Real quantities (sold, bought, excess demand)

3. Nominal amounts (spent in both USD and local currency)

4. Updates seller-side time series (if prices are set):

5. Real quantities sold (total and by destination country)
6. Nominal sales in local currency (total and by destination)

7. Excess demand tracking

8. Updates buyer-side time series:

9. Nominal amounts spent (in both USD and local currency)
10. Real quantities bought (total and by source country)

All monetary values are converted between USD and local currency using the current exchange rate. Values are stored in both currencies to facilitate both domestic and international economic analysis.

Parameters:

Name	Type	Description	Default
rounding	int	Number of decimal places for rounding. Defaults to 16. Higher precision is used to minimize cumulative rounding errors in large-scale simulations.	16

gen_reset() -> None

Reset the agent to its initial state.

Restores initial states and resets time series data.