Learning the National Household Model

The NHM is programmable; it might be better to think of it as a tool for making models rather than a particular model, as most of the things you will want it to simulate you will have to explain to it in your program. It does not simulate very much apart at all from what your program instructs. It is designed to make certain kinds of simulation program easy to write, so they can have a short description, but you will still have to write something.

For those readers who have used programmable tools before, the NHM will have some degree of familiarity; you write a scenario, which is just some text obeying a special syntax, and then ask the model to run your scenario. It simulates what it's been instructed to simulate, and produces any outputs (typically big tables about what happened) that it's been instructed to emit. There is more about the syntax in the section on reading scenario language

You can then take the outputs and use them to inform policy decisions.

A discrete-event simulation is one where time passes in fits and starts between events, and nothing happens otherwise. An event is an instantaneous change in the state of affairs that happens at a particular time. Other types of models might use differential equations to represent values which change continuously in time, but in a discrete event model everything stays the same until an event comes along, at which moment there is a corresponding change to how things are. Then everything stays in its new arrangement until the next event, and so on.

The model uses the syntax in your scenario to set up the sequence of events which are going to happen in the simulation. This sequence (the event queue) is a list of 'things to do', sorted by the date on which they should be done. The events that a scenario defines usually describe a command for changing something, like "take a random 10% of semi-detached houses in the south-west, and offer each one some loft insulation", or a command to make some output, like "record how many semi-detached houses in the south-west have loft insulation".

Once the model has read your scenario and set up its future events, it simply goes through the list and does them in order until it's either reached the maximum date you want to simulate, or there are no events left to think about. An important thing to understand here is that at a particular point in simulated time, the model has an idea of how the world is. When an event happens, it can change this representation of the world, so that the next event is presented with a different state of affairs. This is the analog of the arrow of time which seems to exist in reality - things which happen in the past may affect the future, but not vice-versa.

The state of affairs mentioned in the previous section is mostly defined by the condition of a collection of dwellings; a dwelling is a place where one or more households reside, typically a flat or a house (as distinct from a building, which may contain several dwellings, or a household, of which a dwelling may contain several).

The initial state (S0 in 1) is defined by a stock, which is a file containing descriptions of the dwellings that should exist to start with, which we will call cases. The stock which the model will use is specified in the scenario, so the same scenario can be run against different initial conditions by referring to a different stock.

Each case in the stock has a weight associated with it, which indicates how many dwellings in the real world correspond with that description. For example, there might be 5,000 dwellings which are to be represented by a description of a medium-sized flat in London, whereas there may only be 500 dwellings represented by a description of a detached house in the North of Scotland. The total weight of all the cases in the stock should equal the number of dwellings in regions which the stock covers.

Imagine a stock which contains cases as described in table 1.

1. What simulated dwellings and what gross weight would be produced using a quantum of:
   1. 50
   2. 100
   3. 150
   4. 500

2. Here is a procedure for sampling from the set of simulated dwellings:

   To sample dwellings of weight \(w\), shuffle the dwellings into a random order, and then take as many from the beginning of the order up to but not exceeding total weight \(w\).

   If we take a sample of weight 500, what is the expected floor area, and the variance in expected floor area, for a quantum of:

   1. 1
   2. 50
   3. 100
   4. 150 An analytical answer may be unfeasible here, and for 500, but you can simulate this with Excel quite easily
   5. 500

The NHM is a domestic energy model. It uses the dwelling descriptions in the stock to predict dwellings' energy uses using the BREDEM model, which is the basis for SAP. Many of the odd results which can be produced by the NHM are attributable to features of the SAP method, in which the meaning or use of certain terms can be quite counterintuitive. We would recommend that you read the SAP document before using the NHM in anger, or at least look through the SAP worksheet⁵. We also provide a brief overview here, which also explains a little bit of building physics for those new to the entire area.

A SAP calculation breaks down into a few parts, which are (in rough order of signifiance):

• Space heating
• Water heating
• Lighting and appliance use

We now come onto the syntax for NHM scenarios; this defines what scenarios the model can understand, and how to read their structure.

The scenario language is a kind of special-purpose programming language. A lot of languages work by describing a series of steps to do¹. Some parts of an NHM scenario form a list of steps, but as a rule it does not proceed by processing one line at a time in sequence.

Instead, the statements in a scenario should to be interpreted as instructions that have meaning given to them by the context in which they are written.

Every statement in a scenario one of four things:

1. A literal, which is a word, number or other sequence of characters except spaces, or any sequence of characters between double quotation marks (including spaces)
   • hello is a literal
   • hello world is two literals, hello and world
   • 103.4 is a literal
   • 90% is a literal
   • 01/01/2014 is a literal
   • *my-long.thing!* is a literal
2. An expression (or s-expression or symbolic expression), which is exactly one literal followed by zero or more other statements enclosed in parentheses ( and ). Expressions are usually commands to the model, and the first literal gives the name of the command. The rest of the things are arguments to the command; they belong to the command and affect what it does in some way. Different commands accept different arguments.
   • (hello) is an expression, which is invoking a command called hello
   • (+ 1 2 3) is an expression, which is invoking the command + with three literals 1, 2 and 3 as inputs. In this case + does what you would think as do numbers, and this is an instruction to sum the values 1, 2 and 3.
   • (measure.wall-insulation type: Cavity) is an expression invoking the command measure.wall-insulation, and giving it the arguments type: and Cavity. Arguments which end with a colon (:) tell the command something about the intended meaning of the following argument, so here Cavity is the type of measure.wall-insulation
   • (+ (* 1 2) 3) is an expression invoking + with two arguments; the first argument is another expression (* 1 2), and the second is the literal 3. Again, this means what you might expect: multiply 1 by 2, and then add 3 to the result.
   • (1 + 2) is an expression, but it does not mean "add 1 and 2", or "supply 1 and 2 to +". If it meant anything it would be supply the literals + and 2 to a command called 1; however the model has no command called 1.
   • ((1 + 3) * (4 + 5)) is not a legal expression, because the head is not a literal.
   • () is not a legal expression, because it has no head
3. A list, which is a series of other statements enclosed in brackets [ and ]
   • [1 2 3 4] is a list of the four literals 1, 2, 3, and 4.
   • [(+ 1 2) 8] is a list with two things in; the expression (+ 1 2) and the literal 8
   • [] is a list with nothing in it

4. An infix expression, which is a normal mathematical expression enclosed in braces { and }. Infix expressions must be space separated, because the names of NHM literals can contain characters that look like mathematical operators. Infix expressions are translated automatically into standard expressions when they are read. You don't have to use infix expressions anywhere if you don't want to, but in a few places they may make things easier to read.

   • {1 + 2} is an infix expression which is read as the expression (+ 1 2)
   • {1+2} is an infix expression which is read as the expression (1+2), which is not + applied to 1 and 2.
   • {9 * x + 33 / 7} is an infix expression which is read as the expression (+ (* 9 x) (/ 33 7)).

   When you read an expression, it can be helpful to mentally translate it into a description of an instruction; here are some examples: (we will cover what the terms written actually mean, and how to use them later)

   (measure.wall-insulation
    resistance:0.01
    thickness:50
    capex:(* 1.1 (size.m2)))
   

   This can be read as

   Use the command measure.wall-insulation, giving it a resistance of 0.01, a thickness of 50, and a capex determined by using the command * with 1.1 and the result of the command size.m2.

   (apply
    (measure.standard-boiler)
    to: (filter (house.region-is London)))
   

   Reads as

   Use the apply command, giving it the command measure.standard-boiler, and telling it that to is the result of using the filter command with the house.region-is command given London.

   These translations are ignorant of the meaning of all the terms. We have tried (and sometimes succeeded) to make it so that the names of commands and of their named arguments have a guessable meaning. In the examples given, you can hopefully determine something about what the commands written will actually do. Every command has a page in the manual which should describe what arguments it takes, and what it does with them.

   It can be helpful to think of s-expressions as hierarchies, a bit like an org-chart. For example, the expression

   (a (b c d)
      (e f g (h (i j) k)))
   

   could be illustrated as in figure 2. Just as in a real org-chart, entities which are higher up (like managers) are more important than those lower down (human resources); the managers direct the actions of their subordinates but because they are ideas people they do not have to understand the implied detail. They need only be concerned with the requirements they and the form of the outputs they will produce. In the examples above, you might say that measure.wall-insulation delegates the task of computing a number for the argument capex: to the expression (* 1.1 (size.m2)); in this case * does not 'know' that its output is to be used for capex, and measure.wall-insulation does not 'know' how to multiply two numbers together.

   

   Figure 2: A hierarchy describing the expression (a (b c d) (e f g (h (i j) k))). Arrows point to nodes which are more general, or important, or controlling. The node a controls b and e, and may determine their environment and use both their outputs; e can only see the effect of b insofar as a relates them.

1. For each of these bits of syntax, which sentence gives a description consistent with this section of the manual? Note that the syntax written here may not have any semantics assigned to it in the NHM, but it is syntactically OK, so you could define some terms in a scenario that would give it a meaning. Further note if any of them seem like they look like a mistake.
   1. (house.energy-use)
      1. calculate house.energy minus use
      2. invoke the command house.energy with the unnamed argument use
      3. invoke the command house.energy-use
   2. (house.energy-use by-fuel:MainsGas)
      1. invoke the command house.energy-use with the unnamed argument by-fuel:MainsGas
      2. invoke the command house.energy-use with MainsGas for the named argument by-fuel:
   3. (+ 1 house.energy-use by-fuel: mainsgas)
      1. invoke the command + with two unnamed arguments, 1 and house.energy-use, and the keyword argument by-fuel: being mainsgas
      2. invoke the command + with the arguments 1, and
         • the command house.energy-use given a keyword argument by-fuel: being mainsgas
   4. (aggregate.count name:how-many)
      1. invoke the command aggregate with the unnamed argument count and and the keyword argument name: being how-many
      2. invoke the command aggregate.count with the keyword argument name: being how-many
   5. (+ 10 (* 4 (house.total-floor-area)) 3)
      1. invoke the command + with the arguments * 4 and house.total-floor-area and 3
      2. invoke the command + with the arguments 10, and:
         • the command * with the arguments 4 and
           • the command house.total-floor-area, and
           • 3
      3. invoke the command + with the arguments 10, and:
         • the command * with the arguments 4 and
           • the command house.total-floor-area
         • 3
   6. (/ 8 (+ 3 4))
      1. invoke the command + with the arguments / 8 and 3 and 4
      2. invoke the command / with two arguments, 8 and
         • the command + itself having two arguments, 3 and 4
   7. (8 / 9 + 3)
      1. invoke the command / with 8 and 9 and then invoke the command + with 3
      2. invoke the command 8 with the arguments /, 9, + and 3
   8. (1+2)
      1. invoke the command 1 with + and 2 as arguments
      2. invoke the command + with 1 and 2 as arguments
      3. invoke the command 1+2 with no arguments
2. For each of these bits of syntax, write your own outline description
   1. (/ 1 2 3 4 5)
   2. (+ + + + plus)
   3. (+ (1 2) (/ 3) 4)
   4. (+ (1 2) (/ 3 4))
   5. (+ 1 2 (/ 3 4))
   6. (+ 1 2 / 3 4)
   7. (log base:9 9)
   8. (log 9 base: 9)
   9. (log (log 9) base: (log base:9 9))
   10. (measure.standard-boiler fuel:mainsgas capex: (+ 500 (* 40 size.kw)))
   11. (qwer [123 (qwer 303)] pip: [pop])
3. For each of these outline descriptions, write equivalent syntax
   1. The word fish
   2. A use of the command fish
   3. The command fish applied to the single unnamed argument 4
   4. The command + applied to two unnamed arguments:
      • the command house.energy-use, given the named argument:

        by-fuel:

        MainsGas

      • the command house.energy-use, given the named argument:

        by-fuel:

        HouseCoal

4. For each of these bits of syntax, indicate why it cannot be valid syntax
   1. (+ 1 2 3
   2. (+ ((* 3 4)))
   3. [(house.energy-use by-fuel:) mainsgas]
   4. ([house.region] [house.built-form])

By now we have covered the NHM syntax, but little to nothing about the semantics. If you have a well-formed scenario the semantics say what simulation will if it runshappen. However, not all syntactically correct scenarios can be made into a simulation, because not every command can be used in every place. For example, you cannot add a house's region to its floor area, because region is not something that can go within + (ultimately because it's not a number). There is an exhaustive list of what commands can be used where in the language reference.

In truth most of the rest of this document is about the semantics, going into depth about the behaviour of different parts of the language, and what commands can be used where.

However, for familiarity here is a shallow overview of the semantics associated with common bits of syntax.

• Top level elements There are two things you will see at the top level of a scenario
  • scenario is the command declaring a single scenario. This will instruct the model to load some houses from a stock file, and then simulate changes to the houses and trigger the production of reports
  • batch is the command declaring a suite of related scenarios A batch contains a scenario: argument, which is a scenario, and an inputs: argument, which generates a table of parameters. The parameters are substituted into 'placeholders' in the scenario: argument to produce many variants, which are run and then summarised together. This is mostly good for sensitivity analysis.
• Things which go inside a scenario

  • Commands to make things happen; on.dates, on.change

    Mostly you will use on.dates within the top level of a scenario. It sets up the simulation to do things when the model gets to particular dates. The things inside it are the things that will get done. The order in which things get done is determined by the date, and then by the line number.

  • Commands to change things about how the model works

    Along with on.dates, you may write a few things mostly starting with context. which change 'global' settings in the model. For example, context.tariffs sets up fuel prices, context.weather changes the weather, context.carbon-factors changes the carbon factors and so on.

  • Definitions

    Finally you may see definitions of variables and actions. The command def defines a variable, which will either be stored against each modelled house (like number of measures house has received) or as a single global counter (like number of measures given out in total) depending on the on: argument.

    There are also commands def-action, def-test, def-function and def-report which merely serve to define things for later reuse; they have no direct effect on their own.

• Things which happen on particular dates We mentioned on.dates which makes things happen; here are some of the things it can make happen:
  • apply is one of the most basic things you can make happen. When it happens, it finds a population of houses defined by its to: argument, and then goes through the actions it has to take applying each action to all the houses in turn.
  • aggregate is a command to produce a summary table about a population of houses. When it happens, rows are added to that table, so it lets you see the state of the stock at a moment in time.
  • repeat is a command that tries doing something to the stock again and again until a condition is met
• Measures and actions apply is what you use to change houses, using an action. A measure is a kind of action that represents a technology being put into a house. The NHM has lots of actions; the important ones are:
  • action.case, which lets you pick an action to take depending on how the house is
  • do, which lets you combine a series of actions into one
  • choice, which lets you pick an action to take based on how the house will be afterwards
  • action.do-nothing and action.fail, which are explained later
• Modules and templates Along with everything described so far, you are likely to encounter, modules, templates and macros. These are ways to make your scenario shorter to read and write by avoiding writing the same or similar things again and again. They are explained later, but basically template and any command starting with ~ are special, and transform the scenario in some way before it gets run (and so before any stock is loaded or energy calculations are done or anything).
• Includes Finally if your scenario gets big enough or has parts that need reusing, it may be broken up into separate files. Any of the commands starting with include is akin to a mechanism for copy-pasting another file into your scenario when it is run.

The latest version of the NHM is always available from http://deccnhm.org.uk/standalone/. This presents four different builds for different operating systems. For the windows version, you will need to download cse.nhm.ide.application-win32.win32.x86_64.zip. This requires you have:

• A 64-bit processor and associated Windows operating system
• Sufficient memory; this is probably 4GiB (gigabytes) at a minimum

It includes a version of the Java Runtime Environment (JRE) which it needs, so you do not need to install this. However, the applications offered for other platforms do not include this, so if you want to use the Mac OS or Linux versions you will need to install your own JRE.

The NHM requires very little installation - all that you need to do is unzip the zip file you downloaded in the previous step somewhere on your computer. In windows you can usually do this by right-clicking on the zip file, and choosing Extract all...

If you are installing the application in a multi-user environment, where several users of the same machine may run it at the same time, you may need to do further setup. The Eclipse documentation explains more about this for system administrators.

Now that you have the application installed, let's have a quick walk-through of the major features. Start the application double-clicking on the National Household Model.exe program.

If everything is working correctly, you should see a loading window like this:

