Developer's Guide > API Documentation > API Documentation PTV xCluster > XCluster

Component xcluster

Diagrams

XCluster

Exceptions

Operations

planClusters

The operation planClusters is the simplest way of planning clusters. Given is an amount of orders. An order contains one visit. The cluster optimization groups these visits into a given number of clusters assigning every visit to exactly one cluster. Thus the clustering performs a partitioning of the visits into disjoint sets of visits.
Parameter Name Type Description
orders ClusterOrder[] The list of cluster orders.
params ClusterParams The cluster parameters controlling the optimization.
Return Type Description
ClusterPlan The list of planned orders assigning the visits to clusters and list of planned clusters accumulating the cluster values.
XClusterException Thrown if an xCluster server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs.

startPlanClusters

This is the asynchronous version of planClusters. Calling this method will not block until the result has been calculated. Instead of a result object a Job object is returned which identifies the started calculation. To get status updates on a running job use the method watchJob and check the attribute status of type JobStatus. If it turns to SUCCEEDED, the calculation was successful and the result can be obtained using fetchClusterPlan. If the job ended with status FAILED, fetchClusterPlan throws the exception that occured during calculation.
Parameter Name Type Description
orders ClusterOrder[] The list of cluster orders.
params ClusterParams The cluster parameters controlling the optimization.
Return Type Description
Job The Job reference.
XClusterException Thrown if an xCluster server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs.

fetchClusterPlan

Fetches results of type ClusterPlan for the given job id. If the calculation ended with an exception fetchClusterPlan will rethrow it. If the id of the job is unknown a SystemException with message 'unknown id' is thrown.
Parameter Name Type Description
id String The id of the job.
Return Type Description
ClusterPlan The list of planned orders assigning the visits to clusters and list of planned clusters accumulating the cluster values.
XClusterException Thrown if an xCluster server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs.

planWeek

The operation planWeek plans the visits for one week. Given is an amount of orders. An order contains one or more visits within that week. Thereby all visits of an order have the same location and follow specified weekday patterns (for example in case of two visits Monday-Wednesday or Tuesday-Friday). The cluster optimization groups these visits into the given weekdays assigning every visit to exactly one weekday.
Parameter Name Type Description
orders WeekOrder[] The list of week orders.
params WeekParams The week parameters controlling the optimization.
Return Type Description
WeekPlan The list of planned orders assigning the visits to weekdays and list of planned clusters accumulating the weekday values.
XClusterException Thrown if an xCluster server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs.

startPlanWeek

This is the asynchronous version of planWeek. Calling this method will not block until the result has been calculated. Instead of a result object a Job object is returned which identifies the started calculation. To get status updates on a running job use the method watchJob and check the attribute status of type JobStatus. If it turns to SUCCEEDED, the calculation was successful and the result can be obtained using fetchWeekPlan. If the job ended with status FAILED, fetchWeekPlan throws the exception that occured during calculation.
Parameter Name Type Description
orders WeekOrder[] The list of week orders.
params WeekParams The week parameters controlling the optimization.
Return Type Description
Job The Job reference.
XClusterException Thrown if an xCluster server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs.

fetchWeekPlan

Fetches results of type WeekPlan for the given job id. If the calculation ended with an exception fetchWeekPlan will rethrow it. If the id of the job is unknown a SystemException with message 'unknown id' is thrown.
Parameter Name Type Description
id String The id of the job.
Return Type Description
WeekPlan The list of planned orders assigning the visits to weekdays and list of planned clusters accumulating the weekday values.
XClusterException Thrown if an xCluster server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs.

planMultiWeeks

The operation planMultiWeeks plans the visits for more than one week. Given is an amount of orders. An order contains one or more visits within that weeks. Thereby all visits of an order have the same location and follow specified week rhythms (for example every week or biweekly) and within a week specified weekday patterns. The cluster optimization groups these visits into the given weeks and weekdays assigning every visit to exactly one day. Every day corresponds to one cluster.
Parameter Name Type Description
orders MultiWeeksOrder[] The list of multi weeks orders.
params MultiWeeksParams The multi weeks parameters controlling the optimization.
Return Type Description
MultiWeeksPlan The list of planned orders assigning the visits to days and list of planned clusters accumulating the day values.
XClusterException Thrown if an xCluster server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs.

startPlanMultiWeeks

This is the asynchronous version of planMultiWeeks. Calling this method will not block until the result has been calculated. Instead of a result object a Job object is returned which identifies the started calculation. To get status updates on a running job use the method watchJob and check the attribute status of type JobStatus. If it turns to SUCCEEDED, the calculation was successful and the result can be obtained using fetchMultiWeeksPlan. If the job ended with status FAILED, fetchMultiWeeksPlan throws the exception that occured during calculation.
Parameter Name Type Description
orders MultiWeeksOrder[] The list of multi weeks orders.
params MultiWeeksParams The multi weeks parameters controlling the optimization.
Return Type Description
Job The Job reference.
XClusterException Thrown if an xCluster server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs.

fetchMultiWeeksPlan

Fetches results of type MultiWeeksPlan for the given job id. If the calculation ended with an exception fetchMultiWeeksPlan will rethrow it. If the id of the job is unknown a SystemException with message 'unknown id' is thrown.
Parameter Name Type Description
id String The id of the job.
Return Type Description
MultiWeeksPlan The list of planned orders assigning the visits to days and list of planned clusters accumulating the day values.
XClusterException Thrown if an xCluster server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs.

getWeekAssignments

The operation getWeekAssignments returns the possible combinations dividing the visits of one order into weekdays and regions. This overview of possible cluster assignments establishes a better understanding for the optimization planWeek. The optimization potential of an order is estimable with the resulting number of possible assignments. Because of some parts are independent from each other, not all combinations are created (for example the regions in different weekdays). Therefore the optimization selects the best option in each part.
Parameter Name Type Description
rules WeekAssignmentRules All necessary information to create the possible cluster assignments of one order.
Return Type Description
WeekAssignment[] The list of possible week order assignments.
XClusterException Thrown if an xCluster server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs.

