Code for parsing CCP-NC ab-initio magnetic resonance file format and processing ab-initio magnetic resonance parameters. Maintained by Tim Green (
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Build Status

Code for parsing the CCP-NC ab-initio magnetic resonance file format as used in the latest version of CASTEP, coming soon to other codes such as Quantum ESPRESSO. See more on this page

Documentation for the is available here.

A few IPython notebooks have been written using the library as examples. You can see them here.

IPython is an enhanced interpreter for Python and offers an excellent in-browser workbook experience, similar to Matlab or Mathematica. This is particularly useful when developing code using this library to process your magnetic resonance calculations. You can read instructions for installing it here.

A calculated J-coupling network in ethanol.


Clone the repository or download and extract the .zip file somewhere. From the command line, run:

sudo python install

to install it globally, or

python install --user

to install it just for your user account (read more here), and the Python module and associated scripts should now be installed.

If you have installed it locally with --user, you may have to add ~/.local/bin to your PATH. You can do this by adding

export PATH=$HOME/.local/bin:$PATH

to your ~/.bashrc and restarting your session or running "source ~/.bashrc". If you use tcsh you do

setenv PATH $HOME/.local/bin:$PATH

and then restart your session.

Extraction scripts

Some utility scripts for extracting values from a large number of calculation output files are provided. Look at their help information for detailed instructions

For magnetic shieldings (chemical shifts) --help

For electric field gradients (quadrupolar couplings) --help

For J-couplings (indirect spin-spin coupling) --help

These scripts can be called with an atom list to restrict which atoms or couplings are shown. These can select an entire species


will select all hydrogen atoms. They can select a single atom


will select the second hydrogen atom. They select ranges of atoms


will select the second to fifth hydrogen atoms. These can also be chained together with commas


will select the first five hydrogen atoms and all oxygen atoms.

For example, . Zn

will print only the magnetic shieldings of zinc atoms in all the .magres files found in the current directory.

The -N flag optionally outputs in the first columns of the output an attempt at parsing out numbers in a path. This is useful for convergence tests. E.g. the path grid_scale=2/energy_cut_off=80/ethanol.magres will output the numbers 2.0 and 80.0 in the first two output columns.

Conversion script usage

The script converts an old-style Castep magres file to the new-style CCP-NC format for use with the new tools. You use it from the command line like: sample.magres >

and optionally with the associated job's .castep file, to capture the lattice information, sample.magres sample.castep >

Python module usage

The magres.format and magres.atoms modules contain code for, respectively, a low level parser of the CCP-NC ab-initio magres format and a high-level collection of objects to represent its contents.

The module also include the useful magres.constants module, which gives the best-known gamma constants and quadrupole moments for all isotopes, the most common isotopes used in experiments.

More documentation is available here. Also, see the IPython notebooks linked at the top of this document.

JSON schema

We use the JSONschema definition to provide a specification for the internal datastructure used by the parser and the format of the JSON emitted and consumed by .as_json() and .load_json() on MagresFile.

To dump the JSON representation of a .magres simply do sample.magres > sample.magres.json

and sample.magres.json should now contain a schema-compliant JSON representation of sample.magres.