What is RouteMatrix?

RouteMatrix is a licensed add-on feature for PC*Miler Connect that efficiently calculates travel time and distance between all possible pairs of points in a set of locations. RouteMatrix is a powerful tool for load planning, scheduling and stop optimization that can be used for numerous carrier, shipper and third party logistics applications via their own custom integrations or within third party transportation management systems.

RouteMatrix provides the ability to calculate an N X N trip matrix efficiently by taking advantage of the functionality of multi-processor CPUs by using multiple cores at the same time. It enables users to create a stop list with n number of stops and have a vector of information returned that includes mileage, travel time, and tolls information (if the Tolls add-on is licensed).

RouteMatrix APIs

The following APIs are for use with RouteMatrix:

• PCMSMatrixAddStop adds a stop to the stop list for the trip matrix. If a trip matrix has already been calculated, adding new stops will require a full rerun.
• PCMSMatrixAppendStop appends a stop to the stop list for the trip matrix. Appending a stop will not require a full rerun of the entire trip matrix.
• PCMSMatrixSetOptions sets the routing parameters used when calculating the route for each cell of the matrix.
• PCMSMatrixClear deletes all stops from the trip matrix.
• PCMSMatrixGetStopCount returns the number of stops that are currently part of the trip matrix.
• PCMSMatrixCalculate initiates the calculation of the trip matrix with all of its current stop information.
• PCMSMatrixAddOrigin configures RouteMatrix to only calculate N number of rows, allowing faster transaction times.
• PCMSSetDateOption sets the date option related to the depart time calculation.
• PCMSMatrixSetDepartDayAndTime clears existing depart times and sets the depart time.
• PCMSMatrixAddDepartDayAndTime appends the depart time to existing values.
• PCMSMatrixGetDepartTimeCount returns the count of depart times for the route matrix.
• PCMSMatrixGetCell allows the user to retrieve certain pieces of information from a specific cell in the trip matrix.
• PCMSMatrixGetCell2 allows the user to retrieve certain pieces of information from a specific cell, including the index of the depart times.
• PCMSMatrixSetThreadCount allows the calling application to specify how many threads to use for parallel processing.
• PCMSMatrixSetComputeTollDollars allows the calling application to specify that toll dollars should be generated in the matrix.
• PCMSMatrixSetComputeTollandStateMiles allows the calling application to specify that toll miles by state should be generated in the matrix.
• PCMSGetTravelTimes returns an array of travel times for a trip.
• PCMSMatrixSetMaxAirMiles allows the calling application to specify a maximum airline distance to be used by the PCMSMatrixCalculate in order to decide if it needs to run the route.

Sample Code

The sample code below uses five stops. A formula for converting thousandths of hours to hours and minutes is included below the sample code.

void TestRouteMatrix_UserGuide(PCMServerID server)
{
  // The Lat/Longs for the stops used in each comparison
  const int NUM_STOPS = 5;
  const char* latLongs[] = {
    "35.173099517822266n,107.89029693603516w",
    "35.160099029541016n,103.70149993896484w",
    "35.232200622558594n,97.485397338867188w",
    "34.064998626708984n,81.024497985839844w",
    "43.603099822998047n,96.767799377441406w"
  };

  Trip matTrip = PCMSNewTrip(server);

  // Set up the Matrix Routing options
  PCMSSetCalcType(matTrip, CALC_PRACTICAL);
  PCMSMatrixSetOptions(matTrip);

  // Set the number of threads to be used internally
  PCMSMatrixSetThreadCount(2);

  // Add the stops onto the matrix
  for (int i = 0; i < NUM_STOPS; i++)
  {
    PCMSMatrixAddStop(latLongs[i]);
  }

  // Error check to see if the stops are loaded to the matrix correctly
  long lStopCount = PCMSMatrixGetStopCount();
  if (lStopCount <= 0)
  {
    printf("ERROR: Could not load stops!\n");
  }
  else
  {
    // Calculate the routes
    PCMSMatrixCalculate(NULL);

    // Print the distance results
    for (long i = 0; i < lStopCount; i++)
    {
      for (long j = 0; j < lStopCount; j++)
      {
        char szBuffer[256] = {0};
        PCMSMatrixGetCell(i, j, 0, szBuffer, sizeof(szBuffer));
        printf("%s\t", szBuffer);
      }
      printf("\n");
    }
  }

  // Clear the matrix of all data so that it can be run again
  PCMSMatrixClear();
}

To convert thousandths of hours to hours and minutes, use the following formula:

public int ConvertDurationHours(double duration, out long hours, out long minutes)
{
  // Duration is stored in thousandths of an hour
  bool bLessThan0 = duration < 0;
  duration = bLessThan0 ? -duration : duration;

  double time = (double)(duration) / 1000;

  hours = (int)(time);
  minutes = (int)((60.0 * (time - hours)) + 0.5);
  if (60 == minutes)
  {
    hours++;
    minutes = 0;
  }

  hours = bLessThan0 ? -hours : hours;
  minutes = bLessThan0 ? -minutes : minutes;
  return 0;
}