getMultiWeeksAssignments

The operation getMultiWeeksAssignments returns the possible combinations dividing the visits of one order into weeks and weekdays. This overview of possible cluster assignments establishes a better understanding for the optimization planMultiWeeks. The optimization potential of an order is estimable with the resulting number of possible assignments. Because of some parts are independent from each other, not all combinations are created (for example the weekdays in different weeks in case of no regularity). Therefore the optimization selects the best option in each part.
Parameter Name Type Description
rules MultiWeeksAssignmentRules All necessary information to create the possible cluster assignments of one order.
Return Type Description
MultiWeeksAssignment[] The list of possible multi weeks order assignments.
XClusterException Thrown if an xCluster server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs.

getCalculationProgress

The operation getCalculationProgress returns the progress of the ongoing cluster optimization. If a call of the plan operations takes a longer time, this operation is helpful to estimate the remaining period of the optimization. To clearly identify the corresponding progress, this operation implies only one cluster optimization at the same time.
Parameter Name Type Description
Return Type Description
CalculationProgress The progress of the different steps.
XClusterException Thrown if an xCluster server exception such as an invalid request parameter occurs.
XServiceException Thrown if a PTV xServer framework exception occurs.

watchJob

Returns status information on jobs.
Parameter Name Type Description
id String The id of the job.
watchOptions WatchOptions The options to control job status and progress updates.
Return Type Description
Job The job reference.
SystemException Thrown if job management is not available, for example if it is misconfigured.

stopJob

Attempts to stop a running job. If the status of the job turns to SUCCEEDED, preliminary results can be fetched, if available.
Parameter Name Type Description
id String The id of the job to be stopped.
Return Type Description
Job The job reference.
SystemException Thrown if a preliminary result cannot be provided or job management in general is not available, for example if it is misconfigured.

deleteJob

Attempts to delete a running job. If successful the returned job will have state DELETED.
Parameter Name Type Description
id String The id of the job to be deleteed.
Return Type Description
Job The job reference.
SystemException Thrown if job management is not available, for example if it is misconfigured.

Classes

CalculationProgress

Describes the progress of the ongoing cluster optimization. The progress is divided into different steps. Only the already executed steps and the current step are displayed. The upcoming or irrelevant steps are omitted. In case of no ongoing cluster optimization, the progress of the last executed optimization is showed.
Attribute Name Type Description
active boolean If true, the cluster optimization is in progress.
linkLocationsStep StepProgress The progress of the link locations step (that meanas linking the locations to a digital road map). This step is only executed in case of distance type ROAD. It is not organized in loops.
calcRoutingsStep StepProgress The progress of the calc routings step (that means calculation of a distance matrix between all locations). This step is only executed in case of distance type ROAD. It is not organized in loops.
findRefPointsStep StepProgress The progress of the find reference points step (that means finding the reference points to all locations). This step is only executed in case of distance type REFERENCE. It is not organized in loops.
initialisationStep StepProgress The progress of the initialisation step (that means assigning the visits without an imported cluster assignment to an arbitrary cluster). This step is always executed. It is not organized in loops.
constructionStep StepProgress The progress of the construction step (that means relocating the visits to improve the objective compactness). This step is only executed if the attribute constructionsStep is true. It is organized in loops.
improvementStep StepProgress The progress of the improvement step (for example relocating the visits to improve the objective distribution and not to worsen the objective compactness crucially). This step is only executed if the attribute improvementStep is true. It is organized in loops.
postOptStep StepProgress The progress of the post optimization step (for example swaping two visits from different clusters to improve the objective compactness). This step is only executed if the attribute postOptStep is true and there are relevant orders available. It is organized in loops.

Cluster

Extends ClusterInfo

Extends the class ClusterInfo with cluster attributes.
Attribute Name Type Description
clusterIndex int Index of the cluster to identify the cluster clearly.

ClusterInfo

Describes the basic information object for clusters accumulating visit related values.
Attribute Name Type Description
visitCount int Number of visits without splits.
quantity int Sum of the quantity.
target int Target quantity.
load double Utilised quantity ([%]).

ClusterOrder

Extends Order

Extends the class Order with cluster attributes to plan the visits in clusters. Thereby an order corresponds to one visit.
Attribute Name Type Description
quantity int Quantity of the order for example service period or turnover (>= 0).
clusterIndex Integer Imported cluster assignment of the order (1 <= x <= clusterCount, optional). The clusters are numbered consecutively starting with index 1. Omitting the attribute means no cluster assignment to import.

ClusterParams

Extends Params

Extends the class Params with cluster attributes to plan cluster orders.
Attribute Name Type Description
clusterCount int The number of clusters to plan (1 <= x <= 364).

ClusterPlan

Describes the results of the cluster optimization assigning the visits to clusters.
Attribute Name Type Description
orders OutputClusterOrder[] The list of planned cluster orders. Number and sequence of the orders correspond to the imported list.
clusters Cluster[] The list of planned clusters. The clusters are numbered consecutively starting with index 1. The number of elements correspond to clusterCount.

DayCluster

Extends ClusterInfo

Extends the class ClusterInfo with day attributes.
Attribute Name Type Description
week int Week to identify the cluster in combination with the weekday clearly.
weekday Integer Weekday to identify the cluster in combination with the week clearly (optional). This attribute is only available, if a planning with weekdays is executed.

DimaParams

