Use Cases > Cluster Planning > How to change territories > ... with predefined limits

How to plan territories with activity limits

A predefined activity limit for a territory ensures that the sum of all its activities is roughly constrained. Since a territory can only have exactly one limit assigned, the entire territory will be limited by this single constraint on the basis of the sum of all its activities. Having multiple limits constraining one and the same territory is therefore not possible. To be able to limit a territory on the basis of all its comprised activities, a limit has to be uniquely assigned to a territory by referring to the unique identifier of the territory.

Typical use cases for the use of limits are territory planning, location assignment and change territories.

Limiting territories can have a major impact on the calculation results in all use cases. However, when limits are applied, it can become impossible to find a valid calculation result. If this occurs, more reasonable values for the limits themselves or other planning parameters within the planningProfile need to be considered.

Terminology

limit: A limit is an optional property within a PTV xTerritory server request that constrains the sum of all activities of exactly one existing territory that is uniquely referenced by this individual limit. The maximumValue field of a limit is used as total number for allowed activities within the territory that uniquely references the limit.

Benefits

Limits give more fine-grain control over the calculation process during territory planning, location assignment and change territories by optionally limiting the sum of activities within territories.
Limits constrain the sum of activities of territories (for each territory individually by a unique limit) to fit to individual site conditions or employee experience.
Limits can be set before each calculation step planTerritories(), distributeLocations() or changeTerritories().

Prerequisites

Check if the following prerequisites are fulfilled before you start with one of the supported use cases.

PTV xTerritory server has been installed and the desired map is configured correctly.
A valid license for the individual use case: territory planning, location assignment and/or change territories.

Concept

In general, limiting an existing territory's capacity on the basis of its comprised locations' activity values adds fine-grain control not only during location assignment and change territories but also during initial territory planning. The only difference is that with territory planning, limits must not reference any territory because there are no pre-existing territories.

If no limits should be used, the field for the list of limits within a PTV xTerritory server request has to be left out completely - do not hand an empty limits array to the PTV xTerritory server.

Definition and interpretation of limits

The sum of all user-defined activity limits does not necessarily have to fit the exact sum of all activities. If the sum of limits is less or greater than the total sum of activities, PTV xTerritory server will not try to meet the exact values of the specified limits, but will consider them as weights. Exact limit values are therefore calculated based on the given limit proportions and then used for planning (see planning scenario 2).

Territory Planning

In the use case territory planning, user-defined limits must not assign territories since they do not yet exist. If limits carry assignments to non-existing territories, the PTV xTerritory server will not start to plan territories.
The number of user-defined limits must always be equal to the exactNumberOfTerritories within the planningOptions of the PTV xTerritory request, otherwise the PTV xTerritory server will not start to plan territories.

Location Assignment

In the use case location assignment the number of user-defined limits must be equal to the length of the list of existing territories specified in the request. This means there have to be as many limits as there are territories within the territories array of a PTV xTerritory request. Every limit needs to be uniquely assigned to an individual existing territory that has not set candidate=true, so every territory has a unique maximumValue assignment prior to calculation.

Change Territories

In the use case change territories, independently of increasing/decreasing (with or without candidates) of the number of territories, the number of user-defined limits must always be equal to the exactNumberOfTerritories within the planningOptions of the PTV xTerritory request. If this prerequisite is kept, all change scenarios can be calculated with activity limits.

If the user-defined limits are not met right away after the calculation has terminated, check if they do when the field imbalanceTolerance is considered or check if setting the solutionQuality=HIGH achieves desired results.

Programming Guide

The following examples all relate to the use of AbsoluteActivityLimits. In order to restrict tour periods, please see the use case "How to estimate tour periods".

How to set limits in general

In order to carry out a territory planning, location assignment, or territory change with predefined limits, the following is required:

Locations
Planned Territory objects, locations can be assigned/are assigned to (not necessary for territory planning).
As many AbsoluteActivityLimit objects as (desired) Territory objects because every territory has to be limited. Limiting only a subset of territories is not possible.

Set locations for the use of limits

In order to balance the sum of activity measure per territory, the class AbsoluteActivity is used. Each Location object needs to provide an AbsoluteActivity object because only this type of Activity works in conjunction with AbsoluteActivityLimits.

