Bring your own model to Nextmv with Python

⌛️ Approximate time to complete: 20 min.

In this tutorial you will learn how to bring your own decision model to the Nextmv Platform, from scratch. Complete this tutorial if you:

Have a pre-existing decision model and you want to explore the Nextmv Platform.
Are fluent using Python 🐍.

To complete this tutorial, we will use two external examples, working under the principle that they are not Nextmv-created decision models. You can, and should, use your own decision model, or follow along with the examples provided:

At a high level, this tutorial will go through the following steps using both examples:

Nextmv-ify the decision model.
Run it locally.
Track local runs remotely.
Push the model to Nextmv Cloud.
Run the model remotely.
Perform scenario testing.

Let's dive right in 🤿.

1. Prepare the executable code

If you are working with your own decision model and already know that it executes, feel free to skip this step.

The decision model is composed of executable code that solves an optimization problem. Copy the desired example code to a script named main.py.

Pyomo transport problem example
HiGHS network flow example

#  ___________________________________________________________________________
#
#  Pyomo: Python Optimization Modeling Objects
#  Copyright (c) 2015-2025
#  National Technology and Engineering Solutions of Sandia, LLC
#  Under the terms of Contract DE-NA0003525 with National Technology and
#  Engineering Solutions of Sandia, LLC, the U.S. Government retains certain
#  rights in this software.
#  This software is distributed under the 3-clause BSD License.
#  ___________________________________________________________________________


#!/usr/bin/env python
# -*- coding: utf-8 -*-

# Import
from pyomo.environ import *
 
# Creation of a Concrete Model
model = ConcreteModel()
 
## Define sets ##
#  Sets
#       i   canning plants   / seattle, san-diego /
#       j   markets          / new-york, chicago, topeka / ;
model.i = Set(initialize=['seattle','san-diego'], doc='Canning plants')
model.j = Set(initialize=['new-york','chicago', 'topeka'], doc='Markets')
 
## Define parameters ##
#   Parameters
#       a(i)  capacity of plant i in cases
#         /    seattle     350
#              san-diego   600  /
#       b(j)  demand at market j in cases
#         /    new-york    325
#              chicago     300
#              topeka      275  / ;
model.a = Param(model.i, initialize={'seattle':350,'san-diego':600}, doc='Capacity of plant i in cases')
model.b = Param(model.j, initialize={'new-york':325,'chicago':300,'topeka':275}, doc='Demand at market j in cases')
#  Table d(i,j)  distance in thousands of miles
#                    new-york       chicago      topeka
#      seattle          2.5           1.7          1.8
#      san-diego        2.5           1.8          1.4  ;
dtab = {
    ('seattle',  'new-york') : 2.5,
    ('seattle',  'chicago')  : 1.7,
    ('seattle',  'topeka')   : 1.8,
    ('san-diego','new-york') : 2.5,
    ('san-diego','chicago')  : 1.8,
    ('san-diego','topeka')   : 1.4,
    }
model.d = Param(model.i, model.j, initialize=dtab, doc='Distance in thousands of miles')
#  Scalar f  freight in dollars per case per thousand miles  /90/ ;
model.f = Param(initialize=90, doc='Freight in dollars per case per thousand miles')
#  Parameter c(i,j)  transport cost in thousands of dollars per case ;
#            c(i,j) = f * d(i,j) / 1000 ;
def c_init(model, i, j):
  return model.f * model.d[i,j] / 1000
model.c = Param(model.i, model.j, initialize=c_init, doc='Transport cost in thousands of dollar per case')
 
## Define variables ##
#  Variables
#       x(i,j)  shipment quantities in cases
#       z       total transportation costs in thousands of dollars ;
#  Positive Variable x ;
model.x = Var(model.i, model.j, bounds=(0.0,None), doc='Shipment quantities in case')
 
## Define constraints ##
# supply(i)   observe supply limit at plant i
# supply(i) .. sum (j, x(i,j)) =l= a(i)
def supply_rule(model, i):
  return sum(model.x[i,j] for j in model.j) <= model.a[i]
model.supply = Constraint(model.i, rule=supply_rule, doc='Observe supply limit at plant i')
# demand(j)   satisfy demand at market j ;  
# demand(j) .. sum(i, x(i,j)) =g= b(j);
def demand_rule(model, j):
  return sum(model.x[i,j] for i in model.i) >= model.b[j]  
model.demand = Constraint(model.j, rule=demand_rule, doc='Satisfy demand at market j')
 