Describes the way of dealing with distance matrices in case of distance type ROAD or REFERENCE.
Attribute Name Type Description
dimaID Integer Unique key to identify the distance matrix clearly (> 0, optional). Omitting the attribute means that the default value in the default properties file is used.
deleteBeforeUsage Boolean Only ROAD: An existing distance matrix is deleted before the new one is calculated (true) or an existing distance matrix is augmented if unknown locations appear (false, optional). So this attribute controls the reusability of calculated distance matrices as this process is time consuming. Omitting the attribute means that the default value in the default properties file is used.
deleteAfterUsage Boolean Only ROAD: A calculated distance matrix is deleted after the optimization because no further reusability is necessary (true, optional). So this attribute controls the reusability of calculated distance matrices as this process is time consuming. Omitting the attribute means that the default value in the default properties file is used.
optimization Byte Only ROAD: Weight for the routing calculation between distance and time, whereby 0 calculates the shortest and 100 calculates the fastest route (optional). The attribute is not relevant using an existing distance matrix without executing new routings. Omitting the attribute means that the default value in the default properties file is used.
vehicleType VehicleType Only ROAD: Type of the vehicle (optional). Depending on the chosen vehicle type additional constraints for example road blockings are considered in the route calculation. The attribute is not relevant using an existing distance matrix without executing new routings. Omitting the attribute means that the default value in the default properties file is used.
speedProfile String Only ROAD: A string of 16 comma separated values representing the two speed values per network class (optional). The attribute is not relevant using an existing distance matrix without executing new routings. Omitting the attribute means that the default value in the default properties file is used.

DistanceCalculation

Describes the way of dealing with distance calculation. These distances between the visits are the basis to evaluate the compactness of the clusters..
Attribute Name Type Description
dimaCoordFormat DimaCoordFormat Format of all coordinates (optional). Omitting the attribute means that the default value in the default properties file is used.
distanceType DistanceType Type of distance calculation (optional). Omitting the attribute means that the default value in the default properties file is used.
dimaParams DimaParams Distance matrix parameters in case of distance type ROAD or REFERENCE (optional). Omitting the attribute means that the default values in the default properties file are used.

Location

Describes a geografical position. The format of the coordinates is defined by the params.
Attribute Name Type Description
x int x coordinate.
y int y coordinate.

MultiWeeksAssignment

Describes the multi weeks assignment dividing the visits of one order into weeks and weekdays.
Attribute Name Type Description
visits OutputMultiWeeksVisit[] The list of visits of the multi weeks assignment. The number of visits correspond to (((lastWeek - firstWeek) / weekRhythm) + 1) * visitsPerWeek.

MultiWeeksAssignmentRules

Describes all necessary information to create the possible combinations dividing the visits of one order into weeks and weekdays. No day fixing by the attribute weights is considered.
Attribute Name Type Description
weekCount int Number of weeks in the planning period (1 <= x <= 52).
weekdayCount Integer Number of weekdays within one week (2 <= x <= 7, optional). Omitting the attribute means no weekdays to plan.
rules MultiWeeksRules All rules and restrictions to assign every visit of one order to exactly one day.

MultiWeeksOrder

Extends Order

Extends the class Order with multi weeks attributes to plan the visits for more than one week. Thereby an order contains one or more visits within that weeks. Normally every day corresponds to one cluster. Sometimes it is necessary to plan just the weeks and the weekdays are irrelevant. Then every week corresponds to one cluster.
Attribute Name Type Description
assignmentRules MultiWeeksRules All rules and restrictions to assign every visit of the order to exactly one day (required). These specifications must enable at least one valid multi weeks assignment.
visits MultiWeeksVisit[] Description of the visits of the order (required). The number of visits is not stated explicitly, but can be calculated by the following term:
  • (((lastWeek - firstWeek) / weekRhythm) + 1) * visitsPerWeek
visitSplits Integer Number of visits within one day by splitting the visit in parts (>= 2, optional). This is relevant for the calculation of the corresponding quantities (only reasonable in case of service periods). It is not used to create clusters for parts of a day. Omitting the attribute means no splitting.

MultiWeeksParams

Extends Params

Extends the class Params with multi weeks attributes to plan multi weeks orders.
Attribute Name Type Description
weekCount int Number of weeks in the planning period (1 <= x <= 52).
weekdayCount Integer Number of weekdays within one week (2 <= x <= 7, optional). Omitting the attribute means no weekdays to plan.
weights WeekWeight[] Weight per day to control the distribution (optional). The sum of all weights is the basis to calculate the distribution by percentage, for example all days with weight 100 and one day with weight 50 means the half of the quantity for that day compared to the others. The weight 0 indicates a fixed day, for example no visits are changed in or out of this cluster. The number of elements must correspond to weekCount. In case of planning without weekdays, day1 corresponds to a whole week. Omitting the attribute means an equal distribution between the days.
visitSplitsFactor Double The factor to modify the quantities of an visit in case of splitting it in parts (>= 1, optional). As all parts of a visit are always assigned to one cluster, this factor should compensate the increased effort to visit the parts. A factor > 1 considers the additional driving period. So this is only reasonable in case of quantities standing for service periods. Omitting the attribute means no modification of the quantities.
fixWeekdayOfRegulars Boolean

Can be used to switch on (=true) the fixing of the weekday for visits with regularity (optional).

MultiWeeksPlan

Describes the results of the cluster optimization assigning the visits to days.
Attribute Name Type Description
orders OutputMultiWeeksOrder[] The list of planned multi weeks orders. Number and sequence of the orders correspond to the imported list.
clusters DayCluster[] The list of planned clusters. Every day corresponds to one cluster. The days are numbered consecutively starting with weekday 1 in week 1. The number of elements correspond to weekCount * weekdayCount. In case of planning without weekdays every week corresponds to one cluster and the number of elements to weekCount.

MultiWeeksRules

