A Program for the Calculation of Effective One-Particle Potentials (OPPs)
Dr. Dennis Wiedemann
Technische Universität Berlin
Institut für Chemie, Sekr. C 2
Straße des 17. Juni 135
10623 Berlin, Germany
Phone: +49 30 314-26178
Fax: +49 30 314-79656
E-mail: dennis.wiedemann@chem.tu-berlin.de
Web: http://dennis.wiedemann.name
In the one-particle potential (OPP) approach, every atom is treated as an individual Einstein oscillator subject to Boltzmann statistics in the classical limit. The effective OPP itself represents the potential energy as experienced by an atom at a certain position and allows assessing the viability and activation barriers of migration pathways (see K. N. Trueblood et al., Acta Crystallogr., Sect. A 1996, 52, 770–781).
The OPP V(u) experienced by an atom displaced from its reference position by a vector u can be calculated from a probability-density function (PDF) p(u) adequately describing it, cf. H. Boysen, Z. Kristallogr. 2003, 218, 123–131 (kB: Boltzmann constant, T: temperature, 𝕍: volume element under scrutiny):
Depending on the problem, CalcOPP allows to calculate the effective OPP from a PDF sampled in 2D/3D by JANA2006, to reformat 2D PDF input, and to handle the associated uncertainty maps. CalcOPP can also process MEM-reconstructed scatterer densities ϱ(u) sampled using Dysnomia—under certain additional conditions (ϱloc: local density extremum):
A PDF has to be non-negative, Lebesgue-integrable, and normalized to an integral of unity over the whole space.
Although it is far from mathematically rigorous, the following rationale suggests that a ratio of scattering-length densities within carefully chosen limits has the properties of a probability-density ratio:
- Adequacy: If the negative/positive scattering-length density is solely generated by the unique atom under scrutiny, the former is an adequate measure for the distribution of the latter. In some other cases (another static negative/positive scatterer), it is adequate if the scope is limited to areas accessible for the atom (i.e., the environment of the migration pathways).
- Non-Negativity: Only non-negative ratios (both probability-density values either negative or positive) are taken into account.
- Integrability: Sampled scattering-length and electron densities are Lebesgue-integrable.
- Normalization: For ratios of probability-density values, normalization is unnecessary (the normalizing constant cancels).
CalcOPP can estimate the OPP uncertainty if a suitable PDF uncertainty map (as calculated by JANA2006 using a Monte-Carlo method) is provided. Unfortunately, some problems prohibit the use of common progression approaches:
- In areas of high probability density (e.g., the atomic positions), correlations between uncertainties of maximal and local probability density occur, leading to an overestimation of OPP uncertainty.
- In areas of low probability density (e.g., the bottleneck positions), relative uncertainties may be far too high to warrant a treatment via Taylor series, let alone linear approximation.
- The value distributions depend on the problem but are, in general, neither normal nor log-normal.
- The range of uncertainty for the PDF is supposed to be symmetric around the central value, while the one for the (logarithmic) OPP is asymmetric.
As CalcOPP is unaware of the covariance of maximal and local probability density, it cannot overcome the first problem; keep this in mind if you evaluate the OPP near its minima. To cope with the other problems, CalcOPP does not propagate uncertainties but calculates the OPP differences Δ±V(u) from the upper and lower PDF uncertainty limits:
The source code adheres to the specifications of Python 3.9 and heeds PEP 8 – Style Guide for Python Code. It has been compiled against Python 3.9.2 and frozen using PyInstaller 4.2. The modules calcopp-gui and sd2opp were frozen including PySimpleGUI 4.38.0 and NumPy 1.20.1, respectively.
Options are detailed in the build scripts build.cmd (Windows) and build.sh (Linux) shipped with the source code.
The source code adheres the specifications of Fortran 2018 with GNU-specific extensions. It has been compiled using GFortran 10.2.0 with static linking, all symbol table and relocation information removed, and optimization level set to “O3”.
Options are detailed in the build scripts build.cmd (Windows) and build.sh (Linux) shipped with the source code.
- On Windows versions earlier than Windows 10, install the Visual C++ Redistributable for Visual Studio 2015 with the same bitness as CalcOPP if it is not present yet.
- Unpack one of the archives (version for Windows/Linux) into any user-writable directory. For the graphical user interface (GUI) to work correctly, the executables must be in a common directory.
- On Unix-like systems, set execute permissions for the executables
CalcOPP,pdf2opp_2d,pdf2opp_3d, andsd2opp:
chmod +x CalcOPP pdf2opp_2d pdf2opp_3d sd2opp
Start the application CalcOPP[.exe] via desktop environment or shell. Further instructions are displayed in the box on the left side of the GUI.
For pdf2opp_2d[.exe], you can drag and drop the icon of an appropriate *.stf file on the executable’s icon. The program will then try to read the measurement temperature from a JANA2006 *.m90 file in the working directory and, if the file is found, automatically write the output to *_opp.asc. If an uncertainty map with the name *_err.stf is present, it will also be processed.
For pdf2opp_3d[.exe], you can drag and drop the icon of an appropriate *_tmp.xsf file on the executable’s icon. The program will then try to read the measurement temperature from a JANA2006 *.m90 file in the working directory and, if the file is found, automatically write the output to *_opp.xsf and *_opp.vesta.
If you want to use pdf2opp_2d[.exe], pdf2opp_3d[.exe], or sd2opp[.exe] from the command line (e.g., in custom scripts), please invoke them with the parameter -h (for help) to display their usage. The former two are stand-alone executables.
CalcOPP has been inspired by work from Dr. Hans Boysen (Ludwig-Maximilians-Universität München) and Dr. Anatoliy Senyshyn (Technische Universität München).
If you prepare data for publication with CalcOPP, please use the following citation:
D. Wiedemann, CalcOPP, Calculation of Effective One-Particle Potentials, Technische Universität Berlin, Berlin (Germany), 2021, doi:10.5281/zenodo.2530345.
It would be much appreciated if you reported any bugs, typos, or suggestions for improvement to dennis.wiedemann@chem.tu-berlin.de.