## Define Objective and solve ##
#  cost        define objective function
#  cost ..        z  =e=  sum((i,j), c(i,j)*x(i,j)) ;
#  Model transport /all/ ;
#  Solve transport using lp minimizing z ;
def objective_rule(model):
  return sum(model.c[i,j]*model.x[i,j] for i in model.i for j in model.j)
model.objective = Objective(rule=objective_rule, sense=minimize, doc='Define objective function')
 
 
## Display of the output ##
# Display x.l, x.m ;
def pyomo_postprocess(options=None, instance=None, results=None):
  model.x.display()
 
# This is an optional code path that allows the script to be run outside of
# pyomo command-line.  For example:  python transport.py
if __name__ == '__main__':
    # This emulates what the pyomo command-line tools does
    from pyomo.opt import SolverFactory
    import pyomo.environ
    opt = SolverFactory("glpk")
    results = opt.solve(model)
    #sends results to stdout
    results.write()
    print("\nDisplaying Solution\n" + '-'*60)
    pyomo_postprocess(None, model, results)

2. Install requirements

If you are working with your own decision model and already have all requirements ready for it, feel free to skip this step.

Make sure you have the appropriate requirements installed for your model. If you don't have one already, create a requirements.txt file in the root of your project with the Python package requirements needed.

Pyomo
HiGHS

pyomo>=6.9.5

Install the requirements by running the following command:

Bash

pip install -r requirements.txt

The Pyomo example uses the GLPK solver. Make sure you install it as well.

MacOS
Linux

brew install glpk

For Windows, install from SourceForge.

3. Run the executable code

If you are working with your own decision model and already know that it executes, feel free to skip this step.

Make sure your decision model works by running the executable code.

Bash

python main.py

Here is the output produced by both examples.

Pyomo
HiGHS

# ==========================================================
# = Solver Results                                         =
# ==========================================================
# ----------------------------------------------------------
#   Problem Information
# ----------------------------------------------------------
Problem:
- Name: unknown
  Lower bound: 153.675
  Upper bound: 153.675
  Number of objectives: 1
  Number of constraints: 5
  Number of variables: 6
  Number of nonzeros: 12
  Sense: minimize
# ----------------------------------------------------------
#   Solver Information
# ----------------------------------------------------------
Solver:
- Status: ok
  Termination condition: optimal
  Statistics:
    Branch and bound:
      Number of bounded subproblems: 0
      Number of created subproblems: 0
  Error rc: 0
  Time: 0.006303071975708008
# ----------------------------------------------------------
#   Solution Information
# ----------------------------------------------------------
Solution:
- number of solutions: 0
  number of solutions displayed: 0

Displaying Solution
------------------------------------------------------------
x : Shipment quantities in case
    Size=6, Index=i*j
    Key                       : Lower : Value : Upper : Fixed : Stale : Domain
     ('san-diego', 'chicago') :   0.0 :   0.0 :  None : False : False :  Reals
    ('san-diego', 'new-york') :   0.0 : 275.0 :  None : False : False :  Reals
      ('san-diego', 'topeka') :   0.0 : 275.0 :  None : False : False :  Reals
       ('seattle', 'chicago') :   0.0 : 300.0 :  None : False : False :  Reals
      ('seattle', 'new-york') :   0.0 :  50.0 :  None : False : False :  Reals
        ('seattle', 'topeka') :   0.0 :   0.0 :  None : False : False :  Reals

4. Nextmv-ify the decision model

We are going to turn the executable decision model into a Nextmv Application.

So, what is a Nextmv Application? A Nextmv Application is an entity that contains a decision model as executable code. An Application can make a run by taking an input, executing the decision model, and producing an output. An Application is defined by its code, and a configuration file named app.yaml, known as the "app manifest".

Think of the app as a shell, or workspace, that contains your decision model code, and provides the necessary structure to run it.

A run on a Nextmv Application follows this convention:

App diagram

The app receives one, or more, inputs (problem data).
The app run can be configured through options.
The app processes the inputs, and executes the decision model.
The app produces one, or more, outputs (solutions).
The app optionally produces statistics (metrics) and assets (can be visual, like charts).

We are going to adapt the examples so that they can follow these conventions.

Start by adding the app.yaml file, which is known as the app manifest, to the root of the project. This file contains the configuration of the app.

Pyomo app.yaml
HiGHS app.yaml

type: python
runtime: ghcr.io/nextmv-io/runtime/pyomo:latest
files:
  - main.py
python:
  pip-requirements: requirements.txt
