9. API de enrutamiento PILOT (interfaz de enrutamiento)
Contenido:
|
• Modo de resolución
• VRP predeterminado
• Modo de plan
• Aporte
• Trabajos
• Envíos
• Vehículos
• Notas
• matrices
• Producción
• Código
• Resumen
• Rutas
• Ejemplos
• Usando un motor de enrutamiento (OSRM u Openrouteservice)
• Usando matrices personalizadas
• Usando -c para elegir ETA e informar violaciones
|
Notas :
• el orden esperado para todas las matrices de coordenadas es[lon, lat]
• todos los tiempos están en segundos
• todas las distancias están en metros
• un time_window objeto es un par de marcas de tiempo en la forma[start, end]
• Las claves obsoletas están tachadas.
• cost Los valores en la salida son los utilizados en el objetivo de optimización (actualmente igual a duration).
• una "tarea" es un trabajo, una recogida o una entrega
Modo de resolución
VRP predeterminado
El modo de resolución predeterminado toma como entrada la descripción de un problema de generación de rutas para vehículos y genera un conjunto de rutas que coinciden con todas las restricciones.
Modo de plan
Activado mediante -c, este modo tiene como objetivo elegir ETA para todos los pasos de la ruta. Toma el mismo formato de entrada aumentado con una descripción de la ruta esperada para cada vehículo. Todas las restricciones en la entrada se convierten implícitamente en restricciones suaves. El resultado es un conjunto de rutas que coinciden con la descripción esperada y al mismo tiempo minimizan las violaciones de tiempo y reportan todas las violaciones de restricciones.
Aporte
La descripción del problema se lee desde la entrada estándar o desde un archivo (usando -i) y debe tener json un formato válido como se muestra a continuación.
|
Llave
|
Descripción
|
|
jobs
|
conjunto de job objetos que describen los lugares a visitar
|
|
shipments
|
conjunto de shipment objetos que describen tareas de recogida y entrega
|
|
vehicles
|
conjunto de vehicle objetos que describen los vehículos disponibles
|
|
[ matrices]
|
descripción opcional de matrices personalizadas por perfil
|
|
[ matrix]
|
matriz bidimensional opcional que describe una matriz personalizada
| |
Trabajos
Un job objeto tiene las siguientes propiedades:
|
Llave
|
Descripción
|
|
id
|
entero
|
|
[ description]
|
una cadena que describe este trabajo
|
|
[ location]
|
matriz de coordenadas
|
|
[ location_index]
|
índice de fila y columna relevantes en matrices personalizadas
|
|
[ setup]
|
duración de la configuración del trabajo (por defecto 0)
|
|
[ service]
|
duración del servicio de trabajo (por defecto 0)
|
|
[ amount]
|
una matriz de números enteros que describen cantidades multidimensionales
|
|
[ delivery]
|
una matriz de números enteros que describen cantidades multidimensionales para la entrega
|
|
[ pickup]
|
una matriz de números enteros que describen cantidades multidimensionales para recoger
|
|
[ skills]
|
una serie de números enteros que definen habilidades obligatorias
|
|
[ priority]
|
un número entero en el [0, 100]rango que describe el nivel de prioridad (el valor predeterminado es 0)
|
|
[ time_windows]
|
una serie de time_window objetos que describen espacios válidos para el inicio del servicio de trabajo
| |
Se informa un error si dos job objetos tienen el mismo id.
Envíos
Un shipment objeto tiene las siguientes propiedades:
|
Llave
|
Descripción
|
|
pickup
|
un shipment_step objeto que describe la recogida
|
|
delivery
|
un shipment_step objeto que describe la entrega
|
|
[ amount]
|
una matriz de números enteros que describen cantidades multidimensionales
|
|
[ skills]
|
una serie de números enteros que definen habilidades obligatorias
|
|
[ priority]
|
un número entero en el [0, 100]rango que describe el nivel de prioridad (el valor predeterminado es 0)
| |
A shipment_step es similar a un job objeto (excepto las claves compartidas que ya están presentes en shipment):
|
Llave
|
Descripción
|
|
id
|
entero
|
|
[ description]
|
una cadena que describe este paso
|
|
[ location]
|
matriz de coordenadas
|
|
[ location_index]
|
índice de fila y columna relevantes en matrices personalizadas
|
|
[ setup]
|
duración de la configuración de la tarea (por defecto 0)
|
|
[ service]
|
duración del servicio de tarea (por defecto 0)
|
|
[ time_windows]
|
una serie de time_window objetos que describen espacios válidos para el inicio del servicio de tareas
| |
Se informa un error si dos delivery (respectivamente pickup) objetos tienen el mismo valor id.
Vehículos
Un vehicle objeto tiene las siguientes propiedades:
|
Llave
|
Descripción
|
|
id
|
entero
|
|
[ profile]
|
perfil de enrutamiento (por defecto car)
|
|
[ description]
|
una cadena que describe este vehículo
|
|
[ start]
|
matriz de coordenadas
|
|
[ start_index]
|
índice de fila y columna relevantes en matrices personalizadas
|
|
[ end]
|
matriz de coordenadas
|
|
[ end_index]
|
índice de fila y columna relevantes en matrices personalizadas
|
|
[ capacity]
|
una matriz de números enteros que describen cantidades multidimensionales
|
|
[ skills]
|
una serie de números enteros que definen habilidades
|
|
[ time_window]
|
un time_window objeto que describe las horas de trabajo
|
|
[ breaks]
|
una serie de break objetos
|
|
[ speed_factor]
|
un valor doble en el rango [0, 5] se utiliza para escalar todos los tiempos de viaje del vehículo (el valor predeterminado es 1), la precisión respetada se limita a dos dígitos después del punto decimal
|
|
[ max_tasks]
|
un número entero que define el número máximo de tareas en una ruta para este vehículo
|
|
[ steps]
|
una serie de vehicle_step objetos que describen una ruta personalizada para este vehículo
| |
Un breakobjeto tiene las siguientes propiedades:
|
Llave
|
Descripción
|
|
id
|
entero
|
|
time_windows
|
una serie de time_window objetos que describen espacios válidos para el inicio del descanso
|
|
[ service]
|
duración del descanso (por defecto 0)
|
|
[ description]
|
una cadena que describe esta ruptura
| |
Se informa un error si dos break objetos tienen lo mismo id para el mismo vehículo.
Un vehicle_step objeto tiene las siguientes propiedades:
|
Llave
|
Descripción
|
|
type
|
una cadena (ya sea start, job, pickup, deliveryobreak )end
|
|
[ id]
|
ID de la tarea que se realizará en este paso si type el valor es job,pickupdelivery obreak
|
|
[ service_at]
|
restricción estricta del tiempo de servicio
|
|
[ service_after]
|
restricción estricta en el límite inferior del tiempo de servicio
|
|
[ service_before]
|
restricción estricta en el límite superior del tiempo de servicio
| |
Notas
Ubicaciones de tareas
Para objetos y , si se proporcionan matrices personalizadas job:pickup delivery
-
location_index es obligatorio
-
location es opcional pero se puede configurar para recuperar coordenadas en la respuesta
Si no se proporciona ninguna matriz personalizada:
-
table Se enviará una consulta al motor de enrutamiento.
-
-
location_index es irrelevante
Ubicaciones de vehículos
-
clave start y end son opcionales para a vehicle, siempre que al menos uno de ellos esté presente
-
si end se omite, la ruta resultante se detendrá en la última tarea visitada, cuya elección está determinada por el proceso de optimización
-
si start se omite, la ruta resultante comenzará en la primera tarea visitada, cuya elección está determinada por el proceso de optimización
-
para solicitar un viaje de ida y vuelta, solo especifica ambos start y end con las mismas coordenadas
-
Dependiendo de si se proporcionan matrices personalizadas, los campos obligatorios siguen la misma lógica que para job las claves location ylocation_index
Restricciones de capacidad
Utilice cantidades ( capacity para vehículos delivery y pickup para trabajos, amount para envíos) para describir un problema con restricciones de capacidad. Esas matrices se pueden usar para modelar restricciones personalizadas para varias métricas a la vez, por ejemplo, número de artículos, peso, volumen, etc. Un vehículo solo puede realizar un conjunto de tareas si la carga resultante en cada paso de la ruta es menor que el valor coincidente. para capacity cada métrica. Cuando se utilizan varios componentes para las cantidades, se recomienda anteponer las métricas más importantes/limitantes.
Se supone que todos los montos relacionados con la entrega para los trabajos se cargan al inicio del vehículo, mientras que todos los montos relacionados con la recolección para los trabajos se devuelven al final del vehículo.
Habilidades
Se utiliza skills para describir un problema en el que no todos los vehículos pueden realizar todas las tareas. Las habilidades laborales son obligatorias, es decir, un trabajo sólo puede ser realizado por un vehículo que tenga todas las habilidades requeridas. En otras palabras: el trabajo jes elegible para vehículo vsi j.skillsestá incluido en v.skills.
Esta definición implica en particular que:
-
una tarea sin habilidades puede realizarse con cualquier vehículo;
-
un vehículo sin habilidades sólo puede cumplir tareas sin necesidad particular (es decir, también sin habilidades).
Para facilitar los problemas de modelado sin necesidad de habilidades, no se proporciona una skills clave de forma predeterminada, sino una matriz vacía.
Prioridades de tarea
Útil en situaciones en las que no se pueden realizar todas las tareas, para obtener cierto control sobre qué tareas no están asignadas. Establecer un priority valor alto para algunas tareas tenderá en la medida de lo posible a incluirlas en la solución en lugar de tareas de menor prioridad.
Tiempos de configuración de tareas
Los tiempos de preparación sirven como un medio para describir el tiempo que lleva comenzar una tarea en una ubicación determinada. Esto modela una duración que no debe volver a aplicarse para otras tareas que se realicen en el mismo lugar. Por lo tanto, el "tiempo de acción" total para una tarea es al llegar a una nueva ubicación o solo si se realiza una nueva tarea en la ubicación anterior del vehículo.setup + service service
Ventanas de tiempo
Depende de los usuarios decidir cómo describir las ventanas de tiempo:
-
valores relativos , por ejemplo, [0, 14400]para una ventana de tiempo de 4 horas que comienza al comienzo del horizonte de planificación. En ese caso, todos los tiempos reportados en la salida con la arrival clave son relativos al inicio del horizonte de planificación;
-
valores absolutos , marcas de tiempo "reales". En ese caso, todos los tiempos informados en la salida con la arrival clave pueden interpretarse como marcas de tiempo.
La ausencia de una ventana de tiempo en la entrada significa que no se aplica ninguna restricción de tiempo. En particular, un vehículo sin time_window llave podrá realizar cualquier número de tareas, y una tarea sin time_windows llave podrá incluirse en cualquier momento de cualquier ruta, en la medida en que lo permitan otras limitaciones como habilidades, capacidad y otros vehículos/ ventanas de tiempo de tareas.
Pasos del vehículo
En modo plano
La steps matriz describe exactamente el orden de ruta que se generará en respuesta. service_*Las claves (opcionales) para vehicle_step objetos se utilizan como restricciones de tiempo adicionales.
En modo resolución
El uso steps para vehículos en el modo de resolución VRP predeterminado es una forma de forzar el inicio de la búsqueda desde la solución coincidente definida por el usuario, si es válida. A diferencia del comportamiento de resolución predeterminado de ejecutar varias búsquedas simultáneas, esto significa en particular que se sigue una única ruta de búsqueda, empezando por la solución proporcionada. Por lo tanto, obviamente se espera que la calidad resultante dependa en gran medida del punto de partida definido por el usuario.
En ese contexto:
-
solo los pasos con type=job, pickup o delivery se utilizan para decidir el pedido de rutas iniciales
-
service_*las claves no se utilizan
Se genera un error si para alguno de los vehículos proporcionados se steps describe una ruta que no es válida con respecto a alguna de las restricciones.
matrices
El matrices objeto permite ingresar matrices personalizadas (no vacías) para cada perfil de vehículo. Cada matriz es una matriz de matrices de números enteros sin signo archivados bajo la profile clave y luego bajo:
-
durations para una matriz de tiempo de viaje personalizada que se utilizará para todas las comprobaciones de las limitaciones de tiempo;
-
costs para obtener una matriz de costos personalizada que se utilizará en todas las evaluaciones de costos de ruta.
Si solo durations se proporciona el valor, se da a entender que también debe usarse para evaluaciones de costos.
Ejemplo de descripción de diferentes matrices para diferentes perfiles de vehículos:
Si se proporcionan matrices personalizadas para todos los valores de vehículo requeridos , profile las propiedades y se vuelven opcionales. En lugar de las coordenadas, durante la optimización se utilizan las indicaciones de filas y columnas proporcionadas con las claves.locationstart end *_index
Producción
La solución calculada se escribe como json en la salida estándar o en un archivo (usando ), con el siguiente formato.-o
|
Llave
|
Descripción
|
|
code
|
código de estado
|
|
error
|
mensaje de error (el presente sif code es diferente de 0)
|
|
summary
|
objeto que resume los indicadores de solución
|
|
unassigned
|
conjunto de objetos que describen tareas no asignadas con sus id,type y ,description si se proporcionan , location ylocation_index
|
|
routes
|
conjunto de route objetos
| |
Código
Los valores posibles para el código de estado son:
|
Valor
|
Estado
|
|
0
|
no se generó ningún error
|
|
1
|
error interno
|
|
2
|
error de entrada
|
|
3
|
error de enrutamiento
| |
Resumen
El summary objeto tiene las siguientes propiedades:
|
Llave
|
Descripción
|
|
cost
|
costo total para todas las rutas
|
|
routes
|
número de rutas en la solución
|
|
unassigned
|
número de tareas que no se pudieron realizar
|
|
setup
|
tiempo total de configuración para todas las rutas
|
|
service
|
tiempo total de servicio para todas las rutas
|
|
duration
|
tiempo total de viaje para todas las rutas
|
|
waiting_time
|
tiempo total de espera para todas las rutas
|
|
priority
|
suma total de prioridad para todas las tareas asignadas
|
|
violations
|
variedad de violation objetos para todas las rutas
|
|
[ amount]
|
importe total para todas las rutas
|
|
[ delivery]
|
entrega total para todas las rutas
|
|
[ pickup]
|
recogida total para todas las rutas
|
|
[ distance]*
|
distancia total para todas las rutas
| |
*: proporcionado al usar la -gbandera.
Rutas
Un route objeto tiene las siguientes propiedades:
|
Llave
|
Descripción
|
|
vehicle
|
ID del vehículo asignado a esta ruta.
|
|
steps
|
conjunto de step objetos
|
|
cost
|
costo para esta ruta
|
|
setup
|
tiempo total de preparación para esta ruta
|
|
service
|
tiempo total de servicio para esta ruta
|
|
duration
|
tiempo total de viaje para esta ruta
|
|
waiting_time
|
tiempo total de espera para esta ruta
|
|
priority
|
suma total de prioridad para las tareas en esta ruta
|
|
violations
|
conjunto de violation objetos para esta ruta
|
|
[ amount]
|
monto total para trabajos en esta ruta
|
|
[ delivery]
|
entrega total para tareas en esta ruta
|
|
[ pickup]
|
recogida total para tareas en esta ruta
|
|
[ description]
|
descripción del vehículo, si se proporciona en la entrada
|
|
[ geometry]*
|
geometría de ruta codificada con polilínea
|
|
[ distance]*
|
distancia total de la ruta
| |
*: proporcionado al usar la -gbandera.
Pasos
Un step objeto tiene las siguientes propiedades:
|
Llave
|
Descripción
|
|
type
|
una cadena (ya sea start, job, pickup, deliveryobreak )end
|
|
arrival
|
hora estimada de llegada a este paso
|
|
duration
|
tiempo de viaje acumulado al llegar a este paso
|
|
setup
|
tiempo de configuración en este paso
|
|
service
|
tiempo de servicio en este paso
|
|
waiting_time
|
tiempo de espera al llegar a este paso
|
|
violations
|
conjunto de violation objetos para este paso
|
|
[ description]
|
descripción del paso, si se proporciona en la entrada
|
|
[ location]
|
matriz de coordenadas para este paso (si se proporciona en la entrada)
|
|
[ location_index]
|
índice de fila y columna relevantes en matrices personalizadas para este paso (si se proporciona en la entrada)
|
|
[ id]
|
ID de la tarea realizada en este paso, solo se proporciona si type el valor es job, pickupodeliverybreak
|
|
[ job]
|
ID del trabajo realizado en este paso, solo se proporciona si typeel valor esjob
|
|
[ load]
|
carga del vehículo después de completar el paso (con restricciones de capacidad)
|
|
[ distance]*
|
Distancia recorrida al llegar a este paso.
| |
*: proporcionado al usar la -gbandera.
Violación
Un violation objeto tiene las siguientes propiedades:
|
Llave
|
Descripción
|
|
Llave
|
Descripción
|
|
cause
|
cadena que describe la causa de la infracción
|
|
[ duration]
|
Anticipación (resp. retraso) si cause es "lead_time" (resp. "retraso")
| |
Las posibles causas de infracción son:
-
"retraso" si el inicio real del servicio no cumple con una ventana de tiempo de tarea y llega tarde al final de una ventana de tiempo
-
"lead_time" si el inicio real del servicio no cumple con una ventana de tiempo de tarea y es temprano en una ventana de tiempo de inicio
-
"carga" si la carga del vehículo supera su capacidad
-
"max_tasks" si el vehículo tiene más tareas que su max_tasks valor
-
"habilidades" si el vehículo no tiene todas las habilidades necesarias para una tarea
-
"precedencia" si shipment no se cumple una restricción de precedencia ( pickup sin coincidencia delivery, delivery antes/sin coincidencia pickup)
-
"missing_break" si se ha omitido una parada del vehículo en su ruta personalizada
Nota sobre infracciones: informar solo tiene sentido cuando se usa -cpara elegir ETA para rutas personalizadas descritas en la entrada usando las steps teclas para un vehicle. Cuando se utiliza la optimización regular, las infracciones aún se informan para mantener la coherencia, pero se garantiza que serán "nulas", es decir, las violations matrices están vacías.
Ejemplos
Usando un motor de enrutamiento (OSRM u Openrouteservice)
Usando matrices personalizadas
Uso para elegir ETA y denunciar infracciones-c
Un ejemplo con una ruta con exceso de capacidad y otra con plazos de entrega y retrasos.