Adds support for conda environment (#42)

* adds creating conda envronment using orbit.sh (-c)
* fixes running of formatter in orbit.sh (-f)
* adds docs building to orbit.sh (-d)
* updates docs with orbit.sh help, vscode instructions and state machine sample

.vscode/launch.json

@@ -14,7 +14,6 @@
                 "EXP_PATH": "${workspaceFolder}/_isaac_sim/apps",
                 "RESOURCE_NAME": "IsaacSim"
             },
-            "python": "${workspaceFolder}/_isaac_sim/kit/python/bin/python3",
             "envFile": "${workspaceFolder}/.vscode/.python.env",
             "preLaunchTask": "setup_python_env"
         },

.vscode/tasks.json

@@ -4,6 +4,7 @@
     "version": "2.0.0",
     "tasks": [
         {
+            // setup python env
             "label": "setup_python_env",
             "type": "shell",
             "linux": {
@@ -11,6 +12,7 @@
             }
         },
         {
+            // run formatter
             "label": "run_formatter",
             "type": "shell",
             "linux": {

.vscode/tools/setup_vscode.py

@@ -13,6 +13,7 @@ when the "setup_python_env.sh" is run as part of the vs-code launch configuratio
 """
 
 import re
+import sys
 import os
 import pathlib
 
@@ -23,16 +24,25 @@ ISAACSIM_DIR = os.path.join(ORBIT_DIR, "_isaac_sim")
 """Path to the isaac-sim directory."""
 
 
-def main():
+def overwrite_python_analysis_extra_paths(orbit_settings: str) -> str:
+    """Overwrite the python.analysis.extraPaths in the orbit settings file with the path names
+    from the isaac-sim settings file.
+
+    Args:
+        orbit_settings (str): The settings string to use as template.
+
+    Returns:
+        The settings string with overwritten python analysis extra paths.
+    """
     # isaac-sim settings
     isaacsim_vscode_filename = os.path.join(ISAACSIM_DIR, ".vscode", "settings.json")
     # make sure the isaac-sim settings file exists
     if not os.path.exists(isaacsim_vscode_filename):
         raise FileNotFoundError(f"Could not find the isaac-sim settings file: {isaacsim_vscode_filename}")
+
     # read the path names from the isaac-sim settings file
     with open(isaacsim_vscode_filename) as f:
         vscode_settings = f.read()
-
     # extract the path names
     # search for the python.analysis.extraPaths section and extract the contents
     settings = re.search(r"\"python.analysis.extraPaths\": \[.*?\]", vscode_settings, flags=re.MULTILINE | re.DOTALL)
@@ -46,6 +56,45 @@ def main():
     # combine them into a single string
     path_names = ",\n\t\t".expandtabs(4).join(path_names)
 
+    # replace the path names in the orbit settings file with the path names from the isaac-sim settings file
+    orbit_settings = re.sub(
+        r"\"python.analysis.extraPaths\": \[.*?\]",
+        '"python.analysis.extraPaths": [\n\t\t'.expandtabs(4) + path_names + "\n\t]".expandtabs(4),
+        orbit_settings,
+        flags=re.DOTALL,
+    )
+    # return the orbit settings string
+    return orbit_settings
+
+
+def overwrite_default_python_interpreter(orbit_settings: str) -> str:
+    """Overwrite the default python interpreter in the orbit settings file with the path to the
+    python interpreter used.
+
+    Args:
+        orbit_settings (str): The settings string to use as template.
+
+    Returns:
+        The settings string with overwritten default python interpreter.
+    """
+    # read executble name
+    python_exe = sys.executable
+    # if python interpreter is from conda, use that. Otherwise, use the template.
+    if "conda" not in python_exe:
+        return orbit_settings
+    # replace the default python interpreter in the orbit settings file with the path to the
+    # python interpreter in the orbit directory
+    orbit_settings = re.sub(
+        r"\"python.defaultInterpreterPath\": \".*?\"",
+        f'"python.defaultInterpreterPath": "{python_exe}"',
+        orbit_settings,
+        flags=re.DOTALL,
+    )
+    # return the orbit settings file
+    return orbit_settings
+
+
+def main():
     # orbit template settings
     orbit_vscode_template_filename = os.path.join(ORBIT_DIR, ".vscode", "tools", "settings.template.json")
     # make sure the orbit template settings file exists
@@ -54,13 +103,13 @@ def main():
     # read the orbit template settings file
     with open(orbit_vscode_template_filename) as f:
         orbit_template_settings = f.read()
-    # replace the path names in the orbit settings file with the path names from the isaac-sim settings file
-    orbit_settings = re.sub(
-        r"\"python.analysis.extraPaths\": \[.*?\]",
-        '"python.analysis.extraPaths": [\n\t\t'.expandtabs(4) + path_names + "\n\t]".expandtabs(4),
-        orbit_template_settings,
-        flags=re.DOTALL,
-    )
+
+    # overwrite the python.analysis.extraPaths in the orbit settings file with the path names
+    orbit_settings = overwrite_python_analysis_extra_paths(orbit_template_settings)
+    # overwrite the default python interpreter in the orbit settings file
+    # NOTE: thisis disabled since we don't need it. The default interpreter should always be the one from isaac-sim
+    # orbit_settings = overwrite_default_python_interpreter(orbit_settings)
+
     # add template notice to the top of the file
     header_message = (
         "// This file is a template and is automatically generated by the setup_vscode.py script.\n"

docs/requirements.txt

 # for building the docs
+importlib-metadata==4.11.3
 Jinja2==3.0.3
 Sphinx==4.5.0
 sphinx-book-theme==0.3.3

docs/source/setup/developer.rst

@@ -29,7 +29,7 @@ To setup the IDE, please follow these instructions:
 1. Open the ``orbit`` directory on Visual Studio Code IDE
 2. Run VSCode
    `Tasks <https://code.visualstudio.com/docs/editor/tasks>`__, by
-   pressing **``Ctrl+Shift+P``**, selecting ``Tasks: Run Task`` and
+   pressing ``Ctrl+Shift+P``, selecting ``Tasks: Run Task`` and
    running the ``setup_python_env`` in the drop down menu.
 
    .. image:: ../_static/vscode_tasks.png
@@ -50,19 +50,27 @@ following links:
 * `Debugging with VSCode <https://docs.omniverse.nvidia.com/app_isaacsim/app_isaacsim/tutorial_advanced_python_debugging.html>`__
 
 
-.. note::
+Configuring the python interpreter
+----------------------------------
 
-   In the provided configuration, we set the default python interpreter to use the
-   python executable provided by Omniverse. This is specified in the
-   ``.vscode/settings.json`` file:
+In the provided configuration, we set the default python interpreter to use the
+python executable provided by Omniverse. This is specified in the
+``.vscode/settings.json`` file:
 
-   .. code-block:: json
+.. code-block:: json
 
    {
       "python.defaultInterpreterPath": "${workspaceFolder}/_isaac_sim/kit/python/bin/python3",
       "python.envFile": "${workspaceFolder}/.vscode/.python.env",
    }
 
+If you want to use a different python interpreter (for instance, from your conda environment),
+you need to change the python interpreter used by selecting and activating the python interpreter
+of your choice in the bottom left corner of VSCode, or opening the command palette (``Ctrl+Shift+P``)
+and selecting ``Python: Select Interpreter``.
+
+For more information on how to set python interpreter for VSCode, please
+refer to the `VSCode documentation <https://code.visualstudio.com/docs/python/environments#_working-with-python-interpreters>`_.
 
 Repository organization
 -----------------------

docs/source/setup/installation.rst

@@ -130,17 +130,14 @@ Organizing the workspace
       # create a symbolic link
       ln -s ${ISAACSIM_PATH} _isaac_sim
 
-Building extensions
-~~~~~~~~~~~~~~~~~~~
-
-We provide a helper executable ```orbit.sh`` <orbit.sh>`__ that provides
+We provide a helper executable `orbit.sh <https://github.com/NVIDIA-Omniverse/Orbit/blob/main/orbit.sh>`_ that provides
 utilities to manage extensions:
 
-.. code:: bash
+.. code:: text
 
    ./orbit.sh --help
 
-   usage: orbit.sh [-h] [-i] [-e] [-f] [-p] [-s] [-v] -- Utility to manage extensions in Isaac Orbit.
+   usage: orbit.sh [-h] [-i] [-e] [-f] [-p] [-s] [-v] [-d] [-c] -- Utility to manage extensions in Orbit.
 
    optional arguments:
       -h, --help           Display the help content.
@@ -150,23 +147,53 @@ utilities to manage extensions:
       -p, --python         Run the python executable (python.sh) provided by Isaac Sim.
       -s, --sim            Run the simulator executable (isaac-sim.sh) provided by Isaac Sim.
       -v, --vscode         Generate the VSCode settings file from template.
+      -d, --docs           Build the documentation from source using sphinx.
+      -c, --conda [NAME]   Create the conda environment for Orbit. Default name is 'orbit'.
 
-The executable automatically fetches the python bundled with Isaac
-Sim, using ``./orbit.sh -p`` command. To not restrict running commands
-only from the top of this repository (where the README.md is located),
-we recommend adding the executable to your environment variables in
-your ``.bashrc`` or ``.zshrc`` file as an alias command. This can be
-achieved running the following on your terminal:
-
+To not restrict running commands only from the top of this repository
+(where the README.md is located), we recommend adding the executable to your environment
+variables in your ``.bashrc`` or ``.zshrc`` file as an alias command. This can be achieved
+running the following on your terminal:
 
 .. code:: bash
 
    # note: execute the command from where the `orbit.sh` executable exists
-   # for bash users
+   # option1: for bash users
    echo -e "alias orbit=$(pwd)/orbit.sh" >> ${HOME}/.bashrc
-   # for zshell users
+   # option2: for zshell users
    echo -e "alias orbit=$(pwd)/orbit.sh" >> ${HOME}/.zshrc
 
+Setting up the environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The executable ``orbit.sh`` automatically fetches the python bundled with Isaac
+Sim, using ``./orbit.sh -p`` command (unless inside a virtual environment). This executable
+behaves like a python executable, and can be used to run any python script or
+module with the simulator. For more information, please refer to the
+`documentation <https://docs.omniverse.nvidia.com/app_isaacsim/app_isaacsim/install_python.html>`__.
+
+Although using a virtual environment is optional, we recommend using ``conda``. To install
+``conda``, please follow the instructions `here <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html>`__.
+In case you want to use ``conda`` to create a virtual environment, you can
+use the following command:
+
+.. code:: bash
+
+   ./orbit.sh --conda  # or `./orbit.sh -c`
+
+
+.. note::
+
+      If you are using ``conda`` to create a virtual environment, make sure to
+      activate the environment before running any scripts. For example:
+
+      .. code:: bash
+
+         conda activate orbit
+
+
+Building extensions
+~~~~~~~~~~~~~~~~~~~
 
 To build all the extensions, run the following commands:
 

docs/source/setup/sample.rst

@@ -73,6 +73,20 @@ useful to ensure that the environments are configured correctly.
 
       ./orbit.sh -p source/standalone/environments/random_agent.py --task Isaac-Cartpole-v0 --num_envs 32
 
+
+State machine
+~~~~~~~~~~~~~
+
+We include examples on hand-crafted state machines for the environments. These
+help in understanding the environment and how to use the provided interfaces.
+The state machines are written in `warp <https://github.com/NVIDIA/warp>`__ which
+allows efficient execution for large number of environments using CUDA kernels.
+
+.. code:: bash
+
+   ./orbit.sh -p source/standalone/environments/state_machine/play_lift.py --num_envs 32
+
+
 Teleoperation
 ~~~~~~~~~~~~~
 

orbit.sh

@@ -18,7 +18,7 @@ export ORBIT_PATH="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd
 #==
 
 # extract the python from isaacsim
-extract_isaacsim_python() {
+extract_python_exe() {
     # Check if IsaacSim directory manually specified
     # Note: for manually build isaacsim, this: _build/linux-x86_64/release
     if [ ! -z ${ISAACSIM_PATH} ];
@@ -29,8 +29,14 @@ extract_isaacsim_python() {
         # Use TeamCity build
         build_path=${ORBIT_PATH}/_isaac_sim
     fi
-    # python executable to use
+    # check if using conda
+    if ! [[ -z "${CONDA_PREFIX}" ]]; then
+        # use conda python
+        local python_exe=${CONDA_PREFIX}/bin/python
+    else
+        # use python from kit
         local python_exe=${build_path}/python.sh
+    fi
     # check if there is a python path available
     if [ ! -f "${python_exe}" ]; then
         echo "[ERROR] No python executable found at path: ${build_path}" >&2
@@ -66,7 +72,7 @@ extract_isaacsim_exe() {
 # check if input directory is a python extension and install the module
 install_orbit_extension() {
     # retrieve the python executable
-    python_exe=$(extract_isaacsim_python)
+    python_exe=$(extract_python_exe)
     # if the directory contains setup.py then install the python module
     if [ -f "$1/setup.py" ];
     then
@@ -75,18 +81,98 @@ install_orbit_extension() {
     fi
 }
 
+# setup anaconda environment for orbit
+setup_conda_env() {
+    # get environment name from input
+    local env_name=$1
+    # check conda is installed
+    if ! command -v conda &> /dev/null
+    then
+        echo "[ERROR] Conda could not be found. Please install conda and try again."
+        exit 1
+    fi
+    # Check if IsaacSim directory manually specified
+    # Note: for manually build isaacsim, this: _build/linux-x86_64/release
+    if [ ! -z ${ISAACSIM_PATH} ];
+    then
+        # Use local build
+        build_path=${ISAACSIM_PATH}
+    else
+        # Use TeamCity build
+        build_path=${ORBIT_PATH}/_isaac_sim
+    fi
+    # check if the environment exists
+    if { conda env list | grep ${env_name}; } >/dev/null 2>&1; then
+        echo -e "[INFO] Conda environment named '${env_name}' already exists."
+    else
+        echo -e "[INFO] Creating conda environment named '${env_name}'..."
+        conda env create --name ${env_name} -f ${build_path}/environment.yml
+    fi
+    # cache current paths for later
+    cache_pythonpath=$PYTHONPATH
+    cache_ld_library_path=$LD_LIBRARY_PATH
+    # clear any existing files
+    rm -f ${CONDA_PREFIX}/etc/conda/activate.d/setenv.sh
+    rm -f ${CONDA_PREFIX}/etc/conda/deactivate.d/unsetenv.sh
+    # activate the environment
+    source $(conda info --base)/etc/profile.d/conda.sh
+    conda activate ${env_name}
+    # setup directories to load isaac-sim variables
+    mkdir -p ${CONDA_PREFIX}/etc/conda/activate.d
+    mkdir -p ${CONDA_PREFIX}/etc/conda/deactivate.d
+    # add variables to environment during activation
+    local isaacsim_setup_conda_env_script=${ORBIT_PATH}/_isaac_sim/setup_conda_env.sh
+    printf '%s\n' '#!/bin/bash' '' \
+        '# for isaac-sim' \
+        'source '${isaacsim_setup_conda_env_script}'' \
+        '' \
+        '# for orbit' \
+        'alias orbit='${ORBIT_PATH}'/orbit.sh' \
+        '' > ${CONDA_PREFIX}/etc/conda/activate.d/setenv.sh
+    # reactivate the environment to load the variables
+    # needed because deactivate complains about orbit alias since it otherwise doens't exist
+    conda activate ${env_name}
+    # remove variables from environment during deactivation
+    printf '%s\n' '#!/bin/bash' '' \
+        '# for orbit' \
+        'unalias orbit &>/dev/null' \
+        '' \
+        '# for isaac-sim' \
+        'unset CARB_APP_PATH' \
+        'unset EXP_PATH' \
+        'unset ISAAC_PATH' \
+        '' \
+        '# restore paths' \
+        'export PYTHONPATH='${cache_pythonpath}'' \
+        'export LD_LIBRARY_PATH='${cache_ld_library_path}'' \
+        '' > ${CONDA_PREFIX}/etc/conda/deactivate.d/unsetenv.sh
+    # install some extra dependencies
+    conda install -c conda-forge -y importlib_metadata &> /dev/null
+    # deactivate the environment
+    conda deactivate
+    # add information to the user about alias
+    echo -e "[INFO] Added 'orbit' alias to conda environment for 'orbit.sh' script."
+    echo -e "[INFO] Created conda environment named '${env_name}'.\n"
+    echo -e "\t\t1. To activate the enviornment, run:                conda activate ${env_name}"
+    echo -e "\t\t2. To install orbit extensions, run:                orbit -i"
+    echo -e "\t\t3. To install learning-related dependencies, run:   orbit -e"
+    echo -e "\t\t4. To perform formatting, run:                      orbit -f"
+    echo -e "\t\t5. To deactivate the environment, run:              conda deactivate"
+    echo -e "\n"
+}
+
 # update the vscode settings from template and isaac sim settings
 update_vscode_settings() {
     echo "[INFO] Setting up vscode settings..."
     # retrieve the python executable
-    python_exe=$(extract_isaacsim_python)
+    python_exe=$(extract_python_exe)
     # run the setup script
     ${python_exe} ${ORBIT_PATH}/.vscode/tools/setup_vscode.py
 }
 
 # print the usage description
 print_help () {
-    echo -e "\nusage: $(basename "$0") [-h] [-i] [-e] [-f] [-p] [-s] [-v] -- Utility to manage extensions in Isaac Orbit."
+    echo -e "\nusage: $(basename "$0") [-h] [-i] [-e] [-f] [-p] [-s] [-v] [-d] [-c] -- Utility to manage extensions in Orbit."
     echo -e "\noptional arguments:"
     echo -e "\t-h, --help           Display the help content."
     echo -e "\t-i, --install        Install the extensions inside Isaac Orbit."
@@ -95,6 +181,8 @@ print_help () {
     echo -e "\t-p, --python         Run the python executable (python.sh) provided by Isaac Sim."
     echo -e "\t-s, --sim            Run the simulator executable (isaac-sim.sh) provided by Isaac Sim."
     echo -e "\t-v, --vscode         Generate the VSCode settings file from template."
+    echo -e "\t-d, --docs           Build the documentation from source using sphinx."
+    echo -e "\t-c, --conda [NAME]   Create the conda environment for Orbit. Default name is 'orbit'."
     echo -e "\n" >&2
 }
 
@@ -119,7 +207,7 @@ while [[ $# -gt 0 ]]; do
             echo "[INFO] Installing extensions inside orbit repository..."
             # recursively look into directories and install them
             # this does not check dependencies between extensions
-            export -f extract_isaacsim_python
+            export -f extract_python_exe
             export -f install_orbit_extension
             # source directory
             find -L "${ORBIT_PATH}/source/extensions" -mindepth 1 -maxdepth 1 -type d -exec bash -c 'install_orbit_extension "{}"' \;
@@ -132,30 +220,55 @@ while [[ $# -gt 0 ]]; do
         -e|--extra)
             # install the python packages for supported reinforcement learning frameworks
             echo "[INFO] Installing extra requirements such as learning frameworks..."
-            python_exe=$(extract_isaacsim_python)
+            python_exe=$(extract_python_exe)
             # install the rl-frameworks specified
             ${python_exe} -m pip install -e ${ORBIT_PATH}/source/extensions/omni.isaac.orbit_envs[all]
             shift # past argument
             ;;
+        -c|--conda)
+            # use default name if not provided
+            if [ -z "$2" ]; then
+                echo "[INFO] Using default conda environment name: orbit"
+                conda_env_name="orbit"
+            else
+                echo "[INFO] Using conda environment name: $2"
+                conda_env_name=$2
+                shift # past argument
+            fi
+            # setup the conda environment for orbit
+            setup_conda_env ${conda_env_name}
+            shift # past argument
+            ;;
         -f|--format)
+            # reset the python path to avoid conflicts with pre-commit
+            # this is needed because the pre-commit hooks are installed in a separate virtual environment
+            # and it uses the system python to run the hooks
+            if [ -n "${CONDA_DEFAULT_ENV}" ]; then
+                cache_pythonpath=${PYTHONPATH}
+                export PYTHONPATH=""
+            fi
             # run the formatter over the repository
             # check if pre-commit is installed
             if ! command -v pre-commit &>/dev/null; then
                 echo "[INFO] Installing pre-commit..."
                 pip install pre-commit
             fi
-            echo "[INFO] Formatting the repository..."
             # always execute inside the Orbit directory
-            cd "${ORBIT_PATH}"
+            echo "[INFO] Formatting the repository..."
+            cd ${ORBIT_PATH}
             pre-commit run --all-files
-            cd -
+            cd - > /dev/null
+            # set the python path back to the original value
+            if [ -n "${CONDA_DEFAULT_ENV}" ]; then
+                export PYTHONPATH=${cache_pythonpath}
+            fi
             shift # past argument
             # exit neatly
             break
             ;;
         -p|--python)
             # run the python provided by isaacsim
-            python_exe=$(extract_isaacsim_python)
+            python_exe=$(extract_python_exe)
             echo "[INFO] Using python from: ${python_exe}"
             shift # past argument
             ${python_exe} $@
@@ -178,6 +291,25 @@ while [[ $# -gt 0 ]]; do
             # exit neatly
             break
             ;;
+        -d|--docs)
+            # build the documentation
+            echo "[INFO] Building documentation..."
+            # retrieve the python executable
+            python_exe=$(extract_python_exe)
+            # install pip packages
+            cd ${ORBIT_PATH}/docs
+            ${python_exe} -m pip install -r requirements.txt > /dev/null
+            # build the documentation
+            ${python_exe} -m sphinx -b html -d _build/doctrees . _build/html > /dev/null
+            # open the documentation
+            echo -e "[INFO] To open documentation on default browser, run:"
+            echo -e "\n\t\txdg-open $(pwd)/_build/html/index.html\n"
+            # exit neatly
+            cd - > /dev/null
+            shift # past argument
+            # exit neatly
+            break
+            ;;
         -h|--help)
             print_help
             exit 1