configuration:
  content:
    format: json
  options:
    items:
      - name: duration
        description: Duration for the solver, in seconds.
        required: false
        option_type: float
        default: 1
        additional_attributes:
          min: 0
          max: 10
          step: 1
        ui:
          control_type: slider
      - name: solver
        description: Solver provider to use.
        required: false
        option_type: string
        default: glpk
        additional_attributes:
          values:
            - scip
            - cbc
            - glpk
        ui:
          control_type: select
      - name: input
        description: Path to input file. Default is stdin.
        required: false
        option_type: string
        default: ""
      - name: output
        description: Path to output file. Default is stdout.
        required: false
        option_type: string
        default: ""

This tutorial is not meant to discuss the app manifest in-depth, for that you can go to the manifest docs. However, these are the main attributes shown in the manifests:

type: both are python applications.
runtime: Pyomo uses the special pyomo:latest runtime, as it comes with solvers pre-installed. HiGHS uses the standard python:3.11 runtime.
files: contains files that make up the executable code of the app. In both cases only a single main.py file is needed. Make sure to include all files and dirs that are needed for your decision model.
python.pip-requirements: specifies in both cases the file with the python packages that need to be installed for the application.
configuration.content: Pyomo will use the json format, so it does not need additional configurations. HiGHS will use multi-file, so additional configurations are needed. As you complete this tutorial, the difference between the two formats will become clearer.
configuration.options: for both examples, we are adding options to the application, which allow you to configure runs, with parameters such as solver duration.

For both examples, a dependency for nextmv (the Nextmv Python SDK) is also added. This dependency is optional, and SDK modeling constructs are not needed to run a Nextmv Application. However, using the SDK modeling features makes it easier to work with Nextmv apps, as a lot of convenient functionality is already baked in, like:

Reading and interpreting the manifest.
Easily reading and writing files based on the content format.
Parsing and using options from the command line, or environment variables.
Structuring inputs and outputs.

These are the new requirements.txt

Pyomo requirements.txt
HiGHS requirements.txt

pyomo>=6.9.5
nextmv>=0.34.1

Now, you can overwrite your main.py files with the Nextmv-ified version.

Pyomo main.py
HiGHS main.py

#  ___________________________________________________________________________
#
#  Pyomo: Python Optimization Modeling Objects
#  Copyright (c) 2015-2025
#  National Technology and Engineering Solutions of Sandia, LLC
#  Under the terms of Contract DE-NA0003525 with National Technology and
#  Engineering Solutions of Sandia, LLC, the U.S. Government retains certain
#  rights in this software.
#  This software is distributed under the 3-clause BSD License.
#  ___________________________________________________________________________


#!/usr/bin/env python
# -*- coding: utf-8 -*-


import nextmv

# Import
from pyomo.environ import *

# Duration parameter for the solver.
SUPPORTED_PROVIDER_DURATIONS = {
    "cbc": "sec",
    "glpk": "tmlim",
    "scip": "limits/time",
}

# Creation of a Concrete Model
model = ConcreteModel()

nextmv.redirect_stdout()
manifest = nextmv.Manifest.from_yaml(".")
options = manifest.extract_options()
input = nextmv.load(path=options.input)

## Define sets ##
#  Sets
#       i   canning plants   / seattle, san-diego /
#       j   markets          / new-york, chicago, topeka / ;
sets = input.data["sets"]
model.i = Set(initialize=sets["i"], doc="Canning plants")
model.j = Set(initialize=sets["j"], doc="Markets")

## Define parameters ##
#   Parameters
#       a(i)  capacity of plant i in cases
#         /    seattle     350
#              san-diego   600  /
#       b(j)  demand at market j in cases
#         /    new-york    325
#              chicago     300
#              topeka      275  / ;
params = input.data["parameters"]
model.a = Param(
    model.i,
    initialize=params["a"],
    doc="Capacity of plant i in cases",
)
model.b = Param(
    model.j,
    initialize=params["b"],
    doc="Demand at market j in cases",
)
#  Table d(i,j)  distance in thousands of miles
#                    new-york       chicago      topeka
#      seattle          2.5           1.7          1.8
#      san-diego        2.5           1.8          1.4  ;
dtab = {(edge["from"], edge["to"]): edge["cost"] for edge in params["d"]}
model.d = Param(model.i, model.j, initialize=dtab, doc="Distance in thousands of miles")
#  Scalar f  freight in dollars per case per thousand miles  /90/ ;
model.f = Param(
    initialize=params["f"], doc="Freight in dollars per case per thousand miles"
)


