Example:

                
obj.lattice.lat_const = [3 3 4];
                
                

                
obj.genlattice('lat_const',[3 3 4], 'sym', 1,'angled',[90 90 120]);
                
                

The crystal lattice information is stored in spinw.lattice , to define the parameters use:

• spinw.genlattice() with options: lat_const, angle, angled, sym
• sym option accept name of space group or symmetry operators in matrix

The symmetry inequivalent atoms are stored in spinw.unit_cell with following parameters:

• position in lattice units in r
• spin quantum number in S
• string label with magnetic form factor definition (FullProf convention, e.g. MCr3 for Cr$^{3+}$ ions)
• color for plotting (RGB code for each atom)

To define the atoms use:

• spinw.addatom() function with options as above
• function checks the validity of the input and has default values (e.g. S can be generated from the label)
• defines magnetic form factor

Magnetic lattice is dynamically generated from:

• unit cell parameters (a, b, c, angles) stored in spinw.lattice
• magnetic atoms (S>0) stored in spinw.unit_cell
• space group stored in spinw.lattice.sym

The function M = spinw.matom() generates the positions:

• we call the number of magnetic atoms in the unit cell: nMagAtom
• position in l.u. in M.r
• index pointing to the atom in spinw.unit_cell stored in M.idx
• spin quantum number stored in M.S

The space group generators are stored in the symmetry.dat file, and spinw.lattice.sym stores all symmetry operators of the space group

The first nMagAtom magnetic moment directions stored in spinw.mag_str.S are corresponding to the magnetic lattice generated by spinw.matom().

The generators of the 230 space group with standard settings are stored in symmetry.dat.

• to add a new setting or permute axes, use
  sym = swsym.add(symStr, {symName})
• use the line number in spinw.lattice.sym
• P0 $\neq$ P1

The space group is used:

• generate the atomic positions $\rightarrow$ ALWAYS
• determines equivalent bonds
• allowed terms in the magnetic Hamiltonian
• magnetic structure? Not yet

If symmetry is off for bonds, the equivalent bonds will be generated based on length.

Reduce symmetry:

• spinw.no_sym() removes all symmetries $\rightarrow$ P0 and repopulates spinw.unit_cell with all the originally generated positions.
• {T} = spinw.newcell(bvect, {bshift}) creates a new unit cell and reduce the symmetry to P0 and return the transformation matrix: Qrlu_new = T * Qrlu_old

This will be covered in the symmetry presentation.

Symmetry Presentation

3x3 matrices can be stored in the spinw.matrix field:

• values are stored in a 3x3xnMat matrix (mat subfield)
• label and color stores corresponding label and color for plotting

These matrices are really just numbers. They will be part of the Hamiltonian once they are assigned to a single ion anisotropy, g-tensor or exchange coupling.

To add new matrix use spinw.addmatrix().

The matrix value is given in the mat option:

• single number gives Heisenberg interaction, e.g. mat = J1
• vector gives a Dzyaloshinskii-Moriya interaction, e.g. mat = [D1 0 D2]
• generall accept 3x3 matrices, e.g. mat = diag([Jxy Jxy Jz])

Each matrix can be referenced by its index (e.g. mat(:,:,idx)) or by ist label (e.g. J1).

Bonds are stored in spinw.coupling field:

• each bond is defined by the index of 2 interacting magnetic atoms of the magnetic lattice...
• ... and a translation vector in lattice units (dl)
• the bond has a direction: matom.r(:,atom1) $\rightarrow$ matom.r(:,atom2) + dl
• each bond has an increasing index (idx), starting with 1
• equivalent bonds have the same index
• each bond can have a pointer to 3 different matrices that define the J value (mat_idx)

The bonds are generated from the magnetic lattice and the space group (if any) using the spinw.gencoupling() method:

• maxDistance option determines the maximum bond length that will be generated
• can generate up $10^6$ bonds/s, can be used for very large unit cell for dipole-dipole interaction

To assign a matrix to a bond use spinw.addcoupling():

• assigned matrix is given by a matrix label or index (option mat)
• bond can be given by an index (option bond)
• sub indices can be also given (option subIdx)

Single ion

g-tensor and external field values are stored in spinw.single_ion.

Subfields:

• aniso single ion anisotropy is stored with 1xnMagAtom and a pointer to a matrix
• g g-tensor is nMagAtom
• field stored as a row vector

To assign anisotropy use spinw.addaniso(matLabel,{atomIdx}) with matrix label and optional atom indices of labels.

Similar function spinw.addg().

Magnetic structure is stored in the spinw.mag_str field.

It can store arbitrary magnetic structures using Fourier components.

Subfields:

• magnetic supercell in l.u. stored in nExt
• k-vector(s) stored in k
• Fourier transform of the spin expectation value in F

The number of magnetic moments stored in F are: nMagExt = prod(nExt)*nMagAtom

The experimental magnetization can be obtained by multiplying F with the g-tensor!

For spin wave calculation, the complex magnetic structure is converted to the rotating frame representation using the spinw.magstr() function.

Output of spinw.magstr() is a struct with fields:

• size of magnetic supercell in l.u. stored in nExt
• single k-vector stored in k
• vector normal to the spiral plane is stored in n
• real magnetic moment directions (spin quantization axis) are stored in S

