9, Final exercise land use allocation

Extending the RuimteScanner for a client


Background

In modules 0 to 3 you learned the GeoDMS language: items and namespaces, units and domains, calculations across domains, classification and visualisation, reading and writing data, and meta scripting with templates and for_each. In this closing exercise, you apply all of that to a working model rather than a clean sheet.

The model is a simplified version of the RuimteScanner (Land Use Scanner, RS 1.0). It allocates a fixed set of land-use classes to grid cells. Three ingredients drive the allocation:

Ingredient What it is Where it lives in the config
Claims The regional demand (in hectares) per land-use class, per allocation region /Scenario_Components/Regional_Demand/<Scenario>/per_LU_type/<lu-class>
Suitability A score per grid cell per land-use class, expressing how fit a cell is for that use /Scenario_Components/Local_Suitability/<Scenario>
Allocation region The spatial unit at which claims are defined and balanced /ModelParameters/RegioUnit_str

The allocation engine then assigns each cell to the class that, given the claims and the suitability, produces the most plausible spatial pattern.

This exercise mirrors three concrete extensions that a client wants to make to its own RS 1.0 configuration:

Client goal Task in this exercise
Add more suitability layers Task 2
Define claims at a finer regional level (province, COROP, municipality) instead of Randstad, Intermediate and Periphery Task 3
Split land-use further, for example, economic sectors into sub-classes Task 4

By the end, you will have added a suitability factor, a finer allocation region, and a new land-use class to a running model, and you will have seen the effect of each change on the allocation result.


Before you start

You need a working GeoDMS GUI (module 0) and the exercise configuration.

  1. Download the LUS demo here. The zip unpacks as LandUseModelling-main.
  2. Unzip it to your local project directory and open LandUseModelling-main/lus_demo/cfg/demo.dms in the GeoDMS GUI.
  3. The configuration runs out of the box with the three zones Randstad, Intermediate and Peripheral as allocation regions.

Several containers of this model are hidden, such as Classifications and Final_Results. Switch on Show hidden items in Settings > GUI Options to see them in the tree. The parameter ModelResolution in demo.dms sets the grid to ‘100m’ or ‘500m’; at 500 m every run is much faster, which helps while you build.

The worked-out solution of all tasks is in the branch academy-final-exercise of the same repository: download it here. Use it to check your work, not as a starting point.

A note on how to work: extend in small steps and check the result of each step before moving on. After every change, recalculate and open a result item. If something turns red, the detail pages tell you what is missing. Build up, do not rewrite.


Getting oriented (no scripting yet)

Open the configuration and explore before you change anything.

  • Open the land-use classification Classifications/ggModel. How many classes are there? This is the list of land-use types the model knows; the exogenous ones (infrastructure, water and exterior) are taken as given, the others are allocated.
  • Open the container Scenario_Components/Local_Suitability and in it one scenario, for example A1_GE. For one class, follow how its suitability score is built up from input layers. Notice that each contributing factor is a value on the grid that is normalised and then combined with a weight; in the delivered scenarios only the current land use has a weight, the other factors are listed with weight 0.
  • Open the container Scenario_Components/Regional_Demand. The claims file lus_demo/data/Scenarioclaims/LUS_demo_additionalclaims.xlsx gives the claims per province, and the template Claims_per_LU_T in Templates.dms adds them up per zone. At which regional level does the model use them now? Open Regional_Demand/A1_GE/per_LU_type/Additional_Claims in a table view.
  • Find the model parameter RegioUnit_str in ModelParameters. What does it point to? It selects a unit in /Geography/RegionalUnits.
  • Open the allocation result /Simulations/A1_GE/Results/Continuous/LandUse/Predominant (the same as /Final_Results/A1_GE_Cont) in a map view. This is the picture you will be changing.

Task 1: Reproduce the baseline (verify your setup)

Before extending anything, confirm that you can generate results with the current settings.

  1. Run the allocation with the settings as delivered (/Simulations/A1_GE/Results/Continuous/LandUse/Predominant).
  2. Open the allocation result in a map view.
  3. Note two things you can compare against later: the overall spatial pattern and one number, for example, the allocated area of a single class in /Simulations/A1_GE/Results/Continuous/Evaluation/Total/AllocatedLanduse.

This is your reference. Every later task changes the result, and you want to be able to see what changed.

Checkpoint: You have a result map and at least one reference number written down.


Task 2: Add a new suitability factor (Modules 1c, 1d, 2)

This is the most contained extension and a good warm-up. You add one new input layer and let it influence where a land-use class is allocated.

