Logistics API Settings
The simulation.data.logistics_api_settings object allows you to fine-tune the optimization process when running simulations using the Stateful API. These settings control various aspects of the solver, model constraints, and calculation behavior.
Core Optimization Objectives
These parameters define the primary goals of the optimization, such as minimizing cost, time, or distance.
| Parameter | Type | Description | Default |
|---|---|---|---|
optimize_quantity | string | Optimization goal: total_time (default) or total_distance. | total_time |
time_dependent_transit | boolean | If true, optimization goal is always total_distance. | false |
trip_cost | number | Cost assigned to each trip. | - |
vehicle_costs | number | Cost per vehicle. High costs can discourage using additional vehicles. | 0 |
booking_penalty | number | Penalty for dropping a visit (unserved booking). Added to the objective function. Must be high enough to heavily discourage the solver from rejecting viable orders. | 10000 |
slack_cost | number | Penalty applied per unit of slack time (waiting time) for all nodes. Setting this helps the solver try to minimize idle waiting times for drivers, leading to more compact schedules. | - |
logistics_optimize_slack | boolean | If true, the solver will actively optimize and reduce the total slack (idle waiting time) in the resulting routes, tightening the schedule. | - |
use_path_equalizer | boolean | Enables the Path Equalizer, which adds a penalty for routes that deviate from the average route length (in terms of number of stops). Helps distribute assignments more evenly across available vehicles. | - |
path_equalizer_weight | integer | The weight (penalty multiplier) for the path equalizer objective. A higher value strongly forces the solver to prioritize balancing the number of stops across all vehicles over reducing pure travel time. | - |
route_cost_modification_primary | object | Advanced configuration to apply non-linear (polylinear) penalties or step-functions to travel time or distance matrices for the primary routing engine. Enables custom cost rules such as penalizing trips beyond a given distance or time threshold to encourage compact routes. Translated internally to travel_matrix_operator before the solver call. | - |
route_cost_modification_secondary | object | Analogous to route_cost_modification_primary but applied to the secondary routing engine (e.g. spheroid for straight-line distance). Adding a small distance factor here promotes geographic compactness without overriding the primary time objective. See Route Compactness for usage details. | - |
Operational Constraints
These settings define the hard limits and constraints for routes, such as time windows, slack, and compliance rules.
| Parameter | Type | Description | Default |
|---|---|---|---|
max_slack | number | Maximum allowed total slack (idle waiting time) in seconds across a route. Useful to prevent excessively inefficient driver schedules. | null |
max_pickup_slack | integer | Maximum allowed waiting time (slack) before a pickup node (in seconds). Limits how early a vehicle can arrive and wait idly before a pickup starts. | - |
max_dropoff_slack | integer | Maximum allowed waiting time (slack) before a dropoff node (in seconds). Limits how early a vehicle can arrive and wait idly before a dropoff. | - |
allow_vehicle_late | boolean | Relaxes time constraints to allow late or early arrivals for better route efficiency or to fit more orders, instead of rejecting them. | false |
vehicle_late_penalty_coefficient | integer | Penalty weight for lateness when allow_vehicle_late is true. Higher values discourage late arrivals, preserving strict SLAs unless absolutely necessary. | - |
max_possible_lateness | integer | Absolute maximum allowed lateness in seconds. Even if allow_vehicle_late is enabled, the solver will not violate this extreme upper limit. | null |
truckban_enabled | boolean | Enables or disables truck ban constraints, which restrict certain areas for vehicles during specific time windows. | - |
truckban_strategy | object | Defines the strategy for handling truck bans (e.g., waiting outside the zone, avoiding the zone entirely, etc.). | - |
truckban_buffer_time_windows | integer | Buffer time (in seconds) added when adjusting time windows for truck bans, providing a safety margin for the vehicle to leave the restricted zone before the ban starts. | - |
enable_time_windows_adjustment | boolean | Enables time window adjustment for nodes generated from operations_locations. This allows modifying the node's time windows using open_ts_offset and close_ts_offset values from the location settings. | false |
time_windows_adjustment_strategy | string | Defines the strategy for time window adjustment. Currently, the only supported value is DROPOFF_FIXED_CLOSE_TS_OFFSET. Under this strategy, the close_ts_offset (seconds) is subtracted from the node's original close time, ensuring it does not precede the open time: new_close_time = max(original_open_time, original_close_time - close_ts_offset). The open_ts_offset is currently unused by this strategy. Modification of open_ts is not supported at the moment. | DROPOFF_FIXED_CLOSE_TS_OFFSET |
use_walking_time_to_reduce_time_windows | boolean | Uses walking time to adjust time windows. | false |
is_pickup_end_of_trip | boolean | If true, marks pickup nodes as the completion of a trip for calculating vehicle trip limitations (e.g. max trips per vehicle). | - |
is_dropoff_end_of_trip | boolean | If true, marks dropoff nodes as the completion of a trip for calculating vehicle trip limitations. | - |
cumulative_limitations | array | Defines physical or operational limitations on the number of vehicles that can be serviced simultaneously at a specific location or depot. | - |
clear_cumulative_limitations | boolean | If true, clears and ignores any previously set cumulative vehicle limitations at locations. | - |
compound_zones | array | Definitions for specialized zones (e.g. specific areas or depots) that apply an artificial time penalty strictly upon entry or exit. | - |
Grouping & Sequence Rules
These parameters control how orders are grouped onto vehicles and the sequence in which they are serviced.
| Parameter | Type | Description | Default |
|---|---|---|---|
node_grouping_enabled | boolean | Activates logic to group nodes situated very close to each other, optimizing routing speed and allowing vehicles to consolidate nearby dropoffs/pickups efficiently. | - |
node_grouping_capacity_strategy | object | The strategy used to enforce capacity constraints on grouped nodes (e.g., ensuring sum of demands of grouped nodes does not exceed vehicle capacity). | - |
groups_order | object | A dictionary mapping group names to their sequential priority. Forces the solver to serve bookings from groups in a strictly defined continuous order within a route. | - |
mutually_exclusive_groups | array | List of group pairs that are designated as mutually exclusive. This prevents bookings from these specified groups from being simultaneously mixed on the same vehicle. | - |
strictly_exclusive_groups | array | List of groups that cannot be mixed under any generic circumstances on the same vehicle. By default, all groups are treated as strictly-exclusive unless overridden. | - |
group_crossing_penalty | number | Penalty added to the cost function when non-strictly exclusive groups are mixed, discouraging crossed deliveries while still preserving mathematical feasibility. | - |
mixed_fleet | boolean | Set to true to enable distinct time/distance matrices logic if vehicles in the fleet use demonstrably different routing profiles (e.g. bike vs truck). | false |
booking_order_prioritization | object | Configuration rule to prioritize critical bookings over standard jobs, influencing the solver to guarantee specific SLAs on high-priority orders. | - |
use_lifo_order_check | boolean | Enables strict Last-In-First-Out (LIFO) order constraints, frequently used in standard PDP cases to match stackable loading logic. | false |
lifo_order_check_on_all_vehicles | boolean | Ensures the LIFO execution check is systematically applied across all vehicles rather than selectively. | true |
Manual Editing & Re-Planning Support
These settings specifically affect how the system behaves when manual edits (insertions, moves) are performed or when re-planning live routes.
| Parameter | Type | Description | Default |
|---|---|---|---|
manual_edit_api_minimize_slack | boolean | Tries to actively minimize idle waiting times (slack) when a planner performs manual edit actions (e.g., drag and drop bookings). | - |
manual_edit_allow_vehicle_late | boolean | Dictates whether vehicles are allowed to be late specifically during manual edits, giving the planner more flexibility to force an assignment. | true |
manual_edit_lateness_penalty_coefficient | integer | The penalty coefficient applied for lateness when the planner forces an edit that causes a delay. | 10 |
manual_edit_api_vehicle_logistics_optimize_slack | boolean | Determines if vehicle-specific slack optimization is enforced during manual operations. If not provided, relies on the broader logistics_optimize_slack flag. | - |
manual_edit_api_use_vehicle_start_time | boolean | Ensures that manual edit calculations explicitly respect and adapt to the vehicle's predefined daily start time and ongoing sequence timeline. | - |
manual_edit_api_solver_kind | string | Defines the specific solver algorithm used specifically to handle manual edits (default: LOCAL). Useful for tuning responsiveness vs robustness during interaction. | LOCAL |
manual_edit_finalization_type_pickups | string | Defines the specific time finalization constraint strategy (min for earliest possible time, or max for latest) used iteratively for pickups during edits. | - |
manual_edit_finalization_type_dropoffs | string | Defines the specific time finalization strategy (min or max) assigned to dropoff nodes explicitly upon performing a manual edit. | - |
manual_edit_max_possible_lateness | integer | The discrete maximum upper limit in lateness allowable during manual interventions (seconds) before raising an outright failure. | - |
manual_edit_optimize_quantity | string | Defines the localized operational goal specifically invoked during edits: normally overriding to total_time or total_distance temporarily. | - |
manual_edit_slack_cost_factor | number | Modifiable cost penalty applied per incremental unit of slack explicitly when validating a user's manual re-arrangement or forced fit. | - |
manual_edit_allow_cvrptw_conversion | boolean | Enables CVRPTW mode and order grouping during manual edits in the simulation. When active, manual planning actions trigger an optimization check for CVRPTW feasibility (same pickup locations and time windows). If feasible, multiple orders are converted into a single node. Similarly, drop-offs at the same location with overlapping time windows are consolidated into a single action (ignoring capacity constraints).This streamlines manual planning by ensuring trips have a single pickup and consolidated drop-offs, visiting each location only once per trip. | false |
manual_edit_try_strict_time_windows_request | boolean | Tries to strictly enforce time windows perfectly during manual edits initially; only gently loosens timewindow constraints sequentially if unfeasible. Should be used with manual_edit_allow_vehicle_late=true. | false |
manual_edit_keep_assigned_nodes_relative_order | boolean | If true, the solver strictly preserves the relative sequence of already assigned nodes during manual edits. Useful for a planner inserting new orders without unexpectedly reshaping or reshuffling the ongoing route context. | - |
Simulation Execution & Logic
These parameters control the flow of the simulation and how it interacts with the current state of execution.
| Parameter | Type | Description | Default |
|---|---|---|---|
scheduling_mode | string | Defines the core operation structural intent: commonly prebook (for standard discrete PDP) or prebook_cvrptw (optimized for single depot/capacity-focused fulfillment). | - |
only_pdp | boolean | Strives to forcefully mandate classic Pickup and Delivery Problem (PDP) mathematical model processing rather than gracefully failing back to CVRPTW. | - |
pipeline_type | string | Internal logic layout configuration: e.g., simple_one_stage executes exactly one holistic stateless solver pass; whereas two_stages performs a structural estimation run followed closely by precision scaling adjustments. | - |
allow_upload_after_simulation_start_time | boolean | If true, enables live operational changes by explicitly allowing order/booking injections or manifest modifications even sequentially after the core shift start time has passed. | false |
booking_data_pipeline_filters | array | List of filter rules applied to incoming bookings before they are processed by the pipeline. Each rule targets a field in booking.data and supports operations such as equals, not_equals, contains, not_contains, in, not_in, is_null, and is_not_null. The value field supports Django template syntax (e.g. {{ simulation.start_time|date:'Y-m-d' }}), allowing dynamic filtering based on simulation properties. All rules are applied sequentially; only bookings matching all rules are passed to the solver. | [] |
should_lock_next_stop_if_vehicle_live | boolean | Operationally locks the immediate upcoming physical stop assignment for active vehicles, structurally preventing real-time re-optimizations from abruptly modifying a driver's target destination while en route. | true |
should_optimize_fail_to_board_bookings | boolean | Attempts actively to re-examine or securely salvage trips that were temporarily tagged or rejected as failed-to-board within the continuing sequential solve logic. | true |
geofence_definition_strategy | object | Operational strategy pattern assigning logic for localized map geofence creation rules. | - |
geofence_vehicle_allocation_strategy | object | Allocation stringency rule map (STRICT vs. FLEXIBLE) defining precisely how robustly a vehicle is structurally held within its parent designated geofence operational cluster bounds. | - |
should_set_max_slack_start_location_zero | boolean | Explicitly resets maximum allowed waiting time on the vehicle's initial start node perfectly to zero, essentially preventing artificial dispatch delays systematically. | - |
path_constraints_mode | string | Underpinning path architectural restrictions engine methodology (legacy vs logistics). | - |
route_compactness | object | Settings applied rigorously to encourage denser, compact physical cluster groupings visually minimizing unneeded geographic spread logically via polylinear penalties. | - |
finalization_type_pickups | string | Method defining the physical time allocation assignment internally for generic pickups, choosing either min (dispatch as earliest logically scheduled) or deliberately assigning to max. | min |
finalization_type_dropoffs | string | Method defining the physical time allocation assignment explicitly for generic dropoff completions (min or equivalently max). | min |
Advanced Solver Configuration
These parameters provide low-level control over the VRP solver algorithm. They are typically used by experts to tune performance and search behavior.
| Parameter | Type | Description | Default |
|---|---|---|---|
algorithm | string | Solver algorithm: static (default) or dynamic (for real-time/on-demand). | static |
calculations_mode | string | sync (return result immediately) or async (return job ID). | - |
first_solution_strategy | integer | Strategy used to find the initial solution. | 0 |
first_solution_strategies | array | A list of first solution strategies (integers) to be used concurrently to execute the optimization run. | - |
solution_limit | number | Maximum number of solutions to generate during the search. | 10000000 |
time_limit_ms | number | Maximum time allowed for the search (in milliseconds). | 10000000 |
auto_calculate_time_limit_enabled | boolean | Enable or disable auto calculation of solver time limit. | null |
auto_calculate_time_limit_params | object | Parameters for auto calculation of solver time limit. See Auto Calculation Solver Time for details. | null |
use_local_search_metaheuristic | boolean | Enables local search metaheuristics. | false |
guided_local_search_lambda_coefficient | number | Parameter for the guided local search procedure. | 0.1 |
use_tsp_opt | boolean | Enables Traveling Salesperson Problem (TSP) optimization. | false |
log_search | boolean | Enables search logging. | false |
lns_time_limit_ms | number | Time limit for Large Neighborhood Search (LNS) completion search. | 1000 |
savings_neighbors_ratio | number | Ratio for savings neighbors. | 0 |
waypoints_optimization_second_phase | boolean | Enables a second phase of waypoint optimization for prebook mode. | false |
optimization_step | number | Minimum improvement step for local search. | 1 |
use_all_local_search_operators | boolean | Uses all available local search operators. | false |
use_depth_first_search | boolean | Uses depth-first search instead of local search. | false |
cvb_fleetmin_time_limit | integer | Time limit for CVB fleet minimization. | - |
cvb_fleetmin_solutions_limit | integer | Solution limit for CVB fleet minimization. | - |
cvb_fleetmin_iterations_limit | integer | Iteration limit for CVB fleet minimization. | - |
use_cvb_local_search_operator | boolean | Uses CVB local search operator. | - |
cvb_local_search_iterations_limit | integer | Iteration limit for CVB local search. | - |
average_travel_duration_to_node | integer | Estimated average travel duration to a node (in seconds). | - |
use_vehicles_nodes | boolean | Enables or disables the use of nodes representing vehicles. | - |
Infrastructure & Connectivity
Settings for connecting to external calculation services.
| Parameter | Type | Description | Default |
|---|---|---|---|
stateless_api_server | string | URL of a custom stateless API server to use for the simulation. | - |
stateless_api_login | string | Login for custom stateless API server. | - |
stateless_api_password | string | Password for custom stateless API server. | - |