Describes all rules and restrictions to assign every visit of the order to exactly one day.
Attribute Name Type Description
weekRhythm int Week rhythm over the weeks, for example every week with value 1 or biweekly with value 2 (1 <= x <= weekCount).
visitsPerWeek int Number of visits within one week without splits (1 <= x <= weekdayCount). In case of planning without weekdays, there is only one visit possible.
validities WeekValidity[] Valid days within the weeks, for example closed on Monday in week 2 (optional). The number of elements must correspond to weekCount. In case of planning without weekdays, day1 corresponds to a whole week. Omitting the attribute means all days are valid.
weekdayPatterns WeekValidity[] Weekday patterns within every week, for example Monday-Wednesday or Tuesday-Thursday are two examples for weekday patterns of an order with two visits a week (optional). The number of valid days in one pattern must correspond to visitsPerWeek. There are up to 35 weekday patterns per order possible. Omitting the attribute is only possible in case of planning without weekdays.
regularity Integer Regularity of the order (>=0, optional). The visits in every visited week follow the same weekday pattern.For example if the visits are on Monday and Wednesday in the first visited week, than the visits are on Monday and Wednesday in all other visited weeks. There are three cases to differentiate:
  • No regularity: By omitting the attribute the visits in every visited week can be assigned to different weekdays.
  • Strict regularity: With value 0 the visits in every visited week must be assigned to the same weekdays.
  • Flexible regularity: A value >0 describes the number of visited weeks the regularity can deviate from the strict regularity, for example with value 1 the visits in every week are assigned to the same weekdays except one week with different weekdays. There must always be more strict weeks than flexible ones.
firstWeek Integer First valid week visits are possible (1 <= x <= lastWeek, optional). Omitting the attribute means that week 1 is the first valid week.
lastWeek Integer Last valid week visits are possible (firstWeek <= x <= weekCount, optional). Omitting the attribute means that week weekCount is the last valid week.
firstWeekFix boolean If the first visit must be assigned to the first valid week, then this visit must be fixed (true). In the case of no fixing (false), the first visit can be assigned to one of the first valid weekRhythm weeks.
leftShiftWeek int Maximum deviation from the week rhythm to an earlier week, for example the value 2 allows shifting the visited weeks two weeks earlier to use the week rhythm in a more flexible way (>= 0). This is not possible for the first and last visited week. In addition to that no intersections are allowed, the shifted weeks must keep their sequence(for example shifting a visited week to the latest week and shifting the following visited week to the earliest week). This attribute is only used if no valid assigment exists in a week following the week rhythm (for example because of holidays).
rightShiftWeek int Maximum deviation from the week rhythm to a later week, for example the value 2 allows shifting the visited weeks two weeks later to use the week rhythm in a more flexible way (>= 0). This is not possible for the first and last visited week. In addition to that no intersections are allowed, the shifted weeks must keep their sequence (for example shifting a visited week to the latest week and shifting the following visited week to the earliest week). This attribute is only used if no valid assigment exists in a week following the week rhythm (for example because of holidays).

MultiWeeksVisit

Describes one visit of the order.
Attribute Name Type Description
quantity int Quantity of the visit for example service period or turnover (>= 0).
week Integer Imported week of the visit (1 <= x <= weekCount, optional). The weeks are numbered consecutively starting with index 1. Omitting the attribute means no week to import.
weekday Integer Imported weekday of the visit (1 <= x <= weekdayCount, optional). This attribute is only considered, if week is specified and a planning with weekdays is executed. Then it is required. Omitting the attribute means no weekday to import.

Order

Describes the basic planning object for cluster optimization.
Attribute Name Type Description
orderID int Unique key to identify the order clearly (> 0).
loc Location Location or reference point of the order (required).
orderFixed boolean The ability of changing the cluster assignment. Only the not fixed orders (false) can change their cluster assignment during the optimization. If the order is fixed (true), a valid cluster assignment has to be imported.

OutputClusterOrder

Describes the planned cluster order assigning the visits to clusters.
Attribute Name Type Description
orderID int Unique key to identify the related order clearly.
clusterIndex int Cluster assignment of the order after the optimization.

OutputMultiWeeksOrder

Describes the planned multi weeks order assigning the visits to days.
Attribute Name Type Description
orderID int Unique key to identify the related order clearly.
visits OutputMultiWeeksVisit[] The list of planned visits of the multi weeks order. The number of visits correspond to (((lastWeek - firstWeek) / weekRhythm) + 1) * visitsPerWeek.

OutputMultiWeeksVisit

Describes the planned visit of the multi weeks order.
Attribute Name Type Description
week int Week of the visit after the optimization.
weekday Integer Weekday of the week after the optimization (optional). This attribute is only available, if a planning with weekdays is executed.

OutputWeekOrder

Describes the planned week order assigning the visits to weekdays.
Attribute Name Type Description
orderID int Unique key to identify the related order clearly.
visits OutputWeekVisit[] The list of planned visits of the week order. The number of visits correspond to visitsPerWeek.

OutputWeekVisit

Describes the planned visit of the week order.
Attribute Name Type Description
weekday int Weekday of the visit after the optimization.
region Integer Region of the weekday after the optimization (optional). This attribute is only available, if a planning with regions is executed.

Params

