Physical Bounds and Model Caveats

Physical Bounds and Model Caveats#

The models in the RouteE Powertrain library are statistical fits, not physical simulations. They are good at what they were fit to and can be wrong outside it. This page attempts to make clear where the boundaries are and how to exercise caution when using the models.

Know what these models can and cannot do#

The random forest, CNN and NGBoost models were trained on simulated (FASTSim) energy over short road links: roughly 0.01 to 0.5 miles with most average speeds falling between 5 to 70 mph. Outside that range, above all on links longer than half a mile, a prediction is extrapolation and can be incorrect.

Trip totals over real road links are reliable. Individual link predictions are noisier, and they are not guaranteed to obey physics. On a single link a model may charge less for a climb than the height gained, return more energy on a descent than the hill contains, or price a hill and its return leg below flat ground.

CNN models read the previous four links of a trip. Give them whole trips in driving order. A lone link, or a trip with links shuffled or missing, is not the input they were trained on.

Run routee-powertrain validate-physics <model> to see which physical checks a specific model passes on a synthetic sweep of links.

The output guardrail#

Since 2.1.0, Model.predict clips every link's energy to a physical ceiling before returning it: the energy needed to lift the vehicle up the link's rise, bring it to the link's speed once, and push it against rolling and aerodynamic resistance over the link's length, plus an accessory draw for the time the link takes. For a fuel target it also clips at zero: burned fuel does not return to the tank.

The vehicle constants behind the ceiling are deliberately generous (a heavy rolling resistance, a large drag area, a poor driveline), so it is a bound on any plausible vehicle rather than an estimate for this one. It is the same ceiling validate-physics reports as absolute_ceiling.

What it does not do#

  • It does not fix the learned function. A climb can still cost less than its potential energy, a hill can still be cheaper than flat ground, and a BEV model can still return more on a descent than the hill held.

  • It needs a vehicle mass (vehicle.mass_lbs in the metadata, or a mass feature), a speed feature, a distance in a recognised length (miles, kilometers or meters) and a target in a recognised energy unit. When any is missing the prediction passes through unchanged, with a warning saying which one — many published models carry no mass, and filling in mass_lbs turns the guardrail on.

  • It applies to Model.predict and to lookup tables. A consumer that runs the estimator binary itself gets raw output.

Turning it off#

The contract.output_guardrail field in metadata.json takes two values: "envelope" (the default, and what every model published before the field existed loads as) or "none". Set it at training time on the ModelConfig for an estimator whose outputs are bounded by construction, or at runtime:

model = pt.load_model("chevrolet/bolt_bev/2017/rf_base_fe510e40")
model.metadata.contract.output_guardrail = "none"

Raw output, with neither the clamp nor the adjustment factor, is one call away:

raw = model.estimator.predict(links_df, model.metadata.config)

And the band itself is public, so a caller can see where the clamp would bind:

floor, ceiling = pt.physical_bounds(links_df, model.metadata.config)["electric_kwh"]

The floor is the validation floor described above; the guardrail applies only the ceiling, and zero for fuel.

Contents