Setting simulation parameters

Overview:

General notes

Simulation parameters to ppafm can be set in multiple ways:

Using command line arguments of the scripts.
Using the params.ini/params.toml file put in the simulation folder. If no such file is provided, the defaults are used (see PpafmParameters class).
- Any line in the params.ini file can be commented on by using # (ideally with space).

We strongly recommend keeping all the parameters for the calculations (mainly multipole = tip, sigma, PBC and the second multipole = tip_base) in the params.ini instead of using flags.

Tables

In the table below we list all accepted parameters.

The parameter types stand for

bool: Boolean (True or False)
int: Integer number
real: Real number
string: String of text
list(type): A list of values of the given type.

Force-field grid parameters

Parameter	Default value	Type	Units	Description
PBC	`True`	`bool`	-	To use or not the periodic boundary conditions for calculating the grid force field. (note: electrostatic potential from DFT is always considered as PBC)
nPBC	`[1, 1, 1]`	`list(int)`	-	The number of cell replicas along each lattice vector if `PBC` is `True`.
gridN	`[-1, -1, -1]`	`list(int)`	-	The number of sampling points along each lattice vector for grid force field, if not taken from `XSF` or `cube` input file. When <0 approximate spacing of 0.1 Ångström is used for calculating `gridN` automatically
gridO	`[0.0, 0.0, 0.0]`	`list(real)`	-	TBC
gridA	`[20.0, 0.0, 0.0 ]`	`list(real)`	Ångström	The lattice vector `a` of the grid force field. Should be in format `[ax,ay,0.0]`.
gridB	`[0.0, 20.0, 0.0 ]`	`list(real)`	Ångström	The lattice vector `b` of the grid force field. Should be in format `[bx,by,0.0]`.
gridC	`[0, 0, 20.0 ]`	`list(real)`	Ångström	The lattice vector `c` of the grid force field. Should be in the format `[0.0,0.0,cz]`.
FFgrid0	`[ -1.0, -1.0, -1.0 ]`	`list(real)`	Ångström	Force-field grid origin used in the GUI/OpenCL. Usually does not need to be specified manually.
FFgridA	`[ -1.0, -1.0, -1.0 ]`	`list(real)`	Ångström	Force-field grid lattice vector `a` used in the GUI/OpenCL. Usually does not need to be specified manually.
FFgridB	`[ -1.0, -1.0, -1.0 ]`	`list(real)`	Ångström	Force-field grid lattice vector `b` used in the GUI/OpenCL. Usually does not need to be specified manually.
FFgridC	`[ -1.0, -1.0, -1.0 ]`	`list(real)`	Ångström	Force-field grid lattice vector `c` used in the GUI/OpenCL. Usually does not need to be specified manually.

Force-field model parameters

Parameter	Default value	Type	Units	Description
ffModel	`LJ`	`string`	-	London+Pauli potential model `Morse` or `LJ`, or `vdW` for the Full-density based model.
vdWDampKind	`2`	`int`	-	Kind of damping function used when `ffModel` is `vdW` (together with density-overlap)
Apauli	`18.0`	`real`	Ångström	Amplitude for density-overlap `E_pauli = Apauli(rho_tip rho_sample ) ^ Bpauli`
Bpauli	`1.0`	`real`	?	Exponent for density-overlap E_pauli = Apauli (rho_tip*rho_sample) ^ Bpauli density-overlap use just 'vdW'
Rcore	`0.7`	`real`	Ångström	Radius of core-density subtracted from input density of grid to ensure the neutrality of atoms (simulate charge of nuclei or neutral atom)

Tip Parameters

Parameter	Default value	Type	Units	Description
probeType	`O`	`string`	-	Type of atom that is set to the probe particle (oxygen by default).
charge	`0.0`	`real`	e	Charge of the probe particle (if tip density is not provided). For CO tip we normally use `<-0.1,-0.05>`
r0Probe	`[0.0, 0.0, 4.0]`	`list(real)`	Ångström	The equilibrium position of the probe particle under the tip relative to the anchor point. In the Cu-CO tip, the oxygen is normally 3 Ångström below the last Cu atom.
tip	`s`	`string`	-	tip electrostatics model if no tip-charge density is provided, typical choice s,pz,dz2, for other see here. dz2 is the most common choice for the CO tip, with the quadrupole moment being then `Qsigma*2` .
sigma	`0.7`	`real`	Ångström	The radius of Gaussian tip charge density when no tip-charge density is provided.
stiffness	`[-1.0, -1.0, -1.0]`	`list(real)`	N/m	The stiffness of the probe particle x,y, and radial, if negative klat,krad is used.
klat	`0.5`	`real`	N/m	The lateral stiffness (tilt; used if stiffness vector is <0). Normally `<0.2,0.25>` for the CO tip.
krad	`20.00`	`real`	N/m	The radial stiffness (bond length; used if stiffness vector is <0) ?

