Metadata-Version: 1.1
Name: kangrouter-py
Version: 1.0.3
Summary: Python client for the KangRouter transportation service optimizer.
Home-page: https://github.com/TheSolvingMachine/kangrouter-py
Author: TheSolvingMachine
Author-email: support@thesolvingmachine.com
License: Apache
Download-URL: https://github.com/TheSolvingMachine/kangrouter-py/tarball/1.0.3
Description: [![Build Status](https://travis-ci.org/TheSolvingMachine/kangrouter-py.svg?branch=master)](https://travis-ci.org/TheSolvingMachine/kangrouter-py)
        
        # kangrouter-py
        Python client for KangRouter. KangRouter is an application for large scale transportation service optimization (see https://thesolvingmachine.com/kangrouter). 
            
        ## Installation
        
        ```bash
        pip install kangrouter-py
        ```
        
        ## Usage
        
        ### Preliminaries
        For interacting with the API, both an *apiKey* and a *licenseId* are required. Please
        obtain them from https://thesolvingmachine.com/account.
        
        ### An example problem
        
        Input problems are described as a python dict. As a (simplistic) example, consider the problem of:
        * Taking [Alberto Caeiro](https://en.wikipedia.org/wiki/Fernando_Pessoa#Alberto_Caeiro) home after a medical appointment at the [Garcia de Orta Hospital](http://www.hgo.pt/). He is ready to leave the hospital after 13:00, and must be home no later than 14:15. Alberto is on a wheelchair, so we allocate 5 minutes for pickup and dropoff.
        * Picking [Ricardo Reis](https://en.wikipedia.org/wiki/Fernando_Pessoa#Ricardo_Reis) at the [Brasileira](https://en.wikipedia.org/wiki/Caf%C3%A9_A_Brasileira) café, and take him to a beach restaurant. He wants to be there no later than 12:15. Ricardo takes a regular seat.
        
        Assume that the vehicle available for transportation is parked in [Sintra](https://en.wikipedia.org/wiki/Sintra), has 3 seats and room for 2 wheelchairs.  Additionally, the driver must have a 60 minute lunch break between 12:00 and 14:00. 
        
        This problem translates to the following object:
        
        ```python
        problem = {
          "nbResources": 2,
          "jobs": [
            {
              "jobId": "Pickup Alberto at the hospital",
              "origLat": "38.674921",
              "origLon": "-9.175401",
              "destLat": "38.716860",
              "destLon": "-9.162417",
              "minStartTime": "13:00",
              "maxEndTime": "14:15",
              "pickupDuration": 5,
              "deliveryDuration": 5,
              "consumptions": [0,1]
            },
            {
              "jobId": "Take Ricardo to the beach",
              "origLat": "38.710835",
              "origLon": "-9.142143",
              "destLat": "38.634080",
              "destLon": "-9.230549",
              "maxEndTime": "12:15",
              "pickupDuration": 1,
              "deliveryDuration": 1,
              "consumptions": [1,0]
            }
          ],
          "vehicles": [
            {
              "vehicleId": "12-AS-46",
              "depotLat": "38.806842",
              "depotLon": "-9.382556",
              "minStartTime": "07:00",
              "maxEndTime": "22:00",
              "maxWorkDuration": 540,
              "capacities": [2,3],
              "breaks": [
                {
                  "breakId": "Lunch",
                  "minStartTime": "12:00",
                  "maxEndTime": "14:00",
                  "duration": 60
                }
              ],
              "overspeed": 1.25
            }
          ]
        }
        ```
        Interesting problems have multiple jobs and multiple vehicles, but the example above should be enough to get you going.
        
        ### Submit a problem
        
        The code below creates a new solver for the provided example:
        
        ```python
        from kangrouter import KangRouterClient
        api = KangRouterClient(apiKey,licenseId)
        solverId = api.create(problem)
        ```
        
        ### Check solving status
        
        After a solver is created it can be in one of 4 states:
        * pending - The solver is queued for execution but not started yet.
        * solving - The solver is executing.
        * completed - The solver has finished.
        * invalid - The problem is invalid, or an unexpected error has occurred.
        
        The function below is used to query the solver current state and obtain information regarding the solving progress:
        
        ```python
        status = api.getStatus(solverId)
        print(status)
        ```
        
        This is a very simple problem, so the solver executes very quickly:
        
        
        ```python
        {
          "execStatus": "completed",
          "nbJobsDiscarded": 0,
          "solverEndTime": "Wed Nov 18 11:59:48 2015 GMT",
          "solverStartTime": "Wed Nov 18 11:59:40 2015 GMT",
          "totalDistance": 98,
        }
        ```
        
        Given that larger problems may take a few minutes, calling this function while the solver is executing will also return ETA (expected delivery time) for completion.
        
        ### Get the solution
        
        When the solver is done, the solution may be retrieved as follows:
        
        ```python
        solution = api.getSolution(solverId)
        print(solution)
        ```
        
        The solution shows at what times, or time intervals, drivers must leave their depots, start their work breaks, or perform pickup/delivery actions:
        
        ```python
        {
          "jobsScheduled": [
            {
              "jobId": "Pickup Alberto at the hospital",
              "maxEndTime": "14:15",
              "maxStartTime": "13:55",
              "minEndTime": "13:20",
              "minStartTime": "13:00",
              "vehicleId": "12-AS-46"
            },
            {
              "jobId": "Take Ricardo to the beach",
              "maxEndTime": "12:15",
              "maxStartTime": "11:59",
              "minEndTime": "11:14",
              "minStartTime": "10:58",
              "vehicleId": "12-AS-46"
            }
          ],
          "type": "total",
          "vehiclesScheduled": [
            {
              "breaks": [
                {
                  "breakId": "Lunch",
                  "maxEndTime": "13:55",
                  "maxStartTime": "12:55",
                  "minEndTime": "13:00",
                  "minStartTime": "12:00"
                }
              ],
              "maxEndTime": "14:35",
              "maxStartTime": "11:38",
              "minEndTime": "13:40",
              "minStartTime": "10:37",
              "vehicleId": "12-AS-46"
            }
          ]
        }
        ```
        ### Other methods
        The remaining methods allow to stop a running solver, which might be useful if you're in a hurry:
        
        ```python
        api.stop(solverId)
        ```
        
        and remove a solver (and associated data) from the server:
        
        ```python
        api.delete(solverId)
        ```
        
        ## More documentation
        For a complete description of the KangRouter API please visit https://thesolvingmachine.com/swagger/kangrouter/srv/.
Keywords: Vehicle Routing With Time Windows,Pickup and Delivery,Optimization
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
