Installation#

There are two ways to get started with HElayers: using Docker or directly through Python.

  • The Docker image installation option is recommended for new HElayers users who wish to explore the various demos that HElayers provides, which may have dependencies on 3rd-party libraries such as scikit-learn. The Docker images come with these dependencies already installed, together with a C++ or Python IDE, where the users can immediately start programming some HE-based applications.

  • The import to Python option is recommended for users who already have a Python environment of choice installed and wish to simply import the pyhelayers package and start programming.

GPU support

HElayers Premium edition allows compiling HElayers with GPU support.

Importing the pyhelayers Python packge#

Install and import one of the following packages to use HElayers from your Python environment of choice.

Python packages
Package Arch OS Supported backends (HE libraries)
HEaaN HElib OpenFHE Lattigo Palisade SEAL
pyhelayers zSystem (s390s) Linux ✔ ✔ ✔ ✔
pyhelayers x86_64 Linux ✔ ✔ ✔ ✔ ✔ ✔
pyhelayers x86_64 MacOS ✔
pyhelayerslite (no AI layer) x86_64 Windows ✔

To install a package e.g., pyhelayers from your command line run:

pip install pyhelayers

If the pip Python package manager is not installed on your system use these instructions.

First verify if Python and pip are installed on your system:

> python --version
Python 3.9.2
> pip --version
pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8)

  • Goto Python if it is not installed.

  • Goto pip if pip is not installed.

In some cases, you may need to upgrade pip to the latest version:

pip install --upgrade pip

On Windows, some of the above commands may not work out-of-the-box. A workaround is to preface every Python command with python -m as follows:

python -m pip install pyhelayers

Docker image installation#

System Requirements#

  • A system that is capable of running a Docker container, with the necessary user privileges to run docker commands.

  • A working internet connection.

Do not expose the HElayers containers to unauthorized access.

Anyone with access to the container web interface will be able to execute code inside it. Only start the HElayers containers on platforms with controlled access.

Getting Started with HElayers on Z systems - instructional setup video

For your convenience, an instructional setup video of how to use the Python demos of HElayers on Z systems is available here. The exact details are also listed in the next sections.

Docker types and supported systems#

Two Docker image types are provided:

  • helayers-lab: Provides C++ APIs. When the container is running, interactions are through the VS Code C++ IDE accessed via the browser.

  • helayers-pylab: Provides Python APIs. When the container is running, interactions are through a Python Jupyter notebook accessed via the browser.

The tables below show the support OSs and HE backends per image.

C++ Docker images
Docker image name Supported backends (HE libraries)
HEaaN HElib OpenFHE Lattigo Palisade SEAL
helayers-lab-x86_64 ✔ ✔ ✔ ✔ ✔ ✔
helayers-lab-s390x ✔ ✔ ✔ ✔

Python Docker images
Docker image name Supported backends (HE libraries)
HEaaN HElib OpenFHE Lattigo Palisade SEAL
helayers-pylab-x86_64 ✔ ✔ ✔ ✔ ✔ ✔
helayers-pylab-s390x ✔ ✔ ✔ ✔

Supported zSystems architectures.

s390x images are built to run on all zSystems architectures including Linux on IBM Z (z16 and LinuxOne III), and zCX Container Extensions.

Compiling HElayers with a single backend.

HElayers Premium edition allows compiling HElayers with only some of the supported libraries, allowing it to run without dependence on the unused ones.

Docker installation#

Step 1: Pull the Docker image#

In your terminal pull the relevant Docker image from the IBM Container Registry to your local repository. Use the helayers docker name from the tables above and specify :latest to pull the most recent version. To specify a specific release version replace :latest with the version number, such as :1.0.

docker pull icr.io/helayers/<helayers docker name>:latest

If the fetch is successful, it will download the image and you will now have an image in your local repository named icr.io/helayers/’helayers docker name’:latest. Check that this image exists with

docker images

Step 2: Running the image#

Once the image download is complete, run the image as a container in Docker using the relevant helayers docker name.

docker run -p 8888:8888 -d --rm --name helayers-lab icr.io/helayers/<helayers docker name>:latest

This command runs the image and sets the container to be accessed via port 8888. It also gives the container a name called helayers-lab, which is used for finding it in the list of other running containers.

Running several Docker containers at once.

When required to run several containers in parallel, e.g., for using the C++ and Python APIs at the same time, set a different port per container. For example, use 8888:8888 for the helayers-lab container and 8888:9999 for the helayers-pylab container.

Step 3: Accessing HElayers and running the tutorials#

  • For Python users:

    • Connect to the Juptyer notebook welcome page by opening a web browser on your host machine (not the docker container instance), and browse to

    http://127.0.0.1:8888/lab/?token=demo-experience-with-fhe-and-python

    • Open (double click) the 00_Getting_Started.ipynb notebook. It contains information about the available tutorials, as well as instructions on how to run them.

  • For C++ users:

    • Connect to the VS Code welcome page by opening a web browser on your host machine (not the docker container instance), and browse to

    http://127.0.0.1:8888

    • Click on the application menu (three bars icon, top left), and choose Terminal > New Terminal

    • In the terminal change directory to examples/<demoName>, where the list of demos and their description is found here.

    • Follow the directions in the readme file of that demo.

Running from a remote machine.

Remember to change the IP address 127.0.0.1 when running the web browser on a different machine other than the docker container.