Output formats

Currently grogupy relies on a .pkl file as its main output format that can be used to reload its main system object, but HDF should be the default in the future. Furthermore it supports different input formats for atomistic spin dynamics and magnon spectrum calculation.

Magnopy

The magnopy input format is fully supported. The two softwares can be easily used in a pipeline.

UppASD Atomistic Spin Dynamics

grogupy outputs the posfile, momfile, exchange and inpsd.dat. The on-site anisotropy, if it is available, is written in the exchange file as an interaction of a spin with itself. The inpsd.dat is mostly empty, it only contains the cell information and the paths to the other input files, so you have to manually fill in the remaining required information to run a simulation.

Vampire

Vampire only supports rectangular unit cells, which is partially supported by grogupy. It can convert some 2D unit cells with C3 symmetry to the acceptable format. grogupy outputs the vampire.UCF and vampire.mat files with all the information, but you have to set some parameters in the input file.

Spin Hamiltonian file

In a lot of cases grogupy outputs a spin Hamiltonian file using the magnopy format, because in the future it should be able to convert between many input formats of different softwares.

First of all here is the specification of the full file

 1===============================================================================
 2GROGU INFORMATION 
 3
 4<Any amount of lines and information
 5Any comments 
 6Any details here>
 7===============================================================================
 8Hamiltonian convention
 9Double counting      true
10Normalized spins     true
11Intra-atomic factor  +1
12Exchange factor      +0.5 
13===============================================================================
14Cell (Ang)
15<a1_x> <a1_y> <a1_z>
16<a2_x> <a2_y> <a2_z>
17<a3_x> <a3_y> <a3_z>
18===============================================================================
19Magnetic sites
20Number of sites <M>
21Name     x (Ang) y (Ang) z (Ang) s     sx      sy      sz    
22<Name1>  <r1_x>  <r1_y>  <r1_z>  <s1>  <s1_x>  <s1_y>  <s1_z>
23<...>
24<NameM>  <rM_x>  <rM_y>  <rM_z>  <sM>  <sM_x>  <sM_y>  <sM_z>
25===============================================================================
26Intra-atomic anisotropy tensor (meV) 
27------------------------------------
28<Name> 
29Matrix 
30   <Axx> <Axy> <Axz>
31   <Ayx> <Ayy> <Ayz>
32   <Azx> <Azy> <Azz>
33------------------------------------
34<...>
35------------------------------------
36===============================================================================
37Exchange tensor (meV)
38Number of pairs <N>
39-----------------------------------------
40Name1   Name2      i   j   k      d (Ang)
41-----------------------------------------
42<Name1>  <Name2>  <i> <j> <k>     <d> 
43Matrix 
44   <Jxx> <Jxy> <Jxz>
45   <Jyx> <Jyy> <Jyz>
46   <Jzx> <Jzy> <Jzz>
47-----------------------------------------
48<...>
49-----------------------------------------
50===============================================================================

The file is composed by a number of sections. Sections are separated by approximately 80 “=” symbols. Some of the sections have subsections, that are separated by approximately 40 “-” symbols. Next we describe the sections of the file one by one.

Comment section

1===============================================================================
2GROGU INFORMATION 
3
4<Any amount of lines and information
5Any comments 
6Any details here>
7===============================================================================

line

Formal description

1

Section separator. Approximately 80 “=” symbols.

2-6

Any amount of lines. Undocumented comments with usefull information.

7

Section separator. Approximately 80 “=” symbols.

This section might list the detatils of the grogupy calculations or of the underlying DFT calcuation. The amount of lines in this section is arbitrary and might be different in different versions of grogupy. The content of this section is not restricted and can be arbitrary as well.

Hamiltonian convention

 7===============================================================================
 8Hamiltonian convention
 9Double counting      true
10Normalized spins     true
11Intra-atomic factor  +1
12Exchange factor      +0.5 
13===============================================================================

line

Formal description

7

