R3 Simulation Spec

Release 3 Scenario Content

This document outlines a schema for the scenario payload (content) for the given release.

Schema (v3)

{
  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,
      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
      }
    }
  ],
  traffic?: { // optional section which defaults traffic_level to "default" if omitted
    traffic_level?: string,
    global?: [ // no global traffic if omitted
       {
          multiplier: float or number, # multiplier must be bigger than 0 and smaller than 1
          start_time: string, // "DAY:HH:MM" timestamp
          end_time: string // "DAY:HH:MM" timestamp
       }
    ]
  },
}

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.
4. If traffic provided, the field traffic_level must be one of the following strings: "default", "no_traffic", "low_congestion", "medium_congestion" or "high_congestion".
5. There can be multiple scheduled global traffic events, but they cannot overlap each other.

R3 Simulation Payload (needs to be updated)

interface R3Payload {
  simId: string
  headquarters: {
    position: [number, number]
  }
  tasks: {
    id: number
    stationId: number
    state: 'scheduled' | 'open' | 'assigned' | 'inprogress' | 'inservice' | 'closed'
    assignedDriverId: number | null
  }
  stations: {
    id: number
    name: string
    position: [number, number]
    taskIds: number[]
  }
  drivers: {
    id: number
    name: string
    position: [number, number]
    taskIds: number[]
    route?: {
      coordinates: [number, number][]
      trafficRanges: [
        startCoordinateIndex: number
        endCoordinateIndex: number
        congestionLevel: string
      ]
    }
    state:
      | 'off_shift'
      | 'pending_shift'
      | 'on_route'
      | 'servicing_station'
      | 'on_break'
      | 'idle'
      | 'seeking_hq_for_inventory'
      | 'restocking'
      | 'ending_shift'
    shift: {
      start_time: number
      end_time: number
      lunch_break?: number 
    }
    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
    batteryCapacity: number
  }
  clock: {
    simSecondsPassed: number
    simMinutesPassed: number
    realSecondsPassed: number
    realMinutesPassed: number
    startTime: number
    running: bool
    realTimeFactor: number
    pausedByUser: bool
  }
  reporting: { // more reports will be added
    servicingToDrivingRatio: number
    vehicleUtilizationRatio: number
    averageTasksServicedPerShift: number
    averageTaskResponseTime: number
  }
}