Model¶

In short SpinW can solve the following spin Hamiltonian using classical and quasi classical numerical methods:

where \(\mathbf{s}_i\) are spin vector operators, \(J_{ij}\) are 3x3 exchange matrices describing coupling between spins, \(A_{ij}\) are 3x3 single ion anisotropy matrices, \(\mathbf{B}\) is external magnetic field, \(g_i\) are the g-tensors with 3x3 elements and \(\mu_B\) is the Bohr-magneton. The 3x3 matrices are necessary to include all possible anisotropic and antisymmetric interactions.

Features¶

Properties¶

The output of the previous command shows all the data fields of model1. Each data field has an initial value and any of them can be modified directly:

model1.lattice.lat_const = [3 5 5];

The above command directly modifies the lattice parameters of the lattice. Modifying propoerties directly is quick and very flexible but prone to error. The most common mistake is that the new values are not the same data type as the original ones. For example the field that stores the lattice space group is integer type:

class(model1.lattice.sym)

Thus if we want to change it directly, we need an integer number:

model1.lattice.sym = int32(5);

This will change the crystal space group to ‘C 2’. To avoid most common mistakes, there are several methods (functions) for modifying the above properties that also perform additional error checking and makes certain input conversions. For example all lattice related properties can be modified using the genlattice() function:

model1.genlattice('lat_const',[3 5 5],'sym','C 2','angled',[90 90 90])

The alternative usage of the above function is the following:

genlattice(model1,'lat_const',[3 5 5],'sym','C 2','angled',[90 90 90])

This reflects better the input argument structure. The first argument is the sw object ‘model1’. After the first argument comes option name and value pairs. The first options is ‘lat_const’ and the value it expects is a vector with 3 elements if the input vector has different length, the function throws an error. The second option is ‘sym’ that also accepts string input (name of the space group) that is automatically converted to the index of the space group and stored in model1:

model1.lattice.sym

The last option is ‘angled’ that requires a vector with three elements and defines the alpha, beta, gamma lattice angles in degree. This will be converted into radian and stored:

model1.lattice.angle

List of properties¶

The sw object properties store all the information necessary for the spin wave calculation. There are eight public properties of the sw class each with several subfields:

• sw.lattice
• sw.unit_cell
• sw.twin
• sw.matrix
• sw.single_ion
• sw.coupling
• sw.mag_str
• sw.unit

sw.lattice¶

The lattice field stores the lattice parameters and space group information. The subfields are:

lat_const

Lattice constants in a row vector with three elements (\(a\), \(b\) and \(c\)) in Å units.

angle

\(\alpha\), \(\beta\) and \(\gamma\) angles in a row vector with three elements in radian units.

sym

Crystal space group, single integer (int32 type) that gives the line number in the symmetry.dat file. This file stores the generators of the space group and by default contains the 230 crystallographic space groups with standard settings.

See also sw.genlattice(), sw.abc(), sw.basisvector(), sw.nosym().

sw.unit_cell¶

The unit_cell field stores the information on the atoms in the crystallographic unit cell. Subfields are:

r

Atomic positions in lattice units, matrix with dimensions of [3 nAtom], in lattice units.

S

Spin (or angular momentum) quantum number of the atoms, row vector with nAtom number of elements. Non-magnetic atoms have \(S=0\).

label

String label of the atoms in a cell with dimensions of [1 nAtom].

color

Color of the atoms for plotting. Stored in a matrix with dimensions of [3 nAtom], every column is an RGB code (int32 numbers between 0-255).

See also sw.addatom(), sw.atom(), sw.matom(), sw.newcell().

sw.twin¶

The twin field stores information on crystallographic twins. The subfields are:

rotc

Rotation matrices in the xyz coordinate system for every twin, stored in a matrix with dimensions of [3 3 nTwin].

vol

Relative volume of the twins, stored in a row vector with nTwin elements.

See also sw.addtwin(), sw.twinq(), sw.ntwin().

sw.matrix¶

The matrix field stores 3x3 matrices that can be referenced in the magnetic Hailtonian. The subfields are:

mat

