magnopy-optimize-sd#
This scenario optimizes classical energy of the spin Hamiltonian and finds the spin directions that describe a local minima of the energy landscape.
First we give an example of what this script can compute and then go through its usage and parameters in details.
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-optimize-sd --help
That should output something similar to
usage: magnopy-optimize-sd [-h] -sf FILENAME -ss KEYWORD [-sv [S1 [S2 ...]]]
[-s xa_1 xa_2 xa_3] [-et ENERGY_TOLERANCE]
[-tt TORQUE_TOLERANCE] [-mf h_x h_y h_z]
[-of OUTPUT_FOLDER] [-no-html] [-hpd]
[-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 optimizes classical energy of the spin Hamiltonian and finds the spin directions that describe a local minima of the energy landscape.
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 KEYWORD
Source of the spin Hamiltonian. Either "GROGU" or
"TB2J"
-sv, --spin-values [S1 [S2 ...]]
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.
-s, --supercell xa_1 xa_2 xa_3
Specification of the supercell for the spin
optimization. Expects three integers as an input. Pass
1 1 1 to optimize within the original unit cell.
-et, --energy-tolerance ENERGY_TOLERANCE
Tolerance parameter. Difference between classical
energies of two consecutive optimization steps.
-tt, --torque-tolerance TORQUE_TOLERANCE
Maximum torque among all spins.
-mf, --magnetic-field h_x h_y h_z
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.
-no-html, --no-html Disable plotting of the spin direction image in the
.html format. 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.
-msdi, --make-sd-image MAKE_SD_IMAGE MAKE_SD_IMAGE MAKE_SD_IMAGE
make_sd_image is deprecated, image is made by default,
use --no-html to suppress. 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 is usually 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 (
-ssor--spinham-source);Path to the file with the spin Hamiltonian (
-sfor--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-optimize-sd -ss TB2J -sf data/hamiltonians/trial1/TB2J/exchange.out ...
or in the long form
magnopy-optimize-sd -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.
Minimization domain#
By default magnopy vary only the spins within the original unit cell of the Hamiltonian.
In that way it can miss the true ground state if it spans over several unit cells that
can not be transformed into one another by a simple translation. To address this issue,
we offer an option of minimization on the supercell. The supercell is produced by a number of
translations of the original unit cell (-s or --superell). For example, to ask
for a minimization of the \(3\times7\times2\) supercell one can use the command, in
the short form
magnopy-optimize-sd ... -s 3 7 2 ...
or in the long form
magnopy-optimize-sd ... --supercell 3 7 2 ...
In that case every spin in the \(3\times7\times2\) supercell is treated as an individual variable. Note, that the computational cost of minimization will grow with the size of the supercell.
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.
Accuracy or tolerance conditions#
In theory numerical optimization can continues indefinitely, improving accuracy of some target value with each step. In reality an algorithm should reach some values of the tolerance after the finite amount of steps.
The minimization algorithm implemented in magnopy [1] traces two values:
Absolute value of the difference in total energy between two consecutive steps of the minimization (
-etor--energy-tolerance).Maximum (among all spins of the unit cell or supercell) value of the torque vector (
-ttor--torque-tolerance).
An algorithm stops and output the obtained spin directions when both tolerance parameters are reached. The default values, that magnopy uses should lead to the reasonable results in most of the cases.
However, if you want to increase accuracy of one of the parameters or both, then try to pass the corresponding parameters to the script. In the short form
magnopy-optimize-sd ... -et 0.000001 -tt 0.001 ...
or in the long form
magnopy-optimize-sd ... --energy-tolerance 0.000001 --torque-tolerance 0.001 ...
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-optimize-sd ... -mf 1.7112 1.7112 0 ...
or in the long form
magnopy-optimize-sd ... --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 asmagnopy-optimize-sd ... > 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-SO-trial-1", then you can use the parameter
-ofor--output-folder. In the short formmagnopy-optimize-sd ... -of magnopy-SO-trial-1 ...
or in the long form
magnopy-optimize-sd ... --output-folder magnopy-SO-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.