Quickstart Guide

Step 1: NGC Account Setup

An NGC org (organization) is a dedicated virtual instance used to enable and manage NVIDIA cloud services. Upon your approval to the cuOpt Cloud Service EA program, an NVIDIA representative will add you to the NGC org. You should receive a welcome email that instructs you to continue the activation and sign-in process.

Please contact NVIDIA Support for additional details.

Important

Please retrieve the Welcome to NGC email which you received from: noreply-ngc@nvidia.com.

To get started with the cuOpt service, first you will need to have an NGC account if you do not already have an account.

  1. Sign up for a free NGC org through the NGC sign-in portal and create a new NVIDIA account.

  2. Click on the link within the NGC Welcome email to accept the invitation to the org.

    Note

    Please refer to the NGC documentation for further details.

    The following cuOpt Service landing page will be displayed.

    _images/image4.png

Step 2: Setup the Python Environment

Prior to setting up the Python thin client, we’ll create a Python virtual environment to use for the installation. This will allow us to install any Python scripts or libraries specifically for this service.

Note

Supported OSes include Linux, WSL, and macOS. We recommend you use bash shell on macOS.

  1. First, ensure that Python 3.9+ is installed on the system. You can check the version of Python that’s installed using the command below.

    python3 --version
    
  2. Install the Python virtual environment package.

    • For installation on macOS, run:

      pip3 install virtualenv
      
    • For installation on Ubuntu, run:

      apt install python3.9-venv (or the specific package for your version of Python)
      
  3. Next, make sure you’re in a proper working directory, such as your home directory, and create a virtual environment within that directory.

    1cd ~
    2python3 -m venv cuopt-service-env
    
  4. Activate the new environment by running the following command.

    source cuopt-service-env/bin/activate
    
  5. Proceed to the next step to download and set up the Python thin client into this environment.

Step 3: Download Python Thin Client

Important

You must complete this download step. After completion of this step, NVIDIA will produce your credentials as soon as possible. Please wait for a welcome email from NVIDIA granting access to a service account and making you the administrator of an Oauth 2.0 client, then proceed with Step 4: Obtain Credentials for cuOpt Managed Service.

The cuOpt Service Python Thin Client is a Python interface to enable access to the NVIDIA-managed service. This lightweight client connects to the cuOpt server via a standard socket connection. It does not hold any data but simply establishes a socket connection to the server and performs all operations through it. It sends new and updated data to the cuOpt server and receives the server response (either the optimized routes or an error message) in return.

  1. Login into NVIDIA NGC.

  2. Click on the Download Python Thin Client link on the cuOpt landing page in NGC, as shown in the highlight below. This will download a zip file called cuopt_managed_service.zip.

    images/landing.png
  3. Unzip the downloaded file into the current working directory, using the command below.

    unzip cuopt_managed_service.zip -d .
    
  4. Navigate to the managed service directory that was just unzipped.

    cd cuopt_managed_service
    
  5. Make sure that your Python virtual environment that you created in the previous step is active, then execute the following command:

    pip install .
    

    This will install everything included in the managed service directory into your Python virtual environment. Now cuopt_cli can be run from that environment, and the cuopt_thin_client package can now be imported in Python.

  6. Wait to receive an email from NVIDIA granting access to a service account and making you the administrator of an Oauth 2.0 client.

Note

The cuOpt Managed Service Client handles requests to the cuOpt service through NVIDIA Cloud Functions (NVCF). Route Optimization problem data files are sent to the server using .json. Please refer to the upcoming API section for more details.

Step 4: Obtain Credentials for cuOpt Managed Service

NVIDIA Identity Federation API Key (API Key)

Note

There are two types of API Keys, Run Keys and Service Keys. Service keys may only be created by Org Owners and are designed for use in automation. Most users will create a Run Key.

  1. An API Key is used to authenticate with the cuOpt managed service

  2. Log into the NGC org that has been created for you

  3. Select the CLOUD FUNCTION tab on the left side panel and choose Functions

  4. Select the shared functions tile to check functions available

  5. Note down the function id with name cuopt

    _images/cuopt_landing_page.png
  6. For Org Owners only

    1. Select ORGANIZATION -> Service Keys

      _images/service_keys.png
    2. Select Create Service Key on top right corner

    3. Fill the details and choose the expiration as per your need as shown below and generate key.

    4. Need to select a particular function id rather than all functions options.

    5. This function id can be found in CLOUD FUNCTION -> Functions -> Shared Functions

    6. The name of the of the function would be cuopt

      _images/service_key_creation.png
    7. Save this key since you will not be able to retrieve the same one, but you can rotate the key to get new one in the same page.

  7. For all org user

    1. Select CLOUD FUNCTION tab on the left side panel and choose Functions

    2. Select “Generate Run Key”

      _images/cloud_functions.png
    3. Save this key and share it wisely since these keys can’t be deleted or disabled like service key

    4. This will be valid for a month from the date of creation

Step 5: Installing thin client using pip index

  1. Whenever thin clients need to be updated or installed, you can directly install it using Nvidia pip index

    pip install --upgrade --extra-index-url https://pypi.nvidia.com cuopt-thin-client
    

Step 6: Adding additional users to your ngc Org

  1. Navigate to ORGANIZATION -> Users, you would observe option to Invite User on the right corner

    _images/users.png
  2. Select Invite User and fill the details as shown below,

    1. Fill the name and email-id

    2. Choose Organization under Roles

    3. Select following roles
      • CuOpt Service -> CuOpt User

      • Cloud Functions -> Viewer

      • it is up to user whether they want to provide any admin authorities using Organization

    4. Choose Add Role on right side to add these settings

      _images/add_role.png
  3. Make sure only following set of roles are set as shown below, delete Registry Read role.

    _images/invite_user.png
  4. Select Invite User on top right corner to invite the user.

  5. For more information on adding users visit NGC page