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)