Describes the planning parameters controlling the optimization.
Attribute Name Type Description
distanceCalculation DistanceCalculation Distance calculation parameters (optional). Omitting the attribute means that the default values in the default properties file are used.
costDistanceKm Integer Costs for one kilometre to weight the distance and the driving period (>= 0, optional). Omitting the attribute means the default value 100.
costPeriodMinute Integer Costs for one minute to weight the distance and the driving period (>= 0, optional). Omitting the attribute means the default value 100.
constructionStep Boolean Execute (true) or omit (false) the construction step (optional). This step tries to relocate the visits to another cluster to build the clusters as compact as possible. The objective distribution is not considered. This step should be executed in case of starting a new planning. Omitting the attribute means that the construction step is executed.
improvementStep Boolean Execute (true) or omit (false) the improvement step (optional). This step tries to relocate the visits to another cluster to improve the objective distribution and at the same time not to worsen the objective compactness crucially. Omitting the attribute means that the improvement step is executed.
improvementLoops Integer Only improvementStep: Number of loops (>= 0, optional). Omitting the attribute means the default value 100.
improvementCompactnessFactor Integer Only improvementStep: Factor for the compactness to weight the objectives compactness and distribution (>= 0, optional). If the factor is 0, the objective compactness is not considered. If both factors are 0, the optimization uses an automatic approach. Omitting the attribute means the default value 0.
improvementDistributionFactor Integer Only improvementStep: Factor for the distribution to weight the objectives compactness and distribution (>= 0, optional). If the factor is 0, the objective distribution is not considered. If both factors are 0, the optimization uses an automatic approach. Omitting the attribute means the default value 0.
postOptStep Boolean Execute (true) or omit (false) the post optimization step (optional). This step tries to swap two visits from different clusters to improve the objective compactness. As these two visits must have the same quantity, the objective distribution remain unchanged. Only orders containing one visit are considered. Omitting the attribute means that the post optimization step is executed.

StepProgress

Describes one progress step of the ongoing cluster optimization.
Attribute Name Type Description
active boolean If true, the step is in progress.
elapsedTime int The elapsed time within the step ([sec]).
loop int The current loop within the step or 0, if the step is not organized in loops.
progressValue int The current progress value within the loop or within the step if the step is not organized in loops ([‰]).

WeekAssignment

Describes the week assignment dividing the visits of one order into weekdays and regions.
Attribute Name Type Description
visits OutputWeekVisit[] The list of visits of the week assignment. The number of visits correspond to visitsPerWeek.

WeekAssignmentRules

Describes all necessary information to create the possible combinations dividing the visits of one order into weekdays and regions. No weekday fixing by the attribute weights is considered.
Attribute Name Type Description
weekdayCount int Number of weekdays in the planning period (1 <= x <= 7).
regionCount Integer Number of regions per weekday (2 <= x <= 5, optional). Omitting the attribute means no regions to plan.
rules WeekRules All rules and restrictions to assign every visit of one order to exactly one weekday.

WeekOrder

Extends Order

Extends the class Order with week attributes to plan the visits for one week. Thereby an order contains one or more visits within that week. Normally every weekday corresponds to one cluster. Sometimes it is necessary to split the weekdays in more than one cluster (for example in case of more than one resource serving the customers). These so called regions are only relevant for the objective compactness as the objective distribution and the constraints always refer to weekdays.
Attribute Name Type Description
assignmentRules WeekRules All rules and restrictions to assign every visit of the order to exactly one weekday (required). These specifications must enable at least one valid week assignment.
visits WeekVisit[] Description of the visits of the order (required). The number of visits must correspond to visitsPerWeek.
visitSplits Integer Number of visits within one weekday by splitting the visit in parts (>= 2, optional). This is relevant for the calculation of the corresponding quantities (only reasonable in case of service periods). It is not used to create clusters for parts of a weekday. Omitting the attribute means no splitting.

WeekParams

Extends Params

Extends the class Params with week attributes to plan week orders.
Attribute Name Type Description
weekdayCount int Number of weekdays in the planning period (1 <= x <= 7).
regionCount Integer Number of regions per weekday (2 <= x <= 5, optional). Omitting the attribute means no regions to plan.
weights WeekWeight Weight per weekday to control the distribution (optional). The sum of all weights is the basis to calculate the distribution by percentage, for example all weekdays with weight 100 and one weekday with weight 50 means the half of the quantity for that weekday compared to the others. The weight 0 indicates a fixed weekday, for example no visits are changed in or out of this cluster. Omitting the attribute means an equal distribution between the weekdays.
visitSplitsFactor Double The factor to modify the quantities of an visit in case of splitting it into parts (>= 1, optional). As all parts of a visit are always assigned to one cluster, this factor should compensate the increased effort to visit the parts. A factor > 1 considers the additional driving period. So this is only reasonable in case of quantities standing for service periods. Omitting the attribute means no modification of the quantities.

WeekPlan

Describes the results of the cluster optimization assigning the visits to weekdays.
Attribute Name Type Description
orders OutputWeekOrder[] The list of planned week orders. Number and sequence of the orders correspond to the imported list.
clusters WeekdayCluster[] The list of planned clusters. Every weekday corresponds to one cluster. The weekdays are numbered consecutively starting with weekday 1. The number of elements correspond to weekdayCount.

WeekRules

Describes all rules and restrictions to assign every visit of the order to exactly one weekday.
Attribute Name Type Description
visitsPerWeek int Number of visits within the week without splits (1 <= x <= weekdayCount).
validities WeekValidity Valid weekdays within the week, for example closed on Mondays (optional). Omitting the attribute means all weekdays are valid.
weekdayPatterns WeekValidity[] Weekday patterns within the week, for example Monday-Wednesday or Tuesday-Thursday are two examples for weekday patterns of a two visit order (required). The number of valid days in one pattern must correspond to visitsPerWeek. There are up to 35 weekday patterns per order possible.

WeekValidity

Describes the valid weekdays within a week, for example Monday could correspond to day1. Only the first weekdayCount days are considered.
Attribute Name Type Description
day1 boolean Day 1 is valid (true) or invalid (false).
day2 boolean Day 2 is valid (true) or invalid (false).
day3 boolean Day 3 is valid (true) or invalid (false).
day4 boolean Day 4 is valid (true) or invalid (false).
day5 boolean Day 5 is valid (true) or invalid (false).
day6 boolean Day 6 is valid (true) or invalid (false).
day7 boolean Day 7 is valid (true) or invalid (false).

WeekVisit

