Use Cases > PTV xTour > Additional Use Cases

Additional Use Cases

How to Use Different Vehicle Profiles for Distance Calculation

The PTV xTour Server can be parameterised to use several vehicle profiles that reflect different types of vehicles within your fleet. Within the CallerContext you may set a main profile which also defines a common distance matrix profile with the property

distanceCalculation.profile

This setting is overwritten by DistanceMatrixByRoad elements which can be added to the attribute distanceMatrixCalculation of the PlanningParams. The attribute profileName of DistanceMatrixByRoad references a distance matrix profile, which must be located in the conf/profiles directory of the PTV xTour Server.

The profile files have the extension xml, but they are referenced without this extension. The PTV xTour Server is shipped with several different dima*.xml files. Please have a look at them in the conf/profiles folder. These can be used to create customised profiles to reflect the vehicle types you are using. The attribute dimaId of a DistanceMatrixByRoad element must contain a unique numeric key. Setting this unique key to the attribute dimaId of a Vehicle element determines the distance matrix calculation profile for this vehicle.

How to Use PTV_TruckAttributes for Road Distance Calculation

The PTV xTour road distance calculation supports the manipulation of road attributes and restrictions by RoadEditor layers. In order to consider the RoadEditor attributes you have to set up the following configuration:

RoadEditor Base Path: The location of the RoadEditor attributes data defaults to <maps.path>/re. If your path differs from the default location, you can specify it in xtour.properties:
```
roadEditorParameter.binPath=./data/map/re
```
RoadEditor Layer Name: Set the name of the RoadEditor layer in your profile (e.g. xtour-default.properties):
```
roadEditorParameter.layerName = truckattributes
```

Configure the vehicle restrictions (e.g. dimaTruck.ini):

[RoadEditorProperties]
Segment.IsUrbanArea.Enabled = true
Segment.BlocksCar.Enabled = true
Segment.BlocksTruck.Enabled = true
Segment.HasTollCar.Enabled = true
Segment.HasTollTruck.Enabled = true
Segment.MaxHeight.Enabled = true
Segment.MaxHeight.MaxLevelDir1 = 300
Segment.MaxHeight.MaxLevelDir2 = 300
Segment.MaxWeight.Enabled = true
Segment.MaxWeight.MaxLevelDir1 = 20000
Segment.MaxWeight.MaxLevelDir2 = 20000
Segment.MaxWidth.Enabled = true
Segment.MaxWidth.MaxLevelDir1 = 200
Segment.MaxWidth.MaxLevelDir2 = 200
Segment.MaxLength.Enabled = true
Segment.MaxLength.MaxLevelDir1 = 800
Segment.MaxLength.MaxLevelDir2 = 800

How to Use Driver Regulations According to the European Union

To use driver regulations according to the EU one must set up an instance of the class DriverRegulations, specify a set of initial values and add the instance to the array of BaseRegulations in PlanningParams.

For EU regulations set the values as follows:

id: The individual id of this regulations object. Must use values greater than 0. Use this id in DriverSettings to point to this regulations object.
beginningOfCalendarWeek: Specifies the time in seconds to mark Monday 00:00 o’clock. This value is important because some of the rest rules rely on calendar weeks. We strongly recommend to use Unix time (number of seconds that have elapsed since midnight Coordinated Universal Time, 1 January 1970) for all time values within xTour. Hence, this value should be set to Monday the 5th January 1970 (=345600) and then use absolute time values for all operating and opening intervals.
breakRule: Sets the periods for breaks that are required after a certain period of driving. After a driving period a driver shall take an uninterrupted break. This break can be replaced by two separate uninterrupted breaks (=> breakPeriod1 and breakPeriod2). The rule assumes that the period of the single breaks equals the sum of both split breaks. According to EU regulation the values should be set as follows:
- drivingPeriod: 4h 30min (16200s)
- breakPeriod1: 15min (900s)
- breakPeriod2: 30min (1800s)
dailyRestRule: Periods and frequencies needed to obey the daily rest rules of the EU. A driver has to take a regular rest after a regular driving period. Within a calendar week he may have 2 extended driving periods of 10h and a maximum of 3 reduced rest periods of 9h. Rests can be split into two separate parts. For EU regulations set the values as follows:
- regularRestPeriod: 11h (39600s)
- firstSplitRestPeriod: 3h (10800s)
- secondSplitRestPeriod: 9h (32400s)
- reducedRestPeriod: 9h (32400s)
- numberOfReducedRestPeriods: 3
- regularDrivingPeriod: 9h (32400s)
- extendedDrivingPeriod: 10h (36000s)
- numberOfExtendedDrivingPeriods: 2
- maximumPeriodBetweenEndOfDailyRests: 24h (86400s)
weeklyRestRule: Periods and frequencies needed to obey the weekly rest rules of the European Union.
- maximumPeriodBetweenWeeklyRests: 6d (518400s)
- maximumWeeklyDrivingPeriod: 56h (201600s)
- maximumBiweeklyDrivingPeriod: 90h (324000s)
- weeklyRestPeriod: 45h (162000s)

The last attribute of DriverRegulations is called breakIntervals. This class holds a period and a list of intervals. If these values are set xTour will try to insert a break with length period within each of the specified intervals. In doubt set this value to null. It is not part of the EU regulations.

