vrt-lss-universal 6.5.1990

VRt.Universal [UV]

# Description  **VRt.Universal** is designed to solve complex problems which may include two types of orders - deliveries/pick-ups as well as service orders.  This service suits for complex cases, especially if it is possible to change business requirements during the integration with the service.  ## Features  * Ability to pick up cargo from any location * Ability of unloading in any location * Demand types: pickup (loading of cargo), drop (unloading of cargo), work (work on the location without moving the cargo) * An order can include several demands (a delivery order consists of at least two demands: pickup and drop; a work order can include either a single work or a set of works; a complex order can consist of any number of demands of any type: pickup, drop, work) * Transport and performers are different entities, during the planning the appropriate performer is assigned to the transport * A transport may have several compartments for different types of cargo. Each compartment may have different parameters * Accounting for the transport and cargo compatibility (by dimensions: length, width, height) * Accounting for the compartment and cargo compatibility (refrigerator, thermal bag, fasteners, etc.) * Alternative demands are supported, i. e. the ability to fulfil one of the demands, which is selected according to its geographical location and time window  ## Restrictions support  **Performer** restrictions:  * Start/finish location * Accounting for the performer's way to the transport location * Performer's availability schedule is a list of time windows when the performer can move and work on locations * The maximum duration of the performer's work during the specified time period  **Transport** restrictions:  * Start/finish location * Transport availability schedule is a list of time windows when the transport is available * The maximum route distance * Several compartments in the transport, each with its own parameters * Capacity upper limit (weight, volume, number of orders, number of demands)  **Order** restrictions:  * Strict time windows * Ability to specify different valid time windows for a location and time windows to fulfil the desired demand * Accounting for the requests fulfillment order within the route * A list of desired time windows with different associated costs  ## Compatibilities  Entities are compatible if the capabilities list of one entity corresponds to the list of restrictions of another entity (example: fleet parameters corresponds to cargo parameters to be delivered).  Supported compatibilities:  | Name                    | Restrictions                     | Features                     | |-------------------------|----------------------------------|------------------------------| | Order - Performer       | order.performer_restrictions     | performer.performer_features | | Order - Not a performer | order.performer_blacklist        | performer.performer_features | | Cargo - Compartment     | order.cargo.box_restrictions     | transport.box.box_features   | | Location - Transport    | location.transport_restrictions  | transport.transport_features | | Transport - Performer   | transport.performer_restrictions | performer.performer_features | | Performer - Transport   | performer.transport_restrictions | transport.transport_features | | Order - Order           | order.order_restrictions         | order.order_features         |  Business rule examples:  | Name                    | Business rule example                                                                               | |-------------------------|-----------------------------------------------------------------------------------------------------| | Order - Performer       | The driver must have a special license to fulfil the order                                          | | Order - Not a performer | The driver is in the blacklist                                                                      | | Cargo - Box             | For transportation of frozen products, a compartment with a special temperature profile is required | | Location - Transport    | Restrictions on the transport height                                                                | | Transport - Performer   | The truck driver must have the class C driving license                                              | | Performer - Transport   | The driver is allowed to work on a specific transport                                               | | Order - Order           | It is not allowed to transport fish and fruits in the same compartment                              |  ## Cargo placement  List of possibilities of a object rotations (90 degree step):  * `ALL` - can rotate by any axis * `YAW` - can yaw * `PITCH` - can pitch * `ROLL` - can roll    ![rotation](../images/universal_cargo_yaw_pitch_roll.svg)  ## Trip model  The trip is described by the list of states of the executor, while the executor can be in several states at the same time (for example, to be inside the working time window of a location and fulfill an order at the same location).  Possible values ​​of the flags responsible for the geographical location:  * `AROUND_LOCATION` - the performer is located near the location - in the process of parking or leaving it. * `INSIDE_LOCATION` - the performer is at the location.  Possible values ​​of the flags responsible for being in time windows:  * `INSIDE_WORKING_WINDOW` - the executor is inside the working time window. * `INSIDE_LOCATION_WINDOW` - the executor is inside the location's working time. * `INSIDE_EVENT_HARD_WINDOW` - the executor is inside a hard time window. * `INSIDE_EVENT_SOFT_WINDOW` - the executor is inside the soft time window.  Possible values ​​of flags responsible for actions:  * `ON_DEMAND` - the executor is working on the request. * `WAITING` - the performer is in standby mode. * `RELOCATING` - the executor is moving to the next stop. * `BREAK` - the performer is on a break.  ### An example of a route with multiple states at each point in time  | time  | set of active flags                                                                                                                                                          | location / order / application / event | comment                                                                                        | |:------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------|:-----------------------------------------------------------------------------------------------| | 10:00 | INSIDE_LOCATION <br/> AROUND_LOCATION                                                                                                                                        | 2 / - / - / -                          | starting location                                                                              | | 10:10 | RELOCATING                                                                                                                                                                   | - / - / - / -                          | we go to the first order                                                                       | | 10:20 | AROUND_LOCATION                                                                                                                                                              | 2 / - / - / -                          | arrived at the first order                                                                     | | 10:40 | AROUND_LOCATION <br/> INSIDE_LOCATION <br/> WAITING                                                                                                                          | 2 / - / - / -                          | parked                                                                                         | | 11:00 | AROUND_LOCATION <br/> INSIDE_LOCATION <br/> INSIDE_LOCATION_WINDOW <br/> WAITING <br/> INSIDE_EVENT_HARD_WINDOW                                                              | 2 / - / - / -                          | waited for the start of the location window and at the same time the availability of the order | | 11:25 | AROUND_LOCATION <br/> INSIDE_LOCATION <br/> INSIDE_LOCATION_WINDOW <br/> ON_DEMAND <br/> INSIDE_WORKING_WINDOW <br/> INSIDE_EVENT_HARD_WINDOW                                | 2 / 1 / 2 / 3                          | waited for the change of artist                                                                | | 11:30 | AROUND_LOCATION <br/> INSIDE_LOCATION <br/> INSIDE_LOCATION_WINDOW <br/> ON_DEMAND <br/> INSIDE_WORKING_WINDOW <br/> INSIDE_EVENT_HARD_WINDOW <br/> INSIDE_EVENT_SOFT_WINDOW | 2 / 1 / 2 / 3                          | while working - a soft window happened                                                         | | 11:40 | AROUND_LOCATION <br/> INSIDE_LOCATION <br/> INSIDE_LOCATION_WINDOW <br/> INSIDE_WORKING_WINDOW                                                                              | 2 / - / - / - | finished working | | 11:45 | AROUND_LOCATION <br/> INSIDE_WORKING_WINDOW                                                                                                                                  | 2 / - / - / - | drove out of the parking lot | | 11:45 | RELOCATING <br/> INSIDE_WORKING_WINDOW                                                                                                                                       | - / - / - / - | we go to the next order |  ## Planning configuration  For each planning, you can specify a planning configuration that determines the objective function, desired route quality, and calculation speed.  The name of the planning configuration is passed to the `trips_settings.configuration` field.  Possible options:  | Name                                     | Task                                                                                                                                                                  | |------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **optimize_distance**                    | Used by default: to deliver as many orders as possible, then minimize the total mileage (the number of transports is selected based on mileage)                       | | **visual_grouping**                      | To deliver as many orders as possible, using as little transports as possible. The routes should be grouped visually                                                  | | **optimize_transports**                  | To deliver as many orders as possible, using as little transports as possible, as also to optimize the working hours of performers                                    | | **optimize_locality_grouping**           | To deliver as many orders as possible, with visual grouping for the trips (all the delivery locations should be close to each other)                                  | | **optimize_cars_then_distance**          | To deliver as many orders as possible, then optimize the quantity of transports, then mileage                                                                         | | **optimize_time**                        | To deliver as many orders as possible, then optimize the total time of the performers                                                                                 | | **optimize_cars_then_time**              | To deliver as many orders as possible, then optimize the quantity of transports, then the total time of the performers                                                | | **optimize_visual_grouping**             | To deliver as many orders as possible, then distribute orders equally based on transport accessibility zones (as visual_grouping, but this is calculated differently) | | **optimize_cars_then_locality_grouping** | To deliver as many orders as possible, then optimize the number of transports, then visual grouping of routes                                                         | | **optimize_money**                       | To optimize the value of profit - costs, which consists of demand fulfillment rewards and expenses for performers and transports (optimized value is non-negative)    |  In addition to existing planning options, you can create an objective function for the client's business processes ([ask us for the configuration](mailto:[e-mail])).  It is recommended to use the **optimize_cars_then_distance** for development, because this configuration does not require a detailed selection of tariffs and order prices.  ## Data validation  Input data validation consists of several steps, which are described below.  Validation of planning results (including the search for possible reasons why orders were not planned) is located in the `analytics` method.  ### 1. Schema check  If the request does not follow the schema, then scheduling is not fully started and such an error is returned along with a 400 code in `schema_errors`.  We recommend validating the request against the schema (or yaml file) before sending it to the server.  ### 2. Check for logical errors that prevent planning from continuing  Schema-correct data passes the second stage of checking for the possibility of starting planning.  An example of errors at this stage are keys leading to empty entities, or if all orders are incompatible with all performers, i.e. something that makes the planning task pointless.  These errors are returned along with a 400 code in `logical_errors`.  ### 3. Check for logical errors that prevent planning from continuing  At the third stage, each entity is checked separately.  All entities that have not passed validation are cut out from the original task and are not sent for planning.  Depending on the setting of `treat_warnings_as_errors`, the results of this type of validation are returned to `warnings` either with a 400 code or with the scheduling result.  ### 4. Checks in the planning process  Part of the checks can only be carried out in the planning process.  For example - that according to the specified tariffs and according to the current traffic forecast, it is physically impossible to reach a certain point.  The results of these checks are returned in `warnings` or together with the scheduling result.  ## Entity relationship diagram  ![erd](../uml/universal.svg)  # Xlsx  <!-- AUTO-GENERATED-CONTENT:START (FILE:src=xlsx.md) --> <!-- The below content is automatically added from xlsx.md --> Description of VRt.Universal XLSX format for import / data export.  This format is a complete display of data JSON models and is used for:  * initial data * process settings * calculation results * statistics on the calculation result  Below is a description of each sheet separately.  ## Locations  The name of the sheet `locations`.  List of locations that are used in orders and shifts.  The described object: <SchemaDefinition schemaRef=\"#/components/schemas/location\" />  ## Performers  The name of the sheet is `performers`.  List of available performers.  The described object: <SchemaDefinition schemaRef=\"#/components/schemas/performer\" />  ## Transports  The name of the sheet `transports`.  List of available transport.  The described object: <SchemaDefinition schemaRef=\"#/components/schemas/transport\" />  ## Boxes  The name of the sheet is `transports.boxes`.  List of transport boxes that can accommodate the load. The table is mandatory if there are orders with applications of types of `PICKUP` and `DROP`. In the description of the compartments, those fields that describe cargo are required.  The described object: <SchemaDefinition schemaRef=\"#/components/schemas/box\" />  ## Orders  The name of the sheet is `orders`.  List of orders.  The described object: <SchemaDefinition schemaRef=\"#/components/schemas/order\" />  ## Cargos  The name of the sheet is `orders.cargos`.  List of goods. It may contain one load for `DROP`, a list for `PICKUP`, empty for `WORK`. The table is not obligatory if all applications have the type `WORK`.  The described object: <SchemaDefinition schemaRef=\"#/components/schemas/cargo\" />  ## Hardlinks  The name of the sheet is `hardlinks`.  List of hardlinks.  The described object: <SchemaDefinition schemaRef=\"#/components/schemas/hardlink\" />  ## Trips  The name of the sheet `trips`.  List of trips.  The described object: <SchemaDefinition schemaRef=\"#/components/schemas/trip\" />  ## Facts  The name of the sheet is `facts`.  List of facts.  The described object: <SchemaDefinition schemaRef=\"#/components/schemas/facts\" />  ## Plan settings  The name of the sheet `plan_settings`.  The described object: <SchemaDefinition schemaRef=\"#/components/schemas/plan_settings\" />  ## Actualize settings  The name of the sheet is `actualize_settings`.  The described object: <SchemaDefinition schemaRef=\"#/components/schemas/actualize_settings\" />  ## Replan settings  The name of the sheet is `replan_settings`.  The described object: <SchemaDefinition schemaRef=\"#/components/schemas/replan_settings\" /> <!-- AUTO-GENERATED-CONTENT:END -->  # noqa: E501