Build Guide¶

Although vortex supports CMake, its many dependencies make it somewhat cumbersome to build. This guide attempts to ease the difficulty in building vortex.

Warning

If you only plan to use vortex via Python (and do not need to run a C++ debugger), use of a binary wheel is strongly recommended over setting up your own build.

Note

See the Step-by-Step Guide for step-by-step instructions for building with vcpkg and Visual Studio 2019.

Build Options¶

vortex’s build options are controlled exclusively through CMake flags. There are flags that tailor the build to available dependencies, that enable vortex-specific features, and support debugging.

Dependency Control¶

WITH_ALAZAR (default: ON): Provide support for AlazarTech digitizers.
WITH_ALAZAR_GPU (default: OFF): Provide support for AlazarTech digitizers using their proprietary CUDA support. This option is not recommended as vortex provides its own CUDA support at a comparable performance level, at least in preliminary testing.
WITH_CUDA (default: ON): Use CUDA for nVIDIA GPU-accelerated OCT processing. This option is strongly recommended.
WITH_DAQMX (default: ON): Provide support for signal I/O using National Instruments DAQmx-compatible modules.
WITH_FFTW (default: OFF): Use FFTW for fast Fourier transforms, primarily in the CPU OCT processor.
WITH_HDF5 (default: ON): Provide support for the MATLAB v7.3 file format.
WITH_PYTHON (default: ON): Build Python bindings.
WITH_REFLEXXES (default: ON): Enable time-optimal scan trajectory generation with the Reflexxes library. If this option is disabled, scan generation is not available. This option is strongly recommended.

Feature Control¶

ENABLE_DEMOS (default: OFF): Build C++ demo applications.
ENABLE_BUILD_PYTHON_WHEEL (default ON): On Python-enabled builds, generate a binary wheel that installs vortex. The wheel will be deposited in the build output folder alongside the vortex libary.
ENABLE_INSTALL_PYTHON_WHEEL (default ON): If the Python wheel is built as above, automatically install the wheel into the current Python environment.
ENABLE_DEPENDENCY_PACKAGING (default ON): If the Python wheel is built as above, binary dependencies of vortex are analyzed after the build and packaged alongside vortex. This helps reduce the burden of installing vortex in simple deployment scenarios (i.e., those that do not provide binary dependency management).
ENABLE_OUT_OF_TREE_PACKAGING (default OFF): By default, only binary dependencies within the vortex root directory are packaged if dependency packaging in enabled. This helps avoid deploying closed-source libraries in the wheel. It is thus recommended to clone vcpkg into the vortex root folder so that the dependencies that it provides are automatically packaged. Turn on this option to include all non-system binary dependencies in the wheel.

Debugging Support¶

ENABLE_CUDA_KERNEL_SERIALIZATION (default OFF): Synchronize the GPU with cudaDeviceSynchronize after every CUDA kernel launch for debugging purposes. This option may adversely affect performance and is not recommended for regular use.
ENABLE_EXCEPTION_GUARDS (default ON): Surround all callback invocations in vortex with try-catch blocks to handle exceptions. Turn off this option to propagate exceptions in callbacks to the debugger for debugging purposes. This option is strongly recommended for regular use.

Warning

The vortex Python bindings will emit warnings if any of these options are left in their non-recommended state.

Dependencies¶

Open Source via vcpkg¶

All of vortex’s open source dependencies are available in vcpkg with use of the vcpkg-izattlab ports overlay.

Component	Packages	CMake Option
core	`fmt spdlog xtensor[tbb,xsimd]`
scan generation	`reflexxes`	`WITH_REFLEXXES`
CUDA	`cuda cub`	`WITH_CUDA`
CPU OCT processor	`fftw3[avx2]`	`WITH_FFTW`
Python bindings	`xtensor-python pybind11`	`WITH_PYTHON`
MATLAB v7.3 file support	`hdf5[cpp]`	`WITH_HDF5`
C++ demos	`bfgroup-lyra`	`ENABLE_DEMOS`

Open Source via conda¶

Almost all of vortex’s open source dependencies are available in conda. The only ones missing are reflexxes and bfgroup-lyra. Note that the conda-provided version of TTB may require manual patching of the feature detection header for compatibility with clang-cl.

Component	Packages	CMake Option
core	`fmt spdlog xtensor tbb-devel`
scan generation	`reflexxes`	`WITH_REFLEXXES`
CUDA	`cudatoolkit cub`	`WITH_CUDA`
CPU OCT processor	`fftw3`	`WITH_FFTW`
Python bindings	`xtensor-python pybind11`	`WITH_PYTHON`
MATLAB v7.3 file support	`hdf5`	`WITH_HDF5`

Closed Source¶

