Truck routing with custom route choice functions

May 2023 — Technical note #80

Dimitris Triantafyllos

Senior Product Specialist


Traffic congestion remains one of the biggest pain points in logistics management. For logistics professionals, congestion-related delay causes additional operation costs (excess fuel consumption, extra working hours etc.), lower travel time reliability, customer dissatisfaction, a higher environmental footprint, and reduced safety for drivers and cargo.

Efficient planning of the commercial vehicle routes can contribute to reducing the impact of congestion on delivery times. Logistics operators often provide drivers with fleet guidance systems that assist them in making the best decision when choosing a route. You can model this truck behavior in Aimsun Next mobility modeling software. We provide you with the possibility to code a custom Route Choice function that provides the probability of choice of each of the available routes: those calculated based on the costs during the previous interval(s), those read from an input path file, for example produced with a Dynamic User Equilibrium (DUE) assignment, or even OD Routes predefined in the Aimsun Next document.



A truck transport company providing services for hauling specialized items has decided to upgrade its fleet of trucks from a Base Navigation System (Base NS), which only suggests a fixed, OD Route to an Advanced Navigation System (Advanced NS), which suggests the route with the current lowest cost among a selection of possible routes(predefined in Aimsun Next).

The traffic demand consists of 2 OD matrices (Car, Truck) starting at 08:00am with a duration of 2 hours. Regarding the Dynamic Traffic Assignment (DTA) of Cars and Trucks:

  • For the vehicle type Car: in both scenarios (Base NS and Advanced NS), Car can use either the paths from the Dynamic User Equilibrium APA file (probability 70%) or from the Stochastic Route Choice (SRC) calculation (probability 30%). For more details check Dynamic Traffic Assignment – Aimsun Next Users Manual.
  • For the vehicle type Truck: in the Base NS scenario, heavy vehicles will always follow a specific predefined OD Route (Main OD Route), while in the Advanced NS scenario heavy vehicles can choose among a set of OD Routes by applying a custom Route Choice function in the Dynamic Traffic Assignment. In this case the function will compare the travel costs calculated on each of the OD Routes available and will assign trucks to the route with the lowest cost estimated in the previous 5-min. Costs for every route will be updated every route choice interval (5-min).

In the case of an unexpected event, the delivery of the goods will face a significant delay with the Base NS. An incident occurs at 08:15am with a duration of 60-min on the route where the trucks are assigned to follow. The incident is a Traffic Management Strategy > Section Incident closing 2 out of 2 lanes on the motorway.

In this example, we will focus on a single specific Origin-Destination route.


Base NS

The current navigation system provides the truck driver with a single designated OD Route from the Origin centroid named: Vic to the Destination centroid named: Ribes independently of the current traffic conditions on that route. Thus, 100% of the Trucks will follow this route.

Figure 1 shows the OD matrices in the traffic demand (08:00-10:00 AM) for both Car and Truck vehicle types and for the OD matrix for vehicle type Truck, the percentage 100% assigned to the Main OD Route in the Path Assignment Tab for Origin Vic and Destination Ribes. For more info how to define percentages to various OD Routes, check OD Matrices – Aimsun Next Users Manual.

Figure 1

To assign the Main OD Route to 100% of the Trucks:

  • Open the Dynamic Experiment
  • Go to Dynamic Traffic Assignment Tab
  • In Fixed Routes, set the Following OD Routes for Trucks to 100%.

Figure 2 shows how to define the 100% of the OD Routes in the DTA.

Figure 2

As explained, an incident will happen on the motorway from 08:15 – 09:15am, closing 2 out of 2 lanes. Figure 3 shows the main designated route of the trucks for that OD pair and the location of the incident.

Figure 3

As a result:

  • 30% of the Cars (those following SRC paths) can be reassigned to follow alternative routes.
  • 100% of the Trucks will get stuck on the motorway waiting until the clearing of the event.

In the following video, you can check out the queue propagation per path type. Trucks displayed with orange color are assigned to follow a single OD Route.

Advanced NS

In the Advanced Navigation System scenario, two new alternative OD Routes were added. These new OD Routes were designed to calculate the most reliable, compliant, cost-efficient, and time-effective ways for trucks to reach their destinations in the case of an unexpected event on the route. All these routes have been defined in Aimsun Next as OD Route objects. Before the departure of the truck, the Advanced NS navigation system will recommend one of the designated routes, the route with the lowest cost in the past 5-min (we are using the default cost function in all links). Figure 4 shows the 2 alternative OD Routes from Vic to Ribes.

Figure 4

In this example we created a new Route Choice function where:

  • Trucks will be assigned to follow the OD Route with less cost observed in the last 5-min among the 3 designated OD Routes.
  • For the Cars that will follow SRC (30% probability) for this Origin and Destination pair, a logit function is applied.
  • For the Cars that will follow DUE APA paths (probability 70%), they will still follow the DUE paths in the APA file with the percentages varying in each interval of the route choice.

To activate the 3 designated OD Routes:

  1. Open the OD matrix Truck
  2. Go to Path Assignment Tab
  3. Filter per Origin (Vic) and Destination (Ribes)
  4. Assign a value > 0 to the 3 OD Routes that you want to assess the costs. Value does not matter.

