Enable loading XSF files from FHI-AIMS

The FHI-AIMS code offers to output the grid data either as CUBE or as XSF files. However, the structure of data in those XSF files is somewhat different from what one gets from VASP by applying the v2xsf tool on a LOCPOT or CHGCAR file. The loadXSF and loadXSFGeom functions need to be modified in order to read the FHI-AIMS data correctly. Essentially, the grid data in the FHI-AIMS generated XSF files, including the grid dimensions and the ordering of the data points, are the same as they would be in the corresponding CUBE files (except that lengths are fortunately still expressed in angstrom, not bohr, in XSF). The consequences can be summarized into the following three points:

Even for periodic systems, the grid dimensions need not be the same as the dimensions of the periodic cell. The default behavior for periodic systems, if you do not specify anything to the contrary in the control.in file, is still such that the grid covers the whole unit cell. However, a grid covering the unit cell means something slightly different for FHI-AIMS compared to what it means for VASP. There are no repeated data points at the unit cell boundary in FHI-AIMS like there would be in the XSF output from VASP. The first and the last point along an axis are not identical. The logic of FHI-AIMS is that the positions of nodes that form the grid are centers of the corresponding "voxels", which implies that the first and last point (node) along a particular axis do not in fact lie right on the cell boundary but they are shifted by half the voxel size (=half the grid step). Let me illustrate this by a concrete example: Suppose we have a 10x10x10 cell, which we want to sample with a grid in which the neighboring points are separated by the step of 0.1. The corresponding grid we expect to get from VASP would have 101x101x101 points, the origin would be at (0,0,0) and the grid vectors (pointing from the grid origin to the final points along the corresponding axes) would be
```
10   0   0
 0  10   0
 0   0  10
```
The first and the one-hundred-first points are duplicates of each other in any of the three main directions. In XSF from FHI-AIMS, in contrast, there would be just 100x100x100 data points. The origin would be at (0.05, 0.05, 0.05) and the grid vectors would be shorter by one "voxel" compared to VASP, like this:
```
9.9  0.0  0.0
0.0  9.9  0.0
0.0  0.0  9.9
```
Well, actually, the grid vectors from FHI-AIMS would be
```
0.0  0.0  9.9
0.0  9.9  0.0
9.9  0.0  0.0
```
as I will explain in the next point. Anyway, the control.in file of FHI-AIMS allows a fine-tuned control over the grid size and position, by using the cube origin and cube edge keywords. So, in principle, the user could always extract the same grid from FHI-AIMS as it would have been obtained from VASP. But it would be rather awkward. In particular, the cube origin in control.in does not really mean origin. Instead, it specifies the center of the grid. So it would have to be something like half the lattice vector in every direction minus half the grid step in every direction in order to obtain the desired result. I want to avoid having to do this when using FHI-AIMS. It should be possible as the XSF file contains both the information on the lattice vectors (as PRIMVEC) as well as the independent information on the grid dimensions. The lattice vectors would still be
```
10.0     0.0    0.0
 0.0    10.0    0.0
 0.0     0.0   10.0
```
even from FHI-AIMS, but the grid vectors would differ from the lattice vectors and the origin would be non-zero. The loading functions in ppafm/io.py need to interpret this information correctly.
The arrangement of data on the grid as for the order of the axes is the same in the FHI-AIMS-generated XSF files as it is in CUBE files. Consequently, the first and third grid axes are swapped with respect to the lattice vectors in periodic systems. Likewise, these grid axis are also swapped with respect to the Cartesian axes in non-periodic systems. Again, this could in principle be recognized by the loading function(s) since the grid vectors are recorded in the XSF file and can be compared to the lattice vectors in the same file.
Finally, the Hartree (electrostatic) potential is given in the Ha (rather than eV) units by FHI-AIMS. This is a point were I got a bit desperate because, in contrast to the issues above, there is no record inside the XSF file to indicate in what units the data are supposed to be expressed. After having figured out how to solve the other issues, I really did not want to introduce some new keyword argument to the PP-AFM code that would explicitly specify whether the input is from FHI-AIMS or from VASP. So, my proposed solution: Whenever the loadXSF functions detects that the first and third grid vectors have been swapped, a matter which has to be decided anyway, assume that the data originate from FHI-AIMS and, if moreover the data being read are expected to be a potential (rather than density), do the conversion from Ha to eV.

Hi Martin,

Just a quick comment! Do not use XSF from AIMS. Never, ever. There is a mess in the units, in the cell, as you are pointing out, and so on. I have once looked into it, it does not make sense to work with it for us, it is a not-necessary extra work. We should just say it in the manual, that in FHI-aims one should use only cube files.

Ondrej

- Reply to this email directly, view it on GitHubhttps://github.com/Probe-Particle/ppafm/issues/217, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ADFZAFI2O266BHY327JTRYLYA7JI5AVCNFSM6AAAAAA6N244KCVHI2DSMVQWIX3LMV43ASLTON2WKOZRHE2TSNBVHA2DSMA. You are receiving this because you are subscribed to this thread.Message ID: @.**@.>>

I am working on this issue. In fact, I have already done the greater part of the job, I believe. That is why I could describe the differences in the respective XSF formats in such detail above, I learned most of it along the way. I have pushed the work as a branch xsf-and-cube but it is not ready for merging yet.

When done, it should solve #190 as a side issue too.

The main part of the work on this issue that I still have to do involves proper treatment of the grid origin, as read from the XSF or CUBE file. A byproduct of this effort will be that negative coordinates can be allowed for the scanning area over non-periodic systems, because the origin will not be forced to zero.

