Client Installation

The AODT client provides C++ and Python libraries for configuring and running simulations over gRPC. It supports remote data transfer over gRPC and optional CUDA IPC for fast local GPU transfers when the client and worker are colocated.

Transport mode

Transport mode defines how the client and worker exchange simulation data.

In Interactive Mode, channel impulse responses (CIRs) can be read directly from GPU memory through the client APIs. This requires the client and worker to run on the same machine with a shared GPU. AODT refers to this configuration as LOCAL_IPC.

In non-colocated deployments, CIRs are copied from GPU memory to host memory on the worker, then transferred to the client over gRPC. This configuration is referred to as REMOTE.

Platform support

CUDA is detected automatically at configure time. When CUDA is unavailable, the client still works over gRPC in REMOTE mode.

Prerequisites

Complete the Prerequisites for your deployment type before continuing:

• Colocated — Client and worker run on the same machine. Install GPU drivers, Docker, and the NVIDIA Container Toolkit as described on the prerequisites page.
• Non-colocated — Client and worker run on different machines. The client does not require a GPU. Install the OS-specific build dependencies listed in the platform sections below.

Clone the AODT repository

Clone AODT 1.5.0 from GitHub:

$
git clone https://github.com/NVIDIA/aerial-omniverse-digital-twin.git aodt_1.5.0

This creates an aodt_1.5.0 directory at the clone path. All commands in this documentation use aodt_1.5.0 as the package root, with component paths underneath it:

aodt_1.5.0/
├── client/    # Client library and examples
├── worker/    # Worker stack and Docker Compose files
└── viewer/    # Web viewer application

Note the full path to aodt_1.5.0 on your system — subsequent commands assume you are working from that package root or its subdirectories.

Choose an installation path

Use a source build if any of the following apply:

• You are installing the client natively on macOS or Windows
• Docker is not available on your system
• You are integrating AODT into your own application
• You need a development environment for modifying client code

If you need a source build, skip to Source build on Linux or the section for your platform.

Quickstart via container

On Linux or WSL2, the development container is the fastest way to build and run the client when Docker is available. The image includes all build and runtime dependencies.

$
cd aodt_1.5.0
$
$
# Open an interactive shell inside the container
$
./container/run.sh
$
$
# Or build the client directly
$
./container/run.sh cmake -B client/build -DCMAKE_BUILD_TYPE=Release client/
$
./container/run.sh cmake --build client/build -j$(nproc)

No additional client setup is required after a successful container build.

Verify the container installation

The client cannot be exercised until the worker is running. After completing Worker Installation, follow Verify Installation — colocated container test.

Source build on Linux

Use this path to install the client directly on your system. It is the recommended approach for development workflows.

Install dependencies

From the client/ directory:

$
sudo apt-get update
$
sudo apt-get install -y cmake protobuf-compiler-grpc libgrpc++-dev pkg-config python3-dev python3-venv
$
python3 -m venv .venv
$
source .venv/bin/activate
$
pip install pybind11 pyyaml omegaconf pytest numpy

Optional: CUDA toolkit

CUDA is optional. When present, it enables CUDA IPC for colocated LOCAL_IPC transport. Without CUDA, the client remains fully usable over gRPC.

To enable CUDA for colocated deployments:

$
# Install NVIDIA driver (skip if already installed — check with nvidia-smi)
$
# Use apt-cache search nvidia-driver to list available versions.
$
# Install using the driver series number (e.g. nvidia-driver-535).
$
# Do NOT supply a patch-level version number like 590.48.01.
$
sudo apt-get install -y nvidia-driver-<driver-series>
$
sudo reboot

$
# Install CUDA Toolkit (example for Ubuntu 22.04)
$
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
$
sudo dpkg -i cuda-keyring_1.1-1_all.deb
$
sudo apt-get update
$
sudo apt-get install -y cuda-toolkit

Verify with nvidia-smi and nvcc --version. See the CUDA compatibility guide for driver and toolkit version requirements.

Build

From the client/ directory:

$
source .venv/bin/activate
$
cmake -B build -DCMAKE_BUILD_TYPE=Release -DPython3_EXECUTABLE=$(which python3) .
$
cmake --build build -j$(nproc)

