Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve the README.md file #172

Merged
merged 2 commits into from
Jun 13, 2023
Merged

Improve the README.md file #172

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2e44fd8
Improve the README.md
yakutovicha Jun 13, 2023
d1d11d9
Update README.md
yakutovicha Jun 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 73 additions & 86 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,91 +3,83 @@

Simple and efficient **simulation software for high-resolution atomic force microscopy** (**HR-AFM**) and other scanning probe microscopy (SPM) techniques with sub-molecular resolution (STM, IETS, TERS). It simulates deflection of the particle attached to the tip (typically CO molecule, but also e.g. Xe, Cl-, H2O and others).

### Further information
- Publications: https://github.com/Probe-Particle/ProbeParticleModel#notable-publications-using-probe-particle-model
- Wiki: https://github.com/Probe-Particle/ProbeParticleModel/wiki
- API documentation: https://ppafm.readthedocs.io/en/latest/

## Flavors of PPM

Since 2014 PPM developed into the toolbox of various methodologies adjusted for a particular use case.
## Installation

1. **CPU version:** - Original implementation using Python & C/C++. It can simulate a typical AFM experiment (3D stack of AFM images) in ~1 minute. It is the base version for the development of new features and methodology. All available simulation models are implemented in this version, including:
1. **Point charge electrostatics + Lennard-Jones:** Original fully classical implementation allows the user to set up calculation without any ab-initio input simply by specifying atomic positions, types and charges.
2. **Hartree-potential electrostatics + Lennard-Jones:** Electrostatics is considerably improved by using Hartree potential from DFT calculation (e.g. LOCPOT from VASP) and using the Quadrupole model for CO-tip. We found this crucial to properly simulate polar molecules (e.g. H2O clusters, carboxylic acids, PTCDA) which exhibit strong electrostatic distortions of AFM images. Thanks to implementation using fast Fourier transform (FFT) this improvement does not increase the computational time (still ~1 minute), as long as the input electrostatic field is accessible.
3. **Hartree-potential electrostatics + Density overlap:** Further accuracy improvement is achieved when Pauli repulsion between electron shells of atoms is modeled by the overlap between electron density of tip and sample. This repulsive term replaces the repulsive part of Lennard-Jones while the attractive part (C6) remains. This modification considerably improves especially simulation of molecules with electron pairs (-NH-, -OH, =O group), triple bonds and other strongly concentrated electrons. Calculation of the overlap repulsive potential is again accelerated by FFT to achieve minimal computational overhead (2-3 minutes) as long as input densities of tip and sample are available.
2. **GPU version:** - Version specially designed for generation of training data for machine learning. Implementation using `pyOpenCL` can parallelize the evaluation of forcefield and relaxation of probe-particle positions over hundreds or thousands of stream-processors of the graphical accelerator. Further speed-up is achieved by using hardware accelerated trilinear interpolation of 3D textures available in most GPUs. This allows simulating 10-100 AFM experiments per second on consumer-grade desktop GPU.
* GPU version is designed to work in collaboration with machine-learning software for AFM (https://github.com/SINGROUP/ASD-AFM) and use various generators of molecular geometry.
3. **GUI @ GPU** - The speed of GPU implementation also allows to make interactive GUI where AFM images of molecules can be updated on the fly (<<0.1s) on a common laptop computer while the user is editing molecular geometry or parameters of the tip. This provides an invaluable tool especially to experimentalists trying to identify and interpret the structure and configuration of molecules in experiments on-the-fly while running the experiment.
To install the latest version of PPM, run:

#### Other branches
```bash
$ pip install ppafm
```

* **master_backup** - Old `master` branch was recently significantly updated and named `main`. For users who miss the old master branch, we provided a backup copy. However, this version is very old and its use is discouraged. If you miss some functionality or are not satisfied with the behavior of current `main` branch please let us know by creating an *issue*.
* **PhotonMap** - implements the latest developments concerning sub-molecular scanning probe combined with Raman spectroscopy (TERS)y and fluorescent spectroscopy (LSTM).
* **complex_tip** - Modification of probe-particle model with 2 particles allows a better fit to experimental results at the cost of additional fitting parameters.
This should install the package and all its dependencies.
Once the installation is completed, the following commands should be available:

## Installation & running examples
- `ppafm-generate-elff` - command-line interface to gelerate electrostatic force field.
- `ppafm-generate-elff-point-charges` - command-line interface to gelerate electrostatic force field using point charges.
- `ppafm-generate-ljff` - command-line interface to gelerate Lennard-Jones force field.
- `ppafm-relaxed-scan` - command-line interface to run scan the sample with the probe particle.
- `ppafm-plot-results` - command-line interface to plot the results of the simulation.
- `ppafm-gui` - GUI application for interactive simulation of AFM images.

All development and testing were done on **linux** OS (mostly ubuntu). However, there are also pip wheels for Windows available. See also the docker image below for a platform-independent way of running the code.

#### Install & run CPU version
### Install GPU GUI

**Requirements:** Python3 (numpy,matplotlib) & C/C++ compiler (g++,make)
To make sure the `ppafm-gui` command works without problems, you need to install QT5 library on your system.
On Ubuntu, you can do this by running:

##### First run: Graphene with point-charges
1. clone the repository: `clone https://github.com/Probe-Particle/ProbeParticleModel.git`
2. compile the C/C++ modules
* `cd ProbeParticleModel/Graphene`
* `make`
3. Navigate to examples directory `cd ProbeParticleModel/examples/Graphene`this example uses simple (Point-charges + Lennard-Jones)
4. run the example `./run.sh`
5. output directory `/examples/Graphene/Q-0.05K0.50/Amp2.0` should contain simulated images with tip charge -0.05e, stiffness 0.5N/m and ossicaltion amplitude 2.0A.
```bash
$ sudo apt install python3-pyqt5
```

*NOTE:* Python package is designed to automatically recompile the C/C++ automatically, which is convenient for development, so explicit compilation in step #2 maybe not be necessary. see e.g. `cpp_utils.make("PP")` in `ppafm/core.py`
The other dependencies should be installed automatically when you install the `ppafm` package with `opencl` option:

##### Example 2: PTCDA with Hartree potential
```bash
$ pip install ppafm[opencl]
```

1. navigate to `ProbeParticleModel/examples/PTCDA_Hartree`
2. run the example `./run.sh`
Additionally an OpenCL Installable Client Driver (ICD) for your compute device is required:
* Nvidia GPU: comes with the standard Nvidia driver (nvidia-driver-xxx)
* AMD GPU: `sudo apt install mesa-opencl-icd`
* Intel HD Graphics: `sudo apt install intel-opencl-icd`
* CPU: `sudo apt install pocl-opencl-icd`

*NOTE:* Notice that the script `run.sh` downloads and unpack LOCPOT file:
`wget --no-check-certificate "https://www.dropbox.com/s/18eg89l89npll8x/LOCPOT.xsf.zip"`
`unzip LOCPOT.xsf.zip`
this is a large 3D volumetric file which contains Hartree electrostatic potential (in this example computed by VASP) which have to be provided.
### Use ppafm Docker container

##### Example 3: Pyridine with Density-overlap
We propose to use [Docker](https://docs.docker.com/get-docker/) to make the code platform-independent.
Comment on lines +46 to +48
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But we also plan to have wheels for all platforms, which should become the more straightforward installation option for every platform. Docker is useful to have as an option, but in order to keep the README minimal, maybe this should also be moved to the wiki page with additional installation options.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since you proposed to make follow-up PRs, will you take care of that too?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, I'll do it.


1. navigate to `ProbeParticleModel/examples/pyridineDensOverlap`
2. run the example `./run.sh`
Here are the steps to build and run the ppafm Docker container:

*NOTE:* Notice that the script `run.sh` downloads and unpacks files `CHGCAR.xsf` & `LOCPOT.xsf` and places them in subdirectories `sample` and `tip`. These are electron density and Hartree potential which need to be provided from DFT calculation (this time from VASP).
1. Build the image.

#### Install & run GPU GUI
```bash
$ docker build -t ppafm:latest .
```
2. Execute the container.

Install prerequisites (Ubuntu):
```sh
sudo apt install git python3-pip python3-pyqt5
pip install matplotlib numpy pyopencl reikna ase
```bash
$ docker run --rm -it -v ${PWD}:/exec ppafm:latest <ppafm command>
```

Additionally an OpenCL Installable Client Driver (ICD) for your compute device is required:
* Nvidia GPU: comes with the standard Nvidia driver (nvidia-driver-xxx)
* AMD GPU: `sudo apt install mesa-opencl-icd`
* Intel HD Graphics: `sudo apt install intel-opencl-icd`
* CPU: `sudo apt install pocl-opencl-icd`

Run the GUI application:
```sh
./GUI/ppm-gui
```
## Usage examples

We provide a set of examples in the `examples` directory.
To run them, navigate to the directory and run the `run.sh` script.
For example:

In order to make the GUI application appear in the system application menu and 'Open with' context menus, link the `ppm-gui` application to a location that is on PATH, e.g. `~/.local/bin`, and install the provided .desktop file. This can be achived by running the following in the repository root:
```bash
ln -s `realpath ./GUI/ppm-gui` $HOME/.local/bin
cp ./GUI/resources/ppm-gui.desktop $HOME/.local/share/applications
$ cd examples/PTCDA_single
$ ./run.sh
```

###### Usage:
You can study the script to see how to run the simulation.
Also, have a look at the `params.ini` file to see how to set up the simulation parameters.


Once the simulation is finished, a number of files and folders will be created.

### GUI usage
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would move this whole section to the wiki as well. The GUI needs more documentation anyway.


* Open a file by clicking `Open File...` at the bottom or provide an input file as a command line argument. The input file can be a .xyz geometry file (possibly with point charges*), a VASP POSCAR or CONTCAR file, an FHI-aims .in file, or a .xsf or .cube Hartree potential file. 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.
Expand All @@ -102,45 +94,40 @@ Hover the mouse cursor over any parameter for a tooltip explaining the meaning o

*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.

#### Run GPU generator for machine learning
### Run GPU generator for machine learning

* `examples/CorrectionLoopGraphene` use GPU accelerated PPM to iteratively improve the estimate of molecular geometry by comparing simulated AFM images with reference. This is work-in-progress. Currently, modification of estimate geometry is random (Monte-Carlo), while later we plan to develop a more clever (e.g. Machine-Learned) heuristic for more efficient improvment.
* `examples/Generator` quickly generates a batch of simulated AFM images (resp. 3D data stacks) which can be further used for machine learning. Especially in connection with (https://github.com/SINGROUP/ASD-AFM).

## Making ppafm platform-independent.
## Flavors of PPM

We propose to use [Docker](https://docs.docker.com/get-docker/) to make the code platform-independent.
Since 2014 PPM developed into the toolbox of various methodologies adjusted for a particular use case.

Here are the steps to build and run the ppafm Docker container:
1. **CPU version:** - Original implementation using Python & C/C++. It can simulate a typical AFM experiment (3D stack of AFM images) in ~1 minute. It is the base version for the development of new features and methodology. All available simulation models are implemented in this version, including:
1. **Point charge electrostatics + Lennard-Jones:** Original fully classical implementation allows the user to set up calculation without any ab-initio input simply by specifying atomic positions, types and charges.
2. **Hartree-potential electrostatics + Lennard-Jones:** Electrostatics is considerably improved by using Hartree potential from DFT calculation (e.g. LOCPOT from VASP) and using the Quadrupole model for CO-tip. We found this crucial to properly simulate polar molecules (e.g. H2O clusters, carboxylic acids, PTCDA) which exhibit strong electrostatic distortions of AFM images. Thanks to implementation using fast Fourier transform (FFT) this improvement does not increase the computational time (still ~1 minute), as long as the input electrostatic field is accessible.
3. **Hartree-potential electrostatics + Density overlap:** Further accuracy improvement is achieved when Pauli repulsion between electron shells of atoms is modeled by the overlap between electron density of tip and sample. This repulsive term replaces the repulsive part of Lennard-Jones while the attractive part (C6) remains. This modification considerably improves especially simulation of molecules with electron pairs (-NH-, -OH, =O group), triple bonds and other strongly concentrated electrons. Calculation of the overlap repulsive potential is again accelerated by FFT to achieve minimal computational overhead (2-3 minutes) as long as input densities of tip and sample are available.
2. **GPU version:** - Version specially designed for generation of training data for machine learning. Implementation using `pyOpenCL` can parallelize the evaluation of forcefield and relaxation of probe-particle positions over hundreds or thousands of stream-processors of the graphical accelerator. Further speed-up is achieved by using hardware accelerated trilinear interpolation of 3D textures available in most GPUs. This allows simulating 10-100 AFM experiments per second on consumer-grade desktop GPU.
* GPU version is designed to work in collaboration with machine-learning software for AFM (https://github.com/SINGROUP/ASD-AFM) and use various generators of molecular geometry.
3. **GUI @ GPU** - The speed of GPU implementation also allows to make interactive GUI where AFM images of molecules can be updated on the fly (<<0.1s) on a common laptop computer while the user is editing molecular geometry or parameters of the tip. This provides an invaluable tool especially to experimentalists trying to identify and interpret the structure and configuration of molecules in experiments on-the-fly while running the experiment.

1. Build the image.
### Other branches

```bash
$ docker build -t ppafm:latest .
```
2. Execute the container.
* **master_backup** - Old `master` branch was recently significantly updated and named `main`. For users who miss the old master branch, we provided a backup copy. However, this version is very old and its use is discouraged. If you miss some functionality or are not satisfied with the behavior of current `main` branch please let us know by creating an *issue*.
* **PhotonMap** - implements the latest developments concerning sub-molecular scanning probe combined with Raman spectroscopy (TERS)y and fluorescent spectroscopy (LSTM).
* **complex_tip** - Modification of probe-particle model with 2 particles allows a better fit to experimental results at the cost of additional fitting parameters.

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

## Building the code
## For developers

The ppafm package contains C++ extension that need to be built for the code to run. Pre-built distributions are available on PyPI via pip: https://pypi.org/project/ppafm/. However, if you want to build the pip wheel for yourself from the repository, this can be done in the following way.
If you would like to contribute to the development of ppafm code, please read the [Developer's Guide](https://github.com/Probe-Particle/ppafm/wiki/For-Developers) wiki page.

First install the pre-requisite packages:
```bash
pip install setuptools build
```
**Linux**: Install `g++` and `make`: `sudo apt install g++ make`

**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.
### Further information
- Publications: https://github.com/Probe-Particle/ProbeParticleModel#notable-publications-using-probe-particle-model
- Wiki: https://github.com/Probe-Particle/ProbeParticleModel/wiki
- API documentation: https://ppafm.readthedocs.io/en/latest/

Then clone the repository and execute in the repository root:
```bash
python -m build
```
After the build completes, you should find the built wheel under `dist`.

### Notable publications using Probe Particle Model

Expand Down