Merge branch 'main' into 10-draft-python-version-of-spinwavem

.github/workflows/lint.yml

@@ -18,6 +18,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install pylint
+        pip install -r requirements.txt
     - name: Analysing the code with pylint
       run: |
         pylint --disable C $(git ls-files '*.py')

docs/developers/adr/001_use_atomic_simulation_environment.md

@@ -0,0 +1,38 @@
+# 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.
+* If `ase` changes its code this might break anything we might build on top of it.
+* 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.
+* Reading of CIF files is supported by ASE
+* Some plotting is already supported by ASE

docs/developers/adr/004_magnetic_lattice.md

@@ -0,0 +1,28 @@
+# Classes for different kinds of magnetic structures
+
+## Context
+
+SpinW has different methods for dealing with different kinds of simulation, some simulations only work for systems decribed by a single (possibly complex) propagation vector, some (e.g. "biquadratic") only work
+when the propagation vector is (0,0,0). It seems that a useful distinction is between systems where every unique magnetic state is explicitly represented, and ones where it is implicitly defined. 
+The notion of commensurability maps on to this. Commensurate propagation vectors permit a finite (though potentially large) explicit representation.
+
+The plan is to make separate classes for these descriptions, provide some degree of conversion between the two, and associate appropriate calculations with each one.
+1) The explicit structure - every unique site is described explicity - explcit supercell, only (0,0,0), supports biquadratic
+2) The implicit structure - described by a unit cell, and a single propagation vector - implicit supercell, supports incommensurate and true helical structures. The impilcit structure requires the "trick" used in spinw to calculate intensities at +/- the propagation vector.
+
+In both cases the classes should implement a method to return the set of `zed` and `eta` vectors needed for the spin wave calculations as detailed in [this doc](../design/001_linear_spinwave_theory.md#local-spin-directions).
+
+In addition, it would be useful if the user can specify a set of propagation vector(s) and basis(es) in the explicit representation rather than every spin orientation in the unit cell, but this is an implementation detail to be discussed later.
+
+## Decision
+
+We will create two classes for handling the magnetic structure, a `CommensurateStructure` for the "explicit" representation and a `RotatingFrameStructure` for the "implicit" representation.
+
+## Status
+
+Accepted
+
+## Advantages
+
+* Clear distinction between two kinds of description
+* Separation of code

docs/developers/adr/03_backwards_compatibility_layer.md

@@ -0,0 +1,25 @@
+# PySpinW will have a backwards compatibility layer
+
+## Context
+
+A clean class structure for pySpinW will entail making some relatively large changes to the intended use, this
+might be off-putting to some users, and will break compatibility with existing scripts.
+
+One big change is that there won't be a single big, stateful class, but lots of smaller stateless classes.
+
+However, it would not be difficult to maintain existing syntax by putting all the new stuff into a stateful class that
+closely resembles the original matlab.
+
+## Decision
+
+Create a class that mimics the original spinW interface, backed by the new objects. 
+In particular, this class will only expose functionality which is currently in the Matlab version (and will omit new functionality written for Python) in order to encourage users to migrate.
+
+## Status
+
+Accepted
+
+## Consequences
+
+* Will take time to do
+* Might prevent users from migrating, and become permanent

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.