nrel / routee-powertrain

RouteE-Powertrain is a tool for predicting energy usage over a set of road links.

Overview

RouteE-Powertrain is a Python package that allows users to work with a set of pre-trained mesoscopic vehicle energy prediction models for a varity of vehicle types. Additionally, users can train their own models if "ground truth" energy consumption and driving data are available. RouteE-Powertrain models predict vehicle energy consumption over links in a road network, so the features considered for prediction often include traffic speeds, road grade, turns, etc.

The typical user will utilize RouteE's catalog of pre-trained models. Currently, the catalog consists of light-duty vehicle models, including conventional gasoline, diesel, hybrid electric (HEV), plugin hybrid electric (PHEV) and battery electric (BEV). These models can be applied to link-level driving data (in the form of pandas dataframes) to output energy consumption predictions.

Users that wish to train new RouteE models can do so. The model training function of RouteE enables users to use their own drive-cycle data, powertrain modeling system, and road network data to train custom models.

Quickstart

RouteE Powertrain is available on PyPI and can be installed with pip:

pip install pip --upgrade
pip install nrel.routee.powertrain

(For more detailed instructions, see here)

Then, you can import the package and use a pre-trained model from the RouteE model catalog:

import pandas as pd
import nrel.routee.powertrain as pt

# Print the available pre-trained models
print(pt.list_available_models(local=True, external=True))

# [
#   '2016_TOYOTA_Camry_4cyl_2WD',
#   '2017_CHEVROLET_Bolt',
#   '2012_Ford_Focus',
#   ...
# ]

# Load a pre-trained model
model = pt.load_model("2016_TOYOTA_Camry_4cyl_2WD")

# Inspect the model to see what it expects for input
print(model)

# ========================================
# Model Summary
# --------------------
# Vehicle description: 2016_TOYOTA_Camry_4cyl_2WD
# Powertrain type: ICE
# Number of estimators: 2
# ========================================
# Estimator Summary
# --------------------
# Feature: speed_mph (mph)
# Distance: miles (miles)
# Target: gge (gallons_gasoline)
# Raw Predicted Consumption: 29.856 (miles/gallons_gasoline)
# Real World Predicted Consumption: 25.606 (miles/gallons_gasoline)
# ========================================
# Estimator Summary
# --------------------
# Feature: speed_mph (mph)
# Feature: grade_dec (decimal)
# Distance: miles (miles)
# Target: gge (gallons_gasoline)
# Raw Predicted Consumption: 29.845 (miles/gallons_gasoline)
# Real World Predicted Consumption: 25.596 (miles/gallons_gasoline)
# ========================================

# Predict energy consumption for a set of road links
links_df = pd.DataFrame(
    {
        "miles": [0.1, 0.2, 0.3], # miles
        "speed_mph": [30, 40, 50], # mph
        "grade_dec": [-0.05, 0, 0.05], # decimal
    }
)

energy_result = model.predict(links_df)

routee-powertrain's Issues

Add ability to output target variance

Currently, we only output a single energy target in all of our models. To make this more flexible, we could also return some kind of "output metadata" that might include additional information like the variance of predicted energy target.

We should determine the best way to return this to the user. Perhaps it could just be an additional column in a dataframe that gets returned? Something like:

model = pt.load_pretrained_model("ICE")
result = model.predict(my_links_df)

result.head()

index	gallons_gas	variance
0	.05	.005
1	.025	.002
2	.05	.001

Add methods to Model for visualization

We currently have methods to visualize individual features and a combination of features. It would be convenient to add a method on the Model class that calls these functions (maybe using the feature ranges as default). Maybe it would look something like:

import nrel.routee.powertrain as pt

model = pt.load_pretrained_model("ICE")

model.visualize_feature("speed")
model.visualize_feature("grade")
model.contour("speed", "grade")

Where the user just inputs one or more feature names and the code does the work to generate the inputs for producing the plots.

Add API docs

Using sphinx and autodoc, we should add an API docs page to the documentation. Here's an example configuration for the jupyter-book config file:

sphinx:
  extra_extensions:
    - "sphinx.ext.autodoc"
    - "sphinx.ext.napoleon"
    - "sphinx.ext.viewcode"
  config:
    html_theme: sphinx_book_theme
    language: "python"
  html_context:
    default_mode: light

  # Autodoc config reference
  # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
  autodoc_default_options:
    members: true
    member-order: bysource
    private-members: true

Update error computations to support stochastic prediction

Once we have estimators that can provide stochastic energy estimates, we need to update the error metrics for these.

First, we'll need to identify an estimator that is capable of predicting in a stochastic manner. Perhaps the Estimator class should also require a method called prediction_type() that indicates if the model can predict stochastic estimates or not and then our error computation routines can compute different error metrics depending on the prediction type (PredictionType.DETERMINISTIC, PredictionType.STOCHASIC).