The configuration reads one layer that no suitability uses yet: the dike rings in /Geography/RegionalUnits/DijkRing, read from lus_demo/data/Geography/dijkringen_2009.shp. A dike ring is an area protected by a closed ring of primary flood defences, and NormPeriod is its safety standard: the return period in years of the flood its dikes are built to withstand. You will normalise it and add it to the suitability of one class.

  1. Add data. Open DijkRing/NormPeriod in a table view and the dike rings on a map. They are polygons, so rasterise them to the grid of the other suitability inputs first (module 2). DijkRing/per_domain already gives the dike ring of each cell on the model grid domain, so NormPeriod[per_domain] puts the standard on the grid. Cells outside all dike rings get no value; decide what they should get.
  2. Normalise it. A suitability contribution is a comparable score, not a raw value. Convert the raw layer to a score on a fixed range, for example, 0 to 1. Think about direction. If a high raw value means less suitable (for example, a high flood probability, which is 1 divided by NormPeriod), subtract the factor in the suitability or invert the score with 1f - factor_score. And check your units: open your factor score in the Detail Pages and look at its values unit and metric. The raw layer carries the unit of whatever it measures; the score you feed into the suitability should not. If the metric still shows, say, years, step 3 would be adding years to scores, and this factor would drown out, or vanish next to, the others.
  3. Wire it into suitability. Open the suitability definition of the class you want to influence (for example, the residential or the industrial class) and add your normalised factor as an extra weighted term.
  4. Run and compare. Recalculate, open the allocation result, and compare it to your Task 1 reference. Where did the allocation of this class move towards or away from?

Reflection: change the weight up and down and rerun. How sensitive is the pattern to this one factor? This is the same tuning judgement you will need for any real suitability layer.

Checkpoint: the new factor appears in the suitability map of your chosen class, and the allocation result has visibly shifted.

Answer for Task 2

In Current_situation/thematic_maps.dms, in the container Safety, the flood probability of the dike ring as a share of the highest one. Years divided by years leaves no unit. Outside the dike rings the score is 0: the high grounds need no dikes, and the river beds have their own layer, Policy_maps/Water/IsReservedForRivers.

attribute<float32> FloodProbability (domain) := MakeDefined(min(RegionalUnits/DijkRing/NormPeriod) / RegionalUnits/DijkRing/NormPeriod[RegionalUnits/DijkRing/per_domain], 0f);

In each scenario file (ScenarioComponents/A1.dms and the others), in the Safety block of the residential suitability; the other classes get the same line with weight 0:

 -  5.0 [Eur_M2] * Safety/FloodProbability

Task 3: Add a finer allocation region (Modules 1c, 2)

The client wants claims at the province, COROP or municipality level instead of the three zones. The claims file already gives the claims per province, and Claims_per_LU_T adds them up per zone (Claim_RandstadIntermediatePeripheral := sum(Claim_Provincie, Provincie/Landsdelen_rel)). So you first switch to the provinces, and then go one level finer, to the 40 COROP regions, for which you make the regions and the claims yourself. Download a geopackage of the regions here, from the zip with the classifications from 2016 onwards, and copy the one of 2026, cbsgebiedsindelingen2026.gpkg, to lus_demo/data/Geography.

  1. Switch to the provinces. Point RegioUnit_str at 'Provincie'. Recalculate and compare with Task 1: the same claims are now balanced per province instead of per zone.

  2. Add data to /Geography/RegionalUnits. Read the layer coropgebied_gegeneraliseerd of the geopackage as a unit COROP, next to Provincie, and rasterise it to the grid (per_domain, as Provincie has one), so that every cell has a region. Give each region its province (Provincie_rel). Open it on the map. Look closely at the coast and the lakes: the CBS boundaries follow the coastline, while the provinces of this model include the water. Land on shores, flats and islands, such as the Marker Wadden, falls outside every COROP region and drops out of the allocation, unless you give it a region of its own province.

  3. Adjust the model parameter. Point RegioUnit_str at 'COROP'. Recalculate and follow where the model now expects claims. It will report that Current_COROP, Claim_COROP and Total_COROP are missing in Claims_per_LU_T, which is the next step.

  4. Provide claims at the new level. You have two options:

    Option A, author them. Make a claim table indexed by the new region and fill it with plausible demands, just like the current Excel file. The sheet COROP of the claims file holds the growth of the built-up area, the population and nature per COROP region in the WLO 2025, from which the claims per province were made. Option B, derive them. Split each province claim over its COROP regions in proportion to the current area of that class per region. The totals per province are preserved. One thing needs care: the land in a region is fixed, so the claims of a region must add up to zero. In the claims file agriculture takes the rest in each province; let it take the rest in each COROP region too. The core of it looks like this, per class:

