Plugin guide

This page covers installation, a first run, the data downloader, the run dialog, the outputs, and troubleshooting. The introduction explains the model itself, the theory page relates it to the published model, and the scenario library provides prepared data and parameters to start from.

Install

In QGIS 4: Plugins → Manage and Install Plugins → Settings, tick “Show also experimental plugins”, then search for isobenefit and install it.
Two toolbar buttons appear: Isobenefit Urbanism (the simulation) and Extract from OpenStreetMap (the data downloader).
The first time you run the simulation, the plugin checks for its isobenefit engine and, if missing, offers to install it into the QGIS Python environment (this requires an internet connection). Restart QGIS once it finishes.

If the automatic install is not available or not working on your system, run the shown command yourself with the QGIS Python:

<qgis-python> -m pip install "isobenefit>=0.12.20,<0.13"

Quick start: your first run

The fastest route uses the OSM downloader for the data and accepts most defaults.

Zoom the map to a place you want to test (a town and its surroundings; the area must be more than twice the walking distance across, and a window of a few kilometres works well).
Open Extract from OpenStreetMap. Click Draw area on map…: the dialog hides, left-clicks add corners, a right-click finishes the polygon (Esc cancels).
Leave all datasets ticked, choose an output GeoPackage path, and press Fetch. The layers are saved to the GeoPackage and added to the project as an “OSM” group.
Open Isobenefit Urbanism. The dialog pre-fills its layer pickers from the OSM download, suggests a local projected CRS, and validates as you type; the status line under the form lists what is still missing.
Confirm the output folder and the run name. With an OSM download present, the folder is pre-filled as a scenarios folder beside the downloaded data (numbered upward when earlier runs exist); all of the run’s files take the name.
Set the target population: the number of new residents to house. Existing buildings are context only and are never counted.
Check the Development density group: three densities (people per km²) and the share of new blocks built at each. The shares must sum to 1; the feedback line shows the running total and the resulting mean density.
Press Run. The simulation runs as a background task; the progress bar tracks it, and a run can be cancelled safely. Per-stage detail (grid size, ensemble progress, post-processing candidates, warnings) streams to the Log Messages panel: View → Panels → Log Messages, Isobenefit tab. With the default Development likelihood mode, several layers load on completion; start with the optimised placement plan.
The run’s full settings are saved next to the output as <name>_params.json. To repeat or adjust the run later, use Load parameters at the top of the dialog.

If the first result shows less growth than expected, some constraint is usually binding harder than intended for the place. The usual suspects, in order: the target population against the iterations available (the run report states both); the centre walk, which bounds growth around each centre until a new one seeds; a minimum green span wider than the gaps growth would need to fill; and unbuildable land fragmenting the window. The troubleshooting section walks through each.

To start from a prepared case instead, use a scenario download, described in the next section.

Using a downloaded scenario

Each entry in the scenario library downloads as one ZIP with the data and parameters for a run.

Contents: extents*.geojson (the study boundary), the input layers (built, green, centres, unbuildable, industrial, streets, railways, stops, stations), the terrain bands (steep.geojson), and one or more params*.json presets.
Layers: drag the GeoJSON files onto the QGIS map.
Local adjustment: the layers are ordinary editable data, and the scenarios are prepared on the assumption that they will be revised. The built fabric, the extents, the green areas and the unbuildable land can each be corrected wherever local knowledge or stakeholder feedback improves on the downloaded state.
Centre seeding: the urban-centres layer steers the simulation and is the most direct expression of local intent. A point or area added where a mixed-use centre is planned draws growth around it; removing one examines a future without it.
Terrain: steep.geojson holds slope bands (15° / 20° / 25° / 30°) from the Copernicus GLO-30 elevation model. Select it as the Steep slopes layer and set Slope limit (degrees); the bands at or above that limit are treated as unbuildable, and the rest of the layer is left alone. Leave the limit empty to apply no slope constraint. Do not merge the bands into the unbuildable layer, which would carve every band whatever its slope.
Walkable ways: walkable.geojson holds the footpaths and streets a pedestrian can use. Select it as the Walkable ways layer: where one of these crosses an unbuildable corridor, that cell stays undeveloped but walks may pass through it, so a footbridge or level crossing keeps both sides connected. Edit the layer, or supply your own, to say where crossings exist.
Parameters: in Isobenefit Urbanism, Load parameters with the scenario’s params.json fills in the dialog.
Running: select the layers in the Input layers group, confirm the suggested CRS, choose an output folder and run name, and press Run.
Reproducing a published panel: the explorer’s per-run parameter files carry the exact seed and settings at the scenario’s full resolution. The gallery previews are computed on a coarser grid, so a rerun gives a finer, slower result of the same kind rather than an identical image.

