Skip to content

CART User Manual ‐ Scenario Configuration

Jump to bottom
Sébastien Ouellet edited this page May 14, 2025 · 4 revisions

The Scenario Config File

The Optimization tool allows you to determine an optimized solution for visiting customers in an efficient manner .The config file is written in the JSON format. You can edit it in any text editor. It is easy to not get the correct format in JSON files (e.g., brackets not lining up properly, missing commas, etc). You can use https://jsonlint.com/ to help check that your formatting is correct.

One must provide a configuration file to the tool to let it know things like:

  • What zone do you want the tool to optimize
  • What kind of vehicle are you using
  • Where are vehicles starting / ending
  • What is the load time
  • Do you want to allow vehicles to unload or do just full trips
  • And other options related to how the tool will find a solutions (extra constraints)

Note: A zone is a separate solution, independent from other zones.

The configuration file has 3 separate sections:
zone_configs:

  • This section contains a list of zone specific configurations. Each zone you run the model on can have some different options specified.
  • Arguments of each zone_config:
    • optimized_region:
      • Required Field: YES
      • Description: The “optimized_region” parameter lists the zone labels to be optimized together. The config below gives an example of a single zone designation and a multi-zone designation. In most cases, you will define a single zone. Simply specify the zone name in quotes inside the [] brackets (as shown for [“East”] in this example). In some instances, you may want to group some zones together and can do so by specifying the zone names in quotes inside the [] brackets and separated by a comma (as shown for ["West", "East"] in this example). The name of the zone must match the name in the “Block” category of the customer input file.
      • Allowed Values: List of strings
        • Example: ["East"], ["East", "West"]
    • Start_Point
      • Required Field: YES if not using unload, NO if using unload.
      • Description: The “Start_Point” parameter defines the start point for all vehicles in that zone configuration. The name must match the name as given in the extra_points.csv file.
      • Allowed Values: Strings
        • Example: [“waste_basket”]
    • End_Point
      • Required Field: YES if not using unload, NO if using unload.
      • Description: The “End_Point” parameter defines the end point for all vehicles in that zone configuration. The name must match the name as given in the extra_points.csv file.
      • Allowed Values: Strings (see Start_Point for examples)
    • load_time:
      • Required Field: YES
      • Description: The “load_time” parameter defines the average loading time per customer in minutes. The default provided here is 2.5 minutes.
      • Allowed Values: All positive floating point numbers
    • trips_vehicle_profile:
      • Required Field: YES if not using unload, NO if using unload.
      • Description: Defines the vehicle set-up. The parameter has two parameters. The first parameter, a string encapsulated with quotes, defines the vehicle profile for the solver. Currently, this setting must be either “3wheeler” or “wheelbarrow”. The second parameter is the capacity (i.e. number of containers the vehicle can carry) and should be an integer.
      • Allowed Values: Lists with 2 arguments a string vehicle, and an integer capacity value.
        • Example: [["3wheeler", 81]] or [["wheelbarrow", 12]]
    • enable_unload
      • Required Field: YES
      • Description: Determines whether to allow vehicles to unload or not. The tool either assumes each trip is a round trip from the Start_Point and End_Point (above) OR it allows for vehicles to unload containers between specific vehicle start and end points (set in the unload_vehicles argument below. Unload is good for areas where one or two vehicles can do the whole area but may not be able to do it in a single trip.
      • Allowed Values: Boolean: true, false
    • unload_vehicles
      • Required Field: No, unless enable_unload=true
      • Description: If you have enable_unload=true, then you need to provide the model with information on the number of vehicles available. When enable_unload=false, we do not have to provide the number of vehicles available because the tool determines how many vehicles are needed to visit all customers within 8 hours, or whatever values is used in hours_allowed. When using the unload option we must provide a list of vehicles to let the model know how many vehicles can be used. Please note that if you do not provide enough vehicles for the model to visit all customers in the hours allowed the model may fail to find a solution.
      • Allowed Values: List of lists - where the inner list contains information about each vehicle available
        • Example where we have 2 vehicles available for unloading. The first element in the list determines the type of vehicle, the second provides the capacity of that vehicle, the third is the vehicle's start point and the last element is the vehicle's end point:
"unload_vehicles": [
    ["3wheeler", 81, "waste_basket", "waste_basket"],
    ["3wheeler", 81, "waste_basket", "waste_basket"],
]
  • custom_unload_points
    • Required Field: Yes, if enable_unload is true | No, if enable_unload is false
    • Description: When enable_unload is true then vehicles can automatically unload containers at either the start or end point, but we wanted to allow for a custom unload location such as a truck parked on the side of a major road. Custom_unload_points allows the vehicle to use a specific unload point that is not its start or end point. To use this feature you must add an unload point to the extra_points.csv file and follow the format used in that file. Then you can add this custom unload point to this zone configuration by adding its name in the list. If you have multiple custom unload points you can add multiple and just separate them by a comma.
    • Allowed Values: List of names
      • Example:
        • custom_unload_points": ["EAST_UNLOAD"]
        • Where in the extra_points.csv file you have an entry like below: (add screenshot from GitHub file)
  • use_time_windows:
    • Required Field: NO
    • Description: You can provide time windows in the customer_data.xlsx file but you can make the tool ignore them by setting this value to false.
    • Allowed Values: false or true
  • start_time:
    • Required Field: NO
    • Description: The time at which the route would start, relevant if using time windows. Format is similar to “6:00AM”, for example.
  • hours_allowed:
    • Required Field: NO
    • Description: The model assumes an 8 hour day for visiting all customers and returning to end points. But sometimes a longer or shorter day may be preferred, especially when using the UNLOADING version of the model. For instance if using enable_unload=True, with only a limited number of vehicles it may take longer than 8 hours for those vehicles to visit all customers. In this case the model will not find a solution and will print out an error message saying this. You could then either add more vehicles OR extend the day. Another use would be to force the model to use more vehicles instead of having a smaller number of vehicles pick up more and unload them. By saying “I want this zone done in 4 hours” the model will have to use more vehicles simultaneously.
    • Allowed Values: Positive integers
  • consider_elevation:
    • Required field: NO
    • Description: We ignore automatically calculated elevation costs unless this is set to true, in which case we will avoid paths with large changes in elevation based on digital elevation models. This does not impact the use of tags from OSM such as the incline of a road, which can be controlled via vehicle profiles.
  • solver_options
    • Required Field: NO
    • Description: Google OR tools has various options to influence the solving of the optimization. These solver options are zone specific options to primarily allow for 2 things. 1) Attempt to have all vehicles travel about the same distance (span cost coefficient) and 2) have all vehicles not exceed a certain level of load (soft upper bound value and soft upper bound penalty).
    • span_cost_coefficient:
      • Required Field: NO
      • Description: Forces the algorithm toward a solution with trips that require a similar total distance. The difference between the shortest trip and the longest trip represents an additional penalty, so a solution with two trips of 20 and 21 km respectively may be chosen instead of one where there are two trips of 11 and 30 km respectively. This may produce solutions with a larger overall total distance than if the option is disabled, so use with caution.
      • Allowed Values: Positive Integers, common value is 1.
    • soft_upper_bound_value
      • Required Field: NO
      • Description: Soft constraint (meaning that it can be violated) that will try to force the algorithm to not exceed a certain number of units by too much. So if it is set to a value of 45, and the vehicle has a capacity of 81 and the soft_upper_bound_penalty is set to some penalty the model will try to only use up to about 45 units for each vehicle - but it can violate that if it is more efficient to violate it. You can increase the penalty to make this less flexible, or reduce the penalty to make it more.
      • Allowed Values: Positive Integers
    • soft_upper_bound_penalty
      • Required Field: NO, but is required if the soft_upper_bound_value is present
      • Description: This is the penalty value - for the soft upper bound, higher values make it more strict, lower make it less strict.
      • Allowed Values: Positive Integers (common values 1-100)

