Struct RsrDispatch 

pub struct RsrDispatch {
    pub eta_weight: f64,
    pub wrong_direction_penalty: f64,
    pub coincident_car_call_bonus: f64,
    pub load_penalty_coeff: f64,
    pub peak_direction_multiplier: f64,
    pub age_linear_weight: f64,
}

Additive RSR-style cost stack. Lower scores win the Hungarian assignment.

See module docs for the cost shape. All weights default to 0.0 except eta_weight (1.0), giving a baseline that mirrors NearestCarDispatch until terms are opted in.

Weight invariants

Every weight field must be finite and non-negative. The with_* builder methods enforce this with assert!; direct field mutation bypasses the check and is a caller responsibility. A NaN weight propagates through the multiply-add chain and silently collapses every pair’s cost to zero (Rust’s NaN.max(0.0) == 0.0), producing an arbitrary but type-valid assignment from the Hungarian solver — a hard bug to diagnose.

Fields

eta_weight: f64

Weight on travel_time = distance / max_speed (seconds). Default 1.0; raising it shifts the blend toward travel time.

wrong_direction_penalty: f64

Constant added when the candidate stop lies opposite the car’s committed travel direction.

Default 0.0; the Otis RSR lineage uses a large value so any right-direction candidate outranks any wrong-direction one. Ignored for cars in ElevatorPhase::Idle or stopped phases, since an idle car has no committed direction to be opposite to.

coincident_car_call_bonus: f64

Bonus subtracted when the candidate stop is already a car-call inside this car.

Merges the new pickup with an existing dropoff instead of spawning an unrelated trip. Default 0.0. Read from DispatchManifest::car_calls_for.

load_penalty_coeff: f64

Coefficient on a smooth load-fraction penalty (load_penalty_coeff · load_ratio).

Fires for partially loaded cars below the bypass_load_*_pct threshold enforced by pair_can_do_work; lets you prefer emptier cars for new pickups without an on/off cliff. Default 0.0.

peak_direction_multiplier: f64

Multiplier applied to wrong_direction_penalty when the TrafficDetector classifies the current tick as TrafficMode::UpPeak or TrafficMode::DownPeak.

Default 1.0 (mode-agnostic — behaviour identical to pre-peak tuning). Raising it strengthens directional commitment during peaks where a car carrying a lobby-bound load shouldn’t be pulled backwards to grab a new pickup. Off-peak periods keep the unscaled penalty, leaving inter-floor assignments free to reverse cheaply.

Silently reduces to 1.0 when no TrafficDetector resource is installed — tests and custom sims that bypass the auto-install stay unaffected.

age_linear_weight: f64

Coefficient on the linear waiting-age fairness bonus. Each candidate stop’s rank is reduced by age_linear_weight · Σ wait_ticks across waiting riders at the stop, so stops hosting older calls win ties without the quadratic blow-up a squared- wait term would have.

Default 0.0 at new / serde round-trip (keeps single-term mutant tests valid and snapshots backward-compatible); tuned / default ship 0.002, lighter than ETD’s 0.005 because RSR’s wrong-direction penalty and pair_is_useful path guard already handle two starvation patterns that ETD needed the full-strength term for. See the inline comment at tuned() for the harness numbers behind the calibration.

Mirrors the Lim 1983 / Barney–dos Santos 1985 CGC lineage already used in EtdDispatch::age_linear_weight; composes additively with the other penalty-stack terms.

Implementations

impl RsrDispatch

pub const fn new() -> Self

Create a new RsrDispatch with the baseline weights (eta_weight = 1.0, all penalties/bonuses disabled).

This is the additive-composition baseline — every penalty and bonus is zero, so the rank reduces to NearestCarDispatch on distance alone. Useful for tests that want to measure a single term in isolation (RsrDispatch::new().with_wrong_direction_penalty(…)).

For the opinionated “out-of-the-box RSR” configuration used by BuiltinStrategy::Rsr and the playground, use RsrDispatch::default instead. Default ships with the full penalty stack turned on; new() is the empty canvas you build on top of.

