Engine settings aggregated object
routing_engine objectrequired
Name of the engine to be used.
Possible values: [euclidian, euclidian_geo, asteria, graphhopper, mapbox, valhalla, osrm, osrme, google, here, spheroid, spheriodtd, tomtom]
asteriaRoad network to be used by the routing engine
combiSpeed value used by the routing engine
0Can be used to manually adjust time needed to move between the waypoints compared to what the routing engine provides based on behicle profile.
1truemodel_parameters objectrequired
General metadata parameters describing simulation, including predefined settings for groups, compound zones, cumulative limitations etc. that will need to be configured for respective nodes (vehicles or bookings)
Applicable to certain solver models. If set to logistics, enables a mode that allows to add cost to slack and minimize slack for trips while retaining all other constraints in place.
Sets wait of slack cost for the model. The higher the value, the more slack is optimized. Recommened range is 0.1 - 1000. Use with caution because it may result in overoptimizing slack and force vehicle to travel longer, or for vehicle to do mulitple trips instead of a single trip.
cost of each vehicle. In scenarios where trips take much longer than 2.78 hours (10000 s) or 10 km (10000 m), vehicle cost of 10000 might lead to higher number of vehicles used (as the cost of initiating additional vehicle is cheaper than using the existing ones).
0Amortized default vehicle cost (linear part)
nullAmortized default vehicle cost (quadratic part)
nullThe penalty refers to a cost associated with dropping visits to certain locations. In vehicle routing problems, penalties are used to make a trade-off between visiting every location and minimizing overall costs (such as distance or time). If visiting a location is not feasible, a penalty is incurred instead. This allows the solver to skip visits to some locations, especially when visiting them would lead to excessive costs or infeasibility, while still returning a valid solution.
This penalty is added to the total objective function and helps guide the solver in making decisions about which locations to skip.
10000Only set to true if vehicles are using different routing profile and\or have different capacity.
falseFlag that enables using walking time in time windows reduction.
falseIf true then optimization goal is always total_distance regardless of the value passed in optimization_quantity.
falseDefines the optimization goal. Possible values: total_time - optimize total time of all routes and total_distance - optimize total distance of all route. passenger_optimization - objective function becomes the total sum of all travel times of each booking
Possible values: [total_time, total_distance, passenger_optimization]
total_timeMaximum allowed slack for nodes in an optimization run.
nullFlag that enables LIFO order check for nodes of this booking. Used only if use_lifo_order_check is set for model.
falseEnables LIFO order checking on all vehicles in the model.
trueList of mutually-exclusive group relations. Group names are set in the group field for bookings and nodes. Every item of the list should be a list of string group names whose bookings (or nodes) cannot be on the same vehicle at the same time. For example, the value [["group1", "group2"], ["group2", "group3"]] prohibits bookings with groups group1 and group2 along with group2 and group3 from being transferred in the same vehicle at the same time, but allows simultaneous transfer of bookings with groups group1 and group3.If strictly_exclusive_groups are not set, then this constraint is soft, and its weight is based on the group_crossing_penalty value. To achieve a hard constraint, strictly_exclusive_groups should have a list of such groups.
Some groups can have a hard constraint and other groups can have a soft constraint at the same time.
List of groups that cannot be at any circumstances be crossed with other groups. Default: All groups are strictly-exclusive.
Penalty for crossing non-strictly exclusive groups.
compound_zones object[]
This list contains zones where entering or exiting may require additional time. Compound zone parameters will be applied to nodes belonging to groups specified in this list, and compound zone time will be added to the total travel time for those nodes. This allows for optimization against nodes with shorter enter/exit times, likewise supporting scenarios with fixed required docking times.
A list of groups that belong to the zone.
Represents and validates UUID string
Time in seconds required to enter the zone
0Time in seconds required to exit the zone
0cumulative_limitations object[]
Contains a list describing limitations on the number of cumulative vehicles at the starting depot. This option is used to limit the number of vehicles that can be serviced simultaneously at the same depot as well as manage how vehicles are serviced at the depot.
For this option to work properly, every vehicle should have not more than one node of type vehicle_position, bound as a partial route. This node is a placeholder for the pickup event. If the partial_route contains other nodes, the vehicle_position node must be the last in the list. The list of nodes_uids should hold the UID of these pickup nodes. The scheduler will split pickup time intervals into some service intervals. Each service interval has a duration of depot_service_time. After this, the scheduler will remove the initial pickup nodes and instead insert pickup nodes, one per vehicle for every service interval.
Options group and node_uids can be used together in the same cumulative limitation instance.
Nodes belonging to this group will be included in the list identifying the pickup location.
List of node uids identifying the pickup location.
Time in seconds to service a vehicle in the nodes defined in this object
Number of vehicles that can be served at these pick up nodes at the same time
groups_order object
Order of groups. Dict that should contain group names mapped to integer sequence number of this group.
Node ordering depends on their assigned groups and the groups_order configuration:
- Nodes with groups in
groups_order: These nodes are sorted by their priority values. Higher priority values appear earlier. - Nodes without groups in
groups_order: These nodes have the lowest priority and appear after all nodes in point 1. - Nodes with groups in
groups_orderbut withNonepriority: The order of these nodes is undefined and they may appear anywhere in the sequence.
route_compactness object
Route compactness is achieved by employing a polylinear model that adds a cost (either time or distance, depending on the optimization goal) to vehicle travel to the nodes. This model penalizes longer travel, thereby promoting more compact routes. Integrated into the total cost function as a soft constraint, this mechanism automatically increases route compactness, balancing it against other optimization penalties.
Specifies whether to use distance or time. This value does not need to match the optimize_quantity in the payload.
Possible values: [distance, time]
If true, no penalty is applied to the trip from partial_route to the first subsequent node. Note that penalties are always ignored for internal trips within a multi-node partial_route
trueIf true, no penalty is applied to the trip from the last node to partial_route_end. Note that penalties are always ignored for internal trips within a multi-node partial_route.
trueDefines the threshold for applying the penalty. Its units match those of the matrix_type matrix (typically meters for distance, seconds for time).
Determines if the penalty applies to values above or below the threshold.
Possible values: [greater, less]
penalty object
A number whose units match those of the matrix_type matrix.
0The penalty rate per unit from the matrix_type matrix.
0solver_parameters objectrequired
Solver paramters control the underlying solver behaviors and should be used only by experts.
Solver to be used for optimization. dynamic should be used for real time operations (on-demand)
Possible values: [static, dynamic]
staticThe value first_solution_strategy defines the first solution-finding strategy to be used during calculations.
0 = AUTOMATIC
1 = GLOBAL_CHEAPEST_ARC
2 = LOCAL_CHEAPEST_ARC
3 = PATH_CHEAPEST_ARC
4 = PATH_MOST_CONSTRAINED_ARC
5 = EVALUATOR_STRATEGY
6 = ALL_UNPERFORMED
7 = BEST_INSERTION
8 = PARALLEL_CHEAPEST_INSERTION
9 = LOCAL_CHEAPEST_INSERTION
10 = SAVINGS
11 = SWEEP
12 = FIRST_UNBOUND_MIN_VALUE
13 = CHRISTOFIDES
14 = SEQUENTIAL_CHEAPEST_INSERTION
16 = ADJUSTABLE_PARALLEL_CHEAPEST_INSERTION
17 = LOGISTICS_PARALLEL_CHEAPEST_INSERTION
AUTOMATIC Lets the solver detect which strategy to use according to the model being solved. May not always be the best.
PATH_CHEAPEST_ARC Starting from a route "start" node, connect it to the node which produces the cheapest route segment, then extend the route by iterating on the last node added to the route.
PATH_MOST_CONSTRAINED_ARC Similar to PATH_CHEAPEST_ARC, but arcs are evaluated with a comparison-based selector which will favor the most constrained arc first. To assign a selector to the routing model, use the method ArcIsMoreConstrainedThanArc().
EVALUATOR_STRATEGY Similar to PATH_CHEAPEST_ARC, except that arc costs are evaluated using the function passed to SetFirstSolutionEvaluator().
SAVINGS Savings algorithm (Clarke & Wright). Reference Clarke, G. & Wright, J.W. "Scheduling of Vehicles from a Central Depot to a Number of Delivery Points" , Operations Research, Vol. 12, 1964, pp. 568-581.
SWEEP Sweep algorithm (Wren & Holliday). Reference Anthony Wren & Alan Holliday Computer Scheduling of Vehicles from One or More Depots to a Number of Delivery Points Operational Research Quarterly (1970-1977), Vol. 23, No. 3 (Sep., 1972), pp. 333-344.
CHRISTOFIDES Christofides algorithm (actually a variant of the Christofides algorithm using a maximal matching instead of a maximum matching, which does not guarantee the 3/2 factor of the approximation on a metric travelling salesperson). Works on generic vehicle routing models by extending a route until no nodes can be inserted on it. Reference Nicos Christofides, Worst-case analysis of a new heuristic for the travelling salesman problem, Report 388, Graduate School of Industrial Administration, CMU, 1976.
ALL_UNPERFORMED Make all nodes inactive. Only finds a solution if nodes are optional (are element of a disjunction constraint with a finite penalty cost).
BEST_INSERTION Iteratively build a solution by inserting the cheapest node at its cheapest position; the cost of insertion is based on the global cost function of the routing model. As of 2/2012, only works on models with optional nodes (with finite penalty costs).
PARALLEL_CHEAPEST_INSERTION Iteratively build a solution by inserting the cheapest node at its cheapest position; the cost of insertion is based on the arc cost function. Is faster than BEST_INSERTION.
LOCAL_CHEAPEST_INSERTION Iteratively build a solution by inserting each node at its cheapest position; the cost of insertion is based on the arc cost function. Differs from PARALLEL_CHEAPEST_INSERTION by the node selected for insertion; here nodes are considered in their order of creation. Is faster than PARALLEL_CHEAPEST_INSERTION.
GLOBAL_CHEAPEST_ARC Iteratively connect two nodes which produce the cheapest route segment.
LOCAL_CHEAPEST_ARC Select the first node with an unbound successor and connect it to the node which produces the cheapest route segment.
FIRST_UNBOUND_MIN_VALUE Select the first node with an unbound successor and connect it to the first available node. This is equivalent to the CHOOSE_FIRST_UNBOUND strategy combined with ASSIGN_MIN_VALUE (cf. constraint_solver.h).
SEQUENTIAL_CHEAPEST_INSERTION Strategy implies an incremental first stage, which can be used to speed up the first solution for incremental solver calls. The incremental first stage tries to build the first solution based on a previous successful call to the Solver. For this to work properly, nodes, assigned during the previous API call, should be present in a list of assigned nodes in vehicles.
ADJUSTABLE_PARALLEL_CHEAPEST_INSERTION Strategy implies an incremental first stage, which can be used to speed up the first solution for incremental solver calls. The incremental first stage tries to build the first solution based on a previous successful call to the Solver. For this to work properly, nodes, assigned during the previous API call, should be present in a list of assigned nodes in vehicles.
LOGISTICS_PARALLEL_CHEAPEST_INSERTION Strategy is more efficient when logistics problems (when all pickups are located in one geographical location) are modelled as PDPTW ("prebook" mode).
0Limit to the number of solutions generated during the search.
10000000Flag that enables using local search metaheuristic
falseParameter of the local search procedure.
0.1Flag that enables TSP optimization.
falseLimit in ms to the time spent in the search.
10000000Flag that enables log search.
falseLimit in ms to the time spent in the completion search for each local search neighbor.
1000Savings neighbors ratio
0Enables second phase waypoints optimization for prebook.
falseWaypoints solution limit in second phase.
1000Minimum step by which the solution must be improved in local search.
1Use all local search operators.
falseIf True, the solver should use depth-first search rather than local search to solve the problem.
falseList of additional local search operator names. Currently supported: extended_swap_active that improves solutions when waypoints are used;
logistics_relocate_pair that improves performance when logistics problem is solved in prebook mode.
Possible values: [extended_swap_active, logistics_relocate_pair]
First solution strategies for second stage (Only one of them is used)
Maximum calculation time for second stage in milliseconds
calculation_parameters objectrequired
Choose between default - Pickup and Delivery Problem (PDP) and Capacitated Vehicle Routing Problem with Time Windows (CVRPTW). CVRPTW is only suitable for scenarios with only one pickup point/DC. In this CVRPTW mode, all the pickup nodes are combined together, significantly reducing the number of nodes, which significantly improve the result. Each vehicle is limit to the maximum of one trip (or one pickup), as pickup nodes are combined. Both modes support capacity constrains.
Possible values: [prebook, prebook_cvrptw]
In sync mode, calculation results will be returned to the initial request, while in async mode, the consumer should retrieve the results by using another request with job_id as a reference.
Possible values: [sync, async]
Disables or enables the use of nodes representing vehicles in optimization.
Relaxes time constrains allowing for vehicles to arrive late to the nodes trading off more efficient routes.
falsePenalty coefficient for lateness, used when allow_vehicle_late is true. The higher the penalty, the more weight is given to arrival on time.
Time in seconds for max possible lateness. Max lateness is not limited if this is null. Used if allow_vehicle_late is true.
If true and the assignment contains loops the algorithm will try to schedule dropoffs earlier, so the passenger will not move through their stop twice. Breaks are not rescheduled.
If both dropoff_earlier and pickup_earlier are disabled (unspecified), loop detection is completely off, no analysis is performed, and no relevant actions are taken.
falseIf true and the assignment contains loops the algorithm will try to schedule pickups later, so the passenger will not move through their stop twice. Breaks are not rescheduled.
If both dropoff_earlier and pickup_earlier are disabled (unspecified), loop detection is completely off, no analysis is performed, and no relevant actions are taken.
If true then the Solver will take into account each node's possible departure time when query matrix (mixed time matrix mode).
If current_time then all nodes will use the current time (from API request) as departure time, if min_time or max_time then node's open or close time will be used.
Possible values: [current_time, min_time, max_time]
If true node weights are used in the cost calculation.
falseThis setting is for CVRPTW mode. If a positive value is present, then vehicle cost is added to the overall cost function if the number of nodes on the path is greater than the given value. A negative value disables additional costs.
-1Defines whether to use paths equalizer
falseDefines weight of the additional cost element produced by variance of path lengths.
100Enables cumulative distance calculation. If set to true every node in the 'vehicles' section in the result will contain a 'scheduled_distance' field, which contain distance to this node.
falseIf enabled, optimization bookings that have unroutable nodes will result in a no-offer situation (so no vehicle assignments will occur).
The default is false, in which case if a node is unroutable, the optimization engine will use an air distance (straight line) approximation between the nodes.
Routability is determined by the underlying map, selected vehicle profile, and any temporary or permanent restrictions in place.
falseEqualize paths during second stage of calculation. The system will first calculate the minimum number of vehicles required to meet the demand, and it will then balance the workload across the active vehicles based on the selected balancing method (e.g., number of bookings, total trip distance, or total trip time). The system will ensure that the number of vehicles is not increased during the balancing process.
false{
"routing_engine": {
"routing_engine_name": "asteria",
"road_network": "combi",
"speed": 0,
"time_factor": 1,
"make_depot_zero": true
},
"model_parameters": {
"path_constraints_mode": "string",
"slack_cost_factor": 0,
"vehicle_costs": 0,
"vehicle_amortized_linear_cost_factor": null,
"vehicle_amortized_quadratic_cost_factor": null,
"booking_penalty": 10000,
"mixed_fleet": false,
"use_walking_time_to_reduce_time_windows": false,
"time_dependent_transit": false,
"optimize_quantity": "total_time",
"max_slack": null,
"use_lifo_order_check": false,
"lifo_order_check_on_all_vehicles": true,
"mutually_exclusive_groups": [
"string"
],
"strictly_exclusive_groups": [
"string"
],
"group_crossing_penalty": 0,
"compound_zones": [
{
"groups": [
"string"
],
"node_uids": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"enter_time": 0,
"exit_time": 0
}
],
"cumulative_limitations": [
{
"group": [
null
],
"node_uids": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"depot_service_time": 0,
"max_cumulative_vehicles": 0
}
],
"groups_order": {},
"route_compactness": {
"matrix_type": "distance",
"ignore_first": true,
"ignore_last": true,
"threshold": 0,
"relation": "greater",
"penalty": {
"base": 0,
"rate": 0
}
}
},
"solver_parameters": {
"algorithm": "static",
"first_solution_strategy": 0,
"solution_limit": 10000000,
"use_local_search_metaheuristic": false,
"guided_local_search_lambda_coefficient": 0.1,
"use_tsp_opt": false,
"time_limit_ms": 10000000,
"log_search": false,
"lns_time_limit_ms": 1000,
"savings_neighbors_ratio": 0,
"waypoints_optimization_second_phase": false,
"waypoints_solution_limit": 1000,
"optimization_step": 1,
"use_all_local_search_operators": false,
"use_depth_first_search": false,
"use_local_search_operators": [
"extended_swap_active"
],
"first_solution_strategies_second_stage:": [
0
],
"time_limit_ms_second_stage": 0
},
"calculation_parameters": {
"scheduling_mode": "prebook",
"calculations_mode": "sync",
"use_vehicles_nodes": true,
"allow_vehicle_late": false,
"vehicle_late_penalty_coefficient": 0,
"max_possible_lateness": 0,
"dropoff_earlier": false,
"pickup_later": true,
"use_mixed_time_matrix": true,
"matrix_timestamp_selection": "current_time",
"use_node_weights_cost": false,
"cvrptw_artificial_nodes_per_vehicle": -1,
"use_path_equalizer": false,
"path_equalizer_weight": 100,
"calculate_cumulative_distance": false,
"exclude_unroutable_booking": false,
"use_selective_path_equalizer": false
}
}