Skip to content
This repository was archived by the owner on Sep 5, 2023. It is now read-only.

Commit 8f753de

Browse files
jain-aayush1123jain-aayush1123
authored
add docs (#26)
1 parent 11ad5ef commit 8f753de

File tree

6 files changed

+315
-0
lines changed

6 files changed

+315
-0
lines changed

‎docs/notebooks/tour_planning.ipynb‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "code",
5+
"execution_count": null,
6+
"source": [
7+
"import os\n",
8+
"from here_location_services import LS"
9+
],
10+
"outputs": [],
11+
"metadata": {}
12+
},
13+
{
14+
"cell_type": "code",
15+
"execution_count": null,
16+
"source": [
17+
"os.environ[\"LS_API_KEY\"] = \"MY-API-KEY\" # replace your API key here."
18+
],
19+
"outputs": [],
20+
"metadata": {}
21+
},
22+
{
23+
"cell_type": "code",
24+
"execution_count": null,
25+
"source": [
26+
"from here_location_services.config.tour_planning_config import (\n",
27+
" VEHICLE_MODE,\n",
28+
" Fleet,\n",
29+
" Job,\n",
30+
" JobPlaces,\n",
31+
" Plan,\n",
32+
" Relation,\n",
33+
" VehicleProfile,\n",
34+
" VehicleType,\n",
35+
")\n",
36+
"\n",
37+
"LS_API_KEY = os.environ.get(\"LS_API_KEY\") # Get API KEY from environment.\n",
38+
"ls = LS(api_key=LS_API_KEY)\n",
39+
"\n",
40+
"fleet = Fleet(\n",
41+
" vehicle_types=[\n",
42+
" VehicleType(\n",
43+
" id=\"09c77738-1dba-42f1-b00e-eb63da7147d6\",\n",
44+
" profile_name=\"normal_car\",\n",
45+
" costs_fixed=22,\n",
46+
" costs_distance=0.0001,\n",
47+
" costs_time=0.0048,\n",
48+
" capacity=[100, 5],\n",
49+
" skills=[\"fridge\"],\n",
50+
" amount=1,\n",
51+
" shift_start={\n",
52+
" \"time\": \"2020-07-04T09:00:00Z\",\n",
53+
" \"location\": {\"lat\": 52.5256, \"lng\": 13.4542},\n",
54+
" },\n",
55+
" limits={\"maxDistance\": 20000, \"shiftTime\": 21600},\n",
56+
" shift_end={\n",
57+
" \"location\": {\"lat\": 52.5256, \"lng\": 13.4542},\n",
58+
" \"time\": \"2020-07-04T18:00:00Z\",\n",
59+
" },\n",
60+
" shift_breaks=[\n",
61+
" {\n",
62+
" \"duration\": 1800,\n",
63+
" \"times\": [[\"2020-07-04T11:00:00Z\", \"2020-07-04T13:00:00Z\"]],\n",
64+
" }\n",
65+
" ],\n",
66+
" )\n",
67+
" ],\n",
68+
" vehicle_profiles=[VehicleProfile(name=\"normal_car\", vehicle_mode=VEHICLE_MODE.car)],\n",
69+
")\n",
70+
"\n",
71+
"plan = Plan(\n",
72+
" jobs=[\n",
73+
" Job(\n",
74+
" id=\"4bbc206d-1583-4266-bac9-d1580f412ac0\",\n",
75+
" pickups=[\n",
76+
" JobPlaces(\n",
77+
" duration=180,\n",
78+
" demand=[10],\n",
79+
" location=(52.53088, 13.38471),\n",
80+
" times=[[\"2020-07-04T10:00:00Z\", \"2020-07-04T12:00:00Z\"]],\n",
81+
" )\n",
82+
" ],\n",
83+
" deliveries=[\n",
84+
" JobPlaces(\n",
85+
" duration=300,\n",
86+
" demand=[10],\n",
87+
" location=(52.53088, 13.38471),\n",
88+
" times=[[\"2020-07-04T14:00:00Z\", \"2020-07-04T16:00:00Z\"]],\n",
89+
" )\n",
90+
" ],\n",
91+
" skills=[\"fridge\"],\n",
92+
" priority=2,\n",
93+
" )\n",
94+
" ],\n",
95+
" relations=[\n",
96+
" Relation(\n",
97+
" type=\"sequence\",\n",
98+
" jobs=[\"departure\", \"4bbc206d-1583-4266-bac9-d1580f412ac0\", \"arrival\"],\n",
99+
" vehicle_id=\"09c77738-1dba-42f1-b00e-eb63da7147d6_1\",\n",
100+
" )\n",
101+
" ],\n",
102+
")\n",
103+
"\n",
104+
"# Synchronous Solving\n",
105+
"response = ls.solve_tour_planning(\n",
106+
" fleet=fleet, plan=plan, id=\"7f3423c2-784a-4983-b472-e14107d5a54a\"\n",
107+
")\n",
108+
"print(response)"
109+
],
110+
"outputs": [],
111+
"metadata": {}
112+
},
113+
{
114+
"cell_type": "code",
115+
"execution_count": null,
116+
"source": [
117+
"# Asynchronous Solving\n",
118+
"async_response = ls.solve_tour_planning(\n",
119+
" fleet=fleet, \n",
120+
" plan=plan, \n",
121+
" id=\"7f3423c2-784a-4983-b472-e14107d5a54a\",\n",
122+
" is_async=True\n",
123+
")\n",
124+
"print(async_response)"
125+
],
126+
"outputs": [],
127+
"metadata": {}
128+
},
129+
{
130+
"cell_type": "code",
131+
"execution_count": null,
132+
"source": [],
133+
"outputs": [],
134+
"metadata": {}
135+
}
136+
],
137+
"metadata": {
138+
"orig_nbformat": 4,
139+
"language_info": {
140+
"name": "python",
141+
"version": "3.9.6",
142+
"mimetype": "text/x-python",
143+
"codemirror_mode": {
144+
"name": "ipython",
145+
"version": 3
146+
},
147+
"pygments_lexer": "ipython3",
148+
"nbconvert_exporter": "python",
149+
"file_extension": ".py"
150+
},
151+
"kernelspec": {
152+
"name": "python3",
153+
"display_name": "Python 3.9.6 64-bit"
154+
},
155+
"interpreter": {
156+
"hash": "aee8b7b246df8f9039afb4144a1f6fd8d2ca17a180786b69acc140d282b71a49"
157+
}
158+
},
159+
"nbformat": 4,
160+
"nbformat_minor": 2
161+
}

