Visualization and processing of computed solid-state NMR parameters: MagresView and MagresPython

We introduce two open source tools to aid the processing and visualisation of ab-initio computed solid-state NMR parameters. The Magres ﬁ le format for computed NMR parameters (as implemented in CA-STEP v8.0 and QuantumEspresso v5.0.0) is implemented. MagresView is built upon the widely used Jmol crystal viewer, and provides an intuitive environment to display computed NMR parameters. It can provide simple pictorial representation of one-and two-dimensional NMR spectra as well as output a selected spin-system for exact simulations with dedicated spin-dynamics software. MagresPython provides a simple scripting environment to manipulate large numbers of computed NMR parameters to search for structural correlations.


Introduction
First-principles calculations of NMR parameters in the solid state are a vital component of the NMR crystallography toolbox, providing a connection between the underlying atomistic structure and the observed NMR spectrum [1,2].Such calculations can now provide all of the key NMR parameters relevant to diamagnetic solids: the magnetic shielding, electric field gradient (EFG), direct dipolar coupling and indirect spin-spin (J) coupling.Significantly, calculations provide the full tensorial information for each NMR parameter, giving the orientation with respect to the crystal lattice.There is a clear need to visualise the computed resultsto assign experimental spectra, and to gain understanding about the relation between NMR parameters and atomic level structure.There are a number of programs to view crystal structures and tools have been developed to visualise spin systems e.g.SIMMOL [3] and Spinach GUI [4] or to display and manipulate NMR spectra [5][6][7][8].However, there is still a need for a visualisation tool that has a complete understanding both of NMR parameters and crystal symmetry.
A related issue occurs when needing to process large numbers of calculated NMR parameters.For example for a system undergoing rapid dynamics it may be necessary to perform a molecular dynamics simulation and to calculate the NMR parameters as an ensemble average over the trajectory.Similarly, when studying materials with positional or compositional disorder it may be necessary to simulate multiple copies of the unit cell each containing a different configuration of atoms.An illustration of the latter case is a study of the Al/Si ordering in the Calcium Aluminosilicate Gehlenite by Florian et al. [9].They considered 50 unit cells with differing Al/Si ordering each containing 256 atoms.From these calculations the correlation of the 27 Al EFG with the number of silicon next nearest neighbours could be obtained.Extracting this information by hand from the calculation output files would be extremely tedious and prone to error.In contrast a scripted approach should be both efficient and reliable.
In this article we introduce two open source tools to address these issues.The Magres file format is a simple format for storing the result of a first-principles calculation of NMR parameters.Ma-gresView provides a graphical viewer for these magres files, and MagresPython a scripting interface to process multiple magres files.

Magres file format
As more computational codes incorporate the prediction of NMR parameters, a unified output format is necessary in order to create a common platform for the further development of tools.The format described here can be used as an input to tools for diverse tasks such as visualisation, interfacing to spin simulation software, and for performing the sort of flexible analysis required in the course of research.It can also be used as an archival format for preserving research products.This format is written by default by CASTEP v8.0 [10] and later and QuantumEspresso v5.0.0 [11] and later.
This unified format includes all the information produced by a first-principles calculation of NMR parameters, without redundancy, and all quantities are precisely defined theoretically and with units.The full specification can be found in the SI but here we will give a brief summary.
The format is designed with minimal complexity to be easy to understand and parse by someone of modest programming skill in most computer languages.By deliberately designing the format to be easily parsed, without compromising the information contained, it will be significantly more accessible to the average researcher.The file itself is an ASCII text file and is broken up into a number of blocks, each containing a sequence of records, one per line.Records are identified by the contents of their first column, unrecognised blocks or records can be ignored, single-line comments can be added and units are always specifiedin a sense making the data self-documenting.
The first line of the file identifies it as a magres file.Additional lines starting with # are optional comments.After this the file can contain a block for meta-data describing the computational details of the calculation, e.g. the code used and its version, the methodology used, the choice of density functional, and the details of the basis set.The exact fields are not specified, but it should be sufficient to reproduce the calculation in conjunction with the atomic data.Next, the file contains a block with the unit cell lattice vectors, atomic coordinates and any symmetry operations present.These are all given in a Cartesian basis.Finally, there is a block containing the magnetic resonance parameters, usually rank-2 tensors.The tensors are also stored in a Cartesian basis.Magnetic shielding tensors are given in units of ppm, EFG tensors are given in atomic units and the J-coupling tensors are given in reduced SI units.This choice of units has been made so quantities given are independent of the isotope of the nucleus.The MagresView and MagresPython software allow a user to select a particular isotope and display parameters in commonly used systems of units.Files written in this format are given the file extension '.magres'.A sample file for quartz is shown in Fig. 1.

