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:
Change directories into the newly created template folder.
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.
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
andStops
, 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
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 runduration
, solver type, etcsolutions
- prints the results of the runstatistics
- prints the statistics around the solution(s) foundversion
- returns the version of SDK that was used for the run
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 vehicleid
stops
- array of stopid
, andposition
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 vehicleid
stops
- array of stopid
, andposition
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 vehicleid
,capacity
andstart
locationstops
- array of stopid
,position
andquantity
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 clusteredclusters
- number of total clusters to createmaximum_weight
- max weight value allowed per clusterweight
- weight given to eachpoint
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 vehicleid
stops
- array of stopid
andposition
stop_weight
- weight given to each stopcluster_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 itemid
,value
, andweight
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 ofitem_id
,value
,weight
, andvolume
weight_capacity
- max weight the knapsack can holdvolume_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 scheduleworkers
- number of available workerspreference
- array ofshift_type
includingworkers
who prefer atype
of dayunavailable
- array ofworker
and unavailabledays
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 scheduleschedule_end
- the end date of the scheduleusers
- list of users to assign to shifts, containingname
,id
,type
, and optionalunavailable
days andpreferences
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 foodname
and amount instock
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 stopid
andposition
vehicles
- list of vehicleid
starts
- list of vehicle startlocation
ends
- list of vehicle endlocation
shifts
- array of vehicle shiftstart
andend
timesduration_matrix
- matrix of point to point costs in travel timedistance_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 vehicleid
stops
- array of stopid
andposition
shifts
- array ofstart
andend
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 stopid
andposition
vehicles
- list of vehicleid
starts
- list of vehicle startlocation
ends
- list of vehicle endlocation
unique_points
- a unique set of locations that need to be visitedunique_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.