Hi, Ondřej (@ondrejkrejci), I have edited out the copy of my own post from yours in this comment section to keep it more concise. I hope this alteration does not break anything. As for the substance: Well, avoiding the XSF from FHI-AIMS would surely be a solution too, but... The XSF from AIMS is not any worse than the CUBE file as long as you know it comes from AIMS. In other words, the only advantage of CUBE is in fact that we can always assume it comes from FHI-AIMS and handle it accordingly. Other than that, there is not that much difference and in fact the main problem of XSF from AIMS is that it is too similar to CUBE (the exactly same grid as in CUBE, with grid point positions and ordering untypical for the XSF format). There is at least one issue I need to solve because of FHI-AIMS, irrespective whether I am going to use XSF or CUBE files. I do not like the origin of the grid-covered space being forced to the origin of the Cartesian system. As it is now, I have to make sure that the origin of the grid in the CUBE file is always at zero, which means always putting the center of the unit cell to the cube origin line in the control.in, which is a pain.

Hi,

“”” The XSF from AIMS is not any worse than the CUBE file as long as you know it comes from AIMS. In other words, the only advantage of CUBE is in fact that we can always assume it comes from FHI-AIMS and handle it accordingly. Other than that, there is not that much difference and in fact the main problem of XSF from AIMS is that it is too similar to CUBE (the exactly same grid as in CUBE, with grid point positions and ordering untypical for the XSF format). “”” I see the main problem in the units conversion that is why I would suggest to omit it. Especially when CUBE is like a nature format for AIMS. My point was to save your time, to not try solve all the problems on the world 😊. Regards, Ondrej

From: Martin Ondráček @.> Sent: tiistai 24. lokakuuta 2023 18.32 To: Probe-Particle/ppafm @.> Cc: Krejci Ondrej @.>; Comment @.> Subject: Re: [Probe-Particle/ppafm] Enable loading XSF files from FHI-AIMS (Issue #217)

Hi, Ondřej, I have edited out the copy of my own post from yours in this comment section to keep it more concise. I hope this alteration does not break anything. As for the substance: Well, avoiding the XSF from FHI-AIMS would surely be a solution too, but... The XSF from AIMS is not any worse than the CUBE file as long as you know it comes from AIMS. In other words, the only advantage of CUBE is in fact that we can always assume it comes from FHI-AIMS and handle it accordingly. Other than that, there is not that much difference and in fact the main problem of XSF from AIMS is that it is too similar to CUBE (the exactly same grid as in CUBE, with grid point positions and ordering untypical for the XSF format). There is at least one issue I need to solve because of FHI-AIMS, irrespective whether I am going to use XSF or CUBE files. I do not like the origin of the grid-covered space being forced to the origin of the Cartesian system. As it is now, I have to make sure that the origin of the grid in the CUBE file is always at zero, which means always putting the center of the unit cell to the cube origin line in the control.in, which is a pain.

— Reply to this email directly, view it on GitHubhttps://github.com/Probe-Particle/ppafm/issues/217#issuecomment-1777493372, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ADFZAFPH4GRVE5TYIMJ736DYA7NOVAVCNFSM6AAAAAA6N244KCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTONZXGQ4TGMZXGI. You are receiving this because you commented.Message ID: @.**@.>>

Hi everybody. This is just to announce that I am going to finish this work after all. The reasons are that:

The bulk of the work is already done, part of it (regarding the XSF input and output itself) in my xsf-and-cube branch, another part (regarding the grid origin) now submitted as PR #229 (needed to fix an other issue anyway), so what I mainly have to do now is just merging and testing the stuff.
I want to use FHI-AIMS, whether through XSF or CUBE, and neither actually worked as it should have until recently. Resolving the issue with the grid origin was likely the main thing needed to make CUBE work while much additional work was needed for XSF, but I did not know that before I actually did the work. Now that the work is mostly done, why throw it out of window.
Having the two input options available, both CUBE and XSF, is a kind of safety feature. In the future, I want to avoid the frustration I have experienced in my attempts to use PP-AFM with FHI-AIMS. The experience went something like: "I have troubles using the XSF files from FHI-AIMS in PP-AFM." "Well, XSF from AIMS sucks, why don't you use CUBE?". "Handling coordinates from CUBE is a total mess, I can't figure out how the scan region relates to atom positions..." "Okay, CUBE is not that well tested in PP-AFM, why don't you use XSF instead?" And so on, loop to infinity. So while I am going to stick to CUBE files in my everyday work with FHI-AIMS, once anything breaks down, I want to have the option to test CUBE against XSF and see whether the problems are dependent on the input format or not.
Maintaining the ability to read XSF from various sources will force us to handle this format properly, including, for instance, handling the seemingly unrelated issue of grid dimensions of the OutFz.xsf files which I discuss in #198.

A possible argument against implementing this feature: The XSF from FHI-AIMS is indeed rather idiosyncratic. While my idea was that our functions that implement the XSF input should be as general as possible, there will nevertheless have to be a point in the code where it decides "is this XSF from AIMS or not?" and handles the "Yes, from AIMS" branch separately. This is so for two reasons:

The data ordering (ZYX vs XYZ or, if you want, F-contiguous vs C-contiguous) and
the eV vs hartree units for potentials.

The necessity of making such decision is potentially dangerous: If a XSF file were misidentified as created by FHI-AIMS even though it actually originated from elsewhere, that would cause troubles. But I believe I can implement the FHI-AIMS vs non FHI-AIMS input recognition safely.

Probe-Particle / ppafm

Enable loading XSF files from FHI-AIMS #217