Section separator. Approximately 80 “=” symbols.

8

Keyword Hamiltonian convention.

9

Keyword Double counting followed by at least one space symbol and the value keyword true.

10

Keyword Normalized spins followed by at least one space symbol and the value keyword true.

11

Keyword Intra-atomic factor followed by at least one space symbol and the value +1.

12

Keyword Exchange factor followed by at least one space symbol and the value +0.5.

13

Section separator. Approximately 80 “=” symbols.

This section has a fixed amount of lines. It describes the convention of the spin Hamiltonian in grogupy. The parameters of the file should be interpreted together with this convention.

The Hamiltonian in this convention would be written as

\[\mathcal{H} = \sum_{i} \boldsymbol{e}_{i} \cdot \boldsymbol{A}_{i} \cdot \boldsymbol{e}_{i} + \dfrac{1}{2} \sum_{i \ne j} \boldsymbol{e}_{i} \cdot \boldsymbol{J}_{ij} \cdot \boldsymbol{e}_{j}\]

where \(\boldsymbol{e}_{i} = \boldsymbol{S}_{i}/S_i\) is a spin vector operator normalised by its value (thus Normalized spins true in the convention); \(\boldsymbol{A}_{i}\) is an intra-atomic anisotropy tensor; \(\boldsymbol{J}_{ij}\) is a full matrix of the exchange parameter. Both pairs \(\boldsymbol{e}_{i}\boldsymbol{J}_{ij}\boldsymbol{e}_{j}\) and \(\boldsymbol{e}_{j}\boldsymbol{J}_{ji}\boldsymbol{e}_{i}\) are explicitly included in the sum (hence the Double counting true in the convention).

Cell

13===============================================================================
14Cell (Ang)
15<a1_x> <a1_y> <a1_z>
16<a2_x> <a2_y> <a2_z>
17<a3_x> <a3_y> <a3_z>
18===============================================================================

line

Formal description

13

Section separator. Approximately 80 “=” symbols.

14

Keyword Cell (Ang).

15

Three numbers separated by at least one space symbol. Components of the first lattice vector \(\boldsymbol{a}_1 = (a_1^x, a_1^y, a_1^z)\) given in Angstroms.

16

Three numbers separated by at least one space symbol. Components of the second lattice vector \(\boldsymbol{a}_2 = (a_2^x, a_2^y, a_2^z)\) given in Angstroms.

17

Three numbers separated by at least one space symbol. Components of the third lattice vector \(\boldsymbol{a}_3 = (a_3^x, a_3^y, a_3^z)\) given in Angstroms.

18

Section separator. Approximately 80 “=” symbols.

This section describes the (unit or super) cell of the underlying periodic lattice on which the spin Hamiltonian is defined.

Magnetic sites

18===============================================================================
19Magnetic sites
20Number of sites <M>
21Name     x (Ang) y (Ang) z (Ang) s     sx      sy      sz    
22<Name1>  <r1_x>  <r1_y>  <r1_z>  <s1>  <s1_x>  <s1_y>  <s1_z>
23<...>
24<NameM>  <rM_x>  <rM_y>  <rM_z>  <sM>  <sM_x>  <sM_y>  <sM_z>
25===============================================================================

line

Formal description

18

Section separator. Approximately 80 “=” symbols.

19

Keyword Magnetic sites.

20

Keyword Number of sites followed by at least one space symbol and one integer number \(M\).

21

Line with the headers.

22

Line with the description of the first magnetic site. 8 elements on the line, the elements are separated by at least one space symbol.

  • Name - a string that do not contain no space symbols. Serves as the identifier of the magnetic site. The name of every magnetic site should be unique.

  • r1_x r1_y r1_z - three numbers. Absolute coordinates of the magnetic site given in Angstroms.

  • s1 - one number. Spin value (or magnitude of spin) of the magnetic site. Always positive.

  • s1_x s1_y s1_z- three numbers. Direction of the spin vector operator.

23

