NDD Solution ResponseSolution Response

Overview

The NDD solution response has two tiers of structure. An initial Optimise request returns a Pareto frontier of compact solutions, each representing a different tradeoff between competing objectives (e.g. cost vs. balance). The user selects a point on the frontier and submits an Evaluate solve request to recover the full route detail as a solution instance.

Applicable models

• NDD ndd-cmibu6krtqja

Endpoint

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

Solution Response

The top-level solution response contains either a frontier (from an Optimise request) or a solution instance (from an Evaluate request), but typically not both.

Schema definition

message SolutionResponse {
  repeated CompactSolution frontier = 1;
  optional SolutionInstance instance = 2;
}

Fields

frontier

A list of compact solutions forming the non-dominated Pareto frontier. Populated when an Optimise solve request is issued.

instance

A solution instance containing full route detail. Populated when an Evaluate solve request is issued.

Compact Solution

A compact solution summarises a single point on the Pareto frontier. It contains the task sequences needed to reconstruct the full schedule and the objective function values that characterise this particular tradeoff.

Schema definition

message CompactSolution {
  repeated TaskSequence taskSequence = 1;
  repeated float objectives = 2;
  repeated string objectiveNames = 3;
}

Fields

taskSequence

The task sequences that fully define this solution. These can be submitted in an Evaluate solve request to recover the detailed route information.

objectives

A list of objective values for this solution, one per optimisation facet.

objectiveNames

A list of names corresponding to each objective value, describing what each objective measures.

Notes

• NDD models typically involve two stages: first an Optimise request which returns the Pareto frontier as compact solutions, then an Evaluate request to retrieve full detail for a selected point.
• The CompactSolution provides measurements (in terms of objective function values) without the detailed routing information, keeping the response compact.

Solution Instance

A solution instance provides the full route detail for a particular solution, analogous to a standard routing solution response but with day-level assignments.

Schema definition

message SolutionInstance {
  repeated Route routes = 1;
  repeated Infeasibility infeasibilities = 2;
}

Fields

routes

A list of routes detailing the movements and task allocations for each vehicle on each day. Routes with no allocated tasks will contain only the shift start and shift end stops.

infeasibilities

A list of infeasibilities describing jobs that could not be feasibly scheduled, along with reasons.

Route

A route describes the scheduled activities and evaluation values for a particular vehicle on a particular day.

Schema definition

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

Fields

vehicleId

The vehicle identifier.

stops

The collection of stops describing the standing activities performed by this vehicle on this day.

interStops

The collection of inter-stops describing the movements between locations.

fixedCost

The fixed cost applied to the vehicle if it was used on this day.

transitRuleAttributes

A collection of transit rule attributes recording triggered transit rules on this route.

day

The day (zero-based) on which this route is performed within the planning period.

Stop

A stop describes a point in the route where a task is performed.

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 StopAttribute attributes = 6;
}

Fields

id

The unique stop identifier (a numeric sequence starting at zero).

sequence

The sequence of the stop within the current route (zero-based, incrementing by one for each task).

locationId

The location at which this stop occurs.

taskId

The task identifier being performed at this stop.

jobId

The job identifier to which this task belongs.

attributes

A list of stop attributes for each dimension in the model.

Stop Attribute

A stop attribute describes the dimensional properties at a stop, recording the cumulative values at the start and end of performing the task.

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

startValue

The cumulative dimensional value at the start of performing this task.

endValue

The cumulative dimensional value at the end of performing this task. The difference between endValue and startValue provides the marginal contribution of this task.

cost

The cost incurred at this stop on this dimension.

slackValue

The amount of slack added on this dimension to satisfy a window constraint (e.g. waiting time).

slackCost

The cost of the slack added.

tardyValue

The amount of tardiness incurred on this dimension (e.g. late arrival).

tardyCost

The cost of the tardiness incurred.

InterStop

An inter-stop describes the movement between two consecutive stops in a route.

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.

toStopId

The destination stop identifier.

attributes

A list of inter-stop attributes for each dimension in the model.

routeSegments

A list of geocodes defining the path through the road network from the origin to the destination. These can be interpreted as a linestring for visualisation.

InterStopAttribute

An inter-stop attribute describes the dimensional properties of the movement between two stops.

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

startValue

The cumulative dimensional value at the start of the transit.

endValue

The cumulative dimensional value at the end of the transit. The difference between endValue and startValue provides the marginal transit quantity.

cost

The cost of the transit on this dimension (i.e. (endValue - startValue) * cost coefficient).

TransitRuleAttribute

A transit rule attribute records the details of a triggered transit rule on a particular route segment.

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 (prefixed with the ruleIdPrefix from the transit rule definition).

dimId

The dimension on which the rule was triggered.

fromStopId

The origin stop identifier.

toStopId

The destination stop identifier.

startValue

The cumulative dimensional value at the point the rule was triggered.

endValue

The cumulative dimensional value after the rule was applied.

cost

The cost incurred by the transit rule.

Infeasibility

An infeasibility describes a task that could not be feasibly scheduled, along with diagnostic information.

Schema definition

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

Fields

taskId

The unique task identifier for which the infeasibility applies.

infeasibilityInfo

A list of infeasibility info objects describing the reasons for the infeasibility.

Infeasibility Info

An infeasibility info object provides the specifics of a detected infeasibility.

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 was broken.

dimId

If present, the dimension on which a constraint was broken.

limit

The constraint limit (lower or upper bound) on the dimension.

value

The evaluation value at the point the constraint was broken. If the value is below the limit, an infeasible window start is present. If above the limit, a window end or capacity limit was exceeded. For Optimise requests, the limit and value represent averages across many infeasible evaluations.

count

The number of infeasible constraint evaluations used to compute the average limit and value.

constrainingTaskIds

A list of task identifiers that are prohibiting the current task from being feasible.