Solution Response

Overview

The solution response is the granular feedback provided by the scheduling engine for a given solve request. This is considered the primary output from the engine. The solution response contains all the dimensional evaluation information for each vehicle, i.e. travel durations and distances between locations as well as the instantaneous dimensional information (such as vehicle capacity) at each task performed in the schedule.

Applicable models

IVR7 ivr7-kt461v8eoaif
IVR8 ivr8-yni1c9k2swof

Endpoint

GET: https://api.icepack.ai/vehicle-router/solve/{requestid}

Solution Response

The solution response contains three core elements. The first is the objective cost of the schedule which is the total cost as evaluated by the engine given the input model parameters (such as the cost coefficient parameters on the vehicle class). The second is a list of routes which are the detailed activities for each vehicle. The routes list will correspond in length to the number of input vehicles. An “empty” route will consist of two tasks, namely the shift start and shift end for a vehicle. Finally, any infeasibilities detected in the model are provided in the last list of the solution response.

Schema definition

message SolutionResponse {
  required float objective = 1;
  repeated Route routes = 2;
  repeated Infeasibility infeasibilities = 3;
}

Fields

objective: The total cost of the solution response provided. The sum of all marginal cost terms (across all routes) and fixed cost terms (for vehicles used) will correspond to this objective cost.
routes: A list of routes detailing the movements and task allocations for each vehicle. The routes list will correspond in length to the vehicles provided. Routes with no tasks or jobs allocated to them have only two tasks assigned, namely the shift start and shift end task for that vehicle.
infeasibilities: It is typically desireable to schedule as many orders as possible for a given model. In certain instances, jobs may be infeasible in the context of either scheduling parameters provided, or other jobs in a particular model definition. In instances where jobs are not performed by any vehicle, the engine will evaluate such jobs once the search is complete and provide reasons for the infeasibility of unperformed jobs.

Route

The route provides the scheduled activities and evaluation values for a particular vehicle in a solution response.

Schema definition

message Route {
  required string vehicleId = 1;
  repeated Stop stops = 2;
  repeated InterStop interStops = 3;
  repeated float fixedCost = 4;
  repeated TransitRuleAttribute transitRuleAttributes = 5;
}

Fields

vehicleId: The vehicle identifier, corresponding to the identifier of each vehicle provided in the input model.
stops: The collection of stop objects describing the standing activities of a vehicle.
interStops: The collection of interstop objects describing the movements of a vehicle between locations (i.e. transit).
fixedCost: The fixed cost applied to the vehicle if it was used.
transitRuleAttributes: A collection of transit rule attributes that were applied to this particular route.

Stop

The Stop describes a point in the route of a vehicle where a task is performed. Stops are given their own unique identifier in the output and are referenced by the interstops.

Schema definition

message Stop {
  required int32 id = 1;
  required int32 sequence = 2;
  required string locationId = 3;
  required string taskId = 4;
  required string jobId = 5;
  repeated NodeAttribute attributes = 6;
  optional string compartmentId = 7;     // IVR 8 only.
}

Fields

id: The unique stop identifier. The stop identifier provided as output is a numeric sequence starting at zero.
sequence: The sequence of the stop within the current route. The sequence is zero-based and increasing by a single unit for each task completed.
locationId: The unique identifier of the location at which this stop occurs.
taskId: The unique task identifier which the vehicle is performing at this stop.
jobId: The unique job identifier which the vehicle is performing at this stop.
attributes: A list of node attributes for each dimension in the model.
compartmentId: A compartment assignment for the task being performed at this stop. Omitted for vehicle shift tasks or if no compartments are configured.

Examples

This example shows the full detail for a single stop in a schedule. The stop is the 12th stop in the sequence (11 + 1) and is at the “Brogans” bar. This particular task is a dropoff task and this can be seen by the decrease in the cpaaicty attributes from 600 to 400 on performing the task (i.e. 200 units of capacity were dropped off at Brogans). The distance dimension did not change while performing the task (which is sensible as the vehicle did not move) and the time increased by 20 minutes at a cost of 0.199 monetary units. No slack or tardiness values were incurred in any of the dimensions.

id: 53
sequence: 11
locationId: "Brogans"
taskId: "dropoff_Brogans"
jobId: "job_Brogans"
attributes {
  dimId: "time"
  startValue: 560.993
  endValue: 580.993
  cost: 0.199
  slackValue: 0
  slackCost: 0
  tardyValue: 0
  tardyCost: 0
}
attributes {
  dimId: "distance"
  startValue: 2.374
  endValue: 2.374
  cost: 0
  slackValue: 0
  slackCost: 0
  tardyValue: 0
  tardyCost: 0
}
attributes {
  dimId: "capacity"
  startValue: 600
  endValue: 400
  cost: 0
  slackValue: 0
  slackCost: 0
  tardyValue: 0
  tardyCost: 0
}

