Add ADR proposal and LSWT draft

docs/developers/adr/001_use_atomic_simulation_environment.md

@@ -0,0 +1,35 @@
+# PySpinW will use the Atomic Simulation Environment as a dependency
+
+## Context
+
+The [Atomic Simulation Environment](https://wiki.fysik.dtu.dk/ase/) is a Python library for setting up, running, visualizing and analyzing atomistic simulations.
+Primarily, it supports `calculators` based on density function theory or force fields.
+In most cases these codes are not written in Python but `ase` provides an interface to drive the calculations from Python.
+In particular it has an `Atoms` [class](https://wiki.fysik.dtu.dk/ase/ase/atoms.html) which embodies a collection of atoms which can be the lattice which SpinW calculations need.
+Each `Atom` in an `Atoms` object has a `position` and magnetic moment `magmom`, as well as `charge` and `mass` which SpinW does not need.
+Most importantly, the `Atoms` can be visualized using the `ase.visualize.view` [function](https://wiki.fysik.dtu.dk/ase/ase/visualize/visualize.html)
+which provides an internal viewer (`ase.gui`) as well as interface to a variety of external viewers.
+Finally, there is a spacegroup package with a `crystal` [constructor](https://wiki.fysik.dtu.dk/ase/ase/spacegroup/spacegroup.html) which creates an `Atoms` object with a particular space group symmetry.
+Thus much of the functionality provided by the current `genlattice` and `addatom` methods could be outsourced to `ase` reducing the amount of code needed to be written in PySpinW.
+
+
+## Decision
+
+We will use the [Atomic Simulation Environment](https://wiki.fysik.dtu.dk/ase/) as a dependency in PySpinW to handle constructing and manipulating a lattice.
+
+
+## Status
+
+Proposed
+
+
+## Consequences
+
+This adds a significant dependency to the project. The possible downsides are:
+
+* Needing to adapt spinw code to the `Atoms` class which may not be flexible enough for our needs.
+* Risk that the `ase` project becomes abandoned (considered low as it has a large user base and an STFC staff member is a contributor).
+
+The advantages is:
+
+* Saving a large amount of coding in order to write a `Lattice` class or the lattice handling part of the `spinw` class.

docs/developers/adr/README.md

@@ -0,0 +1,39 @@
+# Architectural Decision Records
+
+Significant architectural choices in the PySpinW project will use this workflow:
+
+1. A pull request which creates a new markdown file in this folder with the proposed architectural design choice is opened.
+2. Detailed design documentation supporting the decision will be placed separately into markdown files in the [design](../design) folder and should be referenced in the ADR file.
+3. Project members and interested parties will comment on the pull request. If discussion meetings were convened about the decision, they should be minuted or summarised in comments on the PR.
+4. The MD file is modified in light of the comments.
+5. The PR is merged or closed without merging. Merging the PR signals that the proposed design decision is accepted.
+
+
+## File name format
+
+The files in this folder should named as `NNN-<short-title>` where `NNN` is a sequential number.
+
+
+## Template
+
+ADRs in PySpinW will use the template suggested in [this blog post](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html):
+
+```
+# Title
+
+## Context
+
+Detailed information should refer to design documents in the [design](../design) folder.
+
+## Decision
+
+"We will..."
+
+## Status
+
+Proposed / Accepted / Deprecated / Superseded
+
+## Consequences
+```
+
+The ADR file should be short - not more than approximately one page if printed out. Detailed designs should be in the [design](../design) folder.

docs/developers/design/001_linear_spinwave_theory.md

@@ -0,0 +1,95 @@
+# The Maths behind Linear Spin Wave Theory Calculations
+
+This documentation describes the maths behind linear spin wave theory calculations as implemented in the (Matlab) [SpinW](https://github.com/spinw/spinw) code.
+A fuller description can be found in the papers of [S. Petit (2011)](https://doi.org/10.1051/sfn/201112006) and [Toth and Lake (2015)](https://doi.org/10.1088/0953-8984/27/16/166002).
+(We shall mostly be using the notation of Petit as this is what is used in the SpinW Matlab code).
+
+
+## Introduction
+
+Spin waves are collective excitations (normal modes) of a lattice of atomic spins
+(atoms with unfilled electronic shells and hence a net magnetic moment) coupled by exchange interactions.
+These excitations can be described using a semiclassical approach using an equation of motion in which
+the internal magnetic field generated by the moment on one atom causes a torque on its neighbour. [citation needed]
+The resulting wave is a precession of the spins about their ordered direction, with a net phase between site.
+Another way of thinking about these excitations is as (quantised) quasiparticles in a field theory.
+This is "linear spin wave theory" and its quasiparticles are "magnons".
+
+
+## The Holstein-Primakoff transformation
+
+Consider a single atom with total spin quantum number $S$, which can be in states labelled by $`S_z=-S,-S+1,...,S-1,S`$.
+In the ordered state, this spin is in the state with maximum $`S_z=S`$.
+A small deviation from this (i.e. initiating a spin wave) will change the state to $`S_z=S-1`$.
+This can be described by the spin lowering operator $`\hat{S}^-`$.
+Likewise, restoring the ordered state from this deviation is described by the spin raising operator $`\hat{S}^+`$.
+
+Now, the _Holstein-Primakoff_ transformation is a mapping between these lowering and raising operators
+to bosonic creation $`\hat{b}^{\dagger}`$ and annihilation $`\hat{b}`$ operators as follows (we drop the hats):
+
+```math
+S^+ = b \hbar \sqrt{2S - b^{\dagger}b} \\
+S^- = b^{\dagger} \hbar \sqrt{2S - b^{\dagger}b} \\
+S^z = \hbar (S - b^{\dagger}b)
+```
+
+The number of magnons is $`b^{\dagger}b`$ and $`S_z`$ is the projection of the spins along the local ordered moment direction.
+We thus see that when no magnons are excited this corresponds to the fully ordered state,
+and that as more magnons are excited the spins become canted perpendicular to this direction,
+as the ladder (raising/lowering) operators can be related to the $x$ and $y$ spin components by $`S^{\pm} = S^x \pm iS^y`$.
+
+The term in the square root is usually expanded in a Taylor series in practical calculations,
+and usually only the first order (linear) term is retained which is equivalent to neglecting the $`b^{\dagger}b`$ term in the square root.
+This is strictly only valid when $2S$ is large (to see this, rearrange to get $`\sqrt{1-b^{\dagger}b/2S}`$).
+Thus, _linear spin wave theory_ is said to be only valid for large $S$ systems.
+
+
+## Local spin directions
+
+We see in the above that mapping to the bosonic operators $`b^{\dagger}, b`$ requires the Hamiltonian
+to be described in terms of the local spin ordered moment direction, since it describes small deviations from this direction.
+
+We thus define a set of rotation matrices $`R_i^{\alpha}`$ which transforms a spin vector $`\mathbf{S}'_i`
+in the local coordinate system (where $z$ is along the ordered moment direction)
+to a vector $`\mathbf{S}_i`$ in a Cartesian coordinate system connected to the crystal lattice:
+(In SpinW, this Cartesian system is defined by $x||a$, $z$ perpendicular to $a$ and $c$ and $y$ perpendicular to $x$ and $z$).
+
+```math
+\mathbf{S}_i = R_i \mathbf{S}'_i
+```
+
+where $`R_i`$ is a $3 \times 3$ matrix.
+Additionally, to more easily map to the operators $S^z$, $S^-$ ($b^{\dagger}) and $S^+$ ($b$) operators above,
+we will define the following vectors from the columns of $`R_i`$ for each spin:
+
+```math
+\mathbf{z}_i = R_i^1 + i R_i^2 \\
+\mathbf{\eta}_i = R_i^3
+```
+
+that is $`z_i`$ is formed from the first and second column of $`R_i`$ whilst $`\eta_i`$ from the third column of $`R_i`$.
+This is so that we can express the spin vector (in the local coordinate system) in terms of the bosonic operators as:
+
+```math
+\mathbf{S}'_i = \sqrt{\frac{S}{2}}\left( \mathbf{z}_i^* b_i + \mathbf{z}_ib_i^{\dagger} \right) + \mathbf{\eta}_i \left( S_i - b_i^{\dagger} b \right)
+```
+
+where we have made the linear approximation and taken:
+
+```math
+S^x = \frac{(S^+ + S^-)}{2} = \sqrt{frac{S}{2}}(b + b^{\dagger}) \\
+S^y = \frac{(S^+ - S^-)}{2i} = \frac{\sqrt{S}}{i\sqrt{2}}(b - b^{\dagger}) \\
+S^z = S - b^{\dagger}b
+```
+
+
+## The Heisenberg Hamiltonian
+
+
+
+
+
+## The Bogoliubov transformation
+
+
+## Solving the quadratic form