The representation allows an additional k=0 component parallel to n, however this is rarely used.

The conversion from Fourier components to rotating frame representation is not always possible, in this case magstr() gives the best approximation and gives a warning. The conversion is approximate:

• multi-k structures
• non-Bravais lattice with counter-rotating incommensurate spirals
• non-Bravais lattice with non-coplanar spirals
• non-Bravais antiferromagnet with non-coplanar moments

This will be covered in the magnetic structure presentation.

Magnetic Structure Presentation

The spin Hamiltonian from LSWT:

$$H = \sum_{mi, mj} S^{T}_{mi}J_{mi, nj}S_{nj} + \sum_{mi}S^{T}_{mi}A_{i}S_{mi} + \mu_BH^{T}\sum_{mi}g_iS_{mi}$$

Identify the symbols:

• ($m$,$n$) unit cell indices: SpinW only stores the (0,0) cell the rest is taken care by a Fourier- transformation
• ($i$,$j$) index of the magnetic atom on the magnetic supercell
• $S_{mi}$ are stored in spinw.mag_str.S
• $J_{mi, nj}$ are given by:
  • spinw.coupling.atom1 $\rightarrow$ $i$
  • spinw.coupling.atom2 $\rightarrow$ $j$
  • spinw.coupling.dl $\rightarrow$ $m-n$
  • spinw.matrix.mat(:,:,spinw.coupling.mat_idx) $\rightarrow$ $J$
• $H$ is given by spinw.single_ion.field

swSpec = spinw.spinwave({Q1 Q2 nQ})

• Solves the general Hamiltonian
• Commensurate and incommensurate magnetic structures
• Calculates the spin-spin correlation function in xyz coordinate system:

$$ S^{\alpha\beta}(k, \omega) $$
• Two methods:
  • diagonalizing Hermitian matrixa $\rightarrow$ fast but only for strictly positive definite matrices
  • diagonalizin non-Hermitian matrixa $\rightarrow$ bit slower, but works for non positive definite matrices
• $Q$ can be a $3\cdot nQ$ matrix or cell that defines linear scans between points

There are a few important options:

formfact

• true: Includes magnetic form factor stored in spinw.unit_cell
• false: Magnetic form factor is not considered.

gtensor

• true: g-tensor is included in the spin-spin correlation function.
• false: g-tensor is not considered

hermit

• true: Colpa method is used.
• false: White method is used

usemex

• true: Use compiled code for speedup (especially for small magnetic unit cells)
• false: Use MATLAB JIT code

swSpec = spinw.spinwave({Q1 Q2 nQ})

swSpec structure for commensurate structures:

• .omega- D:$[2\cdot nMagExt, nHkl]$, dispersion at every Q-point
• .Sab- D:$[3, 3, 2, \cdot nMagExt, nHkl]$, 3x3 correlation function for every omega and Q
• .hkl- D:$[3, nHkl]$, Q points in r.l.u.
• .hklA- D:$[3, nHkl]$, Q points in $\unicode{x212B}^{-1}$, xyz coordinate system
• .incomm- Whether the spectrum is calculated in incommensurate mode.
• .obj- Copy of the input spinw object.

If there are several crystallographic twins, .omega and .Sab are packaged into a cell that contains nTwin number of matrices.

For incommensurate magnetic structures nHkl is tripled: $(k-k_m,k,k+k_m)$.

swSpec = sw_neutron(swSpec, ‘pol’,true,’uv’,{u1 v1})

Calculates the polarised/unpolarised neutron scattering cross section.

New fields:

• .Sperp- D:$[2\cdot nMagExt, nHkl]$, neutron scattering intensity for each .omega and Q
• .intP- D:$[3, 2, \cdot nMagExt, nHkl]$, polarised intensity
• .Pab- D:$[3, 3, 2\cdot nMagExt, nHkl]$, polarisation matrix for every mode and Q
• .Mab- D:$[3, 3, 2\cdot nMagExt, nHkl]$, spin-spin correlation function in the Blue-Maleev coordinate system ($x\parallel Q$, $y$ in scattering plane, $z$ vertical)

swSpec = sw_egrid(swSpec, ‘component’,{’Sxx’ ‘Syy’},’Evect’,E)

Convolutes selected elements of the spin-spin correlation function.

• ‘component’: selects either a single element: ‘Sperp’, ‘S$_{xx}$+S$_{yy}$+S$_{zz}$’, ‘S$_{xx}$’, etc. or several components to compare: {‘S$_{xx}$’, ‘S$_{yy}$’}, etc.
• 'Evect': energy bin (bin edges)

New fields:

• .swConv- D:$[nE, nHKL]$, convoluted spectrum
• .swInt- D:$[nMode, nHKL]$, polarised intensity

swSpec = sw_instrument(swSpec, ‘dE’,dE1, ‘dQ’, dQ1, ...)

Introduces instrumental and other factors to the convoluted spectrum.

• Finite energy and Q resolution (Gaussian).
• ($k_i$, $Theta_{Min}$) to calculate the measurable ($E$,$Q$) volume.
• energy transfer dependent energy resolution for TOF.
• 'norm':true to normalize the spectrum to mbarn/meV/cell units

New fields:

• .swRaw- D:$[nE, nHKL]$, original convoluted spectrum
• .norm
• .ki
• .dE
• .dQ