# 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, the 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 the case that 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 being, we'll create an empty consumption parameters object

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

The speed consumption table is the basis for much of the consumption calculation, this is stored in the `consumptionSpeed`

property. The table represents the consumption of the vehicle per meter 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.

Speed range (km/h) | Consumption per meter (kWh) |
---|---|

0 - 30 | 38.82 |

31 - 90 | 18.20 |

> 90 | 27.41 |

From this table, we see that our vehicle consumes 38.82 kWh of capacity per metre when traveling between 0 and 30 km/h, 18.20 kWh of capacity per metre when traveling between 31 and 90 km/h and 27.41 kWh of capacity per metre when traveling 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 the `consumptionSpeed`

property, using the upper bound of each range as the key and the consumption per metre as the value. The final key (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 the case that the final destination of the route is reachable, `lastPosition`

will be `nil`

.

We can also use the 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 the `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.