Setting simulation parameters

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

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