Skip to content

Introduce aux efficiency field aux_eff for FC and RES, deprecate Conv alt_eff - #304

Open
kylecarow wants to merge 12 commits into
fastsim-3from
f3/aux-efficiency
Open

Introduce aux efficiency field aux_eff for FC and RES, deprecate Conv alt_eff#304
kylecarow wants to merge 12 commits into
fastsim-3from
f3/aux-efficiency

Conversation

@kylecarow

@kylecarow kylecarow commented Jul 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Resolves #286

Build upon PR #279 (thus related to #287). PR starts at a3b0320

This PR:

  • Introduces new Option fields for the FC and RES (where aux load actually comes from) rather than using alt_eff at the powertrain level (which introduces problems for
    • this AuxEfficiency comes with all the standard efficiency range and value checks that PR Reusable code for component efficiencies #279 introduces
    • slightly refined the macro from that PR to add a From impl to easily create constant-efficiency instances
      • could also and a From<Ratio<64>> method as well
  • plumbs up FC aux_eff to replace alt_eff for conventional vehicles
  • plumbs up RES aux_eff to account for aux load efficiency from batteries (e.g. DC:DC conversion, etc.)
  • deprecates alt_eff
    • allows it to still be read, parsed into aux_eff if its not set, and emitting appropriate warnings
    • no longer serialized, defaults to 1.0 (100%) when not provided (i.e. for newly serialized vehicles)

Modeling improvements:

  • All conventional vehicles no longer require an alternator efficiency, instead it is handled by the optional FC aux_eff
  • HEV/PHEV/BEV can now account for DC:DC conversion, or extra losses for aux load on top of battery efficiency
  • HEVs can apply aux load to FC and RES with diffferent efficiencies
  • FCEVs when implemented can have None for the aux_eff for fuelconverters, which is more fitting than having a powertrain-level parameter that impacts FC and RES. They still will have no aux load directly supplied by the FC, only the RES, which we can check at runtime Tracking issue for fuel cell electric vehicles #270

@kylecarow kylecarow mentioned this pull request Jul 21, 2026
Open
3 tasks
@kylecarow

kylecarow commented Jul 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

TODO: Move Default impl into impl_efficiency_enum! and remove existing AuxSupplyEfficiency default impl

This will make all efficiencies default to constant 100% if not provided in the yaml, which will be useful if we add efficiencies to components in the future that don't currently have them

Done

@kylecarow
kylecarow requested a review from Copilot July 30, 2026 01:42
Copilot AI reviewed Jul 30, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR introduces a component-level auxiliary-load efficiency model (aux_supply_eff) for the FuelConverter and ReversibleEnergyStorage, deprecates the conventional-vehicle alt_eff field, and updates serialization/resources accordingly. It also includes Python API additions (Plotly-based cycle plotting), pytest configuration changes, and a substantial documentation restructure/build pipeline tightening.

Changes:

  • Add AuxSupplyEfficiency and plumb aux_supply_eff into FC/RES initialization + aux-load power accounting (Conv/BEV shown in diff), while deprecating alt_eff.
  • Update vehicle YAML resources to include aux_supply_eff (and remove alt_eff where applicable).
  • Add Plotly plotting to the Python Cycle API, tighten docs build (--strict), and rework docs content/layout + pytest defaults.

Reviewed changes

Copilot reviewed 154 out of 181 changed files in this pull request and generated 9 comments.

Show a summary per file
File Description
python/fastsim/fastsim.pyi Update Python type stubs (Cycle plotting API).
python/fastsim/init.py Add Plotly-based Cycle.plot() helper and wire it onto the Cycle type.
pyproject.toml Add Plotly dep; expand test deps and set pytest defaults; adjust pixi tasks.
fastsim-core/src/vehicle/vehicle_model/fastsim2_interface.rs Map Fastsim2 alt_eff interop to new aux efficiency representation; update RES efficiency enum name usage.
fastsim-core/src/vehicle/vehicle_model.rs Introduce AuxSupplyEfficiency enum and export via vehicle module.
fastsim-core/src/vehicle/powertrain/fuel_converter.rs Add aux_supply_eff field to FuelConverter + validation and fastsim2 conversion.
fastsim-core/src/vehicle/mod.rs Re-export AuxSupplyEfficiency.
fastsim-core/src/vehicle/hev.rs Remove (comment out) debug eprintln! output in init checks.
fastsim-core/src/vehicle/conv.rs Deprecate alt_eff, warn on use, and switch aux-load demand to use fc.aux_supply_eff.
fastsim-core/src/vehicle/bev.rs Apply res.aux_supply_eff to aux-load demand.
fastsim-core/src/utils/interp.rs Add InterpolatorScanValues helpers for validating interpolator value ranges.
fastsim-core/src/simdrive/mod.rs Rename Python-exposed SimDrive.reset_py to reset.
fastsim-core/src/macros.rs Expand impl_efficiency_enum! macro to include Default/From and extra validation logic.
fastsim-core/resources/vehicles/2022_Renault_Zoe_ZE50_R135.yaml Add aux_supply_eff to RES in bundled vehicle resource.
fastsim-core/resources/vehicles/2016_TOYOTA_Prius_Two.yaml Add aux_supply_eff to RES and FC in bundled vehicle resource.
fastsim-core/resources/vehicles/2012_Ford_Fusion.yaml Add aux_supply_eff to FC and remove serialized alt_eff in bundled vehicle resource.
docs/requirements.txt Remove legacy docs requirements file.
docs/myst.yml Restructure documentation TOC and content layout.
docs/demos_to_notebooks.py Remove legacy demo script ↔ notebook conversion utility.
docs/demo_scripts/vehicle_controls/demo_trace_miss.py Remove legacy demo script.
docs/demo_scripts/vehicle_controls/demo_microtrips.py Remove legacy demo script.
docs/demo_scripts/vehicle_controls/demo_maneuver_intro.py Remove legacy demo script.
docs/demo_scripts/vehicle_controls/demo_eco_cruise.py Remove legacy demo script.
docs/demo_scripts/vehicle_controls/demo_dfco.py Remove legacy demo script.
docs/demo_scripts/vehicle_controls/demo_cruise_and_coast.py Remove legacy demo script.
docs/demo_scripts/vehicle_controls/demo_coast_with_grade.py Remove legacy demo script.
docs/demo_scripts/vehicle_controls/demo_basic_coasting.py Remove legacy demo script.
docs/demo_scripts/vehicle_controls/demo_advanced_coasting.py Remove legacy demo script.
docs/demo_scripts/thermal/demo_hev_thrml_ws_wa.py Remove legacy thermal demo script.
docs/demo_scripts/thermal/demo_hev_thrml_ws_ca.py Remove legacy thermal demo script.
docs/demo_scripts/thermal/demo_hev_thrml_cs_ca.py Remove legacy thermal demo script.
docs/demo_scripts/thermal/demo_bev_thrml_ws_wa.py Remove legacy thermal demo script.
docs/demo_scripts/thermal/demo_bev_thrml_ws_ca.py Remove legacy thermal demo script.
docs/demo_scripts/thermal/demo_bev_thrml_cs_ca.py Remove legacy thermal demo script.
docs/demo_scripts/test_demos.py Remove legacy demo test runner.
docs/demo_scripts/powertrains/demo_conv.py Remove legacy demo script.
docs/demo_scripts/powertrains/demo_bev.py Remove legacy demo script.
docs/demo_scripts/getting_started/demo_getting_started.py Remove legacy getting-started demo script.
docs/demo_notebooks/vehicle_controls/demo_microtrips.ipynb Remove legacy generated demo notebook.
docs/demo_notebooks/vehicle_controls/demo_eco_cruise.ipynb Remove legacy generated demo notebook.
docs/demo_notebooks/vehicle_controls/demo_cruise_and_coast.ipynb Remove legacy generated demo notebook.
docs/demo_notebooks/vehicle_controls/demo_coast_with_grade.ipynb Remove legacy generated demo notebook.
docs/demo_notebooks/vehicle_controls/demo_basic_coasting.ipynb Remove legacy generated demo notebook.
docs/demo_notebooks/vehicle_controls/demo_advanced_coasting.ipynb Remove legacy generated demo notebook.
docs/demo_notebooks/thermal/demo_hev_thrml_ws_wa.ipynb Remove legacy generated thermal notebook.
docs/demo_notebooks/thermal/demo_hev_thrml_ws_ca.ipynb Remove legacy generated thermal notebook.
docs/demo_notebooks/thermal/demo_hev_thrml_cs_ca.ipynb Remove legacy generated thermal notebook.
docs/demo_notebooks/thermal/demo_bev_thrml_ws_wa.ipynb Remove legacy generated thermal notebook.
docs/demo_notebooks/thermal/demo_bev_thrml_ws_ca.ipynb Remove legacy generated thermal notebook.
docs/demo_notebooks/thermal/demo_bev_thrml_cs_ca.ipynb Remove legacy generated thermal notebook.
docs/content/vehicle-model.md Remove placeholder doc page.
docs/content/user-guide/running-simulations/label-fe.ipynb Add new (placeholder) notebook page for label fuel economy.
docs/content/user-guide/drive-cycles/telematics.md Add new telematics guidance page.
docs/content/release-process.md Remove placeholder doc page.
docs/content/overview/what-is-fastsim.md Add new overview page (placeholder).
docs/content/label-fe.md Remove placeholder doc page (replaced by notebook).
docs/content/intro.md Update intro page and links to new doc structure.
docs/content/installation.md Update installation instructions and internal links.
docs/content/how-to-update.md Remove old docs update instructions (replaced by developers docs).
docs/content/editing-sim-params.md Remove placeholder doc page.
docs/content/developers/updating-docs.md Add new docs update instructions aligned with pixi/jupyter-book v2.
docs/content/developers/making-releases.md Add new release process page.
docs/content/developers/environment-setup.md Add new environment setup guide.
docs/content/developers/compiling-from-source.md Add new build-from-source instructions.
docs/content/developers.md Remove legacy developer page.
docs/content/custom-vehicles.md Remove placeholder doc page.
docs/content/custom-cycles.md Remove placeholder doc page.
docs/content/compilation-from-source.md Remove placeholder doc page.
cal_and_val/f3-vehicles/Toyota Mirai.yaml Add aux_supply_eff fields for RES/FC in calibration vehicle YAML.
cal_and_val/f3-vehicles/Toyota Hilux Double Cab 4WD.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/Toyota Etios Liva diesel.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/Toyota Corolla Cross Hybrid.yaml Add RES/FC aux_supply_eff (incl. non-1.0 example).
cal_and_val/f3-vehicles/Renault Megane 1.5 dCi Authentique.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/Renault Clio IV diesel.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/Regional Delivery Class 8 Truck.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/Nissan Navara.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/Maruti Swift 4cyl 2WD.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/Line Haul Conv.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/Class 4 Truck (Isuzu NPR HD).yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/BYD ATTO 3.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/Bajaj Boxer 150.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2024 Volkswagen Polo 1.0 MPI.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2024 VinFast VF e34.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2024 Toyota Vios 1.5 G.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2024 BYD Dolphin Active.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2023 Volvo C40 Recharge.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2023 Polestar 2 Long range Dual motor.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2023 Mitsubishi Pajero Sport.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2022 Volvo XC40 Recharge twin.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2022 Toyota Yaris Hybrid Mid.yaml Add RES/FC aux_supply_eff (incl. non-1.0 example).
cal_and_val/f3-vehicles/2022 Toyota RAV4 Hybrid LE.yaml Add RES/FC aux_supply_eff (incl. non-1.0 example).
cal_and_val/f3-vehicles/2022 Tesla Model Y RWD.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2022 Tesla Model 3 RWD.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2022 Renault Zoe ZE50 R135.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2022 Renault Megane E-Tech.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2022 MINI Cooper SE Hardtop 2 door.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2022 Ford F-150 Lightning 4WD.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2021 Peugot 3008.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2021 Honda N-Box G.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2021 Fiat Panda Mild Hybrid.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2021 Cupra Born.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2021 BMW iX xDrive40.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2020 VW Golf 2.0TDI.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2020 VW Golf 1.5TSI.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2020 Hero Splendor+ 100cc.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2020 Chevrolet Colorado 2WD Diesel.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2017 Toyota Highlander 3.5 L.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2017 Prius Prime.yaml Add RES/FC aux_supply_eff.
cal_and_val/f3-vehicles/2017 Maruti Dzire VDI.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2017 CHEVROLET Bolt.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2016 Toyota Prius Two FWD.yaml Add RES/FC aux_supply_eff.
cal_and_val/f3-vehicles/2016 TOYOTA Highlander Hybrid.yaml Add RES/FC aux_supply_eff.
cal_and_val/f3-vehicles/2016 TOYOTA Corolla 4cyl 2WD.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2016 TOYOTA Camry 4cyl 2WD.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2016 TESLA Model S60 2WD.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2016 Nissan Leaf 30 kWh.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2016 MITSUBISHI i-MiEV.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2016 Leaf 24 kWh.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2016 KIA Optima Hybrid.yaml Add RES/FC aux_supply_eff.
cal_and_val/f3-vehicles/2016 Hyundai Tucson Fuel Cell.yaml Add RES/FC aux_supply_eff.
cal_and_val/f3-vehicles/2016 HYUNDAI Sonata PHEV.yaml Add RES/FC aux_supply_eff.
cal_and_val/f3-vehicles/2016 HYUNDAI Elantra 4cyl 2WD.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2016 FORD Explorer 4cyl 2WD.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2016 FORD Escape 4cyl 2WD.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2016 FORD C-MAX HEV.yaml Add RES/FC aux_supply_eff.
cal_and_val/f3-vehicles/2016 FORD C-MAX (PHEV).yaml Add RES/FC aux_supply_eff.
cal_and_val/f3-vehicles/2016 CHEVROLET Volt.yaml Add RES/FC aux_supply_eff.
cal_and_val/f3-vehicles/2016 CHEVROLET Spark EV.yaml Add RES aux_supply_eff.
cal_and_val/f3-vehicles/2016 CHEVROLET Malibu 4cyl 2WD.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2016 BMW i3 REx PHEV.yaml Add RES/FC aux_supply_eff.
cal_and_val/f3-vehicles/2016 BMW 328d 4cyl 2WD.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2016 AUDI A3 4cyl 2WD.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2012 Ford Fusion.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2012 Ford Focus.yaml Add FC aux_supply_eff; remove serialized alt_eff.
cal_and_val/f3-vehicles/2010 Mazda 3 i-Stop.yaml Add FC aux_supply_eff; remove serialized alt_eff.
.github/workflows/deploy_docs.yaml Switch docs build to --strict in deploy workflow.
Comments suppressed due to low confidence (1)

fastsim-core/src/simdrive/mod.rs:56

  • Renaming the Python-exposed method from reset_py to reset is a breaking API change for existing Python users, and there is no compatibility alias. Consider keeping reset_py as a deprecated alias so downstream code keeps working while migrating.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread fastsim-core/src/vehicle/conv.rs
Comment thread fastsim-core/src/vehicle/conv.rs
Comment thread python/fastsim/fastsim.pyi Outdated
Comment thread pyproject.toml Outdated
Comment thread docs/content/intro.md Outdated
Comment on lines +27 to +29
- [](overview/what-is-fastsim.md): what the tool is and how it models vehicles
- [](installation.md): install with pip or build from source
- [](getting-started.ipynb): load a vehicle, run a simulation, inspect results
Comment thread docs/content/user-guide/drive-cycles/telematics.md Outdated
Comment thread docs/content/developers/environment-setup.md Outdated
Comment thread docs/content/developers/making-releases.md
Comment thread docs/content/user-guide/drive-cycles/telematics.md Outdated
@@ -0,0 +1,27 @@
# Using Telematics Data

Instead of using predefined regulatory drive cycles, we often wish to simulate vehicle models over real-world vehicle telematics data in order to validate vehicles models or exercise them in representative scenarios.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Refactor alt_eff to be a FuelConverter/ReversibleEnergyStorage level aux load efficiency penalty

2 participants

@kylecarow