Agent-Based Model Module¶

This module implements agent-based modeling techniques for simulating bank behaviors during stress scenarios.

BankAgent¶

Bank agent implementation for financial network simulations.

This module provides the BankAgent class which represents a bank in the agent-based model and implements its decision-making behaviors.

class scr_financial.abm.bank_agent.BankAgent(bank_id, initial_state, decision_model=None, stochastic=True)[source]¶

Bases: object

Represents a bank in the agent-based model.

Parameters:

bank_id (str) – Unique identifier for the bank.
initial_state (dict) – Dictionary containing initial bank attributes.
decision_model (object, optional) – Decision model to use for agent behavior, by default DefaultDecisionModel().
stochastic (bool) – Enable Ornstein-Uhlenbeck noise on regulatory ratios each step.

id¶

Bank identifier.

Type:: str

state¶

Current state of the bank.

Type:: dict

connections¶

Dictionary of connections to other banks.

Type:: dict

memory¶

List of past states (capped at memory_length entries).

Type:: list

memory_length¶

Maximum number of past states to remember (default 10).

Type:: int

__init__(bank_id, initial_state, decision_model=None, stochastic=True)[source]¶

Initialize a bank agent with an ID and initial state.

Parameters:

bank_id (str)
initial_state (Dict[str, Any])
decision_model (object | None)
stochastic (bool)

evolve_ratios(rng, dt=1.0)[source]¶

Apply one discrete Ornstein-Uhlenbeck step to CET1, LCR, NSFR.

dx = theta*(mu - x)*dt + sigma*sqrt(dt)*N(0,1)

Parameters:

rng (Generator)
dt (float)

Return type:

None

apply_counterparty_loss(loss_amount)[source]¶

Apply a credit loss from a defaulted counterparty.

Reduces interbank_assets, CET1 proportionally, and cash.

Parameters:: loss_amount (float)
Return type:: None

is_defaulted()[source]¶

Bank is in default if CET1 < 0 or cash < 0.

Return type:: bool

freeze()[source]¶

Mark bank as defaulted — no further lending/evolution.

Return type:: None

update_state(new_state)[source]¶

Update the bank’s state with new information.

Parameters:: new_state (dict) – Dictionary containing updated attributes
Return type:: None

assess_solvency()[source]¶

Determine if the bank is solvent based on capital ratios.

Returns:: True if the bank is solvent, False otherwise
Return type:: bool

assess_liquidity()[source]¶

Determine if the bank has adequate liquidity.

Returns:: True if the bank has adequate liquidity, False otherwise
Return type:: bool

calculate_lending_capacity()[source]¶

Calculate how much the bank can lend to other banks.

Returns:: Lending capacity in currency units
Return type:: float

decide_lending_action(potential_borrowers, market_sentiment)[source]¶

Decide lending actions based on current state and market conditions.

Parameters:

potential_borrowers (dict) – Dictionary mapping bank IDs to their states
market_sentiment (float) – Market sentiment indicator (0-1 scale, 1 being positive)

Returns:

Dictionary containing lending decisions

Return type:

dict

decide_borrowing_action(potential_lenders, market_sentiment)[source]¶

Decide borrowing actions based on current state and market conditions.

Parameters:

potential_lenders (dict) – Dictionary mapping bank IDs to their states
market_sentiment (float) – Market sentiment indicator (0-1 scale, 1 being positive)

Returns:

Dictionary containing borrowing decisions

Return type:

dict

respond_to_shock(shock_params)[source]¶

Respond to an external shock.

Parameters:: shock_params (dict) – Dictionary containing shock parameters
Returns:: Dictionary containing response actions
Return type:: dict

update_connections(bank_id, weight)[source]¶

Update connection strength with another bank.

Parameters:

bank_id (str) – Identifier of the connected bank
weight (float) – New connection weight

Return type:

None

get_connection_strength(bank_id)[source]¶

Get connection strength with another bank.

Parameters:: bank_id (str) – Identifier of the connected bank
Returns:: Connection strength
Return type:: float

BankingSystemSimulation¶

Banking system simulation for financial network analysis.

This module provides the BankingSystemSimulation class for simulating interbank lending and contagion dynamics.

class scr_financial.abm.simulation.BankingSystemSimulation(bank_data, network_data, system_indicators, stochastic=True, seed=None)[source]¶

Bases: object

Implements the agent-based simulation engine.

Parameters:

bank_data (dict) – Dictionary mapping bank IDs to their initial states
network_data (dict) – Dictionary representing the network structure
system_indicators (dict) – Dictionary of system-wide indicators
stochastic (bool)
seed (int | None)

banks¶

Dictionary of bank agents

Type:: dict

network¶

Current network structure

Type:: dict

time¶

Current simulation time

Type:: int

history¶

History of system states

Type:: list

__init__(bank_data, network_data, system_indicators, stochastic=True, seed=None)[source]¶

Initialize the simulation with bank data, network data, and system indicators.

Parameters:

bank_data (Dict[str, Dict[str, Any]])
network_data (Dict[str, Dict[str, float]])
system_indicators (Dict[str, Any])
stochastic (bool)
seed (int | None)