It stores the actual values of 3x3 matrices stacked along the third dimension with dimensions of [3 3 nMat].

color

RGB color codes assigned for every matrix, stored in a matrix with dimensions of [3 nMatrix], each column is an [R;G;B] code with int32 numbers between 0 and 255.

label

Label for every matrix, stored as strings in a cell with dimensions of [1 nCell].

See also sw.addmatrix(), sw.getmatrix(), sw.setmatrix().

sw.single_ion¶

The single_ion field stores the single ion expression of the Hamiltonian. The subfields are:

aniso

Row vector contains nMagAtom integers, each integer assignes one of the matrices from the sw.matrix field to a magnetic atom in the sw.matom() list as a single ion anisotropy. Zero means no assigned anisotropy matrix.

g

Row vector of nMagAtom integers, each integer assignes one of the matrices from the sw.matrix field to a magnetic atom in the sw.matom() list as a g-tensor.

field

External magnetic field stored in a row vector with the 3 components in the xyz coordinate system, default unit is Tesla.

T

Temperature, scalar, default unit is Kelvin.

See also sw.addaniso(), sw.addg(), sw.getmatrix(), sw.setmatrix(), sw.intmatrix(), sw.field().

sw.coupling¶

The coupling field stores the list of bonds. Where each bond is defined between two magnetic atom. Each bond has a direction, it points from atom 1 to atom 2. In the subfiels every column defines a bond, the subfields are:

dl

Translation vector between the unit cells of the two interacting spins, stored in a matrix of integer numbers with dimensions of [3 nCoupling].

atom1

Stores the index of atom 1 for every bond pointing to the list of magnetic atoms in sw.matom() list, stored in a row vector with nCoupling elements.

atom2

Index of atom 2 for each bond.

mat_idx

Integer indices selecting exchange matrices from sw.matrix field for every bond, stored in a matrix with dimensions of [3 nCoupling]. Maximum three matrices per bond can be assigned (zeros for no coupling).

idx

An integer index for every bond, an increasing number with bond length. Symmetry equivalent bonds have the same index.

See also sw.gencoupling(), sw.addcoupling().

sw.mag_str¶

The mag_str field stores the magnetic structure. It can store single-Q structures or multi-Q structures on a magnetic supercell. Strictly speaking it stores the expectation value of the spin of each magnetic atom. The magnetic moment directions are given by \(g_i\cdot \langle S_i\rangle\). The subfields are:

S

It stores the spin directions for every magnetic atom either in the crystallographic unit cell or in a magnetic supercell in a matrix with dimensions of [3 nMagExt]. Every column stores \(\langle S_x\rangle, \langle S_y\rangle, \langle S_z\rangle\) spin components in the xyz coordinate system. The number of spins in the supercell is:

nMagExt = nMagAtom*prod(mag_str.N_ext);

k

Magnetic ordering wave vector stored in a row vector with 3 components in reciprocal lattice units. Default value is [0 0 0].

n

Normal vector to the rotation of the moments in case of non-zero ordering wave vector (single-Q magnetic structures), row vector with three elements. The components are in the xyz coordinate system. Default value is [0 0 1].

N_ext

Dimensions of the magnetic supercell in lattice units stored in a row vector with three elements. Default value is [1 1 1] if the magnetic cell is identical to the crystallographic cell. The three elements extends the cell along the \(a, b, c\) axes.

See also sw.genmagstr(), sw.optmagstr(), sw.anneal(), sw.nmagext(), sw.structfact(), sw.optmagsteep().

sw.unit¶

The unit field stores the conversion factors between energy, magnetic field and temeprature units in the Hamiltonian. Defaults units are meV, Tesla and Kelvin for energy, magnetic field and temperature respectively. To use identical units for energy, magnetic field and temperature use 1 for each subfields. The subfields are:

kB

Boltzmann constant, default value is 0.0862 meV/K.

muB

Bohr magneton, default value is 0.0579 meV/T.

Methods¶

In line with the above example the general argument structure of the method functions is one of the following:

function(obj,'Option1',Value1,'Option2',Value2,...)
function(obj,Value1,Value2,...)

