R2 Simulation Spec

Release 2 Scenario Content

Scenarios are a set of initial conditions and parameters that define how a simulation will "play" against a dispatcher. This document outlines a schema for the scenario payload (content) for the given release.

Schema (v2)

{
  version?: number // defaults to 1
  start_time: string, // "HH:MM" timestamp
  end_time: string, // "HH:MM" timestamp
  vehicle_battery_capacity: number, // probably should have check that it isn't 0
  stations: [
    {
      name: string,
      position: [number, number], // [lon, lat]
      initial_task_count?: number, // defaults to 0
      scheduled_tasks: string[] // list of "DAY:HH:MM" 8601 timestamps
    }
  ],
  vehicles: [
    {
      name: string,
      position?: [number, number] | string, // [lon, lat] or station name - can be omitted
      battery_count?: number // assume 0 if not provided
    }
  ],
  drivers: [
    {
      name: string, // is a name necessary?
      shift: {
        start_time: string, // "DAY:HH:MM" timestamp
        end_time: string, // "DAY:HH:MM" timestamp
        lunch_break?: string, // "DAY:HH:MM" timestamp marking beginning of 30 minute lunch break - can be omitted
      }
    }
  ],
}

Logical constraints

1. There must be at least 1 station, 1 vehicle, 1 driver, and 1 task in any scenario created.
2. There must be as many drivers that are on-shift at simulation start time as there are vehicles with a specified position.
3. No vehicle should have a battery_count that is greater than vehicle_battery_capacity.

Release 2 New Behaviours

The biggest simulation change in release 2 is the separation of resources into distinct driver and vehicle entities. The list below details their behaviour over the course of a running sim:

1. At simulation start, every non-HQ vehicle is assigned a driver whose shift is beginning / has already begun.
2. When a driver's shift ends, they return to HQ, and their vehicle is reassigned to another driver if one is waiting (on-shift) at HQ.
3. When a driver's shift ends, they return to HQ, and their tasks are released as unassigned.
4. When a driver ends their shift, returns to HQ, and releases their vehicle, this vehicle enters "battery refill state" even if immediately assigned to a new driver that had been waiting at HQ.

R2 Simulation Payload

interface R2Payload {
  simId: string
  tasks: {
    id: number
    stationId: number
    state: 'open' | 'assigned' | 'inprogress' | 'closed'
    assignedDriverId: number | null
  }
  stations: {
    id: number
    name: string
    position: [number, number]
    taskIds: number[]
  }
  drivers: {
    id: number
    position: [number, number]
    taskIds: number[]
    route?: {
      coordinates: [number, number][]
    }
    // NEW 'state' attribute
    // not strictly necessary but nice-to-have - wait to see what amby ends up doing for driver state in sim side
    state:
      | 'off_shift'
      | 'on_route'
      | 'servicing_station'
      | 'lunch_break'
      | 'idle'
      | 'ending_shift'
    // NEW 'shift' attribute
    shift: {
      start_time: string // "DAY:HH:MM" timestamp
      end_time: string // "DAY:HH:MM" timestamp
      lunch_break?: string // "DAY:HH:MM" timestamp - might NOT be ommitable if in the end we decide all lunch breaks on sim init / start - tbd.
    }
    inProgressTaskId: number | null
    vehicleId: number | null // null implies at HQ, not on route
  }
  vehicles: {
    id: number
    driverId: number | null // null implies at HQ, not on route
    batteryCount: number
  }
  clock: {
    simSecondsPassed: number
    simMinutesPassed: number
    realSecondsPassed: number
    realMinutesPassed: number
    startTime: number
  }
}