A standard format and a graphical user interface for spin system specification

We introduce a simple and general XML format for spin system description that is the result of extensive consultations within Magnetic Resonance community and unifies under one roof all major existing spin interaction specification conventions. The format is human-readable, easy to edit and easy to parse using standard XML libraries. We also describe a graphical user interface that was designed to facilitate construction and visualization of complicated spin systems. The interface is capable of generating input files for several popular spin dynamics simulation packages.


I. Introduction
The task of setting up a complicated spin system for a solid state NMR or EPR simulation is a noted test of perseverance: an aspiring theorist would find himself juggling nested timedependent tensor rotations in half a dozen ad hoc conventions [1][2][3][4][5][6][7], struggling with Euler angle singularities [8][9][10] and trying to visualize interactions that occur in direct products of Lie algebras [11,12]. Function libraries [13][14][15][16][17], command-line [14][15][16][17] and interactive [18] simulation tools for spin systems are available, but convenient point-and-click visualization and editing tools for setting up complex calculations are in their infancy. More importantly, no standards exist (whether by ISO, IUPAC or even a consensus) on a universal spin system description format that would be applicable across all types of Magnetic Resonance spectroscopy -every major simulation package has its own spin system specification requirements. Of the existing formats, the Pople convention [19] only deals with NMR spectroscopy and the latest IUPAC recommendations only go as far as listing reasonable chemical shift and shielding tensor reporting styles [4,7]. At the time of writing, the task of setting up a complicated spin system for simulation still amounts to manual parsing of unintuitive conventions and hand-coding of the associated tensor transformations.
In this communication, we suggest a simple and general XML [20,21] format for spin system description that is the result of broad consultations within the NMR and EPR communities.
The format does not attempt to introduce or change any of the current interaction specification conventions [1][2][3][4]6,7,[21][22][23][24][25][26], but instead incorporates them as special cases and options into a common framework. SpinXML format is human-readable, extensible and easy to edit, both manually and automatically. We also describe a graphical user interface that was designed to facilitate the setting up of complicated spin systems and is capable of importing interaction data from electronic structure theory programs as well as producing input files for spin dynamics simulation packages.