Describes one visit of the order.
Attribute Name Type Description
quantity int Quantity of the visit for example service period or turnover (>= 0).
weekday Integer Imported weekday of the visit (1 <= x <= weekdayCount, optional). The weekdays are numbered consecutively starting with index 1. Omitting the attribute means no weekday to import.
region Integer Imported region of the visit (1 <= x <= regionCount, optional). This attribute is only considered, if weekday is specified and a planning with regions is executed. Then it is required. Omitting the attribute means no region to import.

WeekWeight

Describes the weights per weekday to control the distribution. Only the first weekdayCount weights are considered.
Attribute Name Type Description
day1 int The weight of day 1 (>= 0).
day2 int The weight of day 2 (>= 0).
day3 int The weight of day 3 (>= 0).
day4 int The weight of day 4 (>= 0).
day5 int The weight of day 5 (>= 0).
day6 int The weight of day 6 (>= 0).
day7 int The weight of day 7 (>= 0).

WeekdayCluster

Extends ClusterInfo

Extends the class ClusterInfo with weekday attributes.
Attribute Name Type Description
weekday int Weekday to identify the cluster clearly.

Enumerations

DimaCoordFormat

Enumerates the format of all coordinates.
Enumerator Name Value Description
MERCATOR 0 Mercator format.
GEODECIMAL 1 Geo-Decimal format.
SUPERCONFORM 2 Super-Conform format.
GEOMINSEC 3 Geo-Min-Sec format.
GAUSSKRUEGER 4 Gauss-Krueger format.
UTM 5 UTM format.
CONFORM 6 Conform format.
SMARTUNITS 7 SMART-Units format.

DistanceType

Enumerates the type of distance calculation.
Enumerator Name Value Description
GEOMETRIC 0 Geometric distances for example all distances as the crow flies. This type requires no distance matrix.
ROAD 1 Road distances for example all distances based on digital road maps. This type requires the calculation of a distance matrix between all locations right before the cluster optimization.
REFERENCE 2 Reference point method for example all distances approximated via reference points. This type requires a pre-calculated distance matrix.

ErrorCode

Enumerates the error code.
Enumerator Name Value Description
LICENSE_ERROR 10000 The license is not valid or expired.
PROFILESETTINGS_ERROR 10001 Invalid profile settings.
MODULE_ERROR 10002 General error code of the module.
ENGINE_ERROR 10003 General error code of the engines.
REQUIREDPARAMETER_ERROR 10004 Missing a required input parameter.
INVALIDPARAMETER_ERROR 10005 Invalid input parameter.

VehicleType

Enumerates the type of the vehicle.
Enumerator Name Value Description
TRUCK 0 Truck.
CAR 1 Car.

Exceptions

XClusterException

Exception thrown on module specific problems such as wrong parameters or engine errors.

Component common

Diagrams

basetypes

opengis-geometry

Exceptions

Asynchronous Requests

Classes

BoundingBox

A bounding box, definded by its left top corner point and right bottom corner point.
Attribute Name Type Description
leftTop Point

The left top corner point.
rightBottom Point

The right bottom corner point.

BulkProgress

Extends JobProgress

Default implementation for bulk jobs.
Attribute Name Type Description
remaining int

Specifies how many requests have still to be calculated.
successful int

The number of successful calculations so far.
failed int

The number of failed computations so far.

ClusterProgress

Extends JobProgress

Implementation of JobProgress for cluster planning.
Attribute Name Type Description
action String

The current action being executed. For more information on progress see About Asynchronous Protocol.
distanceMatrixProgress DistanceMatrixProgress

The progress of the distance matrix calculation, available only if action equals "DistanceMatrix.Calculation".
optimizationProgress OptimizationProgress

The progress of the optimization, available only if action starts with "Optimization.".

DistanceMatrixCalculationProgress

Progress information of the currently active distance matrix calculation
Attribute Name Type Description
dimaId int

The unique key to identify the distance matrix currently being calculated.
currentDimaIndex int

The 1-based index of the distance matrix currently being calculated. Depending on the number of different vehicles in the request the number of distance matrices to be calculated can be greater than
lastDimaIndex int

The index of the last distance matrix to be calculated, that is the total number of distance matrices.
currentDistanceMatrixProgress DistanceMatrixProgress

The progress of the distance matrix currently being processed, available only if action equals "DistanceMatrix.Calculation".

DistanceMatrixProgress

Extends JobProgress

Default implementation for distance matrix calculation jobs.
Attribute Name Type Description
currentRowIndex int

The 1-based index of the current row of the current distance matrix being calculated.
lastRowIndex int

The index of the last row of the current distance matrix to be calculated.

EncodedGeometry

Extends EncodedGeometryBase

The abstract base class for geometry objects used in a geographical PTV xServer. Contains the attributes to represent openGIS conform encodings with a specific coordinate format. The actual representation is defined by the CallerContext ResponseGeometry property (GeometryEncoding) and the CallerContext CoordFormat property (CoordFormat).

Attribute Name Type Description
wkb byte[]

If not null, this attribute contains the well-known binary encoded form of the geometry
wkt String

If not null, this attribute contains the well-known text encoded form of the geometry
kml KML

If not null, this attribute contains the well-known text encoded form of the geometry

EncodedGeometryBase

The abstract base class for geometry objects.
No attributes defined.

GeometryCollection

Extends EncodedGeometry

A geometry collection as specified by the openGIS standard.
Attribute Name Type Description
geometryCollection PlainGeometryCollection

If not null, this attribute contains the explicit form of the geometry

ImprovementProgress

Progress information of the currently active improvement step of the optimization.
Attribute Name Type Description
availableMachineTime int

The available machine time stated in the request in [s]. This value is 0 if available machine time is not set in the request.
usedMachineTime int

The machine time already used in [s].
iterationIndex int

The index of this iteration. Index 0 denotes the initial plan directly after construction or the input plan.
numberOfImprovements int

