RouteE-Powertrain Model Library

Pre-trained mesoscopic vehicle energy prediction models: given link-level driving conditions (speed, road grade, turn angle, …) they predict how much energy a specific vehicle consumes traversing that link. They are the model catalog behind routee-powertrain and are consumed by routing engines such as routee-compass to compute energy-aware routes.

• 282 models covering 74 vehicle configurations across 25 makes
• Powertrains: ICE, HEV, BEV, PHEV (both charge-depleting and charge-sustaining modes), and generic Class-8 heavy duty
• Format: ONNX (random forest, 266 models) and joblib (NGBoost probabilistic, 16 models)
• Maintained by the National Laboratory of the Rockies

Quickstart

pip install routee.powertrain

import pandas as pd
import routee.powertrain as pt

# This repo is the default registry — no configuration needed.
print(pt.query_available_models(make="tesla", model="model 3"))

model = pt.load_model("tesla/model_3_bev/2022/rf_c3326385")  # version optional -> latest

links_df = pd.DataFrame({
    "distance":      [0.1, 0.2],   # miles
    "speed_mph":     [30, 55],     # mph
    "grade_percent": [-2.0, 1.0],  # percent
})

model.predict(links_df)
#         kwh
# 0  0.005089
# 1  0.064848

print(model) prints the full input contract — every feature with its units, the distance column, the target, and the predict method.

Downloads go through huggingface_hub into the shared HF cache, so repeat loads are offline. Everything here is public; no token is required.

Addressing a model

Each model lives at a path that is its identifier:

v2/<make>/<vehicle_slug>/<year>/<config_slug>/v<N>/
    metadata.json     # full model card data: contract, errors, provenance, digest
    model.onnx        # or a .joblib blob for NGBoost estimators
v2/index.json         # machine-readable catalog of every model in the repo

• vehicle_slug = <model>_<powertrain_family> (e.g. camry_ice, bolt_bev). Both PHEV modes share one vehicle slug; the mode lives in the config slug.
• config_slug = <architecture>_<variant?>_<feature_hash> — the same vehicle trained with a different feature set or variant is a different config, not a different version.
• v<N> is a registry coordinate. Omit it and you get the latest.

Every path segment is derived from the model's own metadata, so a path and its metadata.json can never disagree — the loader raises if they do.

Catalog

Inputs and outputs

Inputs — one row per road-network link, as a pandas DataFrame:

Outputs — energy consumed on each link, in the units the vehicle's fuel implies:

Most models are trained on an energy rate (energy per mile) and multiply by distance at predict time; the contract in each model states which.

Real-world adjustment

Predictions are scaled by a powertrain-level factor that corrects laboratory/simulated consumption toward observed real-world consumption:

Set apply_real_world_adjustment=False when training, or divide it back out, if you want the unadjusted estimate.

Using the ONNX files directly

You do not need the Python package. Every ONNX graph is self-describing: the positional input/output contract is embedded in metadata_props, so a consumer holding only the .onnx file can reconstruct the exact column order.

import onnxruntime as ort, json
from huggingface_hub import hf_hub_download

path = hf_hub_download(
    "nreinicke/routee-powertrain-model-library",
    "v2/toyota/camry_ice/2016/rf_c3326385/v1/model.onnx",
)
sess = ort.InferenceSession(path)
meta = sess.get_modelmeta().custom_metadata_map
cols = [c["name"] for c in json.loads(meta["routee_input_columns"])]  # ['speed_mph', 'grade_percent']

Feed features in that order. Getting the order wrong does not raise — it silently returns wrong energy. With predict_method == "rate", multiply the output by distance and apply the real-world factor yourself.

Evaluation

Every model carries its own hold-out test errors under errors in metadata.json (RMSE, normalized RMSE, weighted relative percent difference, and net error, at both link and trip aggregation). Across the 280 models that report trip-level errors:

Weighted RPD is reported as a fraction, so 0.13 ≈ 13% typical trip-level error. Median absolute net error — total predicted energy vs. total actual across the test set — is 1.5% (p90 4.3%), which is the metric that matters for fleet- or corridor-level aggregates. Link-level errors are naturally larger (median wRPD 0.40).

Training data

Models are trained on link-aggregated drive-cycle data: high-frequency GPS or telematics traces map-matched to a road network and aggregated per link, paired with energy consumption that is either vehicle-reported/measured or simulated with a powertrain model such as NLR FASTSim.

You can train your own models on the same footing and publish them into a registry of this shape — see the training example and publishing a model.

Reproducibility

• Content identity. Every model carries a model_digest (sha256:…) computed at train time over its identity, contract, estimator bytes, and training provenance, plus an estimator_sha256 over the exact binary. A corrupt binary raises on load. Resolve a digest back to a path with pt.query_available_models(model_digest="sha256:…").

• Pinning. Set ROUTEE_HF_REVISION to a commit sha to freeze the entire library — every model and the index — to an exact state:

  export ROUTEE_HF_REVISION=<commit-sha>
  

License

BSD 3-Clause, matching the routee-powertrain package.

Citation

@software{routee_powertrain,
  title  = {RouteE-Powertrain},
  author = {{National Laboratory of the Rockies}},
  url    = {https://github.com/NatLabRockies/routee-powertrain},
  note   = {Model library: https://huggingface.co/nreinicke/routee-powertrain-model-library}
}

Links

• 📦 routee-powertrain on GitHub
• 📖 Documentation
• 🐍 PyPI
• 🧭 routee-compass — energy-aware routing engine