Figure 5

To Create a new Route Choice function:

    1. Go to Demand Data folder in the Project menu.
    2. Create a new function in Functions folder > Right Click > New > Function.
    3. In Function Type, select the option “Route Choice”.

Figure 6

Below you will find the Route Choice function used in this example. For more info how to define your own custom Route Choice functions, check Cost Functions – Aimsun Next Users Manual.
					import math 
def rcf( context, manager, origin, destination, pathsRC, pathsOD, pathsAPA, indexPath ): 
    # get the vehicle type name from GKFunctionCostContext and for Trucks 
    if context.getVehicle().getName() == "Truck": 
        print("indexPath: "+str(indexPath)+", vehicle: "+str(context.getVehicle().getName()) + ", origin: "+ str(origin.getId()) +", destination: "+str(destination.getId())+ ", pathsRC: "+str(len(pathsRC))+", pathsOD: "+str(len(pathsOD))+", pathsAPA: "+str(len(pathsAPA)) ) 
        # exclude all RC and APA file routes. The range of indexPath is 0 to the sum of the length of pathRC, pathOD, and pathAPA lists.  
        if indexPath < len(pathsRC) or indexPath>=len(pathsRC)+len(pathsOD): 
            return 0 
        indexPathOD = indexPath-len(pathsRC) 
        # number of the OD Routes 
        numPaths = len(pathsOD) 
        # path to assess 
        pIP = pathsOD[indexPathOD] 
        # calculate cost of the current path 
        costIP = -pIP.getSPCurrentCost(manager, context.userClass.getDTAVehicleType())/3600.0 
        # iterate through all paths except the current path 
        for j in range(numPaths): 
            if j!=indexPathOD: 
                # calculate cost of the rest of the paths 
                costJ = -pathsOD[j].getSPCurrentCost(manager, context.userClass.getDTAVehicleType())/3600.0 
                # examine if the new cost is greater than the cost of the main path 
                if costJ < costIP: 
                    # if yes, there is another path with lower cost, so this path should get a probability of 0 
                    return 0 
        # there is no other path with lower cost, so this path must be chosen by all trucks (probability of 1) 
        return 1 
    # for the rest of the vehicle types (Car), apply a logit as in the base scenario 
        # set the scale factor equal to the scale factor in the base scenario 
        scaleFactor = 4 
        numPaths = len(pathsRC) 
        if indexPath<numPaths: 
            aux = 0 
            pIP = pathsRC[indexPath] 
            # calculate cost of the current path 
            costIP = -pIP.getSPCurrentCost(manager, context.userClass.getDTAVehicleType())/3600.0 
            # iterate through all paths except the current path 
            for j in range(numPaths): 
                if j!=indexPath: 
                    # Calculate cost of the rest of the paths 
                    costJ = -pathsRC[j].getSPCurrentCost(manager, context.userClass.getDTAVehicleType())/3600.0 
                    # Apply the logit function 
                    aux = aux + math.exp((costIP-costJ)*scaleFactor) 
            # Calculate probabilities 
            prob = 1.0/(1.0+aux) 
            return prob 
            return 0 

To enable the Route Choice function in the DTA:

  1. Open Dynamic Experiment.
  2. Go to Dynamic Traffic Assignment Tab.
  3. In Stochastic Route Choice Model, select the option: User-Defined.
  4. Select the Parameters Tab.
  5. In Available Functions select the “Route Choice function”.

Note that in the Fixed Routes window, the Following OD Routes percentage for the Trucks should be set to 0%, otherwise Trucks with that percentage will follow the % assigned in the OD matrix (in this example: 1%-1%-1%).

Figure 7 shows how to enable the usage of the Route Choice function.

Figure 7

Check how trucks will be assigned to the route with the least cost among the 3 designated OD Routes available in case of an incident on the motorway.

Figure 8 shows how rerouting of trucks to alternative designated OD Routes can reduce the queue length significantly and anticipate hazardous traffic conditions on the network.

Figure 8

Once the simulation is terminated, you can check in detail the Path Assignment result in the Replication > Path Assignment Tab.
  • Got a question? Get in touch.

    We are here to help!


Cite Aimsun Next

Aimsun Next 24

Aimsun (2024). Aimsun Next 24 User’s Manual, Aimsun Next Version 24.0.0, Barcelona, Spain. Accessed on: April. 16, 2024. [Online].


Aimsun Next 24

@manual {AimsunManual,
title = {Aimsun Next 24 User’s Manual},
author = {Aimsun},
edition = {Aimsun Next 24.0.0},
address = {Barcelona, Spain},
year = {2024. [Online]},
month = {Accessed on: Month, Day, Year},
url = {},

Aimsun Next 24

T1 – Aimsun Next 24 User’s Manual
A1 – Aimsun
ET – Aimsun Next Version 24.0.0
Y1 – 2024
Y2 – Accessed on: Month, Day, Year
CY – Barcelona, Spain
PB – Aimsun
UR – [In software]. Available: