Route Consumption

Route consumption calculation is a beta feature which allows the consumption of fuel to be calculated for a given, already calculated route.

Vehicles have a limited range depending on the amount of fuel remaining and how much fuel the vehicle consumes per kilometre under different driving conditions. This is especially important for electric vehicles, which can typically travel less distance on a full charge than a gasoline powered vehicle could travel on a full tank.

To ensure that a vehicle is able to complete a calculated route, SDK for iOS can calculate the consumption for each element in that route given certain consumption parameters. This allows the developer to, firstly, determine how much fuel the vehicle will have left at the end of the route and, secondly, check where vehicle would run out of fuel in case if the final destination is not reachable.

Since different vehicles consume different types of fuel (such as gasoline and electricity) and also have different rates of consumption, the consumption calculation must be configured with consumption parameters for a given vehicle before the calculation is performed.

An important concept for consumption calculation is the capacity unit. The capacity unit is how fuel is measured for a given vehicle. Because consumption calculation is general, the unit is effectively defined by the developer. For an electric vehicle the capacity unit is generally kilowatt hours (kWh), for a gasoline powered vehicle it could be liters of gasoline.

A vehicle will have a maximum capacity and current capacity, which indicates how much fuel it can hold in total and the current amount respectively.

In the following description we will assume that we are calculating consumption for an electric vehicle since this is the most common use case. The capacity unit used will be kilowatt hours (kWh).

The consumption parameters are grouped onto the NMARouteConsumptionParameters class. The API documentation provides descriptions of each of the individual values that can be modified. Here we will describe the more complex and important values. To begin with, we'll create an empty consumption parameters object.

NMARouteConsumptionParamters *consumptionParams = [[NMARouteConsumptionParameters alloc] init];

The speed consumption table is the basis for most of the consumption calculation. It is stored in consumptionSpeed property. The table represents consumption of the vehicle per metre in kilowatt hours (the capacity unit) for ranges of speeds.

Consider a very simple example with three ranges of speeds and a consumption for each.

From this table we see that our vehicle consumes 38.82 kWh of capacity per metre when travelling between 0 and 30 km/h, 18.20 kWh of capacity per metre when travelling between 31 and 90 km/h, and 27.41 kWh of capacity per metre when travelling at 90 km/h or faster. Of course, this example is very simple, a real world speed consumption table would have finer grained values.

To use this table in our consumption parameters, we set consumptionSpeed property using the upper bound of each range as the key and the consumption per metre as the value. The final range (for > 90 km/h) should use the key 250.

consumptionParams.consumptionSpeed = @{ @(30):  @(38.82),
          @(90):  @(18.20),
          @(250): @(27.41) };

The speed consumption table is enough to calculate simplistic consumption for a route, so let's look at how to do that. Let's assume that we already have an NMARoute object called route which contains a calculated route. Now let's calculate the consumption for this route.

NMARouteConsumption *consumption =
  [route consumptionWithParameters:consumptionParams
          dynamicPenalty:nil];

Once we have the route consumption, we can determine the last reachable position on the same route given current capacity of our vehicle. In this example we'll suppose that our vehicle has 100,000 kWh of remaining capacity at the beginning of the route.

NMAGeoCoordinates *lastPosition =
  [route lastReachablePositionWithConsumption:consumption
                currentCapacity:100000];

The variable lastPosition will now contain the last point that our vehicle will be able to reach before the capacity reaches zero. In case if the final destination of the route is reachable, lastPosition will be nil.

We can also use route consumption to obtain the consumption for each route element that comprise the route itself. The following code snippet prints out the starting and ending geo-coordinates for each route element as well as the consumption for that route element.

[route.routeElements enumerateObjectsUsingBlock:^(NMARouteElement *element, NSUInteger idx, BOOL *stop) {
    if (idx >= [consumption firstAvailableConsumptionIndex] && [element.geometry count] > 0) {
      NSInteger elementConsumption = [consumption getConsumptionWithIndex:idx];
      NSLog(@"Route element (%.4f, %.4f) --> (%.4f, %.4f) consumption: %zd",
          element.geometry.firstObject.latitude, element.geometry.firstObject.longitude,
          element.geometry.lastObject.latitude, element.geometry.lastObject.longitude,
          consumption);
    }
  }];

As mentioned above, setting only consumptionSpeed property is sufficient for basic consumption calculation. There are more specialised values which can be set to more closely model the consumption of a real vehicle across different road and traffic conditions. For more details on these properties please see the API documentation.