> ## Documentation Index
> Fetch the complete documentation index at: https://docs.models.dunsky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# eFleet methodology

> Understand eFleet energy and cost calculations, annual vehicle replacement decisions, fleet limits, and the interpretation of its Excel outputs.

eFleet compares fleet replacement strategies using vehicle purchases, energy consumption, maintenance, emissions costs, and model penalties. It produces vehicle replacement plans and annual fleet results.

## Choose a workflow

Use [models.dunsky.com](https://models.dunsky.com) for the **EV Fleet** workflow. Follow the [platform run guide](https://docs.models.dunsky.com/quickstart.md) to configure a run and retrieve its results.

For local execution, install the eFleet package and run:

```bash theme={null}
efleet --input-file "inputs.xlsx" --output-folder "./outputs"
```

## What the model represents

A **fleet need** is one vehicle service requirement: its region, facility, subtype, annual distance, idle hours, and initial vehicle. Replacement options describe ICE, BEV, and PHEV technologies for that subtype.

| Strategy | Interpretation |
| - | - |
| Keep All | Retain the starting vehicles; provides the reference calculations |
| Replace In-Kind | Evaluate replacements using each initial vehicle’s powertrain |
| Optimal | Evaluate available powertrains and select annual purchases by positive cost reduction |

“Optimal” is the output label for a sequential, greedy annual selection. It is not a guarantee of the globally lowest-cost fleet schedule across all years and vehicles.

## Prepare the input workbook

| Worksheet | Content |
| - | - |
| `Inputs` | Start year, end year, horizon, and PHEV replacement-cycle setting |
| `Annual Inputs` | Annual whole-fleet and subtype replacement percentages |
| `Global Data` | Regional fuel/electricity prices, emissions intensities, and carbon prices |
| `Vehicle Specs` | Retirement age and mileage, efficiencies, battery sizes, and powertrain specifications |
| `EV Availability` | First availability year for BEV and PHEV options |
| `Maintenance Costs` | ICE and electric maintenance costs per distance |
| `Replacement Costs (ICE)`, `Replacement Costs (BEV)`, `Replacement Costs (PHEV)` | Purchase costs by year and subtype |
| `Basic Fleet Info` | Fleet needs, initial vehicles, annual usage, idling, and per-vehicle early-replacement permission |

Keep distance, energy, fuel, price, and emissions units consistent. Regional prices and intensities fall back to the `all` region when the regional series is unavailable.

### Time horizon

Let $s$ be `StartYear`, $H$ be `Horizon`, and $A_{\max}$ be the largest retirement age.

* Annual replacement decisions iterate over $s,\ldots,H-1$.
* Cost and energy arrays extend through $H+A_{\max}$, inclusive.
* Input validation requires the relevant time series to cover $H+A_{\max}+1$.
* `EndYear` is also used by the penalty calculation for ICE vehicles continuing after that year.

The cost comparison sums annual values without a discount factor. It should not be interpreted as a discounted net-present-value calculation.

## Calculate energy consumption

Let $D$ be annual distance, $I$ annual idle hours, and $N$ working days. Daily distance is $d=D/N$, and daily idle hours are $i=I/N$.

### ICE vehicles

With driving fuel intensity $f_d$ and idle fuel intensity $f_i$:

$$
F_{\mathrm{ICE}}=D f_d+I f_i
$$

### Battery-electric vehicles

With driving electricity intensity $e_d$ and idle electricity intensity $e_i$:

$$
E_{\mathrm{BEV}}=D e_d+I e_i
$$

The usage calculation assigns the whole distance to electricity. It assumes recharging can supply the required energy; battery range does not constrain BEV service feasibility in this calculation.

### Plug-in hybrid vehicles

If one battery cycle covers the day’s driving and idling, the PHEV uses electricity only. Otherwise, electricity use is capped at one daily battery cycle and the remaining driving distance uses fuel:

$$
d_e=\frac{B-i e_i}{e_d},
\qquad
F_{\mathrm{PHEV}}=N(d-d_e)f_d,
\qquad
E_{\mathrm{PHEV}}=NB
$$

Here $B$ is battery energy capacity. The partially electric branch assumes positive battery capacity; idling is supplied electrically. Use physically consistent inputs so idling does not exceed the available battery energy.

## Calculate annual costs and emissions

For annual fuel use $F$, electricity use $E$, and year-specific energy prices $p_{f,t}$ and $p_{e,t}$:

$$
C_{\mathrm{energy},t}=F p_{f,t}+E p_{e,t}
$$

The Excel field **Fuel Costs** includes both purchased fuel and electricity.

If emissions intensities $g_{f,t}$ and $g_{e,t}$ are expressed in grams of CO₂-equivalent per fuel unit and per kWh:

$$
G_t=\frac{F g_{f,t}+E g_{e,t}}{10^6},
\qquad
C_{\mathrm{GHG},t}=G_t p_{\mathrm{carbon},t}
$$

$G_t$ is in tonnes. The code applies the $10^6$ conversion directly, so the emissions inputs must match that convention.

ICE and BEV maintenance costs equal annual distance times their respective maintenance cost per distance. PHEV maintenance uses a distance-weighted blend of electric and ICE maintenance rates.

### Cash costs and model penalties

The selection calculation compares:

$$
J=\sum_t
\left(
C_{\mathrm{capital},t}
+C_{\mathrm{energy},t}
+C_{\mathrm{maintenance},t}
+C_{\mathrm{GHG},t}
+P_t
\right)
$$

$P_t$ is a model penalty used to encourage replacement when age or mileage thresholds are exceeded and to penalize continued ICE use after the configured end year. It is not a cash expenditure. Review **Penalty Costs** separately when interpreting financial results.

## Select annual replacements

For each decision year:

1. Evaluate the available replacement options for each fleet need. EV availability years and the permitted number of PHEV purchases restrict the options.
2. Keep the option with the largest positive reduction in summed costs.
3. Rank the fleet needs by that reduction, largest first.
4. Select purchases within the whole-fleet and subtype limits. If early replacement is disabled for a vehicle, it must be eligible for retirement.
5. Carry the selected decisions into the next year.

### Replacement limits

Percentages are converted to counts using the number of fleet needs:

$$
L_{\mathrm{fleet},t}
=\operatorname{round}\left(\frac{p_{\mathrm{fleet},t}}{100}n_{\mathrm{fleet}}\right)
$$

Whole-fleet limits use rounding. For a subtype, a strictly positive fractional count below one is raised to one; a zero count stays zero. The whole-fleet cap still applies.

Retirement eligibility considers both initial vehicle age and mileage. Subsequent replacement cycles use the smaller of retirement age and the floored mileage-based life.

## Worked energy and operating-cost example

The following values are illustrative assumptions, not recommended defaults.

| Assumption | ICE | BEV |
| - | -: | -: |
| Annual distance | 20,000 km | 20,000 km |
| Annual idling | 100 h | 100 h |
| Driving energy intensity | 0.08 L/km | 0.20 kWh/km |
| Idle energy intensity | 1 L/h | 1 kWh/h |
| Energy price | \$1.80/L | \$0.15/kWh |
| Emissions intensity | 2,300 g/L | 30 g/kWh |
| Maintenance | \$0.10/km | \$0.06/km |

At a carbon price of \$100/t, the annual calculations are:

| Result | ICE | BEV |
| - | -: | -: |
| Energy | 1,700 L | 4,100 kWh |
| Energy cost | \$3,060 | \$615 |
| Maintenance cost | \$2,000 | \$1,200 |
| Emissions | 3.91 t | 0.123 t |
| Emissions cost | \$391 | \$12.30 |
| Operating and emissions cost | \$5,451 | \$1,827.30 |

The BEV reduces those annual costs by **\$3,623.70**. This comparison excludes vehicle purchases and model penalties; it does not determine a replacement year on its own.

## Interpret the Excel outputs

| Worksheet | Interpretation |
| - | - |
| Fleet Needs | Vehicle needs and derived usage information |
| In-Kind Replacement Plan | Purchases under the same-powertrain strategy |
| Optimal Replacement Plan | Selected replacement years, technologies, and purchase costs |
| Replacement Strategy Summary | Annual capital, energy, maintenance, emissions, and penalty values |
| Facility Charging | Annual electricity aggregated by facility, not an hourly load profile or charger kW requirement |
| TCO Comparison | Purchase-year comparison over a vehicle’s retirement life; excludes the model’s replacement penalties |

TCO comparison values and annual strategy costs answer different questions. Do not treat the lowest single-vehicle TCO as a complete fleet replacement schedule.

## Assumptions and interpretation limits

* Annual distance, idle hours, and technology efficiency determine energy use. Energy prices and emissions intensities vary by year.
* The annual purchase ranking does not solve a joint, globally optimal fleet scheduling problem.
* BEV range, charger availability, depot capacity, and hourly charging schedules are not feasibility constraints in the usage calculation.
* Workbook runs currently use 250 working days; supplying `WorkingDays` does not override that value. Direct `FleetNeed` construction can use another value.
* Discounting is not applied in the annual strategy comparison or the TCO export.
* **Optimal** and **TCO Comparison** should be interpreted alongside model penalties, replacement caps, and vehicle service assumptions.

## Implementation and validation

The `efleet` command uses `run.py` and `fleet_results.py`. The separate `efleet_old` command uses the older implementation.

| Calculation | Implementation | Related tests |
| - | - | - |
| Workbook loading | [inputs.py](https://github.com/dunsky-consulting/packages/blob/91234a66599b059bf32072e24c861c9cde5c49c2/efleet/src/efleet/inputs.py) | Input and backward-compatibility tests |
| Energy, maintenance, emissions | [fleet\_results.py](https://github.com/dunsky-consulting/packages/blob/91234a66599b059bf32072e24c861c9cde5c49c2/efleet/src/efleet/fleet_results.py) | `test_calc_usage_costs.py` |
| Annual selection and limits | [fleet\_results.py](https://github.com/dunsky-consulting/packages/blob/91234a66599b059bf32072e24c861c9cde5c49c2/efleet/src/efleet/fleet_results.py) | `test_calc_savings.py`, `test_replacement_limits.py` |
| Penalties and retirement | [fleet\_results.py](https://github.com/dunsky-consulting/packages/blob/91234a66599b059bf32072e24c861c9cde5c49c2/efleet/src/efleet/fleet_results.py) | `test_calc_penalty.py` |
| Workbook exports and TCO | [outputs.py](https://github.com/dunsky-consulting/packages/blob/91234a66599b059bf32072e24c861c9cde5c49c2/efleet/src/efleet/outputs.py) | Output calculations and review against strategy results |

[Source package and installation guide](https://github.com/dunsky-consulting/packages/blob/91234a66599b059bf32072e24c861c9cde5c49c2/efleet/README.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.