VRt.Universal [UV] (7.36.3317)

Programming interface for universal trip planning.

• Ability to pick up cargo from any location
• Ability to drop off cargo at any location
• Paired demands of several types: PICKUP (loading), DROP (unloading)
• Single demands of several types: DROP_FROM_BOX (unloading of cargo that is already in the box), PICKUP_TO_BOX (picking up cargo into the box without subsequent unloading), WORK (work at a location without moving cargo)
• A complex order may consist of any number of demands of any types
• Transport and performers are split into separate entities; during planning, an optimal assignment of a performer to a transport is performed
• Transport has multiple boxes — each of which can hold cargo and has its own characteristics
• Compatibility check between cargo and transport based on cargo dimensions (length, width, height, additional capacity parameters)
• Compatibility check between cargo and transport box (allowing to take into account box features: refrigerator, thermo bag, fasteners, etc.)
• Replacement demands — i.e. the ability to perform one of several substitute demands, the choice being made based on the demand's geographic location and time window

Constraints on a performer:

• Start/finish location
• Accounting for the performer's travel to the transport's start point
• Performer availability schedule — a list of time windows during which the performer can travel and perform work at locations
• Maximum work duration of the performer within a given time period

Constraints on transport:

• Start/finish location
• Transport availability schedule — a list of time windows during which the transport can travel
• Maximum route length
• Multiple boxes in the transport, each with its own parameters
• Upper limit on summed capacities (mass, volume, number of orders, number of demands)

Constraints on an order:

• Hard time windows
• Ability to specify different allowed location work windows and desired demand execution windows
• Order of demand execution within a route
• List of desired execution time windows with different costs for each of them

Entities are compatible if the list of features of one entity fully covers the list of restrictions of another entity (the opposite for performer_blacklist — the lists must not overlap).

Supported compatibilities:

Examples of business rules:

The hardlinks mechanism (hardlinks) is used to specify requirements for orders, a performer and a transport to be in the same trip.

A hardlink guarantees that the entities are in the same trip and does not guarantee that the entity is actually planned. For example, if the performer cannot complete the order in time, the order will not be planned, but it will still be assigned to the trip (it will end up in waitlist).

A hardlink also does not cancel the specified compatibilities (and the penalties for compatibility violations). For example, if an order cannot be performed by the performer, it will not be planned but will be assigned to the trip (it will end up in waitlist).

List of an object's rotation capabilities (in 90-degree increments):

• ALL — can be rotated around any axis any number of times
• YAW — can be rotated once around the vertical axis (around its own axis)
• PITCH — can be rotated once around the transverse axis (set vertically)
• ROLL — can be rotated once around the longitudinal axis (laid on its side)

A trip is described by a list of performer states; a performer can be in several states at the same time (e.g. be inside a location's working time window and at the same time perform an order at the same location).

Values of the flags responsible for the geographic position (multiple flags may be active at the same time):

• AROUND_LOCATION — the performer is near the location, in the process of parking or leaving it.
• INSIDE_LOCATION — the performer is at the location.

Values of the flags responsible for being inside time windows (multiple flags may be active at the same time):

• INSIDE_WORKING_WINDOW — the performer is inside the working time window.
• INSIDE_LOCATION_WINDOW — the performer is inside the location's operating time.
• INSIDE_EVENT_HARD_WINDOW — the performer is inside the hard time window.
• INSIDE_EVENT_SOFT_WINDOW — the performer is inside the soft time window.

Values of the flags responsible for actions (only one flag can be active at a time):

• ON_DEMAND — the performer started working on a demand.
• WAITING — the performer started waiting.
• RELOCATING — the performer started moving to the next stop.
• BREAK — the performer started a break.
• REST — the performer started a long rest.
• ARRIVAL — the performer started parking.
• DEPARTURE — the performer finished leaving the parking.

Values of the flags responsible for the logical state:

• DURING_ROUNDTRIP — the performer is performing a round trip.

Example route with multiple states at every moment in time

A trip consists of one or more round trips.

The round-trip flag DURING_ROUNDTRIP is set when work on a demand starts and is removed in one of three cases:

• the performer arrived at the next location to stop using the transport
• the performer arrived at a location that separates round trips
• the performer stopped using the transport (in a location that does not separate round trips, after performing some other action)

Between the end of one round trip and the beginning of another there can be no RELOCATING change of location, but the following can occur: WAITING, performer's BREAK, performer's REST.

A location separates a trip into round trips in one of two cases:

• if the location has a throughput limit timetable.limits (in this case there can be more than one location separating the trip)
• if the location is simultaneously the start and finish location of all performers and transports, as well as of all PICKUP-type demands (in this case there will be only one location separating the trip)

Examples of such locations (depending on the problem statement) include:

• distribution centers when delivering goods to stores or warehouses for long-haul transportation tasks
• stores or warehouses when delivering goods to customers in last-mile tasks
• dumps in waste collection tasks

For each planning run it is possible to specify a planning configuration that defines the objective function, the desired route quality, and the calculation speed.

The configuration name is passed in the trips_settings.configuration field.

Main configurations:

Additional configurations:

In addition to the existing planning options, an objective function can be created specifically for a client's business processes (request a configuration).

For development we recommend using optimize_cars_then_distance, as this configuration does not require fine-tuning of tariffs and order costs.

Validation of input data consists of several stages described below.

1. Schema check

If a request does not pass schema validation, planning is not started at all and such an error is returned together with code 400 in schema_errors.

We recommend validating the request against the schema (or the yaml file) before sending it to the server.

2. Check for logical errors that prevent planning from continuing

Data that is correct against the schema goes through the second validation stage to determine whether planning can be started.

Examples of errors at this stage are keys pointing to empty entities, or all orders being incompatible with all performers — i.e. anything that makes the planning task meaningless.

These errors are returned together with code 400 in logical_errors.

3. Check for logical errors that prevent planning from continuing

At the third stage each entity is checked individually.

All entities that fail the check are removed from the original task and are not sent to planning.

Depending on the treat_warnings_as_errors setting, the results of this type of check are returned in warnings together with code 400, or together with the planning result.

4. Checks during planning

Some checks can only be performed during planning.

For example — that according to the specified tariffs and the current traffic forecast it is physically impossible to drive to a particular point.

The results of these checks are returned in warnings together with the planning result.

Planning — creating trips that take into account all the specified constraints, based on the data about orders, performers and transport.

Planning requests can be executed in synchronous (for testing) and asynchronous (for production use) modes.

To get the result of cleansing the original task, use data cleansing for planning.