Python library for automated single crystal refinement with Shelx
Authors: E. Antono and J. Ling at Citrine Informatics
Please contact: erin (at) citrine (dot) io with any questions.
This package is intended to be used with the SHELX code suite: Sheldrick, George M. "A short history of SHELX." Acta Crystallographica Section A: Foundations of Crystallography 64.1 (2008): 112-122.
The purpose of this package is to automate many of the steps in single crystal refinement. It automatically detects split occupancy, deficiency, wrong element assignments, and anisotropy.
Clone this git repo:
git clone firstname.lastname@example.org:CitrineInformatics/crystal-refinement.git
pip install -r requirements.txt python setup.py install
to install python dependencies and the crystal structure refinement package. We recommend that this step is done in a python virtual environment (https://virtualenv.pypa.io/en/stable/).
- SHELXTL executables (xl.exe and xs.exe on Windows, shelxl and shelxs on MacOS).
- In order to use the machine learning model for bond lengths, you will also need to create a free account at https://citrination.com
- Graphviz to render the optimization graphs: https://graphviz.gitlab.io/download/
The optimization package can be run using a command line interface and configuration file. Run
to see the help menu for the command line interface.
To run an example optimization on the ins file in the example folder, change the
minimal.yml file to correspond to the path of the SHELX executables on your machine. Then run:
crystal_refinement -c minimal.yml -d examples/ -i input -o test
The results of the optimization will be output to the
0.res is the highest
scoring result file,
optimization_graph.pdf is the optimization graph generated by graphviz, and
contain metadata on the optimization process.
config.yml for further documentation of the configuration file parameters.
The optimization package can also be used directly in python by creating an instance of the
Optimizer object and
How it works
The optimizer tries the following steps in order:
- Identify crystal sites (try adding or removing Q peaks)
- Switch elements at each crystal site
- Try site mixing at each site
- Try partial occupancy at each site
- Try extinguishing
- Try anisotropy
At each step, the optimization takes into account both the fit R1 value as well as the bond lengths. The ideal bond lengths can be determined by 3 different methods:
- User input via the bond_length argument to the Optimizer class
- A machine learning model for bond length hosted at citrination.com. To use this model, the user must have a free account on the public Citrination site.
- Atomic radii of the elements
The optimizer will follow multiple paths to see which path yields the best final fit. For example, if two different elements both yield similar R1 values at a given crystal site, the optimizer will try both options to see which give the best final fit. This results in a branching tree structure.