Getting Started¶

vortex is available in Python and C++. For standard hardware setups, the Python bindings via a binary wheel are the fastest way to get started.

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. 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-cuda112 vortex-oct-tools -f https://www.vortex-oct.dev/

Install Dependencies¶

These binary wheels are compiled for use with an AlazarTech digitizer for acquisition, a CUDA-compatible GPU for processing, and National Instruments hardware for I/O. They require the installation of the following driver and runtime components, even if the corresponding hardware is not present.

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.

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

vortex will fail to import if any of the above dependencies are missing. 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 and the vortex version if vortex is correctly installed.

> python -c "import vortex; print('OK', vortex.__version__)"
OK 0.4.1

If you receive the API version incompatibility error message below, you likely need to upgrade NumPy.

> python -c "import vortex; print('OK', vortex.__version__)"
RuntimeError: module compiled against API version 0xf but this version of numpy is 0xe
OK 0.4.1
> pip install --upgrade numpy
> python -c "import vortex; print('OK', vortex.__version__)"
OK 0.4.1

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. Make sure to install Clang/LLVM support for Visual Studio.

Activate Developer Prompt¶

The vortex setup script requires the Visual Studio Developer PowerShell (or Prompt) for building. This is necessary to ensure CMake detects clang-cl. You can activate the Developer PowerShell from an existing PowerShell session as follows.

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

Configure Features¶

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

> $env:VORTEX_BUILD_FEATURES="WITH_ALAZAR=ON;WITH_CUDA=ON;WITH_DAQMX=ON;WITH_HDF5=ON;WITH_REFLEXXES=ON"

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¶

Clone the repository or download the source, and then run the setup script.

> git clone https://gitlab.oit.duke.edu/izatt-lab/oct/vortex.git
> python vortex/setup.py install

Alternatively, you may install directly from the repository using the Package Installer for Python. You may need to pass the --no-build-isolation flag if building vcpkg dependencies fails inside pip’s isolated build environment.

> pip install git+ssh://git@gitlab.oit.duke.edu/izatt-lab/oct/vortex.git

C++¶

A C++ installation provides full access to vortex’s features. To get started quickly with a standard build configuration, see below. For more advanced needs, see the Build Guide to get your build system set up.

Build Dependencies¶

In either case, clone the repository or download the source first.

> git clone git@gitlab.oit.duke.edu:izatt-lab/oct/vortex.git
> git clone https://github.com/microsoft/vcpkg.git vortex/build/vcpkg
> .\vortex\build\vcpkg\bootstrap-vcpkg.bat -disableMetrics
> .\vortex\build\vcpkg\vcpkg.exe --triplet=x64-windows --overlay-ports=vortex\.vcpkg install fmt spdlog xtensor[tbb,xsimd] reflexxes cuda cub xtensor-python pybind11 hdf5[cpp]

Visual Studio¶

Recent versions of Visual Studio (2019 or newer) can open the vortex source root as a CMake project. Visual Studio will then use CMakePresets.json to configure and build the project. For more advanced needs, add your own CMakeUserPresets.json and consult the Build Guide. Make sure to install Clang/LLVM support for Visual Studio.

CMake¶

To use CMake directly, use any of the existing presets from within a Visual Studio Developer PowerShell (or Prompt). List the available presets using cmake --list-presets.

> cmake --list-presets
Available configure presets:

  "clang-win-x64-debug"     - Clang x64 Windows Debug
  "clang-win-x64-release"   - Clang x64 Windows Release
  "clang-win-x64-unopt"     - Clang x64 Windows Unoptimized
> cmake -S vortex -B vortex/build --preset clang-win-x64-release
> cmake --build vortext/build

For more advanced needs, see the Build Guide.