// current area of a class per COROP region
attribute<claimHa> Current_COROP    (COROP) := ='sum(Current_situation/current_landuse/'+lu_name+', COROP/per_domain)';

// share of the region in the current area of the class in its province
attribute<float32> Share_COROP      (COROP) := Current_COROP / sum(Current_COROP, COROP/Provincie_rel)[COROP/Provincie_rel];

// the claim of the province, divided over its COROP regions
attribute<claimHa> ShareClaim_COROP (COROP) := Claim_Provincie[COROP/Provincie_rel] * Share_COROP;

// agriculture takes the rest, so that the claims of a region add up to zero
attribute<claimHa> Claim_COROP      (COROP) := =lu_name == 'agriculture'
    ? 'ShareClaim_COROP - add('+AsItemList('../'+/Classifications/ggEndogenous/name+'/ShareClaim_COROP')+')'
    : 'ShareClaim_COROP';

// claims are additional, so add the current area to it.
attribute<claimHa> Total_COROP      (COROP) := Current_COROP + Claim_COROP;

For the demo, option B gives you a working result without hand-authoring a single number.

Answer for B

In demo.dms, in ModelParameters and ModelParameters/Advanced:

parameter<string>    RegioUnit_str       := 'COROP'; // RandstadIntermediatePeripheral Provincie COROP

parameter<Meter>     CoropEdge           := 10000[Meter];
parameter<String>    ClaimRest_COROP     := 'agriculture';

In geography.dms, in the container RegionalUnits, next to Provincie:

unit<UInt32> COROP
:	StorageName     = "%projDir%/data/geography/cbsgebiedsindelingen2026.gpkg"
,	StorageType     = "gdal.vect"
,	StorageReadOnly = "True"
,	SqlString       = "SELECT statcode, statnaam, geom FROM coropgebied_gegeneraliseerd"
{
	attribute<rdc_meter>    geometry          (poly);
	attribute<String>       statcode;
	attribute<String>       statnaam;
	attribute<String>       label                   := statnaam;
	attribute<Provincie>    Provincie_rel           := modus(Provincie/per_domain, poly2grid(geometry, domain));
	attribute<rdc_meter>    geometry_edge     (poly) := geos_buffer_multi_polygon(geometry, float64(/ModelParameters/Advanced/CoropEdge), 8b) * Provincie/geometry_edge[Provincie_rel];
	attribute<.>            per_domain      (domain) := MakeDefined(poly2grid(geometry, domain), poly2grid(geometry_edge, domain));
}

The province of a region is the province of most of its cells. A cell outside all COROP regions gets a region of its own province within CoropEdge: the buffer of each region is cut off at the edge of its province. 10 km reaches all land in the lakes and along the coast. The worked-out solution also gives these items a Descr, Source and URL; they are left out here.

In Templates.dms, in the template Claims_per_LU_T, after the zones:

attribute<claimHa> Current_COROP    (COROP) := ='sum(Current_situation/current_landuse/'+lu_name+', COROP/per_domain)';
attribute<float32> Share_COROP      (COROP) := Current_COROP / sum(Current_COROP, COROP/Provincie_rel)[COROP/Provincie_rel];
attribute<claimHa> ShareClaim_COROP (COROP) := Claim_Provincie[COROP/Provincie_rel] * Share_COROP;
attribute<claimHa> Claim_COROP      (COROP) := =lu_name == ModelParameters/Advanced/ClaimRest_COROP
    ? 'ShareClaim_COROP - add('+AsItemList('../'+/Classifications/ggEndogenous/name+'/ShareClaim_COROP')+')'
    : 'ShareClaim_COROP';
attribute<claimHa> Total_COROP      (COROP) := Current_COROP + Claim_COROP;

The existing items Current, Claim and Total of the template pick these up through RegioUnit_str.

  1. Run and compare. Recalculate and open the result. The regional pattern of the claims is now finer. Compare to Task 1: the same total demand is now distributed across more regions.

Reflection: compare the demand and the allocated area per region in Results/Continuous/Evaluation/Regional, for example DemandRealisation. In most COROP regions the claims are met exactly. A small, urban region can however get more claims than it has land for: in Agglomeratie Haarlem the shares of the growth of Noord-Holland in housing, recreation and nature need more land than its agriculture can give up, so the model meets 88 to 99 percent of the demand there, depending on the scenario, and GOF/IsConverged stays false. Where else do you start to see the limits of the split rule and of the available data? Try the municipality level (gemeente_gegeneraliseerd) too: what happens to the result as the regions get smaller?

