PIEFACE - Fitting Distorted Coordination Polyhedra

PIEFACE is a Python program to fit distortions in atomic coordination polyhedra.

PIEFACE is designed to be easy to use, versatile and easily extendable. The MBE ellipsoid method used to fit polyhedra is very general, and can be applied to a wide range of coordination problems. Full details of the method, and a few interesting examples can be seen in the original research publication:

James Cumby & J. Paul Attfield, Ellipsoidal Analysis of Coordination Polyhedra, Nature Communications 14235 (2017).

To get started with PIEFACE, have a look at the Introduction and Tutorials. Further documentation can be found below.

Introduction to PIEFACE

Polyhedra Inscribing Ellipsoids For Analysis of Coordination Environments

Polyhedra Inscribing Ellipsoids For Analysis of Coordination Environments (or PIEFACE) is an open source Python project intended for the analysis of distortions of a chemical coordination polyhedron. The analysis is very general, irrespective of polyhedron size or nature of the distortion, and could be applied to any problem where a coordination sphere with known coordinates exists, from extended inorganic solids to organic molecules. Full details of the method can be found in the original research article, James Cumby & J. Paul Attfield, Ellipsoidal Analysis of Coordination Polyhedra, Nature Communications 14235 (2017)., including some interesting examples.

For many crystallographic polyhedra, distortion is difficult to rationalise simply in terms of deviations of bond lengths or bond angles from ideal values. By fitting the smallest volume ellipsoid around the polyhedron, distortions are defined in terms of the three principal axes of the ellipsoid and it’s orientation in space. The distortion of this ellipsoid can then give a simple description of the distortions involved.

Getting Started

Once installed (see Installation) PIEFACE can be accessed either through a command-line interface (CIFellipsoid) or a user-friendly graphical interface (EllipsoidGUI). Both should be available on the system command line/terminal, and also from the start menu (if installed using the Windows installer).

EllipsoidGUI
Should be adequate for most users. This GUI provides a clickable interface to commonly used PIEFACE functions, and allows users to import CIF files for analysis, and examine/save the resulting output.
CIFellipsoid
Gives terminal-based access to a wider range of capabilities, details of which can be found by typing CIFellipsoid --help.

In both cases, the input required is one or more CIF files, and a list of atom types or labels to be used as polyhedron centres and ligands. Once calculated (which can take some time for a large number of files) the resulting ellipsoid parameters are saved as a text file (one per CIF file). The resulting ellipsoids and parameters can also be visualised interactively.

More detailed examples of usage can be found in Tutorials.

License

PIEFACE is distributed under the MIT license. Any use of the software should be cited.

Disclaimer

This software is provided as-is, on a best-effort basis. The authors accept no liabilities associated with the use of this software. It has been tested for accuracy of results for a number of cases, but only for uses that the authors can think of. We would be interested to hear of any suggestions for new uses, or potential additions to the software.

We will attempt to correct any bugs as they are found on a best-effort basis!

Authors

James Cumby - james.cumby@ed.ac.uk

Installation

PIEFACE is written in pure Python. While this makes it highly transferrable between operating systems, it does require a number of other Python packages to operate.

Installing

Detailed installation instructions specific to different operating systems can be found under Windows, MAC OS X and Linux derivatives.

PIEFACE is registered on PyPI, therefore if you already have a working Python distribution, installation may be as simple as:

pip install PIEFACE

or alternatively by manually installing from sources.

Note

The PyPI version is currently exhibiting issues resolving dependencies correctly with pip. See known issues for details.

In reality, installation can sometimes be operating-system specific.

Updates

From version 1.1.0, PIEFACE now includes automatic update checking. From EllipsoidGUI go to Help ‣ Check for Updates and follow the dialogue boxes. From CIFellipsoid, type CIFellipsoid -V and follow the resulting link.

Windows

Due to problems with ensuring correct dependencies, the recommended method for obtaining PIEFACE for Windows is to download the most recent self-contained installer WinSetup_PIEFACE_1.1.0.0.exe and run it, following the on-screen prompts. This will also (optionally) add PIEFACE shortcuts to the Start Menu and Windows Desktop, as well as making the two main scripts accessible from the Windows Command Line (cmd).

The installer comes packaged with a minimal Python runtime environment, therefore this installer will work without (and not interfere with an existing) Python installation.

MAC OS X

Unfortunately PIEFACE is not currently available as a pre-built MAC distribution, as the author does not have access to that operating system!

If Python is available from the terminal, installing may be as simple as:

pip install PIEFACE

or installing from sources. If this does not work, see Known Issues.

