Templates

Introduction

The Nextmv SDK templates provide all of the files required to publish an optimization model as a Nextmv app. This guide will walk you through our template structure. For a list of existing templates, check out the full list of available templates below.

Available templates

Focus Area	Template Name	Use Case
vehicle routing	`nextroute`	Solves a VRP for delivery, distribution, and sourcing problems
vehicle routing	`routing`	Solves a VRP for delivery, distribution, and sourcing problems
vehicle routing	`routing-matrix-input`	Solves a VRP using a custom matrix
vehicle routing	`measure-matrix`	Input generator for the `routing-matrix-input` template
vehicle routing	`time-dependent-measure`	Solves a VRP for measures dependent on time (ie. time windows)
vehicle routing	`unique-matrix-measure`	Solves a VRP with a unique matrix that reduces input size
vehicle routing	`cloud-routing`	Solves a VRP for existing Nextmv routing app customers
clustering	`cluster`	Groups a set of data points into clusters based on similarities
clustering	`cluster-tsp`	Creates a set of clusters equal to the number of vehicles, then solves a TSP for each vehicle
packing	`knapsack`	Maximizes the total value without exceeding weight capacity, given a collection of items with a value and weight
packing	`mip-knapsack`	Solves the `knapsack` problem using Mixed Integer Programming
scheduling	`shift-scheduling`	Assigns one worker to each shift while maximizing worker happiness
scheduling	`pager-duty`	Assigns users to shifts for incident response on-call duty using input and output data structures compatible with PagerDuty API
custom	`new-app`	Provides a skeleton for creating a completely custom model
puzzle	`sudoku`	Fills a 9x9 grid such that all columns and all 3x3 subgrids contain the numerals 1 through 9
allocation	`mip-meal-allocation`	Demonstrates how to solve a Mixed Integer Programming problem using Nextmv

Template Overview

We'll use the nextroute template as our example, but every template will follow the same pattern. To initialize the template, run the following command from your terminal:

Bash

nextmv sdk init -t nextroute

Change directories into the newly created template folder.

Bash

cd nextroute

The following table shows the files that are created under the nextroute folder.

file	description
`LICENSE`	Contains the Apache License 2.0 under which we distribute this template.
`README.md`	Gives a short introduction to the problem and shows you how to run the template.
`go.mod` and `go.sum`	Define a Go module and are used to manage dependencies, including the Nextmv SDK.
`input.json`	Describes the input data for a specific problem that is solved by the template.
`main.go`	Contains the actual code of the template.
`.code-workspace`	This file should be used to open the template in Visual Studio Code. It is pre-configured for you so that you can run and debug the template without any further steps.

Now you can run the template with the Nextmv CLI, reading from the input.json file and writing to an output.json file. The following command shows you how to specify other options as well.

Bash

nextmv sdk run . -- -runner.input.path input.json -runner.output.path output.json -solve.duration 10s

Input File

The input.json file lists the required fields that will be ingested into the model. These include:

actors - available players to utilize in the solution, for routing, this includes Vehicles and Stops, but could also include employees (scheduling), objects (packing), etc
constraints - specific requirements that must be met. This includes things like volume and weight limit, time windows, etc

JSON

