vrt-lss-universal 7.32.3215

VRt.Universal [UV]

vrt_lss_universal

Description

Software interface for universal trip planning.

Features

• Ability to pick up cargo from any location
• Possibility of unloading in any location
• Pair orders of several types: PICKUP (loading), DROP (unloading)
• Single requests of several types: DROP_FROM_BOX (unloading cargo that is already in the body), PICKUP_TO_BOX (cargo pickup into the body without subsequent unloading), WORK (working at the location without moving the cargo)
• A complex order can consist of any number of orders of any type
• Transport and performers are divided into different entities, when planning, the optimal assignment of the performer to the transport occurs
• The transport has several boxes - each of which can accommodate cargo and has its own characteristics
• Accounting for the compatibility of cargo with transport in terms of cargo dimensions (length, width, height, additional capacity parameters)
• Taking into account the compatibility of the cargo-box of transport (the ability to take into account the features of the box: refrigerator, thermal bag, fasteners, etc.)
• Substitute applications, i.e. the ability to execute one of the substitute applications, the choice of which is based on its geographic 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 boxes 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 - Box	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 box 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 box

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

Trip model

A trip is described by a list of states of the performer, while at the same time the performer can be in several states (for example, being inside the working time window of a location and fulfilling an order at the same location).

The meanings 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 located at the location.

The values ​​of the flags responsible for being in time windows:

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

The values ​​of the flags responsible for the actions:

• ON_DEMAND - the performer is working on the request.
• WAITING - the performer is in standby mode.
• RELOCATING - the performer moves to the next stop.
• BREAK - the performer is on a break.
• REST - the performer is on a long vacation.

Flag values ​​responsible for the logical state:

• DURING_ROUNDTRIP - the executor is performing a roundtrip.

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 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 INSIDE_LOCATION WAITING	2 / - / - / -	parked
11:00	AROUND_LOCATION INSIDE_LOCATION INSIDE_LOCATION_WINDOW WAITING 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 INSIDE_LOCATION INSIDE_LOCATION_WINDOW ON_DEMAND INSIDE_WORKING_WINDOW INSIDE_EVENT_HARD_WINDOW	2 / 1 / 2 / 3	waited for the change of artist
11:30	AROUND_LOCATION INSIDE_LOCATION INSIDE_LOCATION_WINDOW ON_DEMAND INSIDE_WORKING_WINDOW INSIDE_EVENT_HARD_WINDOW INSIDE_EVENT_SOFT_WINDOW	2 / 1 / 2 / 3	while working - a soft window happened
11:40	AROUND_LOCATION INSIDE_LOCATION INSIDE_LOCATION_WINDOW INSIDE_WORKING_WINDOW	2 / - / - / -	finished working
11:45	AROUND_LOCATION INSIDE_WORKING_WINDOW	2 / - / - / -	drove out of the parking lot
11:45	RELOCATING INSIDE_WORKING_WINDOW	- / - / - / -	we go to the next order

Roundtrips

A trip consists of one or more round trips.

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

• the executor arrived at the next location to stop using transport
• the executor arrived at the location separating round trips
• the executor stopped using transport (in a location not separating round trips, after performing some other action)

Between the end of one round trip and the beginning of another round trip, a change of location RELOCATING cannot occur, but the following can occur: waiting WAITING, a break for the executor BREAK, a rest for the executor REST.

Locations dividing a trip into round trips are defined as follows:

• if the location has a capacity limitation timetable.limits (in this case, there may be more than one location dividing the trip)
• if the location is simultaneously the starting and ending location of all performers and transports, as well as all requests with the PICKUP type (in this case, there will be only one location dividing the trip)

Examples of such locations, depending on the task formulation, can be:

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

Planning configuration

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

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

Main configurations:

Title	Task
optimize_distance	Arrange as many orders as possible, then optimize the total mileage (the number of vehicles is selected based on the mileage), used by default
optimize_transports	Place as many orders as possible, while using as little transport as possible, ceteris paribus, optimize the work time of performers
optimize_locality_grouping	Place as many orders as possible, while striving to optimize the visual grouping of routes, but not their number
optimize_cars_then_distance	Arrange as many orders as possible, then optimize the number of vehicles, then the mileage
optimize_time	Place as many orders as possible, then optimize the total work time of performers
optimize_cars_then_time	Arrange as many orders as possible, then optimize the number of transport, then the total time of the performers
optimize_money	Optimize the value of "profit - costs", consists of rewards for applications and costs for performers and transports (optimized value is non-negative)