#  Parameter c(i,j)  transport cost in thousands of dollars per case ;
#            c(i,j) = f * d(i,j) / 1000 ;
def c_init(model, i, j):
    return model.f * model.d[i, j] / 1000


model.c = Param(
    model.i,
    model.j,
    initialize=c_init,
    doc="Transport cost in thousands of dollar per case",
)

## Define variables ##
#  Variables
#       x(i,j)  shipment quantities in cases
#       z       total transportation costs in thousands of dollars ;
#  Positive Variable x ;
model.x = Var(model.i, model.j, bounds=(0.0, None), doc="Shipment quantities in case")


## Define constraints ##
# supply(i)   observe supply limit at plant i
# supply(i) .. sum (j, x(i,j)) =l= a(i)
def supply_rule(model, i):
    return sum(model.x[i, j] for j in model.j) <= model.a[i]


model.supply = Constraint(
    model.i, rule=supply_rule, doc="Observe supply limit at plant i"
)


# demand(j)   satisfy demand at market j ;
# demand(j) .. sum(i, x(i,j)) =g= b(j);
def demand_rule(model, j):
    return sum(model.x[i, j] for i in model.i) >= model.b[j]


model.demand = Constraint(model.j, rule=demand_rule, doc="Satisfy demand at market j")


## Define Objective and solve ##
#  cost        define objective function
#  cost ..        z  =e=  sum((i,j), c(i,j)*x(i,j)) ;
#  Model transport /all/ ;
#  Solve transport using lp minimizing z ;
def objective_rule(model):
    return sum(model.c[i, j] * model.x[i, j] for i in model.i for j in model.j)


model.objective = Objective(
    rule=objective_rule, sense=minimize, doc="Define objective function"
)


## Display of the output ##
# Display x.l, x.m ;
def pyomo_postprocess(options=None, instance=None, results=None):
    model.x.display()


# This is an optional code path that allows the script to be run outside of
# pyomo command-line.  For example:  python transport.py
if __name__ == "__main__":
    # This emulates what the pyomo command-line tools does
    from pyomo.opt import SolverFactory

    opt = SolverFactory(options.solver)
    opt.options[SUPPORTED_PROVIDER_DURATIONS[options.solver]] = options.duration
    results = opt.solve(model)
    # sends results to stdout
    results.write()
    print("\nDisplaying Solution\n" + "-" * 60)
    pyomo_postprocess(None, model, results)

    shipments = [
        {"from": ix[0], "to": ix[1], "quantity": x()}
        for ix, x in model.x.items()
        if x() > 0.01
    ]
    solution = {"shipments": shipments}
    statistics = nextmv.Statistics(
        result=nextmv.ResultStatistics(
            duration=results.solver.time,
            value=value(model.objective, exception=False),
            custom={
                "variables": model.nvariables(),
                "constraints": model.nconstraints(),
                "num_edges_used": len(shipments),
            },
        )
    )
    output = nextmv.Output(
        options=options,
        solution=solution,
        statistics=statistics,
    )
    nextmv.write(output, path=options.output)

This is a short summary of the changes introduced for each of the examples:

Pyomo
- Load the app manifest from the app.yaml file.
- Extract options (configurations) from the manifest.
- The input data is no longer in the Python file itself. We will move it to a file under inputs/problem.json. In a single json file we will define the complete input. Given that we are working with the json content format, we use the Python SDK to load the input data from stdin.
- Modify the definition of sets, and parameters to use the data from the loaded input.
- Store the solution to the problem, and solver metrics (statistics), in an output.
- Write the output to stdout, given that we are working with the json content format.
HiGHS
- Load the app manifest from the app.yaml file.
- Extract options (configurations) from the manifest.
- The input data is no longer in the Python file itself. We are representing the problem with several files under the inputs directory. In inputs/edges.csv we are going to write the edges with their corresponding weights. In inputs/nodes.json we are going to set the information about nodes, like which node is the origin and which is the destination. When working with more than one file, the multi-file content format is ideal. We use the Python SDK to load the input data from the various files.
- Modify the definition of nodes, edges, and decision variables to use data from the loaded inputs.
- Store the solution to the problem, and solver metrics (statistics), in an output.
- Write the output to several files, under the outputs directory, given that we are working with the multi-file content format.

Here are the data files that you need to place in an inputs directory.

Pyomo

problem.json

