Nextmv

https://www.nextmv.io/docs
Admin
Nextmv is a DecisionOps platform that accelerates teams with optimization tooling, solver...
Tokens:512,783
Snippets:2,629
Trust Score:8.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### Update Nextmv Platform and Install SDK (Bash)

Source: https://www.nextmv.io/docs/releases/archive/v0-32-0-bugfixes-and-improvements

Commands to update the Nextmv platform to the latest version and install the SDK. Assumes the user has completed the quick start guide.

```bash
nextmv update
nextmv sdk install

```

--------------------------------

### Install Hexaly Solver (Dockerfile)

Source: https://www.nextmv.io/docs/using-nextmv/deploy/app/runtimes

This Dockerfile snippet sets up a Python runtime, installs wget, and then downloads and installs the Hexaly solver by making the downloaded installer executable and running it.

```dockerfile
FROM ghcr.io/nextmv-io/runtime/python:3.11

# Set a default working directory.
WORKDIR /app

# Update the package list and install deps.
RUN apt-get update
RUN apt-get install -y wget

# Set Hexaly variables.
ENV HEXALY_VERSION=13_0_20240712
ENV HEXALY_FILE=Hexaly_${HEXALY_VERSION}_LinuxA64.run

# Download the Hexaly solver.
RUN wget https://www.hexaly.com/downloads/${HEXALY_FILE}

# Install the Hexaly solver.
RUN chmod +x ${HEXALY_FILE}
RUN bash ${HEXALY_FILE}
```

--------------------------------

### Install SCIP Solver and Dependencies (Dockerfile)

Source: https://www.nextmv.io/docs/using-nextmv/deploy/app/runtimes

This snippet installs essential build tools and libraries required for compiling the SCIP solver, then downloads, builds, and installs the SCIP solver itself. It also installs Python dependencies from requirements.txt.

```dockerfile
RUN apt-get install -y \
    wget \
    gcc \
    g++ \
    gfortran \
    liblapack3 \
    libtbb12 \
    libcliquer1 \
    libopenblas-dev \
    libgsl27 \
    patchelf \
    cmake \
    wget \
    m4 \
    xz-utils \
    libgmp-dev \
    unzip \
    zlib1g-dev \
    libboost-program-options-dev \
    libboost-serialization-dev \
    libboost-regex-dev \
    libboost-iostreams-dev \
    libtbb-dev \
    libreadline-dev \
    pkg-config \
    git \
    liblapack-dev \
    libgsl-dev \
    flex \
    bison \
    libcliquer-dev \
    gfortran \
    file \
    dpkg-dev \
    libopenblas-dev \
    rpm

ENV SCIP_VERSION=9.1.1
ENV SCIP_DIR=scip-ச்சல்${SCIP_VERSION}
ENV SCIP_TAR=${SCIP_DIR}.tgz
RUN wget https://scipopt.org/download/release/${SCIP_TAR}

RUN tar xvzf ${SCIP_TAR} && \
    cd ${SCIP_DIR} && \
    mkdir build && \
    cd build && \
    ls -lah && \
    cmake .. -DAUTOBUILD=on -DCMAKE_INSTALL_PREFIX=/usr && \
    make && \
    make check && \
    make install && \
    cp -r bin/* /usr/bin && \
    cp -r lib/* /usr/lib

# Install requirements.
COPY requirements.txt .
RUN pip install --upgrade pip
RUN pip install -r requirements.txt

# Clean up.
RUN rm ${SCIP_TAR}
RUN rm -rf ${SCIP_DIR}
```

--------------------------------

### Install Nextmv Python SDK with All Dependencies

Source: https://www.nextmv.io/docs/python-sdks/nextmv/installation

Installs the Nextmv Python SDK along with all its optional dependencies. This is recommended for full functionality and access to extended features.

```Bash
pip install "nextmv[all]"
```

--------------------------------

### Install Nextmv Python SDK

Source: https://www.nextmv.io/docs/python-sdks/nextmv/installation

Installs the core Nextmv Python SDK package using pip. This is the basic installation for interacting with the Nextmv Platform.

```Bash
pip install nextmv
```

--------------------------------

### Nextmv IO Configuration Example

Source: https://www.nextmv.io/docs/use-cases/vehicle-routing

This snippet shows a basic configuration object for a Nextmv IO problem, including solver settings like deterministic runs and starting solutions.

```json
{
  "relative_threshold": 0
},
"run_deterministically": true,
"start_solutions": 1
}
```

--------------------------------

### Build and Install SCIP Solver

Source: https://www.nextmv.io/docs/platform/execution-environment/runtimes

This Dockerfile snippet compiles and installs the SCIP solver after downloading and extracting its source code. It uses CMake for the build process and installs the solver to /usr.

