Credit Market API Reference

This section documents the Credit Market module, which manages lending, loan servicing, and credit allocation between banks, firms, and households.

macromodel.markets.credit_market.credit_market.CreditMarket

Credit market implementation managing lending relationships and loan lifecycles.

This class implements the core credit market functionality, managing the interactions between financial institutions (banks) and borrowers (firms and households). It handles loan origination, servicing, repayment, and default processes.

The market maintains state information about all outstanding loans including: - Principal amounts - Interest rates - Payment schedules - Default status

Loan types are tracked in separate arrays with dimensions [3, n_banks, n_borrowers]: - Index 0: Outstanding principal - Index 1: Interest rate - Index 2: Monthly payment amount

Attributes:

Name	Type	Description
country_name	str	Name of the country this market operates in
functions	dict[str, Any]	Market functions (clearing, pricing, etc.)
ts	TimeSeries	Time series tracking market metrics
states	dict[str, ndarray]	Current state of all loans
initial_states	dict[str, ndarray]	Initial state snapshot for resets

Example

market = CreditMarket.from_data( ... country_name="USA", ... st_loans=short_term_loan_data, ... lt_loans=long_term_loan_data, ... cons_loans=consumer_loan_data, ... mort_loans=mortgage_loan_data ... ) market.clear(banks, firms, households, npl_firm=0.02, npl_cons=0.03, npl_mort=0.01)

from_pickled_market(synthetic_credit_market: SyntheticCreditMarket, credit_market_configuration: CreditMarketConfiguration, country_name: str) -> 'CreditMarket' classmethod

Create a credit market instance from a pickled synthetic market.

This factory method initializes a credit market from preprocessed synthetic data, which includes historical loan data and market configuration parameters.

Parameters:

Name	Type	Description	Default
synthetic_credit_market	SyntheticCreditMarket	Preprocessed market data	required
credit_market_configuration	CreditMarketConfiguration	Market parameters	required
country_name	str	Name of the country this market operates in	required

Returns:

Name	Type	Description
CreditMarket	'CreditMarket'	Initialized credit market instance with historical data

Note

The synthetic market data includes: - Historical loan volumes by type - Default rates and loss history - Interest rate patterns - Bank-borrower relationships

from_data(country_name: str, st_loans: np.ndarray, lt_loans: np.ndarray, cons_loans: np.ndarray, mort_loans: np.ndarray) -> 'CreditMarket' classmethod

Create a credit market instance directly from loan data arrays.

This factory method provides a simpler way to initialize a credit market when you have direct access to loan data arrays rather than a synthetic market.

Parameters:

Name	Type	Description	Default
country_name	str	Name of the country this market operates in	required
st_loans	ndarray	Short-term loan data [3, n_banks, n_firms]	required
lt_loans	ndarray	Long-term loan data [3, n_banks, n_firms]	required
cons_loans	ndarray	Consumer loan data [3, n_banks, n_households]	required
mort_loans	ndarray	Mortgage loan data [3, n_banks, n_households]	required

Returns:

Name	Type	Description
CreditMarket	'CreditMarket'	Initialized credit market instance

Note

Each loan array has shape [3, n_banks, n_borrowers] where: - Index 0: Outstanding principal - Index 1: Interest rate - Index 2: Monthly payment amount

reset(configuration: CreditMarketConfiguration) -> None

Reset the credit market to its initial state.

Restores all loan states to their initial values and updates market functions with the new configuration. This is useful for running multiple simulations or testing different scenarios.

Parameters:

Name	Type	Description	Default
configuration	CreditMarketConfiguration	New market configuration to use	required

clear(banks: Banks, firms: Firms, households: Households, current_npl_firm_loans: float, current_npl_hh_cons_loans: float, current_npl_mortgages: float) -> None

Clear the credit market by matching loan supply with demand.

This is the core market clearing function that: 1. Evaluates new loan applications 2. Determines credit allocation 3. Updates loan states 4. Records lending activity

The clearing process considers: - Bank lending capacity and risk appetite - Borrower creditworthiness - Current NPL rates - Market conditions

Parameters:

Name	Type	Description	Default
banks	Banks	Banking sector agent	required
firms	Firms	Corporate sector agents	required
households	Households	Household sector agents	required
current_npl_firm_loans	float	Current NPL rate for firm loans	required
current_npl_hh_cons_loans	float	Current NPL rate for consumer loans	required
current_npl_mortgages	float	Current NPL rate for mortgages	required

Note

The function updates various time series metrics including: - New loan originations by type - Outstanding loan balances - Bank portfolio composition

pay_firm_installments() -> np.ndarray

Process firm loan payments for the current period.

Processes monthly payments for both short-term and long-term firm loans. The payment amount is the minimum of the scheduled payment and outstanding balance.

Returns:

Type	Description
ndarray	np.ndarray: Array of total payments made by each firm

pay_household_installments() -> np.ndarray

Process household loan payments for the current period.

Processes monthly payments for both consumer loans and mortgages. The payment amount is the minimum of the scheduled payment and outstanding balance.

Returns:

Type	Description
ndarray	np.ndarray: Array of total payments made by each household

remove_repaid_loans() -> None

Clean up fully repaid loans from the market state.