{
  "sets": {
    "i": ["seattle", "san-diego"],
    "j": ["new-york", "chicago", "topeka"]
  },
  "parameters": {
    "a": {
      "seattle": 350,
      "san-diego": 600
    },
    "b": {
      "new-york": 325,
      "chicago": 300,
      "topeka": 275
    },
    "d": [
      { "from": "seattle", "to": "new-york", "cost": 2.5 },
      { "from": "seattle", "to": "chicago", "cost": 1.7 },
      { "from": "seattle", "to": "topeka", "cost": 1.8 },
      { "from": "san-diego", "to": "new-york", "cost": 2.5 },
      { "from": "san-diego", "to": "chicago", "cost": 1.8 },
      { "from": "san-diego", "to": "topeka", "cost": 1.4 }
    ],
    "f": 90
  }
}

HiGHS

edges.csv
nodes.json

from,to,weight
A,B,2.0
B,C,3.0
A,C,1.5
B,D,2.5
C,D,1.0

After you are done Nextmv-ifying, your Nextmv app should have the following structure, for the examples provided.

Pyomo
HiGHS

.
├── app.yaml
├── inputs
│   └── problem.json
├── main.py
└── requirements.txt

2 directories, 4 files

Now you are ready to explore the Nextmv Platform 🥳.

5. Install the Nextmv Python SDK

Install the Nextmv Python SDK, with additional requirements:

Bash

pip install --upgrade 'nextmv[all]'

Please note that even if you are not using the Python SDK's modeling constructs as part of your executable code, you still need to install it for this tutorial. On the other hand, if you decided that you want to use the Python SDK for the executable code, you would have needed to install it.

6. Run the Nextmv Application locally

The local package of the Nextmv Python SDK provides functionality to run Nextmv Applications locally on your machine.

The local experience is completely free of charge and does not require a Nextmv account.

Create an app.py script at the same location as the app.yaml manifest. Use the following code. Alternatively, this can also be the cell of a Jupyter notebook.

Pyomo app.py
HiGHS app.py

import os
import time

import nextmv
from nextmv import local

# Instantiate the local app.
local_app = local.Application(src=".")

# Start a new run, loading the data from a file.
problem = nextmv.load(path=os.path.join("inputs", "problem.json"))
run_id_1 = local_app.new_run(input=problem.data)

# Sleep and get metadata, output (results), logs.
time.sleep(3)

run_metadata_1 = local_app.run_metadata(run_id=run_id_1)
nextmv.write(run_metadata_1)

run_results_1 = local_app.run_result(run_id=run_id_1)
nextmv.write(run_results_1.output)

run_logs_1 = local_app.run_logs(run_id=run_id_1)
print(run_logs_1)

Run the app.py script, or notebook cell.

Bash

python app.py

You will see results similar to the following in your terminal:

Pyomo
HiGHS

{
  "description": "Local run created at 2025-11-10T17:20:43.386461Z",
  "id": "local-h61b3nvr",
  "metadata": {
    "application_id": ".",
    "application_instance_id": "",
    "application_version_id": "",
    "created_at": "2025-11-10T17:20:43.386461Z",
    "duration": 1063.7,
    "error": "",
    "input_size": 877.0,
    "output_size": 0.0,
    "format": {
      "input": {
        "type": "json"
      },
      "output": {
        "type": "json"
      }
    },
    "status_v2": "succeeded"
  },
  "name": "local run local-h61b3nvr",
  "user_email": "",
  "console_url": ""
}
{
  "options": {
    "duration": 1,
    "solver": "glpk",
    "input": "",
    "output": ""
  },
  "solution": {
    "shipments": [
      {
        "from": "seattle",
        "to": "new-york",
        "quantity": 50.0
      },
      {
        "from": "seattle",
        "to": "chicago",
        "quantity": 300.0
      },
      {
        "from": "san-diego",
        "to": "new-york",
        "quantity": 275.0
      },
      {
        "from": "san-diego",
        "to": "topeka",
        "quantity": 275.0
      }
    ]
  },
  "statistics": {
    "result": {
      "duration": 0.006533145904541016,
      "value": 153.67499999999998,
      "custom": {
        "variables": 6,
        "constraints": 5,
        "num_edges_used": 4
      }
    },
    "schema": "v1"
  },
  "assets": []
}
# ==========================================================
# = Solver Results                                         =
# ==========================================================
# ----------------------------------------------------------
#   Problem Information
# ----------------------------------------------------------
Problem: 
- Name: unknown
  Lower bound: 153.675
  Upper bound: 153.675
  Number of objectives: 1
  Number of constraints: 5
  Number of variables: 6
  Number of nonzeros: 12
  Sense: minimize
