Deepening IV, Discrete allocation

learning objective: setting up a discrete land-use allocation with discrete_alloc: the land units, the suitabilities, the regions and the claims, and checking whether the result meets the claims

introduction

Module 7, Allocating land use works with the continuous allocation of the Land Use Scanner: each cell gets a mix of land-use types. The discrete allocation gives each cell exactly one land-use type, the one with the highest suitability, as long as the regional claims allow it. Appendix 7I, Land Use Scanner Background explains the method: the allocation is a linear programming problem, and its solution is optimal when the sum of the suitabilities of all allocated cells is as high as possible within the claims.

This deepening shows how such an allocation is set up in GeoDMS, with the operator discrete_alloc. It uses the project in the folder allocation of the Academy repository. Open allocation/cfg/allocatie.dms in the GeoDMS GUI; the discrete allocation is in the container Results/Discrete, in the file cfg/allocatie/results.dms. The same file also contains a continuous allocation (Results/Continueous) that you can compare it with.

This page assumes you know relations and aggregations (Module 1c, Learning the basic concepts of GeoDMS, calculations over multiple domains), for_each (Module 3, Meta scripting ‐ templates and for_each) and the potential function (Module 5, Basic analyses with grid data).

the example

The land units are the cells of a 100 m grid of the Netherlands. The land use of 2017 has ten types, from residential and agriculture to water and exterior water. The claims are set per COROP region, the 40 regions between the provinces and the municipalities. The example is about the mechanics, not about a realistic scenario: the suitability of a cell for a type is the share of that type in its surroundings, so the allocation mostly smooths the current map.

step 1: the land units

discrete_alloc needs a domain unit with the land units that take part. Cells outside all COROP regions, at sea and abroad, should not take part, so the example selects the cells with a region:

unit<uint32> ADomain := select_with_org_rel(IsDefined(AggRegio/per_grid))
,	DialogType = "Map"
,	DialogData = "BaseGrid";
attribute<ADomain> BaseGrid (NL_grid/domain) := invert(ADomain/org_rel);

ADomain has 3,503,974 land units. org_rel relates each land unit to its cell, and BaseGrid, the inverse relation, relates each cell to its land unit. With BaseGrid the result goes back to the grid at the end, and the two dialog properties let you show attributes of ADomain as a map.

If the cells have a part that is not allocated, such as water or infrastructure that stays where it is, select only the cells of which most is free. Otherwise a cell with a small piece of free land gets a whole land-use type. The Land Use Scanner of Modules 7 and 9 does that with the parameter MinFreeShareDiscrete.

step 2: the suitabilities

discrete_alloc needs, for each land-use type, an attribute of the land units with its suitability, all in one container and all with value type int32. The example makes them with for_each_nedv, one item per land-use type:

container Suitability :=
	for_each_nedv(
		LandUse/name
		, 'convert(potential(float32(SourceData/Landuse/Predominant == LandUse/V/'+LandUse/name+'), /Geography/Kernels/kernel_100m/relddWeight) * 100f, int32)[ADomain/org_rel]'
		, ADomain
		, int32
	);

The suitability is the share of the type within about 2 km, weighted by distance, times 100. Because the values are whole numbers, the factor 100 sets the precision: suitabilities that differ by less than 0.01 become equal. The names of the items must be exactly the names in LandUse/name, because discrete_alloc looks them up by name.

step 3: the regions

Each land-use type has its claims on one set of regions, a partitioning. In the example all types use the same partitioning, the COROP regions:

unit<uint8> Partitioning: nrofrows = 1
{
	attribute<string> name : ['id'];
}
attribute<AggRegio> AtomicRegionMap (ADomain) := AggRegio/per_grid[ADomain/org_rel]
{
	attribute<AggRegio> id (AggRegio) := id(AggRegio);
}

When the types use different partitionings, for example provinces for agriculture and municipalities for housing, the atomic regions are the intersections of the regions of all partitionings. Then each partitioning gets an attribute of the atomic regions with the region it belongs to, under its name in Partitioning/name. With one partitioning the atomic regions are the COROP regions themselves, and the attribute id relates each to itself. See AtomicRegions for the general case.

step 4: the claims

The claims are numbers of land units, not hectares: per land-use type an attribute of the regions with the minimum, and one with the maximum. In the example a type may get at most twice the number of cells it has now in a region, and the minimum is 0:

container maxclaims :=
	for_each_nedv(
		  LandUse/name
		, 'sum(uint32(SourceData/Landuse/Predominant == LandUse/V/'+LandUse/name+'), AggRegio/per_grid) * 2'
		, AggRegio
		, uint32
	);
container minclaims :=
	for_each_nedv(
		  LandUse/name
		, 'const(0, AggRegio)'
		, AggRegio
		, uint32
	);

