In this tutorial, you will learn how to build a more complex model than the simple trading model demonstrated in the introductory tutorial. You will also be taught some more advanced modelling concepts and explore best practices for the iterative development of models.
\nThe model is a simulation of a commercial bank's mortgage portfolio. Mortgages are lent to households, who are hit by income shocks, earn income, pay taxes, consume, and attempt to repay their mortgage. Households who are unable to make their repayments eventually default on their mortgage, and the mortgage contract is written off the bank's balance sheet.
\nThis tutorial is divided into three parts. This reflects the iterative nature of building agent-based models. When we are done, we should have the below model displayed on the console.
\nThe code for this tutorial is available as a zip download, containing a complete model as a Maven project. This project should be able to be run from any Maven or Java IDE environment.
\n\n\n MortgageModel.java The Bank class describes stylised data and behaviours of a commercial bank. In this skeleton model, the bank's balance sheet is comprised of debt, assets and equity, which is calculated as assets minus debt. The bank updates its assets in line with the sum of mortgage repayments it receives. Bank.java The Household class describes the stylised data and behaviours of a household with a mortgage. In the skeleton model, the household earns income, consumes, and compares its stock of wealth with its required mortgage repayment. If it can afford to pay its mortgage, the household sends a message to the bank containing its mortgage repayment. Household.java In this iteration of the model, we have introduced a more extensive set of agent behaviours -- as described by the two sequences at the bottom of the MortgageModel class. Households actively apply for mortgages, and Banks check that a mortgage application meets certain requirements before issuing it. Significantly more output is reported to the console. In this stage of model development, it is useful to track a large number of variables to ensure that the model is generating sensible intermediate and final outputs. The other significant change in this version, compared to the last version, is the collection of the messages together inside an object (Messages). This is a stylistic choice, but one we recommend as a best practice -- see Class Organisation. MortgageModel.java Relative to the last version, the bank's behaviour is significantly more complicated. The bank has new methods for processing mortgage applications, processing arrears, and cumulating impairments. A final method ( Bank.java Similarly, the behaviour of the household has also been made more complex than in the skeleton version. The households have additional methods which capture behaviours to do with applying for and taking out a mortgage. A simple class is also included to reflect a mortgage contract. Household.java The final version of the model introduces additional features to ensure that it is a more accurate reflection of the system we are seeking to model. Agents have more complex behaviour as well as additional data. The distribution class is introduced to allow the Households to have their income drawn from data that is representative of the UK household sector as a whole. In this way, we can accurately generate any number of realistically parameterised and yet heterogeneous agents. For many applications of simulation modelling, there is a need to run multiple runs of the same simulation. Due to the stochasticity and emergent properties of these types of model, results are best presented as a distribution. The Simudyne SDK includes a multi-run setting which allows the user to specify a Monte Carlo evaluation of their model. We can look at this in action in the mortgage model developed in this tutorial: \n import simudyne.core.abm.Action;\nimport simudyne.core.abm.AgentBasedModel;\nimport simudyne.core.abm.GlobalState;\nimport simudyne.core.abm.Group;\nimport simudyne.core.annotations.Input;\nimport simudyne.core.graph.LongAccumulator;\n\npublic class MortgageModel extends AgentBasedModel<GlobalState> {\n\n @Input(name = \"Number of Households\")\n public long nbHouseholds = 100;\n\n @Override\n public void init() {\n createLongAccumulator(\"equity\", \"Bank Equity (£)\");\n createLongAccumulator(\"assets\", \"Assets\");\n\n registerAgentTypes(Household.class, Bank.class);\n registerLinkTypes(Links.BankLink.class);\n }\n\n @Override\n public void setup() {\n // Create our agent groups\n Group<Household> householdGroup = generateGroup(Household.class, nbHouseholds);\n Group<Bank> bankGroup = generateGroup(Bank.class, 1);\n\n // Each household is connected to 1 bank\n householdGroup.partitionConnected(bankGroup, Links.BankLink.class);\n\n super.setup();\n }\n\n @Override\n public void step() {\n super.step();\n\n run(\n Action.create(\n Household.class,\n household -> {\n household.earnIncome();\n household.consume();\n household.payMortgage();\n }),\n Action.create(Bank.class, Bank::updateBalanceSheet));\n }\n}The Bank Class
\nimport simudyne.core.abm.Agent;\nimport simudyne.core.abm.GlobalState;\nimport simudyne.core.annotations.Variable;\n\nimport java.util.List;\n\npublic class Bank extends Agent<GlobalState> {\n\n @Variable public int debt = 90;\n\n void updateBalanceSheet() {\n int assets = 0;\n List<Messages.RepaymentAmount> paymentMessages =\n getMessagesOfType(Messages.RepaymentAmount.class);\n for (Messages.RepaymentAmount payment : paymentMessages) {\n assets += payment.getBody();\n }\n\n getLongAccumulator(\"assets\").add(assets);\n getLongAccumulator(\"equity\").add(assets - this.debt);\n }\n}The Household Class
\nimport simudyne.core.abm.Agent;\nimport simudyne.core.abm.GlobalState;\nimport simudyne.core.annotations.Variable;\n\npublic class Household extends Agent<GlobalState> {\n\n @Variable public int income = 5000;\n @Variable public int consumption = 3000;\n @Variable public int wealth = 1000;\n @Variable public int repayment = 100;\n\n void consume() {\n wealth -= consumption;\n }\n\n void earnIncome() {\n wealth += income;\n }\n\n void payMortgage() {\n if (canPay()) {\n getLinks(Links.BankLink.class).send(Messages.RepaymentAmount.class, repayment);\n }\n }\n\n private Boolean canPay() {\n return wealth >= repayment;\n }\n}Complex Behaviours
\nimport org.apache.commons.math3.random.EmpiricalDistribution;\nimport simudyne.core.abm.Action;\nimport simudyne.core.abm.AgentBasedModel;\nimport simudyne.core.abm.GlobalState;\nimport simudyne.core.abm.Group;\nimport simudyne.core.annotations.Input;\nimport simudyne.core.annotations.ModelSettings;\nimport simudyne.core.data.CSVSource;\n\n@ModelSettings(macroStep = 120)\npublic class MortgageModel extends AgentBasedModel<MortgageModel.Globals> {\n\n @Input(name = \"Number of Households\")\n public long nbHouseholds = 100;\n\n private int wealth = 50000;\n\n public static final class Globals extends GlobalState {\n @Input(name = \"LTI Limit\")\n public double LTILimit = 4.5;\n\n @Input(name = \"LTV Limit\")\n public double LTVLimit = 0.95;\n\n @Input(name = \"Interest Rate (%)\")\n public double interestRate = 5.0;\n\n @Input(name = \"Top Rate Tax Threshold (£k)\")\n public int topRateThreshold = 45;\n\n @Input(name = \"Personal Allowance (£k)\")\n public int personalAllowance = 11;\n\n @Input(name = \"Basic Rate of Tax (%)\")\n public double basicRate = 20.0;\n\n @Input(name = \"Top Rate of Tax (%)\")\n public double topRate = 40.0;\n\n @Input(name = \"Income Volatility (%)\")\n public double incomeVolatility = 2.5;\n }\n\n @Override\n public void init() {\n createLongAccumulator(\"equity\", \"Bank Equity (£)\");\n createLongAccumulator(\"badLoans\", \"Bad Loans\");\n createLongAccumulator(\"writeOffs\", \"Write-offs\");\n createLongAccumulator(\"impairments\", \"Impairments (£k)\");\n createLongAccumulator(\"debt\", \"Debt\");\n createLongAccumulator(\"income\", \"Income\");\n createLongAccumulator(\"mortgages\", \"Mortgages\");\n createLongAccumulator(\"assets\", \"Assets\");\n\n registerAgentTypes(Household.class, Bank.class);\n registerLinkTypes(Links.BankLink.class);\n }\n\n @Override\n public void setup() {\n EmpiricalDistribution incomeDist =\n getContext().getPrng().empiricalFromSource(new CSVSource(\"data/income-distribution.csv\"));\n\n Group<Household> householdGroup =\n generateGroup(\n Household.class,\n nbHouseholds,\n house -> {\n house.income = (int) incomeDist.sample(1)[0];\n house.wealth = wealth;\n });\n\n Group<Bank> bankGroup = generateGroup(Bank.class, 1);\n\n householdGroup.partitionConnected(bankGroup, Links.BankLink.class);\n\n super.setup();\n }\n\n @Override\n public void step() {\n super.step();\n\n run(Household.applyForMortgage, Bank.processApplication, Household.takeOutMortgage);\n\n run(\n Action.create(\n Household.class,\n (Household h) -> {\n h.incomeShock();\n h.earnIncome();\n h.payTax();\n h.subsistenceConsumption();\n h.payMortgage();\n h.discretionaryConsumption();\n }),\n Action.create(\n Bank.class,\n (Bank b) -> {\n b.accumulateIncome();\n b.processArrears();\n b.clearPaidMortgages();\n b.updateAccumulators();\n }),\n Action.create(Household.class, h -> h.writeOff()));\n }\n}UpdateAccumulators) updates the bank's balance sheet data via accumulators which are reported on the console.The Bank Class
\nimport simudyne.core.abm.Action;\nimport simudyne.core.abm.Agent;\nimport simudyne.core.annotations.Variable;\nimport simudyne.core.functions.SerializableConsumer;\n\nimport java.util.List;\n\npublic class Bank extends Agent<MortgageModel.Globals> {\n\n @Variable public int debt = 0;\n @Variable public int assets = 10000000;\n\n @Variable\n public int equity() {\n return assets - debt;\n }\n\n @Variable public int nbMortgages = 0;\n\n public static final double NIM = 0.25;\n\n private int termInYears = 15; // Should be 25\n private int termInMonths = termInYears * 12;\n\n int impairments = 0;\n int income = 0;\n\n @Variable(name = \"Stage 1 Provisions\")\n public double stage1Provisions = 0.0;\n\n @Variable(name = \"Stage 2 Provisions\")\n public double stage2Provisions = 0.0;\n\n private double interest() {\n return 1 + (getGlobals().interestRate / 100);\n }\n\n private static Action<Bank> action(SerializableConsumer<Bank> consumer) {\n return Action.create(Bank.class, consumer);\n }\n\n static Action<Bank> processApplication =\n action(\n bank ->\n bank.getMessagesOfType(Messages.MortgageApplication.class).stream()\n .filter(m -> m.amount / m.income <= bank.getGlobals().LTILimit)\n .filter(m -> m.wealth > m.amount * (1 - bank.getGlobals().LTVLimit))\n .forEach(\n m -> {\n int totalAmount =\n (int) (m.amount * Math.pow(bank.interest(), bank.termInYears));\n\n bank.send(\n Messages.ApplicationSuccessful.class,\n newMessage -> {\n newMessage.amount = totalAmount;\n newMessage.termInMonths = bank.termInMonths;\n newMessage.repayment = totalAmount / bank.termInMonths;\n })\n .to(m.getSender());\n bank.nbMortgages += 1;\n bank.assets += m.amount;\n bank.debt += m.amount;\n }));\n\n void accumulateIncome() {\n income = 0;\n getMessagesOfType(Messages.Payment.class).forEach(payment -> income += payment.repayment);\n\n assets += (income * NIM);\n }\n\n void processArrears() {\n List<Messages.Arrears> arrears = getMessagesOfType(Messages.Arrears.class);\n // Count bad loans\n calcBadLoans(arrears);\n // Calculate provisions\n double stage1Provisions = calcStageOneProvisions(arrears);\n double stage2Provisions = calcStageTwoProvisions(arrears);\n this.stage1Provisions = stage1Provisions * 0.01;\n this.stage2Provisions = stage2Provisions * 0.03;\n\n writeLoans(arrears);\n }\n\n private void calcBadLoans(List<Messages.Arrears> arrears) {\n arrears.forEach(\n arrear -> {\n if (arrear.monthsInArrears > 3) {\n getLongAccumulator(\"badLoans\").add(1);\n }\n });\n }\n\n private void writeLoans(List<Messages.Arrears> arrears) {\n impairments = 0;\n arrears.forEach(\n arrear -> {\n // A mortgage is written off if it is more than 6 months in arrears.\n if (arrear.monthsInArrears > 6) {\n impairments += arrear.outstandingBalance;\n\n getLongAccumulator(\"writeOffs\").add(1);\n\n // Notify the sender their loan was defaulted.\n send(Messages.LoanDefault.class).to(arrear.getSender());\n }\n });\n assets -= impairments;\n }\n\n private int calcStageTwoProvisions(List<Messages.Arrears> arrears) {\n return arrears.stream()\n .filter(m -> m.monthsInArrears > 1 && m.monthsInArrears < 3)\n .mapToInt(m -> m.outstandingBalance)\n .sum();\n }\n\n private int calcStageOneProvisions(List<Messages.Arrears> arrears) {\n return arrears.stream()\n .filter(m -> m.monthsInArrears <= 1)\n .mapToInt(m -> m.outstandingBalance)\n .sum();\n }\n\n /** Remove any mortgages that have closed from the books. */\n void clearPaidMortgages() {\n int balancePaidOff = 0;\n\n for (Messages.CloseMortgageAmount closeAmount :\n getMessagesOfType(Messages.CloseMortgageAmount.class)) {\n balancePaidOff += closeAmount.getBody();\n nbMortgages -= 1;\n }\n\n debt -= balancePaidOff;\n assets -= balancePaidOff;\n }\n\n public void updateAccumulators() {\n getLongAccumulator(\"debt\").add(debt);\n getLongAccumulator(\"impairments\").add(impairments);\n getLongAccumulator(\"mortgages\").add(nbMortgages);\n getLongAccumulator(\"income\").add(income);\n getLongAccumulator(\"assets\").add(assets);\n getLongAccumulator(\"equity\").add(equity());\n }\n}The Household Class
\nimport simudyne.core.abm.Action;\nimport simudyne.core.abm.Agent;\nimport simudyne.core.annotations.Variable;\nimport simudyne.core.functions.SerializableConsumer;\n\npublic class Household extends Agent<MortgageModel.Globals> {\n\n @Variable public int income;\n @Variable public int wealth = 1000;\n\n @Variable\n public int repayment() {\n if (mortgage == null) {\n return 0;\n }\n\n return mortgage.repayment;\n }\n\n int taxBill = 0;\n Mortgage mortgage;\n int monthsInArrears = 0;\n\n private static Action<Household> action(SerializableConsumer<Household> consumer) {\n return Action.create(Household.class, consumer);\n }\n\n void earnIncome() {\n wealth += income / 12;\n }\n\n void payMortgage() {\n if (mortgage != null) {\n if (canPay()) {\n wealth -= mortgage.repayment;\n monthsInArrears = 0;\n mortgage.term -= 1;\n mortgage.balanceOutstanding -= mortgage.repayment;\n checkMaturity();\n } else {\n monthsInArrears += 1;\n getLinks(Links.BankLink.class)\n .send(\n Messages.Arrears.class,\n (m, l) -> {\n m.monthsInArrears = monthsInArrears;\n m.outstandingBalance = mortgage.balanceOutstanding;\n });\n }\n }\n }\n\n private void checkMaturity() {\n if (mortgage.term == 0) {\n getLinks(Links.BankLink.class).send(Messages.CloseMortgageAmount.class, mortgage.amount);\n mortgage = null;\n } else {\n getLinks(Links.BankLink.class)\n .send(\n Messages.Payment.class,\n (m, l) -> {\n m.repayment = mortgage.repayment;\n m.amount = mortgage.amount;\n });\n }\n }\n\n private Boolean canPay() {\n return wealth >= mortgage.repayment;\n }\n\n static Action<Household> applyForMortgage =\n action(\n h -> {\n if (h.mortgage == null) {\n if (h.getPrng().discrete(1, 5).sample() == 1) {\n int purchasePrice = 100000 + h.income * 2;\n h.getLinks(Links.BankLink.class)\n .send(\n Messages.MortgageApplication.class,\n (m, l) -> {\n m.amount = purchasePrice;\n m.income = h.income;\n m.wealth = h.wealth;\n });\n }\n }\n });\n\n static Action<Household> takeOutMortgage =\n action(\n h ->\n h.hasMessageOfType(\n Messages.ApplicationSuccessful.class,\n message ->\n h.mortgage =\n new Mortgage(\n message.amount,\n message.amount,\n message.termInMonths,\n message.repayment)));\n\n void incomeShock() {\n // 50% of households gain volatility income, the other 50% lose it.\n if (getPrng().discrete(1, 2).sample() == 1) {\n income += (getGlobals().incomeVolatility * income / 100);\n } else {\n income -= (getGlobals().incomeVolatility * income / 100);\n }\n\n if (income <= 0) {\n income = 1;\n }\n }\n\n void payTax() {\n if (income < getGlobals().topRateThreshold) {\n taxBill = (int) ((income - getGlobals().personalAllowance) * getGlobals().basicRate / 100);\n } else {\n taxBill =\n (int)\n (((income - getGlobals().topRateThreshold) * getGlobals().topRate / 100)\n + (income - getGlobals().personalAllowance) * getGlobals().basicRate / 100);\n }\n wealth -= taxBill / 12;\n }\n\n void subsistenceConsumption() {\n wealth -= 5900 / 12;\n\n if (wealth < 0) {\n wealth = 1;\n }\n }\n\n void discretionaryConsumption() {\n int incomeAfterSubsistence = income - 5900;\n double minLiqWealth =\n 4.07 * Math.log(incomeAfterSubsistence) - 33.1 + getPrng().gaussian(0, 1).sample();\n double monthlyConsumption = 0.5 * Math.max(wealth - Math.exp(minLiqWealth), 0);\n wealth -= monthlyConsumption;\n }\n\n void writeOff() {\n if (hasMessageOfType(Messages.LoanDefault.class)) {\n mortgage = null;\n }\n }\n\n public static class Mortgage {\n int amount;\n int balanceOutstanding;\n int term;\n int repayment;\n\n public Mortgage(int amount, int balanceOutstanding, int term, int repayment) {\n this.amount = amount;\n this.balanceOutstanding = balanceOutstanding;\n this.term = term;\n this.repayment = repayment;\n }\n }\n}Messages
\nimport simudyne.core.graph.Message;\n\npublic class Messages {\n public static class Arrears extends Message {\n int monthsInArrears;\n int outstandingBalance;\n }\n\n public static class LoanDefault extends Message.Empty {}\n\n public static class CloseMortgageAmount extends Message.Integer {}\n\n public static class MortgageApplication extends Message {\n int amount;\n int income;\n int wealth;\n }\n\n public static class ApplicationSuccessful extends Message {\n int amount;\n int termInMonths;\n int repayment;\n }\n\n public static class Payment extends Message {\n int repayment;\n int amount;\n }\n}Links
\nimport simudyne.core.graph.Link;\n\npublic class Links {\n public static class BankLink extends Link.Empty {}\n}Final Model
\nMultiple Runs
\n