magnopy-lswt#

This scenario runs a calculation for the given spin Hamiltonian at the level of the linear spin wave theory and outputs majority of the results that magnopy can compute.

Help message#

This page of documentation is written by hand and might become outdated due to the human error. Moreover, we do not intend to cover all possible parameters of the script in this page of the documentation. To get the automatically generated description of all input parameters, that is produced by the actual version of magnopy that is installed in you environment use

magnopy-lswt --help

That should output something similar to

usage: magnopy-lswt [-h] -sf filename -ss name [-sd [S1_x S2_y S3_z ... ...]]
                    [-sv [S1 S2 S3 ... ...]] [-kp GAMMA-X-S|GAMMA-Y]
                    [-kps KPOINTS] [-r]
                    [-mf MAGNETIC_FIELD MAGNETIC_FIELD MAGNETIC_FIELD]
                    [-of OUTPUT_FOLDER] [-np NUMBER_PROCESSORS] [-no-html]
                    [-hpd] [-spg-s SPGLIB_SYMPREC]
                    [-msdi MAKE_SD_IMAGE MAKE_SD_IMAGE MAKE_SD_IMAGE]

███╗   ███╗  █████╗   ██████╗  ███╗   ██╗  ██████╗  ██████╗  ██╗   ██╗
████╗ ████║ ██╔══██╗ ██╔════╝  ████╗  ██║ ██╔═══██╗ ██╔══██╗ ╚██╗ ██╔╝
██╔████╔██║ ███████║ ██║  ███╗ ██╔██╗ ██║ ██║   ██║ ██████╔╝  ╚████╔╝
██║╚██╔╝██║ ██╔══██║ ██║  ╚██║ ██║╚██╗██║ ██║   ██║ ██╔═══╝    ╚██╔╝
██║ ╚═╝ ██║ ██║  ██║ ╚██████╔╝ ██║ ╚████║ ╚██████╔╝ ██║         ██║
╚═╝     ╚═╝ ╚═╝  ╚═╝  ╚═════╝  ╚═╝  ╚═══╝  ╚═════╝  ╚═╝         ╚═╝
                                                           ▄   ▄
                      Version: 0.2.0                       █▀█▀█
                Documentation: magnopy.org                 █▄█▄█
             Release date: 10 September 2025                ███   ▄▄
                    License: GNU GPLv3                      ████ █  █
          Copyright (C) 2023-2025  Magnopy Team             ████    █
                                                            ▀▀▀▀▀▀▀▀

This script solves the spin Hamiltonian at the level of Linear Spin Wave Theory (LSWT) and outputs (almost) every possible quantity.

options:
  -h, --help            show this help message and exit
  -sf, --spinham-filename filename
                        Path to the spin Hamiltonian file, from where the
                        parameters would be read.
  -ss, --spinham-source name
                        Source of the spin Hamiltonian. Either "GROGU" or
                        "TB2J"
  -sd, --spin-directions [S1_x S2_y S3_z ... ...]
                        To fully define the system for the calculations of
                        magnons one need the information about the ground
                        state in addition to the parameters of the
                        Hamiltonian. There are two ways to give this
                        information to magnopy: * Give a path to the file. In
                        the file there should be M lines with three numbers in
                        each. The order of the lines would match the order of
                        magnetic atoms in the spin Hamiltonian. * Give a
                        sequence of 3*M numbers directly to this parameter. If
                        none provided, then magnopy attempts to optimize the
                        spin directions prior to the LSWT calculations.
  -sv, --spin-values [S1 S2 S3 ... ...]
                        In the case when the parameters of spin Hamiltonian
                        comes from TB2J, one might want to change the values
                        of spins to be closer to half-integers. This option
                        allows that. Order of the M numbers should match the
                        order of magnetic atoms in the spin Hamiltonian. Note
                        that those numbers are always positive. To specify AFM
                        order use opposite spin directions and not spin values
                        of the opposite sign.
  -kp, --k-path GAMMA-X-S|GAMMA-Y
                        Path of high symmetry k-points for the plots of
                        dispersion and other quantities.
  -kps, --kpoints KPOINTS
                        Alternatively one could provide an explicit list of
                        k-points for calculation. In that case provide a path
                        to the file, in which each k-point is given in a
                        separate line with three numbers per line.
  -r, --relative        When an explicit list of k-points is given, this
                        option specify whether to consider them as relative or
                        absolute coordinates. Absolute by default.
  -mf, --magnetic-field MAGNETIC_FIELD MAGNETIC_FIELD MAGNETIC_FIELD
                        Vector of external magnetic field, given in the units
                        of Tesla.
  -of, --output-folder OUTPUT_FOLDER
                        Folder where all output files of magnopy wil be saved.
  -np, --number-processors NUMBER_PROCESSORS
                        Number of processes for multithreading. Uses all
                        available processors by default. Pass 1 to run in
                        serial.
  -no-html, --no-html   html files are generally heavy (~> 5 Mb). This option
                        allows to disable their production to save disk space.
  -hpd, --hide-personal-data
                        Whether to strip the parts of the paths as to hide the
                        file structure of you personal computer.
  -spg-s, --spglib-symprec SPGLIB_SYMPREC
                        Tolerance parameter for the space group symmetry
                        search by spglib.
  -msdi, --make-sd-image MAKE_SD_IMAGE MAKE_SD_IMAGE MAKE_SD_IMAGE
                        make_sd_image is deprecated, use --no-html instead.
                        This arguments will be removed from magnopy in March
                        of 2026

