Use Cases > Cluster Planning > How to distribute locations > ... with incompatibilities

How to distribute locations with incompatibilities

Incompatibilities ensure that certain locations are kept separate to certain territories during the location assignment. A typical use case are sales representative that should not serve certain customers or field worker with specific qualifications.

Incompatibilities can, under certain circumstances, have a major impact on the planning result. It can become impossible to find a valid result. If this occurs, the tolerance threshold may have to be altered.

Terminology

incompatibility: A property that disqualifies a location for a certain territories.

Benefits

During the distribution of locations to territories, incompatibilities between locations and territories are taken into account.

Prerequisites

Check if the following prerequisites are fulfilled before you start with the use case.

PTV xTerritory server has been installed
High-performance routing network for calculating routes, if applicable.

Concept

Adding incompatibilities properties to locations enables you, for example, to depict real customer relationships during the planning process. Inverting the attribution enables you to model qualifications instead of incompatibilities. However, incompatibilities can lead to clear inequalities between territories and can even mean that no valid solution can be found. In such cases, it is advisable to alter the permitted tolerance threshold for different activity totals (PlanningProfile.imbalanceTolerance).

Configuration Guide

In addition to the digital map of the area which contains the locations, a license is required for the distributeLocations, in the case of location assignment, as well as for the desired number of territories and locations.

If high-performance routing networks are to be used, a license must also be obtained for these. Furthermore, the path to the Routing Network folder must be placed accordingly in conf/xterritory.properties.

Programming Guide

In order to carry out territory planning or location assignment, the following are required:

locations with incompatibilities
parametrisation for the calculation of stretches of route
Number/territory centres of territories to be planned

Set locations

Each location to be planned will be represented by an id and a coordinate.

Moreover, an activity must also be given for each location, since the aim of territory planning is to calculate territories such that they are as balanced as possible. For simple activity measures the class AbsoluteActivity is used, of which the value contains a double value which is simply totalled for each territory during territory planning.

Territories incompatible a location can be set by the incompatibleTerrritoryIds attribute in the element LocationProperties). Non existent territory ids will be ignored.

"locations": [
  {
    "id": "location1",
    "coordinate": {
      "point": {
        "x": 6.166279,
        "y": 49.629301
      }
    },
    "activity": {
      "$type": "AbsoluteActivity",
      "value": 3.0
    },
	"properties": {
      "incompatibleTerrritoryIds": [
         "territory1"
      ]
    }
  }
]

Since the location coordinates are in geodecimal format here, the coordinate format must also be specified in the request, in the CallerContext.

Parametrisation for the calculation of stretches of route

PTV xTerritory server offers several ways to calculate stretches of route:

As the crow flies (ApproximateByDirectDistance)
Distances by road (NewDistanceMatrixByRoad)
Use of previously calculated routes (ExistingDistanceMatrixByRoad and ApproximateByReferenceMatrix)

The respective option will be chosen according to the DistanceCalculationOptions subclass that is instantiated.

Example for NewDistanceMatrixByRoad:

"distanceCalculationOptions": {
  "$type": "NewDistanceMatrixByRoad"
}

Number of territories to be planned

During territory planning, the precise number of territories to be planned must be specified in the PlanningOptions.

"planningOptions": {
  "exactNumberOfTerritories": 2
}

During location assignment, the number of territories is determined by the number of territory centres and must be transferred as a list of territories.

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

Manage response contents

In the request element ResponseContents, two types of result lists can be switched on or off. Generally, a list of territories and their assigned locations will be returned. Instead of (or in addition to) this, the parameter locations lets you switch on a list of locations in the response. The locations in the response are in the same order as in the request and the assigned territory is also shown for every location (Location.territoryId). A list of locations can be used in a follow-up request, for example, to set fixed assignments of individual locations to particular territories (see use case fixed assignments). Both lists do contain redundant information, but this enables clients to choose the list which is most efficient for them.

If a list of territories is not provided in the response, there is no way of finding the reference points of individual territories for the purpose of territory planning.

"responseContents": {
  "territories": false,
  "locations": true
}

Objects in the response

Because territories was set to false and locations was set to true in the ResponseContents element in the request, a list of locations is included in the response instead of a list of territories. Each location still has a unique identifier in the form of its id. Assignments to individual territories are made using the territoryId, which is now set for all locations. The incompatibility of a location to a territory is also displayed the same way in the response as in the request, i.e. via the IncompatibleTerrritoryIds attribute in the properties element.

"locations": [
  {
    "id": "location1",
    "coordinate": {
      "$type": "Point",
      "point": {
        "$type": "PlainPoint",
        "x": 6.166279,
        "y": 49.629301
      }
    },
    "activity": {
      "$type": "AbsoluteActivity",
      "value": 1
    },
    "properties": {
      "incompatibleTerrritoryIds": [
        "territory1"
      ]
    },
    "territoryId": "territory2"
  }
]

If a distance matrix has been calculated or expanded in the request (NewDistanceMatrixByRoad or ExistingDistanceMatrixByRoad) a DistanceMatrixSummary element is included in the response. Among other things, it provides an id for the distance matrix, which can be entered in the ExistingDistanceMatrixByRoad element in any further requests, in order to reuse the distance matrix which had just been calculated.