"locations": [
  {
    "id": "location1",
    "coordinate": {
      "point": {
        "x": 6.166279,
        "y": 49.629301
      }
    },
    "activity": {
      "$type": "AbsoluteActivity",
      "value": 3.0
    }
  },
  {
    "id": "location2",
    "coordinate": {
      "point": {
        "x": 0.166279,
        "y": 0.629301
      }
    },
    "activity": {
      "$type": "AbsoluteActivity",
      "value": 5.0
    }
  }
]

Set existing territories that should be limited (not relevant for territory planning)

For the use cases location assignment and change territories, each limit has to refer to a specific territory. These territories need to be set within the request to the PTV xTerritory server as well.

"territories": [
  {
    "id": "territory1",
    "referencePoint": {
      "point": {
        "x": 6.424008,
        "y": 49.704545
      }
    }
  },
  {
    "id": "territory2",
    "referencePoint": {
      "point": {
        "x": 12.848016,
        "y": 49.704545
      }
    }
  }
]

Set limits in the planning profile

Within the planningProfile attribute of a PTV xTerritory server request, set as many AbsoluteActivityLimit objects into the list of limits as there are territories to be planned. Make sure that each existing Territory object is only assigned to exactly one AbsoluteActivityLimit object within the list of limits. Keep in mind that for the maximumValue of a territory limit only a value greater 0 is allowed.

"planningProfile": {
  "limits":
  [
    {
      "territoryAssignment": "territory1",
      "$type": "AbsoluteActivityLimit",
      "maximumValue": 8.0
    },
    {
      "territoryAssignment" "territory2",
      "$type": "AbsoluteActivityLimit",
      "maximumValue": 8.0
    }
  ]
}

Objects in the response

The actual limit values that were used for calculation are not returned in the response. Limits were considered correctly if the proportions of all totalActivity values are equal to the limit proportions specified in the request.

Planning Scenario 1 - Working with exact activity limits when planning territories from green field

When planning territories, your user-defined limits are considered for the calculation for new, yet non-existing territories. The following sample scenario will help you to understand how territories can be limited right from their initial planning by using exact limit values.

Parameters of the sample scenario

There are three existing locations, each given with the following activity values:
- Location A: activity = 60.0
- Location B: activity = 50.0
- Location C: activity = 30.0
This totals to an overall sum of activity of 140.0 for all three existing locations.
Furthermore, the number of territories to be planned (not yet existing) are: exactNumberOfTerritories = 3.
Finally, the three activity limits (as many as exactNumberOfTerritories) that you want to be considered by the PTV xTerritory server for the three future territories are:
- Activity limit for future territory I: maximumValue = 30.0
- Activity limit for future territory II: maximumValue = 60.0
- Activity limit for future territory III: maximumValue = 50.0
All three activity limits must not carry any territory assignment, since there are no assignable territories yet.

Planning results

Since the limit values exactly fit the specified activity values, the expected result is that location A is assigned to territory II, location B is assigned to territory III, and location C is assigned to territory I.

In general, the planning result may vary due to the optimization parameters given to the PTV xTerritory server. If the limit values are not met as expected, consider setting the imbalanceTolerance to a smaller value, or setting the solutionQuality to HIGH

Planning Scenario 2 - Working with activity limits as weights when planning territories from green field

When planning territories, your user-defined limits are considered for the calculation for new, yet non-existing territories as weights. The following sample scenario will help you to understand how territories can be limited right from their initial planning by using limit values that are considered as weights.

Parameters for the sample scenario

There are three existing locations, each given with the following activity values:
- Location A: activity = 60.0
- Location B: activity = 50.0
- Location C: activity = 30.0
This totals to an overall sum of activity of 140.0 for all three existing locations.
Furthermore, the number of territories to be planned (not yet existing) are: exactNumberOfTerritories = 3.
Finally, the three activity limits (as many as exactNumberOfTerritories) that you want to be considered by the PTV xTerritory server for the three future territories are:
- User-defined limit for future territory I: 90.0
- User-defined limit for future territory II: 60.0
- User-defined limit for future territory III: 80.0
Which totals to a sum of activity limits of 230.0. Therefore the actual activity limits have to be calculated by PTV xTerritory server, considering the given limits as weights:
- Calculated limit for future territory I: 140 x 90/230 = 54.78
- Calculated limit for future territory II: 140 x 60/230 = 36.52
- Calculated limit for future territory III: 140 x 80/230 = 48.69
All three activity limits must not carry any territory assignment, since there are no territories to be assigned.

Planning results

Since the limit values do not exactly fit the specified activity values, the expected result is not trivial. There could be several valid solutions.