ISR Solution ResponseSolution Response

Overview

The solution response is produced by the API as an output object for a given solve request. This is considered the primary output from the Icepack engine. The solution response contains all the evaluation information for each vehicle, i.e. travel durations and distances between collections as well as the streets and matching information in the schedule.

Applicable models

• ISR isr-z4foi53qznrv

Solution Response

The solution response contains five 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 by the configuration). The second is a list of routes which are the detailed activities for each vehicle. 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;               // the routing cost of the solution returned
  repeated Route routes = 2;                  // the list of routes for each vehicle
  repeated Infeasibility infeasibilities = 3; // infeasibilities generated
  repeated Matching matchings = 4;            // for each point, the location on the segment it matched to
  repeated Segment segments = 5;              // only segments that had a matching
}

Fields

objective

The cost of the solution returned. The Icepack solver will attempt to minimise this value.

routes

A list of routes detailing the movements and task allocations for each vehicle. Vehicles with no activities allocated will have an empty route. There is a 1 to 1 relationship between routes and vehicles.

infeasibilities

A list of infeasibility reasons as to why certain collections could not be performed.

matchings

For each collection location in the input payload, a matched position on the road network indicating the attached road segment is provided.

segments

A list of road segments which are associated with the computed matchings.

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;
}

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).

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;
  optional string collectionId = 3;
  optional string offloadSiteId = 4;
  repeated StopAttribute attributes = 5;
  optional int32 segmentId = 6;
  required Geocode location = 7;
}

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.

collectionId

If the stop takes place at a designated collection, the collectionId is provided.

offloadSiteId

If the stop takes place at a designated offload site, the offloadSiteId is provided.

attributes

A list of stop attributes for either time, distance or capacity.

segmentId

If a stop takes place at a collection, the idenfifier of the road segment at which this stop is performed is provided.

location

The matched position for a collection from the road network is provided.

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.

Schema definition

message StopAttribute {
  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. The ISR has three fixed dimensions: time, distance and capacity.

startValue

The starting value of the attribute (in the units of the configuration).

endValue

The ending value of the attribute (in the units of the configuration).

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 unit time. In the context of a distance dimension this may be the cost per km or cost per mile.

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 geometry = 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.

geometry

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.

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).

Infeasibility

Infeasibility information is provided for collections which remain unperformed at the end of a particular solve. It may be that performing a collection is not possible within the constraints of the problem. In such instances, infeasibility information is provided for each collection 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 collection, 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 collectionId = 1;
  repeated Info infeasibilityInfo = 2;
}

Fields

taskId

The unique collection 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 constrainingCollectionIds 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 constrainingCollectionIds = 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.

Matching

A matching provides a description of the position on the road network to which a specific collection was placed. The method used at the moment is to attach to the closest network position.

Schema definition

message Matching {
  required string collectionId = 1;
  required Geocode collectionPoint = 2;
  required int32 segmentId = 3;
}

Fields

collectionId

The unique identifier for the collection

collectionPoint

The position, provided as a geocode, on the road network which has been interpreted as the collection location.

segmentId

The road network segment id (corresponding to the segments list in this response payload) to which this particular collection is attached.

Segment

Schema definition

message Segment {
  required int32 id = 1;
  required string name = 2;
  required float weight = 3;
  required float duration = 4;
  repeated Geocode geometry = 5;
}

Fields

id

The unique identifier for a segment.

name

The name of the segment, typically corresponding to the name of the road.

weight

The distance of this particular segment.

duration

The time taken to traverse the segment before any duration coefficients are applied.

geometry

A list of geocodes which describe the curvature of this particular road segment.