MagresView
MagresView is a user-friendly environment for the visualization and analysis of the Magres file format.The primary author is Simone Sturniolo.It is an application customized for the NMR crystallography community which operates in a web browser; it can be used over the Internet but a downloadable version for offline usage is also available.We developed MagresView to allow a smooth and intuitive interaction with calculated NMR parameters: it provides a graphical representation of the simulated data, generates human readable records (tables and graphs) from the computer readable format, and provide a pipeline for spin dynamics simulations.
MagresView is built on top of Jmol; a free, open-source molecular visualization software available in both Java and JavaScriptonly versions [12].Jmol has full 3D-crystal symmetry and periodic crystal visualization capabilities.Jmol includes basic NMR-specific functionalities as well as the ability to load and display.magresfiles.It can be used directly in its standalone Java version, as a standalone web-based Java applet, or as a JavaScript-only webbased page component [13].MagresView provides more advanced NMR-specific functionality and an easy to use graphical interface.Table 1 contains a rundown of the functionalities provided by each program for various NMR specific tasks.
MagresView provides versatile options for the visualization of NMR ab-initio results (Fig. 2).Magnetic shielding and electric field gradient tensors can be represented graphically as ellipsoids, surrounding each atom.This represents the principal directions and values of the tensor by the principal axes and lengths of the ellipsoids (Fig. 3).In this way the relation between the principal frame of the tensor and that of the crystal structure can be clearly seen.Many calculated parameters of interest can be revealed by text labels or by color scaling on top of the 3D crystal structure (Figs. 4 and 6).By providing a suitable reference shielding, users can convert between the calculated magnetic shielding and the chemical shift.Users can also choose between the various conventions for parameterising the anisotropy of NMR tensors, e.g.Haeberlen [14] (anisotropy, asymmetry) or Herzfeld-Berger [15] (span, skew).Direct dipolar couplings and indirect spin-spin couplings (ISC, J) are represented as links connecting pairs of atoms; including periodic images of atoms in an adjacent unit cell (Fig. 5).Calculation and plotting of dipolar couplings are available even without the ab-initio calculated results; dipolar couplings are determined directly from the atomic coordinates, allowing Ma-gresView to compute them from data in the form of standard crystallographic file formats such as PDB, CIF, and SHELX, all of which Jmol can read.All the properties detailed above can be presented for all or only some of the atoms within the system.Supplementary material related to this article can be found online at http://dx.doi.org/10.1016/j.ssnmr.2016.05.004.
MagresView can visualize a predicted NMR spectrum from the calculated data: 1D spectra can be plotted as simple spectral lines with Lorentzian broadening; the 2D NMR plotting tool can generate a plot of a correlation spectrum by positioning peaks at the coordinates corresponding to the known isotropic chemical shifts (referenced and taking into account the second order quadrupolar shift if required), as well as scaling their intensity by the strength of the dipolar or J coupling for the corresponding spin pair, see Fig. 6.The predicted spectra can then be overlaid on top of an experimental spectrum, allowing easy comparison and assignment of the resonances.A full description of MagresView's functionality is found in Table 1.The MagresView webpage [23] provides easy-to-follow tutorials to help new users get started.

MagresPython
Processing NMR parameters with a GUI is not appropriate for all systems, or problems.A programmatic approach is necessary for efficiently implementing high-throughput approaches, e.g.structure searching or when considering an ensemble of structures -e.g.snapshots of a molecular dynamics simulation, or sites within a disordered material.Implementing analysis programmatically also ensures reproducibility, aids rapid prototyping, and allows publication of verifiable methodology.Hence, as a complement to MagresView, we have developed the MagresPython library [24].Tim Green is the primary author.This library enables natural manipulation of NMR parameters using Python, which is a popular programming language in the scientific community.
The MagresPython library implements a robust parser of the Magres file format, reading the information into native data structures.It then provides classes to represent concepts in the standard, such as atoms, which can have magnetic shielding tensors, electric field gradients and indirect spin couplings.These classes implement the various well-known conventions for tensor components and can implicitly handle converting between reduced J-couplings and coupling frequencies, and between electric field gradients and quadrupole couplings, using a built in library of the gyromagnetic ratios and quadrupole moments for all known isotopes.
The library also provides containers to represent lists of atoms, with behaviour similar to native Python containers.A simple querying system can be used to select subsets of atoms, for example by species or spatial proximity to other atoms, using periodic boundary conditions, and concisely extract properties.By providing an additional set of well-tested tools that have proved useful in real research, these features add value to the library beyond just providing a parser for the Magres format.The library has a number of unit tests and integration tests, along with tutorial notebooks for the IPython system.As a GitHub project it is open for contributions and, with time, should represent best practices in manipulation of Magres files.
Fig. 7 shows an example script which processes the Magres files from calculations on 50 disordered structures on Gahlenite [9].The script classifies each Al site as either T1 (4 Al/Si second nearest neighbours) or T2 (3 Al/Si second nearest neighbours) and for each type of site plots a histogram of 27 Al quadrupolar coupling constants, distinguishing between sites on the basis of how many Al second nearest neighbours are present.The structure is shown in MagresView in Fig. 8.The script takes a short time to execute on a standard desktop computer producing the average values and images shown in Fig. 7.