Specification of the other \(M-2\) magnetic sites.

24

Specification of the last magnetic site.

25

Section separator. Approximately 80 “=” symbols.

This section describes the magnetic sites that constitute the basis of the spin Hamlitonian. Magnetic sites can correspond to the atoms of the underlying crystall or to more complex structures.

Intra-atomic anisotropy

25===============================================================================
26Intra-atomic anisotropy tensor (meV) 
27------------------------------------
28<Name> 
29Matrix 
30   <Axx> <Axy> <Axz>
31   <Ayx> <Ayy> <Ayz>
32   <Azx> <Azy> <Azz>
33------------------------------------
34<...>
35------------------------------------
36===============================================================================

line

Formal description

25

Section separator. Approximately 80 “=” symbols.

26

Keyword Intra-atomic anisotropy tensor (meV).

27

Subsection separator. Approximately 40 “-” symbols.

28

One string that do not contain no spaces. Name of the magnetic site, with which the parameter is associated. Should match one of the names from the Magnetic sites section.

29

Keyword Matrix.

30-32

Full matrix of the intra-atomic anisotropy parameter. Each line contains three numbers. Numbers in each line separated by at least one space symbol.

33

Subsection separator. Approximately 40 “-” symbols.

34

More subsections with other \((M-1)\) parameters. Each subsection has same format as the first one.

35

Subsection separator. Approximately 40 “-” symbols.

36

Section separator. Approximately 80 “=” symbols.

This section lists parameters of the intra-atomic anisotropy of the spin Hamiltonian \(\boldsymbol{A}_{i}\). For further information see the theoretical background in the tutorials.

Exchange interaction

36===============================================================================
37Exchange tensor (meV)
38Number of pairs <N>
39-----------------------------------------
40Name1   Name2      i   j   k      d (Ang)
41-----------------------------------------
42<Name1>  <Name2>  <i> <j> <k>     <d> 
43Matrix 
44   <Jxx> <Jxy> <Jxz>
45   <Jyx> <Jyy> <Jyz>
46   <Jzx> <Jzy> <Jzz>
47-----------------------------------------
48<...>
49-----------------------------------------
50===============================================================================

line

Formal description

36

Section separator. Approximately 80 “=” symbols.

37

Keyword Exchange tensor (meV).

38

Keyword Number of pairs followed by at least one space symbol, followed by one number \(N\).

39

Subsection separator. Approximately 40 “-” symbols.

40

Line with the header for the pair specification.

41

Subsection separator. Approximately 40 “-” symbols.

42

Specification of the first pair. 5 elements on the line, the elements are separated by at least one space symbol.

  • Name1 - a string that do not contain no space symbols. Serves as the identifier of the magnetic site from the \((0, 0, 0)\) cell. Should match one of the names from the Magnetic sites section.

  • Name2 - a string that do not contain no space symbols. Serves as the identifier of the magnetic site from the \((i, j, k)\) cell. Should match one of the names from the Magnetic sites section.

  • i j k - three integer numbers. Specify the unit cell for the second magnetic site. the position of the unit cell is defined as \(i\cdot\boldsymbol{a}_1 + j\cdot\boldsymbol{a}_2 + k\cdot\boldsymbol{a}_3\)

  • d- one number. A distance between the first magnetic site in the unit cell \((0, 0, 0)\) and the second magnetic site in the unit cell \((i, j, k)\).

43

Keyword Matrix.

44-46

Full matrix of the exchange parameter. Each line contains three numbers. Numbers in each line separated by at least one space symbol.

47

Subsection separator. Approximately 40 “-” symbols.

48

More subsections with other \((N-1)\) parameters. Each subsection has same format as the first one.

49

Subsection separator. Approximately 40 “-” symbols.

50

Section separator. Approximately 80 “=” symbols.

The last section lists full the matrices of the biliniar exchange parameters \(\boldsymbol{J}_{ij}\). For further information see the theoretical background in the tutorials.