Linux derivatives

Unix-like operating systems generally come with a version of Python included. In this case:

pip install PIEFACE

should work, but may require some manual installation of dependencies (see Known Issues).

Installation from Sources

Stable Build

PIEFACE can also be installed from the source distribution. The current release is available from the PIEFACE repository. Once downloaded, this file should be unpacked into the desired directory (tar -xzf pieface_1.0.0.tar.gz) before following the manual install instructions.

Manual Install

Once the source code has been downloaded, it is then necessary to install it using Python from within the main PIEFACE directory:

python setup.py install

This should collect all dependencies, and compile them if necessary. If this fails, it may be necessary to install dependencies manually first, before running python setup.py install again.

Development Version

The latest development version of PIEFACE can be obtained from the PIEFACE repository using git:

git clone https://github.com/jcumby/PIEFACE .

To update the repository at a later date, use:

git pull

In both cases, you should then change into the resulting directory, and follow the instruction for manual install.

Requirements
Known Issues

When installing using pip, dependencies on PyCifRW and Matplotlib are not always resolved when using:

pip install PIEFACE

In this case, there are a number of possible solutions:

  • Update pip (this can sometimes solve the problem)

  • Install the dependencies manually first:

    pip install PyCIFRW>=3.3
pip install maplotlib>=1.4.3

followed by pip install PIEFACE

  • Manually download either the wheel (PIEFACE-X.X.X.whl) or compressed package (PIEFACE-X.X.X.zip or PIEFACE-X.X.X.tar.gz) from PyPI, and then install that:

    pip install PIEFACE-X.X.X.whl

  • Install from sources (may require compilation of other packages)

Testing

The package contains some basic unit tests, which can be run following installation either from source or using pip. Tests can be run from within the main PIEFACE directory with the command:

python setup.py test

or alternatively from within a python prompt:

import pieface
pieface.self_test()

All tests should pass without exceptions - if not, please send me a bug report.

Run It!

Once correctly installed, the easiest way to access PIEFACE is using either EllipsoidGUI or CIFellipsoid (see Tutorials).

Tutorials

For most users, the simplest way to use PIEFACE is using the graphical user interface EllipsoidGUI. This gives access to the most common features of PIEFACE, and is operating-system independent. The underlying script is the same as the command line application CIFellipsoid. For more advanced use, CIFellipsoid is recommended.

Using the Grapical Interface (EllipsoidGUI)

The main window

To get started, open EllipsoidGUI either from a command prompt (type EllipsoidGUI) or (on Windows with the PIEFACE installer) click the EllipsoidGUI icon on the desktop/start menu. You should be presented with a window similar to the following:

GUI opening screen

EllipsoidGUI opening window.

The window contains the following elements:

  1. Input area
    Displays loaded CIF files, and allows files to be selected for display of results
  2. Output Log
    Displays calculation logs, useful for determining what options were used, and debugging problems
  3. Add File(s)
    Used to add CIF files for ellipsoid calculation
  4. Remove File(s)
    Can remove CIF files from the list
  5. Plot Results
    Displays an interactive plot of the calculated ellipsoids and summary of the key ellipsoid parameters for the selected CIF file(s)
  6. Results Summary
    Opens a summary of ellipsoid parameters for all calculated files - these can then be exported to a number of file formats
  7. Options for calculating ellipsoids
  8. Runs the calculation for all loaded CIF files

Command Options

Once CIF files have been loaded (using button 3) the next step is to determine parameters for polyhedron determination and ellipsoid fitting (7). These are as follows:

Polyhedron Centres
These are the site labels (as specified in the CIF file) to be considered as the centre of a polyhedron. Exact labels can be given (e.g. Pr1 Pr2 Pr3 Pr4) or regular expressions can also be used (Pr.* or Pr[1-4]). To omit a label from the list, prepend the label with a #, i.e. Pr.* #Pr3 will search for all sites beginning Pr excluding Pr3.
Ligand Types
This is a list of atom types (as defined in the CIF file) to treat as polyhedral ligands, i.e. O or O2-. Wildcards are accepted.
Ligand Labels
This accepts a list of atom labels to treat explicitly as ligands, i.e. O1 or O[1-3].

Note