Stop Attribute

The Stop attribute describes the dimensional properties at the start of performing a particular task and at the end of the same task. The difference between the end and start values for a node attribute will provide the marginal contribution of the node attribute to the cumulative dimension value.

Schema definition

message StopAttribute {
  required string dimId = 1;
  required float startValue = 2;
  required float endValue = 3;
  required float cost = 4;
  required float slackValue = 5;
  required float slackCost = 6;
  required float tardyValue = 7;
  required float tardyCost = 8;
}

Fields

dimId: The dimension over which this attribute is being measured.
startValue: The starting value of the attribute (in the units of the dimension).
endValue: The ending value of the attribute (in the units of the dimension).
cost: The cost of this transaction in the schedule for this particular dimension. In the context of a time dimension, this would be the cost per minute. In the context of a distance dimension, this may be the cost per km or cost per mile.
slackValue: The amount of slack on the specified dimension added to the node in order to ensure feasibility by allowing a value to be shifted up to the start of a window.
slackCost: The cost of the slack which was added to the dimension to ensure feasibility.
tardyValue: The amount of tardiness added to the specified dimension to allow for a window end which has been exceeded.
tardyCost: The cost of the tardiness added to the specified dimension to ensure feasibility.

Examples

This illustates a valid response for the node attribute which provides a start and end value for the time dimension. Indicating that 10 minutes was the duration of the particular stop which was costed at 0.099 monetary units. There was no slack or tardiness on the stop.

attributes {
  dimId: "time"
  startValue: 546.842
  endValue: 556.842
  cost: 0.099
  slackValue: 0
  slackCost: 0
  tardyValue: 0
  tardyCost: 0
}

InterStop

The interstop describes the movement between stops, i.e. the transit between tasks that are performed in a particular schedule.

Schema definition

message InterStop {
  required int32 fromStopId = 1;
  required int32 toStopId = 2;
  repeated InterStopAttribute attributes = 3;
  repeated Geocode routeSegments = 4;
}

Fields

fromStopId: The origin stop identifier which provides the previous task that is being performed for this transit.
toStopId: The destination stop identifier which provides the next task that is being performed for this transit.
attributes: A list of edge attributes applicable to each of the dimensions in the model.
routeSegments: A list of geocodes which define the movement from the origin to the destination. In the instance of road network routing, the geocodes provide a sequence through the road network which may be interpreted as a linestring. Where the source and destination stops are at the same location, two geocodes are provided at the same location so that a linestring can generally be formed in this situation. In the case of planar routing, the geocode of the origin and destination are used to form a straight line between the stops.

Examples

This sample provides a valid return response for an interstop. The fromStopId and toStopId correspond to stops defined in the Route.Stops list.

fromStopId: 11
toStopId: 12
attributes {
  dimId: "time"
  startValue: 556.842
  endValue: 561.013
  cost: 0.041
}
attributes {
  dimId: "distance"
  startValue: 4.543
  endValue: 6.169
  cost: 4.878
}
attributes {
  dimId: "capacity"
  startValue: 600
  endValue: 600
  cost: 0
}
routeSegments {
  longitude: -6.25939083
  latitude: 53.341156
}
... (62 more items) ... 
routeSegments {
  longitude: -6.2556181
  latitude: 53.3468208
}

Notes

It is worth noting that the model is not permitted to place slack or tardiness on a transit edge. All slack and tardy values are incurred at a particular stop.

InterStop.Attribute

An InterStop attribute is an edge attribute describing the movement between tasks in a schedule. The edge attributes record the cumulative starting value and cumulative end value in the respective dimension of measurement at the relevant point in the schedule. The difference between the end value and start value will provide the marginal amount incurred on the specified dimension for this particular transaction.

Schema definition

message InterStopAttribute {
  required string dimId = 1;
  required float startValue = 2;
  required float endValue = 3;
  required float cost = 4;
}

Fields

dimId: The dimension over which this attribute is being measured.
startValue: The starting value of the attribute.
endValue: The ending value of the attribute.
cost: The cost of the units of attribute incurred on this dimension. I.e. (endValue-startValue)*(dimension cost coefficient).

Examples