The Extract from OpenStreetMap tool

Area of interest: a polygon, either drawn on the map (left-click corners, right-click to finish, Esc to cancel) or the union of an existing polygon layer. The polygon’s bounding box drives the download; results are trimmed to the polygon.
Datasets: built-up areas, green space, mixed-use centres, industrial land, streets, railways, public-transport stops, rail/tram stations, water, and unbuildable land. The unbuildable dataset combines water, airfields, military land, quarries, industrial land, and buffered corridors along major roads (motorway, trunk and primary), railways and rivers; the water dataset carries the water features on their own, so maps can colour them separately from other unbuildable land. Untick anything not needed.
Output: one GeoPackage; every dataset becomes a layer in it, added to the project under an “OSM” group. The layers arrive pre-styled in a fixed colour scheme (green space green, water light blue, unbuildable land light grey, built fabric the light purple of the plan rasters, transit stops and stations teal), so every download looks the same.

Downloading and simulating are separate steps. The layers are on disk and can be edited or swapped before any run. The simulation dialog recognises the downloaded layers and pre-selects them.

The run dialog, group by group

Parameters. Load parameters repopulates the dialog from a previous run’s *_params.json sidecar or from a scenario preset. Every run writes such a sidecar next to its output. The feedback line under the button lists exactly which fields the load changed and their old and new values, states when every field already matched, and names any keys in the file it could not use (retired or unrecognised dials).

Simulation.

Field	Default	What it does
Max iterations	100	Cap on growth steps; a run stops early at the target population
Grid size (m)	50	Cell size of the simulation grid
Target population	100,000	New residents to house; growth stops once reached (checked between iterations, so the final count can slightly overshoot)
Build probability	0.25	Per-step chance an eligible cell develops (the growth rate)
Dispersed development	Moderate	Leapfrog rate: Off / Moderate / Aggressive
Random seed	42	The same seed reproduces the same run and the same ensemble, independent of core count

Walkable access. Centre walk (1,200 m) and Green walk (400 m): how far people walk to a mixed-use centre and to a park. The defaults follow common practice: a ten-minute walk to a neighbourhood centre, and everyday green within the stricter reach the WHO and Natural England standards use. During growth the engine uses one walk radius for its checks, set to the larger of these two values, so growth is never cut off by the stricter one mid-run. The finished plan is then scored against each walk separately, and any shortfall shows in the coverage figures and steers the centre re-positioning.

Three further fields steer transit-oriented growth. Stop catchment (400 m) is how far people walk to a bus stop; it defines the catchment around the transit corridor layer. Hub catchment (1,200 m) is how far people walk to a station or designated hub; it defines the wider catchment around the transit hub layer, and its default matches the centre walk because a hub anchors a centre. Corridor preference (0 to 1, default 0) concentrates development along transit: outside the two catchments, the build and seeding draws are scaled by one minus the preference, so at 0 the transit layers are reported only, at intermediate values growth favours transit but can still spill beyond it, and at 1 growth is confined to the catchments. When the catchments cannot hold the target population the run log says so and states the consequence.

Post-processing.