node_loader_options:

  • Required Field: Yes
    • Description: Dictionary that holds the num_containers_default parameter
    • num_containers_default
      • Required Field: YES
      • Description: the default number of containers used if a customer does not have a value populated in the customer data file.
      • Allowed Values: Positive Integers

global_solver_options:

  • Required Field: Yes
    • Description: Dictionary that holds the global solver parameters.
    • max_solver_time_min
      • Required Field: YES
      • Description: The OR-Tools model searches for optimal solutions but not exhaustively. Therefore you have to set the max number of minutes you will search for a solution. We have found good solutions in the 3-10 minute range. Please note that more time does not guarantee a better solution. Also this value is applied to every zone being optimized so if you are optimizing 10 zones and each has a max solver time of 10 minutes you could end up waiting over 100 minutes for the model to finish running.
      • Allowed Values: Positive Integers
    • fast_run
      • Required Field: YES
      • Description: This parameter allows you to run the model very quickly to test config settings. This should be used to ensure that the expected result or change occurs with the model, but if it is set to true it will not generate an optimized result. This option was used extensively in tool development when making changes to the code base. On a day by day level you may never need to set this to true.
      • Allowed Values: Boolean: true, false
        • Most common value will be false
    • presolved
      • Required Field: NO
      • Description: Enables approximations to split the locations across vehicles ahead of time, speeding up optimization.
      • Allowed Values: Boolean: true, false
    • presolved_from_past
      • Required Field: NO
      • Description: Requires users to include in the input data an additional file along the four mandatory files: manual_routes_edits.xlsx. That file can be found in a previous solution. If you'd like the routes to be as similar as possible from one day to another, this will help stabilize routing decisions. This will also try to preserve your manual adjustments. Requires the presolved field to be set to true.
      • Allowed Values: Boolean: true, false 
{"zone_configs": [  
 {"optimized_region": ["East"],  
  "Start_Point": ["waste_basket"],  
  "End_Point": ["waste_basket"],  
  "load_time": 2.5,  
  "trips_vehicle_profile": [["3wheeler", 81]],  
  "enable_unload": false,  
  "unload_vehicles": [["3wheeler", 81, "waste_basket", "waste_basket"]],  
  "custom_unload_points": [],  
  "hours_allowed": 7,  
  "solver_options": {  
   "span_cost_coefficient": 0,  
   "soft_upper_bound_value": 45,  
   "soft_upper_bound_penalty": 0  
  },

},  
 {"optimized_region": ["West"],  
  "Start_Point": ["waste_basket"],  
  "End_Point": ["waste_basket"],  
  "load_time": 2.5,  
  "trips_vehicle_profile": [["3wheeler", 81]],  
  "enable_unload": true,  
  "unload_vehicles": [  
      ["3wheeler", 50, "waste_basket", "waste_basket"],  
      ["3wheeler", 50, "waste_basket", "waste_basket"]  
  ],  
  "custom_unload_points": []  
}  
],  
"node_loader_options": {"num_containers_default": 2},  
"global_solver_options": {  
    "max_solver_time_min": 2,  
    "fast_run": true}  
   }
Clone this wiki locally