@veeroute/[email protected]

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

The version of the OpenAPI document: 7.39.3350

Building

To install the required dependencies and to build the typescript sources run:

npm install
npm run build

Publishing

First build the package then run npm publish dist (don't forget to specify the dist folder!)

Consuming

Navigate to the folder of your consuming project and run one of next commands.

published:

npm install @veeroute/[email protected] --save

without publishing (not recommended):

npm install PATH_TO_GENERATED_PACKAGE/dist.tgz --save

It's important to take the tgz file, otherwise you'll get trouble with links on windows

using npm link:

In PATH_TO_GENERATED_PACKAGE/dist:

npm link

In your project:

npm link @veeroute/lss-universal-angular

Note for Windows users: The Angular CLI has troubles to use linked npm packages. Please refer to this issue https://github.com/angular/angular-cli/issues/8284 for a solution / workaround. Published packages are not effected by this issue.

General usage

In your Angular project:

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideApi } from '@veeroute/lss-universal-angular';

export const appConfig: ApplicationConfig = {
    providers: [
        // ...
        provideHttpClient(),
        provideApi()
    ],
};

NOTE If you're still using AppModule and haven't migrated yet, you can still import an Angular module:

import { LssUniversalApiModule } from '@veeroute/lss-universal-angular';

If different from the generated base path, during app bootstrap, you can provide the base path to your service.

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideApi } from '@veeroute/lss-universal-angular';

export const appConfig: ApplicationConfig = {
    providers: [
        // ...
        provideHttpClient(),
        provideApi('http://localhost:9999')
    ],
};

// with a custom configuration
import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideApi } from '@veeroute/lss-universal-angular';

export const appConfig: ApplicationConfig = {
    providers: [
        // ...
        provideHttpClient(),
        provideApi({
            withCredentials: true,
            username: 'user',
            password: 'password'
        })
    ],
};

// with factory building a custom configuration
import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { provideApi, Configuration } from '@veeroute/lss-universal-angular';

export const appConfig: ApplicationConfig = {
    providers: [
        // ...
        provideHttpClient(),
        {
            provide: Configuration,
            useFactory: (authService: AuthService) => new Configuration({
                    basePath: 'http://localhost:9999',
                    withCredentials: true,
                    username: authService.getUsername(),
                    password: authService.getPassword(),
            }),
            deps: [AuthService],
            multi: false
        }
    ],
};

Using multiple OpenAPI files / APIs

In order to use multiple APIs generated from different OpenAPI files, you can create an alias name when importing the modules in order to avoid naming conflicts:

import { provideApi as provideUserApi } from 'my-user-api-path';
import { provideApi as provideAdminApi } from 'my-admin-api-path';
import { HttpClientModule } from '@angular/common/http';
import { environment } from '../environments/environment';

export const appConfig: ApplicationConfig = {
    providers: [
        // ...
        provideHttpClient(),
        provideUserApi(environment.basePath),
        provideAdminApi(environment.basePath),
    ],
};

Customizing path parameter encoding

Without further customization, only path-parameters of style 'simple' and Dates for format 'date-time' are encoded correctly.

Other styles (e.g. "matrix") are not that easy to encode and thus are best delegated to other libraries (e.g.: @honoluluhenk/http-param-expander).

To implement your own parameter encoding (or call another library), pass an arrow-function or method-reference to the encodeParam property of the Configuration-object (see General Usage above).

Example value for use in your Configuration-Provider:

new Configuration({
    encodeParam: (param: Param) => myFancyParamEncoder(param),
})