1. Using NVIDIA cuOpt

1.1. Learning Objectives

Demonstrate and provide a reference for the use of NVIDIA cuOpt to solve routing optimization problems in simulation.

Topics include:

  • Basic interaction with the cuOpt microservice

  • Visualization and processing of optimization specific data

  • Intra-warehouse transport use case demonstration

15-20 Minute Tutorial

1.2. Getting Started

Prerequisites

  • The example extensions used in this tutorial require a running instance of the cuOpt microservice. Developers can download cuOpt from NGC. Setup instructions for both local and remote instances can be found in the cuOpt-Resources GitHub Repository

    • Recommended cuOpt version: 22.12

    • Minimum cuOpt version: 22.10

  • Review the Core API Hello World and GUI Tutorial series Isaac Sim Interface.

  • NVIDIA cuOpt sample extensions are disabled by default. Enable the extensions required for this tutorial from the Extension Manager by searching for omni.cuopt.examples. Enabling omni.cuopt.examples will automatically enable omni.cuopt.microservice and omni.cuopt.visualization

1.3. NVIDIA cuOpt Examples

../_images/isaac_sim_app_logistics_tutorial_cuopt_examples.png

This tutorial is based around a set of 3 examples from the omni.cuopt.examples extension. These examples are arranged in increasing fidelity from simple randomized routing problems with only basic visualization, to an intra-warehouse transport scenario complete with high fidelity warehouse assets. Each example leverages supporting extensions in order to interact with the cuOpt microservice and visualize optimization data. The code for all examples and supporting extensions is available and can be extended for use in other applications.

1.3.1. Example Overview:

  • Simple Cost Matrix : A minimal example using simple primitives to represent a depot based fleet routing problem where vehicles start from a depot (Cone) and must fulfill the demand across all locations (Spheres). A cost Matrix representing the cost of travel between locations is created by measuring Euclidean distance between points. omni.cuopt.microservice is used for communication between scene data and a running cuOpt microservice instance.

  • Simple Waypoint Graph : cuOpt also supports a weighted waypoint graph representation of the optimization environment which is the focus of this example. Waypoint graphs are a common representation for interior environments where the cost between locations might not be predetermined and straight line distance is not sufficient. Here the waypoint graph represents the travel network, and target locations (a subset of graph nodes) represent the locations to be visited and the location of the fleet. In addition to using omni.cuopt.microservice, utilities from the omni.cuopt.visualization extension are used to process and display the waypoint graph as well as the resulting optimized routes. The waypoint graph, order data, and vehicle data are all loaded from json files that exist alongside the source code for this example and can be modified as needed.

  • Intra-warehouse Transport Demo : In this example a more complex waypoint graph is generated to represent the transportation network for a warehouse environment. The user is able to create and place semantic zones to denote high cost areas of travel to be avoided. In addition to the utilities used in the Simple Waypoint Graph example, additional functionality from the omni.cuopt.visualization extension is used to generate the warehouse environment from a json configuration files alongside the source code for the example.

1.3.2. Supporting Extension Overview :

  • omni.cuopt.microservice : This extension contains a thin wrapper around the cuOpt microservice that is used for preprocessing scene data as well as formatting and sending requests to the cuOpt microservice. This extension also contains utilities for representing the optimization data and formatting text results to be displayed in the UI for the examples.

  • omni.cuopt.visualization : This extension contains utilities for generating scene data including the waypoint graph, semantics zones and the warehouse environment. This extension also contains helper functions for adjusting the weight of graph edges based on proximity to a given semantic zone.

1.4. Running cuOpt Examples

  • Download and run the cuOpt microservice docker container. Note the IP and Port of the running microservice instance.

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_dlrun.png
  • Enable omni.cuopt.examples from the Extension Manager

1.4.1. Simple Cost Matrix

  1. Starting from a New Isaac Sim Session (CTRL + N) navigate to the cuOpt menu item now present in the Isaac Sim interface and select Simple Cost Matrix

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_select_costmat.png
  2. Enter the IP and Port of the running cuOpt microservice and test the connection by clicking TEST. Using a local instance of the cuOpt microservice, the default IP is 0.0.0.0 and the default port is 5000

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_costmat_ipport.png
  3. In the Optimization Problem Setup section select values (or use defaults) for the following, then click SETUP PROBLEM:

    • Fleet Size: The maximum number of vehicles available. Note If a solution can be found using fewer vehicles that solution will be returned.

    • Vehicle Capacity: The number of stops (of demand=1) each vehicle can visit.

    • Number of Locations: The number of non-depot locations that must be visited.

    • Solver Time Limit: The amount of time the cuOpt solver is given to find an optimized solution. Note To maintain solution quality additional time should be given for larger problems

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_costmat_setup.png
  4. In the Run cuOpt section click SOLVE to return optimized routes. A text representation of the routes will be displayed in the UI and results will also be shown in the viewport

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_costmat_solve.png
  5. Click “Open Source Code” to view the reference implementation.

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_costmat_ref.png

