Installation

OpenCL

OpenCL programming language and development tools are available for a number of platforms.

Nvidia

Windows OS

On Windows OS Nvidia distributes OpenCL with the CUDA Toolkit. Note that that Cuda Tolkit 10.2 is the last version that supports older Windows OS, such as Windows 7, Windows 8 and Windows 8.1. The latest version of CUDA toolkit only supports Windows 10. Follow the above links to download the CUDA Toolkit installer executable for your Windows. Run the installer and follow the dialogs to install the CUDA Toolkit.

Linux OS

You can install the CUDA toolkit by downloading the distribution from NVIDIA Developer site and follow the instructions.

Some distributions, such as Ubuntu, also have good native support for installing the NVIDIA drivers using ubuntu-drivers and the autoinstall option that will install the appropriate driver version for the installed hardware.

sudo ubuntu-drivers autoinstall

Cuda Toolkit can be installed using the package manager:

sudo apt update
sudo apt install nvidia-cuda-toolkit

To enable OpenCL, you will also have to install ocl-icd-libopencl1 and optionally a command line tool clinfo that can be used to display all the installed OpenCL devices.

sudo apt update
sudo apt install ocl-icd-libopencl1
sudo apt install clinfo

AMD

Drivers and the OpenCL runtime for AMD devices along with installation instructions can be downloaded from https://www.amd.com/en/support.

Intel

Instructions for installing Intel OpenCL runtime can be found here. Note that some distributions of Linux have native support for installing the required packages through the system package manager. On Ubuntu distribution the drivers and OpenCL runtime are available through the intel-opencl-icd and beignet-opencl-icd packages.

Python

PyXOpto requires Python 3 (version >= 3.7) programming language and at least the following extension packages:

Additional packages are required to use modules that enable scattering phase function calculations for layered spherical particles:

Note that the distribution is tested with the listed versions.

Windows OS

On Windows OS you can conveniently use WinPython, a portable distribution of the Python programming language for Windows 7/8/10. The WinPython distribution comes with many commonly used Python extension packages including the ones required by the PyXOpto package. The installation also comes with Spyder and Visual Studio Code integrated development environments.

Alternatively, use the Anaconda Python distribution that is available for a wide range of operating systems. Follow the instructions to install the required extension packages.

Here you can find many 32- and 64-bit Windows binaries of open-source Python extension packages.

The following two examples should install the Python 3 programming language and the required packages on Windows OS.

Anaconda Python Distribution:

  1. Install the Anaconda Individual Edition.

  2. Run Anaconda Prompt.

  3. Add conda-forge channel:

conda config -add channels conda-forge

  1. Create a new conda environment named custom_env:

conda create -n custom_env

  1. Install the required Python packages:

conda install -n custom_env scipy matplotlib numpy pyopencl shapely jinja2 numba

  1. The custom environment custom_env can be activated:

activate custom_env

