README.md

---
license: bsd-3-clause
pipeline_tag: tabular-regression
library_name: routee-powertrain
tags:
  - onnx
  - joblib
  - energy
  - transportation
  - mobility
  - vehicle-energy-consumption
  - routee
  - random-forest
  - ngboost
---

# 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**](https://github.com/NatLabRockies/routee-powertrain) and are
consumed by routing engines such as
[routee-compass](https://github.com/NREL/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

```bash
pip install routee.powertrain
```

```python
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

<details>
<summary><b>ICE</b> — 30 vehicles, 96 models</summary>

| Path prefix | Description | Target | Configs |
| --- | --- | --- | --- |
| `audi/a3_ice/2016` | 2016_AUDI_A3_4cyl_2WD trained July 2024 | gde | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `bmw/328d_ice/2016` | 2016_BMW_328d_4cyl_2WD trained July 2024 | gde | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `chevrolet/colorado_diesel_ice/2020` | 2020 Chevrolet Colorado 2WD Diesel | gde | `ngb_stochastic_02107a97, ngb_stochastic_940b80b8, ngb_stochastic_aaa9554f, ngb_stochastic_db8522fb, rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `chevrolet/malibu_ice/2016` | 2016_CHEVROLET_Malibu_4cyl_2WD trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `fiat/panda_mild_hybrid_ice/2021` | 2021_Fiat_Panda_Mild_Hybrid trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `ford/escape_ice/2016` | 2016_FORD_Escape_4cyl_2WD trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `ford/explorer_ice/2016` | 2016_FORD_Explorer_4cyl_2WD trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `ford/focus_ice/2012` | 2012_Ford_Focus trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `ford/fusion_ice/2012` | 2012_Ford_Fusion trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `generic_transit/40_foot_diesel_ice/2020-2025` | Test Vehicle | gallons | `rf_793469d3` |
| `honda/n-box_g_ice/2021` | 2021_Honda_N-Box_G trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `hyundai/elantra_ice/2016` | 2016_HYUNDAI_Elantra_4cyl_2WD trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `maruti/dzire_vdi_ice/2017` | 2017_Maruti_Dzire_VDI trained July 2024 | gde | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `maruti/swift_ice/2018` | Maruti_Swift_4cyl_2WD trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `mazda/3_i-stop_ice/2010` | 2010_Mazda_3_i-Stop trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `mitsubishi/pajero_sport_ice/2023` | 2023_Mitsubishi_Pajero_Sport trained July 2024 | gde | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `nissan/navara_ice/2020` | Nissan_Navara trained July 2024 | gde | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `peugeot/3008_ice/2021` | 2021_Peugot_3008 trained July 2024 | gde | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `renault/clio_iv_diesel_ice/2016` | Renault_Clio_IV_diesel trained July 2024 | gde | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `renault/megane_1.5_dci_authentique_ice/2016` | Renault_Megane_1.5_dCi_Authentique trained July 2024 | gde | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `toyota/avanza_e_j_mt_ice/2022` | 2022_Toyota_Avanza_E_J_MT trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `toyota/camry_ice/2016` | 2016_TOYOTA_Camry_4cyl_2WD trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `toyota/corolla_ice/2016` | 2016 Toyota Corolla 4cyl 2WD | gge | `ngb_stochastic_02107a97, ngb_stochastic_940b80b8, ngb_stochastic_aaa9554f, ngb_stochastic_db8522fb, rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `toyota/etios_liva_diesel_ice/2015` | Toyota_Etios_Liva_diesel trained July 2024 | gde | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `toyota/highlander_3.5_l_ice/2017` | 2017_Toyota_Highlander_3.5_L trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `toyota/hilux_double_cab_ice/2020` | Toyota_Hilux_Double_Cab_4WD trained July 2024 | gde | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `toyota/vios_1.5_g_ice/2024` | 2024_Toyota_Vios_1.5_G trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `volkswagen/golf_1.5tsi_ice/2020` | 2020_VW_Golf_1.5TSI trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `volkswagen/golf_2.0tdi_ice/2020` | 2020_VW_Golf_2.0TDI trained July 2024 | gde | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `volkswagen/polo_1.0_mpi_ice/2024` | 2024_Volkswagen_Polo_1.0_MPI trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |

</details>

<details>
<summary><b>HEV</b> — 9 vehicles, 31 models</summary>

| Path prefix | Description | Target | Configs |
| --- | --- | --- | --- |
| `ford/c-max_hev/2016` | 2016_FORD_C-MAX_HEV trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `hyundai/tucson_fuel_cell_hev/2016` | 2016_Hyundai_Tucson_Fuel_Cell trained July 2024 | kg_h2 | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `kia/optima_hev/2016` | 2016_KIA_Optima_Hybrid trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `toyota/corolla_cross_hev/2022` | Toyota_Corolla_Cross_Hybrid trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `toyota/highlander_hev/2016` | 2016_TOYOTA_Highlander_Hybrid trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `toyota/mirai_hev/2021` | Toyota_Mirai trained July 2024 | kg_h2 | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `toyota/prius_two_hev/2016` | 2016_Toyota_Prius_Two_FWD trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `toyota/rav4_hybrid_le_hev/2022` | 2022 Toyota RAV4 Hybrid LE | gge | `ngb_stochastic_02107a97, ngb_stochastic_940b80b8, ngb_stochastic_aaa9554f, ngb_stochastic_db8522fb, rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `toyota/yaris_hybrid_mid_hev/2022` | 2022_Toyota_Yaris_Hybrid_Mid trained July 2024 | gge | `rf_b80965c8, rf_c3326385, rf_db8522fb` |

</details>

<details>
<summary><b>BEV</b> — 22 vehicles, 77 models</summary>

| Path prefix | Description | Target | Configs |
| --- | --- | --- | --- |
| `bmw/ix_xdrive40_bev/2021` | 2021_BMW_iX_xDrive40 trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `byd/atto_3_bev/2022` | BYD_ATTO_3 trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `byd/dolphin_active_bev/2024` | 2024_BYD_Dolphin_Active trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `chevrolet/bolt_bev/2017` | 2017_CHEVROLET_Bolt trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `chevrolet/bolt_bev/2020` | 2020_Chevrolet_Bolt_EV_0F_110F_steady trained July 2025 | kwh | `rf_steady_thermal_856e8a60, rf_steady_thermal_ab1db342, rf_transient_thermal_856e8a60, rf_transient_thermal_ab1db342` |
| `chevrolet/spark_bev/2016` | 2016_CHEVROLET_Spark_EV trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `cupra/born_bev/2021` | 2021_Cupra_Born trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `ford/f-150_lightning_bev/2022` | 2022_Ford_F-150_Lightning_4WD trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `generic_transit/40_foot_battery_electric_bev/2020-2025` | BEB Vehicle | kWhs | `rf_793469d3` |
| `mini/cooper_se_hardtop_2_door_bev/2022` | 2022_MINI_Cooper_SE_Hardtop_2_door trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `mitsubishi/i-miev_bev/2016` | 2016_MITSUBISHI_i-MiEV trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `nissan/leaf_24_kwh_bev/2016` | 2016_Leaf_24_kWh trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `nissan/leaf_30_kwh_bev/2016` | 2016_Nissan_Leaf_30_kWh trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb, rf_steady_thermal_856e8a60, rf_steady_thermal_ab1db342, rf_transient_thermal_856e8a60, rf_transient_thermal_ab1db342` |
| `polestar/2_long_range_bev/2023` | 2023_Polestar_2_Long_range_Dual_motor trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `renault/megane_e-tech_bev/2022` | 2022_Renault_Megane_E-Tech trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `renault/zoe_ze50_r135_bev/2022` | 2022_Renault_Zoe_ZE50_R135 trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `tesla/model_3_bev/2022` | 2022_Tesla_Model_3_RWD trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb, rf_steady_thermal_856e8a60, rf_steady_thermal_ab1db342, rf_transient_thermal_856e8a60, rf_transient_thermal_ab1db342` |
| `tesla/model_s60_bev/2016` | 2016_TESLA_Model_S60_2WD trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `tesla/model_y_bev/2022` | 2022 Tesla Model Y RWD | ess_kwh_out_ach, kwh | `ngb_stochastic_02107a97, ngb_stochastic_940b80b8, ngb_stochastic_aaa9554f, ngb_stochastic_db8522fb, rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `vinfast/vf_e34_bev/2024` | 2024_VinFast_VF_e34 trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `volvo/c40_recharge_bev/2023` | 2023_Volvo_C40_Recharge trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `volvo/xc40_recharge_bev/2022` | 2022_Volvo_XC40_Recharge_twin trained July 2024 | kwh | `rf_b80965c8, rf_c3326385, rf_db8522fb` |

</details>

<details>
<summary><b>PHEV_EV_MODE</b> — 5 vehicles, 15 models</summary>

| Path prefix | Description | Target | Configs |
| --- | --- | --- | --- |
| `bmw/i3_rex_phev/2016` | 2016_BMW_i3_REx_PHEV_Charge_Depleting trained July 2024 | kwh | `rf_charge_depleting_b80965c8, rf_charge_depleting_c3326385, rf_charge_depleting_db8522fb` |
| `chevrolet/volt_phev/2016` | 2016_CHEVROLET_Volt_Charge_Depleting trained July 2024 | kwh | `rf_charge_depleting_b80965c8, rf_charge_depleting_c3326385, rf_charge_depleting_db8522fb` |
| `ford/c-max_phev/2016` | 2016_FORD_C-MAX_(PHEV)_Charge_Depleting trained July 2024 | kwh | `rf_charge_depleting_b80965c8, rf_charge_depleting_c3326385, rf_charge_depleting_db8522fb` |
| `hyundai/sonata_phev/2016` | 2016_HYUNDAI_Sonata_PHEV_Charge_Depleting trained July 2024 | kwh | `rf_charge_depleting_b80965c8, rf_charge_depleting_c3326385, rf_charge_depleting_db8522fb` |
| `toyota/prius_prime_phev/2017` | 2017_Prius_Prime_Charge_Depleting trained July 2024 | kwh | `rf_charge_depleting_b80965c8, rf_charge_depleting_c3326385, rf_charge_depleting_db8522fb` |

</details>

<details>
<summary><b>PHEV_HEV_MODE</b> — 5 vehicles, 15 models</summary>

| Path prefix | Description | Target | Configs |
| --- | --- | --- | --- |
| `bmw/i3_rex_phev/2016` | 2016_BMW_i3_REx_PHEV_Charge_Sustaining trained July 2024 | gge | `rf_charge_sustaining_b80965c8, rf_charge_sustaining_c3326385, rf_charge_sustaining_db8522fb` |
| `chevrolet/volt_phev/2016` | 2016_CHEVROLET_Volt_Charge_Sustaining trained July 2024 | gge | `rf_charge_sustaining_b80965c8, rf_charge_sustaining_c3326385, rf_charge_sustaining_db8522fb` |
| `ford/c-max_phev/2016` | 2016_FORD_C-MAX_(PHEV)_Charge_Sustaining trained July 2024 | gge | `rf_charge_sustaining_b80965c8, rf_charge_sustaining_c3326385, rf_charge_sustaining_db8522fb` |
| `hyundai/sonata_phev/2016` | 2016_HYUNDAI_Sonata_PHEV_Charge_Sustaining trained July 2024 | gge | `rf_charge_sustaining_b80965c8, rf_charge_sustaining_c3326385, rf_charge_sustaining_db8522fb` |
| `toyota/prius_prime_phev/2017` | 2017_Prius_Prime_Charge_Sustaining trained July 2024 | gge | `rf_charge_sustaining_b80965c8, rf_charge_sustaining_c3326385, rf_charge_sustaining_db8522fb` |

</details>

<details>
<summary><b>HEAVY_DUTY</b> — 8 vehicles, 48 models</summary>

| Path prefix | Description | Target | Configs |
| --- | --- | --- | --- |
| `generic_heavy_duty/class_8_daycab_300kw_heavy_duty/2000-2010` | Daycab_old_300kW | gde | `rf_0ae6c8e2, rf_4bf282c6, rf_a1728df5, rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `generic_heavy_duty/class_8_daycab_300kw_heavy_duty/2010-2020` | Daycab_new_300kW | gde | `rf_0ae6c8e2, rf_4bf282c6, rf_a1728df5, rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `generic_heavy_duty/class_8_daycab_400kw_heavy_duty/2000-2010` | Daycab_old_400kW | gde | `rf_0ae6c8e2, rf_4bf282c6, rf_a1728df5, rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `generic_heavy_duty/class_8_daycab_400kw_heavy_duty/2010-2020` | Daycab_new_400kW | gde | `rf_0ae6c8e2, rf_4bf282c6, rf_a1728df5, rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `generic_heavy_duty/class_8_sleeper_300kw_heavy_duty/2000-2010` | Sleeper_old_300kW | gde | `rf_0ae6c8e2, rf_4bf282c6, rf_a1728df5, rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `generic_heavy_duty/class_8_sleeper_300kw_heavy_duty/2010-2020` | Sleeper_new_300kW | gde | `rf_0ae6c8e2, rf_4bf282c6, rf_a1728df5, rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `generic_heavy_duty/class_8_sleeper_400kw_heavy_duty/2000-2010` | Sleeper_old_400kW | gde | `rf_0ae6c8e2, rf_4bf282c6, rf_a1728df5, rf_b80965c8, rf_c3326385, rf_db8522fb` |
| `generic_heavy_duty/class_8_sleeper_400kw_heavy_duty/2010-2020` | Sleeper_new_400kW | gde | `rf_0ae6c8e2, rf_4bf282c6, rf_a1728df5, rf_b80965c8, rf_c3326385, rf_db8522fb` |

</details>

## Inputs and outputs

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

| Column           | Units                | Typical range     |
| ---------------- | -------------------- | ----------------- |
| `distance`       | miles                | —                 |
| `speed_mph`      | mph                  | 0 – 120           |
| `grade_percent`  | percent              | -20 – 20          |
| `turn_angle`     | degrees              | -180 – 180        |
| `mass_lbs`       | pounds               | heavy duty only   |
| `ambient_temp_f` | degrees Fahrenheit   | thermal models    |

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

| Target             | Units                | Used by                          |
| ------------------ | -------------------- | -------------------------------- |
| `gge`              | gallons gasoline     | gasoline ICE, HEV, PHEV (CS)     |
| `gde`              | gallons diesel       | diesel ICE, heavy duty           |
| `kwh`              | kilowatt-hours       | BEV, PHEV (CD)                   |
| `kg_h2`            | kilograms hydrogen   | fuel-cell vehicles               |

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:

| Powertrain | Factor |
| ---------- | ------ |
| ICE        | 1.166  |
| HEV        | 1.1252 |
| BEV        | 1.3958 |
| PHEV (EV)  | 1.3958 |
| PHEV (HEV) | 1.1252 |
| Heavy duty | 1.0    |

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.

| `metadata_props` key     | Value                                                        |
| ------------------------ | ------------------------------------------------------------ |
| `routee_input_columns`   | JSON array of `{name, units, dtype}`, positional input order |
| `routee_output_columns`  | JSON array of `{name, units, dtype}`, positional output order|
| `routee_predict_method`  | `"rate"` or `"raw"`                                          |
| `routee_distance_column` | name of the distance column                                  |

```python
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:

| Powertrain     | Models | Median trip wRPD | p90  | Max  |
| -------------- | ------ | ---------------- | ---- | ---- |
| ICE            | 95     | 0.09             | 0.11 | 0.27 |
| HEV            | 31     | 0.12             | 0.15 | 0.33 |
| Heavy duty     | 48     | 0.12             | 0.16 | 0.19 |
| BEV            | 76     | 0.18             | 0.23 | 0.72 |
| PHEV (EV)      | 15     | 0.25             | 0.30 | 0.32 |
| PHEV (HEV)     | 15     | 0.16             | 0.48 | 0.48 |
| **All**        | 280    | **0.13**         | 0.24 | 0.72 |

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](https://github.com/NatLabRockies/fastsim). 

You can train your own models on the same footing and publish them into a registry of
this shape — see
[the training example](https://natlabrockies.github.io/routee-powertrain/examples/model_training_example.html)
and [publishing a model](https://natlabrockies.github.io/routee-powertrain/publishing_a_model.html).

## 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:

  ```bash
  export ROUTEE_HF_REVISION=<commit-sha>
  ```

## License

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

## Citation

```bibtex
@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](https://github.com/NatLabRockies/routee-powertrain)
- 📖 [Documentation](https://natlabrockies.github.io/routee-powertrain/)
- 🐍 [PyPI](https://pypi.org/project/routee.powertrain/)
- 🧭 [routee-compass](https://github.com/NREL/routee-compass) — energy-aware routing engine