Goods Market API Reference

This section documents the Goods Market module, which manages transactions, market clearing, and supply chains for goods across industries and countries.

macromodel.markets.goods_market.goods_market.GoodsMarket

Goods market implementation managing economic transactions.

This class implements a comprehensive goods market system that handles transactions between buyers and sellers across multiple industries and countries. It manages market clearing, supply chain relationships, and trade flows using configurable mechanisms.

The market operates in discrete steps: 1. Initialization with industry structure and participants 2. Setting of trade proportions and priorities 3. Market clearing through configured mechanism 4. Recording of transactions and supply chain updates

Attributes:

Name	Type	Description
n_industries	int	Number of industries in the economy
functions	dict[str, Any]	Market functions (clearing, etc.)
ts	TimeSeries	Time series tracking market metrics
goods_market_participants	dict[str, list[Agent]]	Market participants by country
states	dict[str, Any]	Market state variables
initial_states	dict[str, Any]	Initial market conditions
buyer_priorities	dict[str, ndarray]	Buyer priority rankings
seller_priorities	dict[str, ndarray]	Seller priority rankings
row_index	int	Index for Rest of World in country arrays

from_data(n_industries: int, configuration: GoodsMarketConfiguration, goods_market_participants: dict[str, list[Agent]], origin_trade_proportions: np.ndarray, destin_trade_proportions: np.ndarray, initial_supply_chain: Optional[SupplyChain] = None, row_index: int = -1) -> GoodsMarket classmethod

Create a goods market instance from configuration data.

Initializes a new goods market with the specified industry structure, participants, and trade relationships. Sets up the market functions, time series tracking, and initial states.

Parameters:

Name	Type	Description	Default
n_industries	int	Number of industries	required
configuration	GoodsMarketConfiguration	Market configuration	required
goods_market_participants	dict[str, list[Agent]]	Market participants	required
origin_trade_proportions	ndarray	Historical or target proportions of trade flows from origin countries. Shape: (n_countries * n_countries * n_industries). These proportions represent the share of each industry's output from each country that historically flows to each destination country. Used as a baseline for trade pattern determination. For example, if country A historically sources 30% of its steel from country B, this would be reflected in these proportions.	required
destin_trade_proportions	ndarray	Historical or target proportions of trade flows to destination countries. Shape: (n_countries * n_countries * n_industries). These proportions represent the share of each industry's imports in each destination country that historically comes from each origin country. Complements origin_trade_proportions by providing the destination country's perspective on trade patterns. For example, if 40% of country A's steel imports come from country B, this would be captured here.	required
initial_supply_chain	Optional[SupplyChain]	Initial supply chain state. If None, initializes an empty supply chain for each industry.	None
row_index	int	Rest of World index. Defaults to -1.	-1

Returns:

Name	Type	Description
GoodsMarket	GoodsMarket	Initialized goods market instance

Note

The trade proportions are reshaped into (n_countries, n_countries, n_industries) arrays where: - First dimension: Origin country - Second dimension: Destination country - Third dimension: Industry These proportions influence but do not strictly determine actual trade flows, which also depend on market clearing conditions, priorities, and other factors.

reset(configuration: GoodsMarketConfiguration)

Reset the market to its initial state.

Resets time series and states to initial conditions and updates market functions with new configuration.

Parameters:

Name	Type	Description	Default
configuration	GoodsMarketConfiguration	New market configuration	required

prepare(collect_sd: bool = True) -> None

Prepare the market for clearing.

Prepares market participants and optionally collects supply/demand data. Initializes supply chain tracking for the current period.

Parameters:

Name	Type	Description	Default
collect_sd	bool	Whether to collect supply/demand data. Defaults to True.	True

clear() -> None

Execute market clearing.

Runs the configured market clearing mechanism to match buyers with sellers and execute transactions. Updates supply chain relationships based on the resulting trades.

record() -> None

Record market outcomes.

Triggers recording of transaction outcomes for all market participants.

save_to_h5(h5_file: pd.HDFStore) -> None

Save market state to HDF5.

Saves time series data to an HDF5 file for later analysis.

Parameters:

Name	Type	Description	Default
h5_file	HDFStore	Open HDF5 file to save to	required

Value Types

macromodel.markets.goods_market.value_type.ValueType

Value type enumeration for goods market transactions.

Defines the possible value types for market transactions: - REAL: Physical quantities or real values - NOMINAL: Monetary values in current prices - NONE: Undefined or not applicable state

Clearing Mechanisms (Abstract)

macromodel.markets.goods_market.func.clearing.GoodsMarketClearer

Abstract base class for goods market clearing mechanisms.

This class defines the interface and common functionality for all market clearing implementations. It handles the matching of buyers and sellers while respecting various economic constraints and preferences.

The clearing process follows these general steps: 1. Preparation of market participants 2. Collection of supply and demand information 3. Execution of clearing algorithm 4. Recording of transactions

Attributes:

Name	Type	Description
real_country_prioritisation	float	Weight given to real countries vs ROW [0,1]
prio_high_prio_buyers	bool	Whether to prioritize high-priority buyers
prio_high_prio_sellers	bool	Whether to prioritize high-priority sellers
prio_domestic_sellers	bool	Whether to prioritize domestic sellers
probability_keeping_previous_seller	float	Chance to maintain supply chains
price_temperature	float	Price sensitivity parameter
trade_temperature	float	Trade flow sensitivity parameter
seller_selection_distribution_type	str	Method for selecting sellers
seller_minimum_fill	float	Minimum order fill rate for sellers
buyer_minimum_fill_macro	float	Minimum fill rate for macro buyers
buyer_minimum_fill_micro	float	Minimum fill rate for micro buyers
deterministic	bool	Whether to use deterministic matching
consider_trade_proportions	bool	Whether to use historical trade patterns
consider_buyer_priorities	bool	Whether to consider buyer priorities
additionally_available_factor	float	Extra capacity factor
price_markup	float	Price adjustment factor
remedy_rounding_errors	bool	Whether to fix rounding errors
allow_additional_row_exports	bool	Whether to allow extra ROW exports