pub const fn tuned() -> Self

Return the opinionated tuned configuration — equivalent to Default::default but usable in const contexts.

See RsrDispatch::default for the rationale behind each weight. The tuned stack ships with every penalty/bonus turned on so picking RSR out of the box is strictly richer than NearestCar, not identical to it.

pub fn with_wrong_direction_penalty(self, weight: f64) -> Self

Set the wrong-direction penalty.

Panics

Panics on non-finite or negative weights — a negative penalty would invert the direction ordering, silently preferring wrong-direction candidates.

pub fn with_coincident_car_call_bonus(self, weight: f64) -> Self

Set the coincident-car-call bonus.

Panics

Panics on non-finite or negative weights — the bonus is subtracted, so a negative value would become a penalty.

pub fn with_load_penalty_coeff(self, weight: f64) -> Self

Set the load-penalty coefficient.

Panics

Panics on non-finite or negative weights.

pub fn with_eta_weight(self, weight: f64) -> Self

Set the ETA weight.

Panics

Panics on non-finite or negative weights. Zero is allowed and reduces the strategy to penalty/bonus tiebreaking alone.

pub fn with_age_linear_weight(self, weight: f64) -> Self

Set the linear waiting-age fairness weight. Composes additively with the other penalty/bonus terms; 0.0 disables the term.

Panics

Panics on non-finite or negative weights. A NaN weight would propagate through mul_add and silently collapse the stack; a negative weight would invert the fairness ordering.

pub fn with_peak_direction_multiplier(self, factor: f64) -> Self

Set the peak-direction multiplier.

Panics

Panics on non-finite or sub-1.0 values. A multiplier below 1.0 would weaken the direction penalty during peaks (the opposite of the intent) — explicitly disallowed so a typo doesn’t silently invert the tuning.

Trait Implementations

impl Default for RsrDispatch

fn default() -> Self

The opinionated “pick RSR from the dropdown” configuration.

Defaults to RsrDispatch::tuned — every penalty and bonus turned on with values calibrated to a 20-stop commercial bank. Before this default was tuned, RsrDispatch::default() reduced to the raw NearestCarDispatch baseline: picking “RSR” in the playground produced worse behaviour than picking “Nearest Car” (no direction discipline, no load balancing, no car-call merging). The tuned default fixes that without making any term mandatory — consumers wanting the zero baseline can still call RsrDispatch::new.

impl<'de> Deserialize<'de> for RsrDispatch

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl DispatchStrategy for RsrDispatch

fn rank(&mut self, ctx: &RankContext<'_>) -> Option<f64>

Score the cost of sending car to stop. Lower is better.

fn builtin_id(&self) -> Option<BuiltinStrategy>

If this strategy is a known built-in variant, return it so Simulation::new can stamp the correct BuiltinStrategy into the group’s snapshot identity.

fn snapshot_config(&self) -> Option<String>

Serialize this strategy’s tunable configuration to a string that restore_config can apply to a freshly-instantiated instance.

fn restore_config(&mut self, serialized: &str) -> Result<(), String>

Restore tunable configuration from a string previously produced by snapshot_config on the same strategy variant. Called by crate::snapshot::WorldSnapshot::restore immediately after BuiltinStrategy::instantiate builds the default instance, so the restore writes over the defaults.

fn pre_dispatch( &mut self, _group: &ElevatorGroup, _manifest: &DispatchManifest, _world: &mut World, )

Optional hook called once per group before the assignment pass.

fn prepare_car( &mut self, _car: EntityId, _car_position: f64, _group: &ElevatorGroup, _manifest: &DispatchManifest, _world: &World, )

Optional hook called once per candidate car, before any rank calls for that car in the current pass.

fn fallback( &mut self, _car: EntityId, _car_position: f64, _group: &ElevatorGroup, _manifest: &DispatchManifest, _world: &World, ) -> DispatchDecision

Decide what an idle car should do when no stop was assigned to it.

fn notify_removed(&mut self, _elevator: EntityId)

Notify the strategy that an elevator has been removed.

impl Serialize for RsrDispatch

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.