Additional configurations:

Title	Task
visual_grouping	Arrange as many orders as possible while using as little transport as possible and routes should be visually grouped
optimize_visual_grouping	Arrange as many orders as possible, then evenly distribute orders taking into account transport accessibility zones (similar to visual_grouping, but visual grouping is calculated differently)
optimize_cars_then_locality_grouping	Arrange as many orders as possible, then optimize the number of vehicles, then visually group the routes
optimize_cars_then_single_location_grouping_sequenced	Place as many orders as possible, then optimize the number of machines, then reliability

In addition to the existing planning options, it is possible to create an objective function directly for the client's business processes (request configuration).

For development, it is recommended to use optimize_cars_then_distance, since this configuration does not require detailed selection of rates and order values.

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

This Python package is automatically generated by the OpenAPI Generator project:

• API version: 7.32.3215
• Package version: 7.32.3215
• Generator version: 7.17.0
• Build package: org.openapitools.codegen.languages.PythonClientCodegen

Requirements.

Python 3.9+

Installation & Usage

pip install

If the python package is hosted on a repository, you can install directly using:

pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git

(you may need to run pip with root permission: sudo pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git)

Then import the package:

import vrt_lss_universal

Setuptools

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Then import the package:

import vrt_lss_universal

Tests

Execute pytest to run the tests.

Getting Started

Please follow the installation procedure and then run the following:

import vrt_lss_universal
from vrt_lss_universal.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.edge7.veeroute.cloud
# See configuration.py for a list of all supported configuration parameters.
configuration = vrt_lss_universal.Configuration(
    host = "https://api.edge7.veeroute.cloud"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure Bearer authorization (JWT): ApiKeyAuth
configuration = vrt_lss_universal.Configuration(
    access_token = os.environ["BEARER_TOKEN"]
)


# Enter a context with an instance of the API client
with vrt_lss_universal.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = vrt_lss_universal.ActualizeApi(api_client)
    process_code = 'process_code_example' # str | Unique process identifier.

    try:
        # Cancel calculation
        api_instance.cancel_actualize_calculation(process_code)
    except ApiException as e:
        print("Exception when calling ActualizeApi->cancel_actualize_calculation: %s\n" % e)

Documentation for API Endpoints

All URIs are relative to https://api.edge7.veeroute.cloud

Class	Method	HTTP request	Description
ActualizeApi	cancel_actualize_calculation	DELETE /universal/actualize/calculation-async/{process_code}	Cancel calculation
ActualizeApi	delete_actualize_result	DELETE /universal/actualize/result/{process_code}	Result removal
ActualizeApi	read_actualize_result	GET /universal/actualize/result/{process_code}	Getting the result
ActualizeApi	read_actualize_state	GET /universal/actualize/state/{process_code}	Calculation state
ActualizeApi	run_actualize_calculation	POST /universal/actualize/calculation	Actualization (SYNC)
ActualizeApi	run_actualize_calculation_async	POST /universal/actualize/calculation-async	Actualization (ASYNC)
ActualizeApi	run_actualize_refine	POST /universal/actualize/refine	Data refine
ActualizeApi	run_actualize_validation	POST /universal/actualize/validation	Data validation
ConvertApi	run_convert_json_to_thrift	POST /universal/convert/json-to-thrift	JSON >> THRIFT
ConvertApi	run_convert_json_to_xlsx	POST /universal/convert/json-to-xlsx	JSON >> XLSX
ConvertApi	run_convert_xlsx_to_json	POST /universal/convert/xlsx-to-json	XLSX >> JSON
PlanApi	cancel_plan_calculation	DELETE /universal/plan/calculation-async/{process_code}	Cancel calculation
PlanApi	delete_plan_result	DELETE /universal/plan/result/{process_code}	Result removal
PlanApi	generate_plan_statistics	POST /universal/plan/statistics	Calculation of statistics on trips
PlanApi	read_plan_result	GET /universal/plan/result/{process_code}	Getting the result
PlanApi	read_plan_state	GET /universal/plan/state/{process_code}	Calculation state
PlanApi	run_plan_calculation	POST /universal/plan/calculation	Planning (SYNC)
PlanApi	run_plan_calculation_async	POST /universal/plan/calculation-async	Planning (ASYNC)
PlanApi	run_plan_refine	POST /universal/plan/refine	Data refine
PlanApi	run_plan_validation	POST /universal/plan/validation	Data validation
ReplanApi	cancel_replan_calculation	DELETE /universal/replan/calculation-async/{process_code}	Cancel calculation
ReplanApi	delete_replan_result	DELETE /universal/replan/result/{process_code}	Result removal
ReplanApi	read_replan_result	GET /universal/replan/result/{process_code}	Getting the result
ReplanApi	read_replan_state	GET /universal/replan/state/{process_code}	Calculation state
ReplanApi	run_replan_calculation	POST /universal/replan/calculation	Replanning (SYNC)
ReplanApi	run_replan_calculation_async	POST /universal/replan/calculation-async	Replanning (ASYNC)
ReplanApi	run_replan_refine	POST /universal/replan/refine	Data refine
ReplanApi	run_replan_validation	POST /universal/replan/validation	Data validation
SystemApi	check	GET /universal/system/check	Checking the availability
SystemApi	file	GET /universal/file/{filename}	Getting the documentation
SystemApi	version	GET /universal/system/version	Getting the service version

Documentation For Models

• ActualizeSettings
• ActualizeTask
• AssignedPerformer
• AssignedTransport
• Attribute
• Box
• BoxCompatibilities
• BoxLimits
• BreakRules
• CalculationAsyncResult
• CalculationInfo
• CalculationSettings
• CalculationState
• CalculationStatus
• Capacity
• CapacityCost
• CapacityLimit
• CapacityMultiplier
• CapacityStatisticsLoad
• CapacityStatisticsRatio
• CapacityStatisticsSum
• Cargo
• CargoAction
• CargoActionType
• CargoCompatibilities
• CargoInvoice
• CargoInvoiceDetail
• CargoInvoiceHonestSign
• CargoInvoiceReceipt
• CargoInvoiceTax
• CargoRotationType
• CheckResult
• CompatibilityPenalty
• Demand
• DemandExtraDuration
• DemandType
• EntityError
• EntityErrorType
• EntityPath
• EntityType
• EntityWarning
• EntityWarningType
• ExtensionSettings
• Fact
• FactEssences
• FactStatus
• FactType
• FeatureLifetime
• General402
• General403
• General404
• General404Detail
• General429
• General500
• GeneralStatistics
• GeoSettings
• Geopoint
• Hardlink
• HardlinkElement
• HardlinkElementType
• LoadStatistics
• Location
• LocationCargosLimit
• LocationCompatibilities
• LocationLimit
• LocationLimitStatistics
• LocationStatistics
• LocationTimetableElement
• LocationTransportsLimit
• Measurements
• ModelBreak
• Order
• OrderCompatibilities
• Performer
• PerformerCompatibilities
• PerformerLimits
• PerformerShift
• PerformerTariff
• PerformerTariffConstraint
• PlanResult
• PlanSettings
• PlanStatistics
• PlanTask
• PossibleEvent
• Quality
• RefineResult
• RemovedItems
• ReplanSettings
• ReplanStrategy
• ReplanTask
• Rest
• RestRules
• RoundtripStatistics
• RoutingMatrix
• RoutingMatrixWaypoint
• RoutingTransportMatrix
• SchemaError
• Service
• StatisticsTask
• StopDemand
• StopStatistics
• TaskStatistics
• TimeWindow
• TimeWindowViolationDetail
• TimeWindowViolations
• Tracedata
• Transport
• TransportCapacityMultiplier
• TransportCompatibilities
• TransportLimits
• TransportLoad
• TransportShift
• TransportSpeedMultiplier
• TransportTariff
• TransportTariffConstraint
• TransportType
• Trip
• TripAssumptions
• TripExpectations
• TripPenalties
• TripStartTimeStrategy
• TripState
• TripStateFlag
• TripStatistics
• TripsSettings
• Universal400WithErrorsAndWarnings
• UniversalData
• UnplannedItems
• ValidateResult
• VersionResult
• WorkAndRestRules

Documentation For Authorization

Authentication schemes defined for the API:

ApiKeyAuth

• Type: Bearer authentication (JWT)

Author

[e-mail]