WinPython distribution:

  1. Download and extract the WinPython distribution (available at https://winpython.github.io/ and make sure that it contains preinstalled packages scipy, matplotlib, numpy, shapely, jinja2 and numba)

  2. The package pyopencl is not included and has to be downloaded separately from Gohlke’s website https://www.lfd.uci.edu/~gohlke/pythonlibs/#pyopencl. Download the latest version that corresponds to the extracted Python version and architecture.

  3. Run WinPython Control Panel from the extracted WinPython folder.

  4. Add and install the package pyopencl by locating the downloaded .whl file.

Linux OS

On Linux operating systems, Python is very likely already installed. If not, use the OS package manager to install Python 3. Individual Python packages can be installed through the Python package manager pip. Note that on some Linux distribution the Python 3 and related Pip executables are named python3 and pip3. In this case, the python and pip executables are reserved for the deprecated Python 2 programming language.

The following example should install the latest Python 3 programming language and related packages on Ubuntu or Debian distributions:

sudo apt update
sudo apt install python3
sudo apt install python3-pip

sudo pip3 install scipy
sudo pip3 install matplotlib
sudo pip3 install numpy
sudo pip3 install Shapely
sudo pip3 install numba
sudo pip3 install pyopencl
sudo pip3 install Jinja2
sudo pip3 install python-scattnlay

Alternatively, install one of the supported Python distributions such as Anaconda and follow the instructions to install the required extension packages.

Integrated development environments

There are numerous Integrated development environments (IDE) that support the Python programming language. As already pointed out, Winpython distribution comes with Spyder IDE and Visual Studio Code that are also supported by the Anaconda distribution. Other popular full-featured IDEs supported across different operating systems:

PyXOpto

First, download or clone the PyXOpto source repository to a local directory. The source code can be installed as a Python package or used directly from the downloaded source.

As a Python package

PyXOpto can be installed as a package using the setup.py file. Run the following command from the root directory of PyXOpto (the one with the setup.py file).

python setup.py install

This will also install the dependencies that include several popular Python packages (scipy, matplotlib, numpy, pyopencl, shapely, numba, and jinja2).

Note

When using Windows OS and Anaconda Python distribution, PyXOpto should be installed by running the Anaconda Prompt and activating the custom environment created in the Python installation section. When using the WinPython distribution, the WinPython Command Prompt found in the extracted WinPython folder should be run instead.

The PyXOpto installation can be verified by running an example found in examples folder, e.g., examples/mcml/basic.py:

python basic.py

Using from source

To use the PyXOpto package from source, you will have to manually install all the Python packages listed in the setup.py file. Follow the installation instructions for Python.

You will also have to manually include the root directory of the PyXOpto package into the Python search path. This can be conveniently accomplished through setting the PYTHONPATH environment variable.

On Linux operating systems use:

export PTYTHONPATH=path/to/pyxopto:$PYTHONPATH

On Windows operating systems use:

set PTYTHONPATH=path\to\pyxopto;%PYTHONPATH%

After installing the dependencies and setting the environment variable PYTHONPATH, you should be able to import PyXOpto.

Binaries

PyXOpto does not require compilation of C/C++ sources. However, performance critical parts of the random number generator module xopto.cl.clrng can optionally benefit from a binary library. The build process is fully automated and can be executed by running the xopto.rebuild() function.

import xopto
xopto.rebuild()

The build process requires GCC or The Microsoft C++ (MSVC) compiler toolset.

Local PyXOpto data

PyXOpto will save a small amount of data (built libraries, temporary files and performance-critical precalculated data) in the home directory of the current user ~/.xopto. This location can be customized through the PYXOPTO_USER_PATH environment variable.

Environment variables

Some properties of PyXOpto can be customized through the use of environment variables:

  • PYXOPTO_VERBOSE=0 - Turns on (PYXOPTO_VERBOSE=1) or off (PYXOPTO_VERBOSE=1) the verbose initialization mode.

  • PYXOPTO_USER_PATH="~/.xopto" - Location for storing temporary files, built libraries and performance-critical precalculated data.

Citing PyXOpto

We, the authors of PyXOpto, expect that the package is used in accordance with the GPL3+ license and that any work using the PyXOpto package also cites the project and at least one of the following references:

  1. P. Naglič, F. Pernuš, B. Likar, and M. Bürmen, Limitations of the commonly used simplified laterally uniform optical fiber probe-tissue interface in Monte Carlo simulations of diffuse reflectance, Biomed. Opt. Expres, 6 (10), 3973-3988 (2015), https://doi.org/10.1364/BOE.6.003973.

  2. P. Naglič, F. Pernuš, B. Likar, and M. Bürmen, Lookup table-based sampling of the phase function for Monte Carlo simulations of light propagation in turbid media, Biomed. Opt. Expres, 8 (3), 1895-1910 (2017), https://doi.org/10.1364/BOE.8.001895.

For commercial use or alternative licensing of PyXOpto please contact us at info@xopto.eu.