# ----------------------------------------------------------
#   Solver Information
# ----------------------------------------------------------
Solver: 
- Status: ok
  Termination condition: optimal
  Statistics: 
    Branch and bound: 
      Number of bounded subproblems: 0
      Number of created subproblems: 0
  Error rc: 0
  Time: 0.006533145904541016
# ----------------------------------------------------------
#   Solution Information
# ----------------------------------------------------------
Solution: 
- number of solutions: 0
  number of solutions displayed: 0

Displaying Solution
------------------------------------------------------------
x : Shipment quantities in case
    Size=6, Index=i*j
    Key                       : Lower : Value : Upper : Fixed : Stale : Domain
     ('san-diego', 'chicago') :   0.0 :   0.0 :  None : False : False :  Reals
    ('san-diego', 'new-york') :   0.0 : 275.0 :  None : False : False :  Reals
      ('san-diego', 'topeka') :   0.0 : 275.0 :  None : False : False :  Reals
       ('seattle', 'chicago') :   0.0 : 300.0 :  None : False : False :  Reals
      ('seattle', 'new-york') :   0.0 :  50.0 :  None : False : False :  Reals
        ('seattle', 'topeka') :   0.0 :   0.0 :  None : False : False :  Reals

The local package allows you to perform runs on the application and store the inputs, options, logs, and outputs that are associated with the run. As you can tell, depending on the content format used for each application, you work with the data differently.

For a json application, you send a dict to the new_run method.
For a multi-file application, you specify a dir where the input files are stored.

Similarly, the content format dictates how to get the output data.

For a json application, the output dict can be obtained from the results.
For a multi-file application, the output files are written to the path specified in the argument.

The run is started and completed in a background process. Instead of sleeping and waiting for the results, you can poll for the run to be finished.

Replace the app.py script, by using the following code. You may also run this code in a new Jupyter notebook cell:

Pyomo app.py
HiGHS app.py

import os

import nextmv
from nextmv import local

# Instantiate the local app.
local_app = local.Application(src=".")

# Start a new run, loading the data from a file, and poll for results.
problem = nextmv.load(path=os.path.join("inputs", "problem.json"))
run_results_2 = local_app.new_run_with_result(input=problem.data)
nextmv.write(run_results_2)  # This time, print both metadata and output at once.

run_logs_2 = local_app.run_logs(run_id=run_results_2.id)
print(run_logs_2)

Running the app.py script again (or the new notebook cell), you'll notice that the results are duplicated, as you are performing the same run but waiting for the results concurrently.

If you inspect the file structure of your application, you will find a tree similar to this:

Pyomo
HiGHS

.
├── .nextmv
│   └── runs
│       ├── {RUN_ID_1}
│       │   ├── inputs
│       │   │   └── input.json
│       │   ├── {RUN_ID_1}.json
│       │   ├── logs
│       │   │   └── logs.log
│       │   ├── outputs
│       │   │   ├── assets
│       │   │   │   └── assets.json
│       │   │   ├── solutions
│       │   │   │   └── solution.json
│       │   │   └── statistics
│       │   │       └── statistics.json
│       │   └── visuals
│       └── {RUN_ID_2}
│           ├── inputs
│           │   └── input.json
│           ├── {RUN_ID_2}.json
│           ├── logs
│           │   └── logs.log
│           ├── outputs
│           │   ├── assets
│           │   │   └── assets.json
│           │   ├── solutions
│           │   │   └── solution.json
│           │   └── statistics
│           │       └── statistics.json
│           └── visuals
├── app.py
├── app.yaml
├── inputs
│   └── problem.json
├── main.py
└── requirements.txt

20 directories, 17 files

The .nextmv dir is used to store and manage the local applications run in a structured way. The local package is used to interact with these files, with methods for starting runs, retrieving results, visualizing charts, and more.

7. Create an account

The local experience is a great free starting point, but the full suite of benefits start with a Nextmv Cloud account.

Sign up for a Nextmv account at https://cloud.nextmv.io.
Verify your account.
- You'll receive an email asking to verify your account.
- Follow the link in that email to sign in.
Log in to your account.

Once you have logged in to your account, you need to fetch your API key. You can do so from your settings.

API keys

When you have your API key, it is convenient to save it as an environment variable so that you can use for the rest of this tutorial.

Bash

export NEXTMV_API_KEY="<YOUR-API-KEY>"

8. Sync local runs to Nextmv Cloud

Replace the app.py script, by using the following code. You may also run this code in a new Jupyter notebook cell:

Pyomo app.py
HiGHS app.py

import os

from nextmv import cloud, local