```Dockerfile
RUN tar xvzf ${SCIP_TAR} && \
    cd ${SCIP_DIR} && \
    mkdir build && \
    cd build && \
    ls -lah && \
    cmake .. -DAUTOBUILD=on -DCMAKE_INSTALL_PREFIX=/usr && \
    make && \
    make check && \
    make install && \
    cp -r bin/* /usr/bin && \
    cp -r lib/* /usr/lib
```

--------------------------------

### Create and Start Batch Experiment

Source: https://www.nextmv.io/docs/using-nextmv/reference/api

Creates and starts a batch experiment for an application.

```APIDOC
## POST /v1/applications/{application_id}/experiments/batch

### Description
Create and start batch experiment.

### Method
POST

### Endpoint
/v1/applications/{application_id}/experiments/batch

### Parameters
#### Path Parameters
- **application_id** (string) - Required - The ID of the application.

#### Request Body
- **experiment_config** (object) - Required - Configuration for the batch experiment.

### Request Example
{
  "experiment_config": { "version_id": "v1", "input_set_id": "iset_abc", "runs": 5 }
}

### Response
#### Success Response (200)
- **batch_id** (string) - The ID of the created batch experiment.

#### Response Example
{
  "batch_id": "batch_xyz"
}
```

--------------------------------

### Create and Start Batch Experiment

Source: https://www.nextmv.io/docs/reference/experiments/batch

Creates and starts a batch experiment with the specified ID, name, input set, and instances.

