Getting Started

vortex is available in Python and C++. The Python bindings via a binary wheel is the fastest way to get started.

Tip

See the Python demo guide for high-level step-by-step instructions to get started quickly.

Python from Binary Wheel

Pre-built binary wheels for recent Python and CUDA versions on Windows are published on the vortex website. Ensure that you install the wheel that matches the CUDA version for your system. vortex uses the suffix -cudaXXY to denote a build for CUDA XX.Y.

Note

For CUDA 11 and higher, vortex supports CUDA forward compatibility between minor versions. In these cases, Y has the value x (e.g., vortex-cuda12x) to indicate support for all CUDA releases for a given major version.

Installation of vortex-oct-tools is also recommended as it provides Python support classes for interacting with vortex and is required for certain demos.

> pip install vortex-oct-cuda12x vortex-oct-tools --extra-index-url https://vortex-oct.dev/stable

$ pip3 install vortex-oct-cuda12x vortex-oct-tools --extra-index-url https://vortex-oct.dev/stable

You can install developments builds of vortex for testing new features by using --extra-index-url https://vortex-oct.dev/develop instead.

Install Dependencies

These binary wheels are compiled with support AlazarTech and Teledyne ADQ digitizers, CUDA-compatible GPUs, and National Instruments I/O and camera interface cards. CUDA is a mandatory dependency for the binary wheels and must be installed for vortex to load. All other hardware components are optional so you need install only the driver and runtime components for each of those specific devices that you plan to use.

Mandatory

  • CUDA runtime with version XX.Y for vortex-oct-cudaXXY

Optional

  • AlazarTech drivers for the installed digitizer

    Attention

    The AlazarTech drivers are different from ATS-SDK, which is the software development kit only. ATS-SDK is required for building vortex and does not include the drivers. The AlazarTech drivers are required to run vortex.

  • Teledyne ADQAPI runtime and drivers for the installed digitizer

  • NI DAQmx runtime

  • NI IMAQ runtime

Tip

See the build guide for help installing the Linux dependencies.

Mandatory

  • CUDA runtime with at least version XX.Y for vortex-oct-cudaXXY

Optional

  • AlazarTech drivers for the installed digitizer

    Attention

    The AlazarTech drivers are different from ATS-SDK, which is the software development kit only. ATS-SDK is required for building vortex and does not include the drivers. The AlazarTech drivers are required to run vortex.

  • Teledyne ADQAPI runtime and drivers for the installed digitizer

    Attention

    Binary releases of vortex are compiled with ADQAPI version 2023.2. Teledyne features may not load for runtime or driver versions other than 2023.2.

  • NI DAQmx runtime

    Attention

    Due to a known issue with DAQmx on Linux, you may need to add iommu=off to your kernel command line.

With the exception of CUDA runtime, vortex will detect the presence of these driver and runtime components and will activate the corresponding functionality. See the Build Guide for instructions on building Python bindings that match your hardware availability.

Check Installation

Check that vortex and its dependencies are installed correctly using the following command. The command outputs OK, the vortex version, and available features if vortex is correctly installed.

> python -c "import vortex; print('OK', vortex.__version__, vortex.__feature__)"
OK 0.5.1 ['machdsp', 'reflexxes', 'fftw', 'cuda', 'hdf5', 'cuda_dynamic_resampling', 'alazar', 'alazar_dac', 'daqmx', 'imaq', 'teledyne', 'simple', 'exception_guards', 'pybind11_optimizations']

$ python3 -c "import vortex; print('OK', vortex.__version__, vortex.__feature__)"
OK 0.5.1 ['machdsp', 'reflexxes', 'fftw', 'cuda', 'hdf5', 'cuda_dynamic_resampling', 'alazar', 'alazar_dac', 'daqmx', 'imaq', 'teledyne', 'simple', 'exception_guards', 'pybind11_optimizations']

If an expected feature is absent from the list, ensure that you installed the correct driver or runtime component above. For more detailed investigation, see the debugging steps. Once everything is installed, try running a demo.

Python from Source

The vortex setup script is capable of installing all open-source build dependencies using vcpkg and generating wheels for installation. Building vortex from source is only recommended if the binary wheels are not suitable for your hardware.

Configure Build Environment

The vortex setup script requires the Visual Studio Developer PowerShell (or Prompt) for building with clang-cl. Make sure to install Clang/LLVM support for Visual Studio. You can activate the Developer PowerShell from an existing PowerShell session as follows.

> Import-Module C:"\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Microsoft.VisualStudio.DevShell.dll"
> Enter-VsDevShell -VsInstallPath "C:\Program Files\Microsoft Visual Studio\2022\Community" -DevCmdArguments "-arch=x64"

The vortex build script requires cmake, ninja, and clang for building. These and other required packages are available through the system package manager.

$ sudo apt install curl zip unzip tar pkg-config cmake ninja-build clang patchelf python3 python3-pip

Configure Features

You can enable or disable features using the VCPKG_MANIFEST_FEATURES environment variable, which is a semicolon-delimited list of vcpkg features, especially those that enable or disable features. The setup script parses the feature specification and automatically installs the required packages from vcpkg. Closed-source dependencies, such as CUDA and NI DAQmx, still require manual installation as for the binary wheel above.

> $env:VCPKG_MANIFEST_FEATURES="asio;backward;cuda;reflexxes;fftw;hdf5;python"