calculate_market_sentiment()[source]¶

Calculate overall market sentiment based on system indicators.

Returns:: Market sentiment (0-1 scale, 1 being positive)
Return type:: float

apply_external_shock(shock_params)[source]¶

Apply an external shock to the system.

Parameters:: shock_params (dict) – Dictionary containing shock parameters
Return type:: None

simulate_interbank_lending()[source]¶

Simulate one round of interbank lending decisions.

Return type:: None

update_network()[source]¶

Update network data based on current bank connections.

Return type:: None

run_simulation(steps, shocks=None)[source]¶

Run the simulation for a specified number of steps.

Parameters:

steps (int) – Number of simulation steps
shocks (dict, optional) – Dictionary mapping time steps to shock parameters

Returns:

History of system states

Return type:

list

record_state()[source]¶

Record the current state of the system.

Return type:: None

reset()[source]¶

Reset the simulation to its initial state.

Clears history, resets time to 0, and re-initialises every bank’s state from the bank_data passed at construction. Network connections are also restored from the original network_data.

Return type:: None

get_adjacency_matrix()[source]¶

Get the adjacency matrix of the current network.

Returns:: Adjacency matrix
Return type:: numpy.ndarray

get_bank_metrics()[source]¶

Get current metrics for all banks.

Returns:: DataFrame containing bank metrics
Return type:: pandas.DataFrame

get_system_metrics()[source]¶

Get current system-wide metrics.

Returns:: Dictionary of system metrics
Return type:: dict

Decision Models¶

Decision models for bank agents in financial network simulations.

This module provides various decision-making models that determine how bank agents behave in different scenarios.

class scr_financial.abm.decision_models.DefaultDecisionModel[source]¶

Bases: object

Default decision model for bank agents.

Implements simple rule-based decision making for lending, borrowing, and responding to shocks.

__init__()[source]¶

Initialise the default decision model.

Return type:: None

decide_lending_action(bank, potential_borrowers, market_sentiment)[source]¶

Decide lending actions based on current state and market conditions.

Parameters:

bank (BankAgent) – The bank agent making the decision
potential_borrowers (dict) – Dictionary mapping bank IDs to their states
market_sentiment (float) – Market sentiment indicator (0-1 scale, 1 being positive)

Returns:

Dictionary containing lending decisions

Return type:

dict

decide_borrowing_action(bank, potential_lenders, market_sentiment)[source]¶

Decide borrowing actions based on current state and market conditions.

Parameters:

bank (BankAgent) – The bank agent making the decision
potential_lenders (dict) – Dictionary mapping bank IDs to their states
market_sentiment (float) – Market sentiment indicator (0-1 scale, 1 being positive)

Returns:

Dictionary containing borrowing decisions

Return type:

dict

respond_to_shock(bank, shock_params)[source]¶

Respond to an external shock.

Parameters:

bank (BankAgent) – The bank agent responding to the shock
shock_params (dict) – Dictionary containing shock parameters

Returns:

Dictionary containing response actions

Return type:

dict

class scr_financial.abm.decision_models.StressDecisionModel[source]¶

Bases: DefaultDecisionModel

Decision model for bank agents during stress scenarios.

This model extends the default model with more conservative behavior during market stress.

decide_lending_action(bank, potential_borrowers, market_sentiment)[source]¶

More conservative lending during stress.

Parameters:

potential_borrowers (Dict[str, Dict[str, Any]])
market_sentiment (float)

Return type:

Dict[str, Any]

respond_to_shock(bank, shock_params)[source]¶

More aggressive response to shocks.

Parameters:: shock_params (Dict[str, Any])
Return type:: Dict[str, Any]

class scr_financial.abm.decision_models.LearningDecisionModel(learning_rate=0.1)[source]¶

Bases: DefaultDecisionModel

Decision model that learns from past interactions.

This model extends the default model with learning capabilities based on past interactions with other banks.

Parameters:: learning_rate (float)

__init__(learning_rate=0.1)[source]¶

Initialise the learning decision model.

Parameters:: learning_rate (float) – Weight given to each new outcome when updating interaction scores. Must be in (0, 1]. Defaults to 0.1.
Return type:: None

decide_lending_action(bank, potential_borrowers, market_sentiment)[source]¶

Lending decisions influenced by past interactions.

Parameters:

potential_borrowers (Dict[str, Dict[str, Any]])
market_sentiment (float)

Return type:

Dict[str, Any]

update_interaction_score(lender_id, borrower_id, outcome)[source]¶

Update interaction score based on outcome.

Parameters:

lender_id (str) – ID of the lending bank
borrower_id (str) – ID of the borrowing bank
outcome (float) – Outcome score (-1 to 1, where 1 is positive)

Return type:

None

get_interaction_score(lender_id, borrower_id)[source]¶

Get interaction score between two banks.

Parameters:

lender_id (str) – ID of the lending bank
borrower_id (str) – ID of the borrowing bank

Returns:

Interaction score (-1 to 1, where 1 is positive)

Return type:

float