Ligand type/label specification can be specified together to create complex queries; if an atom is allowed by either label or type, it will be included in the calculation unless it is specifically excluded (by the use of #).

Bond Radius
The maximum centre-ligand distance to be considered part of the polyhedron.
Fit tolerance
The tolerance for the ellipsoid fit. In most cases the default should be acceptable (although can produce quite long calculation times).
Number of processors
The number of CIF files to be processed in parallel (should be <= the number of processors). Ignored if only one CIF file is loaded.
Save results to file(s)
If checked, this will save the resulting ellipsoid parameters to a text file for each CIF file.
Process in parallel
If checked, performs the calculation in parallel.
Additional options
This will accept some other non-standard options that can be supplied to CIFellipsoid, but may not always work as expected.

Note

EllipsoidGUI is designed to process a large number of CIF files at once, which may not all contain the same atomic labels. If an atom label specified as either a centre or ligand does not exist in a CIF file, it is therefore ignored. An error will be raised if a label is not present in any of the CIF files.

Running calculations

Once CIF files are loaded and options supplied, calculations can be performed by clicking Calculate All. If a subset of CIF files are selected, the option is given to perform the calculation only for those CIFs, keeping results for any other files.

Warning

Depending on the parameters chosen (particularly Fit tolerance) and complexity of the resulting ellipsoid, calculations can take a number of minutes per CIF file. Fit tolerance should not be reduced below 1E-9 to avoid problems with computational rounding errors. 1E-6 should be sufficient for most needs.

Viewing Results

Ellipsoid Summary

Once calculations have been performed, the resulting ellipsoids can be viewed by selecting one or more CIF files in the input window, and clicking Plot Results. This will open a new window for each CIF file, with an summary of key ellipsoid parameters and an interactive plot of the ellipsoid:

Ellipsoid Summary

Ellipsoid summary plot.

The ellipsoid image can be rotated by clicking and dragging in the window. Zooming can be achieved by right-clicking and dragging (at least on Windows).

Note

The ellipsoid is plotted using cartesian axes, with values in angstroms. The polyhedron centre is centred on the origin.

Parameter overview

If calculations have been performed for multiple CIF files, it is often useful to compare results. Clicking Results Summary will open a new window displaying a table of important ellipsoid parameters. If more than one polyhedron has been defined (e.g. more than one central atom) a separate tab is produced for each polyhedron.

The All data table can be exported to a file by selecting File ‣ Save As.

Using the Command-line interface (CIFellipsoid)

CIFellipsoid provides additional functionality beyond that of EllipsoidGUI. It can be started by typing CIFellipsoid from a command prompt, or (if installed using the Windows installer) clicking on the CIFellipsoid icon on the start menu/desktop.

Full input details of the acceptable arguments to CIFellipsoid can be found under User-interface Documentation.

Note

If running CIFellipsoid on Windows, processing a large number of CIF files can be simplified by using wildcard expansion: CIFellipsoid *.cif -m ... will automatically process all cif files in the current folder

User-interface Documentation

CIFellipsoid

This is the main command line script for using PIEFACE to compute MBE from one or more CIF files. Details of the input parameters are given below, or by typing CIFellipsoid --help.

cifs

Name(s) of CIF files to import as a space-delimited list. Can also accept valid web address(es).

-m, --metal
Site label(s) (as found in the CIF file) of polyhedron centres to analyse (e.g. Fe1).
Most regular expressions can be used to make searching easier:
Al.*:matches any site label starting Al (Al1, Al2 … Al9999 etc.)
Al?:matches any label beginning Al, but only 3 characters in length (e.g. Al1 - Al9)
Al[1-9]:matches any site Al1 - Al9
In addition to most normal regular expressions, preceding any label by # will omit it from the search:
#Al1:will omit Al1 from the list of acceptable centres.

By combining these terms, it should be possible to specify most desired combinations.

-o, --output

Name(s) of output files to save results to. Default is <CIF Name>.txt.

-r, --radius

Maximum distance to treat a ligand as part of a polyhedron (default 3 Angstrom).

-l, --ligandtypes

Types of atom (as specified by CIF atom_type) to be considered as valid ligands (can use regular expressions). Default is all atom types.

-n, --ligandnames

Atom labels to use as ligands (same syntax as –metal). By default, any ligand allowed by –ligandtypes is allowed. The combination of –ligandtypes and –ligandnames is taken as an AND-like operation, such that sites are only excluded if done so explicitly.

-t, --tolerance

Tolerance to use for fitting ellipsoid to points (default 1e-6).

-b, --phase

Name of data block to read from CIF file (default is first alphabetically)

--maxcycles

Maximum number of iterations to perform for fitting (default infinite).

-N

Don’t save results to text files

-W, --overwriteall

If existing results files already exist, force PIEFACE to overwrite them all.

-P, --PrintLabels

Print all valid site labels for each CIF file supplied.

-U, --Unthreaded

Turn off parallel processing of CIF files.

--procs

Number of processors to use for parallel processing (default all).

--noplot

Don’t produce interactive ellipsoid images after calculation.

--writelog

Write a debugging log to debug.log.

-V, --version

Print version information, check for updates, and exit.

License

MIT License

Copyright (c) 2017 James Cumby

Except where otherwise noted, all of the documentation and software included

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Changelog

Version 1.1.0 (2016-07-21)

Added features and modifications:

  • Modified readcoord.readcif to accept a phaseblock argument, to allow better reading of multi-phase CIF files.
  • Tests are now controlled by pytest, rather than unittest
  • Added update-check to CIFellipsoid and EllipsoidGUI to check for newer versions of PIEFACE.

Bug fixes:

  • Changed readcoords.readcif so that if neither of _symmetry_Int_Tables_number or _space_group_IT_number is present, spacegroup is set to None. Does not currently affect any other routine in pieface.
  • Minor updates to documentation and code organisation

Version 1.0.0 (2016-12-06)

First public release of PIEFACE!

Documentation is available at http://pieface.readthedocs.io/en/latest/

API Reference

Ellipsoid Module

Contains the core functionality of PIEFACE, responsible for fitting a MBE to a set of points in Cartesian space.

Module containing functions for calculating a minimum bounding ellipsoid from a set of points.

Contains a class to hold Ellipsoid object/properties, and functions to compute the ellipsoid from a set of points

Basic usage:
  • Set up an Ellipsoid object
  • Assign a set of (cartesian) points to be used for fitting
  • Use method findellipsoid() to compute minimum bounding ellipsoid
  • After that, all other properties should be available.
class pieface.ellipsoid.Ellipsoid(points=None, tolerance=1e-06)

An object for computing various hyperellipse properties.

centreaxes()

Return displacement along ellipsoid axes.

centredisp()

Return total displacement of centre.

ellipsvol()

Return volume of ellipsoid.

findellipsoid(suppliedpts=None, **kwargs)

Determine the number of dimensions required for hyperellipse, and call then compute it with getminvol.

getminvol(points=None, maxcycles=None)

Find the minimum bounding ellipsoid for a set of points using the Khachiyan algorithm.

This can be quite time-consuming if a small tolerance is required, and ellipsoid axes lie a long way from axis directions.

meanrad()

Return the mean radius.

numpoints()

Return the number of points.

plot(figure=None, axes=None, **kwargs)

Plot graph of ellipsoid

plotsummary(**kwargs)

Plot graph of ellipsoid with text of basic parameters

points

Points to define a hyperellipse.

raderr()

Return standard deviation in radii

radvar()

Return variance of the radii.

shapeparam()

Return ellipsoid shape measure r3/r2 - r2/r1.

shapeparam_old()

Return ellipsoid shape measure r1/r2 - r2/r3.

sphererad()

Return radius of sphere of equivalent volume as ellipsoid.

strainenergy()

Return ellipsoid strain energy approximation.

uniquerad(tolerance=None)

Determine the number of unique radii within tolerance (defaults to self.tolerance)

Polyhedron

Represents the set of objects that define a coordination polyhedron, including transforming from a unit cell description to one of orthogonal (Cartesian) positions.

Module for containing polyhedron data and functions

class pieface.polyhedron.Polyhedron(centre, ligands, atomdict=None, ligtypes=None)

Class to hold polyhedron object

allbondlens(mtensor)

Return bond lengths to all ligands

alldelabc()

Return all coordinates relative to centre.

alldelxyz(orthom)

Return all cartesian coordinates relative to centre.

allxyz(orthom)

Return all atoms in cartesian coordinates.

averagebondlen(mtensor)

Return average centre-ligand bond length

bondlensig(mtensor)

Return standard deviation of bond lengths

bondlenvar(mtensor)

Return variance of bond lengths

cenxyz(orthom)

Return centre atom cartesian coordinates.

ligdelabc()

Return ligand coordinates relative to centre.

ligdelxyz(orthom)

Return ligand cartesian coordinates relative to centre.

ligxyz(orthom)

Return ligand cartesian coordinates.

makeellipsoid(orthom, **kwargs)

Set up ellipsoid object and fit minimum bounding ellipsoid

pointcolours()

Return a list of colours for points based on ligand type.

Crystal

Class to hold a number of polyhedron objects, as well as unit cell parameters and orthogonalisation matrix, etc.

class pieface.readcoords.Crystal(cell=None, atoms=None, atomtypes=None)

Class to hold crystal data and resulting ellipsoids.

makepolyhedron(centre, ligands, atomdict=None, ligtypes=None)

Make polyhedron from centre and ligands.

mtensor()

Return metric tensor from cell parameters

orthomatrix()

Return orthogonalisation matrix from cell parameters.

Plot Ellipsoid

Class to generate 3D interactive images of ellipsoids.

class pieface.plotellipsoid.EllipsoidImage(figure=None, axes=None)
clearlast(removepoints=True, removeaxes=True, removeframe=True)

Remove previous plot

plotell(ellipsoid, plotpoints=True, plotaxes=True, cagecolor='b', axcols=None, cagealpha=0.2, pointcolor='r', pointmarker='o', pointscale=100, title=None, equalaxes=True)

Plot an ellipsoid

CIF calculation routines

calcfromcif

pieface.calcellipsoid.calcfromcif(CIF, centres, radius, allligtypes=[], alllignames=[], **kwargs)

Main routine for computing ellipsoids from CIF file.

multiCIF

The main module for computing ellipsoids from a number of files, using multiprocessing (one core per CIF file) if required. Largely contains routines for error checking input commands and calling calcfromcif.

Module for processing one or more CIF files using supplied options To run from the command line, call the CIFellipsoid.py script.

exception pieface.multiCIF.KeyboardInterruptError
class pieface.multiCIF.QueueHandler(queue)

This is a logging handler which sends events to a multiprocessing queue. The plan is to add it to Python 3.2, but this can be copy pasted into user code for use with earlier Python versions.

emit(record)

Emit a record. Writes the LogRecord to the queue.

pieface.multiCIF.check_centres(cifs, centres, phase=None)

Determine which centres to use based on CIF contents and user-supplied arguments.

pieface.multiCIF.check_labels(labels, alllabs)

Check that all labels are present in all cif files, handling regular expressions if needed. Returns ——- list of labels to test, list of labels to omit, list of missing labels

pieface.multiCIF.check_ligands(cifs, ligtypes, liglbls, phase=None)

Find lists of ligand labels and types that should be used to define ellipsoids based on supplied lists.

NOTE: This function will find the appropriate combination of label/type commands to find all required ligands,
EXCEPT where a site is found in multiple CIFs with the same label, but different type. In this case, the returned lists of labels and types should work correctly when run through calcellipsoid.calcfromcif
pieface.multiCIF.listener_configurer(name=None)

Function to configure logging output from sub processes

pieface.multiCIF.listener_empty_config(name=None)

Empty listener configurer, to do nothing except pass logs directly to parent

pieface.multiCIF.listener_process(queue, configurer)

Process waits for logging events on queue and handles then

pieface.multiCIF.main(cifs, centres, **kwargs)

Process all supplied cif files using options supplied as kwargs (or defaults).

Returns
phases : Dict
Dictionary of Crystal objects (containing ellipsoid results), keyed by CIF name.
plots : dict or dicts, optional
Dictionary of summary plots (keyed by CIF name) containing Dictionary of plots (keyed by ellipsoid centre)
pieface.multiCIF.run_parallel(cifs, testcen, radius=3.0, ligtypes=[], lignames=[], maxcycles=None, tolerance=1e-06, procs=None, phase=None)

Run ellipsoid computation in parallel, by CIF file

pieface.multiCIF.worker_configure(queue)

Initialise logging on worker

Utility Functions

A number of utility functions are provided to simplify generation of polyhedra and reading/writing of files.

Unit Cell Functions

pieface.readcoords.makeP1cell(atomcoords, symmops, symmid)

Generate full unit cell contents from symmetry operations from Cif file

Returned atom labels (as dict keys) are appended with ‘_##’ to denote the number of the symmetry operation that generated them from cif file (initial position label is not changed).

pieface.readcoords.findligands(centre, atomcoords, orthom, radius=2.0, types=[], names=[], atomtypes=None)

Find all atoms within radius of centre

File Functions
pieface.readcoords.readcif(FILE, phaseblock=None, getocc=False)

Read useful data from cif using PyCifRW.

Module to write pieface ellipsoid parameters to text file.

pieface.writeproperties.writeall(FILE, phase, verbosity=3, overwrite=False)

Write data to file

Increasing verbosity above 0 will increase the amount of data printed to file (4 is maximum output)

Glossary

CIF
Crystallographic Information File
ellipsoid
A three-dimensional object formed by rotating an ellipse.
citation
James Cumby & J. Paul Attfield, Ellipsoidal Analysis of Coordination Polyhedra, Nature Communications 14235 (2017).
MBE
Minimum Bounding Ellipsoid. The smallest volume ellipsoid that can surround a set of points.
GUI
Graphical User Interface

Indices and tables