From 574ca5739c3b1d5ab8cf60fc0d1088a10aadd8fb Mon Sep 17 00:00:00 2001 From: ondrejkrejci Date: Mon, 30 Mar 2026 22:26:52 +0300 Subject: [PATCH 1/8] readme cleanup --- README.md | 39 +++------------------------------------ 1 file changed, 3 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 71f3f40a..c5c48b0b 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ The Python package is named as `ppafm`. ## Documentation +* [Wiki](https://github.com/Probe-Particle/ProbeParticleModel/wiki) * [readthedocs](https://ppafm.readthedocs.io/en/latest/?badge=latest) * Auto-generated: * [DeepWiki](https://deepwiki.com/Probe-Particle/ppafm) @@ -25,7 +26,7 @@ The standard way of installing `ppafm` is: pip install ppafm ``` -This should install the package and all its dependencies. +This should install the package and all its dependencies including **CPU** and **GPU** version and fully working CLI: The most up-to-date installation guide can be found on the [dedicated wiki page](https://github.com/Probe-Particle/ppafm/wiki/Install-ppafm). @@ -73,46 +74,11 @@ Currently, modification of estimate geometry is random (Monte-Carlo), while late * `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). -## ppafm simulation models and implementations - -Since 2014 ppafm developed into the toolbox of various methodologies adjusted for a particular use case. - -1. **CPU version:** - Original implementation using Python & C/C++. -It can simulate a typical AFM experiment (3D stack of AFM images) in a matter of a few minutes. -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 by specifying atomic positions, types and (optionally) charges. - 1. **Hartree-potential electrostatics + Lennard-Jones:** Electrostatics is considerably improved by using Hartree potential from DFT calculation 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. - 1. **Hartree-potential electrostatics + Density overlap:** Further accuracy improvement is achieved when Pauli repulsion between electron shells of atoms is modelled 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 the simulation of molecules with electron pairs (-NH-, -OH, =O group), triple bonds and other strongly concentrated electrons. -1. **GPU version:** - Version specially designed for the 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. -The 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._ -1. **GUI @ GPU** - The speed of GPU implementation enables 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 for experimentalists trying to identify and interpret the structure and configuration of molecules in experiments on the fly while running the experiment. - -## Other branches - -* **master_backup** is the old `master` branch that 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. -* **PhotonMap** implements the latest developments concerning sub-molecular scanning probes combined with Raman spectroscopy (TERS) and fluorescent spectroscopy (LSTM). -* **complex_tip** is a modification of the Probe-Particle Model with 2 particles that allows a better fit to experimental results at the cost of additional fitting parameters. - - ## For contributors If you miss some functionality or have discovered issues with the latest release - let us know by creating [an issue](https://github.com/Probe-Particle/ppafm/issues/new). If you would like to contribute to the development of the ppafm code, please read the [Developer's Guide](https://github.com/Probe-Particle/ppafm/wiki/For-Developers) wiki page. Small improvements in the documentation or minor bug fixes are always welcome. -## Further information -- Wiki: https://github.com/Probe-Particle/ProbeParticleModel/wiki -- Python API documentation: https://ppafm.readthedocs.io/en/latest/ - ## Publications describing the Probe-Particle Model If you have used `ppafm` in your research, please cite the following articles: @@ -122,3 +88,4 @@ If you have used `ppafm` in your research, please cite the following articles: ## License MIT + From f14cca7640e23e98d59b412d6b5bab5f7fcb66e8 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 30 Mar 2026 19:30:03 +0000 Subject: [PATCH 2/8] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index c5c48b0b..33dfe3bc 100644 --- a/README.md +++ b/README.md @@ -88,4 +88,3 @@ If you have used `ppafm` in your research, please cite the following articles: ## License MIT - From 7ad074a78c251e8a3077a4a654ad19d72721da72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Krej=C4=8D=C3=AD?= Date: Tue, 31 Mar 2026 09:51:31 +0300 Subject: [PATCH 3/8] Clarify GPU support and GUI installation in README Updated README to clarify GPU version and installation requirements. --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 33dfe3bc..3d34521a 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ The standard way of installing `ppafm` is: pip install ppafm ``` -This should install the package and all its dependencies including **CPU** and **GPU** version and fully working CLI: +This should install the package and all its dependencies including **CPU** version and fully working CLI: The most up-to-date installation guide can be found on the [dedicated wiki page](https://github.com/Probe-Particle/ppafm/wiki/Install-ppafm). @@ -42,11 +42,12 @@ ppafm-generate-ljff -h For more information, please consult the [dedicated page](https://github.com/Probe-Particle/ppafm/wiki/Command-line-interface) on the command line interface of `ppafm`. -## Graphical User Interface (GUI) -The package comes with a convenient graphical user interface. -Unlike CLI, this interface needs to be explicitly enabled during the installation. +## GPU version and Graphical User Interface (GUI) +The package comes with a **GPU** speedup version and convenient graphical user interface. +Unlike CLI, these needs to be explicitly enabled during the installation. To enable it, check the [dedicated section](https://github.com/Probe-Particle/ppafm/wiki/Install-ppafm#enable-gpugui-support) on the [Install ppafm](https://github.com/Probe-Particle/ppafm/wiki/Install-ppafm#enable-gpugui-support) wiki page. To know more about the GUI interface, please consult the [ppafm GUI](https://github.com/Probe-Particle/ppafm/wiki/PPAFM-GUI) wiki page. +Additional information about the **GPU** version can be found [bellow](https://github.com/Probe-Particle/ppafm?tab=readme-ov-file#run-gpu-generator-for-machine-learning), at [models](https://github.com/Probe-Particle/ppafm/wiki#ppafm-simulation-models-and-implementations) and [models differences](https://github.com/Probe-Particle/ppafm/wiki/Differences-between-the-CPU-and-GPU-implementations) wiki pages. ## Usage examples @@ -88,3 +89,4 @@ If you have used `ppafm` in your research, please cite the following articles: ## License MIT + From 7347b3514d3cdd8090dfe09ac772838a47f0a850 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 31 Mar 2026 06:51:45 +0000 Subject: [PATCH 4/8] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 3d34521a..c49d3cd7 100644 --- a/README.md +++ b/README.md @@ -89,4 +89,3 @@ If you have used `ppafm` in your research, please cite the following articles: ## License MIT - From cbf5a9693665fd7c4ead3f9ccd99c38700dd2e95 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Krej=C4=8D=C3=AD?= Date: Tue, 31 Mar 2026 13:21:43 +0300 Subject: [PATCH 5/8] Revise GPU version information in README Updated links and descriptions related to the GPU version and its usage. --- README.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/README.md b/README.md index c49d3cd7..ad705643 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ The package comes with a **GPU** speedup version and convenient graphical user i Unlike CLI, these needs to be explicitly enabled during the installation. To enable it, check the [dedicated section](https://github.com/Probe-Particle/ppafm/wiki/Install-ppafm#enable-gpugui-support) on the [Install ppafm](https://github.com/Probe-Particle/ppafm/wiki/Install-ppafm#enable-gpugui-support) wiki page. To know more about the GUI interface, please consult the [ppafm GUI](https://github.com/Probe-Particle/ppafm/wiki/PPAFM-GUI) wiki page. -Additional information about the **GPU** version can be found [bellow](https://github.com/Probe-Particle/ppafm?tab=readme-ov-file#run-gpu-generator-for-machine-learning), at [models](https://github.com/Probe-Particle/ppafm/wiki#ppafm-simulation-models-and-implementations) and [models differences](https://github.com/Probe-Particle/ppafm/wiki/Differences-between-the-CPU-and-GPU-implementations) wiki pages. +Additional information about the **GPU** version can be found [bellow, when describing python API](https://github.com/Probe-Particle/ppafm?tab=readme-ov-file#usage-examples), at [models](https://github.com/Probe-Particle/ppafm/wiki#ppafm-simulation-models-and-implementations) and [models differences](https://github.com/Probe-Particle/ppafm/wiki/Differences-between-the-CPU-and-GPU-implementations) wiki pages. ## Usage examples @@ -67,14 +67,6 @@ Once the simulation is finished, several files and folders will be created. See also the tutorial for using the Python API for [running GPU-accelerated simulations](https://ppafm.readthedocs.io/en/latest/tutorials/afmulator-tutorial.html). -### Run GPU generator for machine learning - -* `examples/CorrectionLoopGraphene` use GPU accelerated ppafm to iteratively improve the estimate of molecular geometry by comparing simulated AFM images with reference. -This is a 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 improvement. -* `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). - ## For contributors If you miss some functionality or have discovered issues with the latest release - let us know by creating [an issue](https://github.com/Probe-Particle/ppafm/issues/new). If you would like to contribute to the development of the ppafm code, please read the [Developer's Guide](https://github.com/Probe-Particle/ppafm/wiki/For-Developers) wiki page. From 95ba02b4cac40f388317a60c633d52a3178e0b0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Krej=C4=8D=C3=AD?= Date: Tue, 31 Mar 2026 13:22:50 +0300 Subject: [PATCH 6/8] Create README.md for CorrectionLoopGraphene example Added initial README for CorrectionLoopGraphene example. --- examples/CorrectionLoopGraphene/README.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 examples/CorrectionLoopGraphene/README.md diff --git a/examples/CorrectionLoopGraphene/README.md b/examples/CorrectionLoopGraphene/README.md new file mode 100644 index 00000000..fb61f284 --- /dev/null +++ b/examples/CorrectionLoopGraphene/README.md @@ -0,0 +1,3 @@ +* `examples/CorrectionLoopGraphene` use GPU accelerated ppafm to iteratively improve the estimate of molecular geometry by comparing simulated AFM images with reference. +This is a 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 improvement. From 9e0657eefa5b2caed5767787556ee466ec840360 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Krej=C4=8D=C3=AD?= Date: Tue, 31 Mar 2026 13:25:18 +0300 Subject: [PATCH 7/8] Fix typo in README.md from 'bellow' to 'below' --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ad705643..20d964a2 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ The package comes with a **GPU** speedup version and convenient graphical user i Unlike CLI, these needs to be explicitly enabled during the installation. To enable it, check the [dedicated section](https://github.com/Probe-Particle/ppafm/wiki/Install-ppafm#enable-gpugui-support) on the [Install ppafm](https://github.com/Probe-Particle/ppafm/wiki/Install-ppafm#enable-gpugui-support) wiki page. To know more about the GUI interface, please consult the [ppafm GUI](https://github.com/Probe-Particle/ppafm/wiki/PPAFM-GUI) wiki page. -Additional information about the **GPU** version can be found [bellow, when describing python API](https://github.com/Probe-Particle/ppafm?tab=readme-ov-file#usage-examples), at [models](https://github.com/Probe-Particle/ppafm/wiki#ppafm-simulation-models-and-implementations) and [models differences](https://github.com/Probe-Particle/ppafm/wiki/Differences-between-the-CPU-and-GPU-implementations) wiki pages. +Additional information about the **GPU** version can be found [below, when describing python API](https://github.com/Probe-Particle/ppafm?tab=readme-ov-file#usage-examples), at [models](https://github.com/Probe-Particle/ppafm/wiki#ppafm-simulation-models-and-implementations) and [models differences](https://github.com/Probe-Particle/ppafm/wiki/Differences-between-the-CPU-and-GPU-implementations) wiki pages. ## Usage examples From eaf3ecf74c46ba4f11c7e0fbf4a7b9b08189784d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Krej=C4=8D=C3=AD?= Date: Tue, 31 Mar 2026 14:54:05 +0300 Subject: [PATCH 8/8] Update GPU version information in README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 20d964a2..a2b45ff2 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ The package comes with a **GPU** speedup version and convenient graphical user i Unlike CLI, these needs to be explicitly enabled during the installation. To enable it, check the [dedicated section](https://github.com/Probe-Particle/ppafm/wiki/Install-ppafm#enable-gpugui-support) on the [Install ppafm](https://github.com/Probe-Particle/ppafm/wiki/Install-ppafm#enable-gpugui-support) wiki page. To know more about the GUI interface, please consult the [ppafm GUI](https://github.com/Probe-Particle/ppafm/wiki/PPAFM-GUI) wiki page. -Additional information about the **GPU** version can be found [below, when describing python API](https://github.com/Probe-Particle/ppafm?tab=readme-ov-file#usage-examples), at [models](https://github.com/Probe-Particle/ppafm/wiki#ppafm-simulation-models-and-implementations) and [models differences](https://github.com/Probe-Particle/ppafm/wiki/Differences-between-the-CPU-and-GPU-implementations) wiki pages. +Additional information about the **GPU** version can be found [on readthedocs tutorial](https://ppafm.readthedocs.io/en/latest/tutorials/afmulator-tutorial.html), at [models](https://github.com/Probe-Particle/ppafm/wiki#ppafm-simulation-models-and-implementations) and [models differences](https://github.com/Probe-Particle/ppafm/wiki/Differences-between-the-CPU-and-GPU-implementations) wiki pages. ## Usage examples