vrt-lss-universal 7.37.3331

VRt.Universal [UV]

vrt_lss_universal

Description

Programming interface for universal trip planning.

Capabilities

• 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

Supported constraints

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

Compatibilities used

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:

Name	Restrictions	Features
Order – Performer	order.performer_restrictions	performer.performer_features
Order – Not-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
Cargo – Cargo	cargo.cargo_restrictions	cargo.cargo_features

Examples of business rules:

Name	Example business rule
Order – Performer	To perform the order the driver must have a special permit
Order – Not-Performer	The driver is on the blacklist
Cargo – Box	A box with a special temperature mode is required to transport frozen products
Location – Transport	Restrictions on transport height
Transport – Performer	For freight transport the driver must hold category C
Performer – Transport	The driver is allowed to work only on a specific transport
Order – Order	Fish and fruit cannot be transported in the same box
Cargo – Cargo	Two cargos cannot be placed simultaneously in the same transport box, but can be placed sequentially

Hardlinks

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).

Cargo placement in the box

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)

Trip model

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

Time	Set of active flags	Location / Order / Demand / Event	Comment
10:00	INSIDE_LOCATION AROUND_LOCATION	2 / - / - / -	Start location
10:05	AROUND_LOCATION DEPARTURE	2 / - / - / -	Left the parking
10:10	RELOCATING DEPARTURE	2 / - / - / -	Driving to the first order
10:20	AROUND_LOCATION ARRIVAL	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 / - / - / -	The location's window opened and the order became available
11:25	AROUND_LOCATION INSIDE_LOCATION INSIDE_LOCATION_WINDOW ON_DEMAND INSIDE_WORKING_WINDOW INSIDE_EVENT_HARD_WINDOW	2 / 1 / 2 / 3	Waited for a performer change
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 opened
11:40	AROUND_LOCATION INSIDE_LOCATION INSIDE_LOCATION_WINDOW INSIDE_WORKING_WINDOW	2 / - / - / -	Finished working
11:45	AROUND_LOCATION DEPARTURE INSIDE_WORKING_WINDOW	2 / - / - / -	Left the parking
11:45	RELOCATING INSIDE_WORKING_WINDOW	- / - / - / -	Driving to the next order

Round trips

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

Planning configuration

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:

Name	Goal
optimize_distance	Place as many orders as possible, then optimize the total mileage (the number of transports is chosen based on the mileage); used by default
optimize_transports	Place as many orders as possible, while using as little transport as possible; all else being equal, optimize the working time of performers
optimize_locality_grouping	Place as many orders as possible, while striving to optimize visual route grouping but not the number of routes
optimize_cars_then_distance	Place as many orders as possible, then optimize the number of transports, then the mileage
optimize_time	Place as many orders as possible, then optimize the total working time of performers
optimize_cars_then_time	Place as many orders as possible, then optimize the number of transports, then the total working time of performers
optimize_money	Optimize "reward for completing orders − costs"; consists of rewards for demands and the costs of performers and transports (the optimized value is non-negative)

Additional configurations:

Name	Goal
visual_grouping	Place as many orders as possible, while using as little transport as possible, with visually grouped routes
optimize_visual_grouping	Place as many orders as possible, then evenly distribute orders taking transport accessibility zones into account (similar to visual_grouping but visual grouping is computed differently)
optimize_cars_then_locality_grouping	Place as many orders as possible, then optimize the number of transports, then the visual route grouping
optimize_cars_then_single_location_grouping_sequenced	Place as many orders as possible, then optimize the number of cars, then reliability

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.

Data validation

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.

Entity diagram

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

• API version: 7.37.3331
• Package version: 7.37.3331
• 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
• AdditionalAttributes
• AdditionalAttributesElement
• 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
• FactLore
• FactStatus
• FactType
• FeatureLifetime
• General402
• General403
• General404
• General404Detail
• General429
• General500
• GeneralStatistics
• GeoSettings
• Geopoint
• Hardlink
• HardlinkElement
• HardlinkElementType
• LoadStatistics
• Location
• LocationCargosLimit
• LocationCompatibilities
• LocationLimit
• LocationLimitStatistics
• LocationStatistics
• LocationTimetableElement
• LocationTransportsLimit
• LoreDemandCancelled
• LoreDemandDone
• LoreDemandStart
• LoreJobDone
• LoreNewLocation
• LoreOrderDone
• LoreTripPrecedenceChanged
• 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
• Trackpoint
• Transport
• TransportCapacityMultiplier
• TransportCompatibilities
• TransportLimits
• TransportLoad
• TransportShift
• TransportSpeedMultiplier
• TransportTariff
• TransportTariffConstraint
• TransportType
• Trip
• TripAssumptions
• TripDemandPrecedence
• 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]