Before allocating, discrete_alloc tests whether the claims fit the number of land units per region, as if every land unit were suitable for every type (the FeasibilityTest). With one partitioning, that means that in every region the minimum claims together may not exceed the number of land units, and the maximum claims together must reach it. If the test fails, it allocates nothing, and its status says by how many cells the claims should change.

step 5: the allocation

With the threshold, the minimum suitability a type needs on a land unit to be allocated there, the call has all its arguments:

parameter<int32> threshold := int32(0);

container Disc_alloc :=
	discrete_alloc(
		  LandUse/name                          // 1  the land-use types
		, Input/Compacted/ADomain               // 2  the land units
		, Input/Compacted/Suitability           // 3  suitability per type
		, const(0[Partitioning], LandUse)       // 4  partitioning per type
		, Partitioning/name                     // 5  name per partitioning
		, Input/AggRegio                        // 6  the atomic regions
		, Input/Compacted/AtomicRegionMap       // 7  atomic region per land unit
		, Input/Claims/minclaims                // 8  minimum claims
		, Input/Claims/maxclaims                // 9  maximum claims
		, threshold                             // 10 minimum suitability
		, FeasibleSolution                      // 11 not used; may be left out
	);

All suitabilities in the example are 0 or more, so a threshold of 0 excludes nothing. A higher threshold leaves land units without a type (null) when no type reaches it, and can make a minimum claim impossible to meet.

step 6: the result and its status

The result is a container with these items, among others:

  • Disc_alloc/landuse: the land-use type of each land unit;
  • Disc_alloc/statusFlag: true if the allocation meets all claims;
  • Disc_alloc/status: a text that explains the flag;
  • Disc_alloc/shadow_prices: per type and region the price that made the claims fit.

The example gives the result a values unit and brings it back to the grid with BaseGrid:

attribute<LandUse> LandUse_rel (Input/Compacted/ADomain) := Disc_alloc/landuse;
attribute<LandUse> Result_discrete (NL_grid/domain) := Allocation/LandUse_rel[invert(Input/Compacted/ADomain/org_rel)];

Calculate Disc_alloc/status. In GeoDMS 20.26 it reads: DiscrAlloc completed for 54 tiles with a total magnified suitability of 247,503,663 over 3503974 land units = 70.635131 per land unit, which is optimal. So the average suitability of the allocated types is 70.6, a share of 0.706.

check the result against the claims

A status that says optimal is not yet proof that the result is what you meant. Count the allocated cells per type and region yourself and compare them with the claims. For residential, add this container to Results/Discrete, next to Allocation:

container Check
{
	attribute<uint32> residential_allocated (Input/AggRegio) := sum(uint32(Allocation/LandUse_rel == LandUse/V/residential), Input/Compacted/AtomicRegionMap);
	attribute<bool>   residential_ok        (Input/AggRegio) := residential_allocated >= Input/Claims/minclaims/residential && residential_allocated <= Input/Claims/maxclaims/residential;
	parameter<uint32> residential_now                        := sum(uint32(SourceData/Landuse/Predominant == LandUse/V/residential)[Input/Compacted/ADomain/org_rel]);
	parameter<uint32> residential_after                      := sum(residential_allocated);
}

residential_ok is true in all 40 regions, and the same holds for the other types: no type exceeds its maximum in any region. But residential gets 177,143 cells, while it has 257,684 now. Nothing is wrong with the allocation: the minimum claims are 0, and where agriculture dominates the surroundings, a residential cell gets agriculture. The claims decide what the allocation may do, so they are the first place to look when a result surprises you.

exercises

  1. Set the minimum claims to the number of cells each type has now: replace 'const(0, AggRegio)' by 'sum(uint32(SourceData/Landuse/Predominant == LandUse/V/'+LandUse/name+'), AggRegio/per_grid)'. The minimum claims of a region then add up to all its land units, so each type gets exactly its current number of cells and only their locations change. Check this with the container Check. The status now gives an average of 66.2: the claims leave less freedom, so the total suitability is lower.
  2. Compare the result of exercise 1 with the current land use on the map: which cells change, and why there?
  3. Set the minimum claims back to 0, raise the threshold to 50 and look at statusFlag and status. Which claims are no longer met, and which land units stay without a type? Why does the allocation then exceed the maximum claims of some types?
  4. Look at Disc_alloc/shadow_prices for residential after exercise 1. In which regions is the price high, and what does that say about the claim there?

the Land Use Scanner

The Land Use Scanner of Modules 7 and 9 uses discrete_alloc_sp, the variant for one partitioning: it takes the regions and the region of each land unit instead of the partitionings and the atomic regions. Its discrete result is in the hidden container Simulations/<scenario>/Results/Discrete, and its set-up is in Templates/Allocation_Procedures.dms of LandUseModelling, in the container CaseData/allocate_discrete. There the claims come from the scenario in hectares and are converted to numbers of cells, between 90 and 110 percent of the claim.