This sample corresponds to a valid attribute in the distance dimension (measured in kms) where at the start of the travel the vehicle already had a cumulative distance of 4.543 km’s incurred, and on arrival at the destination had incurred 6.169 kms. This indicates that the vehicle had travelled 626m for this particular transit. The attribute for the time dimension will contain the corresponding duration for this movement.

attributes {
  dimId: "distance"
  startValue: 4.543
  endValue: 6.169
  cost: 4.878
}

TransitRuleAttribute

A transit rule attribute provides the details of each triggered transit rule for a particular route.

Schema definition

message TransitRuleAttribute {
  required string ruleId = 1;
  required string dimId = 2;
  required int32 fromStopId = 3;
  required int32 toStopId = 4;
  required float startValue = 5;
  required float endValue = 6;
  required float cost = 7;
}

Fields

ruleId: The rule identifier. The prefix specified on the transit-rule determines the way in which the identifiers are generated as a rule may be triggered multiple times.
dimId: The dimension to which the attributes for this rule are applied.
fromStopId: The origin stop, provided in the Route.Stops. Transit rules may not be applied during a task and as such are performed either immediately before a task, or immediately after a task.
toStopId: The destination stop, provided in the Route.Stops. Transit rules may not be applied during a task and as such are performed either immediately before a task, or immediately after a task.
startValue: The start value of the triggered transit rule.
endValue: The end value of the triggered transit rule
cost: The cost associated with the marginal value incurred by executing the triggered transit rule.

Infeasibility

Infeasibility information is provided for jobs or tasks which remain unperformed at the end of a search process. It may be that performing a job incurs cost which is higher than the penalty cost of leaving a particular job unperformed. In this instance, no infeasibility is provided as the correct cost-based decision has been made (i.e. the decision is feasible, but does not result in a lower cost solution). In general, infeasibility information is provided for each task at an aggregate level as there may be multiple reason for a particular infeasibility. The infeasibility is qualified with respect to the final incumbent solution found by the search.

When an Evaluate solve request is issued to the solver, the infeasibilities are evaluated slightly differently. Instead of attempting to provide general reasons (or aggregate constraint failures) for a specific task, the specific points of infeasibility (if any) are identified and provided to the user. Providing specific points of feasibility can be provided by the engine as infeasibility is permitted in an Evaluate request, unlike a normal Optimise request (which may only return a feasible incumbent).

Schema definition

message Infeasibility {
  required string taskId = 1;
  repeated Info infeasibilityInfo = 2;
}

Fields

taskId: The unique task identifier for which the infeasibility is applicable.
infeasibilityInfo: A list of infeasibility information objects which aggregate (for Optimise requests) common messages defining the infeasibility. Specific infeasibility messages at each task are provided for Evaluate requests.

Infeasibility Info

An infeasibility info object provides the specifics on an infeasibility detected. Where an infeasibility is related to a dimension, the dimension is provided which typically corresponds to the limits and values provided. Certain constraints are checked at a tier above the dimension in which case the dimension will be omitted. Where performing a given task is feasible, but results in infeasibility in other tasks, the constrainingTaskIds field is then populated.

Schema definition

message Info {
  required string message = 1;
  optional string dimId = 2;
  optional float limit = 3;
  optional float value = 4;
  optional int64 count = 5;
  repeated string constrainingTaskIds = 6;
}

Fields

message: A human-readable message describing the type of constraint that has been broken.
dimId: If present, the dimension on which a constraint has been broken.
limit: Depending on the context, it may pertain to a lower or upper limit on a particular dimension for this particular task.
value: The evaluation value at the point at which the constraint was broken. This value should be read with reference to the limit. I.e. if the value is below the limit, then an infeasible window start is present. If the value is higher than the limit, then a window end or capacity limit has been broken. In the case of a normal Optimise or ReOptimise request, the limit and value will represent the average limit and average value across several infeasibilities. The solver often evaluates thousands of infeasible moves which are aggregated together to provide high-level information.
count: The number of infeasible constraint evaluations that were used in the determination of the average limit and value.
constrainingTaskIds: A list of constraining tasks which are prohibiting the current task from being feasible.

IVR Solution ResponseSolution Response

Overview

Applicable models

Endpoint

Solution Response

Schema definition

Fields

Route

Schema definition

Fields

Stop

Schema definition

Fields

Examples

Stop Attribute

Schema definition

Fields

Examples

InterStop

Schema definition

Fields

Examples

Notes

InterStop.Attribute

Schema definition

Fields

Examples

TransitRuleAttribute

Schema definition

Fields

Infeasibility

Schema definition

Fields

Infeasibility Info

Schema definition

Fields

“Solution Response” was last updated: January 23, 2024