Checkpoint: the allocation runs at the COROP level, and the result reflects the finer claims.


Task 4: Add a new land-use sector (Modules 1c, 1d, 3)

This is the most involved extension. The client wants to split land-use further, for example, an economic sector into subclasses. Here, you add one new class to the model end-to-end. The same recipe works for any split.

A new class touches four parts of the model: the classification, its start state, its suitability, and its claim. Do them in this order and check after each.

  1. Extend the classification. Add the new class to Classifications/ggModel in classifications.dms: a row in Elements/Text with its name, whether it is exogenous, its colour (r, g, b, from which the BrushColor is made), whether it is urban and its maximum flood damage per hectare, and raise NrOfRows by one. Recalculate and confirm the class appears in the classification table. In this example, add an extra class called ‘services’, which splits the BBG-service classes from residential into its own class: 'services', 'FALSE', '254','150','0', 'TRUE', '6'. The flood damage calculation in Scenario_Components/Floodrisk reads a damage factor per water depth for every class from lus_demo/data/DamageFactors.csv, so give that file a column services too, for example a copy of industrial.

  2. Supply its start state. The model needs to know where the class currently exists on the grid. In this demo, the start-state maps are provided: download bbg2022_LUSdemo_ext_100m.zip from the folder final_exercise_land_use in the data folder of the Academy and unzip it in lus_demo/data/Current_situation, so that its ten maps bbg2022_LUSdemo_ext_100m_<class>.tif land in %projdir%/data/Current_situation/bbg_2022. In these maps the BBG classes retail and hospitality, public facilities, and social and cultural facilities are taken out of residential into services. Then point the model at them: in Current_situation/landuse.dms, change _LUSdemo_100m_ into _LUSdemo_ext_100m_ in the file name of Read_100m. Open Current_situation/Current_landuse/services on the map and check that it lands in plausible places.

  3. Add its suitability. Define a suitability score for the new class, following the pattern of an existing class. Reuse the factors that make sense for it and adjust the weights. The allocation needs a suitability for every class in every scenario, so add it to all five scenario files (A1.dms, A1_Policy.dms, A2.dms, B1.dms and B2.dms).

  4. Add its claim. Add a claim for the new class at the active region level. The claims file has no sheet for services. Either add a sheet Services with the same columns as the other sheets (and a line unit<uint32> Services; in Read_Excel in ScenarioComponents.dms), or let services share the claims of residential, the class it was split from, in proportion to their current area per province. The worked-out solution does the latter, with the parameter ClaimSheet_services in ModelParameters/Advanced. If you are using the split from Task 3, services gets its COROP claims from that split as well. Add the class to the overview Additional_Claims in Claims_per_Scenario_T too.

  5. Run and verify. Recalculate and open the result. Confirm the new class appears in the allocation, in roughly the right places, and that its allocated total (Evaluation/Total/AllocatedLanduse/services) is in line with the claim you gave it (Evaluation/Total/TotalDemand/services).

Reflection and a caveat. RS 1.0 allocates one class per cell, so a split is only as fine as your start-state and suitability data allow. To split, say, an industry into sub-sectors by economic activity (SBI), you need data that distinguishes those sub-sectors in space, for example, an establishment or terrain typology. Where such data does not exist, the split becomes a proxy rather than a true sub-allocation. This is a real boundary of the 1.0 approach and a good thing to discuss as a group.

Checkpoint: the new class is allocated and its total matches its claim.


Task 5 (open): Apply it to your own question

Pick one extension you would actually want in your own configuration.

  • Which region level do you need, and is the data available at that level?
  • Which class would you split, and what data distinguishes the sub-classes in space?
  • Which suitability factor is missing for your case, and where would you get it?

Sketch the four touch points (classification, start state, suitability, claim, or for a region: data, parameter, claims) for your own case. This is the bridge from the demo to your own work.


What you have practised

Task Topic RuimteScanner part
1 Running the model, reading results Allocation result
2 Normalising and combining input layers Suitability
3 Switching the allocation region, deriving claims Allocation region and claims
4 Adding a land-use class end to end Classification, start state, suitability, claims
5 Translating the recipe to your own case All of the above

Go to previous module: 8, Final exercise Deltares

Go to next module: Module 10, Starting your own project