Command line interface
content:
The installed code is equipped with these scripts, that are essential for running a simulation of fm-nc-AFM experiment with flexible tip apex, and that can be runned in terminal/PowerShell directly:
The do-it-all script, which can create the df (frequency difference) constant height image nearly instantaneously using calculations on GPU, while calculating the force fields, relaxation, and force -> df conversion in the background. It is the most convenient way to run the simulations for CO-tip and couple of other examples with its own wiki page here, while some of the advanced simulations cannot be run through it. The possible options for this script are:
-h, --help show this help message and exit
-d DEVICE, --device DEVICE
Choose OpenCL device.
-l, --list-devices List available devices and exit.
-v VERBOSITY, --verbosity VERBOSITY
Set verbosity level (0-2)
The first and essential script for the simulations, which translates the geometry of sample provided by means of *.xyz, *.xsf, *.cube and *.in files, into a Lennard-Jones force field, which captures the interaction of a non-reactive (Van der Waals) particle above the simulated sample surface. The script always has to be provided with geometry via: -i YOUR_GEOMETRY_FILE. Important if you calculated electrostatics through Hartree potential, always provide the same *.cube or *.xsf file as you use for generation of the electrostatic field, otherwise the calculation can be wrong. The possible options for this script are:
-h, --help show this help message and exit
-i INPUT, --input=INPUT
Input file, supported formats are: .xyz .cube,.xsf
-f DATA_FORMAT, --data_format=DATA_FORMAT
Specify the output format of the vector and scalar
field. Supported formats are: xsf,npy
--noPBC pbc False
-E, --energy Compute potential energy (not just Force)
--ffModel=FFMODEL kind of potential 'LJ','Morse','vdW'
Creates an electrostatic field around the sample, if the Hartree potential is provided in *.xsf or *.cube format. This is important, when you consider that most of the flexible tip apices are charged, or they are different multipoles, which can change the shape of the visualized sample surface. The calculated force field is always periodic. The script always has to be provided with a Hartree potential via: -i YOUR_HARTREE_POTENTIAL_FILE. The possible options for this script are:
-h, --help show this help message and exit
-i INPUT, --input=INPUT
format of input file
--tip_dens=TIP_DENS tip denisty file (.xsf)
--doDensity do density overlap
--Rcore=RCORE Width of nuclear charge density blob to achieve charge
neutrality [Angstroem]
-t TIP, --tip=TIP tip model (multipole) {s,pz,dz2,..}
--tilt=TILT tilt of tip electrostatic field (radians)
-E, --energy pbc False
--noPBC pbc False
-w SIGMA, --sigma=SIGMA
gaussian width for convolution in Electrostatics
[Angstroem]
-f DATA_FORMAT, --data_format=DATA_FORMAT
Specify the output format of the vector and scalar
field. Supported formats are: xsf,npy
--KPFM_tip=KPFM_TIP read tip density under bias
--KPFM_sample=KPFM_SAMPLE
read sample hartree under bias
--Vref=VREF Field under the KPFM dens. and Vh was calculated in
V/Ang
--z0=Z0 heigth of the topmost layer of metallic substrate for
E to V conversion (Ang)
Creates an electrostatic field around the sample, if the (approximate projection of) atomic charges are provided in the *.xyz file as the last column . This is important, when you consider that most of the flexible tip apices are charged, or they are different multipoles, which can change the shape of the visualized sample surface. The calculated force-field is periodic unless specified otherwise with the --noPBC option. The script always has to be provided with the geometry and charges via: -i YOUR_XYZ_FILE_WITH_CHARGES. The possible options for this script are:
-h, --help show this help message and exit
-i INPUT, --input=INPUT
format of input file
-t TIP, --tip=TIP tip model (multipole)
-E, --energy pbc False
--noPBC pbc False
-f DATA_FORMAT, --data_format=DATA_FORMAT
Specify the output format of the vector and scalar
field. Supported formats are: xsf,npy
The essential script for the simulations, which loads the calculated force fields - if you consider zero charge, then only the Lennard-Jones force-field is loaded and considered - and relax the probe particle (PP) according to the force fields of the sample and the tip. (Additional information about the forces is provided here). The output are forces acting on the tip in the z direction. This is the second step of the simulation, after creating the force field. The possible options for this script are:
-h, --help show this help message and exit
-k KLAT, --klat=KLAT tip stiffenss [N/m]
--krange=KRANGE tip stiffenss range (min,max,n) [N/m]
-q CHARGE, --charge=CHARGE
tip charge [e]
--qrange=QRANGE tip charge range (min,max,n) [e]
-b, --boltzmann calculate forces with boltzmann particle
--bI calculate current between boltzmann particle and tip
--pos save probe particle positions
--disp save probe particle displacements
--vib=VIB map PP vibration eigenmodes; 0-just eigenvals; 1-3
eigenvecs
--tipspline=TIPSPLINE
file where spline is stored
--rotate=ROTATE rotates sampling in xy-plane
-f DATA_FORMAT, --data_format=DATA_FORMAT
Specify the input/output format of the vector and
scalar field. Supported formats are: xsf,npy
-V VBIAS, --Vbias=VBIAS
Aplied bias [V]
--Vrange=VRANGE Bias range [V]
--pol_t=POL_T scaling factor for tip polarization
--pol_s=POL_S scaling factor for sample polarization
The essential script and last part for the simulation which loads the calculated forces acting on the tip in the z direction and if --df flag is used, it calculates the df from it and plot it into images of different heights. On top of it, it can also print it in various formats, or plot/print other things, that are connected with fm-nc-AFM measurements. The possible options for this script are:
-h, --help show this help message and exit
-k KLAT, --klat=KLAT tip stiffness [N/m]
--krange=KRANGE tip stiffenss range (min,max,n) [N/m]
-q Q tip charge [e]
--qrange=QRANGE tip charge range (min,max,n) [e]
-a A oscilation amplitude [A]
--arange=ARANGE oscilation amplitude range (min,max,n) [A]
--iets=IETS mass [a.u.]; bias offset [eV]; peak width [eV]
-V VBIAS, --Vbias=VBIAS
Aplied field [eV/Ang]
--Vrange=VRANGE set of bias to perform the scan under
--LCPD_maps print LCPD maps
--z0=Z0 heigth of the topmost layer of metallic substrate for
E to V conversion (Ang)
--V0=V0 Empirical LCPD maxima shift due to mesoscopic
workfunction diference
--df plot images for dfz
--save_df save frequency shift as df.xsf
--Laplace plot Laplace-filtered images and save them
--pos save probe particle positions
--atoms plot atoms to images
--bonds plot bonds to images
--cbar plot bonds to images
--WSxM save frequency shift into WsXM *.dat files
--bI plot images for Boltzmann current
-f DATA_FORMAT, --data_format=DATA_FORMAT
Specify the input/output format of the vector and
scalar field. Supported formats are: xsf,npy
--noPBC pbc False
If you compile a version with provided source in ppafm/cli you can find these following scripts, which can be used for some advanced usage:
-
conv_rho.py- Produce Pauli-Forcefield from convolution of tip & sample electron density. It is used with Density Overlap version of the code [Ruben Perez et.al.]. -
generateDFTD3- Generate Grimme DFT-D3 vdW force field using the Becke-Johnson damping function. The generated force field is saved to FFvdW_{x,y,z}. -
generateElFF.py- the same asppafm-generate-elff -
generateElFF_point_charges.py- the same asppafm-generate-elff-point-charges -
generateLJFF.py- the same asppafm-generate-ljff -
generateTraining_PVE.py- generate training data for machine-learning using Density-Overlap model -
plot_results.py- the same asppafm-plot-results -
relaxed_scan.py- the same asppafm-relaxed-scan -
relaxed_scan_PVE.py- do scan with relaxing the PP using force-field composed of 3 components (PVE: P=Pauli from DensityOverlap V=van der Waals from C6/R^6 as atractive part of Lennard-Jones, E=Electrostatics from convolution of Hartree potential and density)
To get additional information about provided script options use: -h flag.
Additional scripts can be found in ppafm/cli/utilities
-
cube2xsf.py- Converts.cubefile to.xsffile (nothing more, nothing less) -
evalFFline.py- Evaluate Lennard-Jones force field along some 1D line over some sample. Prokop Hapala used it to prepare illustrative figures how the model works when you vary charge (for supplementary of paper about electrostatic distortions - Nat. Commun. 7, 11560 (2016)). -
extract_densities.py- Utility to extract 1D electron density cuts rho(z) from CHGCAR.xsf above each atom of sample. This is useful to guess parameters of Density-Overlap model for Pauli, LJ-parameters, or generally rationalize why some atoms are more or less visible at certain height. Recently used to fit the atom sizes of ionic materials (calcite) in J. Phys. Chem. Lett. 2023, 14, 7, 1983–1989. -
fitFz.py- Extract 1D cuts F(z) from a simulated force field and conduct a polynominal fit. Prokop Hapala used it in paper with Nadine van der Heiden & Ingmaer Swart - ACS Nano 2016, 10, 9, 8517–8525. -
plot_Quad.py- load some.xsfor.cube fileand make 2D cut along some Quad with 4 arbitrary corners. Useful for plotting, while also doable in VESTA. -
plotZcurves.py- plot some 1D cuts (e.g. F(z) curves) form arbitrary 3D grid (.xsf, .cube) at points in specified 'curve_points.ini'. -
plot_slices_dat.py- load data from.datand put them into.npyand plot them using imshow. -
xsf2png.py- takes arbitrary 3D grid in.xsfformat and plot it slice-by-slice into.pngimages -
fitPauli.py- Using the extracted densities to fit the size of Lennard-Jones potential for each atom. Recently used to fit the atom sizes of ionic materials (calcite) in J. Phys. Chem. Lett. 2023, 14, 7, 1983–1989. The script create a new.xyzfile with geometry and numbered each atom separately and newatomtypes.inifile with fitted elements. After that and adjustparams.iniwith the original grid vectors, one can use the new.xyzfile for creation of more precise Lennard-Jones force-field.
Various Graphic User interfaces can be found in ppamf/cli/gui:
-
ExpShifter.py- GUI for shifting experimental AFM images (reference data) to compare them with machine-learned predictions. Used by Prokop Hapala & Fedor Urtiev when working on ASD-AFM paper - Sci. Adv. 6, aay6913 (2020) -
ExpShifter_2tips.py- GUI for shifting two experimental AFM images obtained with different tip-apices (like CO and Xe), so they visualize the roughly the same area - used for work on Electrostatic discovery atomic force microscopy paper - ACS Nano 2022, 16, 1, 89–97. -
ppafm_gui.py- the same asppafm-gui -
Viewer.py- GUI to load.xsffiles and view it (brows over slices).
Several other scripts used for fitting to the DFT reference data can be found in ppafm/cli/fitting. These scripts were probably used to fit the parameters for the double probe particle model described here which is slightly described in Supplementary information of this paper - J. Am. Chem. Soc. 2018, 140, 10, 3532–3536:
-
fitting.py- Fit Probe Partilce parameters on DFT reference data. Done by Alixander Yakutovich. -
plot_Line.py-plot line profile. Done by Alixander Yakutovych when he was fitting PPM parameters on DFT reference. -
plotZ.py- plot some 1D figures of frequency shift fitted on reference data. Made by Alixander Yakutovich when fitting PPM params on DFT reference.