Install ppafm

Using pip

The standard way of installing ppafm is to use pip:

pip install ppafm

This should install the package and all its dependencies. The approach should work in most cases on all platforms.

Enable GPU/GUI support

The ppafm-gui application requires additional Python dependencies. These dependencies should be installed automatically when you install the ppafm package with the opencl option:

$ pip install ppafm[opencl]

On Linux systems (tested on Ubuntu), you also need to install PyQt5.

$ sudo apt install python3-pyqt5

Additionally, an OpenCL Installable Client Driver (ICD) for your compute device is required. On Ubuntu:

Nvidia GPU: comes with the standard Nvidia driver (nvidia-driver-xxx)
AMD GPU: sudo apt install mesa-opencl-icd (May not work on all AMD devices, see the Pro drivers)
Intel HD Graphics: sudo apt install intel-opencl-icd
CPU: sudo apt install pocl-opencl-icd

Using Anaconda

You can install ppafm with Anaconda. For that, we highly recommend creating a dedicated environment:

conda create -n ppafm python=3.11

You can optionally modify the environment name (ppafm) and Python version (3.11).

Next, activate the environment, and install ppafm:

conda activate ppafm # activation of the environment if created.
pip install ppafm

For GPU/GUI support, install with the additional dependencies:

conda install pyqt ocl-icd-system -c conda-forge
pip install ppafm[opencl]

Note for Windows: With Microsoft OpenCL™ and OpenGL® Compatibility Pack from the Microsoft Store only pyqt is needed, so the installation looks like this:

conda install pyqt -c conda-forge
pip install ppafm[opencl]

Using Docker

Docker allows packaging an application and its dependencies in a virtual container that can run on different operating systems.

After installing Docker on your system, here are the steps to build and run the ppafm Docker container:

Clone the repository, navigate to the root of the repository that has the Dockerfile, and build the image. This can be done on the terminal/PowerShell by running

git clone https://github.com/Probe-Particle/ppafm.git
cd ppafm
docker build -t ppafm:latest .

After the build, the original repository is no longer required, so you may delete it if desired.

Execute the container. On Linux and in Windows PowerShell:

docker run --rm -v ${PWD}:/exec ppafm:latest <ppafm command>

On Windows CMD:

docker run --rm -v %CD%:/exec ppafm:latest <ppafm command>

Here <ppafm command> stands for any of the standard scripting commands in ppafm, such as ppafm-generate-elff, and you would replace the standard commands in the run.sh scripts for any of the examples with the docker command while running in the example folder.

Building `ppafm` from the source

This type of installation is handy for development, in that case, please also check our development wiki pages. To compile the code from the source you need a C++ compiler - Install dependencies:

Linux/MacOS: Install g++ and make. On Ubuntu, for example, sudo apt install g++ make. See lower for additional instructions, if you have problems.
Windows: Install Visual Studio Build Tools: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022. Make sure to check the "Desktop development with C++" option during the installation. Launch the newly-installed x64 Native Tools Command Prompt for VS 2022 and run the following commands inside this prompt.

Clone the repo and install with pip:

git clone https://github.com/Probe-Particle/ppafm.git
cd ppafm
pip install .

Note: sometimes also git is not part of the PowerShell Windows distribution - can be obtained through conda install git.

Notes on different platforms

Linux

Some linux distributions like ubuntu recently started to limit global usage of pip, and force you to create virtual environment by this meassage:

Desktop:~/git/ppafm/$ pip install ppafm
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    
    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.
    
    See /usr/share/doc/python3.11/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

To resolve this problem you have to create and use new environment with these two commands:

python3 -m venv /home/prokop/venvs/ppafm
source ~/venvs/ppafm/bin/activate then follow with the installation as above:

git clone https://github.com/Probe-Particle/ppafm.git
cd ppafm
pip install .

Installing the GPU version with pip according to the README instructions requires rights to install system packages. If you don't have sufficient rights, you can try using Anaconda instead (see above), which is entirely self-contained with PyQt5 support.

Note for zsh users: attempting to install the GPU version with pip install ppafm[opencl] does not work because zsh uses brackets for pattern matching. Do instead pip install ppafm\[opencl\].

MacOS

The basic installation should work without problems on Intel MACs. However, for the more recent ARM processors you need to have the build dependencies installed on your system (see above). Support for the GPU version is not guaranteed.

Building from the source - additional instructions: If the original g++ compiler doesn't compile the code (e.g. 1.0d is not recognized) - consider updating it. If you do not have sudo rights to update your system, please try to get a new compiler through anaconda or through homebrew. You might also use this script to install Homebrew with no sudo rights.

Windows

Windows does not come with Python pre-installed, we suggest using Anaconda as the primary way. There is also a direct way through installing Python if you don't have it yet: https://www.python.org/downloads/windows/. Then open Command Prompt and install with pip install ppafm[opencl] as instructed. Windows may not have all of the paths configured right for Python user installations, so if any of the commands don't work correctly, you may have better success if you do the pip installation with administrative access (Command Prompt->right-click->Run as administrator).

Building from the source - additional instructions: If you do not have administrative rights but want to edit the code on Windows, be prepared for problems. One of the approaches working on Win10, without the possibility to install MS Visual Studio executable, is to go through Anaconda and get g++ for Windows through e.g.:

conda install -c rnicolas mingw-w64-posix-msvcrt

and navigate to the cpp folder where one can have run following commands:

g++ -fPIC -std=c++11 -O2 -mtune=native -fopenmp -c ProbeParticle.cpp -o ProbeParticle.o
g++ -shared -fopenmp ProbeParticle.o -o ProbeParticle_lib.dll
g++ -fPIC -std=c++11 -O2 -mtune=native -fopenmp -c GridUtils.cpp -o GridUtils.o
g++ -shared -fopenmp GridUtils.o -o GridUtils_lib.dll
g++ -fPIC -std=c++11 -O2 -mtune=native -fopenmp -c fitting.cpp -o fitting.o
g++ -shared -fopenmp fitting.o -o fitting_lib.dll
g++ -fPIC -std=c++11 -O2 -mtune=native -fopenmp -c fitSpline.cpp -o fitSpline.o
g++ -shared -fopenmp fitSpline.o -o fitSpline_lib.dll

instead of make, which is not working right. Remember to recompile your C++ code, if you are making changes in that part.

OpenMP

The CPU version of the code currently use OpenMP parallelization by default as we assume it is widely supported by all platforms, but the code can still work easily without OpenMP. You can set the amount of (logical) CPU cores available for the OpenMP run ncores through:

export OMP_NUM_THREADS=ncores

Unfornatunely there is no robust mechanism how to detect failure of OpenMP on your system and disable it automatically. If you encounter OpenMP related problem please do following steps:

Remove -fopenmp from CPPFLAGS in /ppafm/cpp/Makefile (this line: CPPFLAGS= -fPIC -std=c++11 -O2 -mtune=native -fopenmp)
Modify this line in function perform_relaxation() in /ppafm/HighLevel.py so that it use relaxedScan3D() rather than relaxedScan3D_omp()
In case OpenMP header files are not installed on your seesem you may need to remove #include <omp.h> from /ppafm/cpp/Grid.h and /ppafm/cpp/ProbeParticle.cpp and eventually all mention of omp_* function calls in these files.