# Instantiate the local app.
local_app = local.Application(src=".")

# Instantiate the cloud app.
client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
cloud_app = cloud.Application.new(
    client=client,
    name="test-pyomo-app",
    id="test-pyomo-app",
    exist_ok=True,
)

# Sync the local app's runs to the cloud app.
local_app.sync(target=cloud_app, verbose=True)

You will now track these runs in Nextmv Cloud, as external runs. After you run the script, or notebook cell, you should see an output similar to this one, where it shows which runs were synced successfully.

Bash

☁️ Starting sync of local application `.` to Nextmv Cloud application `test-highs-app`.
ℹ️  Found 4 local runs to sync from ./.nextmv/runs.
🔄 Syncing local run `local-gmrkwzrp`...
✅ Synced local run `local-gmrkwzrp` as remote run `{'run_id': 'devint-uPu85_zDg', 'synced_at': '2025-11-10T19:40:00.130408Z', 'app_id': 'test-highs-app'}`.
🔄 Syncing local run `local-ihnmua49`...
✅ Synced local run `local-ihnmua49` as remote run `{'run_id': 'devint-P5RwclkDg', 'synced_at': '2025-11-10T19:40:04.842384Z', 'app_id': 'test-highs-app'}`.
🔄 Syncing local run `local-v8wh5r82`...
✅ Synced local run `local-v8wh5r82` as remote run `{'run_id': 'devint-zRnwclzvg', 'synced_at': '2025-11-10T19:40:09.561436Z', 'app_id': 'test-highs-app'}`.
🔄 Syncing local run `local-suoz75x3`...
✅ Synced local run `local-suoz75x3` as remote run `{'run_id': 'devint-i8DQ5_kDg', 'synced_at': '2025-11-10T19:40:14.467164Z', 'app_id': 'test-highs-app'}`.
🚀 Process completed, synced local application `.` to Nextmv Cloud application `test-highs-app`: 4/4 runs.

Depending on the number of times you run the script, you might be syncing more or fewer runs.

Go to the Apps in the Nextmv Console and click into your application.

Apps

In the overview of the application you will see the most recent runs. Click on any of the runs that were tracked.

Runs

You can use the Nextmv Console to browse the information of the run:

Summary
Output
Input
Metadata
Logs

Nextmv is built for collaboration, so you can invite team members to your account and share run URLs.

Run summary Run metadata

9. Push your Nextmv Application

So far, your application has run locally. We are going to push your app to Nextmv Cloud. Once an application has been pushed, you can run it remotely, perform testing, experimentation, and much more. Pushing is the equivalent of deploying an application, this is, taking the executable code and sending it to Nextmv Cloud.

Replace the app.py script, by using the following code. You may also run this code in a new Jupyter notebook cell:

Pyomo app.py
HiGHS app.py

import os

import nextmv
from nextmv import cloud

# Instantiate the cloud app.
client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
cloud_app = cloud.Application.new(
    client=client,
    name="test-pyomo-app",
    id="test-pyomo-app",
    exist_ok=True,
)

# Push the app.
manifest = nextmv.Manifest.from_yaml(dirpath=".")
cloud_app.push(manifest=manifest, app_dir=".", verbose=True)

After you run the script, or notebook cell, you should see an output similar to this one, where it shows the app being bundled and pushed to Nextmv Cloud.

Bash

💽 Starting build for Nextmv application.
🐍 Bundling Python dependencies.
📋 Copied files listed in "app.yaml" manifest.
📦 Packaged application (3296 files, 29.10 MiB).
🌟 Pushing to application: "test-highs-app".
💥️ Successfully pushed to application: "test-highs-app".
{
  "app_id": "test-highs-app",
  "endpoint": "https://api.cloud.nextmv.io",
  "instance_url": "v1/applications/test-highs-app/runs?instance_id=latest"
}

Refreshing the overview of the application in the Nextmv Console should show that there is now a pushed executable that is assigned to the latest instance. An instance is like the endpoint of the application.

Pushed app

10. Run the Nextmv Application remotely

To run the Nextmv Application remotely, you have several options, like using the cloud package of the Python SDK. For this tutorial, we will be using the Nextmv Console.

Press the "New run" button.
Drop the data files that you want to use. You will get a preview of the data.
- For Pyomo, use the problem.json file.
- For HiGHS, use both the nodes.json and edges.csv files.
Configure your run according to the options that are set in the app.yaml manifest.
- For Pyomo, you can configure the duration and solver.
- For HiGHS, you can configure the duration.
Start the run.

