At the time of this writing, there is no handybeam package ready for automated installation. There might be one in the future.

Hence, one has to install all the files and dependencies by hand.

Notable dependencies

These are explained later in the walk through:

  • pyopencl
  • matplotlib
  • pyqtgraph
  • bugsnag
  • numpy
  • scipy
  • cmocean
  • appdirs – pip install appdirs
  • imutils – conda install -c pjamesjoyce imutilsimutils
  • pillow ( pil ) – conda install -c conda-forge pillowpillow



These are instructions for mac:

  1. install git from https://git-scm.com/download
  2. install anaconda, python 3.6 version, from https://www.anaconda.com/download
  3. go to the mac console. You might need two tabs.
  4. in the console, go to the folder where You intend to store the copy of HandBeam software
  5. create a new environment with Python 3.6.5:
conda create -n handybeam python=3.6.5
  1. Wait for the installation to progress
  2. Activate the new environment:

for Mac, the command may be:

source activate handybeam

for Windows, the command may be:

activate handybeam

for other platforms, consult Conda documentation.

  1. Install jupyter and spyder in this environment. Note that even tough jupyter and spyder would normally launch without this, they might confuse which environment to run in. So we have to remind them by installing them again here.
conda install ipykernel jupyter spyder
  1. Install remaining dependencies
pip install bugsnag appdirs vispy pyquaternion pyopengl
conda install nb_conda_kernels matplotlib pyqtgraph numpy scipy pandas
conda install -c conda-forge cmocean
  1. Install pyopencl. At this point, there might be some errors, depending on how is Your laptop set up. If they occur, you will have to somehow debug it and then come back here. In any case, make sure that pyopencl is installed correctly and you can run some examples.
conda install -c conda-forge pyopencl

Note that the common problem here is that the ‘fully featured’ drivers for either the CPU or GPU are not installed on Your system.

You might want to bing for OpenCL drivers for Your hardware, e.g. like this

  1. Clone the repository from github, or download it.
git clone https://github.com/ultrahaptics/HandyBeam.git handybeam_core_repo
  1. Select the OpenCl compute device


This section might be outdated – please take care. I will update and verify asap!

HandyBeam uses OpenCL to accelerate the compute-intensive parts of the code.

Since there can be many parallel computing devices in Your machine, one needs to be selected.

At this time, there is no automatic selector implemented. You have to do this manually.

import handybeam.propagator

Your selection is stored in cl_platform_config.ini.

For the Ultrahaptics standard issue Macbook Pro (2019) it will typically be:

use_platform = 0
use_device = 2

For a Windows platform with a high-power GPU, it will typically be:

use_platform = 0
use_device = 0

For other machines (Linux, Android e.t.c.) you need to be able to figure it for yourself.

  1. Next time You start Your terminal, be reminded that You need to ‘activate the handybeam envinroment’ first.

for Mac, the command may be:

source activate handybeam

for Windows, the command may be:

activate handybeam

for other platforms, consult Conda documentation.

  1. Try the demos\basic_flat_field_.py
  2. Try the demos\demo_mouse_control_field.py

Back to Welcome

Licence (documentation): Creative Commons CC BY-NC-SA 4.0

Licence (source code): Apache 2.0

EU logo

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 737087.

This project has received funding from Ultrahaptics.

Ultrahaptics logo