‎docs/source/here_location_services.config.tour_planning_config.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
here\_location\_services.config.tour\_planning\_config module
2+
=============================================================
3+
4+
.. automodule:: here_location_services.config.tour_planning_config
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:
8+
:private-members:

‎docs/source/here_location_services.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,5 @@ Submodules
3535
here_location_services.utils
3636
here_location_services.platform
3737
here_location_services.destination_weather_api.rst
38+
here_location_services.config.tour_planning_config
39+
here_location_services.tour_planning_api

‎docs/source/here_location_services.tour_planning_api.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
here\_location\_services.tour\_planning\_api module
2+
===================================================
3+
4+
.. automodule:: here_location_services.tour_planning_api
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:
8+
:private-members:

‎docs/source/index.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,12 @@ A Python client for `HERE Location Services`_.
4242

4343
Destination Weather <dest_weather>
4444

45+
.. toctree::
46+
:maxdepth: 1
47+
:caption: Tour Planning
48+
49+
Tour Planning <tour_planning>
50+
4551
.. toctree::
4652
:maxdepth: 1
4753
:caption: Reference Guide

‎docs/source/tour_planning.rst‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
Tour Planning
2+
===============
3+
`Tour Planning API <https://developer.here.com/documentation/tour-planning/2.3.0/dev_guide/index.html>`_
4+
The HERE Tour Planning API allows you to dynamically optimize routes for multiple vehicles visiting a set of locations given real-life constraints, such as limited capacity in a vehicle or delivery time windows.
5+
6+
The HERE Tour Planning API supports the following use cases:
7+
8+
- Capacitated vehicle routing problem: You can use Tour Planning API to take your vehicle capacity into account when routing your vehicles.
9+
- Vehicle routing problem with time windows: With Tour Planning API, you can schedule your vehicles to visit depots only when they are available.
10+
- Multi-depot vehicle routing problem: In a simple vehicle routing problem, all vehicles start from the same location. In the multi-depot vehicle routing problem, vehicles start from multiple depots and return to their depots of origin at the end of their assigned tours.
11+
- Open vehicle routing problem: Do you work with drivers who have their vehicles and do not return to a planned location after their drop-offs? With Tour Planning API, you can schedule open vehicle routing where your drivers can return to their homes after work.
12+
- Heterogeneous or mixed fleet VRP: Tour Planning API supports routing multiple types of vehicles with different gas mileage, cost of driving, capacity, and more. For example, your fleet can include passenger vehicles and even specialized trucks with fridges in one route.
13+
- Pick up and delivery vehicle routing problem: With Tour Planning API, you can schedule a vehicle to pick up and deliver an item in one route.
14+
- Vehicle routing problem with priorities: Do you have jobs that must be served, such as today, and others that could also be delayed until, such as until tomorrow, and ideally you would like to prevent those priority jobs from being skipped in cases where fleet capacity or shift durations do not allow to serve all jobs, but at the same time you would like to serve as many non-priority jobs as possible? With Tour Planning API, you can define jobs to be with high priority internally the algorithms will try to avoid skipping those high priority jobs and will skip low priority jobs first in scenarios where it is impossible to serve all jobs due to constraints. The priority of a job does not imply its order in the route, as in the position of a high priority job might be anywhere in the route and not necessarily before lower priority jobs.
15+
16+
17+
Example
18+
-------
19+
20+
.. jupyter-execute::
21+
22+
import os
23+
24+
from here_location_services import LS
25+
from here_location_services.config.tour_planning_config import (
26+
VEHICLE_MODE,
27+
Fleet,
28+
Job,
29+
JobPlaces,
30+
Plan,
31+
Relation,
32+
VehicleProfile,
33+
VehicleType,
34+
)
35+
LS_API_KEY = os.environ.get("LS_API_KEY") # Get API KEY from environment.
36+
ls = LS(api_key=LS_API_KEY)
37+
38+
39+
fleet = Fleet(
40+
vehicle_types=[
41+
VehicleType(
42+
id="09c77738-1dba-42f1-b00e-eb63da7147d6",
43+
profile_name="normal_car",
44+
costs_fixed=22,
45+
costs_distance=0.0001,
46+
costs_time=0.0048,
47+
capacity=[100, 5],
48+
skills=["fridge"],
49+
amount=1,
50+
shift_start={
51+
"time": "2020-07-04T09:00:00Z",
52+
"location": {"lat": 52.5256, "lng": 13.4542},
53+
},
54+
limits={"maxDistance": 20000, "shiftTime": 21600},
55+
shift_end={
56+
"location": {"lat": 52.5256, "lng": 13.4542},
57+
"time": "2020-07-04T18:00:00Z",
58+
},
59+
shift_breaks=[
60+
{
61+
"duration": 1800,
62+
"times": [["2020-07-04T11:00:00Z", "2020-07-04T13:00:00Z"]],
63+
}
64+
],
65+
)
66+
],
67+
vehicle_profiles=[VehicleProfile(name="normal_car", vehicle_mode=VEHICLE_MODE.car)],
68+
)
69+
70+
plan = Plan(
71+
jobs=[
72+
Job(
73+
id="4bbc206d-1583-4266-bac9-d1580f412ac0",
74+
pickups=[
75+
JobPlaces(
76+
duration=180,
77+
demand=[10],
78+
location=(52.53088, 13.38471),
79+
times=[["2020-07-04T10:00:00Z", "2020-07-04T12:00:00Z"]],
80+
)
81+
],
82+
deliveries=[
83+
JobPlaces(
84+
duration=300,
85+
demand=[10],
86+
location=(52.53088, 13.38471),
87+
times=[["2020-07-04T14:00:00Z", "2020-07-04T16:00:00Z"]],
88+
)
89+
],
90+
skills=["fridge"],
91+
priority=2,
92+
)
93+
],
94+
relations=[
95+
Relation(
96+
type="sequence",
97+
jobs=["departure", "4bbc206d-1583-4266-bac9-d1580f412ac0", "arrival"],
98+
vehicle_id="09c77738-1dba-42f1-b00e-eb63da7147d6_1",
99+
)
100+
],
101+
)
102+
103+
# Synchronous Solving
104+
response = ls.solve_tour_planning(
105+
fleet=fleet, plan=plan, id="7f3423c2-784a-4983-b472-e14107d5a54a"
106+
)
107+
print(response)
108+
109+
# Asynchronous Solving
110+
async_response = ls.solve_tour_planning(
111+
fleet=fleet,
112+
plan=plan,
113+
id="7f3423c2-784a-4983-b472-e14107d5a54a",
114+
is_async=True
115+
)
116+
print(async_response)
117+
118+
Attributes
119+
----------
120+
121+
=========================== ======================================================================================= ===
122+
Attribute Type Doc
123+
=========================== ======================================================================================= ===
124+
fleet :class:`Fleet <here_location_services.config.tour_planning_config.Fleet>` A fleet represented by various vehicle types for serving jobs.
125+
plan :class:`Plan <here_location_services.config.tour_planning_config.Plan>` Represents the list of jobs to be served.
126+
id string optional A unique identifier of an entity. Avoid referencing any confidential or personal information as part of the Id.
127+
optimization_traffic string optional "liveOrHistorical" "historicalOnly" "automatic" Specifies what kind of traffic information should be considered for routing
128+
optimization_waiting_time Dict optional Configures departure time optimization which tries to adapt the starting time of the tour in order to reduce waiting time as a consequence of a vehicle arriving at a stop before the starting time of the time window defined for serving the job.
129+
is_async bool optional Solves the problem Asynchronously
130+
=========================== ======================================================================================= ===

0 commit comments

Comments
 (0)