Conclusions
First-principles calculations of NMR parameters in the solid state can in many cases provide results with accuracy capable of assigning experimental spectra.This has enabled the community to devise increasingly sophisticated computational simulations in order to address complex materials problems.We have developed a number of freely available tools to aid the visualisation and processing of computed NMR parameters.We hope these provide a platform for future developments, including closer integration with spin-simulation codes and databases of computed and experimental solid-state NMR parameters.Fig. 6.Experimental 2D 1 H-1 H (500 MHz) double quantum MAS (35 kHz) spectrum of L-alanine [17,18].The position of peaks from first-principles calculated data has been superimposed as orange crosses using MagresView.The 1 H chemical shifts for the mobile CH 3 and NH 3 groups have been averaged before plotting using a MagresPython script (The corresponding magres file and script are given in the SI).

Fig. 1 .
Fig. 1.Sample Magres file for Quartz generated by CASTEP.Note that for readability in this figure all values have been truncated to 4 decimal places.

Fig. 2 .
Fig. 2. Screenshot of MagresView running in the Firefox web browser (embedded video Video 1).

Fig. 3 .
Fig. 3. Ellipsoid representation of the 17 O electric field gradient (blue) and shielding (orange) tensors in β-aspartyl-alanine.Crystal structure from Ref. [16] (CDS refcode: FUMTEM) (embedded video).(For interpretation of the references to color in this figure legend, the reader is referred to the web version of this article.)

Fig. 4 .
Fig. 4. β-Aspartyl-Alanine showing hydrogen atoms labelled and color-coded according to 1 H chemical shift (blue is deshielded (low ppm), red shielded (high ppm)), using a reference shielding of 31.0 ppm.(For interpretation of the references to color in this figure legend, the reader is referred to the web version of this article.)

Fig. 7 .
Fig. 7.A selection of an IPython notebook output, showing the MagresPython library being used to concisely extract and plot with the matplotlib library the 27 Al C Q 's of an ensemble of structures from a disordered system as a histogram.

Fig. 8 .
Fig. 8. (left) Structure of Gehlenite: Ca (green), Al (grey), Si (brown), O (red).(right) Al atoms colored according to magnitude of C Q .The largest values of C Q ( 12.9 MHz) are colored red, and correspond to the T1 sites Al-Al 2 Si, while the smallest values ( 2.6 MHz) are colored blue and correspond to the T2 site Al-Al 4 .(For interpretation of the references to color in this figure legend, the reader is referred to the web version of this article.) Contents lists available at ScienceDirect journal homepage: www.elsevier.com/locate/ssnmrSolid State Nuclear Magnetic Resonance http://dx.doi.org/10.1016/j.ssnmr.2016.05.004 0926-2040/& 2016 The Authors.Published by Elsevier Inc.This is an open access article under the CC BY license (http://creativecommons.org/licenses/by/4.0/).

Table 1
Summary of MagresView and Jmol NMR functionality.MagresView and Jmol: Calculate isotropic component of ISC and convert to frequency for the given isotopes.Visualize ISC as link network.MagresView: Different colors for positive and negative ISC links.Limit the range of couplings visualized with a minimal and maximal magnitude values.Visualize ISC with atoms from neighboring unit cells ("ghosts").
VisualizationMagnetic shielding MagresView and Jmol: Represent tensors as ellipsoids.Calculate tensor parameters;.isotropy, anisotropy and asymmetry (or span and skew).MagresView: Visualize isotropy, anisotropy and asymmetry (or span and skew) with labels and/or color codes.Convert from magnetic shielding to chemical shift.Electric field gradient MagresView and Jmol: Represent tensors as ellipsoids.Calculate tensor parameters and quadrupole coupling given the isotope for the element.MagresView: Visualize V zz, anisotropy and asymmetry (or span and skew) and quadrupole coupling with labels and/or color codes.Dipolar coupling MagresView and Jmol: Calculate the dipolar coupling constant (DCC) for arbitrary atom pairs and convert to frequency for the given isotopes.Visualize DCC as link network.MagresView: Visualize DCC for all selected atoms in a spherical neighborhood around one.Visualize DCC with atoms from neighboring unit cells (will appear as 'ghost' atoms).Compute isonuclear and total root square sum coupling.Euler angles MagresView: Calculate Euler angle differences between principal frames of two picked MS or EFG tensors.Compute a table of all Euler angle differences between MS and EFG tensors on the same atom.Choice of Euler angle convention.Additional features MagresView A variety of display options View as asymmetric unit/unit cell/supercell, select and display atoms by species or label, show/hide atom labels etc. Isotope selection Select the desired isotope for each individual atom.System alignment Align the system with the dipolar coupling of a bond, or the magnetic shielding / electric field gradient tensor of a single atom.Save snapshot Export a snapshot of the visualization to a '.jpeg' formatted file.