{
  "defaults": {
    "vehicles": {
      "capacity": {
        "bunnies": 20,
        "rabbits": 10
      },
      "start_location": {
        "lat": 35.791729813680874,
        "lon": -78.7401685145487
      },
      "end_location": {
        "lat": 35.791729813680874,
        "lon": -78.7401685145487
      },
      "speed": 10
    },
    "stops": {
      "duration": 300,
      "quantity": {
        "bunnies": -1,
        "rabbits": -1
      },
      "unplanned_penalty": 200000,
      "target_arrival_time": "2023-01-01T10:00:00Z",
      "early_arrival_time_penalty": 1.5,
      "late_arrival_time_penalty": 1.5
    }
  },
  "stops": [
    {
      "id": "s1",
      "location": {
        "lon": -78.90919,
        "lat": 35.72389
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s2",
      "location": {
        "lon": -78.813862,
        "lat": 35.75712
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s3",
      "location": {
        "lon": -78.92996,
        "lat": 35.932795
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s4",
      "location": {
        "lon": -78.505745,
        "lat": 35.77772
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s5",
      "location": {
        "lon": -78.75084,
        "lat": 35.732995
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s6",
      "location": {
        "lon": -78.788025,
        "lat": 35.813025
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s7",
      "location": {
        "lon": -78.749391,
        "lat": 35.74261
      },
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "s8",
      "location": {
        "lon": -78.94658,
        "lat": 36.039135
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s9",
      "location": {
        "lon": -78.64972,
        "lat": 35.64796
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s10",
      "location": {
        "lon": -78.747955,
        "lat": 35.672955
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s11",
      "location": {
        "lon": -78.83403,
        "lat": 35.77013
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s12",
      "location": {
        "lon": -78.864465,
        "lat": 35.782855
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s13",
      "location": {
        "lon": -78.952142,
        "lat": 35.88029
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s14",
      "location": {
        "lon": -78.52748,
        "lat": 35.961465
      },
      "compatibility_attributes": ["basic"]
    },
    {
      "id": "s15",
      "location": {
        "lon": -78.89832,
        "lat": 35.83202
      }
    },
    {
      "id": "s16",
      "location": {
        "lon": -78.63216,
        "lat": 35.83458
      }
    },
    {
      "id": "s17",
      "location": {
        "lon": -78.76063,
        "lat": 35.67337
      }
    },
    {
      "id": "s18",
      "location": {
        "lon": -78.911485,
        "lat": 36.009015
      }
    },
    {
      "id": "s19",
      "location": {
        "lon": -78.522705,
        "lat": 35.93663
      }
    },
    {
      "id": "s20",
      "location": {
        "lon": -78.995162,
        "lat": 35.97414
      }
    },
    {
      "id": "s21",
      "location": {
        "lon": -78.50509,
        "lat": 35.7606
      }
    },
    {
      "id": "s22",
      "location": {
        "lon": -78.828547,
        "lat": 35.962635
      },
      "precedes": ["s16", "s23"]
    },
    {
      "id": "s23",
      "location": {
        "lon": -78.60914,
        "lat": 35.84616
      },
      "start_time_window": [
        "2023-01-01T09:00:00-06:00",
        "2023-01-01T09:30:00-06:00"
      ]
    },
    {
      "id": "s24",
      "location": {
        "lon": -78.65521,
        "lat": 35.740605
      },
      "start_time_window": [
        "2023-01-01T09:00:00-06:00",
        "2023-01-01T09:30:00-06:00"
      ],
      "succeeds": "s25"
    },
    {
      "id": "s25",
      "location": {
        "lon": -78.92051,
        "lat": 35.887575
      },
      "start_time_window": [
        "2023-01-01T09:00:00-06:00",
        "2023-01-01T09:30:00-06:00"
      ],
      "precedes": "s26"
    },
    {
      "id": "s26",
      "location": {
        "lon": -78.84058,
        "lat": 35.823865
      },
      "start_time_window": [
        "2023-01-01T09:00:00-06:00",
        "2023-01-01T09:30:00-06:00"
      ]
    }
  ],
  "vehicles": [
    {
      "id": "vehicle-0",
      "start_time": "2023-01-01T06:00:00-06:00",
      "end_time": "2023-01-01T10:00:00-06:00",
      "activation_penalty": 4000,
      "compatibility_attributes": ["premium"]
    },
    {
      "id": "vehicle-1",
      "start_time": "2023-01-01T10:00:00-06:00",
      "end_time": "2023-01-01T16:00:00-06:00",
      "max_duration": 21000,
      "compatibility_attributes": ["basic"]
    }
  ]
}

Output File

The output.json file returns the results of the model based on the inputs. There are three main sections in the output file:

options - returns the options defined for the run; like run duration, solver type, etc
solutions - prints the results of the run
statistics - prints the statistics around the solution(s) found
version - returns the version of SDK that was used for the run

JSON

{
  "options": {
    "format": {
      "disable": {
        "progression": true
      }
    },
    "model": {
      "constraints": {
        "disable": {
          "attributes": false,
          "capacity": false,
          "distance_limit": false,
          "groups": false,
          "maximum_duration": false,
          "maximum_stops": false,
          "maximum_wait_stop": false,
          "maximum_wait_vehicle": false,
          "precedence": false,
          "start_time_windows": false,
          "vehicle_end_time": false,
          "vehicle_start_time": false
        },
        "enable": {
          "cluster": false
        }
      },
      "objectives": {
        "cluster": 0,
        "early_arrival_penalty": 1,
        "late_arrival_penalty": 1,
        "min_stops": 1,
        "travel_duration": 0,
        "unplanned_penalty": 1,
        "vehicle_activation_penalty": 1,
        "vehicles_duration": 1
      },
      "properties": {
        "disable": {
          "duration_groups": false,
          "durations": false,
          "initial_solution": false,
          "stop_duration_multipliers": false
        }
      },
      "validate": {
        "disable": {
          "resources": false,
          "start_time": false
        },
        "enable": {
          "matrix": false,
          "matrix_asymmetry_tolerance": 20
        }
      }
    },
    "solve": {
      "duration": 10000000000,
      "iterations": 50,
      "parallel_runs": 1,
      "run_deterministically": true,
      "start_solutions": 1
    }
  },
  "solutions": [
    {
      "objective": {
        "name": "1 * vehicle_activation_penalty + 1 * vehicles_duration + 1 * unplanned_penalty + 1 * early_arrival_penalty + 1 * late_arrival_penalty",
        "objectives": [
          {
            "base": 4000,
            "factor": 1,
            "name": "vehicle_activation_penalty",
            "value": 4000
          },
          {
            "base": 34394.3133084774,
            "factor": 1,
            "name": "vehicles_duration",
            "value": 34394.3133084774
          },
          {
            "base": 1400000,
            "factor": 1,
            "name": "unplanned_penalty",
            "value": 1400000
          },
          {
            "factor": 1,
            "name": "early_arrival_penalty",
            "value": 0
          },
          {
            "base": 621271.1251366138,
            "factor": 1,
            "name": "late_arrival_penalty",
            "value": 621271.1251366138
          }
        ],
        "value": 2059665.4384450912
      },
      "unplanned": [
        {
          "id": "s22",
          "location": {
            "lat": 35.962635,
            "lon": -78.828547
          }
        },
        {
          "id": "s16",
          "location": {
            "lat": 35.83458,
            "lon": -78.63216
          }
        },
        {
          "id": "s23",
          "location": {
            "lat": 35.84616,
            "lon": -78.60914
          }
        },
        {
          "id": "s25",
          "location": {
            "lat": 35.887575,
            "lon": -78.92051
          }
        },
        {
          "id": "s24",
          "location": {
            "lat": 35.740605,
            "lon": -78.65521
          }
        },
        {
          "id": "s26",
          "location": {
            "lat": 35.823865,
            "lon": -78.84058
          }
        },
        {
          "id": "s4",
          "location": {
            "lat": 35.77772,
            "lon": -78.505745
          }
        }
      ],
      "vehicles": [
        {
          "id": "vehicle-0",
          "route": [
            {
              "arrival_time": "2023-01-01T06:00:00-06:00",
              "cumulative_travel_duration": 0,
              "end_time": "2023-01-01T06:00:00-06:00",
              "start_time": "2023-01-01T06:00:00-06:00",
              "stop": {
                "id": "vehicle-0-start",
                "location": {
                  "lat": 35.791729813680874,
                  "lon": -78.7401685145487
                }
              },
              "travel_duration": 0
            },
            {
              "arrival_time": "2023-01-01T06:09:12-06:00",
              "cumulative_travel_distance": 5524,
              "cumulative_travel_duration": 552,
              "duration": 300,
              "end_time": "2023-01-01T06:14:12-06:00",
              "late_arrival_duration": 7752,
              "start_time": "2023-01-01T06:09:12-06:00",
              "stop": {
                "id": "s7",
                "location": {
                  "lat": 35.74261,
                  "lon": -78.749391
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 5524,
              "travel_duration": 552
            },
            {
              "arrival_time": "2023-01-01T06:28:29-06:00",
              "cumulative_travel_distance": 14094,
              "cumulative_travel_duration": 1409,
              "duration": 300,
              "end_time": "2023-01-01T06:33:29-06:00",
              "late_arrival_duration": 8909,
              "start_time": "2023-01-01T06:28:29-06:00",
              "stop": {
                "id": "s6",
                "location": {
                  "lat": 35.813025,
                  "lon": -78.788025
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 8570,
              "travel_duration": 857
            },
            {
              "arrival_time": "2023-01-01T06:49:20-06:00",
              "cumulative_travel_distance": 23604,
              "cumulative_travel_duration": 2360,
              "duration": 300,
              "end_time": "2023-01-01T06:54:20-06:00",
              "late_arrival_duration": 10160,
              "start_time": "2023-01-01T06:49:20-06:00",
              "stop": {
                "id": "s5",
                "location": {
                  "lat": 35.732995,
                  "lon": -78.75084
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 9510,
              "travel_duration": 951
            },
            {
              "arrival_time": "2023-01-01T07:05:29-06:00",
              "cumulative_travel_distance": 30292,
              "cumulative_travel_duration": 3029,
              "duration": 300,
              "end_time": "2023-01-01T07:10:29-06:00",
              "late_arrival_duration": 11129,
              "start_time": "2023-01-01T07:05:29-06:00",
              "stop": {
                "id": "s17",
                "location": {
                  "lat": 35.67337,
                  "lon": -78.76063
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 6688,
              "travel_duration": 668
            },
            {
              "arrival_time": "2023-01-01T07:34:43-06:00",
              "cumulative_travel_distance": 44835,
              "cumulative_travel_duration": 4483,
              "duration": 300,
              "end_time": "2023-01-01T07:39:43-06:00",
              "late_arrival_duration": 12883,
              "start_time": "2023-01-01T07:34:43-06:00",
              "stop": {
                "id": "s1",
                "location": {
                  "lat": 35.72389,
                  "lon": -78.90919
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 14543,
              "travel_duration": 1454
            },
            {
              "arrival_time": "2023-01-01T07:55:20-06:00",
              "cumulative_travel_distance": 54198,
              "cumulative_travel_duration": 5420,
              "duration": 300,
              "end_time": "2023-01-01T08:00:20-06:00",
              "late_arrival_duration": 14120,
              "start_time": "2023-01-01T07:55:20-06:00",
              "stop": {
                "id": "s2",
                "location": {
                  "lat": 35.75712,
                  "lon": -78.813862
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 9363,
              "travel_duration": 936
            },
            {
              "arrival_time": "2023-01-01T08:19:08-06:00",
              "cumulative_travel_distance": 65484,
              "cumulative_travel_duration": 6548,
              "duration": 300,
              "end_time": "2023-01-01T08:24:08-06:00",
              "late_arrival_duration": 15548,
              "start_time": "2023-01-01T08:19:08-06:00",
              "stop": {
                "id": "s15",
                "location": {
                  "lat": 35.83202,
                  "lon": -78.89832
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 11286,
              "travel_duration": 1128
            },
            {
              "arrival_time": "2023-01-01T08:43:25-06:00",
              "cumulative_travel_distance": 77046,
              "cumulative_travel_duration": 7705,
              "duration": 300,
              "end_time": "2023-01-01T08:48:25-06:00",
              "late_arrival_duration": 17005,
              "start_time": "2023-01-01T08:43:25-06:00",
              "stop": {
                "id": "s3",
                "location": {
                  "lat": 35.932795,
                  "lon": -78.92996
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 11562,
              "travel_duration": 1156
            },
            {
              "arrival_time": "2023-01-01T09:02:48-06:00",
              "cumulative_travel_distance": 85682,
              "cumulative_travel_duration": 8568,
              "duration": 300,
              "end_time": "2023-01-01T09:07:48-06:00",
              "late_arrival_duration": 18168,
              "start_time": "2023-01-01T09:02:48-06:00",
              "stop": {
                "id": "s18",
                "location": {
                  "lat": 36.009015,
                  "lon": -78.911485
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 8636,
              "travel_duration": 863
            },
            {
              "arrival_time": "2023-01-01T09:55:35-06:00",
              "cumulative_travel_distance": 114350,
              "cumulative_travel_duration": 11435,
              "end_time": "2023-01-01T09:55:35-06:00",
              "start_time": "2023-01-01T09:55:35-06:00",
              "stop": {
                "id": "vehicle-0-end",
                "location": {
                  "lat": 35.791729813680874,
                  "lon": -78.7401685145487
                }
              },
              "travel_distance": 28668,
              "travel_duration": 2866
            }
          ],
          "route_duration": 14135,
          "route_stops_duration": 2700,
          "route_travel_distance": 114350,
          "route_travel_duration": 11435
        },
        {
          "id": "vehicle-1",
          "route": [
            {
              "arrival_time": "2023-01-01T10:00:00-06:00",
              "cumulative_travel_duration": 0,
              "end_time": "2023-01-01T10:00:00-06:00",
              "start_time": "2023-01-01T10:00:00-06:00",
              "stop": {
                "id": "vehicle-1-start",
                "location": {
                  "lat": 35.791729813680874,
                  "lon": -78.7401685145487
                }
              },
              "travel_duration": 0
            },
            {
              "arrival_time": "2023-01-01T10:14:40-06:00",
              "cumulative_travel_distance": 8801,
              "cumulative_travel_duration": 880,
              "duration": 300,
              "end_time": "2023-01-01T10:19:40-06:00",
              "late_arrival_duration": 22480,
              "start_time": "2023-01-01T10:14:40-06:00",
              "stop": {
                "id": "s11",
                "location": {
                  "lat": 35.77013,
                  "lon": -78.83403
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 8801,
              "travel_duration": 880
            },
            {
              "arrival_time": "2023-01-01T10:24:48-06:00",
              "cumulative_travel_distance": 11889,
              "cumulative_travel_duration": 1188,
              "duration": 300,
              "end_time": "2023-01-01T10:29:48-06:00",
              "late_arrival_duration": 23088,
              "start_time": "2023-01-01T10:24:48-06:00",
              "stop": {
                "id": "s12",
                "location": {
                  "lat": 35.782855,
                  "lon": -78.864465
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 3088,
              "travel_duration": 308
            },
            {
              "arrival_time": "2023-01-01T10:56:41-06:00",
              "cumulative_travel_distance": 28011,
              "cumulative_travel_duration": 2801,
              "duration": 300,
              "end_time": "2023-01-01T11:01:41-06:00",
              "late_arrival_duration": 25001,
              "start_time": "2023-01-01T10:56:41-06:00",
              "stop": {
                "id": "s10",
                "location": {
                  "lat": 35.672955,
                  "lon": -78.747955
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 16122,
              "travel_duration": 1612
            },
            {
              "arrival_time": "2023-01-01T11:17:11-06:00",
              "cumulative_travel_distance": 37310,
              "cumulative_travel_duration": 3731,
              "duration": 300,
              "end_time": "2023-01-01T11:22:11-06:00",
              "late_arrival_duration": 26231,
              "start_time": "2023-01-01T11:17:11-06:00",
              "stop": {
                "id": "s9",
                "location": {
                  "lat": 35.64796,
                  "lon": -78.64972
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 9299,
              "travel_duration": 929
            },
            {
              "arrival_time": "2023-01-01T11:52:20-06:00",
              "cumulative_travel_distance": 55404,
              "cumulative_travel_duration": 5540,
              "duration": 300,
              "end_time": "2023-01-01T11:57:20-06:00",
              "late_arrival_duration": 28340,
              "start_time": "2023-01-01T11:52:20-06:00",
              "stop": {
                "id": "s21",
                "location": {
                  "lat": 35.7606,
                  "lon": -78.50509
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 18094,
              "travel_duration": 1809
            },
            {
              "arrival_time": "2023-01-01T12:34:43-06:00",
              "cumulative_travel_distance": 77830,
              "cumulative_travel_duration": 7783,
              "duration": 300,
              "end_time": "2023-01-01T12:39:43-06:00",
              "late_arrival_duration": 30883,
              "start_time": "2023-01-01T12:34:43-06:00",
              "stop": {
                "id": "s14",
                "location": {
                  "lat": 35.961465,
                  "lon": -78.52748
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 22426,
              "travel_duration": 2242
            },
            {
              "arrival_time": "2023-01-01T12:44:22-06:00",
              "cumulative_travel_distance": 80624,
              "cumulative_travel_duration": 8062,
              "duration": 300,
              "end_time": "2023-01-01T12:49:22-06:00",
              "late_arrival_duration": 31462,
              "start_time": "2023-01-01T12:44:22-06:00",
              "stop": {
                "id": "s19",
                "location": {
                  "lat": 35.93663,
                  "lon": -78.522705
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 2794,
              "travel_duration": 279
            },
            {
              "arrival_time": "2023-01-01T13:54:40-06:00",
              "cumulative_travel_distance": 119804,
              "cumulative_travel_duration": 11980,
              "duration": 300,
              "end_time": "2023-01-01T13:59:40-06:00",
              "late_arrival_duration": 35680,
              "start_time": "2023-01-01T13:54:40-06:00",
              "stop": {
                "id": "s13",
                "location": {
                  "lat": 35.88029,
                  "lon": -78.952142
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 39180,
              "travel_duration": 3918
            },
            {
              "arrival_time": "2023-01-01T14:18:14-06:00",
              "cumulative_travel_distance": 130935,
              "cumulative_travel_duration": 13094,
              "duration": 300,
              "end_time": "2023-01-01T14:23:14-06:00",
              "late_arrival_duration": 37094,
              "start_time": "2023-01-01T14:18:14-06:00",
              "stop": {
                "id": "s20",
                "location": {
                  "lat": 35.97414,
                  "lon": -78.995162
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 11131,
              "travel_duration": 1113
            },
            {
              "arrival_time": "2023-01-01T14:37:18-06:00",
              "cumulative_travel_distance": 139380,
              "cumulative_travel_duration": 13938,
              "duration": 300,
              "end_time": "2023-01-01T14:42:18-06:00",
              "late_arrival_duration": 38238,
              "start_time": "2023-01-01T14:37:18-06:00",
              "stop": {
                "id": "s8",
                "location": {
                  "lat": 36.039135,
                  "lon": -78.94658
                }
              },
              "target_arrival_time": "2023-01-01T04:00:00-06:00",
              "travel_distance": 8445,
              "travel_duration": 844
            },
            {
              "arrival_time": "2023-01-01T15:37:38-06:00",
              "cumulative_travel_distance": 172581,
              "cumulative_travel_duration": 17258,
              "end_time": "2023-01-01T15:37:38-06:00",
              "start_time": "2023-01-01T15:37:38-06:00",
              "stop": {
                "id": "vehicle-1-end",
                "location": {
                  "lat": 35.791729813680874,
                  "lon": -78.7401685145487
                }
              },
              "travel_distance": 33201,
              "travel_duration": 3320
            }
          ],
          "route_duration": 20258,
          "route_stops_duration": 3000,
          "route_travel_distance": 172581,
          "route_travel_duration": 17258
        }
      ]
    }
  ],
  "statistics": {
    "result": {
      "custom": {
        "activated_vehicles": 2,
        "max_duration": 20258,
        "max_stops_in_vehicle": 10,
        "max_travel_duration": 17258,
        "min_duration": 14135,
        "min_stops_in_vehicle": 9,
        "min_travel_duration": 11435,
        "unplanned_stops": 3
      },
      "duration": 0.123200958,
      "value": 2059665.4384450912
    },
    "run": {
      "duration": 0.124943291,
      "iterations": 50
    },
    "schema": "v1"
  },
  "version": {
    "sdk": "VERSION"
  }
}

Continue reading to learn more about each available template within the sdk command suite of Nextmv CLI.

`nextroute` template

The nextroute template is the recommended starting point when solving a vehicle routing problem (VRP) requiring custom constraints or objective functions. This includes use cases for delivery, distribution, and sourcing, such as: food delivery, waste management, ridesharing, and more. Note if custom constraints or objective functions are not required, then we recommend starting with the Nextmv routing app (the app is based on the nextroute template).

standard input:

vehicles - list of vehicle id
stops - array of stop id, and position

Check out our vehicle routing features for a full list of options that can easily be configured to solve most routing problems and our routing tutorial for more information on using the nextroute template

`routing` template

The routing template is a legacy template for use solving a vehicle routing problem (VRP). This includes use cases for delivery, distribution, and sourcing, such as: food delivery, waste management, ridesharing, and more. The routing template uses the Nextmv Router Engine to assign and sequence vehicle visits to stops in the form of routes.

standard input:

vehicles - list of vehicle id
stops - array of stop id, and position

See the router engine options how-to guide for a full list of options that can easily be configured to solve most routing problems and our legacy routing tutorial for more information on using the routing template

`cloud-routing` template

Similar to the routing template, cloud-routing is a legacy template that solves a VRP but uses a different input structure which handles flexible and optional constraints based on the input file.

standard input:

vehicles - array of vehicle id, capacity and start location
stops - array of stop id, position and quantity

Optional constraints such as penalties, precedence, and shifts are outlined in our router engine options how-to guide.

`cluster` template

A cluster is a collection of points that are similar to one another in some way. The goal of clustering is to find natural groupings of the data, such that the points within a cluster are more similar to each other than to points in other clusters.

Clustering has a wide range of applications in various fields, such as:

vehicle routing: group customers or delivery locations based on proximity/similarities. Clustering can be used to identify patterns in customer demand, such as time of day or day of the week, and then use this information to optimize the routing plan accordingly.
marketing: segment customers into different groups based on their demographics, purchasing habits, interests, etc. This can help companies target their marketing efforts more effectively.
data analysis: identify patterns and relationships in large datasets, which can help organizations make more informed decisions.
social network analysis: identify groups of individuals with similar characteristics or behavior in social networks, which can help researchers understand how information spreads and how communities form.

The main entities involved in the cluster template are the data points to be clustered and the clusters themselves. Each data point is a representation of an object or phenomenon in the real world, and a cluster is a group of similar data points.

standard input:

points - each data point to be clustered
clusters - number of total clusters to create
maximum_weight - max weight value allowed per cluster
weight - weight given to each point
maximum_points - max number of points assigned to a given cluster

For more information on clusters, check out the sdk cluster package reference guide.

`cluster-tsp` template

The cluster-tsp template reads a routing input data format but instead of solving a VRP directly, it creates a set of clusters in a pre-processing step, similar to the cluster template. The number of clusters created match the number of vehicles available in the input file, the cluster size is calculated such that points are distributed evenly among them. Then, for each vehicle, a traveling salesman problem (TSP) is solved. This is achieved by using the Attributes option in the routing engine.

Standard input:

vehicles - list of vehicle id
stops - array of stop id and position
stop_weight - weight given to each stop
cluster_capacities - max weight allowed for each cluster

For more information, check out the clustered routes tutorial.

`knapsack` template

The knapsack template solves the knapsack problem using a decision diagram-based solver. The knapsack problem is a common combinatorial optimization problem: Given a set of items, each with a weight and a value, determine which items to include in the collection so that the total weight is less than or equal to a given limit while maximizing the total value.

This template has a wide range of applications, such as:

Bin packing: stacking objects into bins and not caring about how it’s stacked.
Simple marketing spend: optimizing spend for a single marketing campaign.
Material cutting problems: Finding the best way to cut steel coils or irregular shapes out of some textiles with least waste/clippings.
Pallet packing: stacking objects in a particular way (e.g., so nothing gets crushed due to weight, etc.).

standard input:

items - array of potential item id, value, and weight
capacity - an integer representing the max weight of the knapsack

For more information about the knapsack template, check out the knapsack how-to guide

`mip-knapsack` template

The mip-knapsack template solves the knapsack problem described above using Mixed Integer Programming and the open-source solver HiGHS.

Assigns a set number of items to a knapsack (or container). Not all items must be assigned. Optimize for the most valuable set of items possible while not exceeding the container's carrying capacity.

standard input:

items - array of item_id, value, weight, and volume
weight_capacity - max weight the knapsack can hold
volume_capacity - max volume the knapsack can accept

`shift-scheduling` template

The shift-scheduling template assigns assigns one worker to each shift while maximizing worker happiness score (the number of times a preference of a worker has been met) and covering all shifts with as few workers as possible.

standard input:

days - number of days in the schedule
workers - number of available workers
preference - array of shift_type including workers who prefer a type of day
unavailable - array of worker and unavailable days

This template is applicable to a wide range of applications that vary in terms of complexity. This can include:

nurse scheduling
sports scheduling
teacher coverage
driver assignments
cloud resource allocation

For additional information, check out our shift scheduling how-to guide

`pager-duty` template

The pager-duty template is a specific flavor of shift scheduling that assigns users to shifts (days) for incident response on-call duty using input and output data structures compatible with PagerDuty API.

input:

schedule_start - the start date of the schedule
schedule_end - the end date of the schedule
users - list of users to assign to shifts, containing name, id, type, and optional unavailable days and preferences

Click here to learn how to set up and run the pager duty app, and for more background on applying the pager-duty app, check out our blog.

`new-app` template

The new-app template is a template shell that provides a skeleton with guidance on how to utilize store to create a completely custom model. If you want to build a completely new model from scratch, start with this template, which gives sensible defaults for how to structure, validate, and generate a new store. Note, the new-app template requires additional code and input data to run.

`sudoku` template

Creating an algorithmic solver for Sudoku puzzles is a common optimization programming challenge. The sudoku template demonstrates how this can be done with Nextmv. This template completes a 9x9 grid such that all columns, rows, and 3x3 subgrids contain the numerals 1 through 9.

standard inputs:

9x9 matrix listing initial values (1 through 9) and empty spaces (represented by 0)

`mip-meal-allocation` template

The mip-meal-allocation template solves a bunny-inspired twist on the Stigler diet problem that involves determining the best allocation of meals (array of meal name) including a list of ingredients to bunnies in order to maximize the number of binkies produced. We demonstrate this by solving a demo-problem we named mip-meal-allocation.

This template allocates meals (diets) consisting of carrot and endive ingredients to bunnies with the goal of maximizing their happiness through good diets and nutrition. This template uses the open-source solver HiGHS to maximize the number of binkies our bunnies will execute by selecting their meal.

A binky is when a bunny jumps straight up and quickly twists its hind end, head, or both. A bunny may binky because it is feeling happy or safe in its environment.

The input defines a number of meals we can use to maximize binkies, which indicates their level of happiness. Each meal consists out of one or more items and in total we can only use the number of items we have in stock.

standard input:

items - array of food name and amount in stock

`routing-matrix-input` template

When using the routing-matrix-input template, the measure-matrix app must be run first to generate the necessary input required for this template.

A modeling kit for VRPs, this legacy template shows how to use a custom matrix that is passed via an input file. Together with measure-matrix, these templates create a matrix of points from a measure that is accepted by the routing app. For more information on using the routing-matrix-input template, check out the custom matrices tutorial.

standard input:

stops - array of stop id and position
vehicles - list of vehicle id
starts - list of vehicle start location
ends - list of vehicle end location
shifts - array of vehicle shift start and end times
duration_matrix - matrix of point to point costs in travel time
distance_matrix - matrix of point to point costs in distance

`measure-matrix` template

Serves as an input generator for the routing-matrix-input app. The generated input data includes matrices for distance and travel time using one of our supported measures.

For more information on using the legacy measure-matrix template, check out the custom matrices tutorial.

`time-dependent-measure` template

In real world VRPs, it is often needed to take the time of the day into account when calculating routes, e.g. to calculate correct ETAs during rush hours. time dependent measure is a legacy template that shows you how to make use of time dependent measures and apply different costs according to time. This template is based on the routing template and can easily be combined with more options that are shown there like time windows or capacities (among many more).

standard input:

vehicles - list of vehicle id
stops - array of stop id and position
shifts - array of start and end times for each vehicle

For additional information, check out the time dependent measures tutorial.

`unique-matrix-measure` template

The purpose of this legacy template is to reduce input file size.

If the input has many duplicate stops, instead of passing a full matrix for each point, you can find all unique points in the matrix and use a unique matrix and a list of all unique points. Every stop then references a unique point. This data can then be used to recreate a full matrix as it is expected by the solver.

If the input has many duplicate stops input file size can be reduced drastically.

standard input:

stops - array of stop id and position
vehicles - list of vehicle id
starts - list of vehicle start location
ends - list of vehicle end location
unique_points - a unique set of locations that need to be visited
unique_matrix - represents a matrix of costs for going from each of the unique points to another

Check out the unique-matrix-measure tutorial to learn more about using this template.

List of available templates

Introduction

Available templates

Template Overview

Input File

Output File

`nextroute` template

`routing` template

`cloud-routing` template

`cluster` template

`cluster-tsp` template

`knapsack` template

`mip-knapsack` template

`shift-scheduling` template

`pager-duty` template

`new-app` template

`sudoku` template

`mip-meal-allocation` template

`routing-matrix-input` template

`measure-matrix` template

`time-dependent-measure` template

`unique-matrix-measure` template

Contents