The first type of argument list is used for functions that require variable number of input parameters with default values. The second type of argument structure is used for functions that require maximum up to three fixed input parameter. Every method has help that can be called by one of the following methods:

• selecting the function name in the Editor/Command Window and pressing F1

• in the Command Window typing for example:

  help sw.genlattice
  

This shows the help of the genlattice() function in the Command Window. To open the help in a separate window you need to write:

doc sw.genlattice

To unambiguously identify the functions it is usefull to refer them as sw.function() this way matlab knows which function to select from several that has the same name. For example the plot() funcion is also defined for the sw class. However by writing:

help plot

we get the help for the standard Matlab plot function. To get what we want use:

help sw.plot

By the way this function is one of the most usefull ones. It can show effectively all information stored in the sw object by plotting crystal structure, couplings, magnetic structure etc. Calling it on an empty object shows only the unit cell:

plot(model1)

Plot of empty sw object.

As you might noticed, there is an alternative calling of any method function: obj.function(...), this is just equivalent to the previous argument structures.

Copy¶

The sw class belong to the so called handle class. It means in short that the model1 variable is just a pointer to the memory where the class is stored. Thus by doing the following:

model2 = model1;

will only duplicate the pointer but not the values stored in the sw object. Thus if I change something in model1, model2 will change as well. To clone the object (the equivalent of the usual ‘=’ operation in Matlab) the sw.copy() function is necessary:

model2 = copy(model1);

Lattice units (lu) coordinate system¶

This is the lattice coordinate system. The three axis are the a, b and c crystal axes. For example the vector [0,1,0] denotes a position translated from the origin by b vector. The following sw class properties are stored in lattice units:

• atomic positions (sw.unit_cell.r)
• translation vectors for bonds (sw.coupling.dl)

Also several function takes input or output in lattice units:

• atomic positions of the output of matom() and atom() methods of sw
• magnetic moments can be given in lattice units for the genmagstr() function (using the ‘unitS’ option with ‘lu’ value)
• calculated bond vectors from couplingtable()

xyz coordinate system¶

Most of the sw class properties are stored in the xyz coordinate system. The xyz coordinate system is right-handed Cartesian and fixed to the crystal lattice:

• x: parallel to a-axis,
• y: perpendicular to x and in the ab-plane,
• z: perpendicular to xy-plane

The following properties are in the xyz coordinate system:

• twin rotation matrices (sw.twin.rotc)
• stored 3x3 matrices (sw.matrix.mat)
• magnetic field (sw.single_ion.field)
• magnetic moment components (sw.mag_str.S)
• normal vector of the magnetic structure (sw.mag_str.n)

Also output of several functions are in xyz coordinate system:

• spin-spin correlation function matrix elements calculated by spinwave() method (spec.Sab matrices)
• interaction matrices calculated by couplingtable()

Vectors in reciprocal space in Å\(^{-1}\) units are also in a right handed Cartesian coordinate system:

• momentum transfer values in Å\(^{-1}\) reciprocal lattice units of the spec.hklA output of the spinwave() function

Reciprocal lattice (rlu) coordinate system¶

The reciprocal lattice coordinate system is the dual vector space of the lattice coordinate system. The three axis are the reciprocal lattice vectors denoted by a\(^*\), b\(^*\) and c\(^*\). The following sw class properties are stored in rlu units:

• magnetic ordering wave vector (sw.mag_str.k)

Also several function takes input in rlu units:

• the sw_neutron() function takes the option ‘uv’, that defines the scattering plane by two vectors in rlu
• the first input of the spinwave() function is a list of Q points in rlu units

Transformation between coordinate systems¶

To transform vectors and tensors between the above coordinate systems, the output of basisvector() function can be used:

tri = sw;
tri.genlattice('lat_const',[3 3 5],'angled',[90 90 120])
BV = tri.basisvector

The BV 3x3 matrix contains the coordinates of the lattice vectors as column vectors: [a b c]. To convert vectors from the abc coordinate system to the xyz, we can do the following:

r_abc = [1/2 1/2; 0];
r_xyz = BV * r_abc