Identifies loans with near-zero balances (accounting for numerical precision) and removes them from the market state by zeroing out all their attributes.

compute_aggregates() -> None

Update aggregate loan statistics.

Calculates and records total outstanding loan amounts by type: - Short-term firm loans - Long-term firm loans - Consumer loans - Mortgages

compute_outstanding_short_term_loans_by_firm() -> np.ndarray

Calculate total short-term loans for each firm.

Returns:

Type	Description
ndarray	np.ndarray: Array of total short-term loan balances by firm

compute_outstanding_long_term_loans_by_firm() -> np.ndarray

Calculate total long-term loans for each firm.

Returns:

Type	Description
ndarray	np.ndarray: Array of total long-term loan balances by firm

compute_outstanding_consumption_loans_by_household() -> np.ndarray

Calculate total consumer loans for each household.

Returns:

Type	Description
ndarray	np.ndarray: Array of total consumer loan balances by household

compute_outstanding_mortgages_by_household() -> np.ndarray

Calculate total mortgage loans for each household.

Returns:

Type	Description
ndarray	np.ndarray: Array of total mortgage balances by household

compute_outstanding_loans_by_bank() -> np.ndarray

Calculate total loans outstanding for each bank.

Returns:

Type	Description
ndarray	np.ndarray: Array of total loan balances by bank across all loan types

compute_interest_paid_by_firm() -> np.ndarray

Calculate total interest paid by each firm.

Returns:

Type	Description
ndarray	np.ndarray: Array of interest payments by firm across all loan types

compute_interest_paid_by_household() -> np.ndarray

Calculate total interest paid by each household.

Returns:

Type	Description
ndarray	np.ndarray: Array of interest payments by household across all loan types

compute_interest_received_by_bank() -> np.ndarray

Calculate total interest received by each bank.

Returns:

Type	Description
ndarray	np.ndarray: Array of interest income by bank across all loan types

remove_loans_to_firm(firm_id: int | np.ndarray) -> float

Remove all loans associated with specified firm(s).

Used when firms default or exit the market. Returns the total amount written off.

Parameters:

Name	Type	Description	Default
firm_id	int | ndarray	ID(s) of firm(s) to remove loans for	required

Returns:

Name	Type	Description
float	float	Total amount of loans written off

remove_loans_to_households(household_id: int | np.ndarray) -> Tuple[float, float]

Remove all loans associated with specified household(s).

Used when households default. Returns the total amounts written off by loan type.

Parameters:

Name	Type	Description	Default
household_id	int | ndarray	ID(s) of household(s) to remove loans for	required

Returns:

Type	Description
Tuple[float, float]	Tuple[float, float]: Total consumer loans and mortgages written off

remove_loans_by_bank(bank_id: int | np.ndarray) -> None

Remove all loans associated with specified bank(s).

Used when banks fail or exit the market.

Parameters:

Name	Type	Description	Default
bank_id	int | ndarray	ID(s) of bank(s) to remove loans for	required

save_to_h5(group: h5py.Group)

Save credit market state to HDF5 file.

Parameters:

Name	Type	Description	Default
group	Group	HDF5 group to save data to	required

Loan Types

macromodel.markets.credit_market.types_of_loans.LoanTypes

Enumeration of available loan types in the credit market.

Each loan type represents a distinct lending product with its own: - Target borrower (firms vs households) - Purpose (working capital, investment, consumption, housing) - Risk profile - Typical terms and conditions

Attributes:

Name	Type	Description
FIRM_SHORT_TERM_LOAN	int	Working capital and operational loans to firms
FIRM_LONG_TERM_LOAN	int	Capital investment loans to firms
HOUSEHOLD_CONSUMPTION_LOAN	int	Personal loans to households
MORTGAGE	int	Home purchase/refinance loans to households

Example

loan_type = LoanTypes.MORTGAGE if loan_type == LoanTypes.MORTGAGE: ... interest_rate = base_rate + mortgage_spread

Clearing Mechanisms (Abstract)

macromodel.markets.credit_market.func.clearing.CreditMarketClearer

Abstract base class for credit market clearing mechanisms.

This class defines the interface and common functionality for all credit market clearing implementations. It handles the matching of lenders (banks) with borrowers (firms and households) while respecting various financial constraints and regulatory requirements.

The clearing process follows these general steps: 1. Assessment of bank lending capacity 2. Evaluation of borrower creditworthiness 3. Interest rate determination 4. Loan allocation and origination

Attributes:

Name	Type	Description
allow_short_term_firm_loans	bool	Whether to allow short-term lending to firms
allow_household_loans	bool	Whether to allow lending to households
firms_max_number_of_banks_visiting	int	Max banks a firm can approach
households_max_number_of_banks_visiting	int	Max banks a household can approach
consider_loan_type_fractions	bool	Whether to use loan type preferences
credit_supply_temperature	float	Sensitivity to NPL rates in supply
interest_rates_selection_temperature	float	Rate sensitivity in matching
creditor_selection_is_deterministic	bool	Whether to use deterministic matching
creditor_minimum_fill	bool	Whether to enforce minimum lending amounts
debtor_minimum_fill	bool	Whether to enforce minimum borrowing amounts