Get started with Nextmv

Nextmv is a decision platform built around five core concepts:

1. Pre-built apps — “out of the box” decision apps for common domain solutions like vehicle routing, packing and sorting, shift scheduling and more.
2. Nextmv CLI – powerful workflow management tool for developers.
3. Nextmv SDK – developer-friendly API for building custom decision apps.
4. Custom decision apps – apps that you build from scratch or customize from a template for your specific business needs.
5. 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

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:

export NEXTMV_API_KEY=YOUR_NEXTMV_CLOUD_API_KEY_HERE

Now, copy the command below to run a sample input file in your terminal.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEXTMV_API_KEY" \
  -d "{ \
        \"input\": { \
          \"defaults\": { \
            \"vehicles\": { \
              \"speed\": 10 \
            } \
          }, \
          \"stops\": [ \
            { \
              \"id\": \"s1\", \
              \"location\": { \
                \"lon\": -78.90919, \
                \"lat\": 35.72389 \
              } \
            }, \
            { \
              \"id\": \"s2\", \
              \"location\": { \
                \"lon\": -78.813862, \
                \"lat\": 35.75712 \
              } \
            }, \
            { \
              \"id\": \"s3\", \
              \"location\": { \
                \"lon\": -78.92996, \
                \"lat\": 35.932795 \
              } \
            } \
          ], \
          \"vehicles\": [ \
            { \
              \"id\": \"vehicle-0\", \
              \"start_time\": \"2023-01-01T06:00:00-06:00\", \
              \"end_time\": \"2023-01-01T10:00:00-06:00\" \
            } \
          ] \
        } \
      }" \
  "https://api.cloud.nextmv.io/v1/applications/my-routing/runs"

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:

export NEXTMV_BASE_URL=https://api.cloud.nextmv.io
curl -sS "https://cloud.nextmv.io/install-cli.txt" | bash -

After downloading and installing, the last step is to configure Nextmv CLI with your account:

nextmv configure --api-key $NEXTMV_API_KEY

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.

nextmv sdk install

You’re now ready to create your first project.

Let’s initialize a new project using the nextroute template to solve a VRP:

nextmv sdk init -t nextroute

This will create a new directory “nextroute” in your current working directory. Change into this new nextroute directory:

cd nextroute

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:

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

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.

{
  "version": {…},
  "options": {
    "model": {
      "constraints": {…},
      "objectives": {…},
      "properties": {…}
    },
    "solve": {…},
    "format": {…}
  },
  "solutions": [
    {
      "unplanned": […],
      "vehicles": [
        {
          "id": "vehicle-0",
          "route": [
            …,
            {
              "stop": {
                "id": "s18",
                "location": { "lon": -78.911485, "lat": 36.009015 }
              },
              "travel_duration": 2446,
              "cumulative_travel_duration": 2938,
              "arrival_time": "2021-10-17T06:53:58-06:00",
              "start_time": "2021-10-17T06:53:58-06:00",
              "duration": 300,
              "end_time": "2021-10-17T06:58:58-06:00"
            },
            …
          ],
          "route_travel_duration": 9364,
          "route_stops_duration": 3000,
          "route_duration": 12364
        },
        …
      ],
      "objective": {…}
    }
  ],
  "statistics": {…}
}

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:

nextmv app create \
  --app-id "my-routing" \
  --name "My Routing" \
  --description "Custom routing app"

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.

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:

nextmv app push --app-id my-routing

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:

nextmv app run \
  --app-id my-routing \
  --input ./input.json \
  --wait

(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:

nextmv app promote \
  --app-id my-routing \
  --name "Version 1" \
  --version-id version-1 \
  --instance-id production

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:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEXTMV_API_KEY" \
  -d "{ \
        \"input\": $(cat ./input.json) \
      }" \
  "https://api.cloud.nextmv.io/v1/applications/my-routing/runs"

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):

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEXTMV_API_KEY" \
  "https://api.cloud.nextmv.io/v1/applications/my-routing/runs/YOUR_RUN_ID"

The returned result from the API call should contain your solution in the solutions array.

{
  "version": {...},
  "options": {...},
  "solutions": [
    {
      "unplanned": [...],
      "vehicles": [
        {
          "id": "vehicle-0",
          "route": [...],
          "route_travel_duration": 9364,
          "route_stops_duration": 3000,
          "route_duration": 12364
        },
        ...
      ],
      "objective": {...}
    }
  ],
  "statistics": {...}
}

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.

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:

options.Model.Constraints.Disable.Capacity = true

Verify your code change by comparing the main.go Before and After views below:

func solver(
    ctx context.Context,
    input schema.Input,
    options options,
) (runSchema.Output, error) {
    model, err := factory.NewModel(input, options.Model)
    if err != nil {
        return runSchema.Output{}, err
    }

    solver, err := nextroute.NewParallelSolver(model)
    if err != nil {
        return runSchema.Output{}, err
    }

    solutions, err := solver.Solve(ctx, options.Solve)
    if err != nil {
        return runSchema.Output{}, err
    }

    return nextroute.Format(ctx, options, solver, solutions.Last()), nil
}

You can run the model locally to ensure that the change was implemented correctly:

nextmv sdk run . -- \
  -runner.input.path input.json \
  -runner.output.path output-alt.json \
  -solve.duration 3s

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:

nextmv app push --app-id my-routing

Next, let’s create a new version for our updated executable binary.

nextmv app version create \
  --app-id my-routing  \
  --name "Version 2" \
  --description "Model change to disable capacity constraint." \
  --version-id version-2

We now have two versions:

1. version-1 which was created in the Deploy app section and contains the executable binary for our initial model code.
2. 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:

nextmv app instance create \
  --app-id "my-routing" \
  --instance-id staging \
  --name "Staging" \
  --version-id version-2

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):

nextmv experiment input-set create \
  --app-id "my-routing" \
  --input-set-id "sample-production-runs" \
  --instance-id production \
  --name "Sample production runs"

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:

nextmv experiment batch start \
  --app-id my-routing \
  --experiment-id test-experiment \
  --instance-ids "production,staging" \
  --input-set-id sample-production-runs \
  --name "Compare production and staging" \
  --description "Comparison of version 1 vs. version 2"

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.