$ export VCPKG_MANIFEST_FEATURES="asio;backward;cuda;reflexxes;fftw;hdf5;python"

If you do not want the setup script to install dependencies using vcpkg, define the environment variable VORTEX_DISABLE_AUTO_VCPKG or specify CMAKE_TOOLCHAIN_FILE or CMAKE_INSTALL_PREFIX as environment variables.

Build with Setup Script

vortex source distributions lack the -cudaXXY suffix and are thereby distinguished from the binary wheels. You may clone the repository or download the source, and then run the setup script.

> git clone https://gitlab.com/vortex-oct/vortex.git
> pip install ./vortex

$ git clone https://gitlab.com/vortex-oct/vortex.git
$ pip3 install ./vortex

Alternatively, you may install directly from the repository.

> pip install git+https://gitlab.com/vortex-oct/vortex.git

$ pip3 install git+https://gitlab.com/vortex-oct/vortex.git

C++

The build procedure varies based on the use-case for vortex.

As an Application Dependency

Most users will want to include vortex as a dependency in a larger application. See the vortex application example for a walkthrough.

As a Library for Development

To compile vortex directly for development or customization purposes, follow the steps below.

  1. Install and/or setup vcpkg for vortex’s C++ dependencies. Avoiding using shallow clones of vcpkg (e.g., with --depth) as this can cause problems when installing packages with the specific package versions specified in vortex’s manifest file.

    > git clone https://github.com/microsoft/vcpkg.git
> ./vcpkg/bootstrap-vcpkg.bat -disableMetrics

    $ git clone https://github.com/microsoft/vcpkg.git
$ ./vcpkg/bootstrap-vcpkg.sh -disableMetrics

  2. Export the path to vcpkg’s build system for CMake. Use an absolute path to avoid unexpected build failures in the future.

    > $env:CMAKE_TOOLCHAIN_FILE=C:/.../vcpkg/scripts/buildsystems/vcpkg.cmake

    $ export CMAKE_TOOLCHAIN_FILE="/.../vcpkg/scripts/buildsystems/vcpkg.cmake"

    Alternatively, set CMAKE_TOOLCHAIN_FILE as a cache variable as shown below.

  3. Clone vortex.

    > git clone https://gitlab.com/vortex-oct/vortex.git

    $ git clone https://gitlab.com/vortex-oct/vortex.git

  4. Edit the cache variables for the top-level CMake preset (base-x64) for building vortex in vortex/CMakePresets.json. Configure the vortex features to build using the VCPKG_MANIFEST_FEATURES cache variable. Also, you can define the CMAKE_TOOLCHAIN_FILE cache variable here rather than setting it as an environment variable above.

    "cacheVariables": {
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/install/${presetName}"
  "CMAKE_TOOLCHAIN_FILE": "/.../vcpkg/scripts/buildsystems/vcpkg.cmake",
  "VCPKG_MANIFEST_FEATURES": "asio;backward;cuda;reflexxes;fftw;hdf5;python"
},

    Find a complete list of feature names using vcpkg search vortex --featurepackages or in the vortex port manifest. See the documentation for additional build options.

  5. Choose and customize the build preset for your system. vortex provides presets for building with Clang-CL on Windows and clang or gcc on Linux in debug, unoptimized, or release modes.

    • Debug mode builds with debug versions of all libraries and includes symbols. This mode is generally not compatible with Python support since you will need to have a debug version of NumPy installed.

    • Unoptimized mode builds with release versions of all libraries but turns debug symbols on and optimizations off for vortex. This is the recommended mode for debugging vortex if Python features are enabled.

    • Release mode builds with release versions of all libraries and turns on all optimizations for vortex. Debug symbols are included for vortex if not optimized out.

    Edit the presets with names that start with base- so that changes propagate to debug, unoptimized, and release builds.

    "name": "base-clang-win-x64",
"inherits": "base-x64",
"generator": "Ninja",
"environment": {
    "CC": "clang-cl",
    "CXX": "clang-cl",
    "CXXFLAGS": "-m64 -fdiagnostics-absolute-paths -fcolor-diagnostics -Wno-unused-command-line-argument /Zi",
    "CUDAFLAGS": "--expt-relaxed-constexpr -lineinfo -Xcudafe --diag_suppress=base_class_has_different_dll_interface -diag-suppress 27 -Wno-deprecated-gpu-targets -Xcompiler=/wd4984 --debug",
    "LDFLAGS": "/debug"
},
"cacheVariables": {
    "CMAKE_CUDA_STANDARD": "17"
},

  6. If you plan to build with Python support, install the Python requirements first.

    > pip install -r vortex/requirements.txt

    $ pip3 install -r vortex/requirements.txt

  7. Build vortex using your chosen environment.

    • For Visual Studio, open the root folder for vortex as a CMake project. Select the correct preset from the configuration dropdown in the toolbar and then build.

    • For Visual Studio Code, open the root folder for vortex. Make sure to install the C++ and CMake extensions. Select the correct configure preset using the CMake extension and then build.

    • For CMake from the command line, configure using the selected preset.

      > cmake -S vortex -B vortex/build --preset clang-win-x64-release
> cmake --build vortex/build

      $ cmake -S vortex -B vortex/build --preset gcc-linux-x64-release
$ cmake --build vortex/build

    If you edit the CMake preset, delete your CMake cache and reconfigure to ensure that the changes take effect.