```APIDOC
## POST /v1/applications/{APP_ID}/experiments/batch

### Description
Creates and starts a batch experiment. You need to define the desired batch experiment ID and name, and then create the batch experiment.

### Method
POST

### Endpoint
/v1/applications/{APP_ID}/experiments/batch

### Parameters
#### Path Parameters
- **APP_ID** (string) - Required - The ID of the application.

#### Query Parameters
None

#### Request Body
- **id** (string) - Required - The desired batch experiment ID.
- **name** (string) - Required - The desired batch experiment name.
- **input_set_id** (string) - Required - The ID of the input set to use for the experiment.
- **instance_ids** (array of strings) - Required - An array of instance IDs to run the experiment on.
- **description** (string) - Optional - An optional description for the experiment.

### Request Example
```json
{
  "id": "$EXPERIMENT_ID",
  "name": "YOUR_EXPERIMENT_NAME",
  "input_set_id": "$INPUT_SET_ID",
  "instance_ids": ["$INSTANCE_ID", "$INSTANCE_ID"],
  "description": "An optional description"
}
```

### Response
#### Success Response (200)
- **id** (string) - The batch experiment ID that was specified.
- **name** (string) - The batch experiment name that was specified.
- **description** (string) - The batch experiment description that was specified. If no description was specified this field will not exist.
- **status** (string) - The status of the experiment. The status can be: `started`, `completed`, or `failed`.
- **created_at** (string) - The date the experiment was created and started.
- **input_set_id** (string) - The input set ID specified for the batch experiment.
- **instance_ids** (array of strings) - An array of the Instance IDs that were specified for the batch experiment.
- **grouped_distributional_summaries** (array) - The grouped distributional summaries is an array that contains the results of the batch experiment. It is a collection of calculated results from the individual runs by certain groupings.

#### Response Example
```json
{
  "id": "exp-12345",
  "name": "My Batch Experiment",
  "description": "An optional description",
  "status": "started",
  "created_at": "2023-10-27T10:00:00Z",
  "input_set_id": "input-set-abc",
  "instance_ids": ["instance-1", "instance-2"],
  "grouped_distributional_summaries": [
    {
      "key": "route_time",
      "summaries": [
        {
          "value": 120,
          "count": 100,
          "percentiles": {
            "0": 90,
            "50": 110,
            "95": 130
          }
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Clone Community App using Nextmv CLI (Bash)

Source: https://www.nextmv.io/docs/integrations/modeling/pyoptinterface

This bash command uses the Nextmv CLI to clone a community application that demonstrates PyOptInterface integration for solving a knapsack problem. This is a quick way to get started with the library.

```bash
nextmv community clone -a python-pyoptinterface-knapsack

```

--------------------------------

### Install Hexaly Solver

Source: https://www.nextmv.io/docs/platform/execution-environment/runtimes

This Dockerfile snippet makes the downloaded Hexaly solver executable and runs the installer.

```Dockerfile
# Install the Hexaly solver.
RUN chmod +x ${HEXALY_FILE}
RUN bash ${HEXALY_FILE}
```

--------------------------------

### Install Nextmv CLI (Windows PowerShell)

Source: https://www.nextmv.io/docs/platform/installation

Installs the Nextmv CLI on Windows systems using PowerShell by downloading and executing an installation script. It also sets the Nextmv base URL.

```powershell
$env:NEXTMV_BASE_URL="https://api.cloud.nextmv.io"
(New-Object System.Net.WebClient).DownloadString("https://cloud.nextmv.io/install-cli.txt") | Invoke-Expression
```

--------------------------------

### Install Hexaly Solver Requirements

Source: https://www.nextmv.io/docs/platform/execution-environment/runtimes

This Dockerfile snippet installs the 'wget' utility to download the Hexaly solver.

```Dockerfile
FROM ghcr.io/nextmv-io/runtime/python:3.11

# Set a default working directory.
WORKDIR /app

# Update the package list and install deps.
RUN apt-get update
RUN apt-get install -y wget

# Set Hexaly variables.
ENV HEXALY_VERSION=13_0_20240712
ENV HEXALY_FILE=Hexaly_\${HEXALY_VERSION}_LinuxA64.run

# Download the Hexaly solver.
RUN wget https://www.hexaly.com/downloads/${HEXALY_FILE}
```

--------------------------------

### Running Applications

Source: https://www.nextmv.io/docs/core-concepts/apps

This section details how to initiate a run for an application, specifying which instance to use. You can explicitly select an instance via a query parameter or rely on the default instance.

```APIDOC
## POST /api/apps/{app-id}/runs

### Description
Submits input to the application to start a run. The instance to be used is determined by the `instance_id` query parameter or the application's default instance.

### Method
POST

### Endpoint
/api/apps/{app-id}/runs

### Parameters
#### Path Parameters
- **app-id** (string) - Required - The unique identifier of the application.

#### Query Parameters
- **instance_id** (string) - Optional - The ID of the specific instance to use for the run. If not provided, the application's default instance is used. Use `devint` to target the most recently pushed binary.

#### Request Body
- **input_data** (object) - Required - The input data for the model run.

### Request Example
```json
{
  "input_data": {
    "scenario": "example_scenario"
  }
}
```

### Response
#### Success Response (200)
- **run_id** (string) - The unique identifier for the initiated run.
- **status** (string) - The initial status of the run (e.g., "QUEUED", "RUNNING").

#### Response Example
```json
{
  "run_id": "run-mno789pqr",
  "status": "QUEUED"
}
```
```

--------------------------------

### NextMV Duration Matrix Indexing Order

Source: https://www.nextmv.io/docs/use-cases/vehicle-routing/features/duration-matrix

This example outlines the required order of indices within a Nextmv duration matrix. It specifies that stops should be listed first, followed by the start and end locations for each vehicle.

```json
[
  stop-1, ..., stop-n,
  vehicle-1-start-location, vehicle-1-end-location, ..., vehicle-m-start-location, vehicle-m-end-location
]
```

--------------------------------

### Create Application Instance

Source: https://www.nextmv.io/docs/using-nextmv/reference/cli

Creates a new instance for an application using a specified version. Optional parameters include instance ID, name, and description. Options can be passed as key-value pairs.

```bash
nextmv app instance create --app-id <application_id> --version-id <version_id> [--instance-id <instance_id>] [--name <instance_name>] [--description <instance_description>] [--options "key1=value1,key2=value2"]
```

--------------------------------

### Set-based input example for vehicle shifts in Go

Source: https://www.nextmv.io/docs/releases/archive/2023-06-30-marketplace-beta

Demonstrates the structure of set-based inputs for vehicle shifts, where multiple shift start and end times are grouped under a single 'shifts' key. This is typical for older SDK routing templates.

```json
"shifts": [
  {
    "start": "2020-10-17T09:00:00-06:00",
    "end": "2020-10-17T17:00:00-06:00"
  },
  {
    "start": "2020-10-17T09:00:00-06:00",
    "end": "2020-10-17T17:00:00-06:00"
  }
],
```

--------------------------------

### Stop Start Time Window Example

Source: https://www.nextmv.io/docs/vehicle-routing/reference

Demonstrates the 'start_time_window' field, defining acceptable time ranges for starting service at a stop.

```json
{"start_time_window": [["2023-01-01T12:00:00Z", "2023-01-01T12:05:00Z"], ["2023-01-01T12:30:00Z", "2023-01-01T13:35:00Z"]]}
```

--------------------------------

### Run with Solver Options (Bash)

Source: https://www.nextmv.io/docs/platform/deploy-app/instances

Demonstrates how to run an application locally using the Go 'mip' template, passing solver options like input/output paths and solve duration as command-line flags.

```bash
go run . -runner.input.path input.json -runner.output.path output.json -solve.duration 10s
```

--------------------------------

### Get Run Result Example (nextmv app result)

Source: https://www.nextmv.io/docs/platform/reference/cli

Retrieves the actual output of an application run, particularly when formatted as JSON. Requires the app-id and run-id. This is distinct from getting just the metadata.

```bash
nextmv app result \
    --app-id $APP_ID \
    --run-id $RUN_ID
```

--------------------------------

### Run with Solver Options (Bash)

Source: https://www.nextmv.io/docs/platform/deploy-app/instances

Shows how to execute a Python 'pyomo' template locally, providing solver options such as input/output files, duration, and provider via command-line arguments.

```bash
python3 main.py -input input.json -output output.json -duration 30 -provider cbc
```

--------------------------------

### Submit New Run Example (nextmv app run)

Source: https://www.nextmv.io/docs/platform/reference/cli

Shows how to submit a new application run and obtain a run ID. This example specifies the application, instance, input file, and custom run options.

```bash
nextmv app run \
    --app-id $APP_ID \
    --instance $INSTANCE_ID \
    --input $INPUT_FILE \
    --options "solve.duration=10s,solve.iterations=20"
```

--------------------------------

### Run Start Response (JSON)

Source: https://www.nextmv.io/docs/platform/run-app-remotely/large-payloads

Example JSON response after starting a run with a large input. It contains the 'run_id', which is essential for retrieving the status and results of the completed run.

```json
{
  "run_id": "instance1-a_USaanxSR"
}

```

--------------------------------

### Entity-based inputs example for vehicles in Go

Source: https://www.nextmv.io/docs/release-notes/archive/2023-06-30-marketplace-beta

An example of entity-based inputs in Go, used by the nextroute template. Vehicle start and end times are represented within each vehicle entity, unlike set-based inputs.

```Go
"vehicles": [
  {
    "id": "v2",
    "start_location": {
      "lon": 135.772695,
      "lat": 34.967146
    },
    "start_time": "2023-01-01T12:00:00Z"
  },
  {
    "id": "v3",
    "end_location": {
      "lon": 135.762057,
      "lat": 35.025431
    },
    "start_time": "2023-01-01T12:00:00Z",
    "end_time": "2023-01-01T12:20:00Z"
  },
]

```

--------------------------------

### Running the Solver

Source: https://www.nextmv.io/docs/use-cases

Instructions on how to execute the solver program, specifying input and output files, and setting solver options like duration.

```APIDOC
## Running the Solver

### Description
This section details how to execute the NextMV solver, typically via the command line. It shows how to specify input and output files and configure solver parameters.

### Method
Command Line Execution

### Endpoint
N/A (Local execution)

### Parameters
#### Command Line Arguments
- `-runner.input.path` (string) - Required - Path to the input JSON file.
- `-runner.output.path` (string) - Required - Path for the output JSON file.
- `-solve.duration` (string) - Optional - The maximum duration for the solver (e.g., `10s`).

### Request Example
```bash
go run . -runner.input.path input.json -runner.output.path output.json -solve.duration 10s
```

### Response
#### Success Response
A JSON file specified by `-runner.output.path` will be created containing the routing solution.

#### Response Example (output.json)
```json
{
  "options": {
    "check": {
      "duration": 30000000000,
      "verbosity": "off"
    },
    "format": {
      "disable": {
        "progression": true
      }
    },
    "model": {
      "constraints": {
        "disable": {
          "attributes": false,
          "capacities": null,
          "capacity": false,
          "distance_limit": false,
          "groups": false,
          "maximum_duration": false,
          "maximum_stops": false,
          "maximum_wait_stop": false,
          "maximum_wait_vehicle": false,
          "mixing_items": false,
          "precedence": false,
          "start_time_windows": false,
          "vehicle_end_time": false,
          "vehicle_start_time": false
        },
        "enable": {
          "cluster": false
        }
      },
      "objectives": {
        "capacities": "",
        "cluster": 0,
        "early_arrival_penalty": 1,
        "late_arrival_penalty": 1,
        "min_stops": 1,
        "stop_balance": 0,
        "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
        },
        "maximum_time_horizon": 15552000
      },
      "validate": {
        "disable": {
          "resources": false,
          "start_time": false
        },
        "enable": {
          "matrix": false,
          "matrix_asymmetry_tolerance": 20
        }
      }
    },
    "solve": {
      "duration": 10000000000,
      "iterations": 50,
      "parallel_runs": 1,
      "plateau": {
        "absolute_threshold": -1,
        "delay": 0,
        "duration": 0,
        "iterations": 0
      }
    }
  }
}
```
```

--------------------------------

### Set-based inputs example for vehicle shifts in Go

Source: https://www.nextmv.io/docs/release-notes/archive/2023-06-30-marketplace-beta

An example of set-based inputs in Go, representing vehicle shifts with start and end times under a single 'shifts' key. This is characteristic of older router templates.

```Go
"shifts": [
  {
    "start": "2020-10-17T09:00:00-06:00",
    "end": "2020-10-17T17:00:00-06:00"
  },
  {
    "start": "2020-10-17T09:00:00-06:00",
    "end": "2020-10-17T17:00:00-06:00"
  }
],

```

--------------------------------

### NextMV CLI Overview and Available Commands

Source: https://www.nextmv.io/docs/using-nextmv/reference/cli

This displays the general usage of the NextMV CLI and lists all available top-level commands. It also shows global flags like `--config` and `--help` for configuring the CLI and accessing help.

```bash
The Nextmv Command Line Interface (CLI) to interact with the Platform.

Usage:
  nextmv [command]

Available Commands:
  account       Manage your Nextmv account.
  app           Commands to manage and interact with your applications.
  community     Interact with community apps.
  completion    Generate the autocompletion script for the specified shell
  configure     Configure the Nextmv CLI.
  experiment    Commands to run and manage experiments.
  help          Help about any command
  marketplace   Commands to manage and interact with marketplace.
  release-notes View release notes for the Nextmv CLI.
  update        Updates the CLI tool.
  version       Prints the Nextmv CLI version.

Flags:
  -c, --config string   Full path to config file.
  -h, --help            Help for nextmv.

Use "nextmv [command] --help" for more information about a command.
```

--------------------------------

### Vehicle Routing Input Example (JSON)

Source: https://www.nextmv.io/docs/use-cases/vehicle-routing/features/vehicle-start-end-location

This JSON input demonstrates how to configure vehicle routing problems, including defining stops, vehicle speeds, and specifying start and end locations for individual vehicles.

```json
{
  "defaults": {
    "vehicles": {
      "speed": 20
    }
  },
  "stops": [
    {
      "id": "Fushimi Inari Taisha",
      "location": { "lon": 135.772695, "lat": 34.967146 }
    },
    {
      "id": "Kiyomizu-dera",
      "location": { "lon": 135.78506, "lat": 34.994857 }
    },
    {
      "id": "Nijō Castle",
      "location": { "lon": 135.748134, "lat": 35.014239 }
    },
    {
      "id": "Kyoto Imperial Palace",
      "location": { "lon": 135.762057, "lat": 35.025431 }
    },
    {
      "id": "Kinkaku-ji",
      "location": { "lon": 135.728898, "lat": 35.039705 }
    },
    {
      "id": "Arashiyama Bamboo Forest",
      "location": { "lon": 135.672009, "lat": 35.017209 }
    }
  ],
  "vehicles": [
    {
      "id": "v1"
    },
    {
      "id": "v2",
      "start_location": {
        "lon": 135.772695,
        "lat": 34.967146
      }
    },
    {
      "id": "v3",
      "end_location": {
        "lon": 135.762057,
        "lat": 35.025431
      }
    },
    {
      "id": "v4",
      "start_location": {
        "lon": 135.775683,
        "lat": 35.002458
      },
      "end_location": {
        "lon": 135.775683,
        "lat": 35.002458
      }
    }
  ]
}
```

--------------------------------

### Get Nextmv CLI version

Source: https://www.nextmv.io/docs/platform/run-app-remotely/nextmv-cli

Displays the command to retrieve the currently installed Nextmv CLI version.

```bash
nextmv version [flags]
The `version` command prints the Nextmv CLI version.
```

--------------------------------

### Complete Run Workflow Example (nextmv app run --wait)

Source: https://www.nextmv.io/docs/platform/reference/cli

Demonstrates a complete application run workflow by submitting a run, polling for its status, and retrieving results. It utilizes flags for app ID, instance ID, input file, custom options, and waiting for completion.

```bash
nextmv app run \
    --app-id $APP_ID \
    --instance $INSTANCE_ID \
    --input $INPUT_FILE \
    --options "solve.duration=10s,solve.iterations=20" \
    --wait
```

--------------------------------

### Get MLPRegressor Statistics with Nextmv Python SDK

Source: https://www.nextmv.io/docs/python-sdks/nextmv-scikit-learn/statistics

This Python code shows how to use the Nextmv Python SDK to get statistics for an MLP Regressor. It uses the `MLPRegressorStatistics` class, which requires the fitted model, training data (X, y), and a start time.

```python
import json

from nextmv_sklearn import neural_network

# Model code here.

statistics = neural_network.MLPRegressorStatistics(fit, X, y, run_duration_start=start_time)
print(json.dumps(statistics.to_dict(), indent=2))
```

--------------------------------

### Start Batch Experiment via Nextmv CLI (Bash)

Source: https://www.nextmv.io/docs/platform/experiments-tests/batch-experiments

Initiates a batch experiment using the Nextmv CLI. Requires application ID, experiment ID, input set ID, and optionally instance IDs, description, and confirmation.

```Bash
nextmv experiment batch start \
    --app-id $APP_ID \
    --experiment-id $EXPERIMENT_ID \
    --name $EXPERIMENT_ID \
    --input-set-id $INPUT_SET_ID \
    --instance-ids "latest,latest-2" \
    --description "An optional description" \
    --confirm
```

--------------------------------

### Shadow Tests API

Source: https://www.nextmv.io/docs/reference/api/usage

Create, list, get, update, start, stop, and retrieve runs and metadata for shadow tests.

```APIDOC
## POST /v1/applications/{application_id}/experiments/shadow

### Description
Create a shadow test in draft mode.

### Method
POST

### Endpoint
https://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/shadow

### Parameters
#### Path Parameters
- **application_id** (string) - Required - The ID of the application.

### Request Body
- **shadow_test_definition** (object) - Required - The definition of the shadow test.

### Response
#### Success Response (201)
- **created_shadow_test** (object) - Details of the created shadow test.

## GET /v1/applications/{application_id}/experiments/shadow

### Description
List shadow tests for an application.

### Method
GET

### Endpoint
https://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/shadow

### Parameters
#### Path Parameters
- **application_id** (string) - Required - The ID of the application.

### Response
#### Success Response (200)
- **shadow_tests** (array) - A list of shadow tests.

## GET /v1/applications/{application_id}/experiments/shadow/{shadow_id}

### Description
Get shadow test status and results specified by application and shadow ID.

### Method
GET

### Endpoint
https://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/shadow/{shadow_id}

### Parameters
#### Path Parameters
- **application_id** (string) - Required - The ID of the application.
- **shadow_id** (string) - Required - The ID of the shadow test.

### Response
#### Success Response (200)
- **shadow_test_details** (object) - Status and results of the shadow test.

## PATCH /v1/applications/{application_id}/experiments/shadow/{shadow_id}

### Description
Update a shadow test.

### Method
PATCH

### Endpoint
https://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/shadow/{shadow_id}

### Parameters
#### Path Parameters
- **application_id** (string) - Required - The ID of the application.
- **shadow_id** (string) - Required - The ID of the shadow test.

### Request Body
- **updates** (object) - The fields to update for the shadow test.

### Response
#### Success Response (200)
- **updated_shadow_test** (object) - Details of the updated shadow test.

## PUT /v1/applications/{application_id}/experiments/shadow/{shadow_id}/start

### Description
Start shadow test.

### Method
PUT

### Endpoint
https://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/shadow/{shadow_id}/start

### Parameters
#### Path Parameters
- **application_id** (string) - Required - The ID of the application.
- **shadow_id** (string) - Required - The ID of the shadow test.

### Response
#### Success Response (200)
- **start_status** (object) - Status of the shadow test start operation.

## PUT /v1/applications/{application_id}/experiments/shadow/{shadow_id}/stop

### Description
Stop shadow test.

### Method
PUT

### Endpoint
https://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/shadow/{shadow_id}/stop

### Parameters
#### Path Parameters
- **application_id** (string) - Required - The ID of the application.
- **shadow_id** (string) - Required - The ID of the shadow test.

### Response
#### Success Response (200)
- **stop_status** (object) - Status of the shadow test stop operation.

## GET /v1/applications/{application_id}/experiments/shadow/{shadow_id}/runs

### Description
List runs part of a shadow test.

### Method
GET

### Endpoint
https://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/shadow/{shadow_id}/runs

### Parameters
#### Path Parameters
- **application_id** (string) - Required - The ID of the application.
- **shadow_id** (string) - Required - The ID of the shadow test.

### Response
#### Success Response (200)
- **runs** (array) - A list of runs for the shadow test.

## GET /v1/applications/{application_id}/experiments/shadow/{shadow_id}/metadata

### Description
Get shadow test metadata specified by application and shadow test ID.

### Method
GET

### Endpoint
https://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/shadow/{shadow_id}/metadata

### Parameters
#### Path Parameters
- **application_id** (string) - Required - The ID of the application.
- **shadow_id** (string) - Required - The ID of the shadow test.

### Response
#### Success Response (200)
- **metadata** (object) - The metadata for the shadow test.
```

--------------------------------

### Managing Application Instances

Source: https://www.nextmv.io/docs/get-started/concepts/apps

This section details how to manage application instances, which represent specific versions and configurations for running applications. It covers the use of instances for different regions, testing configurations, and managing environments.

```APIDOC
## Instances

### Description
An application instance is a representation of a version and optional configuration that you want to use in some context. Instances are the mechanism by which a run is made.

### Use Cases
- Regional optimization logic
- Testing different app version/configuration combinations
- Staging and production environments
- Individual developer endpoints
- GitHub PR specific instances

### Instance Selection for Runs
An application determines which instance to use for a run in two ways:
1. Explicitly specified using a flag on the Nextmv CLI command or a query parameter in the API call.
2. Using a default instance set for the app, which is used when no instance is specified.

If no application instance is specified and no default application instance is defined, the run will fail.

### Version Management with Instances
The same version can be used by multiple application instances, and an instance's version can be changed. This allows for controlled rollout of model updates to specific environments.

Instances manage which versions are used for runs and provide consistent configuration per run.
```

--------------------------------

### Get Dummy Regressor Statistics with Nextmv Python SDK

Source: https://www.nextmv.io/docs/python-sdks/nextmv-scikit-learn/statistics

This snippet shows how to use the `DummyRegressorStatistics` from the Nextmv Python SDK to get statistics for a dummy regressor model. It takes the fitted model, training data (X, y), and a start time as input, and outputs statistics in JSON format.

```python
import json

from nextmv_sklearn import dummy

# Model code here.

statistics = dummy.DummyRegressorStatistics(fit, X, y, run_duration_start=start_time)
print(json.dumps(statistics.to_dict(), indent=2))
```

--------------------------------

### Time-Dependent Measure Implementation

Source: https://www.nextmv.io/docs/reference/sdk/measures

Provides an example of implementing a time-dependent measure, allowing the selection of routing measures based on the estimated time of arrival at the starting stop.

```go
timeDependentMeasure := nextmv.NewTimeDependentMeasure(dependentByIndex)
```

--------------------------------

### List available templates and versions

Source: https://www.nextmv.io/docs/platform/run-app-remotely/nextmv-cli

Explains how to list available Nextmv templates and their versions using the 'list' subcommand, with options to flatten the output.

```bash
Use the "--flat" flag to flatten the list of names/versions. Init a template with the "init" command.
The `list` subcommand lists the available templates. Use the corresponding flag to list the template's versions instead.
These are the available flags for the `list` subcommand:
Flag| Description  
---|---
`-t`, `--template` `string`| List the versions of the given template.  
`-f`, `--flat` `boolean`| Flat list of template's names. Flat list of an template's version when using the "template" flag.
```

--------------------------------

### Displaying Help Message for Python Script Options

Source: https://www.nextmv.io/docs/python-sdks/nextmv/options

Illustrates how to display the help message for a Python script, detailing all available options, their types, default values, and whether they are required.

```bash
$ python main.py --help
usage: main.py [options]

Options for main2.py. Use command-line arguments (highest precedence) or
environment variables.

options:
  -h, --help            show this help message and exit
  -str_option STR_OPTION, --str_option STR_OPTION
                        [env var: STR_OPTION] (required) (default: default
                        value) (type: str): A string option
  -int_option INT_OPTION, --int_option INT_OPTION
                        [env var: INT_OPTION] (default: 1) (type: int): An int
                        option
  -float_option FLOAT_OPTION, --float_option FLOAT_OPTION
                        [env var: FLOAT_OPTION] (default: 1.0) (type: float):
                        A float option
  -bool_option BOOL_OPTION, --bool_option BOOL_OPTION
                        [env var: BOOL_OPTION] (required) (default: True)
                        (type: bool): A bool option
```

--------------------------------

### Route Stop Data Example

Source: https://www.nextmv.io/docs/use-cases/vehicle-routing/get-started

This snippet shows an example of a single stop in a route, including its arrival time, cumulative travel duration and distance, the stop's duration, start and end times, stop details (ID and location with latitude/longitude), target arrival time, and travel duration and distance for that leg of the journey.

```json
{
              "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
            }
```

--------------------------------

### Get Run Metadata Example (nextmv app metadata)

Source: https://www.nextmv.io/docs/platform/reference/cli

Retrieves metadata for a specific application run, including its status. Requires the app-id and run-id obtained from submitting a run.

```bash
nextmv app metadata \
    --app-id $APP_ID \
    --run-id $RUN_ID
```

--------------------------------

### Promote Application Version (nextmv app promote)

Source: https://www.nextmv.io/docs/platform/reference/cli

Creates a new application version from the last pushed binary and assigns it to a specified or default instance. It handles creation of new instances if the specified ID does not exist. Flags control the app ID, version name, description, and instance ID.

```bash
nextmv app promote [flags]
```

--------------------------------

### Get Nextmv SSO Integration Information

Source: https://www.nextmv.io/docs/platform/reference/cli

Retrieves the current SSO integration configuration details for a Nextmv enterprise account. This command provides information about the active SSO setup.

```bash
nextmv account sso get
```

--------------------------------

### Create Application Instance

Source: https://www.nextmv.io/docs/platform/reference/cli

Creates a new application instance based on a specified application version. Requires application and version IDs. Optional flags allow for instance ID, name, description, and options.

```bash
nextmv app instance create [flags]
```

--------------------------------

### Create Batch Experiment

Source: https://www.nextmv.io/docs/platform/experiments-tests/batch-experiments

Initiates a new batch experiment on Nextmv Cloud. You can specify input sets, instances, and detailed run configurations including option sets.

```APIDOC
## POST /v1/applications/{application_id}/experiments/batch

### Description
Creates and starts a new batch experiment.

### Method
POST

### Endpoint
`https://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/batch`

### Parameters
#### Path Parameters
- **application_id** (string) - Required - The ID of the application to which the batch experiment belongs.

#### Request Body
- **id** (string) - Required - A unique identifier for the batch experiment.
- **name** (string) - Required - A human-readable name for the batch experiment.
- **description** (string) - Optional - A description for the batch experiment.
- **input_set_id** (string) - Required - The ID of the input set to use for the experiment.
- **instance_ids** (array of strings) - Optional - A list of instance IDs to use for the experiment. If not provided, all instances associated with the input set will be used.
- **option_sets** (object) - Optional - A dictionary where keys are option set IDs and values are objects containing configuration options for that set.
  - **option_set_id** (string) - Required - The identifier for the option set.
    - **string** (string) - Required - The configuration option key-value pair.
- **runs** (array of objects) - Optional - A list of specific runs to execute. If not provided, all combinations of input set and instance IDs will be run.
  - **instance_id** (string) - Required - The ID of the instance to use for this run.
  - **version_id** (string) - Optional - The ID of the model version to use for this run.
  - **option_set** (string) - Optional - The ID of the option set to apply to this run.
  - **input_id** (string) - Required - The ID of the input to use for this run. This can be a managed input ID or a previous run ID.

### Request Example
```json
{
  "id": "experiment-1",
  "name": "experiment-1",
  "description": "An optional description",
  "input_set_id": "input-set-1",
  "option_sets": {
    "long_running": {
      "solve.duration": "10s"
    },
    "short_running": {
      "solve.duration": "5s"
    }
  },
  "runs": [
    {
      "instance_id": "latest",
      "input_id": "latest-RNBs7AKSg",
      "option_set": "long_running"
    },
    {
      "instance_id": "latest-2",
      "input_id": "latest-RNBs7AKSg",
      "option_set": "short_running"
    },
    {
      "instance_id": "latest",
      "input_id": "latest-fK_wZ0FSg",
      "option_set": "long_running"
    },
    {
      "instance_id": "latest-2",
      "input_id": "latest-fK_wZ0FSg",
      "option_set": "short_running"
    }
  ]
}
```

### Response
#### Success Response (200)
- **experiment_id** (string) - The ID of the created batch experiment.
- **status** (string) - The initial status of the batch experiment (e.g., 'created', 'running').

#### Response Example
```json
{
  "experiment_id": "exp-abcdef123456",
  "status": "created"
}
```

#### Error Response (400, 404, 500)
- **error** (string) - A message describing the error.

```

--------------------------------

### Vehicle Definition Example

Source: https://www.nextmv.io/docs/use-cases/vehicle-routing/reference/input-output-schema

Defines a vehicle with an ID, start and end times for its operation, an optional activation penalty, and compatibility attributes. It also includes a maximum duration for its route.

```json
{
      "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"]
    }
```

```json
{
      "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"]
    }
```

--------------------------------

### Create CSV Input File

Source: https://www.nextmv.io/docs/using-nextmv/run/non-json

This snippet shows how to create a sample CSV file named 'example.csv' with order data. This file will be used as input for the Nextmv Cloud run.

```text
order_id,customer_id,order_due,order_value
1,1,2021-01-01,100
2,2,2021-01-02,200
3,3,2021-01-03,300
4,4,2021-01-04,400

```

--------------------------------

### Stop Definition Example

Source: https://www.nextmv.io/docs/use-cases/vehicle-routing/reference/input-output-schema

Defines a stop with an ID, location (longitude and latitude), and optional time windows for start and preceding/succeeding stops. This structure is fundamental for defining visit points in a routing problem.

```json
{
      "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"
      ]
    }
```

```json
{
      "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"
    }
```

--------------------------------

### Entity-based input example for vehicles in Go

Source: https://www.nextmv.io/docs/releases/archive/2023-06-30-marketplace-beta

Illustrates entity-based inputs for vehicles in the `nextroute` template, where each vehicle object contains its own `start_time` and `end_time`. This format is used by the `nextroute` template.

```json
"vehicles": [
  {
    "id": "v2",
    "start_location": {
      "lon": 135.772695,
      "lat": 34.967146
    },
    "start_time": "2023-01-01T12:00:00Z"
  },
  {
    "id": "v3",
    "end_location": {
      "lon": 135.762057,
      "lat": 35.025431
    },
    "start_time": "2023-01-01T12:00:00Z",
    "end_time": "2023-01-01T12:20:00Z"
  },
]
```
Tokens:
Raw