Active vehicle penalty

Active vehicle penalty¶

settings.active_vehicle_penalty is an optional penalty on the optimiser's raw cost. It penalises every compiled vehicle that serves at least one Job, so the optimiser prefers to pack work onto fewer vehicles (and, in reset multi-shift, fewer Shifts).

It is not a hard cap on fleet size. Time windows, capacity, Shift bounds, and unserved Jobs still win.

Omit it, set null, or set 0 to leave it off (the default). The value must be a finite number greater than or equal to zero.

The same penalty is added in every optimisation_objective (time, distance, and cost). It is not scaled by costs.hour, by cents, or by the unserved-Job coefficient.

The extra is a lump per active compiled vehicle:

extra = active_vehicle_penalty × (compiled vehicles with ≥ 1 Job)

One Job and fifty Jobs on the same vehicle cost the same. An unused vehicle, including a reset Shift with depot deadhead and no Jobs, contributes 0.

This is not a penalty on used time on later Shifts. For that, see Later shift usage penalty. The two extras add if both are set.

{
  "settings": {
    "optimisation_objective": "time",
    "active_vehicle_penalty": 3600
  }
}

How to choose a value¶

The number is how much extra driving you will accept to leave one vehicle off, not a function of how many Jobs you have.

In time mode, the number is extra driving seconds. 3600 means one hour of extra driving to save one vehicle. 1 is one second — noise.

Ask: how much extra driving will I accept to not turn another vehicle on?

`active_vehicle_penalty`	Extra driving you accept to save one vehicle
`300`	5 minutes (weak)
`1800`	30 minutes
`3600`	1 hour
`14400`	4 hours (strong pack)

Start at 1800 or 3600. Step up if the fleet still splits too readily; stop if tours get ugly or Jobs start looking expensive next to unserved.

Retune when you change optimisation_objective. Distance and cost use the same addend in raw cost units: in distance mode 3600 is metres, not seconds.

Do not copy values from Later shift usage penalty. That table is 0.02–0.1; this one is hundreds to thousands.

Single-day (ordinary) requests¶

Each Driver is one compiled vehicle. The penalty is paid once if that Driver serves at least one Job.

Two Drivers who both work pay twice the penalty, even if they start at the same time. Packing both Jobs onto one Driver saves one lump.

Multi-shift with `mode = reset`¶

Each Shift is compiled as its own vehicle. The penalty is paid once per Shift that has at least one Job.

Monday and Thursday both working is two lumps. Moving Thursday's Jobs onto Monday (when they fit) saves one lump. An unused Thursday Shift is free.

Multi-shift with `mode = continue`¶

The Driver is one compiled vehicle for the whole journey. The penalty is paid once if that Driver serves at least one Job anywhere in the horizon — not once per calendar day.

Monday and Friday on the same Driver is still one lump. Continue does not use this field to drop later days on a Driver who is already working; use Later shift usage penalty for that.

See Multi-Shift.

Stacking with `costs.run`¶

In optimisation_objective: cost, costs.run also penalises an active compiled vehicle (ordinary and continue: once per Driver; reset: once per Shift).

If both are set, both fire. They are not the same unit. costs.run is the money to send the vehicle out (and is scaled for the cost objective). active_vehicle_penalty is an unscaled packing preference, the same raw number as in time and distance mode.

Leave one at 0 if you only want one of those effects. Do not try to equate 3600 with a dollar costs.run.

Stacking with later shift usage¶

A reset Thursday Shift that actually works pays both: this lump for turning that compiled vehicle on, and later_shift_usage_penalty on used time that day.

This field: whether the vehicle or reset Shift is on.
Later shift usage: how much leftover time you burned on a late Shift.

If Thursday is unused, both extras are 0 for that Shift.

Active vehicle penalty