README.md · routee-powertrain-model-library

1	`---`
2	`license: bsd-3-clause`
3	`pipeline_tag: tabular-regression`
4	`library_name: routee-powertrain`
5	`tags:`
6	`- onnx`
7	`- joblib`
8	`- energy`
9	`- transportation`
10	`- mobility`
11	`- vehicle-energy-consumption`
12	`- routee`
13	`- random-forest`
14	`- ngboost`
15	`---`
16
17	`# RouteE-Powertrain Model Library`
18
19	`Pre-trained mesoscopic vehicle energy prediction models: given link-level driving`
20	`conditions (speed, road grade, turn angle, …) they predict how much energy a specific`
21	`vehicle consumes traversing that link. They are the model catalog behind`
22	`[routee-powertrain](https://github.com/NatLabRockies/routee-powertrain) and are`
23	`consumed by routing engines such as`
24	`[routee-compass](https://github.com/NREL/routee-compass) to compute energy-aware`
25	`routes.`
26
27	`- 282 models covering 74 vehicle configurations across 25 makes`
28	`- Powertrains: ICE, HEV, BEV, PHEV (both charge-depleting and charge-sustaining`
29	`modes), and generic Class-8 heavy duty`
30	`- Format: ONNX (random forest, 266 models) and joblib (NGBoost probabilistic,`
31	`16 models)`
32	`- Maintained by the National Laboratory of the Rockies`
33
34	`## Quickstart`
35
36	```bash
37	`pip install routee.powertrain`
38	```
39
40	```python
41	`import pandas as pd`
42	`import routee.powertrain as pt`
43
44	`# This repo is the default registry — no configuration needed.`
45	`print(pt.query_available_models(make="tesla", model="model 3"))`
46
47	`model = pt.load_model("tesla/model_3_bev/2022/rf_c3326385") # version optional -> latest`
48
49	`links_df = pd.DataFrame({`
50	`"distance": [0.1, 0.2], # miles`
51	`"speed_mph": [30, 55], # mph`
52	`"grade_percent": [-2.0, 1.0], # percent`
53	`})`
54
55	`model.predict(links_df)`
56	`# kwh`
57	`# 0 0.005089`
58	`# 1 0.064848`
59	```
60
61	`print(model)` prints the full input contract — every feature with its units, the
62	`distance column, the target, and the predict method.`
63
64	Downloads go through `huggingface_hub` into the shared HF cache, so repeat loads are
65	`offline. Everything here is public; no token is required.`
66
67	`## Addressing a model`
68
69	`Each model lives at a path that is its identifier:`
70
71	```
72	`v2/<make>/<vehicle_slug>/<year>/<config_slug>/v<N>/`
73	`metadata.json # full model card data: contract, errors, provenance, digest`
74	`model.onnx # or a .joblib blob for NGBoost estimators`
75	`v2/index.json # machine-readable catalog of every model in the repo`
76	```
77
78	- `vehicle_slug` = `<model>_<powertrain_family>` (e.g. `camry_ice`, `bolt_bev`). Both
79	`PHEV modes share one vehicle slug; the mode lives in the config slug.`
80	- `config_slug` = `<architecture>_<variant?>_<feature_hash>` — the same vehicle trained
81	`with a different feature set or variant is a different config, not a different version.`
82	- `v<N>` is a registry coordinate. Omit it and you get the latest.
83
84	`Every path segment is derived from the model's own metadata, so a path and its`
85	`metadata.json` can never disagree — the loader raises if they do.
86
87	`## Catalog`
88
89	`<details>`
90	`<summary><b>ICE</b> — 30 vehicles, 96 models</summary>`
91
92	`\| Path prefix \| Description \| Target \| Configs \|`
93	`\| --- \| --- \| --- \| --- \|`
94	\| `audi/a3_ice/2016` \| 2016_AUDI_A3_4cyl_2WD trained July 2024 \| gde \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
95	\| `bmw/328d_ice/2016` \| 2016_BMW_328d_4cyl_2WD trained July 2024 \| gde \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
96	\| `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` \|
97	\| `chevrolet/malibu_ice/2016` \| 2016_CHEVROLET_Malibu_4cyl_2WD trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
98	\| `fiat/panda_mild_hybrid_ice/2021` \| 2021_Fiat_Panda_Mild_Hybrid trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
99	\| `ford/escape_ice/2016` \| 2016_FORD_Escape_4cyl_2WD trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
100	\| `ford/explorer_ice/2016` \| 2016_FORD_Explorer_4cyl_2WD trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
101	\| `ford/focus_ice/2012` \| 2012_Ford_Focus trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
102	\| `ford/fusion_ice/2012` \| 2012_Ford_Fusion trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
103	\| `generic_transit/40_foot_diesel_ice/2020-2025` \| Test Vehicle \| gallons \| `rf_793469d3` \|
104	\| `honda/n-box_g_ice/2021` \| 2021_Honda_N-Box_G trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
105	\| `hyundai/elantra_ice/2016` \| 2016_HYUNDAI_Elantra_4cyl_2WD trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
106	\| `maruti/dzire_vdi_ice/2017` \| 2017_Maruti_Dzire_VDI trained July 2024 \| gde \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
107	\| `maruti/swift_ice/2018` \| Maruti_Swift_4cyl_2WD trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
108	\| `mazda/3_i-stop_ice/2010` \| 2010_Mazda_3_i-Stop trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
109	\| `mitsubishi/pajero_sport_ice/2023` \| 2023_Mitsubishi_Pajero_Sport trained July 2024 \| gde \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
110	\| `nissan/navara_ice/2020` \| Nissan_Navara trained July 2024 \| gde \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
111	\| `peugeot/3008_ice/2021` \| 2021_Peugot_3008 trained July 2024 \| gde \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
112	\| `renault/clio_iv_diesel_ice/2016` \| Renault_Clio_IV_diesel trained July 2024 \| gde \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
113	\| `renault/megane_1.5_dci_authentique_ice/2016` \| Renault_Megane_1.5_dCi_Authentique trained July 2024 \| gde \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
114	\| `toyota/avanza_e_j_mt_ice/2022` \| 2022_Toyota_Avanza_E_J_MT trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
115	\| `toyota/camry_ice/2016` \| 2016_TOYOTA_Camry_4cyl_2WD trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
116	\| `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` \|
117	\| `toyota/etios_liva_diesel_ice/2015` \| Toyota_Etios_Liva_diesel trained July 2024 \| gde \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
118	\| `toyota/highlander_3.5_l_ice/2017` \| 2017_Toyota_Highlander_3.5_L trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
119	\| `toyota/hilux_double_cab_ice/2020` \| Toyota_Hilux_Double_Cab_4WD trained July 2024 \| gde \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
120	\| `toyota/vios_1.5_g_ice/2024` \| 2024_Toyota_Vios_1.5_G trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
121	\| `volkswagen/golf_1.5tsi_ice/2020` \| 2020_VW_Golf_1.5TSI trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
122	\| `volkswagen/golf_2.0tdi_ice/2020` \| 2020_VW_Golf_2.0TDI trained July 2024 \| gde \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
123	\| `volkswagen/polo_1.0_mpi_ice/2024` \| 2024_Volkswagen_Polo_1.0_MPI trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
124
125	`</details>`
126
127	`<details>`
128	`<summary><b>HEV</b> — 9 vehicles, 31 models</summary>`
129
130	`\| Path prefix \| Description \| Target \| Configs \|`
131	`\| --- \| --- \| --- \| --- \|`
132	\| `ford/c-max_hev/2016` \| 2016_FORD_C-MAX_HEV trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
133	\| `hyundai/tucson_fuel_cell_hev/2016` \| 2016_Hyundai_Tucson_Fuel_Cell trained July 2024 \| kg_h2 \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
134	\| `kia/optima_hev/2016` \| 2016_KIA_Optima_Hybrid trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
135	\| `toyota/corolla_cross_hev/2022` \| Toyota_Corolla_Cross_Hybrid trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
136	\| `toyota/highlander_hev/2016` \| 2016_TOYOTA_Highlander_Hybrid trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
137	\| `toyota/mirai_hev/2021` \| Toyota_Mirai trained July 2024 \| kg_h2 \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
138	\| `toyota/prius_two_hev/2016` \| 2016_Toyota_Prius_Two_FWD trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
139	\| `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` \|
140	\| `toyota/yaris_hybrid_mid_hev/2022` \| 2022_Toyota_Yaris_Hybrid_Mid trained July 2024 \| gge \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
141
142	`</details>`
143
144	`<details>`
145	`<summary><b>BEV</b> — 22 vehicles, 77 models</summary>`
146
147	`\| Path prefix \| Description \| Target \| Configs \|`
148	`\| --- \| --- \| --- \| --- \|`
149	\| `bmw/ix_xdrive40_bev/2021` \| 2021_BMW_iX_xDrive40 trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
150	\| `byd/atto_3_bev/2022` \| BYD_ATTO_3 trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
151	\| `byd/dolphin_active_bev/2024` \| 2024_BYD_Dolphin_Active trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
152	\| `chevrolet/bolt_bev/2017` \| 2017_CHEVROLET_Bolt trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
153	\| `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` \|
154	\| `chevrolet/spark_bev/2016` \| 2016_CHEVROLET_Spark_EV trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
155	\| `cupra/born_bev/2021` \| 2021_Cupra_Born trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
156	\| `ford/f-150_lightning_bev/2022` \| 2022_Ford_F-150_Lightning_4WD trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
157	\| `generic_transit/40_foot_battery_electric_bev/2020-2025` \| BEB Vehicle \| kWhs \| `rf_793469d3` \|
158	\| `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` \|
159	\| `mitsubishi/i-miev_bev/2016` \| 2016_MITSUBISHI_i-MiEV trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
160	\| `nissan/leaf_24_kwh_bev/2016` \| 2016_Leaf_24_kWh trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
161	\| `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` \|
162	\| `polestar/2_long_range_bev/2023` \| 2023_Polestar_2_Long_range_Dual_motor trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
163	\| `renault/megane_e-tech_bev/2022` \| 2022_Renault_Megane_E-Tech trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
164	\| `renault/zoe_ze50_r135_bev/2022` \| 2022_Renault_Zoe_ZE50_R135 trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
165	\| `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` \|
166	\| `tesla/model_s60_bev/2016` \| 2016_TESLA_Model_S60_2WD trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
167	\| `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` \|
168	\| `vinfast/vf_e34_bev/2024` \| 2024_VinFast_VF_e34 trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
169	\| `volvo/c40_recharge_bev/2023` \| 2023_Volvo_C40_Recharge trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
170	\| `volvo/xc40_recharge_bev/2022` \| 2022_Volvo_XC40_Recharge_twin trained July 2024 \| kwh \| `rf_b80965c8, rf_c3326385, rf_db8522fb` \|
171
172	`</details>`
173
174	`<details>`
175	`<summary><b>PHEV_EV_MODE</b> — 5 vehicles, 15 models</summary>`
176
177	`\| Path prefix \| Description \| Target \| Configs \|`
178	`\| --- \| --- \| --- \| --- \|`
179	\| `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` \|
180	\| `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` \|
181	\| `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` \|
182	\| `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` \|
183	\| `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` \|
184
185	`</details>`
186
187	`<details>`
188	`<summary><b>PHEV_HEV_MODE</b> — 5 vehicles, 15 models</summary>`
189
190	`\| Path prefix \| Description \| Target \| Configs \|`
191	`\| --- \| --- \| --- \| --- \|`
192	\| `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` \|
193	\| `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` \|
194	\| `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` \|
195	\| `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` \|
196	\| `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` \|
197
198	`</details>`
199
200	`<details>`
201	`<summary><b>HEAVY_DUTY</b> — 8 vehicles, 48 models</summary>`
202
203	`\| Path prefix \| Description \| Target \| Configs \|`
204	`\| --- \| --- \| --- \| --- \|`
205	\| `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` \|
206	\| `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` \|
207	\| `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` \|
208	\| `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` \|
209	\| `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` \|
210	\| `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` \|
211	\| `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` \|
212	\| `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` \|
213
214	`</details>`
215
216	`## Inputs and outputs`
217
218	`Inputs — one row per road-network link, as a pandas DataFrame:`
219
220	`\| Column \| Units \| Typical range \|`
221	`\| ---------------- \| -------------------- \| ----------------- \|`
222	\| `distance` \| miles \| — \|
223	\| `speed_mph` \| mph \| 0 – 120 \|
224	\| `grade_percent` \| percent \| -20 – 20 \|
225	\| `turn_angle` \| degrees \| -180 – 180 \|
226	\| `mass_lbs` \| pounds \| heavy duty only \|
227	\| `ambient_temp_f` \| degrees Fahrenheit \| thermal models \|
228
229	`Outputs — energy consumed on each link, in the units the vehicle's fuel implies:`
230
231	`\| Target \| Units \| Used by \|`
232	`\| ------------------ \| -------------------- \| -------------------------------- \|`
233	\| `gge` \| gallons gasoline \| gasoline ICE, HEV, PHEV (CS) \|
234	\| `gde` \| gallons diesel \| diesel ICE, heavy duty \|
235	\| `kwh` \| kilowatt-hours \| BEV, PHEV (CD) \|
236	\| `kg_h2` \| kilograms hydrogen \| fuel-cell vehicles \|
237
238	`Most models are trained on an energy rate (energy per mile) and multiply by`
239	`distance` at predict time; the contract in each model states which.
240
241	`### Real-world adjustment`
242
243	`Predictions are scaled by a powertrain-level factor that corrects laboratory/simulated`
244	`consumption toward observed real-world consumption:`
245
246	`\| Powertrain \| Factor \|`
247	`\| ---------- \| ------ \|`
248	`\| ICE \| 1.166 \|`
249	`\| HEV \| 1.1252 \|`
250	`\| BEV \| 1.3958 \|`
251	`\| PHEV (EV) \| 1.3958 \|`
252	`\| PHEV (HEV) \| 1.1252 \|`
253	`\| Heavy duty \| 1.0 \|`
254
255	Set `apply_real_world_adjustment=False` when training, or divide it back out, if you
256	`want the unadjusted estimate.`
257
258	`## Using the ONNX files directly`
259
260	`You do not need the Python package. Every ONNX graph is self-describing: the`
261	positional input/output contract is embedded in `metadata_props`, so a consumer holding
262	only the `.onnx` file can reconstruct the exact column order.
263
264	\| `metadata_props` key \| Value \|
265	`\| ------------------------ \| ------------------------------------------------------------ \|`
266	\| `routee_input_columns` \| JSON array of `{name, units, dtype}`, positional input order \|
267	\| `routee_output_columns` \| JSON array of `{name, units, dtype}`, positional output order\|
268	\| `routee_predict_method` \| `"rate"` or `"raw"` \|
269	\| `routee_distance_column` \| name of the distance column \|
270
271	```python
272	`import onnxruntime as ort, json`
273	`from huggingface_hub import hf_hub_download`
274
275	`path = hf_hub_download(`
276	`"nreinicke/routee-powertrain-model-library",`
277	`"v2/toyota/camry_ice/2016/rf_c3326385/v1/model.onnx",`
278	`)`
279	`sess = ort.InferenceSession(path)`
280	`meta = sess.get_modelmeta().custom_metadata_map`
281	`cols = [c["name"] for c in json.loads(meta["routee_input_columns"])] # ['speed_mph', 'grade_percent']`
282	```
283
284	`Feed features in that order. Getting the order wrong does not raise — it silently`
285	returns wrong energy. With `predict_method == "rate"`, multiply the output by distance
286	`and apply the real-world factor yourself.`
287
288	`## Evaluation`
289
290	Every model carries its own hold-out test errors under `errors` in `metadata.json`
291	`(RMSE, normalized RMSE, weighted relative percent difference, and net error, at both`
292	`link and trip aggregation). Across the 280 models that report trip-level errors:`
293
294	`\| Powertrain \| Models \| Median trip wRPD \| p90 \| Max \|`
295	`\| -------------- \| ------ \| ---------------- \| ---- \| ---- \|`
296	`\| ICE \| 95 \| 0.09 \| 0.11 \| 0.27 \|`
297	`\| HEV \| 31 \| 0.12 \| 0.15 \| 0.33 \|`
298	`\| Heavy duty \| 48 \| 0.12 \| 0.16 \| 0.19 \|`
299	`\| BEV \| 76 \| 0.18 \| 0.23 \| 0.72 \|`
300	`\| PHEV (EV) \| 15 \| 0.25 \| 0.30 \| 0.32 \|`
301	`\| PHEV (HEV) \| 15 \| 0.16 \| 0.48 \| 0.48 \|`
302	`\| All \| 280 \| 0.13 \| 0.24 \| 0.72 \|`
303
304	`Weighted RPD is reported as a fraction, so 0.13 ≈ 13% typical trip-level error. Median`
305	`absolute net error — total predicted energy vs. total actual across the test set —`
306	`is 1.5% (p90 4.3%), which is the metric that matters for fleet- or corridor-level`
307	`aggregates. Link-level errors are naturally larger (median wRPD 0.40).`
308
309	`## Training data`
310
311	`Models are trained on link-aggregated drive-cycle data: high-frequency GPS or`
312	`telematics traces map-matched to a road network and aggregated per link, paired with`
313	`energy consumption that is either vehicle-reported/measured or simulated with a`
314	`powertrain model such as [NLR FASTSim](https://github.com/NatLabRockies/fastsim).`
315
316	`You can train your own models on the same footing and publish them into a registry of`
317	`this shape — see`
318	`[the training example](https://natlabrockies.github.io/routee-powertrain/examples/model_training_example.html)`
319	`and [publishing a model](https://natlabrockies.github.io/routee-powertrain/publishing_a_model.html).`
320
321	`## Reproducibility`
322
323	- Content identity. Every model carries a `model_digest` (`sha256:…`) computed at
324	`train time over its identity, contract, estimator bytes, and training provenance, plus`
325	an `estimator_sha256` over the exact binary. A corrupt binary raises on load. Resolve a
326	digest back to a path with `pt.query_available_models(model_digest="sha256:…")`.
327	- Pinning. Set `ROUTEE_HF_REVISION` to a commit sha to freeze the entire library —
328	`every model and the index — to an exact state:`
329
330	```bash
331	`export ROUTEE_HF_REVISION=<commit-sha>`
332	```
333
334	`## License`
335
336	`BSD 3-Clause, matching the routee-powertrain package.`
337
338	`## Citation`
339
340	```bibtex
341	`@software{routee_powertrain,`
342	`title = {RouteE-Powertrain},`
343	`author = {{National Laboratory of the Rockies}},`
344	`url = {https://github.com/NatLabRockies/routee-powertrain},`
345	`note = {Model library: https://huggingface.co/nreinicke/routee-powertrain-model-library}`
346	`}`
347	```
348
349	`## Links`
350
351	`- 📦 [routee-powertrain on GitHub](https://github.com/NatLabRockies/routee-powertrain)`
352	`- 📖 [Documentation](https://natlabrockies.github.io/routee-powertrain/)`
353	`- 🐍 [PyPI](https://pypi.org/project/routee.powertrain/)`
354	`- 🧭 [routee-compass](https://github.com/NREL/routee-compass) — energy-aware routing engine`
355