At the very beginning there is a syntax for the usage of the script, where required arguments are given without brackets and optional arguments are written within brackets. Then there is a logo of magnopy, followed by the list of supported arguments with their short and long names and explanation of what they represent.

Hint

The short (i.e. -sf) and long (i.e. --spinham-filename) are absolutely equivalent. Feel free to use either of them. The long name usually is self-explanatory and the short one is added purely for the convenience of the user.

Spin Hamiltonian and its source#

This script works with the spin Hamiltonian that is coming from some third-party software. At the moment magnopy supports TB2J and GROGU.

Hint

There is number of ways to use this script with the hand-made Hamiltonian:

  • Prepare the file that mimics the format of TB2J.

  • Prepare the file that mimics the GROGU file format.

  • Prepare the spin Hamiltonian programmatically and use the scenario of this command-line script from within your python scripts: scenarios.optimize_sd().

To tell the script what spin Hamiltonian to use provide

  • Source of the spin Hamiltonian (-ss or --spinham-source);

  • Path to the file with the spin Hamiltonian (-sf or --spinham-filename)

For example, if the file with the spin Hamiltonian is located in the "data/hamiltonians/trial1/TB2J/exchange.out" and the source of the file is TB2J, then pass to the script two parameters either in the short form

magnopy-lswt  -ss TB2J -sf data/hamiltonians/trial1/TB2J/exchange.out ...

or in the long form

magnopy-lswt  -spinham-source TB2J -spinham-filename data/hamiltonians/trial1/TB2J/exchange.out ...

Note

The dots ... are not a part of the syntax. They are used only to highlight the parameters that are described in the particular chapter of the documentation and hide all other parameters that might or might not be passed to the script.

Ground state#

For the calculation of exited states (what magnons are) one need to knows the ground state - spin directions for every spin in the Hamiltonian. There are two ways for magnopy to know the spin directions

  • Input from the user

    User can provide a file with spin directions using either the short form of the argument

    magnopy-lswt ... -sd SPIN-DIRECTIONS.txt

    or long form

    magnopy-lswt ... --spin-directions SPIN-DIRECTIONS.txt

  • Internal optimization

    If user do not provide any input, then magnopy tries to optimize spin directions within unit cell.

Note

The dots ... are not a part of the syntax. They are used only to highlight the parameters that are described in the particular chapter of the documentation and hide all other parameters that might or might not be passed to the script.

K-path and k-points#

Magnopy solves magnon problem for a set of points in reciprocal space. Therefore, it needs to know a set of k-points to perform the calculations. User is left with two options

  • Provide explicit list of k-points, using short form of the arguments

    magnopy-lswt ... -kps  K-POINTS.txt

    or long form

    magnopy-lswt ... --kpoints  K-POINTS.txt

  • Let magnopy deduce the set of high-symmetry points based on the space group of the crystal and use recommended k-path (see documentation of wulfric for more details, magnopy uses convention="HPKOT"). In that second case the user can still control the k-path, but limited to the list of the predefined high-symmetry points.

    magnopy-lswt ... -kp  GAMMA-X-S|GAMMA-Y

    or in the long form

    magnopy-lswt ... --k-path  GAMMA-X-S|GAMMA-Y

Note

The dots ... are not a part of the syntax. They are used only to highlight the parameters that are described in the particular chapter of the documentation and hide all other parameters that might or might not be passed to the script.

External magnetic field#

The file with the spin Hamiltonian specifies the interaction parameters that are intrinsic to the material.

In order to add additional effects, for instance an external magnetic field one can use the -mf or --magnetic-field parameter.

This parameter expects three numbers, that specify three Cartesian components of the external magnetic field. The value of the provided vector is interpreted in Tesla.

For example to add magnetic field of 2.42 Tesla along the direction \((1, 1, 0)\) (i.e. in the \(xy\) plane, right in between the \(x\) and \(y\) axis) pass to the script the parameter, in the short form

magnopy-lswt ... -mf 1.7112 1.7112 0 ...

or in the long form

magnopy-lswt ... --magnetic-field 1.7112 1.7112 0 ...

Note

The dots ... are not a part of the syntax. They are used only to highlight the parameters that are described in the particular chapter of the documentation and hide all other parameters that might or might not be passed to the script.

Output of the script#

The script have two types of the output:

  • Text output to the console

    Magnopy outputs the progress of the calculation in the standard output stream, that is typically printed directly to the terminal. If you would like to save this text in a file, we recommend to use stream redirect > operator as

    magnopy-lswt ... > output.txt

    In that way there will be no output to the console, but all the information will be saved in the file "output.txt".

  • Output that is saved in the separated files.

    A number of the files will be saved in the folder that is named "magnopy-results" by default. If you would like to change its name, for instance to "magnopy-LSWT-trial-1", then you can use the parameter -of or --output-folder. In the short form

    magnopy-lswt ... -of magnopy-LSWT-trial-1 ...

    or in the long form

    magnopy-lswt ... --output-folder magnopy-LSWT-trial-1 ...

    Note

    The visual capabilities of magnopy require a third-party plotting library Plotly. It is not included as a default dependency of magnopy and therefore, have to be installed manually. It can be installed with pip, in the same way as magnopy:

    pip install plotly

    or

    pip3 install plotly

Note

The dots ... are not a part of the syntax. They are used only to highlight the parameters that are described in the particular chapter of the documentation and hide all other parameters that might or might not be passed to the script.