Proper documentation for the FDBM (full denity based method) is missing

[mondracek]

Either missing or I was not able to find it. Yes, there is at least the ppafm/examples/pyridineDensOverlap example and ppafm/examples/paper_figure can be used as another example for the GPU version, though it is rather awkward to use ppafm/examples/paper_figure/run_simulation.py as a template for other simulations: It is too much tuned to generate the one specific figure.

Anyway, my problems is that while I believed I was able to launch full-density based simulations using those examples as a template, once i ran into difficulties, I could never be sure whether there was a bug in the code or I just made a mistake in the way I was trying to use it.

This issue began to bother me in my attemtps to simulate a cyclodextrin molecule, in which I have arrived to issue #257. I am now pretty sure that the source of that specific problem is in the DFT-D3 part, but there may or may not be other issues in the FDBM functionality. If I am to report the problems I encounter, however, I need to know what is supposed to work.

[NikoOinonen]

Yes, the documentation is too sparse. I have been meaning to write proper explanations of everything, but never got around to it. There is some limited documentation of the Python API:

• https://ppafm.readthedocs.io/en/latest/ppafm.ocl.html#module-ppafm.ocl.AFMulator
• https://ppafm.readthedocs.io/en/latest/ppafm.ocl.html#ppafm.ocl.field.ForceField_LJC.calc_force_fdbm

[ondrejkrejci]

I have added the FDBM part of the literature on our Main wiki page, once somebody has a time, please put there right citations. Thank you!

[NikoOinonen]

I added there a citation to the original paper.

[NikoOinonen]

I'm looking at the wiki, and I think we in general don't have a good description of the different force fields that can be used. We probably should make a page or a section that lists and describes all of the different force-field models in a similar way as we did in the paper. Maybe add a section under the Forces page?

And there should also be clear instructions on what commands to run and what input files are required for each model. I don't know if these should be separate from the theoretical description.

[NikoOinonen]

I added a new section to the Forces wiki page about the different force field models and how to use them with the CLI. There is still no documentation on the OpenCL version, but I think it would better fit the API doc page and I intend to make those better some time soon (#264).

@ondrejkrejci @mondracek could you check out that wiki page if it makes sense or if something should be added or organized differently.

Edit: I also wonder, is the Morse force field functional, and do we have some example of it? I left it out of the list because I'm not sure if we intend to support it.

[NikoOinonen]

Also relevant to this issue, there is now a tutorial on the Python API for the OpenCL version of the code at https://ppafm.readthedocs.io/en/latest/tutorials/index.html.

[ondrejkrejci]

@NikoOinonen @mondracek - I have updated the forces wiki. If you recheck it quickly, I think that we can close this issue.

@NikoOinonen - great job with readthedocs, by quick reading I think that it is better explained, then in the wiki.

[NikoOinonen]

I made a couple of small adjustments to the wiki page. Everything looks good from my side.

[yakutovicha]

@mondracek will do the final check and potentially close the issue.

[mondracek]

@ondrejkrejci , @NikoOinonen , thanks for the job. I looked at the Wiki section about forces and I think it's good. I just added one sentence to the section about FDBM, emphasizing the need of the same cell geometry for the tip and the sample.

[NikoOinonen]

@mondracek

I just added one sentence to the section about FDBM, emphasizing the need of the same cell geometry for the tip and the sample.

This limitation actually does not exists in the OpenCL version, because it can resample the tip cell to match whatever force-field grid you want. I haven't implemented this in the CPU version, but I could maybe do it at some point if it's something that would be useful to you.

[yakutovicha]

The documentation on this topic can be found here.