Allocation functions

Allocation functions discrete_alloc

Land-use allocation is the process of the assignment of land resources for various usage purposes. It is used to find the allocation of land use to land units that maximize total suitability, given a set of claims, when endogenous interactions are disregarded. The following two allocation processes are distinguished:

1. continuous: each unit of land is allocated to a percentage, indicating the expected value of each land use type for this land unit. The continuous allocation (aka probabilistic allocation) can be configured with the loop operator; see, for example, the Land Use Scanner Student Edition configuration.
2. discrete: each unit of land is allocated to one out of a limited set of land use types. Use the discrete_alloc function, described on this page, for this allocation process.

syntax

• discrete_alloc_np(

  • TypeNames: (LUT: Uint8)->ItemName
  • LandUnitDomain
  • SuitabilityMaps: for each TypeNames { LandUnitDomain->Int32 }
  • MinClaims: for each TypeNames { -> UInt32 }
  • MaxClaims: for each TypeNames { -> UInt32 }
  • Threshold: ->Int32)

• discrete_alloc_sp(

  • TypeNames: (LUT: Uint8)->ItemName
  • LandUnitDomain
  • SuitabilityMaps: for each TypeNames { LandUnitDomain->Int32 }
  • Regions: UInt16 domain
  • RegionMap: LandUnitDomain->Regions
  • MinClaims: for each TypeNames { Regions -> UInt32 }
  • MaxClaims: for each TypeNames { Regions -> UInt32 }
  • Threshold: ->Int32)

• discrete_alloc(

  • TypeNames: (LUT: Uint8)->ItemName
  • LandUnitDomain,
  • SuitabilityMaps: for each TypeNames { LandUnitDomain->Int32 },
  • PartioningAttribute: LUT->P, PartioningName: P->itemname,
  • AtomicRegions: UInt16 domain with for each PartioningName { AtomicRegions->UInt8 },
  • AtomicRegionMap: LandUnitDomain->AtomicRegions,
  • MinClaims: for each TypeNames { Domain of PartioningAttribute -> UInt32 },
  • MaxClaims: for each TypeNames { Domain of PartioningAttribute -> UInt32 },
  • Threshold: ->Int32)

• discrete_alloc_np_16

• discrete_alloc_sp_16

• discrete_alloc_16(

  • *TypeNames: (LUT: Uint16)->ItemName,
  • *LandUnitDomain,
  • *SuitabilityMaps: for each TypeNames { LandUnitDomain->Int32 },
  • *PartioningAttribute: LUT->P,
  • *PartioningName: P->itemname,
  • *AtomicRegions: UInt16 domain with for each PartioningName { AtomicRegions->UInt8 },
  • *AtomicRegionMap: LandUnitDomain->AtomicRegions,
  • *MinClaims: for each TypeNames { Domain of PartioningAttribute -> UInt32 },
  • *MaxClaims: for each TypeNames { Domain of PartioningAttribute -> UInt32 },
  • *Threshold: ->Int32)

• greedy_alloc_np

• greedy_alloc_sp

• greedy_alloc

• greedy_alloc_np_16

• greedy_alloc_sp_16

• greedy_alloc_16

definition

The discrete_alloc function is used to find the discrete allocation of land use to land units that maximize total suitability under the constraints of minimum and maximum claims.

arguments

The discrete_alloc function has 11 arguments:

• TypeNames: an attribute with the name of each land use type, value type: string;
• LandUnitDomain: the domain unit for which the allocation is calculated, value type: uint32;
• SuitabilityMaps: a container with a suitability map for each land use type, value type: int32;
• PartioningAttribute: an attribute that maps each land use type to a partitioning id (a set of attributes with uint8 value type);
• PartioningName: an attribute that maps each partitioning to a partitioning name such as "province" or "municipality", value type: string;
• AtomicRegions: the domain unit defining the set of atomic regions, value type: uint16;
• AtomicRegionMap: an attribute defining to which atomic region each land unit belongs, value type: uint16;
• MinClaims: a container with for each land use type an attribute that defines for each region of the partitioning that belongs to that land use type, the minimum number of land units that should be allocated to that land use type within the region, value type: uint32;
• MaxClaims: a container with for each land use type an attribute that defines for each region of the partitioning that belongs to that land use type, the maximum number of land units that should be allocated to that land use type within the region, value type: uint32. Make sure that the total claims are larger or equal to the number of cells in the analysis;
• Threshold: a parameter defining the minimum suitability value that a land use type should have to get allocated, value type: int32;
• FeasibleSolution: arbitrary container for possible future use (empty container).

results

The function results in the following set of subitems:

• landuse: the attribute containing the allocated land use types for the land units. The values unit of this attribute is a set of land use types; the domain unit is the LandUnitDomain. If the LandUnitDomain is configured as a subset of an original land use grid domain, a lookup function can be used to relate the allocated results to the original land use grid (see the example).
• status: a string parameter describing whether the function resulted in an optimal solution or not. In the latter case, the reason why an optimal solution could not be reached is indicated.
• statusflag: a boolean parameter with the value True if the function resulted in an optimal solution and False in all other cases.
• shadow_prices: a container with subitems for each land use type. These subitems are attributes containing the shadow_prices for each land use type. The value type of these prices is int32. The domain units are the domain units of the claims for these land use types.
• total_allocated: a container with subitems for each land use type. These subitems are attributes containing the number of allocated land units for each land use type. The value type of these numbers is uint32. The domain units are the domain units of the claims for these land use types.
• bid_price: an attribute containing the resulting bid prices of the allocation process. The values unit of this attribute is the same as the values unit of the suitability maps; the domain unit is the LandUnitDomain.

description

When applied iteratively and by incorporation of dynamic neighbourhood enrichment, one can simulate land use change caused by natural processes.

When applied iteratively with feedback from future (neighbourhood-dependent) yields on the current suitability, one can model a time-consistent market equilibrium.

More information on the discrete allocation function can also be found in our wiki.

example

container allocate_discrete := 
   discrete_alloc(
       lu_type/name
      ,Compacted/ADomain
      ,Compacted/SuitabilityMaps
      ,lu_type/partioning
      ,lu_type/PartioningName
      ,AtomicRegions
      ,Compacted/AtomicRegionsMap
      ,claims_min
      ,claims_max
      ,threshold
      ,FeasibleSolution
   )
 {
    attribute<lu_type> alloc (GridDomain) := landuse[Compacted/BaseGrid];
 }

full script

• full discrete alloc script