The last step to integrate the regulations is to specify an instance of DriverSettings on a Vehicle. DriverSettings must be set up as follows:

regulationsId: Points to the regulations to be used. Set this value to the id of the DriverRegulations.
breakRuleActive: True if the break rule is active.
dailyRestRuleActive: True if the daily rest rule is active.
weeklyRestRuleActive: True if the weekly rest rule is active.
workingRuleActive: True if rule for working hours is active.
remainingPeriods: Encoded remaining periods of a driver's former trips.

How to Apply XML Profiles

On applying XML profiles these parts of information can be useful:

The general mechanism of applying XML profiles is described here.
All supported elements of the xRoute profile are documented here (sub chapter).

How to Watch the Progress of Jobs

Please find more general information on jobs (Asynchronous Protocol).

The service methods planBasicTours and planOvernightTours have corresponding start-methods startPlanBasicTours and startPlanOvernightTours to start the calculation as a job. As both methods return a Plan, the corresponding fetch-method is fetchPlan.

During the calculation the current calculation progress can be watched using watchJob. This method returns an instance of PlanProgress which contains information on which action is currently being executed. The action attribute contains one of the following values.

Action	Description
Import	The request data is being imported.
DistanceMatrix.Preparation	The distance matrix calculation for the current vehicle is being prepared which comprises amongst others loading a high-performance routing network and linking the co-ordinates to the routing network.
DistanceMatrix.Calculation	The distance matrix for the current vehicle is being calculated. For this action the calculation progress will be returned in PlanProgress. The final progress information will be preserved for the next steps to denote that distance matrix calculation has been finished.
Optimization.Construction	If no input plan is present, the initial tour plan is being constructed.
Optimization.Sequencing	The sequence of the tour points within all tours of the current plan is being optimised.
Optimization.TourReduction	It is being checked whether the total number of tours can be reduced by moving all tour points from one tour to other existing tours.
Optimization.Improvement	The improvement step of the optimization is being executed. This is probably the most time-consuming action which iteratively improves the plan by moving tour points from one tour to another. For this action the key figures of the current, best, and inital plan will be returned in PlanProgress which can also help the caller to decide when the current plan is good enough and then to stop a long running calculation. The final progress information will be preserved for the next steps to denote that optimization has been finished.
Optimization.VehicleScheduling	It is being checked whether the tour plan can be improved by exchanging the vehicles executing the tours.
Export	The resulting tour plan is exported to the response.
UnscheduledOrderAnalysis	If requested, orders which have not been scheduled are being analysed.
CleanUp	The request clean-up is being executed, that is deleting temporary data and distance matrices, if requested.

The order of the action values is shown in the table above. Both DistanceMatrix actions may occur in a loop when there is more than one distance matrix to be calculated. Furthermore, the exact order of Sequencing, TourReduction, Improvement, and VehicleScheduling is not fixed and depends on the input.

When stopping the currently running job using stop_Job the best plan available at that point of time will be returned by fetchPlan. The stop action may take some time in order to create this plan which will always be valid but may be incomplete containing unscheduled orders. The analysis of unscheduled orders will also be skipped then.

An exception will be thrown if no intermediate result is available, for example when stopping the request during distance matrix calculation.

How to Configure the Directory of the Distance Matrices

By default the distance matrices will be stored in the sub folder data/dima until deleted by request. If need be, this folder can be changed in the file DimaCtrl.ini which can be found in the conf folder.

[Dima]
Root=data/dima

Under some circumstances such as a cloud installation it may be necessary to enter a path which is not located on the local machine but somewhere else on the network. This should be done with care as when multiple PTV xServer access the same distance matrix folder, access violations might occur. For example when one PTV xServer calculates a distance matrix and another one on a different machine wants to access it. Therefore, sub folders are locked during access, using the file system. Unfortunately, not all file systems, especially those for network shares, do support this locking mechanism. Windows or Linux (NFS) shares will be supported when all accessing PTV xServer are installed on the same operating system. Samba shares will not be supported.

If in doubt, check this by calculating a distance matrix on one machine and by deleting it from another machine at the same time. If deleting fails with an access violation which says that the distance matrix is locked, everything should be fine.

How to Use Tenant Namespaces for Distance Matrix IDs

Ids of distance matrices have to be unique in the scope of the PTV xTour Server: different users cannot use the same dima id in their requests and re-use their previously calculated distance matrices (DistanceMatrixByReference and DistanceMatrixByRoad). To avoid such id conflicts, the id scope can be made user-specific by setting a tenant name for each user. The tenant name can be provided in two ways:

In the header field 'x-tenant' of the PTV xServer request.
In the CallerContext property 'TenantId'.

The header field is meant to be set in a middleware that is responsible for user management, e.g. for PTV xTour Server as a private cloud service. If tenant names are used solely to provide user namespaces, you can use the CallerContext property instead. Both mechanisms can even be combined.

The tenant name is case insensitive and will be prepended to the numerical dima id requested by the user. Alpha-numerical dima ids will only be used internally for folder names of stored distance matrices. In exception messages or progress information, the numerical dima id is used.