{"data":{"markdownRemark":{"html":"

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 practice for the iterative development of models.

\n

The 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.

\n

This tutorial is divided into three parts: which reflects the iterative nature of building agent-based models.

\n

\n \n \n \n \n

MortgageModel.java

\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;\n\npublic class MortgageModel extends AgentBasedModel<GlobalState> {\n  {\n    createLongAccumulator(\"equity\", \"Bank Equity (£)\");\n    createLongAccumulator(\"assets\");\n  }\n\n  @Input(name = \"Number of Households\")\n  long nbHouseholds = 100;\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);\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(\n            Bank.class,\n            bank -> {\n              bank.updateBalanceSheet();\n            }));\n  }\n}
\n

The Bank class

\n

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 - debt. The bank updates its assets in line with the sum of mortgage repayments it receives.

\n

Bank.java

\n
import simudyne.core.abm.Agent;\nimport simudyne.core.abm.GlobalState;\nimport simudyne.core.annotations.Variable;\nimport simudyne.core.graph.Message;\n\nimport java.util.List;\n\npublic class Bank extends Agent<GlobalState> {\n  @Variable int debt = 90;\n\n  public void updateBalanceSheet() {\n    int assets = 0;\n    List<Message<Integer>> paymentMessages = getMessagesOfType(Integer.class);\n    for (Message<Integer> payment : paymentMessages) {\n      assets += payment.getBody();\n    }\n\n    getLongAccumulator(\"assets\").add(assets);\n    getLongAccumulator(\"equity\").add(assets - this.debt);\n  }\n}
\n

The Household Class

\n

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

\n

Household.java

\n
import simudyne.core.abm.Agent;\nimport simudyne.core.abm.GlobalState;\nimport simudyne.core.annotations.Variable;\n\npublic class Household extends Agent<GlobalState> {\n  @Variable int income = 5000;\n  @Variable int consumption = 3000;\n  @Variable int wealth = 1000;\n  @Variable int repayment = 100;\n\n  public void consume() { wealth -= consumption; }\n\n  public void earnIncome() { wealth += income; }\n\n  public void payMortgage() {\n    if (canPay()) {\n      broadcastMessage(repayment);\n    }\n  }\n\n  private Boolean canPay() { return wealth >= repayment; }\n}
\n

Complex Behaviours

\n

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.

\n

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 best practice -- see Class Organisation.

\n

MortgageModel.java

\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.annotations.ModelSettings;\n\n@ModelSettings(macroStep = 120)\npublic class MortgageModel extends AgentBasedModel<GlobalState> {\n\n  {\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\n  int income = 5000;\n  int wealth = 50000;\n\n  @Input(name = \"Number of Households\")\n  long nbHouseholds = 100;\n\n  @Override\n  public void setup() {\n    Group<Household> householdGroup =\n        generateGroup(\n            Household.class,\n            nbHouseholds,\n            house -> {\n              house.income = income;\n              house.wealth = wealth;\n            });\n\n    Group<Bank> bankGroup = generateGroup(Bank.class, 1);\n\n    householdGroup.partitionConnected(bankGroup);\n\n    super.setup();\n  }\n\n  @Override\n  public void step() {\n    super.step();\n\n    run(\n      Household.applyForMortgage(),\n      Bank.processApplication(),\n      Household.takeOutMortgage()\n    );\n\n    run(\n        Action.create(\n            Household.class,\n            (Household h) -> {\n              h.incomeShock();\n              h.earnIncome();\n              h.consume();\n              h.payMortgage();\n            }),\n        Action.create(\n            Bank.class,\n            (Bank b) -> {\n              b.accumulateIncome();\n              b.processArrears();\n              b.calculateImpairments();\n              b.clearPaidMortgages();\n              b.updateAccumulators();\n            }));\n  }\n}
\n

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 (UpdateAccumulators) updates the bank's balance sheet data via accumulators which are reported on the console.

\n

The Bank Class

\n

Bank.java

\n
import simudyne.core.abm.Action;\nimport simudyne.core.abm.Agent;\nimport simudyne.core.abm.GlobalState;\nimport simudyne.core.annotations.Variable;\nimport simudyne.core.graph.Message;\n\npublic class Bank extends Agent<GlobalState> {\n  @Variable int debt = 0;\n  @Variable int assets = 10000000;\n\n  @Variable\n  int equity() {\n    return assets - debt;\n  }\n\n  @Variable private int nbMortgages = 0;\n\n  private int termInYears = 15; // Should be 25\n  private double interest = 1.05;\n  private int termInMonths = termInYears * 12;\n\n  private int impairments = 0;\n  private int income = 0;\n\n  private double LTILimit = 4.5;\n  private double LTVLimit = 0.95;\n\n  public static Action<Bank> processApplication() {\n    return new Action<>(\n        Bank.class,\n        bank ->\n            bank.getMessagesOfType(Messages.MortgageApplication.class)\n                .stream()\n                .filter(m -> m.getBody().amount / m.getBody().income <= bank.LTILimit)\n                .filter(m -> m.getBody().wealth > m.getBody().amount *\n                  (1 - bank.LTVLimit))\n                .forEach(\n                    m -> {\n                      bank.sendMessage(\n                          new Messages.ApplicationSuccessful(\n                              m.getBody().amount,\n                              bank.termInMonths,\n                              (int) ((m.getBody().amount * bank.interest) /\n                                bank.termInMonths)),\n                          m.getSender());\n\n                      bank.nbMortgages += 1;\n                      bank.assets += m.getBody().amount;\n                      bank.debt += m.getBody().amount;\n                    }));\n  }\n\n  public void accumulateIncome() {\n    income = 0;\n\n    getMessagesOfType(Messages.Payment.class)\n        .forEach(payment -> income += payment.getBody().repayment);\n\n    double NIM = 0.25;\n    assets += (income * NIM);\n  }\n\n  /**\n   * Record how many bad loans the bank has. A loan is counted as bad if it has been more than 3\n   * months in arrears.\n   */\n  public void processArrears() {\n    getMessagesOfType(Messages.Arrears.class)\n        .forEach(\n            arrears -> {\n              if (arrears.getBody().monthsInArrears > 3) {\n                getLongAccumulator(\"badLoans\").add(1);\n              }\n            });\n  }\n\n  /** Calculate impairments from written off loans. */\n  public void calculateImpairments() {\n    impairments = 0;\n\n    getMessagesOfType(Messages.Arrears.class)\n        .forEach(\n            arrears -> {\n              // A mortgage is written off if it is more than 6 months in arrears.\n              if (arrears.getBody().monthsInArrears > 6) {\n                impairments += arrears.getBody().outstandingBalance;\n\n                getLongAccumulator(\"writeOffs\").add(1);\n              }\n            });\n\n    // Remove any impairments from our assets total.\n    // Note that the debt from the written off loan remains.\n    assets -= impairments;\n  }\n\n  /** Remove any mortgages that have closed from the books. */\n  public void clearPaidMortgages() {\n    int balancePaidOff = 0;\n\n    for (Message<Messages.CloseMortgage> close :\n      getMessagesOfType(Messages.CloseMortgage.class)) {\n        balancePaidOff += close.getBody().amount;\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}
\n

The Household Class

\n

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

\n

Household.java

\n
import simudyne.core.abm.Action;\nimport simudyne.core.abm.Agent;\nimport simudyne.core.abm.GlobalState;\nimport simudyne.core.annotations.Variable;\n\npublic class Household extends Agent<GlobalState> {\n  @Variable int income;\n  @Variable int wealth = 1000;\n\n  Mortgage mortgage;\n  int monthsInArrears = 0;\n  int consumption = 3000;\n\n  public void earnIncome() {\n    wealth += income;\n  }\n\n  public 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        broadcastMessage(new Messages.Arrears(monthsInArrears, mortgage.amount));\n\n        // If we have spent more than 6 months in arrears,\n        // default the mortgage (close it with 0 value).\n        if (monthsInArrears > 6) {\n          broadcastMessage(new Messages.CloseMortgage(0));\n          mortgage = null;\n        }\n      }\n    }\n  }\n\n  private void checkMaturity() {\n    if (mortgage.term == 0) {\n      broadcastMessage(new Messages.CloseMortgage(mortgage.amount));\n      mortgage = null;\n    } else {\n      broadcastMessage(new Messages.Payment(mortgage.repayment, mortgage.amount));\n    }\n  }\n\n  private Boolean canPay() {\n    return (mortgage == null) || (wealth >= mortgage.repayment);\n  }\n\n  public static Action<Household> applyForMortgage() {\n    return Action.create(\n        Household.class,\n        h -> {\n          if (h.mortgage == null) {\n            int purchasePrice = h.income * 4;\n            h.broadcastMessage(new Messages.MortgageApplication(purchasePrice,\n              h.income, h.wealth));\n          }\n        });\n  }\n\n  public static Action<Household> takeOutMortgage() {\n    return Action.create(\n        Household.class,\n        h ->\n          h.hasMessageOfType(\n            Messages.ApplicationSuccessful.class,\n              message ->\n                h.mortgage =\n                  new Mortgage(\n                    message.getBody().amount,\n                    message.getBody().amount,\n                    message.getBody().termInMonths,\n                    message.getBody().repayment)));\n  }\n\n  public void incomeShock() {\n    income += 200 * getPrng().gaussian(0, 1).sample();\n\n    if (income < 0) {\n      income = 1;\n    }\n  }\n\n  public void consume() {\n    wealth -= consumption;\n\n    if (wealth <= 0) {\n      wealth = 1;\n    }\n  }\n\n  public static class Mortgage {\n    private int amount;\n    private int balanceOutstanding;\n    private int term;\n    private 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}
\n

Messages

\n
public class Messages {\n  public static class Arrears {\n    public int monthsInArrears;\n    public int outstandingBalance;\n\n    public Arrears(int monthsInArrears, int outstandingBalance) {\n      this.monthsInArrears = monthsInArrears;\n      this.outstandingBalance = outstandingBalance;\n    }\n  }\n\n  public static class CloseMortgage {\n    public int amount;\n\n    public CloseMortgage(int amount) {\n      this.amount = amount;\n    }\n  }\n\n  public static class MortgageApplication {\n    public int amount;\n    public int income;\n    public int wealth;\n\n    public MortgageApplication(int amount, int income, int wealth) {\n      this.amount = amount;\n      this.income = income;\n      this.wealth = wealth;\n    }\n  }\n\n  public static class ApplicationSuccessful {\n    public final int amount;\n    public final int termInMonths;\n    public final int repayment;\n\n    public ApplicationSuccessful(int amount, int termInMonths, int repayment) {\n      this.amount = amount;\n      this.termInMonths = termInMonths;\n      this.repayment = repayment;\n    }\n  }\n\n  public static class Payment {\n    final int repayment;\n    final int amount;\n\n    public Payment(int repayment, int amount) {\n      this.repayment = repayment;\n      this.amount = amount;\n    }\n  }\n}
\n

Final Model

\n

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.

\n

Agents have more complex behaviour as well as additional data.

\n

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.

","headings":[{"value":"Skeleton Model","depth":2},{"value":"Basic Model Structure","depth":3},{"value":"The Main Model Class","depth":3},{"value":"The Bank class","depth":3},{"value":"The Household Class","depth":3},{"value":"Complex Behaviours","depth":2},{"value":"The Bank Class","depth":3},{"value":"The Household Class","depth":3},{"value":"Messages","depth":3},{"value":"Final Model","depth":2}],"frontmatter":{"title":"Mortgage Model","toc":null,"experimental":null}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.0/docs/tutorials/mortgage.md","versioned":true,"version":"2.0","kind":"docs","pagePath":"/tutorials/mortgage","chronology":{"prev":{"name":"Trader Model","path":"/tutorials/trader"},"next":{"name":"Best Practices","path":"/practices"}},"lastUpdated":"2026-04-21T13:56:54.825Z"}}