Scan Parameters

Parameter	Default value	Type	Units	Description
scanStep	`[0.10, 0.10, 0.10]`	`list(real)`	Ångström	Sampling step of 3D volume of resulting AFM Force data grid.
scanMin	`[0.0, 0.0, 5.0]`	`list(real)`	Ångström	The start of scanning volume grid relative to sample coordinates. Detailed description here. Normally you start max(sample_atom)_z+rProbe_z + 2.8 or even higher.
scanMax	`[20.0, 20.0, 8.0 ]`	`list(real)`	Ångström	The end of scanning volume grid relative to sample coordinates.
scanTilt	`[0.0, 0.0, -0.1]`	`list(real)`	Ångström	Tip oscillation direction when `tiltedScan==True`.
tiltedScan	`False`	`bool`	-	Optionally, the tip can oscillate in a tilted direction (e.g. in Lateral-mode AFM).

Conversion parameters Fz->df

The Giessibl's Formula is used to perform the conversion.

Parameter	Default value	Type	Units	Description
kCantilever	`1800.0`	`real`	N/m	Cantilever stiffness
f0Cantilever	`30300.0`	`real`	Hz	Cantilever base frequency
Amplitude	`1.0`	`real`	Ångström	Peak-to-peak amplitude

Plotting / Conversions parameters

Parameter	Default value	Type	Units	Description
plotSliceFrom	`16`	`int`	-	The first z-slice for plotting from computed df-grid.
plotSliceTo	`22`	`int`	-	The last z-slice for plottig from computed df-grid.
plotSliceBy	`1`	`int`	-	Plotting density, e.g. if 1 plot every slice, if 2 plot every 2nd slice etc.
imageInterpolation	`bicubic`	`string`	-	Interpolation used in matplotlib.imshow() for plotting df-images.
colorscale	`gray`	`string`	-	The color scale used in matplotlib.imshow() for ploting df-images.
colorscale_kpfm	`seismic`	`string`	-	The colorscale used in matplotlib.imshow() for plotting kpfm-images.
ddisp	`0.05`	`real`	Ångström	The displacement used for computing the probe particle vibration modes for IETS.
aMorse	`-1.6`	`real`	1/A	Exponent for morse potential `E_Morse=E0(1-exp(aMorsenorm(r-r_0)))^2`.

KPFM parameters.

Parameter	Default value	Type	Units	Description
Rtip	`30.0`	`real`	Ångström	Radius of the metallic apex of the tip used to calculate the mesoscopic cuadratic term of the CPD in the KPFM mode. This term is calculated acording to: https://doi.org/10.1007/s100510050219
permit	`0.00552634959`	`real`	(e^2)/(eV·Ångström)	Vacuum permittivity.
Vrange	`0.0`	`real`	Volts	Range of voltages within which the LCPD parabolas are calculated in KPFM. The default 0.0 means implies that no KPFM will be performed.
Vbias	`0.0`	`real`	Volts	TBC

Additional notes

Note on parameters in `params.ini`:

Multipole (dipole, quadrupole) charge is not multipole moment. Dipole moment can be calculated as charge * sigma [e*Å]; quadrupole moment is charge * sigmaˆ2 [e*Åˆ2].
CO quadrupole charge varies from -0.05 to -0.30 (using sigma = 0.71 or 0.7) depending on the experiment.
Stiffness of 0.24-0.25 N/m (stiffness 0.24 0.24 20.0) is mostly used for CO-tips (Nat. Commun. 7, 11560 (2016)).
gridN can be assigned automatically (commented or missing in params.ini) with a division of 0.1 A.
The scanning height is referred to the position of the last atom of the metal tip-base. The equilibrium position of the PP is then by r0Probe-z component lower. (4Å is default; e.g. in Nano Lett. 16, pp 1974–1980 (2016) and ACS Nano 12, 5274−5283 (2018) 3Å were used.) More on this is explained in Scan definitions
If in IETS you get many negative frequencies, try to change the scanning grid or gridN. There are always a few negative energies, especially at really close distances.
PBC affects only calculations of LJ potential. The code is always periodic from the nature of its design: PBC False means nPBC 0 0 0 ; PBC True means read nPBC parameter.
nPBC affects only calculations of LJ potential -- how many cells around the original one are used for LJ force-field calculation. The last number plays no role. The total amount of cells is given by (nPBC(x).2+1).(nPBC(y).2+1) and the final geometry is always centered in the original geometry as given in the input file. nPBC 0 0 0 means only the original cell; nPBC 1 1 1 3x3 cells around the original one and so on. See the image below for a graphical representation.