The closed source dependencies are provided by installers from the developer. vortex will detect standard installation locations or you can provide a search path hint.

Component	Installer	CMake Option	Search Path Hint
Alazar card support	ATS-SDK	`WITH_ALAZAR`	`AlazarTech_DIR`
Alazar CUDA library	ATS-GPU-BASE	`WITH_ALAZAR_GPU`	`AlazarTech_DIR`
DAQmx I/O	NI DAQmx	`WITH_DAQMX`	`NIDAQmx_DIR`

If ATS-GPU-BASE is used, vortex will let Alazar manage data movement to the GPU. If ATS-SDK is used, vortex will handle data movement itself.

Note

The performance between using ATS-SDK and ATS-GPU-BASE is comparable in preliminary testing.

Build Systems¶

vortex is compatible with any build system that CMake supports. Examples for common build systems are provided below. The continuous integration scripts are based on the vcpkg example below.

Visual Studio 2019¶

Visual Studio 2019 can directly build vortex using the included CMakePresets.json or the CMakeSettings.json file below placed alongside the top-level CMakeLists.txt file. Make sure to install your dependencies with vcpkg or conda first. If you used vcpkg for dependencies, be sure to change ${vcpkg_root} to the correct path in the cmakeToolchain entry.

{
    "environments": [
    {
      "CXXFLAGS" : "-m64 -fdiagnostics-absolute-paths -Wno-unused-command-line-argument -Wno-deprecated-volatile -Wno-deprecated-declarations /DTBB_SUPPRESS_DEPRECATED_MESSAGES /Zi",
      "CUDAFLAGS" : "-Xcudafe --diag_suppress=base_class_has_different_dll_interface --debug",
      "LDFLAGS": "/debug"
    }
  ],
  "configurations": [
    {
      "name": "x64-Debug clang",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "clang_cl_x64_x64" ],
      "buildRoot": "${projectDir}/build-clang-x64/Debug",
      "installRoot": "${projectDir}/build-clang-x64/install",
      "buildCommandArgs": "-v",
      "variables": [
        {
          "name": "Python3_EXECUTABLE",
          "value": "${python_path}",
          "type": "FILEPATH"
        }
      ],
      "cmakeToolchain": "${vcpkg_root}/scripts/buildsystems/vcpkg.cmake"
    },
    {
      "name": "x64-Release clang",
      "generator": "Ninja",
      "configurationType": "Release",
      "buildRoot": "${projectDir}/build-clang-x64/Release",
      "installRoot": "${projectDir}/build-clang-x64/install",
      "buildCommandArgs": "-v",
      "inheritEnvironments": [ "clang_cl_x64_x64" ],
      "variables": [
        {
          "name": "Python3_EXECUTABLE",
          "value": "${python_path}",
          "type": "FILEPATH"
        }
      ],
      "cmakeToolchain": "${vcpkg_root}/scripts/buildsystems/vcpkg.cmake"
    },
  ]
}

CMake and vcpkg¶

This example illustrates how to build and install vortex from a PowerShell prompt using clang-cl. It is assumed that Python has already been installed and is available on the path. These commands may be run within a Python virtual environment. The build is configured to include debug symbols.

# clone vortex and vcpkg
git clone git@gitlab.oit.duke.edu:izatt-lab/oct/vortex.git
git clone https://github.com/microsoft/vcpkg.git vortex/.vcpkg
git clone git@gitlab.oit.duke.edu:izatt-lab/vcpkg-izattlab.git vortex/.vcpkg-izattlab

# build vcpkg dependencies
.\vortex\.vcpkg\bootstrap-vcpkg.bat -disableMetrics
.\vortex\.vcpkg\vcpkg.exe --triplet=x64-windows --overlay-ports=vortex\.vcpkg-izattlab install fmt spdlog xtensor[tbb,xsimd] reflexxes cuda cub xtensor-python pybind11 hdf5[cpp]

# install Python dependencies
$Python = (Get-Command python).Path
& $Python -m pip install setuptools wheel

# configure build flags
$Env:CXXFLAGS="-m64 -fdiagnostics-absolute-paths -Wno-unused-command-line-argument -Wno-deprecated-volatile -Wno-deprecated-declarations -Wunknown-pragmas /DTBB_SUPPRESS_DEPRECATED_MESSAGES /Zi"
$Env:CUDAFLAGS="-Xcudafe --diag_suppress=base_class_has_different_dll_interface"
$Env:LDFLAGS="/debug"