The configure step prints a summary of detected features:

=== Digital Twin Client Build Configuration ===
  CUDA:       YES
  Compiler:   GNU
  Platform:   Linux
===============================================

Use the Python client

You can run the Python bindings in two ways:

Option 1 — Without installing (development)

$
source .venv/bin/activate
$
export PYTHONPATH=build/:build/config/
$
python3 examples/example_client.py

Option 2 — System-wide install

$
sudo cmake --install build

After installation, import dt_client and import _config work from any directory without setting PYTHONPATH.

Use the C++ client

From the client/ directory:

$
./build/dt_client_example --server localhost:50051

Replace localhost:50051 with the worker address for non-colocated deployments.

Verify the installation

The worker must be running before you test the client. Follow Verify Installation — colocated source build test.

Source build on WSL2

WSL2 follows the same build steps as Linux.

Install dependencies

From the client/ directory inside WSL2:

$
sudo apt-get update
$
sudo apt-get install -y cmake protobuf-compiler-grpc libgrpc++-dev pkg-config python3-dev python3-venv
$
python3 -m venv .venv
$
source .venv/bin/activate
$
pip install pybind11 pyyaml omegaconf pytest numpy

No WSL2-specific transport configuration is required beyond network reachability to the worker address.

Build and run

$
source .venv/bin/activate
$
cmake -B build -DCMAKE_BUILD_TYPE=Release -DPython3_EXECUTABLE=$(which python3) .
$
cmake --build build -j$(nproc)
$
$
export PYTHONPATH=build/:build/config/
$
python3 examples/example_client.py

Source build on macOS

Install dependencies

$
brew install grpc protobuf cmake pkg-config
$
python3 -m venv .venv
$
source .venv/bin/activate
$
pip3 install pybind11 pyyaml omegaconf pytest numpy

Build and run

From the client/ directory:

$
source .venv/bin/activate
$
cmake -B build -DCMAKE_BUILD_TYPE=Release -DPython3_EXECUTABLE=$(which python3) .
$
cmake --build build -j$(nproc)
$
$
export PYTHONPATH=build/:build/config/
$
python3 examples/example_client.py

macOS uses gRPC for request, control, and remote memory transfer. CUDA IPC and LOCAL_IPC mode are not supported.

Source build on Windows (MSVC)

Install dependencies

• Visual Studio 2022 with the “Desktop development with C++” workload, or Visual C++ Build Tools from visualstudio.microsoft.com/visual-cpp-build-tools
• CMake from cmake.org/download — select “Add CMake to system PATH” during installation
• Git from git-scm.com/download/win

Install vcpkg and C++ dependencies:

1
git clone https://github.com/microsoft/vcpkg.git
2
cd vcpkg
3
.\bootstrap-vcpkg.bat
4
.\vcpkg install grpc protobuf yaml-cpp pybind11

Set up Python. vcpkg installs its own Python — the built modules are only compatible with that Python:

1
<vcpkg-root>\installed\x64-windows\tools\python3\python.exe -m ensurepip --upgrade
2
<vcpkg-root>\installed\x64-windows\tools\python3\python.exe -m pip install pyyaml omegaconf pytest numpy

Add vcpkg’s Python to your PATH:

1
$env:PATH = "<vcpkg-root>\installed\x64-windows\tools\python3;<vcpkg-root>\installed\x64-windows\tools\python3\Scripts;$env:PATH"

Build and run

From the client/ directory:

1
cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>\scripts\buildsystems\vcpkg.cmake -DCMAKE_PREFIX_PATH=<vcpkg-root>\installed\x64-windows .
2
cmake --build build --config Release

1
$env:PATH = "..\vcpkg\installed\x64-windows\tools\python3;$env:PATH"
2
$env:PYTHONPATH = "build\Release;build\config\Release"
3
python examples\example_client.py

Windows uses gRPC for request, control, and remote memory transfer. CUDA IPC and LOCAL_IPC mode are not supported.

Next steps

After the client is installed and verified:

1. Complete Worker Installation if you have not already started the worker.
2. Install the Viewer to visualize simulation results.
3. Follow the Quickstart guide to run your first simulation.