Once the application has started up you will be presented with a blank slate for working on NHM scenarios. The window which appears will look something like this, except without all the arrows and boxes drawn on.

You can see in this window the main way the NHM interface works. There is one big window, which has the usual menu bar at the, then a tool bar (the row of icons below the menu bar)⁸. Below that the window is divided up into several non-overlapping rectangular panels. Each panel may house some "views", which show information. In the picture above, there are three panels, one on the left, one at the bottom right and one at the top right. You can see that the left panel contains only the Project Explorer view, and the panel at the bottom contains these four views:

• Problems
• Git Repositories
• Model runs
• Model run log

In the bottom panel, the Problems view is currently displayed. Clicking on the name of one of the other views would switch change to that view.

Each panel also has some little controls in the top right, a thin horizontal bar and a horizontal bar with a rectangle underneath it. The thin horizontal bar will shrink (minimize) the panel down to a narrow bar on the side of the window. The fat horizontal bar will expand (maximize) the panel to fill the whole window. The problems view and the project explorer view both have a cross (X) at the right of their name. Clicking this will close the view. They also both have a view menu, which is the little downward pointing arrow near the minimize and maximize buttons. This shows a menu with options relevant to the view. You can also move views around by dragging and dropping the tab with their name in on the screen.

Try clicking on any of these buttons to see what they do, to get a feel for the user interface.

If you have closed a view, or got confused about how things are, you can put things back to how they started by right clicking on the "NHM" button in the top right (by the house icon), and choosing Reset:

You can also bring back individual views if you have closed them by looking in the Window menu:

Finally in the middle of the window is the editor area. This is where your scenario text will be displayed. At the moment it is empty, because there is no scenario open. We will remedy this by creating a scenario to edit.

An NHM scenario is just a text file, so you could edit all your scenarios in Notepad¹¹. However, the NHM application knows about the syntax for scenarios, and so can help you with your editing.

If you have a lot of scenario files in your workspace, or a lot of template definitions, getting between them can be tiresome. The application offers a key to jump quickly to a particular file, Control-Shift-R (all three keys at once). To find a specific template, you can press Control-Shift-T.

You have already seen how to open multiple editors, and switch between them by clicking on their tabs. You can also look at two (or more) editors at once if your screen is big enough, by dragging their tabs around on the screen. Try opening two editors, and then dragging the tab for one of them to the right hand side of the editor area. You should see a black rectangle showing where the editor will go if you let go, and when dragging to the right this should take up half of the editor area on the right. Let go, and you will have two editors open next to each other.

The above lets you open two files side-by-side or above each other. Sometimes you want to open one file, but see two parts of it at once. You can do this by typing Control-Shift-Minus (Control-Underscore), or Control-Left Brace (Control-Shift-Left Bracket), or looking in the Window, Editor menu.

The application has all sorts of other useful functions, like search and replace across multiple files, local file history, team-working using git, comparisons between two files and so on. These functions can be hard to find, just like in any other program. Fortunately there is a quick way to search all the things the application knows how to do - the quick access box. This is the text box shown on the right hand side of the toolbar near the top of the window. Typing in here will pop up a list of all the commands, settings, help topics and so on that the application knows; for example, here is what happens if you type in "Run".

You can see a list of views that could be displayed on the screen, commands that can be taken in the current context, and preferences that you could change. You can focus the quick access box by pressing Control-3, so it is a quick way to do things for which you have forgotten the commands.

As well as context sensitive help within scenarios, the NHM application also provides the scenario language manual. You can get to this by choosing Help Contents in the Help menu. This will either open the help in a new window, or within the application, depending on your operating system. In either case, the help will look something like this:

The "book" icons on the left are documentation for different parts of the application. You may have more such books than are shown in the screenshot, but you should have one entitled National Household Model. Clicking on this will show you the full manual for the latest version of the model that your application contains. This is where you can find the changelog, which will tell you about any recent changes to the model that you should be aware of.

The other documentation categories may tell you about

• Using EGit, the git client built into the NHM application
• The general principles for the application interface

The NHM application is based on some software called Eclipse, which is what does the work of drawing windows on the screen, managing projects and so on. It has its own help section and terminology, and many of the menus and dialogs will refer to things using these words. Here is a quick list of a few of these words and what they mean:

Workspace

The workspace is a folder on your computer. The application looks in this folder for scenarios and projects. You can have more than one workspace, but you can only use one workspace at a time. It also holds special files containing any settings that you have changed in the application while using that workspace (for example, if you have changed the editor colours).

Project

The workspace contains projects. These are folders within the workspace folder which contain other files and folders. Every file in the application must belong to a project. They are the organising unit of work for the NHM application.

Resource

Sometimes the application will refer to "resources". This is its generic term for files, folders and projects.

Workbench

The main application window is called a "workbench window". You can open more than one workbench window by choosing Window, New Window. Every workbench window has a menu bar at the top tool bar, and an editor area in the middle which may be surrounded by views.

Editor

An editor is a part of the interface responsible for opening and maybe changing a file. The application contains different editors for different sorts of file, like the scenario editor for .nhm files. Editors appear in the editor area of a workbench window.

View

A view is a part of the interface which displays some information but is not an editor. The Project Explorer is a view. Views are arranged into panels which surround the editor area.

Perspective

A perspective is an arrangement of views and other icons in the interface. You will normally use the NHM perspective. This is indicated by the NHM button on the right hand end of the tool bar. You can use this to reset all the views to their default arrangement by right-clicking.

Content Assist

Content assist is the pop-up suggestions that appear when you press Control-Space.

Platform

The "platform" refers to the underlying machinery which makes the application work.

Plugin / Feature

A plugin is a bit of code which adds some behaviour to the application. A feature is a collection of plugins. For example, all the NHM related behaviour in the application is provided by a feature which is added to the bare minimum Eclipse needs to work. EGit is provided by another feature.

Describe in detail what you think the example scenario above does when the model runs. Do not do this by guessing from what's written down; instead, look in the manual or use the context-sensitive help to read the documentation for each term that is used. Remember that the model is stupid, and only understands the scenario insofar as it is programmed to blindly perform certain calculations in response to it. Compare your answer to our description below.

This scenario simulates the following sequence of events:

1. Loading the stock
   1. The stock is loaded from my-houses.stock, starting in 2015. This means that whatever houses whose build year is before or equal to 2015 will be considered to exist at the start of the run; houses built in subsequent years will be constructed at the start of their build year.
   2. The scenario has no quantum: or weighting: specified, which means it will take the defaults of 400 and Uniform. As a result, the cases in the stock will be represented by simulated houses with weights of around 400, but most cases will probably produce houses with a slightly lower weight. Any cases whose weight is less than 400 will just be one house, with that weight.
   3. There is a default tariff defined by context.tariffs; whenever a house is constructed it will get put on that tariff. Since nothing else speaks about tariffs, all the houses will be put on the tariff.
   4. All other details are unspecified, and so fall to defaults; houses will be given a standard heating schedule, weather conditions, and so on. These defaults are described in an appendix to this document.