II. SpinXML data format
This section describes elements, types and attributes specified by the SpinXML schema file that is included into the Supplementary Information and available for download from the Spinach library website (http://spindynamics.org). An XML schema is a general description of an XML document, containing additional constraints on the structure and content of that document beyond those imposed by the syntax of XML itself [20,21]. XML has been used for a while in other areas of NMR -Agilent's VNMRJ package employs it for window layout description and an XML specification was recently proposed for phase cycles [22].
A graphical representation of the SpinXML schema is given in Figure 1. At the bottom of the SpinXML complex type (CT) hierarchy are objects intended to formalize the description of spin interaction tensors -for each interaction, amplitude and orientation information should be given. Vector and matrix complex types are not native in XML and are therefore specified explicitly as collections of double-precision real numbers. One level up, the first physically significant complex type in the SpinXML hierarchy is orientation -a property of anisotropic spin interactions that makes use of the vector and matrix CTs. Four different ways of specifying orientation are supported ( Figure 1, top right corner), corresponding to the four most popular rotation conventions in Magnetic Resonance -Euler angles [23] (in degrees), angle-axis [24] (angle in degrees, unit norm vector), unit quaternion [25] and direction cosine matrix (DCM) [26]. Euler angles and quaternion specifications are simple lists of the corresponding numerical parameters, whereas DCM invokes an instance of the above mentioned matrix CT and angle-axis parameterization makes use of the vector CT for the rotation axis vector. The SWITCH bar that connects the four specifications indicates that only one of the four options may be invoked in each instance of the rotation CT. At the level of the software package making use of SpinXML, the parser function should be able to interpret all four rotation conventions and should be able to write at least one -from our experience working with rotation specifications in Magnetic Resonance context, we strongly recommend DCM as the default convention. SpinXML makes no attempt to rectify the welldocumented ambiguities inherent in Euler angles [10], it only serves as a container.
At the next level in the complex type hierarchy shown in Figure 1, SpinXML formalizes the three general styles of spin interaction specification that are encountered in the daily practice of Magnetic Resonance spectroscopy -a scalar (isotropic interaction not requiring orientation specification), a 3×3 matrix (anisotropic interaction with orientation information already contained in the matrix) and [eigenvalue data] + [orientation data] pair. The three styles are related by a SWITCH bar ( Figure 1 upper left corner). The scalar specification simply requires a double, and the matrix specification an instance of the matrix CT. The [eigenvalue data] + [orientation data] style includes an instance of the above mentioned rotation CT for the orientation information and offers the four commonly encountered ways of specifying eigenvalues: either by listing them explicitly (current IUPAC recommendation [4,7]), or by listing isotropic part, anisotropy and asymmetry [27], or isotropic part, axiality and rhombicity [2,3,28], or isotropic part, span and skew [3,29]. The mandatory attributes of the interaction_term CT include interaction kind (strictly from one of the following: shielding, shift, gtensor, hfc, quadrupolar, exchange, jcoupling, dipolar, spinrotation, zfs), interaction identifier (an integer), physical units and the identifier of at least one spin to which the interaction relates. The second spin (for binary interactions) and a text label are optional.
We will not discuss here the relative merits of the different styles of specifying eigenvaluesthey have a long history [1][2][3][4]6,7,[21][22][23][24][25][26] and a proper unification of the existing conventions is only possible in a format that includes all of them as options. This puts some strain on the software developer (a SpinXML parser should be able to interpret all conventions listed in Figure 1), but makes life easier for the end user. When an instance of SpinXML is being written rather than parsed, we would join IUPAC [4,7] in recommending the 3×3 matrix style for spin interaction tensor specification.
As a matter of practical safety, we would not recommend specifying dipolar interactions as 3×3 interaction matrices or [eigenvalue data] + [orientation data] pairs -there are quite a few papers in Magnetic Resonance literature where the listed dipole-dipole coupling constants or matrices do not correspond to a physically possible arrangement of particles in 3D space. We recommend recording inter-nuclear and inter-electron dipolar couplings by specifying particle coordinates. Electron-nuclear dipolar couplings should be supplied as anisotropic hyperfine interactions. The case of spatially proximate delocalized electrons is covered by the zero-field splitting. If dipole-dipole interactions are specified as effective spin interactions, care should be taken to ensure that the numbers provided are consistent with a physically possible set of particle coordinates.
Another problematic area is the difference between chemical shielding and chemical shift, and the associated debate [1][2][3] about the definition of span and skew parameters -electronic structure theory calculations report absolute nuclear shielding defined in terms of molecular energy derivatives [3], whereas experimental data is reported as fractional frequency shifts relative to a specific substance [2]. To prevent any misunderstanding SpinXML includes two types of nuclear Zeeman interaction terms: "shielding" and "shift", as well as reference attribute in the interaction_term complex type, which is a character string that should contain the name of the reference substance. We recommend the definitions of span and skew given in the Maryland Consortium paper [1], including the subtle difference illustrated therein between the definition of tensor span for shielding and shift tensors. That having been said, although span and skew are provided as specification conventions in SpinXML, we would also support IUPAC [4,7] in discouraging their use -whenever possible, both chemical shift and chemical shielding should be specified using 3×3 interaction matrices that leave no room for ambiguity.
At the top level of the SpinXML format hierarchy, the spin_system element ( Figure 1, bottom middle) contains an arbitrary number of spin and interaction elements. Each spin element has an integer id, an isotope identification string and an optional set of Cartesian coordinates. The interaction elements conform to the interaction_term complex type described in the previous paragraphs. An example of SpinXML specification for the spin system of 13 C-labelled formaldehyde given in Figure 2 illustrates the format structure.
Because of its similarity to HTML (which is actually a subset of XML), SpinXML syntax appears similar to a web page specification. This self-documenting property of XML [20,21] is useful because edits can be made without consulting format documentation.
Note that the isotope specification is not limited to magnetic isotopes -retaining oxygen atoms as 16 O in particular is often useful in visualizations because it puts magnetic interaction schematics into a general chemical context.

III. Graphical user interface
A much needed stage in the spin system simulation setup process is interaction visualization.
Ellipsoid plots [27,28] and spherical harmonic representations [30] of second rank tensors have been around for a while, and visualization tools dealing with subsets of spin interactions (e.g. Simmol [31]) are available, but a general interactive 3D GUI that would be applicable to both NMR and EPR, and be capable of exporting input files for spin dynamics simulation packages, particularly in EPR spectroscopy, has so far been missing.
Spinach GUI (designed primarily to accompany our Spinach library [17], hence the name) is an interactive 3D graphical user interface that implements all SpinXML features. It supports point-and-click specification of NMR and EPR spin systems, interaction tensor import from popular electronic structure theory programs (Gaussian [32], CASTEP [33], ADF [34], ORCA [35]) and export of spin system specifications into popular spin dynamics simulation packages (EasySpin [15], Spinach [17] and SIMPSON [14] at the time of writing). Import and export filters for other major programs will be added in the near future.
The main GUI window is shown in Figure 3. The atom table on the left and the interaction   table on  -chemical shift and shielding tensors, using ellipsoid plots (blue by default), with ellipsoids centered at the corresponding nuclei.
-J-couplings, using straight lines connecting the corresponding nuclei. Interaction amplitude is mapped to the color of the line.
-hyperfine interaction tensors, using ellipsoid plots (yellow by default), with ellipsoids centered at the corresponding nuclei.
-nuclear quadrupolar interaction tensors, using ellipsoid plots (purple by default), with ellipsoids centered at the corresponding nuclei. Electronic structure theory calculations often produce large quantities of small interactions (e.g. J-couplings between remote spins) that are inconsequential in practical simulations. At the point of data import the GUI offers an option to ignore interactions with total magnitude (defined as the Frobenius norm of the corresponding tensor) below the user-specified value.
The 3D view is rendered using the OpenGL library [36]. Real-time rotations are implemented using the ARCBALL scheme [37] that assumes the mouse to be moving on the surface of a ball centered on the model. Dragging the pointer forms an arc that the system is rotated along.
When the pointer is dragged outside the ball (e.g. at the edge of the 3D view panel), the model is rotated only around the axis perpendicular to the screen. The 3D view is cross-referenced with both tables -when an atom is selected in the 3D view, its coordinate line in the atom  convention updates is given in Figure 5.
The interface to spin dynamics simulation packages follows the same design philosophy as the very successful Gaussian/GaussView [32] pair of programs in electronic structure theory.
An example of the export dialogue window is shown in Figure 5. The GUI currently generates ASCII text files containing spin system description inputs for EasySpin [15], Spinach [17] and SIMPSON [14] packages with support for other major simulation programs currently in the works. Only the spin system description part is generated: spinsys section of SIMPSON input and the corresponding Matlab code for Spinach and EasySpin packages -experiment description parts should be appended to the resulting text file by the user.