PPAFM GUI

The GPU version of Probe-Particle Model (namely the AFM part - ppafm) comes with a graphical user interface (GUI) application. It requires some optional dependencies that can be installed according to the instructions on the installation page. After the installation you can launch the GUI from the command line with

ppafm-gui

After running the command, you should see window like this appear: ppafm-gui

Usage

Open a file by clicking Open File... at the bottom or provide the input files as a command line argument. More details below. Notice that loading large files may take some time.
Changing any number in any input box will automatically update the image. There are also presets for some commonly used tip configurations. Hover the mouse cursor over any parameter for a tooltip explaining the meaning of the parameter.
Click anywhere on the image to bring up a plot of the df approach curve for that point in the image.
Scroll anywhere on the image to zoom the scan window in/out of that spot.
Click on the View Geometry button to show the system geometry in ASE GUI.
Click on the Edit Geometry button to edit the positions, types, and charges of the atoms in the system. Note that for Hartree potential inputs, editing charges is disabled and editing the geometry only affects the Lennard-Jones force field.
Click on the View Forcefield button to view different components of the force field. Note that the forcefield box size is inferred automatically from the scan size and is bigger than the scan size. Take into account the probe particle equilibrium distance when comparing the reported z-coordinates between the forcefield and the df image.
Click on the Edit Forcefield button to edit the per-species parameters of the Lennard-Jones forcefield.
Save the current image or df data by clicking the Save Image... or Save df... buttons at the bottom.
The Save parameters... and Load parameters... buttons can be used for saving all of the parameters in the GUI into a params.ini file or loading all of the parameters from an existing file. The params.ini file is the format used by the command-line interface to ppafm.
In case there are multiple OpenCL devices installed on the system, use the -l or --list-devices option to list available devices and choose the device using the -d or --device option with the device platform number as the argument.

Starting a new simulation

You can open files for a new simulation by clicking the Open File... button at the bottom. This opens a new dialogue where you can browse for the files. The number and type of input files depend on the type of force field you want to use for the simulation, which you can choose by clicking on one of the tabs. The different options are detailed below.

Lennard-Jones with optional point-charge electrostatics

Use the Lennard-Jones force field to simulate the Pauli repulsion and attractive van der Waals interactions. Additionally, an electrostatic interaction can be calculated from partial charges specified as point-charges for each atom in the sample. Supported file formats are the .xyz format, the .in format of FHI-aims, and the POSCAR/CONTCAR formats of VASP. The point-charges are only supported in the .xyz format, by adding the charges as an additional column for each atom.

Note that while input files without charges work, depending on the system, the resulting image may be significantly different from an image with electrostatics, and therefore may not be representative of reality. If no electrostatics are included, this is indicated in the title of the image.

Lennard-Jones with Hartree potential electrostatics

Use the Lennard-Jones force field as well as an electrostatic interaction calculated as a cross-correlation between the sample Hartree potential and the tip charge density. Give the sample Hartree potential as an input either in .cube or .xsf formats. You can also optionally supply the tip charge density. If the charge density is an electron density, then check the box underneath to subtract the valence electrons from the density in order to make it neutral. Notice that at the moment the only pseudo-potential electron densities are supported. If the density is already neutral (e.g. delta density), leave the box unchecked. If you don't supply the tip charge density, then an approximation with a multipole density can be specified in the main simulation window.

Full-density based model

Use the full-density based model (FDBM), which approximates the Pauli repulsion as an overlap integral between the sample and tip electron densities. The attractive van der Waals interaction is calculated using the DFT-D3 method, and the electrostatic interaction is the same one as above using the Hartree potential. Provide the sample Hartree potential and electron density, as well as the tip electron density as inputs. At the moment only the .xsf format is supported for the electron densities. You can also optionally provide a neutral charge density (delta density) for the tip for use in the electrostatics calculation. If you don't provide this input, then the valence electrons are subtracted from the tip electron density in order to make a neutral density.

Launching from the desktop

Launching GUI applications from the command line is no fun, so you may want to create a desktop icon for ppafm-gui.

Linux

On Linux desktops, you can create a desktop entry by creating a .desktop file. Create a file named ppafm-gui.desktop inside ~/.local/share/applications/ with the following contents

[Desktop Entry]
Type=Application
Name=PPAFM-GUI
Comment=Simulate high-resolution atomic force microscopy images
Exec=ppafm-gui %f
Terminal=false

A new application named PPAFM-GUI should appear in your list of applications (may require a re-login) and you should be able to open files with this application in your file manager with right-click->"Open with..." dialog. You may want to modify the Exec line with additional options to, for example, choose the OpenCL device with the -d option.

Windows

Go to the desktop and create a new shortcut with right-click->New->Shortcut. In item location field, type ppafm-gui. Click Next, and type any name you want for the shortcut. Double-clicking the shortcut should now open the GUI. It should also be searchable in the Start menu, and you can associate file types to the shortcut with right-click->"Open With". You can modify command-line arguments to the application by right-click->Properties on the shortcut and modify the Target field.

MacOS support

Apple has officially deprecated OpenCL in favor of their Metal platform since MacOS 10.14, so support is not guaranteed into the future. We haven't tested the GUI on MacOS, but you could try anyway. Running with pocl according to the pyopencl documentation should work.