# build and install vortex
cmake -S vortex -B vortex/build -T ClangCL `
  -DPython3_EXECUTABLE:FILEPATH="$Python" `
  -DCMAKE_TOOLCHAIN_FILE:FILEPATH="$PWD/vortex/.vcpkg/scripts/buildsystems/vcpkg.cmake" `
  -DENABLE_BUILD_PYTHON_WHEEL:BOOL=ON `
  -DENABLE_INSTALL_PYTHON_WHEEL:BOOL=ON `
  -DENABLE_OUT_OF_TREE_PACKAGING:BOOL=OFF
cmake --build vortex/build --config Release

CMake and conda¶

This example illustrates how to build and install vortex from a conda PowerShell prompt using clang-cl. The build is configured to include debug symbols.

# create a new environment
conda create --name vortex
conda activate vortex

# install dependencies
conda install -c conda-forge xtensor spdlog fmt xsimd cudatoolkit cub xtensor-python tbb-devel hdf5 pybind11
conda install setuptools wheel

# configure build flags
$Env:CXXFLAGS="-m64 -fdiagnostics-absolute-paths -Wno-unused-command-line-argument -Wno-deprecated-volatile-Wno-deprecated-declarations -Wunknown-pragmas /DTBB_SUPPRESS_DEPRECATED_MESSAGES /Zi"
$Env:CUDAFLAGS="-Xcudafe --diag_suppress=base_class_has_different_dll_interface"
$Env:LDFLAGS="/debug"

# build and install reflexxes
git clone git@gitlab.oit.duke.edu:izatt-lab/robotics/reflexxes.git src-reflexxes
cmake -S src-reflexxes -B build-reflexxes -T ClangCL -DCMAKE_INSTALL_PREFIX:PATH=install
cmake --build build-reflexxes --config Release
cmake --install build-reflexxes

# build and install vortex
git clone git@gitlab.oit.duke.edu:izatt-lab/oct/vortex.git src-vortex
cmake -S src-vortex -B build-vortex -T ClangCL `
  -DPython3_EXECUTABLE:FILEPATH="$Env:PYTHON" `
  -DReflexxes_DIR:PATH="$PWD\install\lib\cmake\Reflexxes" `
  -DCMAKE_PREFIX_PATH:PATH="$Env:CONDA_PREFIX\Library\cmake" `
  -DENABLE_BUILD_PYTHON_WHEEL:BOOL=ON `
  -DENABLE_INSTALL_PYTHON_WHEEL:BOOL=ON `
  -DENABLE_OUT_OF_TREE_PACKAGING:BOOL=OFF
cmake --build build-vortex --config Release

Step-by-Step Guide¶

1. Clone vortex¶

git clone https://gitlab.oit.duke.edu/izatt-lab/oct/vortex.git

2. Clone vcpkg and vcpkg-izattlab¶

git clone https://github.com/microsoft/vcpkg.git vortex/.vcpkg
git clone https://gitlab.oit.duke.edu/izatt-lab/vcpkg-izattlab.git vortex/.vcpkg-izattlab

3. Build vcpkg¶

.\vortex\.vcpkg\bootstrap-vcpkg.bat -disableMetrics

Turn off telemetry (-disableMetrics) if desired.

4. Install vortex Dependencies¶

.\vortex\.vcpkg\vcpkg.exe --triplet=x64-windows --overlay-ports=vortex\.vcpkg-izattlab install fmt spdlog xtensor[tbb,xsimd] reflexxes cuda cub xtensor-python pybind11 hdf5[cpp]

Remove or adjust dependencies based on your needs.

5. Install Python¶

Official Distribution¶

Simply download and install a 64-bit version of Python 3. Make sure that setuptools and wheel packages are available if you into to build a binary wheel.

pip install setuptools wheel

Thrid-Party Distribution¶

You may install Python with Miniconda or the larger Anaconda. Make sure to choose a 64-bit version of Python 3. Also, make sure that setuptools and wheel packages are available if you into to build a binary wheel. If you do install Python with this approach, make sure to launch your build system from within the conda environment. The example below shows how to create a conda environment, activate it, and launch Visual Studio 2019 from within the environment.

conda create --name vortex
conda activate vortex
pip install setuptools wheel
& "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\devenv.exe"

6. Build vortex¶

If you are using Visual Studio 2019, copy the contents of the clang configuration template above into CMakeSettings.json in the vortex root folder (i.e., the directory containing this file). Make sure to change ${vcpkg_root} within the template to the full path of the your vcpkg root (the directory containing vcpkg.exe). Also make sure to change ${python_path} to the full path of your Python executable (e.g., python.exe).

You may now use the menu option File > Open > CMake… to browse and select CMakeLists.txt in the vortex root folder. To customize the CMake options, use Project > CMake Settings for vortex. Make sure to set the appropriate CMake options for the dependencies you installed.

Next, select the desired build configuration from the toolbar, configure the project with Project > Generate Cache for vortex, and build.