The number of improvements the algorithm has already achieved. In other words, this is the number of tour plans with a smaller value of costOfObjectiveFunction than the best one at that time.
currentPlan KeyFigures

The key figures characterizing the current tour plan.
bestPlan KeyFigures

The key figures characterizing the currently best tour plan.
initialPlan KeyFigures

The key figures characterizing the initial tour plan. The initial tour plan is the input plan, if available, or the first tour plan after the construction step.

Job

Reference to jobs running in the background.
Attribute Name Type Description
id String

This id references the background job on the server.
status JobStatus

The current status of the job.
progress JobProgress

The current progress of the job. Can be null at the very beginning or very end of the request execution.
elapsedTime int

Elapsed time since this job has been queued.

JobProgress

Abstract base class for progresses. An individual PTV xServer might define its own implementations.
No attributes defined.

KML

Represents a KML geometry.
Attribute Name Type Description
kml String

The KML string itself.
placemarks String[]

The placemarks of the KML. If empty, all placemarks will be used. This will result in a GeometryCollection, if more than one exists.

KeyFigures

These key figures characterize a tour plan.
Attribute Name Type Description
costOfObjectiveFunction int

The optimization aims at minimizing the objective function. This value contains its arithmetical cost.

The significance of this value is not the value itself, but rather if and how fast it decreases during the calculation. The faster the value decreases the better the tour plans become according to the GoalImportance which defines what "better" means, at all.
numberOfScheduledOrders int

The number of orders already being scheduled.
numberOfUnscheduledOrders int

The number of orders not being scheduled, yet. These orders are feasible and can be scheduled during further improvement iterations.
numberOfInfeasibleOrders int

The number of orders not being scheduled. These orders are infeasible and will not be scheduled during further improvement iterations.
numberOfScheduledVehicles int

The number of vehicles being scheduled.
totalTourCount int

The number of all planned tours.
totalTourPeriod int

The sum of the tour periods for all planned tours ([sec]).
totalTourDrivingPeriod int

The sum of the tour driving periods for all planned tours ([sec]).
totalTourWaitingPeriod int

The sum of the tour waiting periods for all planned tours ([sec]).
totalTourDistance int

The sum of the tour distances for all planned tours ([m]).
totalTourCost int

The sum of the tour costs for all planned tours ([MU]). The costs per chain will not be included, see attribute totalChainCosts.
totalChainCost int

The sum of the costs per chain of all planned chains ([MU]). See VehicleCosts.
totalChainPeriod int

The sum of the chain periods of all planned chains ([sec]). The chain period is defined as the period between the start of the first tour and the end of the last tour. This period is greater than the sum of the periods of all tours if two subsequent tours do not start right after the other.

LineString

Extends EncodedGeometry

A line string as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
lineString PlainLineString

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

LinearRing

Extends EncodedGeometry

A linear ring as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
linearRing PlainLinearRing

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

MultiLineString

Extends EncodedGeometry

A multi line string as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
multiLineString PlainMultiLineString

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

MultiPoint

Extends EncodedGeometry

A multi point as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
multiPoint PlainMultiPoint

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

MultiPolygon

Extends EncodedGeometry

A multi polygon as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
multiPolygon PlainMultiPolygon

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

OptimizationProgress

The progress information of the currently active step of the optimization.
Attribute Name Type Description
currentLoopIndex int

The index of the current loop being calculated.
lastLoopIndex int

The index of the last loop being calculated. The calculation will automatically be finished by the algorithm before reaching this index when no improvement could be reached, anymore. The total number of loops can be set for the improvement step, only (see Params).
progress int

The progress in % of the current loop being calculated.

PlainGeometryBase

The abstract base class for the structured representation of geometry objects.
No attributes defined.

PlainGeometryCollection

Extends PlainGeometryBase

A plain structured polygon consisting of a set geometries.
Attribute Name Type Description
geometries PlainGeometryBase[]

The set of geometries making up the geometry collection.

PlainLineString

Extends PlainGeometryBase

A plain structured line string consisting of a set of points.

Attribute Name Type Description
points PlainPoint[]

The set of points defining the line string.

PlainLinearRing

Extends PlainGeometryBase

A plain structured linear ring consisting of a set of points

Attribute Name Type Description
points PlainPoint[]

The set of points defining the linear ring.

PlainMultiLineString

Extends PlainGeometryBase

A plain structured polygon consisting of a set of line strings.
Attribute Name Type Description
lineStrings PlainLineString[]

The set of line strings making up the multi line string.

PlainMultiPoint

Extends PlainGeometryBase

A plain structured polygon consisting of a set of points.
Attribute Name Type Description
points PlainPoint[]

The set of points making up the multi point.

PlainMultiPolygon

Extends PlainGeometryBase

A plain structured polygon consisting of a set of polygons.
Attribute Name Type Description
polygons PlainPolygon[]

The set of polygons making up the multi polygon.

PlainPoint

Extends PlainGeometryBase

A plain structured point consisting of two floating point attributes for the coordinates. In contrast to Point it is never transformed.

Attribute Name Type Description
x double

The x coordinate
y double

The y coordinate
z Double

The z coordinate (optional, only if requested)

PlainPolygon

Extends PlainGeometryBase

A plain structured polygon consisting of a set of linear rings.

Attribute Name Type Description
linearRings PlainLinearRing[]

The set of linear rings making up the polygon.

PlanProgress

Extends JobProgress

Implementation of JobProgress for tour planning.
Attribute Name Type Description
action String

The current action being executed. For more information on progress information see About Asynchronous Protocol.
distanceMatrixCalculationProgress DistanceMatrixCalculationProgress

The progress of the distance matrix calculation, available only if action starts with "DistanceMatrix.".
improvementProgress ImprovementProgress