2. Now we get to things which are going to be simulated. All of these things happen each year, from 2015 to 2020.

   1. Firstly, we have the events caused by the on.dates rule; these will happen at the start of the year because:

      • The scenario dates are specified as years; these are shorthands for the first of January in each year
      • The on.dates happens regularly, which defaults to the anniversaries from the start date until the end date.

      This rule says to do two things, an apply and an aggregate. The apply will always happen before the aggregate in each year, as they are written in that order.

      1. The apply will first compute the set of houses defined by its to: argument. This is the job of sample, which will compute a subset of its second argument thus:

         • sample asks filter to produce a set of houses, which in turn asks all-houses.
         • all-houses produces all the houses that currently exist, and gives them to filter;
         • filter looks at each one of those houses and asks (house.built-form-is Detached) about them, keeping the ones where that is true. It gives these detached houses back to sample.
         • now sample has all the detached houses, it picks a random subset having 5% of their weight, and gives this back to apply

         Now apply has a set of houses to work on. It shuffles them into a random order (this doesn't matter for this scenario, but it could), and goes through them one at a time. For each house, it asks the measure named #my-insulation to operate on the house if possible. The measure is defined up above the apply, by def-action; you could just as well write the measure directly in the apply

         The measure, when presented with a house, does the following:

         • Checks if the house is suitable for the measure, according to the rules detailed in the manual. In this case, the measure is cavity wall insulation, so the house must have a wall without cavity insulation whose construction type indicates a cavity is present.
         • If the house is not suitable, the measure fails, and the house is unchanged. apply does not care about this, and moves on to the next house.
         • If the house is suitable, the measure computes its size, and makes that available as size.m2; this is the sum of the area of all the suitable walls.
         • Then the measure computes the capex: rule; in this case fifty times size.m2, plus 100. Once the capex: rule has produced a result, the measure causes a transaction from the house to the market of that amount, so the house has paid for the measure.
           • Because we have report.transactions turns on at the bottom, this transaction will be recorded in the transaction log.
         • Finally the measure changes the description of the house in some way; in this case, as it is an insulation measure, it goes to each suitable wall and:
           • Marks the wall as having 50mm of cavity insulation
           • Computes it a new u-value as \(u' = 1/(1/u + (0.01 \times 50))\); this is the resistance of the insulation (its unit resistance times thickness), plus the resistance of the existing wall (\(1/u\)), converted back to a u-value.

         Once the measure has happened, the house's energy calculation result and so on may be different, as its thermal properties may have changed. Important things to note here are:

         • The to: argument of apply did not know about the measure; it has blindly picked some houses, so whether or not they are suitable or have already had a measure before does not come into it unless you ask for it to. So, if you ask to apply a measure to a sample containing 10,000 houses, unless you have already made sure they are suitable, you may not install 10,000 measures.
         • The way the sample is written is important; 5% of detached houses is not the same as those houses which happen to be detached from a 5% sample of all the houses.

      2. Now that apply is finished and probably changed some houses, on.dates will tell the aggregate to do its thing. When the on.dates sets the aggregate off, it will go through each of its over: sets and ask them to compute themselves. In this case, it will always be all-houses (since we are using the default), which is just all the houses that exist at the point.

         Next, the aggregate will ask each of the aggregation rules it contains to compute a value for each of these sets. In this case, we have aggregate.mean; aggregate will present aggregate.mean with the set of houses produced by all-houses. aggregate.mean will then go to each house in that set and present it to house.energy-use, which will produce the energy calculator's estimate of energy use. aggregate.mean takes all of these values and computes a weighted average of them, which is what it gives back to the aggregate.

         Finally the aggregate will write down that value against the simulation's current date and the name of the set, so in this case a row will be produced in a report for group all-houses containing the current mean energy use.

   2. Along with the explicit on.dates rule written in the scenario, there are two automatic rules which happen at the end of every year: houses pay their opex costs for particular technologies they have installed, and they pay their fuel bills according to their current tariffs. In our scenario there are no opex costs set up, so we can ignore that. However, we do have a tariff, so:

      For each house, at the end of the year, the tariffs are computed. All our houses are on a single tariff, which charges 5p per kWh of mains gas used. When the tariff is computed, all the charges it contains are calculated, and these produce transactions according to the relevant amounts.

      In our scenario, these will be visible only in the transaction log report, which we have enabled.

3. The simulation finishes on 01/01/2020; as a result we will see the final year's on.dates, but not the transactions for the tariffs which happen at the end of the year.

This is a detailed description of what happens, but it does not say much about what we would expect to see. Let us use our imaginations to guess about the effects we will observe in the outputs. For this we need to make up some statistics about our stock; let's say that there are 6 million detached houses, of which 3 million have uninsulated cavity walls. Let's also say that 80% of these houses are on gas and use gas as their heating fuel.

In the first year, we will sample 5% of the detached houses. This will give us 5% of 6 million, which is 300,000. These houses are as they were in the stock. Of these 300,000 we would expect roughly half to have an uninsulated cavity, by coincidence. However, we could get anything from 100% to 0% uninsulated. The actual distribution can be had with some elementary statistics, but the important point here is that the model didn't do anything clever to guess our intention. It just did the sampling as stated.

Anyhow, taking the expectation, we will go through these houses and about 150,000 of them will get cavity walls; they will spend some money, which we will see in the transaction log. The remaining houses will be unaffected.

Next the model will make our first year aggregate; this will just contain a single number for overall mean energy use. Again, we get what we asked for; the model does not guess that we wanted change in energy use and produce a baseline, so we cannot see the impact of our first year's efforts. Later chapters will explain more about how to report on the effects of measures in detail, and how to schedule things to happen at different times.

Now we come to the second year; again, we compute a sample of 5% of detached houses. This will be (with very high probability) a different sample to the previous year, but it may well intersect. We would expect about 5% of 5% to be in the intersection in this first year. As a result of this, the proportion which are uninsulated will have gone down a bit - to put it another way we are sampling 5% from a population which now contains (3 million - 150,000) uninsulated cavities. Note that our sample can still in-principle have any proportion of uninsulated houses, as there are more than 300,000 of each sort left to take.

Later chapters will explain how to avoid re-sampling by marking houses or targetting only suitable houses. Anyhow, in our second year we will in expectation insulate slightly fewer houses, and so we will see slightly fewer transactions.

The second year report will show some reduction in energy use; however, it will be quite small, as we are looking at the populatin total. Later chapters will explain how this report could summarise particular subpopulations so as to be more informative.

The end-of-year fuel cost transactions in the second year will also be slightly lower, for those houses which (a) have been insulated and (b) were gas heated.

In the third year, we will have insulated some more houses (although not quite as many in the second year), so our sample will be expected to contain yet fewer uninsulated houses; as a result the expected reduction in energy use and bills in the third year will be a bit lower than in the second.

This process will continue for subsequent years, with the energy use and expenditure asymptotically approaching the values expected for full insulation of cavities in detached properties. The expected shape of the curve is an exponential decay, as each time we shrink the population we are sampling from by a fixed proportion.

As you have hopefully discovered, this scenario does some things you might not want to do:

• It doesn't report on the direct effects of the measure being installed
• It doesn't avoid re-sampling houses that have been affected already

Try making some changes to get a better understanding of this (you may want to return to these questions after reading later chapters):

1. Amend the scenario to report on more details
   • Population level details about:
     • How many houses are suitable for the measure (house.is-suitable-for)
     • How many houses are likely to be in the target set for the apply (aggregate.sum, aggregate over:, house.is-suitable-for, filter, house.built-form-is)
     • How fuel costs are affected for these houses as well as energy use (house.fuel-cost)
   • House level details about the houses targetted (probe)
   • Summaries of the specific target set (probe.aggregate)
2. Amend the scenario to avoid re-sampling; there are two different ways to do this which mean different things:
   • Using house.flags-match and update-flags: to avoid affected houses
   • Using house.is-suitable-for to target only suitable houses in the apply

As mentioned above, when the model runs your scenario it does the following:

1. Sets the date to the start-date: of the scenario
2. Schedules things that are going to happen in the future
3. Does the scheduled things in date order, until the end-date: of the scenario is reached

A small number of things are scheduled automatically:

1. Loading the stock; this is always the first thing that happens
2. Paying fuel bills and operational costs; this always happens annually, at the very end of the year. There is more information about how bills and operational costs are determined in the sections on Money and Tariffs.

Everything else that happens must be scheduled to happen by something written in your scenario. The simplest tool for scheduling is a command called on.dates. If you look it up in the manual, you will see that it belongs at the top level in your scenario (i.e. as an argument to the scenario command), and that it expects:

1. An argument containing a list of dates, which say when something is to happen
2. A series of arguments which define things that should happen

You can think of on.dates as a device for attaching some free-floating things to do to some specific dates, so that the things will be done on those dates.

For example, you might write:

(scenario
 start-date: 01/01/2014
 end-date:   01/01/2020
 stock-id:   my-stock

 (on.dates
  [01/01/2014 01/06/2014 01/01/2018]

  (insulate-some-houses)
  (make-a-report)))

This scenario will schedule the following:

1. On 01/01/2014
   • Load the stock
   • Do the command insulate-some-houses (this is not a real command)
   • Do the command make-a-report (also not real)
2. On 01/06/2014
   • Do the command insulate-some-houses again
   • Do the command make-a-report again
3. On 31/12/2014, 31/12/2015, 31/12/2016, 31/12/2017
   • Pay fuel bills and operational costs; however, the default behaviour is that fuel and operational costs are zero, so effectively this does nothing
4. On 01/01/2018
   • Do the command insulate-some-houses for a third time
   • Do the command make-a-report for a third time
5. On 31/12/2018, 31/12/2019
   • Pay fuel bills and operational costs
6. On 01/01/2020 the simulation finishes

If you want different things to happen on particular dates, you can put more than one on.dates in a scenario. The scheduled dates are interleaved. Any ties are broken by the order in the scenario. For example,

(scenario
 start-date: 01/01/2014
 end-date:   01/01/2020
 stock-id:   my-stock

 (on.dates
  [01/01/2015 01/01/2010]
  (do-thing-A))

 (on.dates
  [01/01/2014 01/01/2010]
  (do-thing-B)))

Sets up the following schedule (ignoring fuel bills etc.):

1. On 01/01/2014
   • do do-thing-B (a made-up command)
2. On 01/01/2015
   • do do-thing-A (also made-up)
3. On 01/01/2010
   • do do-thing-A again
   • do do-thing-B again; this comes second because it is second in the scenario

The reason questions of scheduling are important is the same as why scheduling is important in the real world: the things which have already happened determine how things are now, so doing A then B may not have the same result as doing B then A. If B is producing information in a report and A installs some measures, A then B will show you the outcome of doing A, whereas B then A will show you how things were before doing A, and then install the measures, without telling you anything about it (doing B then A then B again will show you before and after, of course).

Now we come to what sort of thing can you put in on.dates to make something happen; there are a few options, but the most useful one is probably apply. The manual for apply will tell you that it expects two arguments:

1. An action to apply as the first argument
2. An optional named argument to: which is a command to select a set of houses

apply can be thought of as a device for gluing a free-floating thing that you want to do to a population of houses. Putting this together with on.dates you can create an instruction to do a given thing, to a given population, on some particular dates:

(scenario ; start date etc. omitted
 (on.dates
  (scenario-start)
  (apply
   (some-action)
   to: (some-houses))))

A lot more detail is given on what kind of thing you can use in place of (some-action) or (some-houses) later on. For now, let's omit to: (some-houses) entirely (the manual explains that the default for to: is (all-houses), which unsuprisingly represents all the houses in the model), and focus on (some-action).

An action is the broad term for something in the model which does something to a house; this includes

• measures, which are actions that represent an installation of some technology in a house. Examples include:

  • measure.loft-insulation and measure.wall-insulation, which would insulate the loft or walls respectively
  • measure.standard-boiler and measure.heat-pump, which would install a new boiler or a heat pump

  As you can see, most measure commands begin with measure.; this has no special meaning to the model, it's just to make the names distinctive.

• Actions which put other actions together; for example you might want to install a package of several measures together, or choose between some alternatives
• Actions which output information about the condition of a house, which are covered in the next section.

As mentioned, by default apply will operate on all the houses in the model. You can also use the commands filter, union, sample, and bernoulli to select subsets of the population.

filter is a command which will produce a set of houses by using another logical test (true-or-false) command on each house, and only keeping those houses which pass the test. For example

(apply
 (some-action)
 to: (filter (house.has-loft) (all-houses)))

will apply some-action only to those houses which are (a) in all-houses (i.e. all the houses) and (b) for which house.has-loft is true. house.has-loft is an example of a boolean function or test. You can think of what happens here as:

1. something triggers the apply (probably on.dates)
2. apply asks (filter ...) to produce a set of houses to act on
   1. (filter ...) asks (all-houses) for a set of houses, getting back all the houses
   2. filter goes through each house in turn, and asks house.has-loft about that house
   3. filter responds to apply with the houses which passed the test
3. apply shuffles the houses that were chosen into a random order
4. apply goes through each chosen house in turn, and asks (some-action) to operate on that house

If you are looking for a particular number of houses, but you don't mind exactly which ones, you can use sample; it will sample randomly from a set of houses to produce a result of a certain size. For example

(apply
 (some-action)
 to: (sample 15% (all-houses)))

will take the houses in all-houses, pick a random subset of them whose size is 15% of the total, and then apply some-action to them in a random order. sample will interpret samples of size less than 1 as proportions (15% is equivalent to 0.15, as far as the model is concerned), and samples of size 1 or more as counts, so

(apply
 (some-action)
 to: (sample 1000000 (all-houses)))

will take the houses in all-houses, pick a random subset of them whose size is 1 million, and then apply some-action them in a random order.

You can combine sample with filter by using one as an argument to the other; for example

(sample 10% (filter (house.has-loft) (all-houses)))

produces a random 10% of those houses which have a loft. This is not the same as

(filter (house.has-loft) (sample 10% (all-houses)))

which instead takes a random 10% of all the houses, and then retains only those which happened to have a loft; the size of the second of these will probably be smaller than the first. When reading this, you can see that the command with the deepest number of brackets is worked out first; this is always true for the sampling commands (their precedence is as though for arithmetic).

If you want to sample houses at random using a per-house probability, you can use the bernoulli command. It is like a probabilistic version of filter. Where filter expects a logical function about a house and uses it to deterministically rule the house in or out, bernoulli takes a numerical function about a house, and uses it to compute a probability that the house will be included or excluded. For example

(apply
 (some-action)
 to: (bernoulli 10% (all-houses)))

does the following:

1. again, on.dates will trigger the apply on some dates
2. on.dates asks bernoulli for some houses
   1. bernoulli asks all-houses for some houses, getting all the houses
   2. for each of these houses in turn, bernoulli produces a uniform random number from 0 to 1; if the number is less than or equal to 0.1, the house is included, otherwise it is excluded
   3. bernoulli returns all included houses to the apply
3. apply takes each included house in turn, in a random order, and asks some-action to act on the house

The difference between bernoulli with 10% and sample with 10% is that bernoulli may pick more or less than 10% - it could pick 100% or 0%, if the random numbers came up right. In contrast, sample will always pick 10%³.

Along with things scheduled using on.dates, there are a few things which are scheduled 'automatically' by the model. We have already touched on opex and bills, which are processed at the very end of each year. The scenario can also contain 'global' carbon factors and weather, which can be functions of time. If one of these is a function of time, the simulation will contain some automatically included events when the carbon factors or weather would change.

1. Referring to the manual and using your knowledge of energy modelling, what are the significant differences likely to be between the following measure applications?

   1. Naive:

      (apply
       (measure.standard-boiler
        size: (size (house.peak-load))
        capex: (* 100 (size.kw)))
       (measure.wall-insulation
        capex: 500       type: cavity
        resistance: 0.01 thickness: 50))
      

   2. Less naive:

      (apply
       (measure.wall-insulation
        capex: 500       type: cavity
        resistance: 0.01 thickness: 50)
       (measure.standard-boiler
        size: (size (house.peak-load))
        capex: (* 100 (size.kw))))
      

   3. Package:

      (apply
       (do all:true
           (measure.wall-insulation
            capex: 500       type: cavity
            resistance: 0.01 thickness: 50)
           (measure.standard-boiler
            size: (size (house.peak-load))
            capex: (* 100 (size.kw)))))
      

   Hints:

   • Higher up things tend to happen first
   • Things which happen first can affect what comes after, but not vice-versa
   • Packages affect suitability

2. Consider the following partial scenario, in which A, B, C, D, E, F, and G represent things that are to happen (e.g. application of measures, running reports etc.)

   (scenario
    start-date: 2005
    end-date:   2011
   
    (on.dates scenario-start A)
    (on.dates scenario-end B)
    (on.dates scenario-start C)
    (on.dates repeatedly E)
    (on.dates 1990..2015 F)
    (on.dates [2005 01/05/2010 02/01/2011] G))
   

   In what order and on what dates are A to F performed; note that some of them may happen more than once and some may happen on the same date but still have an order.

1. For each of these sampling commands, give a description of the sample that is produced which states the range of sizes of the sample, and anything else you may know about the houses in the sample.
   1. (sample 50%)
   2. (bernoulli 50%)
   3. (sample 50% (filter (house.region-is London)))
   4. (filter (house.region-is London) (sample 50%))
   5. (filter (house.built-form-is Detached) (filter (house.region-is London)))
   6. (union (filter (house.region-is London)) (filter (house.built-form-is Detached)))
2. Write a sampling command to produce:
   1. The set of all the houses
   2. A random 5% of all the houses
   3. A random 100,000 houses
   4. All the houses in the South West
   5. 20% of the houses in the South West
   6. 20% of the houses in the South West and 10% of the houses in London
   7. 30% of the houses in the South West and in London
   8. A set in which each house has a 5% chance of membership
   9. A set in which a house's chance of membership is given by its floor area, clamped to 100.
   10. All the detached houses
   11. All the detached houses in the south west
   12. A set of detached houses, taken from a 10% sample of all the houses
   13. 10% of the detached hosues

There are four commands for producing reports which you are most likely to use:

1. aggregate, a command which outputs summary information about populations of houses. This is useful for keeping track of high-level trends in your scenario.
2. probe, a command which outputs information about individual houses. This is useful for generating detailed data which you can process using other tools, or for digging into what is happening when the model produces confusing results.
3. probe.aggregate, a command which produces summary information about the impact of a specific action on a population of houses. It is the summarising analog for probe.
4. def-report and the report: keyword, which are relatively new commands that combine the features of aggregate and probe.

We will consider these in order

The aggregate command is analogous to apply in that it should be used within on.dates. Where apply uses a sampling command to find a population of houses, and then does a measure to them whenever the surrounding on.dates tells it to, aggregate uses some sampling commands to find some populations and then uses some aggregation commands to work out summary statistics on those populations when the surrounding on.dates tells it to.

The general form of aggregate is:

(aggregate
    name: <<the name of the report file to produce>>
    over: [ <<a list of sampling commands>> ]
    divide-by: [ <<a list of cutting variables>> ]

    << a series of aggregations, like aggregate.count, aggregate.mean, etc. >>
)

When an aggregate is triggered, it does the following:

1. Compute the populations indicated by over:
2. For each population, for each dwelling in the population, work out the divide-by: values
3. For each sub-population induced by divide-by: values:
   • For each aggregation contained in the aggregate, work out that aggregation and record it in the result against the current date, the over: population and the divide-by: values.

For example, here is a very simple aggregate:

(aggregate
    name:example-1
    over: [(all-houses)]
    divide-by: []

    (aggregate.count name:count))

Let us say this is triggered at the start of the run on 01/01/2020; what happens is:

1. The set (all-houses) is computed, which is all the houses
2. The divide-by: values are used to cut up all-houses; there are none, so it is not divided
3. The resulting set, which is just all houses, is presented to aggregate.count, which produces the total weight

4. This value is written down as a row in the report example-1, as follows:

   Date	Group	Count
   01/01/2020	(all-houses)	24000000

If the on.dates was set to trigger on several dates, each date would add a row to the table, producing something like:

As we just saw, using aggregate to determine exactly what is going on in a scenario can be quite difficult, and it is not intended for producing results that go down to house level¹³. To help with this, the model offers the probe command. We have already seen the pattern of putting a command around another command of the same kind to change its behaviour with sample, filter and aggregate.where; probe follows this pattern, but for an action that you are applying to a house. Putting a probe around another action changes the action's behaviour so that it also makes a report which describes what happened whenever the action gets used.

For example, imagine we are installing a new boiler in some houses; the command for this is measure.standard-boiler, so our scenario might have something like this in it:

...
(on.dates ...
    (apply to: (sample 100000)
           (measure.standard-boiler fuel:MainsGas winter-efficiency: 85%
                                    update-flags: affected))
    (aggregate name: heating-systems
           divide-by: [house.main-heating-system-type house.flags]
           (aggregate.count)
           (aggregate.sum (house.energy-use))))
...

This example uses flags, which are described later on; here it suffices to say that when a house get a boiler it will also be "marked" as affected, and that mark will appear in house.flags which is being used to divide up the population in the aggregate.

We are hoping to install 100,000 boilers every year, and expecting that the overall energy use will go down by some amount. However, when we run the scenario, we have two problems:

1. We don't seem to be installing 100,000 boilers every year, and
2. The effect on energy use is not as much as we thought.

It seems that what we have told the model to do is not quite what we intended!

One way to diagnose this kind of problem is to use probe; as described it goes around an existing measure or action. In this scenario there is only one measure, which is the boiler, so we amend the example to include a probe; probes have the following form:

(probe name:<<name of report>>
       capture: [ << list of values to record>> ]
       <<another measure or action>>
       )

so adding the probe around our existing measure we get:

...
(on.dates ...
    (apply to: (sample 100000)
           (probe name:boiler-investigation
                  capture: [
                      (house.main-heating-system-type name:h)
                      (house.flags name:f)
                      (house.heating-efficiency measurement: winter
                                                of: PrimarySpaceHeating
                                                name: e)
                  ]
                  (measure.standard-boiler fuel:MainsGas winter-efficiency: 85%
                                           update-flags: affected)))
    (aggregate name: heating-systems
           divide-by: [house.main-heating-system-type house.flags]
           (aggregate.count)
           (aggregate.sum (house.energy-use))))
...

You can see that the probe surrounds the measure, occupying the space it used to occupy; from the point of view of the other elements of the scenario, the probe is kind-of "transparent", in that the meaning of the simulation itself is unchanged. However, from our point of view the simulation is changed, in that we will have a new output file called dwelling/probe-boiler-investigation.tab, which will help us in our diagnosis. If you write a scenario like this now and run it, you will see that file contains some output of this form (some columns omitted for space reasons):

Each row in this table corresponds to a moment in the simulation when a particular simulated dwelling was sent to the probe by the apply as a result of the on.dates triggering it. You can see that every row contains the date at which the change is happening, a sequence number, the unique ID of the dwelling which is being considered, and the weight of that dwelling so that you can make weighted calculations if you need to. As well as these values, each row also contains (1) the values given to capture: about the house before the measure within the probe got applied, (2) an indication of whether the measure succeeded or not, and (3) when the measure did succeed columns providing the capture: values after the measure's application. In the example table above, you can see one dwelling was presented and got a measure (dwelling 1234), and another was presented and was not suitable (5678). This report can therefore show us exactly which houses were considered, and how (if) they were affected.

In our hypothetical conundrum we might analyse the table and notice the following:

1. On each chosen date, around 100,000 dwellings were presented to the probe; the sum of the weight column would be 100,000 when grouped by the date column
2. However, under 100,000 dwellings had a successful measure installation. This explains why the aggregate contained a lesser effect than we expected.
3. We might then filter the results to show only the cases where the measure did not install, and look for regularities. We might see that most of these houses have electric heaters of some sort; perhaps they are off the gas grid, and so not eligible for a gas boiler?
4. Finally, we would notice that in later years we are operating on some houses which already have an 85% efficient mains gas boiler, and for which house.flags includes affected. This would remind us that the sample command does not automatically understand that we want non-overlapping samples between years.

probe and aggregate were both added fairly early in the development of the model, and are a quick and efficient way to inspect bits of a scenario. However, if you find that you want to probe a lot of actions, and also want some summary statistics produced for the same outputs, they can become quite tiresome to write down. The def-report, which was added more recently, gives an alternative way to report on houses. You use it by defining a report in one place (in the top level of the scenario), and then by sending houses to that report from other places where you want to know what is going on.

Defining a report is a matter of using the def-report command, which has the general form:

(def-report <<name of report>>
    (column ...)
    (column ...)
    (cut ...)
    (cut ...))

So for example, if we wanted a report which told us about the built form and energy use of houses we might write

(def-report example-report
            (column name: built-form value: house.built-form)
            (column name: energy-use value: house.energy-use))

Each column here has a name:, which is the text used to name the column, and then a value which is a command used to compute the value for that column when a house is sent to the report. The easiest way to send a house to the report is to use the send-to-report action, for example:

(on.dates (scenario-start)
          (apply
            to: (all-houses)
            (send-to-report from:this-place #example-report)))

This is all similar to what you have seen before, except for the octothorpe (#) symbol written before example-report. It is used to indicate that the word example-report is a cross-reference to the report defined by the def-report we wrote above. In the NHM application's scenario editor, these cross-references will be coloured in differently to make them stand out. Since send-to-report is an action, we can put it inside apply like any other action, and it gets used on all the houses in the to: set; in this example, all the houses that exist. Each time a house is sent to a report, two things happen:

1. It is treated as though it were observed by a probe command; in this case, a row will be entered into a file called dwelling/probe-example-report.tab which contains the built form and energy use for the house. In addition it will contain the from: argument for send-to-report, so that you can send houses to a report from several places and determine which rows came from where.
2. The values observed are summarised, and when the simulation date advances they may be contributed an aggregate summary of all the houses which were sent to the report since the last time the date changed. In our example, the summary will contain only the date, the from: column and a weighted count. However, you can add more summary statistics and aggregations by using the summary: argument of column and by adding the cut command into the def-report

As well as the user-defined reports you can produce with probe, aggregate, probe.aggregate, and def-report with report:, there are several built-in reports which produce other kinds of outputs that can help you analyse the results of a simulation.

1. Amend an existing scenario to include a report which allows you to answer these questions:
   1. How many houses are there in each region?
   2. How many houses are there of each built form?

   3. How many houses are there whose floor areas are

      • 0-10m
      • 10-100m
      • 100-1000m
      • 1000m-10000m and so on.

      Hint: you could use the log and round commands for this.

   4. For each of these categories, what is the mean energy use and emissions
2. Amend a scenario to emit a report from which you could scatter plot the relationship between floor area and modelled energy use by some different types of fuel.
3. Amend a scenario in which you install a measure to emit a report which tells you exactly which houses were affected by the measure, and what the measure's impact on their carbon emissions (house.emissions) was.
4. Amend a scenario in which you install a measure to emit a report which tells you how many houses were affected by the measure, and what the measure's summed impact on their carbon emissions was, broken down by built form.

Before we come to the details of each measure, let's revisit how the energy calculator thinks about insulation. Insulation is important to the energy calculator because it affects the specific heat loss of the building; roughly speaking this is worked out as

\[ H = V + \sum_s A_s \cdot U_s \]

Where the sum is over external surfaces \(s\), and \(A_s\) is the surface's exposed area and \(U_s\) the u-value of the surface. \(V\) is an additional term covering heat losses due to ventilation, which is not so interesting here.

This value \(H\) is important because it is (roughly speaking) proportional to the heat required in the house, and so the fuel that must be burned to meet that requirement; halving \(H\) will roughly halve the fuel inputs for space heating.

In each modelled house, there are various external surfaces which contribute to the sum above:

• Walls
• Windows
• Doors
• Floors
• Roofs

For each of these, the model has a stored u-value and area⁵, and some information about what kind of insulation is present. When an insulation measure is applied to a house, it will change the u-value and the information about what kind of insulation is present.

You may be used to thinking of insulation in terms of a final u-value; in the interests of verisimilitude, the model prefers to use r-values (resistances). An r-value is simply the reciprocal of a u-value, but the important thing is that r-values can be added together; imagine you are applying the same insulation to two different walls. The first wall has very poor thermal performance (let us say a u-value of 10), whereas the second has good thermal performance (\(u = 0.5\)). Let us also say that the insulation material on its own has a u-value of 1 (neither excellent nor terrible).

The u-value of the wall after insulation should clearly not be the same in both cases; instead it is determined by the combined performance of the wall with the new material. The best-case value for this is the sum of the two layers' thermal resistances, so for wall 1:

\[ u' = \frac{1}{1/10 + 1/1} = 0.91 \]

whereas for wall 2:

\[ u' = \frac{1}{1/0.5 + 1/1} = 0.33 \]

Those measures in the model which add insulation to an existing surface are usually controlled by a (per-unit-thickness) resistance: and thickness: arguments, which are multiplied together to get a total resistance, which is then used to modify the existing u-value of the surface. In these cases you can specify a final u-value function if you prefer, in which case the impact of the insulation is independent of the initial condition of the wall.

Those measures which replace an existing insulated element (like glazing) are controlled by a simpler u-value, as the old material is being entirely replaced and so should not affect the end result.

Insulation measures also have some measure-specific rules around their suitability and the parts of a house which they affect:

When an insulation measure is installed, it temporarily records the area which was insulated and makes it available through the size.m2 command. The value of size.m2 is particular to the measure which contains it in the scenario; it is not a record of the total area insulated so far or anything, but is an ephemeral value which should be used during the installation of a measure or package.

To make this more explicit, if you write

(measure.wall-insulation ... capex: (* 100 size.m2))

When the capex: rule is worked out, size.m2 will produce the area insulated by this application of this measure to the current house.

Similarly, if you write:

(apply (measure.wall-insulation ... capex: (* 100 size.m2))
       (measure.loft-insulation ... capex: (* 200 size.m2)))

The capex: rule for wall-insulation will be 100 pounds per square meter of wall insulation installed by the wall insulation measure, and the capex: rule for loft insulation will be 200 pounds per square meter of roof area that was insulated.

This hopefully illustrates how the value of size.m2 depends on where it is written. A side-effect of this is that if you write something like this:

(aggregate name: total-area
           (aggregate.sum size.m2))

To report on "total insulated area", this will not work; as far as the model is concerned, this means something like "report on the total area insulated by doing this report", which unsuprisingly is zero. If you wish to report on ephemeral values like size.m2, you must do one of two things:

1. Report on them using a probe in the right context:

   (probe capture: [size.m2]
          (measure.wall-insulation ... ))
   

   or

   (probe.aggregate capture: [(sum size.m2)]
                    (measure.wall-insulation ...))
   

2. Store the ephemeral values into a variable from the right context, and then refer to them later:

   (do (measure.wall-insulation ...)
       (increase #insulated-area size.m2))
   

   The do and increase commands and variables have not been met yet, so you will have to skip ahead for more on these.

The cost produced by the capex: rule is available using the command capital-cost, which has the same behaviour; capital-cost is the capital cost of the command containing it, so reporting on capital-cost is asking for the capital cost of the report.

There is more about this in the section on money.

Offering insulation measures is no different to using any other action: you use the apply command to try and put the measure into a population of houses. Each measure has slightly different parameters; here are some examples:

1. Wall insulation:

   (apply (measure.wall-insulation
               type: cavity
               thickness: 50
               resistance: 0.002
               capex: (* 10 size.m2)))
   

   In this example we are offering wall insulation any construction that has a cavity. If any house has a wall with a cavity which is not already insulated, the wall will be marked as having 50mm of insulation, and its u-value changed by adding a resistance of \(50 \times 0.002\). The house will incur a cost of ten pounds per square metre of wall that was changed.

   You can directly specify a u-value instead, if you do not want the initial condition of the wall to matter:

   (apply (measure.wall-insulation
                 type: cavity
                 thickness: 50
                 u-value: 0.2
                 capex: (* 10 size.m2)))
   

   The u-value, resistance and thickness arguments can all be given formulae instead of constants, which will be worked out each time the measure is used. Here is an example using a table of u-values which depend on the build year of the house:

   (measure.wall-insulation ...
           u-value: (~lookup-table
                       row-keys: house.sap-age-band
                       [age  u-value]
                       [A    2]
                       [B    1]
                       [C    0.5]
                       [D    0.25]
                       [E    0.1]
                       [*    0.05]
                       ))
   

2. Loft insulation:

   (apply (measure.loft-insulation
               thickness:  300
               resistance: 0.02
               capex: 500
               top-up: false
          ))
   

   In this example, we will install 300mm of loft insulation on any suitable roof which currently has no insulation at all (the top-up: argument determines this). The u-value will be updated by adding a resistance of 300 * 0.02, and the house will pay a flat fee of 500 pounds.

   When using top-up: true, the u-value will be updated by adding the resistance (300 - existing thickness) * 0.02.

3. Glazing:

   (apply (measure.install-glazing
               frame-factor:0.8
               capex: (+ 100 (* 50 size.m2))
               frame-type: metal
               gains-transmittance: 0.9
               light-transmittance: 0.9
               glazing-type: triple
               insulation-type: lowehardcoat
               u-value : 0.2
          ))
   

   As you can see, glazing has more parameters than other forms of insulation; this is because of its effect on internal gains and lighting usage in the BREDEM calculation. You can find sensible values for these parameters in SAP; the defaults used by the model if you do not specify values do not appear to be sensible as of this writing, so leaving them out is not a good idea. In this example, we will install some triple glazing with a u-value of 0.2, at a cost of 100 pounds plus 50 pounds per square metre of windows installed.

   The measure will replace all the windows in the dwelling with windows of this standard.

   To give a quick summary:

   frame factor

   the amount of the window area not taken up by the frame (and so passing light and heat)

   frame type

   the material the frame is made of; this has no direct effect, but needs to be recorded as you may want it later if you wish to impose different u-values on a house and these depend on the frame type

   gains transmittance

   a factor indicating what proportion of heat from the sun is included into the calculation of solar gains

   light transmittance

   a factor indicating how much light from the sun passes into the house, which has a small effect on the lighting demand

   glazing type

   the kind of glazing; as with frame type, this has no direct effect

   insulation type

   akin to glazing type and frame type

   u-value

   the thermal property of the window, which is significant

There are various commands which you can use to find out about insulation state, either for reporting purposes or to use to change scenario behaviour. These are all documented in more detail in the manual, but here is a summary list:

house.double-glazed-proportion

produces the proportion of a house's glazing which is double glazed or better.

house.floor-insulation-thickness

produces the thickness of any floor insulation

house.loft-insulation-thickness

produces the thickness of any loft insulation

house.predominant-wall-type

produces the predominant wall type; this is the wall type which has the greatest external area

house.floor-construction-type

produces the type of floor construction for the ground floor

house.roof-construction-type

produces the type of roof construction

house.has-loft

tests whether a house has a loft or not

house.any-wall

a complex test which lets you determine whether any of the walls of a house satisfy conditions you are interested in. For example,

(house.any-wall has-cavity-insulation: true)

Will tell you whether the house has any walls for which there is some filled cavity insulation installed. Similarly

(house.any-wall has-cavity-insulation: false)

Will tell you whether the house has any walls which do not have cavity insulation (including those walls which cannot have cavity insulation).

(house.any-wall has-construction: anycavity)

Will tell you whether any of the walls have a cavity; these can be combined, so

(house.any-wall has-construction:anycavity has-cavity-insulation:false)

Will tell you whether a house has at least one wall which currently has no cavity insulation, and has one of the cavity construction types.

house.all-walls

an analog of house.any-wall which only passes if every external wall a house has satisfies the conditions that you are interested in.

Here is a drawing of a normal terraced house; the front elevation is on the left of the drawing.

1. Work out its heat loss coefficient, as it is now (in this exercise we are disregarding some details; the extra height on storeys for the floor joists, ventilation losses etc; these factors are included in the model).
2. Based on this, work out the amount of power required from a heat source to maintain a 7 degree temperature difference with the outside
3. For each of the following measures, note which parts of the house change, and recalculate the heat loss coefficient and power to maintain a 7 degree temperature difference
   1. (measure.wall-insulation type: internal thickness: 50 resistance: 0.01)
   2. (measure.wall-insulation type: cavity thickness: 50 resistance: 0.02)
   3. Both of the above measures
   4. (measure.glazing type:double u-value: 1)
   5. (measure.glazing type:triple u-value: 0.2)
   6. (measure.loft-insulation thickness: 200 resistance: 0.02)
   7. All of the above measures

Heating measures are harder to describe than insulation measures. You might think of a heating system as a thing which meets a need for some amount of heat by converting some fuel at some efficiency. In this view, installing a new heating system might change a house's heating fuel and efficiency, and so convert the same demand for heat into a different demand for heating fuel.

Whilst this is superficially correct, in a BREDEM or SAP type calculation it is complicated by two considerations:

1. The choice of heating system may affect the demand for heat, for various reasons:
   • Moving from point-of-use hot water to central hot water will introduce distribution losses
   • Moving from an instantaneous combi boiler providing hot water to a standard boiler with a tank will introduce tank losses and primary circuit losses
   • Some combinations of heating system and heating controls will change the demand temperature in the house; SAP table 4e lists these kinds of adjustments, and SAP table 9 also makes such an adjustment based on the control type column.
   • The heating system responsiveness will change the demand temperature in the house; this is a dimensionless number between 0 and 1 which reflects the time a heating system takes to respond to demand for heat. Systems with a lower responsiveness are assumed to result in a higher average internal temperature. SAP table 4d gives the responsiveness for wet heating systems, and table 4a the responsiveness for other types of heating system.
2. The efficiency of the heating system may be adjusted according to one of a number of rules; SAP table 4c lists the adjustments that are used. In addition the efficiency used for boilers is usually a function of their winter and summer efficiencies, which are combined in the harmonic ratio of the space heating and water heating heat demands.

In the model, when you install a heating measure, some other changes will be made to ensure that the result makes sense:

• If installing something which requires a central heating system, and the house does not have a central heating system, a central heating system will also be installed. This reflects the cost of fitting pipework, not installing a boiler. Measures which may have this effect have an additional named argument system-capex:, which is used to determine the capital cost of installation.
• If installing something which requires a hot water tank, a new tank will be installed (even if there is an existing tank). The tank's insulation thickness and capacity are given by cylinder-insulation-thickness: and cylinder-volume: respectively.

Most heating systems have a notion of size; you can control this using the size: argument of the measure to enter a sizing rule. A sizing rule will typically look something like this:

(size min: 5 max:50
      (house.peak-load))

The size used is calculated from the first unnamed argument (in the example, this is house.peak-load, which is a reasonable choice. The peak load is the heat output required to keep the house warm on a cold day; by default to produce a 19 degree internal temperature against a -5 degree external temperature). The min: and max: arguments are optional, and restrict the measure's suitability.

The sizing rule is used in two ways:

1. It is calculated before calculating the capital cost or operational cost, and the result is made available via the size.kw command. This allows you to compute a size for a heating system, and then use it in the pricing rule to affect the price
2. As mentioned, the min: and max: arguments restrict the suitability. If the sizing function produces a value below the min: or above the max:, the measure will be unsuitable. This is intended to reflect the fact that some technologies do not work well or are not available in some sizes.

You can use any function for the sizing function, so you could combine house.peak-load with round to represent a technology typically available in 10kW increments:

(size max:50
   (round (house.peak-load) to: upper 10))

This indicates that we should take the peak load, but if it is 1kW we should round it up to 10, if it is 11kW we should round it to 20 and so on.

The commands for putting in new heating systems are:

• measure.standard-boiler This installs a standard condensing boiler, with a hot water tank and central heating system. The boiler will supply space and water heat.
• measure.combi-boiler This measure installs a condensing combi boiler, with a central heating system. You can specify a storage combi boiler using the storage-volume: argument. The boiler will supply space and water heat.
• measure.heat-pump This measure installs a heat pump, with a central heating system. The type of heat pump is given by the type: argument, and the efficiency by the cop: argument. The heat pump will supply space and water heat.
• measure.storage-heater This measure installs storage heaters for space heating.
• measure.room-heater This measure installs a secondary room heater.
• measure.warm-air-system This measure installs a warm air system; it can only ever replace an existing warm air system, so you can never increase the number of warm air systems in the stock.
• measure.district-heating This measure installs a district heating system; as far as the model is concerned, this is a bit like a boiler whose fuel input is CommunityHeat. The SAP rules about primary fuel inputs to community heat or CHP are not modelled, as there is no information about the kind of heat network a house would be connected to.
• measure.solar-dhw This measure installs a solar water heating system. The SAP / BREDEM model for solar water heating is complicated, and the output from the heater depends on the demand for hot water in a complex, nonlinear way. Roughly speaking, the useful output of the solar water heater is greater in houses with a geater demand for hot water. This presumably represents the fact that the heat output is of a relatively low grade, and so will be of most benefit if the tank is cold.

There are several commands which will tell you about the kind of heating system in a house.

At the start of the run, there are never any flags on any of the houses. Naturally our first question is: how do we put flags on some houses? The simplest way to do this is with the action house.flag:

(on.dates (scenario-start)
          (apply to:(sample 20%)
                 (house.flag flag-A flag-B)))

This will:

• Produce a random sample of 20% of all the houses (if this is unfamiliar, read the preceding sections)
• Go through that 20% sample and use the house.flag action on all of them
• This will mark each house with two flags, flag-A and flag-B. You can use any word (without spaces) for a flag, so flag-A and flag-B are indicative here. It could be house-of-interest, or boiler-has-failed or whatever you like.

Once a house has been given a flag, it will keep it until you remove it again. The model does not automatically do anything to the flags on houses, and it has no understanding of their names, so they are entirely your responsibility to manage. In this example, we have marked 1/5 of the houses, and that particular set will remain so marked until we change it. Because of this, if you flag some houses because they are in a certain state (for example, having a high energy use), the presence of the flag later in the run tells you that the houses used to have high energy use. This is useful, when you want to see how a population has changed, but potentially confusing if you don't bear in mind this is what's happening.

Now that you know how to put some flags on a house, we can look at how to find houses which have particular flags.

A house either has a flag or it doesn't, so the thing we are looking for is a logical test which will distinguish these cases. The test for this is house.flags-match, which will tell you whether a house has a certain combination of flags.

For example, to report on the set of houses having flag-A, we might write

(aggregate name:houses-with-A
           over: [
                 (filter (house.flags-match flag-A))
           ]
           (aggregate.count))

Here we are aggregating over: the set (filter (house.flags-match flag-A)), in which (house.flags-match flag-A) will be true for any house that has flag-A on it.

If you look in the manual pages for most actions and measures you will see that they accept the two named arguments test-flags: and update-flags:.

These let you do two things:

1. test-flags: tells the action that, before it is applied, it should check something about the flags on the house, and fail if they are not how you need them to be
2. update-flags: tells the action that, after it has succeeded (if it succeeds), it should modify the flags on the house so that they are a certain way.

For example, you could restrict a measure to work only houses with the flag flag-A like this:

(apply to: (all-houses)
       (measure.wall-insulation
            test-flags: flag-A
            ...
       ))

Note that this does not make the measure suitable for all houses with flag-A; it makes the measure unsuitable for all houses without flag-A, but if a house has flag-A but is already unsuitable it does not become suitable.

This argument accepts a list, so you can also write

(apply to: (all-houses)
       (measure.wall-insulation
            test-flags: [flag-A flag-B]
            ...
       ))

to restrict the measure to houses with both flag-A and flag-B.

The dual to this is update-flags:; say you wanted to mark a house when it had received some insulation from a particular measure, so that you could keep track of it later or report on it.

(apply to: (all-houses)
       (measure.wall-insulation
            update-flags: house-got-some-wall-insulation
            ...
        ))

In this you could refer to the set (house.flags-match house-got-some-wall-insulation), and it would contain any house to which the above measure was applied successfully. These houses would be guaranteed to have had some wall insulation.

If you wanted to split the population into houses which did and did not, out of the target population, you could write

(apply to:(sample 50%)
       (house.flag house-considered)
       (measure.wall-insulation ... update-flags: house-affected))

Now all the houses which were offered the measure (here a random 50%) will be flagged as house-considered, but only those which got insulation will be flagged as house-affected.

All of the commands which work with flags actually work with patterns for flags. A pattern is like a very short rule which lets you match a whole set of flags all at once. The simplest patterns are plain words, like we have already written; the pattern flag-A just matches the flag flag-A.

More complicated patterns can include some special symbols:

• the star symbol * will match any text. For example, the pattern flag-* matches any flag which starts with flag-, so if you say (filter (house.flags-match flag-*)) you would get houses flagged with flag-A and flag-B and flag-some-other-flag and so on.

  (filter (house.flags-match *)) gives the set of all houses which have got any flag on them at all.

• The question mark ? will match any single letter. For example, flag-? matches flag-A and flag-B, but does not match flag-XY because XY is two letters.
• You can write several alternatives like <X,Y,Z>. This pattern matches X or Y or Z.

These parts can be combined, so for example <X-,Y->* will match the flags X-, Y-, X-abcdef, Y-qwert, and so on and so forth.

You cannot use patterns when adding a flag to a house; for example if you were to say (house.flag *) to try and add all possible flags to a house, the model will not validate your scenario.

There is one other special bit of flag syntax; prepending an exclamation point ! to any pattern negates it. When testing a flag this means that no flags should match the pattern, rather than that at least one should. When changing a flag, this means that all flags matching the pattern should be removed.

Here are some examples:

• (house.flag !flag-A) - this will remove just the flag flag-A from any house it's applied to.
• (house.flag !flag-*) - this will remove all flags which start with flag- from any house it's applied to.
• (house.flag !*) - this will remove all the flags from any house it's applied to this is because * matches all the flags that are there, and ! means to remove them, because we are changing flags, rather than testing them.
• (house.flags-match !flag-A) - this will be true for any house which does not have the flag flag-A on it.
• (house.flags-match !flag-A flag-B) - this will match any house which does not have flag-A AND does have flag-B.
• (house.flags-match !flag-A !flag-B) - this will match any house which does not have flag-A AND does NOT have flag-B.
• (house.flags-match !flag-*) - this will be true for any house on which no flag starts with flag-
• (measure.standard-boiler ... test-flags:!got-boiler update-flags:got-boiler) - this will install a boiler in any house which can have a boiler and does not have the flag got-boiler. If it succeeds, and installs a boiler, then it will add the flag got-boiler to the house. Notice this means that this measure (in the absence of other commands to remove the got-boiler flag) can only be applied successfully once to each house.

Because you can check a flag with a logical test, you can use it in other places to do things like controlling the capital cost of a measure.

For example, imagine you were modelling the distinction between easy to treat and hard to treat cavities in the stock; the model does not know about this to start with. Firstly, you would write some code to decide about which houses are hard to treat:

(on.dates (scenario-start)
          ; set up HTT flag;
          (apply to: (sample 10% (...)) ; say a random 10% of some kinds of houses are HTT
                 (house.flag HTT)))

;; then later:

(apply to: (all-houses)
       (measure.wall-insulation ...
            capex: (function.case
                       (when (house.flags-match HTT)
                             1000)
                       default: 500)))

In this example we have defined the capex with the command function.case, which uses logical tests to switch between different values. Here it will be 1000 when the house has the HTT flag on it, but only 500 otherwise.

Note that for this specific case you might instead want to do something different in a real scenario, like having two variants of the measure defined:

(def-action htt-cwi
            (measure.wall-insulation ...
                    capex: 1000
                    test-flags: htt
                    update-flags: got-htt-cwi))

(def-action normal-cwi
            (measure.wall-insulation ...
                    capex: 500
                    test-flags: !htt
                    update-flags: got-normal-cwi))

This uses the def-action command which is explained later; this is just an example of something which you can model more than one way, and the 'right' way depends on what you are trying to do. You could either say that insulation is a measure, and in HTT houses it costs more, or you could say that HTT insulation is a different measure to normal insulation, which costs more and for which only HTT houses are eligible.

You can use (house.flags-match ...) as a value in any report, for example in the capture: argument of a probe, or as a test in aggregate.where, or as divide-by: in aggregate. There is another useful command, house.flags which produces all the flags on a house, separated by commas. This also accepts a pattern, to print all the flags which match the pattern. For example, if you wanted to see all flags starting with got- on a house you could output (house.flags got-*) and you would see a value like got-boiler,got-insulation if the house had those two flags on it. Similarly you could write (house.flags !got-*) to see all flags which do not start with got-

This is a useful thing to use in divide-by: or capture: if you have set up your measures to put a consistent pattern of flags on houses when applied.

Here are some patterns together with sets of flags. In each case, write down the following

1. Whether house.flags-match would be true, given the list of flags
2. What the value of house.flags would be in each case, if given the pattern
3. What the new set of flags would be if the patterns were used with update-flags: (if legal)
4. Whether the measure (action.do-nothing test-flags: [...]) would be suitable, if the patterns were filled in the space.

Whilst flags are defined just by being used, variables must be defined before you can use them. This is done using the def command, which always belongs directly within a scenario. def has the following form:

(def <<variable name here>> default: <<default value here>> on: <<where the variable lives>>)

Let's address the arguments in turn:

1. The variable name is the first positional argument, and it is required. It can be any word (including punctuation), and is what you will use to refer to the variable when changing or looking at its value
2. The default: argument defines a starting value for the variable. If you do not give a default:, accessing the variable before storing a value in it will cause the simulation to halt with an error (see 23.4).
3. The on: argument defines where the variable "lives"; there are three options:
   • house. A variable defined to be on: house may take a different value for each house; in this sense it is like a flag, except it stores a number rather than just being present or missing. This could be used to store something like the number of times a house has been considered by a policy, or the year when it was last given a subsidy, or similar.
   • simulation. A variable defined as on: simulation is the same for all houses; it is more like a counter to keep track of something shared by all the houses. For example, you might use a simulation variable to record how many of a certain measure are available. This is shared by all the houses, as there should be one supply chain for everyone rather than one for each house.
   • event. A variable defined to be on: event is like one defined on:house except it is ephemeral; each time an apply or aggregate or similar command completes, the value is forgotten and goes back to its default (if any).

Now that we know how to define a variable, we come on to how to use them. There are two ways to use a variable:

1. By accessing its value in a calculation or a report
2. By changing its value with an action

To access a variable, you merely refer to its name; if you like, you can prefix this with an octothorpe (# symbol) to make it clear that this is what you are doing.

For example, in this scenario:

(scenario
    ...
    (def my-variable on:house default: 10)

    (on.dates (scenario-start)
              (aggregate name: a-report
                         (aggregate.sum (+ 3 #my-variable))
                         (aggregate.mean #my-variable))))

Will produce two columns in the report:

1. The sum, which will be 13 times the number of houses modelled; this is because:
   • The default value of the variable is 10, and we do not change it anywhere
   • aggregate.sum is summing the value of the variable plus 3 over all the houses
   • ten plus three is thirteen.
2. The mean value of the variable, which is just 10, because again we have not yet changed it.

The key point here is that anywhere where we would write a number, or a function that computes a number, we can refer to a variable instead.

If the variable is defined as on: house, the value will be that for the house or houses being looked at, just as for other house-specific values like house.energy-use.

Dual to accessing a variable is changing it. There are three commands for changing variables, which are all actions

1. set For example, applying the action (set #x 3) will store 3 in the variable x
2. increase Applying (increase #x 10) is equivalent to (set #x (+ 10 #x)); it changes the stored value to be ten more than it is already.
3. decrease Decrease is the opposite of increase; (decrease #x 10) will reduce the stored value of the variable by ten.

Plugging some of these into our previous example we can make some changes to the variable before we report on it:

(scenario
    ...
    (def my-variable on:house default: 10)

    (on.dates (scenario-start)

              (apply to: (sample 5%)
                     (increase #my-variable 10))

              (apply to: (sample 10%)
                     (set #my-variable (* my-variable 1.1)))

              (apply to: (filter (house.region-is london))
                     (decrease #my-variable 1))

              (aggregate name: a-report
                         (aggregate.sum (+ 3 #my-variable))
                         (aggregate.mean #my-variable))))

Now there will be eight different states for the value of #my-variable' across the population, depending on membership of the two samples or the filter to London:

1. Unchanged, if not in London or either random sample, i.e. 10
2. 9, if in London but neither random sample
3. 11, if in the middle sample only
4. 10, if in the middle sample and in London
5. 20, if in the first sample only
6. 19, if in the first sample and in London
7. 22, if in the first and second samples
8. 21, if in the first asn second samples and in London

Estimating the values produced in the report is left as an exercise for the reader.

The values stored in variables can be taken from other calculations, and the set, increase and decrease commands can be used in any place where other actions might be used.

For example, to store the initial energy use for every house in a scenario, before any changes are made, you could write

(scenario
    (def original-energy-use on:house)
    (on.dates scenario-start
              (apply (set #original-energy-use (house.energy-use))))

    ;; later on

    (on.dates ...
       (aggregate name: impacts
          (aggregate.mean (- #original-energy-use (house.energy-use))))))

This illustrates how variables hold the values put in them at particular moments in simulated time. In this case, after being set, the #original-energy-use variable will not change. The house.energy-use command on the other hand will always reflect the current energy use, so by reporting on the difference we can see the change in energy use that has resulted for each house by whatever changes the scenario has so far wrought.

In principle you now know everything there is to know about variables in the NHM; in practise you may wish to refer to a few examples of how variables can be used. Before we come to that you should read the subsequent sections, in particular those about choices and packages and suitability and failure.

Examples of how to use variables to model particular effects are given in 22

For each of the following apply commands, describe the value or values of the variable #x after the apply is finished:

1. First

   (def x on:house)
   ...
   (apply (set #x (house.energy-use)))
   

2. Changing to simulation

   (def x on:simulation)
   ...
   (apply (set #x (house.energy-use)))
   

3. Using increase

   (def x on:house)
   ...
   (apply (increase #x (house.energy-use)))
   

4. Adding a default:

   (def x on:simulation default:0)
   ...
   (apply (increase #x (house.energy-use)))
   

5. With a function

   (def x on:simulation default:0)
   ...
   (apply (increase #x (* (house.weight) (house.energy-use))))
   

6. Referring to own value

   (def x on:house default:10)
   ...
   (apply (increase #x (* #x #x)))
   

Every house has a ledger of transactions. A transaction is a record of the transfer of an amount of money between a house and a named pool of money (representing something like the market, or a policy's spending) on a certain date. The ledger never contains transactions which have yet to happen; however, these can be predicted within the model if you wish to consider the future costs of an immediate action.

Transactions are caused by a few different things in the model:

Installing measures

Measures typically have a capex: argument, which accepts any number-valued command. When a measure is installed, if it succeeds, a transaction is made from the account of the house which received the measure to a ledger representing the market for all measures.

Operational costs

Some measures have an opex: argument, which takes a number. When the measure is installed, the this value will be calculated and stored in the house. Until the thing put in by the measure is removed by another measure (say if a boiler is replaced), the house will make a transaction for this operational cost once a year at the very end of the year. The house is said to have an obligation to pay its operational costs.

Fuel costs

Every year, at the end of the year (when the operational costs are also paid), the house has an obligation to settle for its energy use. This is done by evaluating the house's tariffs, which are discussed in more detail in the next section. A tariff has the opportunity to create a few different transactions for different parts of the bill.

Financial actions

The above are all of the built-in financial considerations in the model; however, if you wish to model other movements of money, there are various commands to do this:

• finance.with-subsidy, which encloses another measure and meets some or all of its cost with an immediate subsidy
• finance.with-loan, which encloses another measure and meets some or all of its cost with an immediate subsidy to be repaid over time as a loan
• finance.with-obligation, which encloses another measure and sets up an arbitrary obligation to pay some amounts in the future
• measure.with-additional-cost, which encloses another measure and adds an arbitrary extra transaction to it
• pay, which allows for the transfer of money between non-house entities.

The best way to make this subject concrete is to take an existing scenario (hopefully you have one by this point in the guide!) and add report.transactions inside the scenario command. This will produce a report containing the model's entire transaction log. Each row of this report shows everything the model knows about a transaction that has happened; the columns are:

payer

this is typically the ID of a dwelling, although money can be moved between policies

weight

this is the weight of the payer, which is usually the dwelling weight

date

the date when the transaction occurred

payee

this is the name of the entity which received the payment

amount

this is the weighted amount of money transferred

address

this is a slash-separated path in the scenario of the command which caused the transaction

tags

each transaction may have several tags on it which indicate something about the type of transaction; this is a comma-separated list of these tags. For example, any capital expenditure will have :CAPEX as a tag, any loan related transaction will have :loan, and so on.

For most questions about money whose results are not needed on-model, it should be possible to produce the answer by processing the transactions log using another tool.

Now we will look into the different commands which produce transactions, and the ways to ask about the costs of particular operations within the model, for specific reporting or for making decisions.

As mentioned, measures generate transactions to pay for their installation. All measures have a capex: argument; when a measure is installed, if it is suitable, it will compute its capex: after the installation is finished and immediately produce a transaction which causes the payment of that amount from the house to a payee called :market. The transaction will have the tag :CAPEX. Measures with an opex: argument compute its value after installation, and cause the future payment of that amount each year at the end of the year, tagged :OPEX. If the measure is later removed or replaced, the associated opex payments will stop.

As mentioned, fuel costs are incurred by every house at the end of the year. The pricing structure is determined by the tariffs for the house; these are described later in the 13 section. Tariff-related transactions are always tagged with their fuel and with the :fuel tag. You can add other tags on the charge command if you want to, for disambiguation of the transaction log.

For on-model questions, you can use several different commands to look at the costs associated with particular types of transactions on houses or accounts.

So far we have discussed only things which cost a house money, like installing measures or paying bills. Sometimes you may want to install measures but to pay for some part of their cost on behalf of the house.

There are two forms of subsidy available:

1. Immediate subsidies which are not recouped, using finance.with-subsidy and finance.fully, or
2. Immediate subsidies which are recouped later by a loan, using finance.with-loan

All of these three commands work in the same way: you write them around another action, and they do the action but also provide the subsidy and set up any loan.

For example:

(finance.fully
   (measure.standard-boiler fuel:mainsgas capex: 1000))

will perform the inner action (installing a new boiler, and hence costing 1000 pounds), and then (if the inner action is suitable), it will provide a subsidy whose value equals the net cost of performing the inner action (in this case, 1000 pounds).

As a result, if you were to write:

(probe
    capture: [(net-cost)]
    (finance.fully X))

the net-cost captured would always be zero, no matter what X was, because finance.fully always provides a subsidy which cancels out the net cost of the thing it's financing.

In a less-generous policy, we might use finance.with-subsidy, in which we have the option to calculate the value of the subsidy using a rule:

(finance.with-subsidy
    subsidy: (min 500 (net-cost))
    (measure.standard-boiler fuel:mainsgas capex:1000))

In this example we use the rule that the subsidy is whatever is least of the net cost of the measure and 500, effectively clamping the upper end of the subsidy to 500 pounds. In this case if we were to add a probe and capture the net-cost for the entire action, it would be 500, as the house would incur the capital cost of 1000 and then receive the subsidy of 500.

Finally, if we were approaching the nadir of policy generosity we might be looking to saddle the house with a loan, which naturally the householders would only accept if it were economically rational. To model this you can use finance.with-loan:

(finance.with-loan
    principal: (net-cost)
    rate: 5%
    term: 10

    (measure.standard-boiler fuel:mainsgas capex:1000))

In this example, a house will install a boiler, incurring a capital cost of 1000 pounds, but then it will be given a 1000 pound immediate subsidy (the principal:, which in this case is the net cost of 1000 pounds). So far the house is doing well - it has a free boiler - but it also incurs the obligation to repay the loan, with interest, which happens on the anniversaries of the date of installation. The loan payments are of equal size, and the interest on the remaining principal is compounded annually.

These finance commands can be combined; for example, you might want to pay for some of a measure using a subsidy, and then settle the remainder with a loan; here is a more complex example:

(finance.with-loan
    principal: (net-cost)
    rate: 6%
    term: 10

    (finance.with-subsidy
        subsidy: (min 500 (* 2 (fall-in (house.emissions))))

        (do (measure.standard-boiler fuel:mainsgas capex:1000)
            (measure.wall-insulation type:cavity capex: (+ 400 (* size.m2 10))))
    ))

Although the loan is written at the top, it is the outermost thing and so it is considered last; you should read this as something like:

1. Finance doing the following with a loan, where the principal of the loan should equal the net cost of the thing we are financing
   1. Finance doing the following with a subsidy, where the subsidy amount is whichever is least of 500 pounds, or double the fall in emissions
      1. Install as a package, the following:
         1. a boiler, at a cost of 1000 pounds
         2. wall insulation, at a cost of 400 pounds and 10 pounds per square meter insulated

Filling in some example figures we might have:

1. Before we can do the loan, we must do the subsidy:
   1. Before we can do the subsidy, we must install the measures
      1. Installing the measures, we have
      2. boiler, at a cost of 1000 pounds
      3. insulation, at a cost of (say) 1500 pounds
      4. the net cost of all this is now 3500
   2. Now we can consider the subsidy amount; say we reduce emissions by 300 kgCO2/year, we will offer a subsidy of 500 as this is less than 600.
   3. finance.with-subsidy gives the house 500 pounds, so the net cost of the subsidised package as a whole is now 3000
2. Now we can work out the principal for the loan, which is the net-cost of the subsidised package; this is 3000
3. The house is given 3000 pounds now, and made to repay this over 10 years at 6% compounded annually.

This example also illustrates how commands like net-cost refer to the net cost of the action which contains them, rather than the net cost of everything that has happened in the scenario.

The finance.with-subsidy cannot produce costs for a household; if the subsidy: argument is negative (which would represent a cost), no subsidy is offered.

The command measure.with-cost is an equivalent which allows the addition of further costs to another action. For example, if you wished to model a service where an advisor visits a house and charges them fifty pounds for the suggestion to decrease their thermostat setting, you could write

(measure.with-cost
    cost: 50

    (action.set-heating-temperatures living-area-temperature: 19))

This would reduce the house's heating temperature, and charge the house 50 pounds for doing so.

The previous section shows how we can set up future payments by offering a loan. There is one more finance command, finance.with-obligation, which is more complicated than the other sorts. This command allows you to commit a house to an arbitrary sequence of future payments.

It has two important arguments:

amount:

the amount: argument gives a command for working out the amount that the house must pay (or if negative, receive). This command is computed each time the house has to make a payment, so it can change over time.

As a consequence, you may want to store the amount a house should pay or receive in a variable, if the value of the command for computing it would change over time, or if it contains an ephemeral value like net-cost.

schedule:

the schedule: argument determines when the obligation is due, and so when the amount: argument will be used to compute a value for a transaction.

For example, to set up a house to receive 100 pounds every year for a decade, you could write

(finance.with-obligation
    amount: -100 ; negative as it is a cost
    schedule: (periodic-payment interval: "1 year" lifetime: "10 years")

    ;; we need to finance something!
    (action.do-nothing))

The amount is computed each year, so we might write:

(finance.with-obligation
    amount: (sim.year)
    schedule: (periodic-payment interval: "1 year" lifetime: "10 years")

    ;; we need to finance something!
    (action.do-nothing))

This would make the house pay the value of the current year (so 2016 pounds in 2016, 2017 in 2017 and so on) each year for ten years. This is because the sim.year command when used produces the simulation's current year, and the future payments are computed in the year when they are due.

As mentioned, all transactions have a set of tags on them; most finance-related commands can either filter the transactions they include by including or excluding transactions which have certain tags, or can put specific tags on the transactions they generate.

Actions which generate transactions will typically have the arguments:

tags:

a list of tags to write on every transaction that the action is responsible for, and

counterparty:

the name of the global account which is on the other side of the transaction from a house.

As mentioned, the model makes no attempt to represent things like cost of capital, inflation, or any other financial matters. All the model captures is the movement of particular amounts of money from place to place; you can set the prices for these things, and it is up to you whether you wish to use real (inflation-adjusted) prices in the future parts of the simulation or not. Similarly, if you wish to compute the discounted value of running a particular policy for the wider world, it is up to you to work this out off-model, bearing in mind the decisions you have made about what prices to use and what they ought to mean¹⁵.

However, there are circumstances in which a scenario needs to compute a discounted value on model. In the NHM this is usually a matter of prediction, rather than accounting; whilst the model does not represent discounted or inflated figures as the ground truth, it does allow you to model the prediction of future values or costs.

For example, you might want to represent a situation in which a house makes a decision between some alternatives which have an immediate cost in exchange for a future benefit based on their expected (possibly discounted) value over some horizon.

There are a couple of simple commands which produce predictions for the current year:

• house.fuel-cost predicts the costs generated by the obligation to pay the fuel bill at the end of the current year, assuming that the house continues to use energy at the current rate and remains on the same tariff
• house.annual-cost predicts all of the costs the house is expecting to incur in the next year, or a subset which have certain tags

Together with these is the command future-value, which computes the value of another command each year for some number of years into the future, insofar as this can be predicted, and adds up those values.

For example, you can write

(future-value horizon: 3 (house.annual-cost))

to predict the annual cost over the next three years. This will compute the annual cost thrice, each time in a hypothesis, one which looks like the current date, then 1 year hence, and finally two years hence. The sum of these values will be produced.

Because the future-value command computes its argument multiple times in a new hypothesis for each year up to the horizon, it can also produce discounted sums by multiplying the value produced in each future year by an appropriate discount factor.

You can write whatever discount function you like, but the model includes exponential-discount and hyperbolic-discount which probably cover most needs.

For example, if you wished to calculate the future costs of a house's obligations including an exponential discount, you could write

(future-value
    horizon: 10
    (exponential-discount rate:5%
        (house.annual-cost)))

The exponential-discount command determines the discount factor in each year and multiplies its first argument by it, in this case the house's annual cost. Putting this all together, you can calculate a "net present value" for doing something by writing

(+  (capital-cost) ;; the immediate capex
    (future-value
        horizon:10
        (exponential-discount rate:5%
             (house.annual-cost))))

Note here how the capital-cost is not inside the future-value but is added to it; this is because the future-value of capital-cost is zero, since in the future hypotheses being produced no further measures are being installed.

The astute reader may be wondering how exponential-discount works; after all, to work out a discount factor for each future year it needs to know how far into the future the prediction has got when it is worked out.

The answer is that the hypotheses generated by future-value do provide access to the simulation's true current year as well as to the hypothetical year using the notion of different levels of foresight. When you use future-value, you can specify the argument predict: to specify a the foresight levels which should be granted to the house. These determine which things should change as the prediction moves into the future, and which things should be opaque. For example, if you wished to do the present value calculation above, but allowing the house perfect foresight about future fuel prices but not future carbon factors or weather, you could write:

(+  (capital-cost) ;; the immediate capex
    (future-value
        predict: [tariffs]
        horizon:10
        (exponential-discount rate:5%
             (house.annual-cost))))

In this, the model would compute the discounted annual cost using future fuel prices for the house's current tariffs, but without future carbon factors, weather, or anything else time-sensitive. If the house's tariff included a charge which depended on a house's emissions, whose unit price changed over time, the future-value above would reflect the changes in the rate, but would not reflect any changes in emissions factors included in the scenario.

If you wish your own scenario functions to have different degrees of predictability, you can use the foresight: argument supplied on time-sensitive functions; for example, if you had a function which changed based on the year:

(function.case
    (when (= (sim.year) 2020) 10)
    default: 9)

You can control the degree of predictability of this function by providing a foresight: argument to sim.year. Say any future-value which is capable of predicting fuel prices ought to be able to predict the value of this function, you could write

(function.case
    (when (= (sim.year foresight: tariffs) 2020) 10)
    default: 9)

If you were then to predict the future value of this function for 2 years from 2019 with future-value, you could get one of two outcomes:

(future-value
    horizon: 2
    predict: []
    (function.case
      (when (= (sim.year foresight: tariffs) 2020) 10)
      default: 9))

In this case, where we have said that nothing can be predicted, the function would be computed twice:

1. Once in hypothetical 2019, where the function would produce 9
2. Once in hypothetical 2020, but where sim.year would be blinded to the hypothetical year, and so would still appear to be 2019, so the function would produce 9

The value would be 18. If we change to say predict: [tariffs], the result will instead be 19, as we have

1. An evaluation in hypothetical 2019, producing 9
2. Another in hypothetical 2020, including for the sim.year, producing 10.

This also answers the question above of how exponential-discount can work; you can always compute the number of years into the future a function is being predicted by the following expression:

(- (sim.year foresight:always) (sim.year foresight:never))

The first term in the difference is always the year being predicted, and the second is always the true year; these levels of foresight are special and can never be prevented or overridden, so this always evaluates to zero in the first hypothetical year, one in the second and so on.

An exponential discount factor of (say) 5% is then just

(/ 1
   (pow 105%
        (- (sim.year foresight:always) (sim.year foresight:never))))

Indeed, this is exactly the value computed by exponential-discount given a rate of five percent.

The context-sensitive nature of ephemeral values creates some potential for confusion:

1. Ephemeral values will not work in aggregate reports; this is because there is no containing action when the value is worked out in the report. Asking an aggregate report to compute capital-cost is like asking for the capital cost of the report; the model has no way of knowing that you mean to say the capital cost of the measures you put in in the last year, or over the simulation so far, or similar.
2. Ephemeral values will not work as expected in 16 produced by the under command or set under:; this is the value will be the value for the actions applied in the hypothesis. The model has no way of knowing if you mean to ask for the value outside the hypothesis, and always produces the value inside, even if it happens to be zero (as it will be for many commands).

Tariffs are normally defined in the context.tariffs element in the scenario. This has two named arguments, defaults: and others:, each of which can accept a list of tariff definitions.

The tariffs in defaults: will be added to all the houses at the start of the run. Because of this, only one of these tariffs may cover each fuel. The tariffs in others: can be any collection of tariffs, which houses may be switched onto later.

For example:

(scenario ...
    (context.tariffs
       defaults: [A B C]
       others: [X Y Z]))

The tariffs A, B and C will be added to each house when it is created; X, Y and Z will have no effect unless they are explicitly used by action.set-tariffs (of which more later).

A tariff definition is either tariff or tariff.simple. Let's look at an example of tariff first:

(tariff
    name: dual-fuel
    (fuel type: peakelectricity (charge (* 0.1 house.meter-reading)))
    (fuel type: offpeakelectricity (charge (* 0.1 house.meter-reading)))
    (fuel type: mainsgas (charge (* 0.05 house.meter-reading))))

This is a tariff implementing the Dual fuel example above; the house will be charge 10p/unit for peak and off peak electricity, and 5p for mains gas.

The house.meter-reading command has some special behaviour:

• At any point in time, it evaluates to the total number of units of fuel that have not yet been paid for.
• Within a fuel command in a tariff, it refers to the unpaid for units of that specific fuel.

This also illustrates another point of interest: the Electricity fuel type has no consumption in tariffs, in order to prevent accidental double-counting. It is always broken down into PeakElectricity and OffPeakElectricity, whether or not the house is on a tariff that has different charges for these two categories.

To complete the example above, we could write something like this:

(context.tariffs
    defaults: [
      (tariff
        name: dual-fuel
        (fuel type: peakelectricity (charge (* 0.1 house.meter-reading)))
        (fuel type: offpeakelectricity (charge (* 0.1 house.meter-reading)))
        (fuel type: mainsgas (charge (* 0.05 house.meter-reading))))
    ]
    others: [
      (tariff
        name: cheap-electricity
        (fuel type: peakelectricity (charge (* 0.08 house.meter-reading)))
        (fuel type: offpeakelectricity (charge (* 0.08 house.meter-reading))))
      (tariff
        name: expensive-gas
        (fuel type: mainsgas (charge (* 0.1 house.meter-reading))))
    ]
)

We could either write the dual-fuel tariff in defaults, or cheap-electricity and/or expensive-gas, but we could not write dual-fuel with either of the others, as dual-fuel is incompatible with both of the others.

Now we can look at a few different kinds of tariff that we could write:

Now we have seen how to define tariffs, and how to set the default tariffs for a scenario, we should look at how to change people's tariffs.

When using these commands, remember that the model will not switch people back off particular tariffs unless you tell it to. For example, if you put someone on an economy 7 type tariff because they have a storage heater, and then you replace their storage heater with a boiler, the model will not switch them on to another tariff for you. They will continue to be on their original tariff until such time as the action.set-tariffs command is used to change them onto another tariff.

Along with tariffs, a house's bill may include so-called extra charges. An extra charge is what it sounds like - an additional charge (or subsidy) added on to your bill after the tariffs have been computed. Unlike tariffs, extra charges are not exclusively responsible for particular fuels. They can be added to a house with action.extra-fuel-charge, and removed with action.remove-fuel-charge.

For example, if you wanted to offer all houses a subsidy of 100 pounds toward their fuel bill you could write

(apply
    (action.extra-fuel-charge
        (extra-charge -100)))

The value is negative because it is a subsidy. In this example, even houses with a bill of less than 100 pounds would receive a 100 pound subsidy. If you wanted the subsidy to be up to 100 pounds you can refer to the cost of the other tariffs using net-cost again:

(apply
    (action.extra-fuel-charge
       (extra-charge (- (min 100 net-cost)))))

Here we have offered a subsidy of 100 pounds or the net-cost of the other tariffs, whichever is least.

If you wanted the net cost of a specific fuel, you can associate a fuel type with the extra charge, which makes net-cost aware only of the costs for that fuel.

(apply
    (action.extra-fuel-charge
       (extra-charge
          fuel: mainsgas
          (- (min 100 net-cost)))))

Here we have offered a subsidy of up to 100 pounds off the gas bill. Unfortunately the division of electricity into peak and off-peak applies here as well, making writing an equivalent rule for two fuels a little more difficult:

(apply
   (action.extra-fuel-charge
      (extra-charge (- (min 100 (net-cost tagged: ":<peak,offpeak>electricity"))))))

Rather than associating the charge with a fuel, we have used the tagged: argument of net-cost to refer only to transactions tagged with either :peakelectricity or :offpeakelectricity.

To remove a charge, you will need to refer to it by its name:. For example, if you had offered all houses a mains gas subsidy as above, except with a name

(apply
   (action.extra-fuel-charge
      (extra-charge
         name: mains-gas-subsidy
         fuel: mainsgas
         (- (min 100 net-cost)))))

But then you wanted to find some houses and remove the subsidy from them, you would elsewhere write something like:

(apply to:(sample 10%)
    (action.remove-fuel-charge #mains-gas-subsidy))

In this, #mains-gas-subsidy refers to the extra-charge above whose name: argument is mains-gas-subsidy.

You can also remove all extra charges from a house just by applying (action.remove-fuel-charge). This is useful if you are computing a hypothetical fuel cost, of which more later.

First let us consider two ways to turn n candidate actions into one by selecting one as the one to do, and disregarding the rest. The first way makes the selection based on information which is independent of the effects of any of the candidates. The action to take is chosen before we do it, and so even before we know whether it will work. The second way is to make the selection after the fact, with knowledge of the effects that each candidate will have.

The other way to assemble n actions into one is to do them in a defined order; the model provides the do command for this. Its syntax is quite simple:

(do
    A
    B
    C
    D
    ...)

When applied to a house, this command will first apply measure A, and then apply measure B to the house (in the condition left by applying A), then apply measure C to the house (in the condition left by B), and so on.

The do command has special behaviour in two aspects: first, it uses 16 to ensure that only suitable packages can have any effect, and second it allows you to see and record "ephemeral" values like net-cost and size.m2 whose values depend where they are being evaluated in the scenario.

Remember that any action applied to a house can go one of two ways:

1. The action succeeds, because it is suitable for the house, and it may have some effect on the house like installing a boiler or changing some flags (this last part is not obligatory; there are two basic commands which are suitable and succeed but have no effect, namely action.do-nothing and an empty (do) statement).
2. The action fails, because it is unsuitable for the house, in which case it is forbidden for the action to have any effect on the house, and if it does it's a bug in the model.

Bearing this in mind there is a natural question for do: what happens if one of the measures that we are doing is unsuitable, and fails?

The answer depends on the all: argument to do:

As mentioned, the do command has special handling of ephemeral values; when using the following commands within a do

• set
• increase
• decrease
• consume
• fail-unless

The values of net-cost, capital-cost, size.m2, size.kw, original, rise-in and fall-in are all computed with respect to the effect of the do command so far. For example, if we amend the example above:

(do (set #x-1 (net-cost))
    (measure.wall-insulation capex: 100 type:cavity ...)
    (set #x-2 (net-cost))
    (measure.standard-boiler capex: 200 fuel:mainsgas ...)
    (set #x-3 (net-cost)))

The variables #x-1, #x-2 and #x-3 will take the values 0, 100, and 300 respectively; this is because when the first set happens the net cost of the do is zero (as it has done nothing to spend money), when the second happens the net cost is 100 as the do has bought some insulation for 100 pounds, and when the third happens it is 300 as the do has bought both 100 pounds of insulation and 200 pounds of boiler.

The same rules about suitability apply here, so the outcome would either be these values of the variables and the two measures installed, or the variables unchanged and neither measure installed.

The choice command has a similar rule for its select: argument; when values in the select: are computed they are computed with respect to a particular alternative, and so net-cost is the net cost of doing the alternative, capital-cost the capital cost, (rise-in x) the increase in x caused by doing that alternative and so on.

1. For each of these situations, which outcome or outcomes would you expect to see (you may want to read the section above on flags first):

   1. Applying the action

      (action.case
          (when (house.region-is London)
                (house.flag london))
          (when (house.built-form-is Detached)
                (house.flag detached))
          (when (> house.total-floor-area 500)
                (house.flag large)))
      

      to each of these houses, all having no flags

      1. A detached house in london with a floor area of 400
      2. A terraced house in london with a floor area of 600
      3. A terraced house in wales with a floor area of 500
      4. A terraced house in wales with a floor area of 600
      5. A detached house in wales with a floor area of 600

   2. Applying the action

      (do
          (house.flag A)
          (house.flag B)
          (house.flag C))
      

      to a house with no flags

   3. Applying the action

      (choice
          select: (select.minimum house.total-floor-area)
          (house.flag A)
          (house.flag B)
          (house.flag C))
      

      to a house with no flags

   4. Applying the action

      (choice
          select: (select.weighted 5)
          (house.flag A)
          (house.flag B)
          (house.flag C))
      

      to a house with no flags

   5. Applying the action

      (do (house.flag A)
          (action.do-nothing test-flags: !A)
          (house.flag B))
      

      to a house with no flags

   6. Applying the action

      (do all:false
          (house.flag A)
          (action.do-nothing test-flags: !A update-flags: C)
          (house.flag B))
      

      to a house with no flags

   7. Applying the action

      (do (action.do-nothing test-flags: !A update-flags: C)
          (house.flag A)
          (house.flag B))
      

      to a house with no flags

   8. Applying the action

      (choice
          select: (select.minimum 0)
          (do (house.flag A)
              (action.fail))
          (house.flag B))
      

      To a house with no flags

   9. Applying the action

      (choice
        select: (select.minimum #x)
        (do (house.flag A)
            (set #x 1))
      
        (do (house.flag B)
            (set #x 2))
      
        (do (house.flag C)
            (set #x 3)))
      

      To a house with no flags or variables set

   10. Applying the action

       (choice
         select: (select.maximum #x)
         (do (house.flag A)
             (set #x 1))
       
         (do (house.flag B)
             (set #x 2))
       
         (do (house.flag C)
             (set #x 3)))
       

       To a house with no flags or variables set

   11. Applying the action

       (choice
         select: (select.weighted #x)
         (do (house.flag A)
             (set #x 1))
       
         (do (house.flag B)
             (set #x 2))
       
         (do (house.flag C)
             (set #x 3)))
       

       To a house with no flags or variables set

   12. Applying the action

       (choice
         select: (select.filter test: (> #x 1)
                                selector: (select.minimum #x))
         (do (house.flag A)
             (set #x 1))
       
         (do (house.flag B)
             (set #x 2))
       
         (do (house.flag C)
             (set #x 3)))
       

       To a house with no flags or variables set

2. Write some code to do each of the following actions
   1. Install three measures

There are some more exercises related to choices and packages in the section on suitability and failure.

All other actions also have suitability rules, which are also documented in the language reference. These rules are more complex for the compound actions like do, choice and action.case. It is important to understand these rules if you use the compound actions, because they can (a) cause your actions to fail when you might expect them to succeed, and also (b) you can use them to model complicated behaviour like supply chains, post-hoc constraints, random outcomes and all sorts of other effects. The sections on these commands describe their suitability rules a little, but this section covers them in more detail, explaining how they can be put together.

Sometimes you may wish to change the suitability of an action. In the NHM, actions' suitability can only ever be reduced, as you can add a test either before or after doing the action which will cause it to fail under certain circumstances, but you can never change the action so that it succeeds in conditions where it would have failed. You have already seen how you can use flags for this, with the test-flags: argument that most measures will accept. You may require a more general rule, which lets you render a measure unsuitable for any reason.

In recent versions of the model you can do this using the fail-unless command within do

For example, say we had a measure like this:

(measure.standard-boiler fuel: mainsgas)

If we wished to amend this measure so that it was only suitable in urban houses we could write:

(do (fail-unless (house.morphology-is urban))
    (measure.standard-boiler fuel:mainsgas))

You could also write this using action.case as

(do (action.case (when (none (house.morphology-is urban)) (action.fail)))
    (measure.standard-boiler fuel:mainsgas))

or

(action.case (when (house.morphology-is urban)
                   (measure.standard-boiler fuel:mainsgas))
      default: (action.fail))

These are all equivalent statements; in each case the morphology of the hosue is tested before the measure is installed, and the installation fails if the morphology is not urban.

Sometimes you may wish to check suitability after the fact; for example, you might say that an insulation measure is not suitable if it insulates a very small or very large area, as small areas are not worthwhile and large areas require a more expensive material.

In this case, you can again use fail-unless or action.case

(do (measure.wall-insulation type:cavity resistance: 0.01 thickness:50)
    (fail-unless (> 10000 (size.m2) 10)))

or

(do (measure.wall-insulation type:cavity resistance: 0.01 thickness:50)
    (action.case (when (none (> 10000 (size.m2) 10)) (action.fail))))

As well as fail-unless, there is a special command called consume which fails unless it can reduce a variable by a certain amount without making it negative; this is useful for defining things like supply chains or maximum emissions rules.

For example, say you wished to restrict installations of a certain measure to 100,000 units per year:

(def remaining-units on:simulation default: 0)

;; every year, reset the remaining units
(on.dates (regularly)
          (set #remaining-units 100000))

(on.dates ...
    (apply to: ...
        (do (consume #remaining-units)
            (the-measure))))

Here we have a global counter called #remaining-units, and in the do command around the-measure, we use consume to make sure that we have enough units left to install; consume will decrease #remaining-units by the house's weight, unless that would make #remaining-units negative in which case it will fail and the-measure will not be installed.

You could write this out as

(do (decrease #remaining-units (house.weight))
    (fail-unless (>= #remaining-units 0))
    (the-measure))

So consume is just a shorthand for this.

For each of these measures, consider its application to the listed houses and determine whether it will succeed, and explain why

1. The simplest option

   (action.do-nothing)
   

   • applied to any house

2. The second simplest option

   (action.fail)
   

   • applied to any house

3. A slightly less simple option (see the 9 section if unclear)

   (action.do-nothing test-flags: qwerty)
   

   • applied to a house with no flags
   • applied to a house with the flag qwerty
   • applied to a house with the flag qwertyuiop

4. And again

   (action.do-nothing test-flags: !qwerty)
   

   • applied to a house with no flags
   • applied to a house with the flag qwerty
   • applied to a house with the flag qwertyuiop

5. Another simple one

   (do)
   

   • applied to any house

6. Doobie doo

   (do (do (do)) (do))
   

   • applied to any house

7. Do choose

   (choice select: (select.weighted 1)
       (do)
       (do)
       (do))
   

   • applied to any house

8. Do choose some more

   (choice select:
           (select.filter test: (house.region-is london)
                          selector: (select.weighted 1))
      (action.do-nothing)
      (do)
      (fail))
   

   • to any house

9. Do fail a choice

   (do
       (choice select: (select.weighted 1)
           (action.fail))
       (choice select: (select.weighted 1)
           (action.do-nothing)))
   

   • to any house

10. Do a measure involving 11 and 10.

    (do (measure.standard-boiler fuel:mains-gas capex:1000)
        (consume #boiler-expenditure (* (house.weight)
                                        (capital-cost))))
    

    • To a house suitable for a gas boiler
    • To a house not on the gas grid

11. Do a measure later

    (do (consume #boiler-expenditure (* (house.weight)
                                        (capital-cost)))
        (measure.standard-boiler fuel:mains-gas capex:1000))
    

    • To a house suitable for a gas boiler
    • To a house not on the gas grid

12. Total failure

    (action.case
        (when (= 1 2) (action.fail))
        default: (action.fail))
    

    • to any house

13. Failure?

    (action.case
        (when (> 1 2) (action.fail))
        default: (do update-flags: hello))
    

    • to any house

14. Success?

    (action.case
        (when (< 1 2) (action.fail))
        default: (do update-flags: hello))
    

The NHM's simulation proceeds by making use of hypotheses; every change that the model thinks about, whether to a single house or a population of houses, starts of as a hypothesis, in which the model changes things speculatively.

The changes which happen when considering a hypothesis are isolated from the model's view of the real world, and can change anything about the world until the hypothesis is either discarded without any change to how things "really" are, or it is accepted and becomes the new status quo.

This basic feature is used to make commands like do and choice work; in a do, the changes being applied happen within the hypothesis that the do will succeed. If one of the changes is not successful, the do can safely throw away the hypothesis in the knowledge that there will be no side-effects. Similarly, the choice command produces n hypotheses, one for each of the alternatives, and discards n-1 of them. To further complicate matters, the model can make a hypothesis within another hypothesis¹⁶; this is what happens when you place a choice within a do or vice-versa.

These commands (do and choice) have a common factor: whichever hypothesis ends up being accepted as the new status quo, we know that nothing which happened in any of the discarded alternative hypotheses can affect the simulation (it can affect reports, of which more later; reports are outside the simulation's view of the world).

There are some other commands which will allow you to work something out in a hypothesis, but to store the result outside that hypothesis. You could think of this as being analogous to using your imagination, at least if your imagination were very effective. Let us look at the first of these commands, under

Imagine a scenario in which you are modelling the offer of several packages of measures to various houses, and the houses are deciding between these packages based on the annual heating bill they will have after installing each package:

(choice
    select: (select.minimum (house.fuel-cost))

    (package-1)
    (package-2)
    (package-3))

package-1, package-2 and package-3 are standing in for some actual packages that we are considering, for ease of reading. In this case, we will take each package, and then pick the one for which the fuel cost after installation is least.

Now say that we wish to model something slightly different: say that the householder making the decision has a belief that electricity prices will rise and gas prices will fall in the future, and so we wish to make the choice on the basis of these different prices.

However, these prices do not yet pertain in the model, and indeed may never as the householder could be wrong in their belief. We must make the choice minimising how fuel cost would be if we were to have a different suite of prices.

The tool for this is the under command, which has the following form:

(under
    <<some actions>>
    evaluate: <<value of interest>>
)

When the under command is used by the model, it does the following:

1. Produce a new hypothesis, which looks the same as where the under is being worked out, but is isolated from it because it is a hypothesis
2. Uses the actions to change things in the hypothesis
3. Works out the argument to evaluate: in the hypothesis, so that it "sees" the changes that were made
4. Discards the hypothesis, and produces the value from 3 back where the under was being computed

You can read this as saying, "without changing how things are now, imagine what would happen if we did the actions and worked out the evaluate: argument afterwards".

So returning to our example, we can evaluate the fuel cost under a different set of tariffs, reflecting the householder's beliefs without changing the tariffs which are actually used in the simulation:

(choice
 select: (select.minimum
          (under
           (action.set-tariffs
            (tariff
             (fuel type:mainsgas (charge (* 0.01 house.meter-reading)))
             (fuel type:peakelectricity (charge (* 0.3 house.meter-reading)))
             (fuel type:offpeakelectricity (charge (* 0.3 house.meter-reading)))
             ))
           evaluate: (house.fuel-cost)))
 (package-1)
 (package-2)
 (package-3))

In this case the model will create six hypotheses, which we can draw out in a hierarchy:

1. From the initial state, before the choice:
   1. a hypothesis in which package-1 has been applied, in which under makes:
      1. A sub-hypothesis in which the tariffs have been changed and package-1 has been applied
   2. a hypothesis in which package-2 has been applied, in which under makes:
      1. A sub-hypothesis in which the tariffs have been changed and package-2 has been applied
   3. a hypothesis in which package-3 has been applied, in which under makes:
      1. A sub-hypothesis in which the tariffs have been changed and package-3 has been applied

In each of the sub-hypotheses, under will work out the house.fuel-cost, giving the fuel costs for:

1. package-1 with the hypothetical tariff
2. package-2 with the hypothetical tariff
3. package-3 with the hypothetical tariff

However, each of these is disposed of after being used to work out the cost, and the choice will select one of the "first-level" hypotheses as the actual outcome.

Using under can be computationally expensive - each use of under can only compute a single value, so if you want to calculate several different values under some hypothetical changes you need to write it out several times. The model is not clever enough to know when the work of making the changes can be reused, so each use of under creates its own hypothesis, does all the work of making the changes and updating derived values like the energy use, and then throws the hypothesis away. As a result, if you ask for ten different values each under the same assumption by writing (under A evaluate:X), (under A evaluate:Y), and so on, it is ten times as expensive as asking for one.

As an alternative the model provides special argument to set to allow you to calculate several values in a hypothesis all at once:

(set
    [#variable-1  #variable-2  #variable-3]
    [(function-1) (function-2) (function-3)]
    under: [(action-1)
            (action-2)])

This will do the following:

1. Produce a new hypothesis, wherein:
   1. Apply action-1 to change things in the hypothesis
   2. Apply action-2 to change things further in hypothesis
   3. Compute function-1 in the hypothesis, and store the result in #variable-1
   4. Compute function-2 in the hypothesis, and store the result in #variable-2
   5. Compute function-3 in the hypothesis, and store the result in #variable-3
2. Copy the values of #variable-1, #variable-2 and #variable-3 out of the hypothesis and into the "real" values for the variables
3. Discard the hypothesis

This will have the same effect as writing

(do (set #variable-1 (under (action-1) (action-2) evaluate:(function-1)))
    (set #variable-2 (under (action-1) (action-2) evaluate:(function-2)))
    (set #variable-3 (under (action-1) (action-2) evaluate:(function-3))))

But it will be much faster, as (action-1) and (action-2) need only happen once, only one hypothesis is generated, and any calculation which can be shared between the three functions will be (for example, uses of the energy calculation).

A very common need is to compute the change in values, as a result of a hypothetical action. For example, when defining a choice you might want to include only those alternatives for which the reduction in fuel cost is greater than the net cost of installation. You can do this with variables, writing something like this:

(do
    (set #initial-bill (house.fuel-cost))
    (choice
        select: (select.filter
                    test: (> (- #initial-bill (house.fuel-cost))
                             (net-cost))
                    selector: (select.minimum (net-cost)))
        (action-1)
        (action-2)
        (action-3)
        ))

Newer versions of the model offer a simpler syntax:

(choice
 select: (select.filter
          test: (> (fall-in (house.fuel-cost))
                   (net-cost))
          selector: (select.minimum (net-cost)))
 (action-1)
 (action-2)
 (action-3))

The command fall-in computes its argument twice and produces the difference; the first time is computed outside the current hypothesis and the second inside. In this case the choice command is responsible for creating the current hypothesis, so the (fall-in (house.fuel-cost)) will be the difference between the fuel cost before applying any alternative and the fuel cost after. The rise-in command does the natural reverse of this (the difference between the value inside and outside), and the original command provides direct access to the value outside.

It can help to draw out how hypotheses are constructed and selected for different commands. In each of these diagrams a circle represents a state of affairs, a solid arrow the application of an action to that state of affairs, and a dashed arrow the production of some hypotheses.

Circles with a red outline are those whose hypotheses are discarded, and those with a double-circle outline are those which are selected.

A red solid arrow indicates a failed measure, and will therefore always lead to a red circle.

Output from reporting commands is sent to files immediately, and is not part of the simulation's state¹⁷; it is therefore not reversed when reporting was done within a hypothesis that is later discarded. This can lead to confusing output, but may also be quite useful; for example, if you apply the following action:

(do
    (probe name: p
           (measure.standard-boiler ...))
    (action.fail))

The probe p will probably contain records which show a boiler being successfully installed in some dwellings (so long as it has been applied to dwellings for which a boiler is suitable). However, these dwellings will never actually receive a boiler, because the action.fail will cause the surrounding do to be unwound; it can never have a real effect.

If you were to amend the above to read:

(probe name:q
  (do
     (probe name: p
            (measure.standard-boiler ...))
     (action.fail)))

The two probes would be correlated; each house presented would produce a row in both p and q, but all the rows in q would show failure whereas some of the rows in p would show success.

The reports generated by def-report include a special column called selected, which indicates whether the hypothesis in which a row of the report was computed was eventually made part of the true state, or whether it was later discarded.

The simplest and most useful facility offered by the preprocessor allows you to define templates. A template is like a pro-forma bit of scenario syntax with some "blank spaces" in it that need to be filled in before it is complete. To employ a template, you first define the pro-forma under a name of your choice, with placeholders for the blank spaces, and then you use the template by invoking the name you gave it.

To make this concrete, consider the following situation; imagine you have written a scenario, but the Minister phones through and says "It is essential that at no point, as a result of the Mauve Deal policy, that emissions due to biomass should exceed 9 million tonnes per year; what would this do to the simulation outcomes? Any time in the next ten to fifteen minutes would be fine so don't rush.".

You consult the NHM manual, put on your thinking hat, and determine that this can be done by restricting the suitability of the measures the scenario is installing; this is a matter of checking a postcondition, namely that after installing a measure if you have made emissions go up you haven't taken them over 9 million tonnes. Postconditions are a good fit for do and fail-unless, so you cook up this:

(do ;; the measure goes here
    (something-or-other)
    ;; now for the postcondition
    (fail-unless
        ;; so we give up, unless either:
        (any
            ;; the emissions for this house have not gone up
            (>= 0 (fall-in (house.emissions by-fuel:biomasswood)))
            ;; or if they have gone up, the total is still fine
            (< (summarize (aggregate.sum (house.emissions by-fuel: biomasswood))) 9000000)
        )))

This seems pretty reasonable, but looking at the clock we notice that we only have six minutes left, and we don't relish the prospect of correctly adding this around each measure we have written, even though we wrote each measure down using #def-action so they are all nicely defined in one place.

What we want here is a template; the code above is clearly a bit of pro-forma; it is the same in all cases, except for the something-or-other, which is a blank we need to fill in.

To define our template, we use the special template command, which looks like this:

(template <<template name>> [<<list of placeholders>>]
          <<pro-forma goes here>>)

In our case, let us say the template is to be called enforce-biomass-emissions-limit; the first step is simply to pop in our pro-forma (a.k.a. the template body):

(template enforce-biomass-emissions-limit []
   (do ;; the measure goes here
      (something-or-other)
      ;; now for the postcondition
      (fail-unless
          ;; so we give up, unless either:
          (any
              ;; the emissions for this house have not gone up
              (>= 0 (fall-in (house.emissions by-fuel:biomasswood)))
              ;; or if they have gone up, the total is still fine
              (< (summarize (aggregate.sum (house.emissions by-fuel: biomasswood))) 9000000)
          ))))

So far so good, but how do we tell the model that we want to put a particular thing in place of something-or-other? The answer is in two parts:

1. We put something in the list of placeholders, to tell the template that it needs something to pop into place, and then 2
2. We refer to that placeholder in the pro-forma in the right place.

To make them stand out, placeholders are always written with an atpersand (@) at the start of them; we can add one into the template we are imagining now:

(template enforce-biomass-emissions-limit [@measure]
   (do ;; the measure goes here
      @measure
      ;; now for the postcondition
      (fail-unless
          ;; so we give up, unless either:
          (any
              ;; the emissions for this house have not gone up
              (>= 0 (fall-in (house.emissions by-fuel:biomasswood)))
              ;; or if they have gone up, the total is still fine
              (< (summarize (aggregate.sum (house.emissions by-fuel: biomasswood))) 9000000)
          ))))

This is now our whole template - we have a placeholder, called @measure, which represents the blank to fill in. Now to write out emissions-limited actions in our scenario, we don't have to copy-paste the pro-forma into place every time; instead we simply invoke the template thus:

(apply to:(some-houses)
       (enforce-biomass-emissions-limit
           measure:
           (measure.standard-boiler fuel:biomasswood ...)
       ))

When the model sees that we have used enforce-biomass-emissions-limit as a command, it will remember that it saw a template by that name, and effectively replace the use of the template with its body; it is exactly as though you had just written down

(apply to:(some-houses)
   (do ;; the measure goes here
      (measure.standard-boiler fuel:biomasswood ...)@measure
      ;; now for the postcondition
      (fail-unless
          ;; so we give up, unless either:
          (any
              ;; the emissions for this house have not gone up
              (>= 0 (fall-in (house.emissions by-fuel:biomasswood)))
              ;; or if they have gone up, the total is still fine
              (< (summarize (aggregate.sum (house.emissions by-fuel: biomasswood))) 9000000)
          ))))

You can think of a template as being a scenario editing rule that you might give to a particularly unfortunate intern, except it is applied transparently and automatically to your scenario when you press run.

Returning to our story, you are now able to zip through all the actions which you have sensibly defined with def-action, and amend them, so where once you had:

(def-action policy-biomass-boiler
            (measure.standard-boiler fuel:biomasswood ...))

You now have

(def-action policy-biomass-boiler
            (enforce-biomass-emissions-limit
                measure:
                (measure.standard-boiler fuel:biomasswood ...)))

Success! The astute reader will note that this replacement is analogous to what we have just done - the change to each def-action is itself a kind of pro-forma edit that could be done by our unfortunate intern. Indeed, if you found yourself doing this very frequently, you could say:

(template def-policy-action [@name @action]
    (def-action @name @action))

(def-policy-action
    name: policy-biomass-boiler
    action: (measure.standard-boiler fuel:biomasswood ...))

And then a single change to def-policy-action could change all your defined actions at a swoop!

This should give you some feel of when to use a template: if you have a lot of code which is often similar but with minor variations, consider replacing it with a template. Of course, adding more templates to your scenario can make it harder to read, especially when someone first approaches it, as they have to understand what each template does before they can understand the code which uses those templates, so you must weigh the introduction of templates carefully.

In the preceding example, we showed how to write a single placeholder, which had a name, and where the thing to be filled into the placeholder was identified by using that name.

There are a few different options available when writing a placeholder, which are explained in more detail in the language reference.

Each placeholder connects an argument supplied when invoking the template to some places in the body of the template.

Sometimes you might want a template to do something a bit more complicated than just producing some pro-forma. There are a small number of other model commands which instruct the pre-processor to do edits to your scenario. All of these commands start with a tilde (~) character, and are documented in the manual section on standard macros. When you are reading a scenario, remember that any command named with a tilde is a command to manipulate the scenario code inside it, not a command pertinent to houses, dates and so on.

Here are some of the macros you are most likely to encounter:

~join

The join macro concatenates bits of text. For example, if you wrote

(~join this - that - the - other)

when the join is expanded it will be replaced with this-that-the-other.

This is useful for writing templates that need to do things like setting a flag with a particular name, or defining a set of variables which should all have related names, because you can use a template placeholder inside the ~join. For example,

(def (~join installation-count-of- @measure-name s))

in a template would expand to produce something like (def installation-count-of-boilers) if @measure-name were to contain boiler.

~maybe

The maybe macro is for passing along named arguments that are optional, without supplying a default in the template where you are writing them. For example, imagine you want to define a template which installs a new boiler, and you have some optional arguments that you want to pass on to measure.standard-boiler:

(template my-boiler [[@capex] [@opex]]
    (measure.standard-boiler winter-efficiency:89% summer-efficiency: 85%
       (~maybe capex: @capex)
       (~maybe opex: @opex)))

The macro accepts either one or two arguments; if the second argument is supplied, it just expands to both the arguments without modifying them. If the second argument is missing, the maybe macro expands to nothing at all.

The effect of this in the example above, is that if a user writes:

(my-boiler)

then they get:

(measure.standard-boiler winter-efficiency:89% summer-efficiency: 85%)

whereas if they write:

(my-boiler capex: 1000)

then they get:

(measure.standard-boiler winter-efficiency:89% summer-efficiency: 85%
    capex: 1000)

~match

The ~match macro is a bit like an if statement. It will look one bit of scenario code that you give it, and compare it to several other options, each of which can have some associated "output". If there is an output that is the same code as the input, it will expand to the output.

The thing to compare is the first argument to ~match, and then all the other arguments should be lists. The first thing in each list checked against the thing to compare, and if it's the same the macro outputs the rest of the list.

For example

(~match large
   [small 100]
   [medium 200]
   [large 300])

Will expand to the single output 200, because large is the first item in the third list.

Note that something like this:

(~match (house.built-form)
   [Detached 1]
   [EndTerrace 2]
   ...)

will not work as you might guess it would on reading. This is because ~match is a macro rather than a normal command, and so it operates on the scenario code itself, not on houses. Macro output is determined before the model runs, so it can never depend on the particulars of houses or things going on in the simulation.

In this case, the match command will compare the literal text (house.built-form) with the literal text Detached, EndTerrace, and so on. The text (house.built-form) does not equal any of these values (in fact, it only equals (house.built-form)!), and so the macro will output nothing as there is no match.

The normal model commands you can use for this kind of thing are things like function.case, action.case, lookup (which can be programmed with ~lookup-table, of which more later).

The ~match command is mainly useful if you are writing a template and you want template users to be able to supply categories of some kind as arguments, and to output different code for different categories, or if you want to produce a useful error message if a user provides an argument to a template which you don't know how to deal with:

(template boiler [@fuel-type]
   ;; check the @fuel-type is OK:
   (~match @fuel-type
        [MainsGas] [Electricity] [Biomass]
        default: (~error No assumptions available in the boiler template for @fuel-type.))
   (measure.standard-boiler fuel: @fuel-type
     capex: (capex-for-fuel-type @fuel-type) ...))

~combinations

The combinations macro is a bit like a loop, if you have used other programming languages. It is a bit complicated to get to grips with initially, but there isn't that much to it in the end.

What it does, is take several lists of commands, and go through each possible combination made by taking exactly one command from each list, putting each combination inside another command that you give it.

To start with, here is an example where there is one list of commands to combine, and the command to put each combination inside is do.

(~combinations 
  template: do
  [(measure.wall-insulation)
   (measure.loft-insulation)])

template: gives the outer command, and the list in brackets gives a list of two things to pick between.

This will output the following scenario code when it is expanded:

(do (measure.wall-insulation))
(do (measure.loft-insulation))

This is because there is one list to choose from, so the only combinations to go through are given by each member of that list.

Now here is a more complicated example:

(~combinations
   template: do

   [(measure.wall-insulation)
    (measure.loft-insulation)]
   [(measure.standard-boiler)
    (measure.heat-pump)])

This will produce four combinations, which are what you get by choosing one thing from each list:

(do (measure.wall-insulation)
    (measure.standard-boiler))
(do (measure.wall-insulation)
    (measure.heat-pump))
(do (measure.loft-insulation)
    (measure.standard-boiler))
(do (measure.loft-insulation)
    (measure.heat-pump))

You can have as many lists as you would like, but remember that the number of combinations produced is the product of the length of each list, so 4 lists each having 6 things in gives you \(6^4 = 1296\) possible combinations, 10 lists of two things gives \(2^10 = 1024\) and so on. If a single combination is expensive to simulate or validate, all of the combinations will be exponentially moreso.

The template: argument can be the name of any model command, or any other template you have defined, so you can also use ~combinations to do things like defining a list of variables:

(do template:def [one two three four])

is

(def one)
(def two)
(def three)
(def four)

and so on.

~lookup-table

Lookup table is a wrapper around the model's lookup command, so we should probably explain the lookup command first.

A lookup is a number-valued command (a function) that lets you conveniently write complicated conditional rules that depend on several other values. You can use a lookup wherever you would write a number, so as the capex: for a measure, or as the sample percentage for a sample and so on.

Here is a spurious example (it is intentionally spurious, to make clear that the values of entries can be anything you like - a lookup entry could contain any function):

(lookup
  default: 1
  keys: [(house.built-form) (house.total-floor-area)]
  (entry [Detached     1000] (* 10 (house.total-floor-area)))
  (entry [SemiDetached 2000] (house.energy-use)))
  (entry [* *] 999))

When this lookup is computed for a house, the command does the following:

1. It works out the values of the commands in the keys: argument

2. It goes through each entry in the lookup in order, and compares the keys: values to the values in the list at the start of the entry, which we will call the matching rules.

   If an entry's matching rules all match their corresponding keys: value, then the lookup computes the second part of the entry, and produces that value.

3. If no entry matched, then the lookup produces the value of the default: argument as a fall-back.

Each of the rules in an entry can be either a specific value, like a certain number or a categorical constant, or true or false for a boolean function in the key, or it can be a wildcard, written as a star * which will allow any value, or for numbers it can be a rule that defines a range of numbers like:

• 13..15 which will match anything from 13 to 15
• <10 which will match anything below 10
• >10 which will match anything above 10

and equivalents using greater-than-equals and so on to include the end-point.

The ~lookup-table macro is a more convenient way to write these lookups. It lets you write one dimension of the lookup across the top of a table as column headings, which can make the rule easier to read.

For example a lookup which gives a time-series of values for each region of the country could be written as:

(~lookup-table
  row-keys: house.region
  column-key: sim.year

  [r         2016 2017 2018 2019 >2019]
  [London    1    2    3    4    5    ]
  [SouthWest 6    7    8    9    10   ]
  ;; and so on
)

This is just the same as a plain lookup as follows:

(lookup keys:[house.region sim.year]
   (entry [London 2016] 1)
   (entry [London 2017] 2)
   (entry [London 2018] 3)
   (entry [London 2019] 4)
   (entry [London >2019] 5)

   (entry [SouthWest 2016] 6)
   (entry [SouthWest 2017] 7)
   (entry [SouthWest 2018] 8)
   (entry [SouthWest 2019] 9)
   (entry [SouthWest >2019] 10))