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 .. literalinclude:: magnopy-input-specs.txt :linenos: :language: text 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 --------------- .. literalinclude:: magnopy-input-specs.txt :linenos: :lineno-match: :lines: 1-7 :language: text ====== ========================================================================= 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 ---------------------- .. literalinclude:: magnopy-input-specs.txt :linenos: :lineno-match: :lines: 7-13 :language: text ====== ========================================================================= 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 .. math:: \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 :math:`\boldsymbol{e}_{i} = \boldsymbol{S}_{i}/S_i` is a spin vector operator normalised by its value (thus ``Normalized spins true`` in the convention); :math:`\boldsymbol{A}_{i}` is an intra-atomic anisotropy tensor; :math:`\boldsymbol{J}_{ij}` is a full matrix of the exchange parameter. Both pairs :math:`\boldsymbol{e}_{i}\boldsymbol{J}_{ij}\boldsymbol{e}_{j}` and :math:`\boldsymbol{e}_{j}\boldsymbol{J}_{ji}\boldsymbol{e}_{i}` are explicitly included in the sum (hence the ``Double counting true`` in the convention). Cell ---- .. literalinclude:: magnopy-input-specs.txt :linenos: :lineno-match: :lines: 13-18 :language: text ====== ========================================================================= 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 :math:`\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 :math:`\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 :math:`\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. .. _user-guide_output-format_magnetic-sites: Magnetic sites -------------- .. literalinclude:: magnopy-input-specs.txt :linenos: :lineno-match: :lines: 18-25 :language: text ====== ========================================================================= 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 :math:`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 :math:`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 ----------------------- .. literalinclude:: magnopy-input-specs.txt :linenos: :lineno-match: :lines: 25-36 :language: text ====== ========================================================================= 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 :ref:`user-guide_output-format_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 :math:`(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 :math:`\boldsymbol{A}_{i}`. For further information see the :ref:`theoretical background ` in the tutorials. Exchange interaction -------------------- .. literalinclude:: magnopy-input-specs.txt :linenos: :lineno-match: :lines: 36-50 :language: text ====== ========================================================================= 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 :math:`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 :math:`(0, 0, 0)` cell. Should match one of the names from the :ref:`user-guide_output-format_magnetic-sites` section. * ``Name2`` - a string that do not contain no space symbols. Serves as the identifier of the magnetic site from the :math:`(i, j, k)` cell. Should match one of the names from the :ref:`user-guide_output-format_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 :math:`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 :math:`(0, 0, 0)` and the second magnetic site in the unit cell :math:`(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 :math:`(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 :math:`\boldsymbol{J}_{ij}`. For further information see the :ref:`theoretical background ` in the tutorials.