The progress of the improvement step during the tour plan optimization, available only if action equals "Optimization.Improvement".

Point

Extends EncodedGeometry

Represents a single coordinate (point). Do not use this type for other points (e.g. pixel in an image), the coordinates are automatically transformed. Instead use PlainPoint.

See EncodedGeometry for possible representations.

Attribute Name Type Description
point PlainPoint

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

Polygon

Extends EncodedGeometry

A polygon as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
polygon PlainPolygon

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

RequestOptions

General options for requests

Attribute Name Type Description
coordFormat CoordFormat

The coordinate format used in the request/response.
responseGeometry GeometryEncoding[]

The geometry encoding for the response.
profile String

The name of the parameter profile to be used.
profileXMLSnippet String

For internal use only.
srId String

If the coordFormat equals to 'OG_SRID', this attribute contains the Spatial Reference Identifier as specified by the Open Geospatial Consortium (OGC), otherwise it is null. All codes of the EPSG Geodetic Parameter Dataset V7.9 maintained by the EPSG.

TerritoryProgress

Extends JobProgress

Implementation of JobProgress for territory planning.

Attribute Name Type Description
action String

The current action being executed. For more information on progress with territory planning see the use case documentation.
distanceMatrixProgress DistanceMatrixProgress

The progress of the distance matrix calculation, available only if action equals "DistanceMatrix.Calculation".
optimizationProgress int

The progress of the optimization, available only if action starts with "TerritoryOptimization.".

WatchOptions

This class includes options to control job status and progress updates. All parameters are optional.
Attribute Name Type Description
progressUpdatePeriod Integer

If defined this optional parameter enables additional progress updates with the specified interval. If no new progress update arrives during the specified period, watchJob will wait for and return with the next available progress update. Important updates such as terminal states will always return immediately. The minimum period must be at least 250ms. If no progress waiting period is defined, progress will only be sent as part of status updates.
maximumPollingPeriod Integer

Specifies the timeout after which watchJob will report the last status even if no further updates are available.If not specified a configured default is used.

ZoneLoadingProgress

Extends JobProgress

Attribute Name Type Description
action String

The current action being executed.
optimizationProgress int

The progress of the optimization, available only if action starts with "LoadingSpaceOptimization.".

Enumerations

CoordFormat

The CoordFormat enumeration contains all coordinate types supported by the PTV xServer. All examples represent the same geographic location.

Enumerator Name Value Description
OG_GEODECIMAL None

OpenGIS representation of WGS 84 coordinates. Example x=8.2505556, y=48.7627778.
PTV_MERCATOR None Mercator projection. Example x=917420, y=6227729.
PTV_GEOMINSEC None

PTV representation of coordinates by degree, minute, and second. Example x=815020, y=4845460.
PTV_GEODECIMAL None

PTV representation of WGS 84 coordinates. Example x=825056, y=4876278.
PTV_CONFORM None

PTV representation of conform coordinates. Example x=1672358, y=1620743.
PTV_SUPERCONFORM None

PTV representation of super-conform coordinates. Example x=5072358, y=3320743.
PTV_SMARTUNITS None

PTV internal coordinate format. Example x=4352286, y=5456405.
OG_SRID None

This format is set implicitly, if a Spatial Reference Identifier as specified by the Open Geospatial Consortium (OGC) is set in the CallerContext. All codes of the EPSG Geodetic Parameter Dataset V7.9 maintained by the EPSG..
Note: The coordinate format 'OG_GEODECIMAL' and the SRID code 'EPSG:4326' are equivalent.

ErrorCode

Enumerator Name Value Description
REQUEST_INVALID_WKT 10

The specified WKT in the request is invalid. It should a well-known text representation of a geometry from a string (see the OpenGIS simple features specification).
REQUEST_INVALID_WKB 11

The specified WKB in the request is invalid. It should be a geometry from a byte stream in well-known binary format.
REQUEST_INVALID_KML 12

The specified KML in the request is invalid.
KML_PLACEMARK_NOT_FOUND 13

Thrown, if requested placemark name is not found in the KML
CONVERT_GEOMETRY_OBJECT 20

One or more geometry objects in the request are invalid. There are problems to convert a geometry object to a plain geometry object. Also used for retrieving the plain geometry object from a geometry object.
CONVERT_COORDINATE_FORMAT 21

There are problems to convert a CoordFormat of the request to a coordinate type.
GEOMETRY_ENCODING 22

Geometry objects cannot be encoded.

GeometryEncoding

Defines encoding options for geometry parameters and results.

Plain indicates that geometry objects should be transmitted in plain object form, WKB indicates that openGIS well-known binary format should be used, WKT represents the openGIS well-known text format. KML represents the Keyhole Markup Language.

Enumerator Name Value Description
PLAIN None

Plain geometry encoding using structured objects and according network presentation.
WKB None

Geometry should be represented by well-known binaries.
WKT None

Use well-known texts to encode geometry objects.
KML None

Use Keyhole Markup Language to encode geometry objects.

JobStatus

Specifies different job status values.
Enumerator Name Value Description
QUEUING None

Job has been enqueued.
RUNNING None

Job is currently running.
STOPPING None

Stop has been requested, the job will terminate its calculation as soon as possible.
SUCCEEDED None

Job has completed successfully.
FAILED None

Job has failed with an exception.
DELETED None

The job was deleted by the user.
UNKNOWN None

The job is in an unknown state. For example a given id is unknown or the job has already been fetched and has thus been deleted from the underlying persistent store.

Exceptions

XServiceException

XServiceException is used for all exceptions which can occur in the PTV xServer framework.

SystemException (from package com.ptvag.jabba.core.exception)

This is the base class for all system relevant exceptions. It is thrown for example if a request has timed out or if a request has been rejected.

 

 

Copyright © 2024 PTV Logistics GmbH All rights reserved. | Imprint