Field	Default	What it does
Optimise centre placement	on	Alongside the as-grown option, save two more: optimised placement (the run’s centres re-positioned to cut walking distances, plus any the provision rule requires; a nearby existing centre does not stand in for new development) and fewest centres (the smallest number that keeps every home within the centre walk). Off saves only the as-grown option. Every option keeps every home within the centre walk
Centre area (m² per person)	20	Mixed-use centre land provided per new resident served
Service viability (people)	2000	The demand a centre must reach within the centre walk to be viable; the default sits at the small end of published facility catchments. Each settlement hosts an attached centre of its own; catchments cross green gaps, so nearby settlements pool their demand toward each centre’s viability; centres below the threshold are cut, and growth left without a viable centre reverts to green. Before the run, open land is developable only where it is locally wide and its region either holds the threshold or lies within the centre walk of an existing centre (served infill); other open land is set aside as protected green (pocket parks). The raw plan keeps everything for comparison
Min green span (m)	400	No green corridor between developments may narrow below this span
Min park area (ha)	2	A contiguous green area must reach this size to qualify as a park, in growth and in the scores; the default follows Natural England’s accessible natural greenspace standard

Development density. Three densities (people per km²) for the high, medium and low tiers, each with a share. The dialog requires positive, strictly descending densities and shares between 0 and 1 that sum to 1; the feedback line shows the running total and the mean. Every new block is built at one of the three densities; post-processing arranges the highest nearest the mixed-use centres.

Output. Development likelihood (the default) blends many runs; the Detail picker sets how many (Quick 10 / Standard 50 / Thorough 100). Untick it for a single run written as a growth animation. The output folder and run name determine where the run’s files land (see Outputs below); the CRS must be a local projected CRS (a suggestion is made from the extents layer; geographic lat/lon CRSs are rejected so the model always works in metres).

Input layers. Extents (required, polygon) plus optional existing urban, existing green, unbuildable, urban centres (points or polygon areas), transit corridors (bus stops as points, or a proposed corridor drawn as a line), and transit hubs (rail/tram stations, or any planner-designated hub point). All layers may be in any CRS; they are reprojected to the chosen run CRS.

The Run button stays disabled until four things are set: an extents layer, an output folder and run name, a projected CRS, and valid densities and shares. The red status line names whichever are missing.

How distances, barriers and public transport are treated

During growth, every distance is a walk across the land grid (diagonal steps allowed), bounded by the walking distance. A walk cannot cross unbuildable land, so water and carved road or rail corridors must be walked around, not over. Streets are not used during growth, and straight-line (crow-flies) distances are never used anywhere.
In post-processing and scoring, the same grid walk applies, so growth and scoring always agree. Street-network distances are not used: a new settlement’s streets do not exist yet, so a network metric would measure new development and existing fabric on different terms. The downloaded streets layer serves as map context, and major-road (motorway, trunk and primary) and rail corridors derived from it are carved as barriers.
Transit hubs (rail and tram stations, or any point a planner adds to the hubs layer) anchor a mixed-use centre: during growth the simulation treats the hub like a centre, so development gathers around it, and in post-processing the centre is pinned at the hub, never moved or culled, and grows and is sized like any other centre. Adding a point to this layer is how a designated centre, a transit-oriented development around a planned station for example, is placed by hand. Hubs and stops that fall on a carved corridor cell are snapped to the nearest walkable cell (a station sits on its own railway, and railways are carved as barriers).
Transit corridors (bus stops, or a proposed corridor drawn as a line) attract growth without anchoring centres. When the corridor preference is above 0, development draws at full probability inside the stop catchment of a corridor or hub and at a reduced probability outside it, so settlements form along existing bus routes or a route the planner proposes. At the default preference of 0 the corridor layer only feeds the report, which states how many new homes end within the stop catchment.

Outputs and how to read them

Ensemble mode writes a family of files into the output folder, sharing the run name: <name>.tif (the built and green likelihood bands), <name>_existing.tif (the starting fabric), <name>_pre.tif (the chosen run before post-processing, coloured by the density tiers the run actually drew, in place), <name>_grown.tif, <name>_placed.tif and <name>_fewest.tif (the three centre options: centres as grown, optimised placement and fewest centres, each coloured by arranged density tier, with built as a yellow-to-brown ramp, mixed-use centres as a reds ramp, and existing fabric muted), <name>_rejected.tif (the diagnostic layer of raw growth the plans rejected, coded by reason: a satellite below the service viability threshold, or growth in a centreless hamlet), <name>_report.txt (the run record) and <name>_params.json (the reloadable settings). Every option keeps each home within the centre walk. QGIS loads the rasters as one layer group, ordered existing fabric, then the raw pre-processing run, then the centre options, with the likelihood bands at the bottom.

