Duration matrix

By default, the duration of traveling between two locations is calculated using the Haversine formula and factoring the speed of each vehicle. To override this behavior, you can specify a duration matrix in the input that provides the duration of going from location A to B, using the duration_matrix feature.

The duration_matrix is useful when you want to use a different travel duration function, or when you want to use a pre-calculated duration matrix. For example, you may have your own mapping service that provides the travel duration between locations.

There are different ways to specify the duration matrix. Depending on your use case, you can choose between the following options:

• The duration_matrix is an array of arrays of float.
• The duration_matrix can handle time dependent travel times, to model e.g. traffic conditions by providing a matrix or by scaling a default matrix for each time period.
• The duration_matrix can be provided as in the case before but specified for different vehicles. This is useful when you want to model e.g. different vehicles with different speeds (cars and bikes, for example).

Whenever you specify a duration_matrix, you need to make sure that the units for the values are seconds. The matrix must be square, and its size is:

n + 2m

Where:

• n: the number of stops.
• m: the number of vehicles.

If you’re using Nextmv Maps, the max size for the duration matrix is 2,000 x 2,000. If you’re using your own matrix there is no size limit other than the 100 MB file size limit for the input file. The size follows that each float value is the duration in seconds of traveling from location at index i to location at index j. Indices must be given in the following order:

[
  stop-1, ..., stop-n,
  vehicle-1-start-location, vehicle-1-end-location, ..., vehicle-m-start-location, vehicle-m-end-location
]

The matrix may be asymmetric, meaning that the duration of going from location A to B may be different than the duration of going from location B to A.

Here are the examples for the different ways to specify the duration matrix. In this example, the duration to travel from "Fushimi Inari Taisha" to "Kiyomizu-dera" and viceversa is 720 seconds. Vehicle locations are omitted, given that the duration of going to/from them is zero.

A sample output obtained after solving the problem is also shown.

{
  "duration_matrix": [
    [0, 720, 1020, 0, 0],
    [720, 0, 660, 0, 0],
    [1020, 660, 0, 0, 0],
    [0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0]
  ],
  "stops": [
    {
      "id": "Fushimi Inari Taisha",
      "location": { "lon": 135.772695, "lat": 34.967146 }
    },
    {
      "id": "Kiyomizu-dera",
      "location": { "lon": 135.78506, "lat": 34.994857 }
    },
    {
      "id": "Nijō Castle",
      "location": { "lon": 135.748134, "lat": 35.014239 }
    }
  ],
  "vehicles": [
    {
      "id": "v1"
    }
  ]
}