1.4.2. Simple Waypoint Graph

  1. Starting from a New Isaac Sim Session (CTRL + N) navigate to the cuOpt menu item now present in the Isaac Sim interface and select Simple Waypoint Graph

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_select_wpgraph.png
  2. Enter the IP and Port of the running cuOpt microservice and test the connection by clicking TEST. Using a local instance of the cuOpt microservice, the default IP is 0.0.0.0 and the default port is 5000

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_wpgraph_ipport.png
  3. In the Optimization Problem Setup section click the LOAD buttons from top to bottom (Waypoint Graph, Orders, Vehicles) to setup the problem:

    • Load Waypoint Graph loads a sample waypoint graph from /extension_data/waypoint_graph.json which exists alongside the source code for this example.

    • Load Orders loads sample order data from /extension_data/order_data.json which exists alongside the source code for this example. Order locations will now appear in green.

    • Load Vehicles loads sample vehicle data from /extension_data/vehicle_data.json which exists alongside the source code for this example. Note Vehicles are assigned to start from Node_0 position but are not shown in the viewport.

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_wpgraph_setup.png
  4. In the Run cuOpt section click SOLVE to return optimized routes. A text representation of the routes will be displayed in the UI and results will also be shown in the viewport

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_wpgraph_solve.png
  5. Click “Open Source Code” to view the reference implementation.

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_wpgraph_ref.png

1.4.3. Intra-warehouse Transport Demo

  1. Starting from a New Isaac Sim Session (CTRL + N) navigate to the cuOpt menu item now present in the Isaac Sim interface and select Intra-warehouse Transport Demo

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_select_intrawaredemo.png
  2. Enter the IP and Port of the running cuOpt microservice and test the connection by clicking TEST. Using a local instance of the cuOpt microservice, the default IP is 0.0.0.0 and the default port is 5000

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_intrawaredemo_ipport.png
  3. In the Optimization Problem Setup section click the LOAD buttons from top to bottom (Sample Warehouse, Waypoint Graph, Orders, Vehicles, Semantic Zone) to setup the problem:

    • Load Sample Warehouse loads a sample warehouse defined by /extension_data/warehouse_building_data.json, conveyors defined by /extension_data/warehouse_conveyors_data.json, and shelves defined by /extension_data/warehouse_shelves_data.json. All json files can be found alongside the source code for this example

    • Load Waypoint Graph loads a sample waypoint graph from /extension_data/waypoint_graph.json which exists alongside the source code for this example.

    • Load Orders loads sample order data from /extension_data/order_data.json which exists alongside the source code for this example. Order locations will now appear in green.

    • Load Vehicles loads sample vehicle data from /extension_data/vehicle_data.json which exists alongside the source code for this example. Note Vehicles are assigned to start from Node_0 position but are not shown in the viewport.

    • (OPTIONAL) Create Semantic Zone creates a semantic zone of user defined size starting at location (0,0,0). If the generated semantic zone is placed over one or more edges in the waypoint graph, edge within that semantic zone will be assigned very high travel cost. cuOpt will attempt to avoid these edges if possible in the optimized solution. Note Each time the Generate button is clicked a new semantic zone is created.

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_intrawaredemo_setup.png
  4. In the Run cuOpt section, if a semantic zone has been created or moved, click UPDATE to capture the current weights. Then click SOLVE to return optimized routes. A text representation of the routes will be displayed in the UI and results will also be shown in the viewport

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_intrawaredemo_solve.png
  5. Click “Open Source Code” to view the reference implementation.

    ../_images/isaac_sim_app_logistics_tutorial_cuopt_intrawaredemo_ref.png

Usage note for Intra-warehouse Transport Demo : This demo is designed to be run in a single Isaac Sim session. Once it has been run, if you leave the demo enabled across multiple sessions, the semantic zone data may carry over, leading to issues when updating weights. To fix any issues that arise, simply disable and re-enable the cuopt examples extension or relaunch Isaac Sim.

1.5. Additional Information

The examples shown here demonstrate only a small subset of cuOpt functionality. For additional features and advanced usage see the cuOpt Documentation and the cuOpt-Resources GitHub Repository