Skip to content

Command line interface

Jump to bottom
NikoOinonen edited this page Aug 5, 2024 · 3 revisions

Content:

Essential and Executable

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:

ppafm-gui

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)

ppafm-generate-ljff

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'

ppafm-generate-elff

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)

ppafm-generate-elff-point-charges

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

ppafm-relaxed-scan

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

ppafm-plot-results

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

CLI

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 as ppafm-generate-elff

  • generateElFF_point_charges.py - the same as ppafm-generate-elff-point-charges

  • generateLJFF.py - the same as ppafm-generate-ljff

  • generateTraining_PVE.py - generate training data for machine-learning using Density-Overlap model

  • plot_results.py - the same as ppafm-plot-results

  • relaxed_scan.py - the same as ppafm-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.

Utilities

Additional scripts can be found in ppafm/cli/utilities

  • cube2xsf.py - Converts .cube file to .xsf file (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 .xsf or .cube file and 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 .dat and put them into .npy and plot them using imshow.

  • xsf2png.py - takes arbitrary 3D grid in .xsf format and plot it slice-by-slice into .png images

  • 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 .xyz file with geometry and numbered each atom separately and new atomtypes.ini file with fitted elements. After that and adjust params.ini with the original grid vectors, one can use the new .xyz file for creation of more precise Lennard-Jones force-field.

GUI

Various Graphic User interfaces can be found in ppamf/cli/gui:

Fitting

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.

Home Page Table of Contents:

Probe Particle Model

Other important Wiki pages:

Install ppafm

PPAFM-GUI

Forces

Command line interface

For Developers

Setting simulation parameters

Technical-details

Complex tip alias double probe particle

double-electrostatics

Omitted KPFM approximations

Related codes:

PPSTM

Clone this wiki locally