Second, we'll need to define a set of error metrics that make sense for the stochastic models. @ShashiKiran07 @jakeholden have you guys developed error metrics we should include here?

Add to_lookup_table function

In older versions of RouteE Powertrain, we had the ability to dump a model to a lookup table. This didn't make it into the 1.0 refactor but we should re-introduce this function on the Model class.

Add constraints to all default models

Now that we have quick methods to do visualization from #21, we should start training our default model library with feature constraints. For example, when building out a model config it might look like this:

feature_set_1 = pt.FeatureSet(
    features=[
        pt.DataColumn(name="speed_mph", units="mph", constraints=pt.Constraints(lower=0, upper=120)),
        pt.DataColumn(name="grade_dec", units="decimal", constraints=pt.Constraints(lower=-0.2, upper=0.2)),
    ] 
)
feature_set_2 = pt.FeatureSet(
    features=[
        pt.DataColumn(name="speed_mph", units="mph", constraints=pt.Constraints(lower=0, upper=120)),
        pt.DataColumn(name="grade_dec", units="decimal", constraints=pt.Constraints(lower=-0.2, upper=0.2)),
        pt.DataColumn(name="road_class", units="category_0_to_5", constraints=pt.Constraints(lower=0, upper=5)),
    ] 
)
distance=pt.DataColumn(name="miles", units="miles")
target=pt.DataColumn(name="gallons_fastsim", units="gallons_gasoline")

Standardize and improve RouteE Metadata

Moved from internal repository.

Right now, RouteE models contain metadata that can be lost when flattening a model into a lookup table. After some discussion, it sounds like it would be a good idea to standardize how metadata is represented in both RouteE models and RouteE lookup tables.

In addition to a standard format, it would also be beneficial to add some more information about where a model came from and how it was trained. Some metadata we could potential add:

• A training dataset tag - we could add a dataset tag so we can determine what dataset was used to train a model
• Real world adjustments tag/coefficients - It would be a good idea to add a tag that indicates whether or not a model has had real world adjustments applied. This is mostly important for lookup tables since the base RouteE models can apply real world adjustments with the apply_real_world_adjustment parameter
• Training dataset stats - it may be beneficial to add some metadata describing the training dataset. This could include stats such as number of cycles, average cycle length, etc.

If anyone has thoughts or potential additions, feel free to leave them here!

Build a trainer for the new NGBoost estimator

Contingent on #16 being completed, we need to build a new Trainer for the NGBoost estimator and implements the inner_train method. See the smartcore_random_forest.py trainer or the sklearn_random_forest.py trainer for an example.

This trainer might take in some arguments like:

• ngboost parameters
• type of distribution

Return multiple energy targets for PHEVs

Right now we model PHEVs with two distinct models:

• a charge depleting model that returns electrical energy and represents the phev operating on battery only
• a charge sustaining model that just returns gasoline energy and represents the phev operating on the gasoline engine.

In order to better capture things like regenerative braking, we should update the charge sustaining model to return both gasoline energy and electrical energy.

Visualization Documentation

We should create some documentation for how to use the visualization functions/script (Something like the batch-trainer README.md). It should detail the following:

• How to setup the visualization config file for running the visualization script (detail what each parameter is, which ones are required, show some examples of a config file)
• How to use the visualization function in a notebook or script. There is already some documentation for the function in docstrings, but perhaps we could add an example of how to use it in a notebook

Add NGBoost Estimator

Add in a new estimator that uses a ngboost model for prediction. This estimator will need to implement all of the required methods from the EstimatorInterface abstract class. The SmartCoreEstimator is a good example of how to do this. The most important method is the predict method.

The new ngboost estimator could take in an argument in its __init__ method (maybe something like sample_energy=False) that indicates whether it should either:

• return a single energy value buy sampling from the predicted distributions or,
• returning the distribution parameters like: mean, standard deviation, etc.

Python 3.12 support

Test if installing and running RouteE Powertrain works with python 3.12. If it does, update the test action and badge. If it doesn't report back here so we can brainstorms ways to make it work.

Powertrain module import issues on install

In installing powertrain for the first time, I ran into some issues with running the notebooks. After cloning the repo and installing the environment + rust per install instructions:

I made sure that powertrain was pip3 installed in both my base and powertrain envs.

base

powertrain conda env

I installed the powertrain scikit in the routee env:

and chose the routee env as my kernel to run. However, trying to run the notebook results in a module not found error.

So, I tried running the same command in a python REPL (activated in the exact same directory as the model_training.ipynb), and it worked just fine:

I believe the issue is due to relative import complications with ipynb specifically. It may be resolved by moving the notebook to a new location, or adding a small path script to the top of the notebook.

Automate documentation building

We can use a github action to automate building and publishing the documentation to a github pages site. Here's an example we can use: https://github.com/NREL/floris/blob/main/.github/workflows/deploy-pages.yaml