New run Pyomo New run HiGHS

Navigate around to visualize the results of the run. This should look, and feel, like the external (local) run you tracked in a previous step. In this case, the run was executed on Nextmv Cloud.

11. Perform a scenario test

We are going to take full advantage of the Nextmv Platform by doing a scenario test. Scenario tests are generally used as an exploratory test to understand the impacts to business metrics (or KPIs) on situations such as:

Updating a model with a new feature, such as an additional constraint.
Comparing how the same model performs in different conditions, such as low demand vs. high demand.
Doing a sensitivity analysis to understand how the model behaves when changing a parameter.

Start by creating an input set. As the name suggests, it is a set of inputs, and it serves as a base so that we can perform runs varying one or more configurations (options). To create an input set, you have several options, like using the cloud package of the Python SDK. For this tutorial, we will be using the Nextmv Console. You may follow these steps for both examples.

Navigate to the "Input sets" section.
Set a name for your input set.
Use the "Instance + date range" creation type given that we already have a few runs on the latest instance.
Create the input set.

Input set

Once your input set has been created, we are going to create a scenario test. Similarly to runs, and input sets, you may use the cloud package of the Python SDK, amongst other options. We will continue to use the Nextmv Console in this tutorial. You may follow these steps for both examples.

Navigate to the "Scenario" section.
Set a name for your scenario test.
Select the input set you just created in the previous step.
Select the latest instance.
Create configuration combinations, which will be factored to create the scenarios.
- For Pyomo, we are setting duration to be 1, 3, and 5 seconds; and for solver we are comparing the three supported solvers: glpk, scip and cbc.
- For HiGHS, we are setting duration to be 1, 3, and 5 seconds.
Optionally, you may configure repetitions. These are useful when the results are not deterministic.
Create the scenario test. Review and confirm the number of scenarios that will be created.

Scenario test Pyomo Scenario test HiGHS

Once all the runs in the scenario test are completed, you can visualize the result of the test. A pivot table is provided to create useful comparisons of your metrics (statistics) across the scenario test runs.

Scenario test result

🎉🎉🎉 Congratulations, you have finished this tutorial!

Full tutorial code

You can find the consolidated code examples used in this tutorial in the tutorials GitHub repository. The bring-your-own-model-python dir contains all the code that was shown in this tutorial.

For each of the examples, you will find two directories:

original: the original example without any modifications.
nextmv-ified: the example converted into a Nextmv Application.

Go into each directory for instructions about running the decision model.

For your convenience, here are the full app.py scripts for the Pyomo and HiGHS examples.

Pyomo app.py
HiGHS app.py

import os
import time

import nextmv
from nextmv import cloud, local

# Instantiate the local app.
local_app = local.Application(src=".")

# Start a new run, load the data from a file.
problem = nextmv.load(path=os.path.join("inputs", "problem.json"))
run_id_1 = local_app.new_run(input=problem.data)

# Sleep and get metadata, output (results), logs.
time.sleep(3)

run_metadata_1 = local_app.run_metadata(run_id=run_id_1)
nextmv.write(run_metadata_1)

run_results_1 = local_app.run_result(run_id=run_id_1)
nextmv.write(run_results_1.output)

run_logs_1 = local_app.run_logs(run_id=run_id_1)
print(run_logs_1)

# Start a new run, and poll for results.
run_results_2 = local_app.new_run_with_result(input=problem.data)
nextmv.write(run_results_2)  # This time, print both metadata and output at once.

run_logs_2 = local_app.run_logs(run_id=run_results_2.id)
print(run_logs_2)

# Instantiate the cloud app.
client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
cloud_app = cloud.Application.new(
    client=client,
    name="test-pyomo-app",
    id="test-pyomo-app",
    exist_ok=True,
)

# Sync the local app's runs to the cloud app.
local_app.sync(target=cloud_app, verbose=True)

# Push the app.
manifest = nextmv.Manifest.from_yaml(dirpath=".")
cloud_app.push(manifest=manifest, app_dir=".", verbose=True)

Bring your own model to Nextmv with Python

A tutorial to explore the Nextmv Platform using a custom Python model.

1. Prepare the executable code

2. Install requirements

3. Run the executable code

4. Nextmv-ify the decision model

5. Install the Nextmv Python SDK

6. Run the Nextmv Application locally

7. Create an account

8. Sync local runs to Nextmv Cloud

9. Push your Nextmv Application

10. Run the Nextmv Application remotely

11. Perform a scenario test

Full tutorial code

Overview

Platform

Contents