Cell definitions

The code expects, that your system is in the cell starting in 0,0,0, given by the 3 lattice vectors - each of them is a row: 1st is gridA; 2nd gridB and the last one is gridC (normally 0. 0. height of cell ) - basically the same strategy as in ASE:

For example, if your system has the centre of mass at 0,0,0 you can run into problems (sometimes problems with FHI-aims).
Or if your geometry is below 0 in z then the atoms are not captured properly, regardless of stated PBC or nPBC.
it is also good practice to leave enough space above the top-most atoms in the z direction: 15 Angstrom is pretty safe.
which leads to another good practice to shift the system to a lower part of your cell.

If you are using Hartree potential (xsf or cube files); Then you do not need to care about these - the points of the grid are the same as in those files with potential.

If you want better (more dense) spacing or larger cell, then you need to redo your DFT calculations with adjusted parameters.

If not -- you have to specify: gridA, gridB and gridC by hand (default values do not make any sense):

if you have a system that is periodic in x and y (surface) then adjust gridA and gridB with the exact lattice vector; gridC needs to have enough space about the atoms (as mentioned above).
In reality, a probe particle cannot approach the sample closer than ~3.5-4.0 Å (because the van der Waals radius of most atoms is typically 1.5-2.0 Å). For this reason, we do not want to sample a region closer than 1.0-2.0 Å to the molecule where the Pauli repulsion would be extremely high, and where quantum mechanical interactions (chemical force) would be important.
The region of scanning (scanMax, scanMin) is defined as the position of the tip apex (not the probe particle). This means that the probe particle can be outside the sampled forcefield grid. The real position of the probe particle (i.e., the point where the force is interpolated from the forcefield grid) is shifted from this position by a considerable distance (~4.0 Å). For example, at the beginning of each tip approach, the shift is r0Probe (relaxation is negligible).

Scan definitions

The estimation of appropriate scan height for forces. Be aware that for the frequency shift we need to account for the oscillation, so this height corresponds to the closest point of the oscillation. You can say that the real scanning distance is the closest point of the oscillation + A/2, where A (peak-to-peak amplitude), when describing the tip-height. However, from the computational point of view it makes more sense to refer to the closest point of oscillation in description, while clearly stating it. Finally, the real tip-sample distance is unknown, as any parametrization we provide, cannot ensure the exact match of short-range F(z) forces. This is even more pronounced, when the long-range forces are in the experiment.

Further outputs from `ppafm-plot-results`

The z-component of the force acting on the tip can be plotted into Fz_???.png files by using the --Fz flag. (Second electrostatics is not taken into account in the plotted force!)

The IETS signal (as calculated in PRL 113, 226101 (2014), that means using variation of CO frustrated translation peak energy approximation, see PRL 119, 166001 (2017) for more details) will be calculated and plotted via applying --iets=M,V,W flag, where: M - PP mass [a.u.]; V - bias offset [eV]; W - peak width [eV].

Both of these quantities can be printed into *.xyz files by means of the --WSxM flag.

Optional flags:

--cbar: adds a color bar with absolute numbers to the *.png images.
--atoms: adds a position of atoms saved in input_plot.xyz into the plotted *.png images.
--bonds: adds also lines in between close-by atoms ...
--no_int: allows for plotting of images without any interpolation between pixels

You can also speed up the calculations and spare approx. 1/2 of your disc memory by using --npy behind all the scripts. It will save all your intermediate data into "machine-readable" *.npy files, which on the other hand are inconvenient for debugging.

There are also other flags, that are connected with other developments. For example, see KPFM approximations here.