The report file is the durable summary of the run: the parameters, then fixed-width tables with the plan options side by side (population accommodated and share of the target, coverage, average walks, per-person centre and green provision), the achieved density mix per tier, and the centre audit including the weakest new centres.

This excerpt is from a run on the committed Cambourne scenario (30,000-person target, at the scenario’s committed settings):

PLAN OPTIONS (side by side; coverage and walks count new homes)
----------------------------------------
  Metric                                            raw   grown  placed  fewest
  ---------------------------------------------  ------  ------  ------  ------
  population accommodated                        31,129  21,582  21,567  21,567
  share of target                                  104%     72%     72%     72%
  built cells (incl. existing)                    6,110   4,768   4,768   4,768
  mixed-use centre areas                             64      46      43      43
  served coverage, new homes (centre AND green)    100%    100%    100%    100%
  incl. existing fabric (no guarantee)              99%     97%     97%     97%
  existing homes alone (FYI)                        95%     91%     91%     91%
  avg walk to a centre (m)                          276     244     242     236
  avg walk to green (m)                             102     104     104     104
  m2 mixed-use centre / person                        4      17      16      16
  m2 walkable green / person                      1,590   2,449   2,451   2,451

Reading it: the four columns are the raw run and the three centre options. The options share the same cleaned fabric and differ only in their centres, so the rows that move between them are the centre count, the walks and the centre provision; here optimised placement consolidates to 43 centre areas against 46 as grown, and the mean centre walk ranges from 236 to 244 m. Every new home is served in all four columns, because the growth rules enforce both walks; the incl.-existing row blends in the fixed fabric, which carries no guarantee, and the FYI row shows the existing homes alone. The gap between raw and the options is the cleanup: the raw run overshoots the target slightly, but part of its growth lies in pockets whose pooled new demand stays below the 2,000-person viability threshold, which revert to green (detached) or join the existing fabric (infill), so the options credit 72% of the target against the raw run’s 104%. A full report adds the walk means, compactness, transit readouts where stops were supplied, the achieved density mix per tier, and the centre audit.

Every population figure counts new residents only; existing fabric is assumed served by its own centres. The per-person readouts follow the same convention: m² of mixed-use centre per person is new centre land over new residents, and m² of green per person is new green over new residents.

Single-run mode writes one band per growth step, plus its own <name>_report.txt (the parameters and the outcome: population accommodated, iterations used). QGIS loads the raster as a temporal animation: open View → Panels → Temporal Controller, press the play button, and the town grows step by step.

Troubleshooting

The engine installed but the tools stay disabled: restart QGIS; the check runs again on the next launch.
Run is greyed out: read the red status line; it names the missing pieces (extents layer, output folder and run name, projected CRS, densities/shares).
“Select a local projected CRS”: geographic (degrees) CRSs are rejected. Accept the suggested UTM zone, or pick the national grid for the area.
“The extents are too small”: the area must exceed twice the walking distance in both directions; enlarge the extents polygon or shorten the walks.
OSM fetch fails: the Overpass servers are shared and sometimes busy; retry after a minute, or draw a smaller area.
Growth stalls or falls short of the target: the run report states the population reached and the iterations used. If the iterations ran out, raise Max iterations or the Build probability. If growth stopped early with iterations to spare, the frontier has usually run out of room within the rules: the Centre walk bounds growth around each centre and new centres seed by a small per-iteration chance, so give reluctant runs more iterations rather than more probability first. Remember the target counts new residents only; existing fabric contributes nothing, however large. A Minimum green span wider than the gaps between built areas also freezes infill: gaps narrower than the span never fill, by design. Engines before 0.12.11 refused to grow toward rivers and carved road corridors; if growth halts a fixed distance from every barrier, update the engine when prompted.
Finding the logs: View → Panels → Log Messages, under the Isobenefit tab, records grid size, per-stage progress, per-option metrics and any warnings.
Recovering a run’s settings: they are saved next to the output raster as <name>_params.json, and load back with the dialog’s Load parameters button.