An automatic workflow software for calculating the ground collinear magnetic state of a given structure and for estimating the critical temperature of the magnetically ordered to paramagnetic phase transition.
Automag is meant to be run on a computing cluster. The first step in the installation is to clone the repository
git clone https://github.com/michelegalasso/automag.git
I assume that you have Python 3 installed on your system, accessible through
the python
command, with the wheel
and the venv
packages installed.
After cloning, go to the automag
directory which has appeared and initialize
a Python virtual environment
cd automag
python -m venv .venv
After that, activate your virtual environment. If you are working on an Unix-like system, you can do it with the command
source .venv/bin/activate
Finally, you need to install all the necessary Python dependencies for Automag with the command
pip install -r requirements.txt
Before using Automag, make sure that enumlib is installed on your system and
that that your command line has access to the commands enum.x
and makeStr.py
.
In addition, Automag needs to know how to use VASP, so you need to edit the file
automag/ase/run_vasp.py
for Automag to correctly load the MKL and MPI libraries
(if needed) and call the vasp_std
executable on your system. Then add the
following lines to your ~/.bashrc
file
export PYTHONPATH=/PATH/TO/automag:$PYTHONPATH
export VASP_SCRIPT=/PATH/TO/automag/ase/run_vasp.py
export VASP_PP_PATH=/PATH/TO/pp
export AUTOMAG_PATH=/PATH/TO/automag
obviously replacing /PATH/TO
with the actual path to these files or directories.
The pp
folder is the VASP pseudopotential library and it should contain two
subfolders named, respectively, potpaw_LDA
and potpaw_PBE
.
Before starting to use Automag, you should also make sure to have the FireWorks
library correctly pointing to a MongoDB database and configured for launching
jobs through a queue management system (for more detailed information refer
to the FireWorks documentation). Last but not least, open the file
automag/common/SubmitFirework.py
and edit line 23 with the location of your
my_launchpad.yaml
file. Now you are ready to use Automag.
When studying a magnetic structure, you may want to start from convergence tests.
Automag allows you to check for convergence of the VASP parameter ENCUT
, which
is the energy cut-off of the plane wave basis set, and to simultaneously check for
convergence of the two parameters SIGMA
and kpts
, which are the electronic
smearing parameter and the k-mesh resolution parameter for Brillouin zone sampling,
respectively.
In order to run convergence tests, go to the folder 0_conv_tests
and insert the
following input parameters in the file input.py
:
mode
can be "encut" for convergence tests with respect toENCUT
or "kgrid" for convergence tests with respect toSIGMA
andkpts
;poscar_file
is the name of the file in POSCAR format which contains the input geometry and which has been put in the folderautomag/geometries
;params
is a collection of VASP parameters to be used during single-point energy calculations.
In addition, the following optional parameters can be specified:
magnetic_atoms
contains the atomic types to be considered magnetic (defaults to transition metals);configuration
is the magnetic configuration to use for convergence tests (defaults to ferromagnetic high-spin);encut_values
contains the trial values forENCUT
(defaults to the interval [500, 1000] eV at steps of 10 eV);sigma_values
contains the trial values forSIGMA
(defaults to the interval [0.05, 0.20] eV at steps of 0.05 eV);kpts_values
contains the trial values forkpts
(defaults to the interval [20, 100] A^-1 at steps of 10 A^-1).
Once you have inserted the input parameters in the file input.py
, launch the
script 1_submit.py
using the python
executable of your virtual environment and
a number of workflows containing single-point VASP calculations will be saved in
your remote database. These calculations need to be run in a separate directory
called CalcFold
. You can enter it and then submit the jobs with the following
commands, being in the automag
directory
cd CalcFold
nohup qlaunch -r rapidfire -m 10 --nlaunches=infinite &
This will enter the directory CalcFold
and it will invoke the qlaunch
command in the background, which constantly checks for new calculations in the
remote database and submits them to the queue management system of your cluster.
The command line option -m 10
means that qlaunch
will allow a maximum number
of 10 jobs to be in the queue of your system at the same time. If 10 or more
jobs are waiting or running in your queue, qlaunch
will not submit more jobs
until their total number becomes less than 10. If you wish, you can change this
parameter to a different number. In the following, I assume that the qlaunch
process is always working in the background.
After all calculations have been completed, you can launch the script named
2_plot_results.py
in the 0_conv_tests
folder. It will read the output file
that Automag wrote in CalcFold
and it will produce a plot of the parameters
under study versus energy. In addition, the script will also print on screen the
values of the parameters under study for which the error in energy is less than
1 meV/atom with respect to the most accurate result.
The linear response formalism for the calculation of the Hubbard U is based on
the application of a series of small perturbations to the first magnetic atom.
During the whole process, the perturbed atom must be treated independently from
the other atoms of the same species, and we achieve this using a simple trick: we
change the chemical identity of the atom to which we want to apply perturbations
to a dummy atomic species, but we place the POTCAR file of the original atomic
species in the pp
folder corresponding to the dummy atom. For example, if we are
calculating the value of the Hubbard U for Fe in the system Fe12O18 and we choose
Zn as dummy atom, we need to ensure that the same POTCAR file of Fe is used also
for Zn in order to have, instead of Zn, a Fe atom that is treated independently
from the others. This can be achieved with the following commands
cd $VASP_PP_PATH/potpaw_PBE/Zn
mv POTCAR _POTCAR
cp ../Fe/POTCAR .
In this way the Automag code, and in particular the ASE library, will treat the
system as if it was ZnFe11O18, but when they will look for the POTCAR file in the
Zn
folder, they will find the POTCAR of Fe, so the system will remain Fe12O18.
Before launching this calculation, go to the directory 1_lin_response
and set
the necessary parameters in the file input.py
:
poscar_file
is the name of the file in POSCAR format which contains the input geometry and which has been put in the folderautomag/geometries
;dummy_atom
is the name of the dummy atomic species to use for the atom which is subject to perturbations (do not forget to manually put the right POTCAR file in thepp
folder for this atom);dummy_position
is the position of the dummy atom in your POSCAR file (from 0 to N - 1, where N is the number of atoms in the unit cell);perturbations
contains the values of the perturbations to apply to the chosen atom in eV;params
is a collection of VASP parameters to be used during single-point energy calculations.
In addition, the following optional parameters can be specified:
magnetic_atoms
contains the atomic types to be considered magnetic (defaults to transition metals);configuration
is the magnetic configuration to use for U calculation (defaults to ferromagnetic high-spin).
Once the input parameters have been inserted in the file input.py
, you can
launch the script 1_submit.py
in order to save the necessary VASP jobs to the
remote database. You will see that the instance of qlaunch
which is running in
the background will immediately send these jobs to the queue management system
of your cluster. When all calculations are completed, you will find in CalcFold
the file charges.txt
, containing the amount of electrons on the partially
occupied shell of the chosen atom for each value of the applied perturbation,
for both the selfconsistent and the non-selfconsistent runs. Now you can execute
the script 2_plot_results.py
, which will plot the selfconsistent and the
non-selfconsistent responses, it will interpolate them as straight lines to the
least squares and it will calculate their slopes. The value of U is obtained from
U = 1/X - 1/X0, where X and X0 are the selfconsistent and the non-selfconsistent
slopes, respectively.
The search for the ground collinear magnetic state consists in generating a
number of trial configurations and in computing their single-point energy, in
order to determine which is the most thermodynamically stable. The trial
configurations differ from each other only by the choice of the unit cell and by
the initialization of the magnetic moments. Note that the value of the magnetic
moment on each atom can change during the single-point energy calculation.
Automag generates trial configurations by separately initializing each Wyckoff
position occupied by magnetic atoms in a ferromagnetic (FM), antiferromagnetic
(AFM) or non magnetic (NM) fashion, taking into account all possible combinations.
A completely non-magnetic (NM) configuration is also generated. In this way,
overall ferrimagnetic (FiM) states are allowed if the magnetic atoms occupy more
than one Wyckoff position. For each magnetic atom, one or two absolute values for
the magnetization can be given in input. In the first case, the given value is
used for initializing all the spin-up and spin-down states in the configurations
generated by Automag. Conversely, if two separate values are given for high-spin
(HS) and low-spin (LS) states, then each Wyckoff position occupied by that
magnetic atom is separately initialized in a HS or LS fashion, taking into account
all possible combinations. In order to run such a calculation, go to the directory
2_coll
and set the necessary input parameters in the file input.py
:
poscar_file
is the name of the file in POSCAR format which contains the input geometry and which has been put in the folderautomag/geometries
;supercell_size
is the maximum supercell size for generating distinct magnetic configurations, in multiples of the input structure;spin_values
a maximum of two values (HS and LS) of the magnetization in Bohr magnetons for each magnetic atom, used to initialize spin-up and spin-down states;params
is a collection of VASP parameters to be used during single-point energy calculations.
In addition, the following optional parameter can be specified:
lower_cutoff
is the minimum value in Bohr magnetons to which a magnetic moment can fall in order for the corresponding configuration to be used for estimating the critical temperature of the material (defaults to zero).
Once the input parameters have been inserted in the file input.py
, you can
launch the script 1_submit.py
in order to save the necessary VASP jobs to the
remote database. The running instance of qlaunch
will send these jobs to the
queue management system of your cluster. Once all calculations have been
completed, you can launch the script 2_plot_results.py
which will produce a
number of files containing the histogram plot of the obtained energies for all
trial configurations that successfully completed the single-point energy
calculation. The script also prints on screen the name of the configuration
with lowest energy.
Automag can calculate the critical temperature of the magnetically ordered to
paramagnetic phase transition from a Monte Carlo simulation of the effective
Hamiltonian which describes the magnetic interaction. Automag computes the
coupling constants of the corresponding Heisenberg model and provides all the
necessary input files to run the Monte Carlo simulation with the VAMPIRE software
package. The simulation itself needs to be run by the user, while Automag can be
used to plot and to fit the results. The accuracy of the Heisenberg model is
evaluated by computing the Pearson Correlation Coefficient (PCC) between the
DFT energies and the predicted energies of a control group of magnetic
configurations. It is worth noting that this approach can be applied only if all
magnetic atoms have the same absolute value of the magnetization. In order to
estimate the critical temperature with Automag, go to the folder 3_monte_carlo
and set the necessary parameters in the file input.py
:
configuration
is the name of the magnetic configuration to use for the Monte Carlo simulation (usually you want to put here the name of the configuration with lowest energy, obtained at the previous step);cutoff_radius
is the maximum distance between two magnetic atoms to be considered as interacting neighbors;control_group_size
is the relative size of the control group used to evaluate the accuracy of the Heisenberg model;append_coupling_constants
is a boolean flag which tells Automag whether or not to append the computed values of the coupling constants to the fileinput.py
, which are needed by the script2_write_vampire_ucf.py
.
In addition, the following optional parameter can be specified:
magnetic_atoms
contains the atomic types to be considered magnetic (defaults to transition metals).
Once the input parameters have been inserted in the file input.py
, you can
launch the script 1_coupling_constants.py
. It will compute the coupling
constants for the given cutoff radius and it will print their values on screen.
In addition, it will create a file model.png
, which contains a plot of the
Heisenberg model energies versus the DFT energies for all the configurations in
the control group. The values of the distances between neighbors, the amounts of
neighboring pairs of magnetic atoms in the unit cell at each distance and the
value of the PCC are also printed on screen.
We suggest to run the script 1_coupling_constants.py
a couple of times with the
append_coupling_constants
flag set to False
and with different values of the
cutoff_radius
, in order to investigate how many neighbors you need to include
for obtaining a well-converged Heisenberg model. Once you are satisfied with the
model's accuracy, run the script a last time with the append_coupling_constants
flag set to True
and Automag will append the values of the coupling constants
and the distances between neighbors to the file input.py
. Now you are ready to
run the script 2_write_vampire_ucf.py
, which will read the file input.py
and
will produce a VAMPIRE unit cell file vamp.ucf
. Now you can run VAMPIRE on your
cluster using the unit cell file written by Automag, an input file and a material
file specific for your problem. Automag contains a sample input file and a sample
material file in the folder 3_monte_carlo/vampire_input
, which can be simply
edited and adapted to the problem under study. Once the VAMPIRE run is done, you
can copy the output
file in the folder 3_monte_carlo
and run the last script
3_plot_results.py
. It will produce a plot of the mean magnetization length (of
the spin-up channel for antiferromagnetic materials) versus temperature obtained
from the Monte Carlo simulation and it will fit the data using the analytical
expression of the mean magnetization length, obtaining the values of the critical
temperature and of the critical exponent. The fitted values of these two
parameters are printed on screen.