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)