FASTSim 2 to FASTSim 3 Migration Guide

FASTSim 3 is the newest version of FASTSim. This guide is for existing FASTSim 2 users migrating to FASTSim 3.

You will learn how to:

• Install and import FASTSim 3

• Load vehicles and drive cycles (including converting your existing FASTSim 2 vehicle files)

• Run simulations

• Read scalar parameters and time-series results

• Modify vehicle parameters

• Identify name and path changes for FASTSim vehicle fields, with provided FASTSim 2 to FASTSim 3 reference guide mapping FASTSim 2 fields to their FASTSim 3 counterparts

What Changed?¶

The biggest change is how vehicle data is stored:

• FASTSim 2 used a flat structure - every parameter (fc_max_kw, ess_max_kwh, mc_max_kw, …) was a top-level attribute on the Vehicle object, and every powertrain field existed on every vehicle regardless of whether it applied (e.g. conventional vehicles still had a battery field).

• FASTSim 3 uses a nested hierarchical structure where each vehicle only contains the fields relevant to its powertrain (Conv, HEV, PHEV, or BEV). Combining incompatible fields (e.g. a conventional vehicle with a battery) is now impossible. This allows for safer, clearer data handling.

Other important differences:

• SI units are baked into field names (_watts, _joules, _kilograms, _meters, _seconds). This means some variable units have been updated (no more kW or mph units), and all variables now have clear and uniformly labeled units.

• Simulation results are accessed via to_dataframe() and to_dict() rather than as direct array attributes on the SimDrive object.

• Method to modify vehicle attributes has changed. Modifying a field now requires first changing to a dict, modifying, then changing back.

• Configurable save intervals (set_save_interval) - disabling per-step recording gives roughly a 10× speedup and decreased memory usage.

• Thermal modeling (cabin, HVAC, battery, engine) is now supported.

Quick Reference¶

The table below covers common FASTSim actions.

Installation and Imports¶

FASTSim 3 is installed the same way as FASTSim 2:

pip install fastsim

The top-level import is unchanged, but many classes have moved to the fastsim root namespace (they used to live in submodules like fastsim.vehicle and fastsim.simdrive):

Loading Vehicles¶

FASTSim 2 used YAML resource files, custom CSV files, or integer database IDs (from_vehdb(10)). FASTSim 3 uses named YAML resources, customized YAML files, or a YAML vehicle database accessible through from_vehdb() (see more in Loading Vehicle Files).

Converting a FASTSim 2 vehicle file¶

If you have existing FASTSim 2 vehicle YAMLs, use Vehicle.from_file to load them directly as FASTSim 3 vehicles. This is the same function to load regular FASTSim 3 vehicle YAML files, and will automatically detect and read in both FASTSim 2 and FASTSim 3 vehicle files. You can then re-serialize them as FASTSim 3 YAMLs (via veh.to_file(...)) for future use.

Note that not every FASTSim 2 field has a 1-to-1 match in FASTSim 3. See the Field-Mapping Reference tables at the end of this guide for details on how FASTSim 2 vehicle parameters line up with FASTSim 3 parameters.

How to read a FASTSim 2 vehicle into FASTSim 3:

veh_from_f2 = fsim.Vehicle.from_file("fastsim_2_vehicle.yaml")

Then, save it to a FASTSim 3 vehicle YAML file for future use:

veh_from_f2.to_file("converted_vehicle.yaml")

Reading Vehicle Parameters¶

In FASTSim 2 you accessed parameters as flat attributes on the Vehicle object:

# FASTSim 2
veh.fc_max_kw          # 130.5
veh.ess_max_kwh        # not applicable - 0.0 for conventional
veh.drag_coef          # 0.393
veh.veh_kg             # 1644

In FASTSim 3 the recommended approach is to call to_dict(flatten=True), which returns a flat dict whose keys use dot-separated paths matching the nested vehicle structure. See the Field-Mapping Reference section of this guide for a list of FASTSim 2 vehicle variables and their corresponding FASTSim 3 variable paths/names, since in many cases both paths to variables and names have been updated.

For quick inspection, FASTSim 3 exposes convenience attributes for the main powertrain components:

• veh.fc - fuel converter (Conv, HEV, PHEV)

• veh.res - reversible energy storage / battery (HEV, PHEV, BEV)

• veh.em - electric machine / motor (HEV, PHEV, BEV)

Unit updates¶

FASTSim 3 field names always include the unit as a suffix, so there is no ambiguity. When translating FASTSim 2 code, remember to convert:

NOTE: for FASTSim 2 vehicles converted into FASTSim 3 vehicles using Vehicle.from_file, these updates happen automatically.

Modifying Vehicle Parameters¶

