Nextmv is a decision platform built around five core concepts:
- Pre-built apps — “out of the box” decision apps for common domain solutions like vehicle routing, packing and sorting, shift scheduling and more.
- Nextmv CLI – powerful workflow management tool for developers.
- Nextmv SDK – developer-friendly API for building custom decision apps.
- Custom decision apps – apps that you build from scratch or customize from a template for your specific business needs.
- Experiments – a framework for testing different model versions, input data, configurations, and scenarios and verifying changes.
These five concepts are fully integrated to make it quick and seamless to deploy decision apps to production-ready infrastructure and manage different developer operation workflows.
The following sections walk you through each concept at a high level: We’ll create an app to solve a vehicle routing problem (VRP), deploy it to a remote production environment, run it, and then carry out an experiment to test a model change. To follow along you will need to sign up for a Nextmv Cloud account.
Nextmv apps
The steps in this section are only operable with a Production Plan. However, you can start a free trial in Nextmv Console that gives you access to everything in the Production Plan.
Nextmv has a Marketplace for pre-built decision apps that solve specific problem domains like routing or shift scheduling. Anyone on Nextmv can subscribe to these applications and get instant access to all the features of that app. We’ll now walk through subscribing to the Nextmv Routing app.
Subscribe to app
After creating a free Nextmv account and starting a free trial, navigate to the Marketplace section in Nextmv Console and then click on the Nextmv Routing app. On this details page you should see a Subscribe button beneath the app’s title and summary. Click the Subscribe button to subsribe to the Nextmv Routing app.
Create new subscription app
After subscribing, the button should now read Create New Subscription App. Click this button to create your own routing app.
In the fields provided, enter a name and description for your new app. Your ID will be created automatically from the name, but this can be customized as well. After filling in these details click the Create app button to create your own routing app.
You should now see your new routing app in the list view for Subscribed apps. Click on your app to view the details. You will also see a Run History and API Reference view. The Run History page will show any runs you make on your app and the API Reference page lists all of the available endpoints for your new routing app.
Make a run
You will need your Nextmv Cloud API key to make a new run with your routing app. After you have copied your API key, open up your terminal and run the following command to store the API key to your environment:
Now, copy the command below to run a sample input file in your terminal.
You should get a run ID as a response. This is the unique ID for your run. Navigate to your app’s Run History page in Nextmv Console to see the run you just made; click on the run to view its details.
You now have your own app to solve vehicle routing problems. Visit the Vehicle Routing features page to see what other features are available.
Next, we’ll take the same template the Nextmv Routing app is based on and use it to create your own app.
Install Nextmv CLI
Nextmv CLI is a command line interface that lets you easily run custom models on your local machine and deploy your custom model as an executable binary to run remotely in the cloud. In this section we will cover installing Nextmv CLI on your local machine.
Using your API key that you stored in the prior section, run the following script to install Nextmv CLI:
After downloading and installing, the last step is to configure Nextmv CLI with your account:
Nextmv CLI has now been installed and configured with your account. In the next section we’ll build a custom routing app to solve a VRP.
Nextmv SDK
Nextmv SDK provides a set of APIs to build decision models. It also comes with a set of templates for solving domain-specific optimization problems. Templates include everything needed to run a model and can be used as the foundation for building a custom decision model.
First let’s use Nextmv CLI to install Nextmv SDK locally. The following command will install Go and get the necessary plugins and other supporting files needed to build and run custom models locally. Note that Nextmv SDK manages its own Go installation and will not affect your current Go installation if you have one.
If you’re on macOS you may need to run a command to allow access to Nextmv SDK. This command will be output at the end of the installation process.
You’re now ready to create your first project.
Let’s initialize a new project using the nextroute
template to solve a VRP:
This will create a new directory “nextroute” in your current working directory. Change into this new nextroute directory:
There are several files in this newly created directory. The main.go
file contains all of the code to solve the VRP and the input.json
file contains sample input for the model.
Let’s run the model locally to see how it works:
The nextmv sdk run
command runs the model using the provided input.json and then writes the output to the specified output.json
file. Open the output.json
file to see the solution to the VRP.
You should see an options
block that contains the various model constraints and objectives used to solve the problem; there should also be a solutions
block with an array that contains an object with an unplanned
and vehicles
array and an objective
object with a more detailed breakdown of the value function used for the solution. The unplanned
array contains stops that were not assigned to a vehicle, and the vehicles
array contains the vehicle route information.
An abridged sample output is shown below.
Deploy custom app
Now that we have a custom model, let’s create a new app and then deploy that model to our app. Create a new app using Nextmv CLI:
This creates a new app with an ID of my-routing
. You can view your newly created app on the Apps page in Nextmv Console.
Alternatively, you can just create the new app from Console by navigating to the Apps page, clicking the New App button and filling out the details there. However, for this tutorial we will be using Nextmv CLI.
Click on your app to view the various sections within the app. An app can be thought of as a container for all of the code and operations needed to solve a particular business problem like routing or scheduling. There are a couple sample apps included in the Apps section for reference if you would like to explore those.
Your new app is just a shell at the moment; it does not contain any executable code so none of the app’s endpoints are operable yet.
In the following steps we will build and deploy your custom model so that you can run your model remotely with your custom app’s endpoints. HOWEVER, to proceed you must first initiate a free trial in Nextmv Console. The free trial is for 14-days and will grant you access to all features included with our Production Plan. Note that you will NOT be auto-enrolled for the Production Plan when the trial ends.
The following steps are only operable with a Production Plan. Start a free trial in Nextmv Console to follow along.
Push executable binary
In this step you will build your local model into an executable binary and push it to your new application in Nextmv Cloud.
From the nextroute
directory created prior, run the push
command to build and push your local model to Nextmv Cloud:
Note how your app ID was specified for the push
command. This is how Nextmv CLI knows to build and push your custom model in the nextroute
directory to your app.
The push
command will initiate a series of steps to build an executable binary from your custom model code. This executable binary is then pushed to your app in Nextmv Cloud. Once the steps have completed, you can see a reference to your pushed executable on the Details page of your custom app in Nextmv Console.
You can now run your app remotely with the run
command:
(Adding the --wait
flag will poll the run until the result is available and then display the result.)
After the run has completed you should get back the output of your run. Congratulations! You just made a remote run with your custom model.
When running from Nextmv CLI, an assumption is made to run with the most recently pushed binary and we do some behind the scenes work to make that happen, but for this tutorial we are skipping over those details.
Assign executable to a version
You now have an executable binary of your custom model in Nextmv Cloud. However, if you were to re-run the push command, the prior pushed binary would be overwritten by this new binary. The way to preserve a specific binary is to assign it to a version.
When you create a new version, the version is assigned the most recently pushed executable. You can think of app versions as versions of your executable binaries.
In Nextmv CLI, we will use the promote command to create a new application version with the executable we pushed in step 2:
The promote
command performs a few extra steps to not only assign the executable to a version but also set that version as the default executable for your app’s REST API endpoints using another concept called instances (hence the instance ID specified). We will skip this concept for now and cover it later in the Experiment section.
Now, no matter how many times a new binary is pushed to your app, this version will always use the executable in the version we just specified.
Run the model remotely
You already ran your app remotely in Step 2 with Nextmv CLI. Now let’s run it remotely using your application’s REST API endpoint:
Note that the full API schema for your app can be found in your app’s API Reference page in Console.
The command above executes the run remotely using the version we specified with the promote
command as it is the version assigned to the app’s default instance. The ID returned from this command is the unique ID for this run. We can now use this unique run ID to retrieve the results of your remote run (make sure to fill in the placeholder with your unique run ID):
The returned result from the API call should contain your solution in the solutions
array.
You now have successfully deployed a custom model to Nextmv Cloud that can be used in a production environment. Next we will run an experiment to test changes in your custom model.
Experiment
In this section we will introduce a functional change to our model and then run an experiment to compare the results of this updated model to our original model.
Experiments use the input from prior remote runs for comparison. The specific runs you want to use for an experiment are defined in an input set. For this example, we will use just the one remote run created prior. And since we performed this run using the application’s default instance we can rely on the experiment’s default behavior to auto-create an input set for us. That said, you can learn more about input sets in the Experiments core concepts section.
First, let’s make a change to our model and then deploy that change as a new version. If you recall from the Deploy custom app section above, we have a “Version 1” that is assigned the first executable binary that we pushed. After we have made a change to our model, we will push a new build and then assign this new executable binary to a “Version 2”.
In the main.go
file in the nextroute
directory, add the following line at the beginning of the solver
function that starts on line 29:
Verify your code change by comparing the main.go
Before and After views below:
You can run the model locally to ensure that the change was implemented correctly:
If you compare the results of output-alt.json
vs. output.json
from the prior run you will find variations in the unplanned stops and the routes assigned to the vehicles.
Now that we have changed our model, let’s build and deploy the updated code as a new executable binary:
Next, let’s create a new version for our updated executable binary.
We now have two versions:
version-1
which was created in the Deploy app section and contains the executable binary for our initial model code.version-2
which contains the executable binary for our modified model code.
You can view these versions in the Versions section of your app in Nextmv Console.
If you recall in the prior section, when we ran the promote
command we specified an --instance-id
parameter of production
. The promote
command then used this parameter to create a new application instance with the ID of production
.
An application instance is a representation of a version and optional configuration that can be used in some context. For example, you might have a configuration that you run for different regions (Northeast, Midwest, etc) or one for different environments, like staging and production. Note that the same version can be used by multiple application instances.
In this example we will use instances for the different environments staging and production and our experiment will be comparing the two different versions, each assigned to the different instances. We have already created the production
instance, create a new instance staging
with the following command:
You can now view both instances in the Instances section of your app in Nextmv Console. The production
instance should have the version-1
assigned to it, and the staging
instance should have the version-2
version assigned.
Note that since the production
instance was created as part of the promote
command with only the ID specified it has been auto-assigned a name. You can change this name to Production
in Nextmv Console if desired.
Input set
Input sets gather inputs from previous remote runs to use for experiments. They are created by specifying a list of run IDs, or by searching for runs made by a specific instance with an optional date and time range. In this case we will use the remote runs we made prior with the production
instance.
Create an input set with the following command (by default, up to the last 20 runs will be used):
This will create an input set with our two production runs made in the Deploy app section above (more will be present if you made additional remote runs). This new input set can be viewed in the Input sets subsection of the app’s Experiments section in Nextmv Console.
We now have the necessary entities to run an experiment.
Run experiment
Run an experiment comparing the results of our updated model code to the initial model code by comparing the staging
instance versus the production
instance. The experiment will run the two underlying versions (represented by instances) against the same set of inputs defined in our input set and compare the result.
Run the following command to start the experiment:
If you now visit the Experiments section of your app in Nextmv Console you will see the experiment you just started listed there. Click on the experiment to view the result of the experiment. Key indicators from your custom model are automatically extracted and compared and a summary of the experiment runs is included at the end.
You can read more about experiments in the Experiments core concepts section.
Congratulations! You have reached the end of the Nextmv quick start guide. Next explore the core concepts section for deeper dives into the topics we covered here.