While not strictly needed for the conversion to C++ of the spin-wave dispersion calculation, refactoring the magnetic structure definition of the spinw object (currently a struct with elements F for the basis, k for the propagation vector and nExt for the super cell size) is desirable for future translation into Python.

The basis spinw.mag_str.F is an array of complex 3-vectors (one vector per spin [indexed j] in the first unit cell / supercell). The general j th moment of a unit cell at t from the first unit cell is:

Note that spinw only supports a single k (propagation) vector (usually the above formula is a sum over different k each of which can have a different basis).

Whilst the above is a general representation of all single-k magnetic structures, what SpinW actually uses is a rotating frame representation with a real magnetisation vector M which rotates within a plane defined by a plane normal n and phases phi between equivalent atoms in different unit cells. The method spinw.magstr() (note no underscore) calculates this rotating frame representation and it is this representation which is used in the spin wave calculation (although other parts of SpinW use the Fourier representation described by the above equation).

Currently there is a magnetic_structure class but it is a very confused object. It was aimed at the spin wave calculation only so takes as its input the (transformed by spinw.magstr()) rotating frame representation and defines two methods (get_local_basis() and transform_frame() which is needed by spin wave calculation itself. This issue is to extend and refactor this class to be a general magnetic structure class for SpinW.

As such, it should first be refactored to use the Fourier representation (or to be constructable with the Fourier representation). Then there should be a method (basically moving spin.magstr() into magnetic_structure) to convert to a rotating frame representation.

The constructor should also accept arguments similar or the same as what the spinw.genmagstr() currently accepts (so that genmagstr() can just call straight through to the magnetic_structure constructor.

Required parts for this work are:

• Refactor current sw_classes.magnetic_structure class to use Fourier basis but to still be able to calculate and export the real magnetisation and rotation plane perpendicular vector on demand
• Add a constructor which mirrors spinw.genmagstr()
• Update functions which currently uses the rotation frame representation to use the methods / properties of magnetic_structure.
• Update functions which currently sets elements of the (Fourier representation) spinw.mag_str structure directly to use setters in the new class.
• Update the spinw.mag_str property and spinw.magstr() method to use sw_classes.magnetic_structure

Completed when:

• A parallel implementation of spinwave.m in C++ (with mex interface) exists which passes CI tests.

Depends on #7

We're planning to use github self-hosted runners for continuous integration. (The runners, have to be self-hosted because we need to use Matlab.)

This implies a security issue if the repository is public. One way around this is to use containers where a fresh instance of the container is used for each job. One idea for doing this is with vagrant boxes which are packaged virtual machines. Hopefully we can run Linux, Windows and Mac OS instances from a single (Linux) server.

The workflow would be:

1. Manually start boxes for each OS.
2. They run the self-hosted runner server and wait for a job request.
3. Run the CI job.
4. At the end of the job, trigger a web-hook
5. Web-hook triggers the shutdown of the current instance and launches another instance.
6. New instance runs self-hosted runner server and waits for a job request.

Complete when there are unit tests that covers 80% of the core calculation code.

There should be several tests which checks the code flow within the spin_wave_calculator class dependent on input.

Object setup

For the tests, a very simple model should be used. I recommend using a linear spin chain with the spin magnitude set to 1 (e.g. like in tutorial 1:

model = spinw;
model.genlattice('lat_const', [3 8 8], 'angled', [90 90 90]);
model.addatom('r', [0 0 0],'S', 1, 'label', 'MCu1', 'color', 'blue');
model.gencoupling('maxDistance', 7);
model.addmatrix('value', -eye(3), 'label', 'Ja', 'color', 'green');
model.addcoupling('mat', 'Ja', 'bond', 1);
model.genmagstr('mode', 'direct', 'k', [0 0 0], 'n', [1 0 0], 'S', [0; 1; 0]);

This model has a particularly simple dispersion - a single mode with energy omega = 2*(1-cos(2*pi*qh)) (see Kittel, chapter 12, eq 22, but note that Kittel defines the Hamiltonian in eq 12 as -2Jsum_ij(Si.Sj) whereas in SpinW the prefactor of 2 is not included; also note that we've set the exchange integral to be 1 in the addmatrix command).

A non-Hermitian model can be setup by changing the magnetic structure to be antiferromagnetic instead:

model.genmagstr('mode', 'direct', 'nExt', [2 0 0], 'S', [0 0; 1 -1; 0 0]);

An incommensurate model can be setup by using the fourier mode and changing the k parameter:

k_incomm = 0.123;
model.genmagstr('mode', 'fourier', 'k', [k_incomm 0 0], 'n', [1 0 0], 'S', [0; 1; 0]);

Note that this would also give a non-Hermitian Hamiltonian because we have a ferromagnetic exchange interaction which would prefer all the spins to be parallel and this structure does not have that.

Possible tests

General tests for twins and incommensurate cases

1. Test that twined input structures give cell arrays as output and number of cells match number of twins
2. Test that incommensurate input structures give the correct number of output modes (6 times the number of atoms in the unit cell; a normal (commensurate) structures has 2*nMagExt number of modes, an incommensurate structure should have three times this, so 6*nMagExt number of modes)

More specific test for the twins case

For each twin, the user gives a 3x3 transformation matrix which is applied to the input hkl q-vectors. A test could do something like this:

1. Run through the calculation with only a single hkl vector (pick any 3 values) -> orig_single output spectra
2. Run the calculation again with the transformed rotmat * hkl vector -> transformed_single output spectra
3. Run the calculation with the original hkl but with the twins set -> twinned output spectra
4. Check the output omega field of the twinned output spectra is a cell with two elements (one for each twin, the first being the identity)
5. Compare the first element of the output omega field of twinned with the omega of orig_single.
6. Compare the second element of the output omega field of twinned with the omega of transformed_single.

Test for the form factor option

The magnetic form factor is a hkl-vector dependent scaling factor on the output neutron intensity. The test here would be to:

1. Run the calculation with a range of hkl without the formfactor option set to false -> spec_no_ff
2. Run the calculation with the formfactor option set to true -> spec_ff
3. Compare spec_no_ff.swConv * ff and spec_ff.swConv.

Note, the swConv property is only generated after running sw_egrid(sw_neutron(spectra)).

Test that the correct calculation is run for the hermit option

There are two different matrix diagonalisation algorithms in SpinW - one which explicit requires a positive definite matrix which is used when hermit is true (that is, the Hamiltonian matrix must not be hermitian but its eigenvalues must also be strictly positive); and a second algorithm which works for any matrix but can give imaginary eigenvalues (e.g. unphysical spin wave energies) when the hermit option is set to false.

The test here is to define the input such that we are sure that Hamiltonian matrix would not be Hermitian and run the calculation with hermit set to true and check that it gives an error. Then run the test with hermit set to false and check that no error is thrown and that omega has imaginary values.

Set up continuous integration.

Must:

• Have Matlab
• Be public (viewable)
• Run on Windows, Linux and Mac OS X

Sub issues: #5

Serial C++ implementation of spinwave.m with a mex interface which can be run using existing API / tests.

Complete when:

• A C++ implementation of spinwave.m exists which passes CI tests.

Currently, there is a single large class spinw with several large methods / functions - especially spinwave.m.

To make it easier to port to C++ and also to write unit tests for (system tests already exist), this code should be refactored to be more object oriented, and the code split into more modular blocks / methods.