In FASTSim 2, you could assign values to variables directly:

# FASTSim 2
veh.fc_max_kw = 150
veh.drag_coef = 0.30

In FASTSim 3, Vehicle objects are immutable from Python. To modify a field, convert to a nested Python dictionary, modify, and then convert back:

1. d = veh.to_dict(flatten=False) - convert to nested dict

2. Edit d

3. veh = fsim.Vehicle.from_dict(d) - convert back to a FASTSim 3 Vehicle

Loading a Drive Cycle¶

In FASTSim 2, cycles in FASTSim resources and custom cycles were loaded using from_file:

resource_cyc = fsim.cycle.Cycle.from_file("udds") # loading a cycle from resource
custom_cyc = fsim.cycle.Cycle.from_file("path/to/custom_cycle.csv") # loading a custom cycle from a file

FASTSim 3 uses separate from_resource / from_file methods to load cycles, similar to how vehicles are loaded. You can use list_resources to view the cycles available in FASTSim resources:

Cycles can also be loaded from file:

cyc = fsim.Cycle.from_file("custom_cycle.csv")

Running a Simulation¶

Four things changed:

1. Class name: fsim.SimDrive (was fsim.simdrive.SimDrive)

2. Argument order: SimDrive(veh, cyc) (was SimDrive(cyc, veh) -- order of inputs switched)

3. Run method: sd.run() (was sd.sim_drive())

4. Save intervals: configurable using set_save_interval (not configurable in FASTSim 2)

FASTSim 3 lets you configure how much time-series data is recorded via set_save_interval (see below). Saving less time-series data (or setting to None) allows for faster simulation when detailed time-series results aren’t needed.

FASTSim 2 always recorded every time step. FASTSim 3 lets you trade time-series detail for speed:

• veh.set_save_interval(1) - record every step (default; needed for time-series plots).

• veh.set_save_interval(n) - record every n-th step.

• veh.set_save_interval(None) - disable per-step recording entirely. About 10× faster than FASTSim 2. Cumulative totals from sd.to_dict(flatten=True) are still available.

Use None for parameter sweeps, large batch runs, and other applications where you only need aggregate results.

Reading Simulation Results¶

FASTSim 2 exposed results as array attributes on the SimDrive object:

# FASTSim 2
sd.mph_ach              # numpy array of achieved speeds (mph)
sd.fc_kw_in_ach         # numpy array of fuel power in (kW)
sd.fc_kw_out_ach        # numpy array of fuel power out (kW)
sd.fs_kwh_out_ach[-1]   # total fuel energy consumed (kWh)
sd.soc                  # state of charge (for HEV/PHEV/BEV)

FASTSim 3 exposes results through two methods on SimDrive:

• sd.to_dataframe() - returns a Polars DataFrame (pass pandas=True for pandas). Recommended for accessing time series data. Column names are dot-separated paths mirroring the vehicle hierarchy.

• sd.to_dict(flatten=True) - returns a flat dict. Used to access cumulative end-of-simulation totals which live under *.state.*. Available even when set_save_interval(None) is used.

Updating Result Paths¶

Common FASTSim 2 result attributes and their FASTSim 3 equivalents:

Replace <Conv|HEV|PHEV|BEV> with the actual powertrain variant returned by veh.veh_type().

Field-Mapping Reference Guide¶

The tables below map every FASTSim 2 Vehicle field to its FASTSim 3 equivalent. FASTSim 3 paths are the keys returned by veh.to_dict(flatten=True). Paths with <variant> change based on the powertrain type: Conv, HEV, PHEV, or BEV.

Vehicle top-level attributes¶

Present in all powertrain types.

Chassis¶

Present in all powertrain types. Fields live under chassis.*.

Fuel storage¶

Present in: Conv, HEV, PHEV. Not present in: BEV.

Fuel converter¶

Present in: Conv, HEV, PHEV. Not present in: BEV.

Reversible energy storage (battery)¶

Present in: HEV, PHEV, BEV. Not present in: Conv.

Electric machine (motor)¶

Present in: HEV, PHEV, BEV. Not present in: Conv.

Transmission, aux loads, HEV controls¶

Transmission (all powertrain types):

Auxiliary loads:

HEV / PHEV powertrain controls (present on HEV, PHEV):

The FASTSim 2 acceleration SOC-buffer fields are replaced by six RGWDB tuning fields (all under pt_type.<variant>.pt_cntrl.RGWDB.*). Each buffer is defined by a reference speed (at which the buffer reaches its full size) and a coefficient that scales the buffer magnitude:

Validation reference values (val_udds_mpgge, val_hwy_mpgge, val_comb_mpgge, val0_to60_mph, val_range_miles, …) are not carried over to FASTSim 3.