XERUS (X-Ray Estimation and Refinement Using Similarity)

Paper

This is the main repository for

• Baptista de Castro, P., Terashima, K., Esparza Echevarria, M.G., Takeya, H. and Takano, Y. (2022), XERUS: An Open-Source Tool for Quick XRD Phase Identification and Refinement Automation. Adv. Theory Simul. 2100588. https://doi.org/10.1002/adts.202100588

For the Xerus version that was published in the paper, please refer to release 1.0r1 here

Introduction

Welcome to the Xerus project. Xerus is an open-source python wrapper / plugin around the GSASII Scriptable package, for automatization of phase quantification and Rietveld analysis by combining similarity calculations of simulated patterns (Pearson´s) with quick Rietveld refinements.

Xerus is only possible due to the existence of the following projects:

• COD (Crystallographic Open Database)
• The Materials Project (MP)
• AFLOW Database
• OQMD (Open Quantum Materials Database)
• GSASII Scriptable Engine
• pymatgen

Xerus is designed to perform analysis through Jupyter notebooks, providing an easy to use API from phase quantification to Rietveld optimization

The main mechanisms behind Xerus stems from the following papers:

• Clustering of XRD patterns using similarity:

  • Iwasaki, Y., Kusne, A.G. & Takeuchi, I. Comparison of dissimilarity measures for cluster analysis of X-ray diffraction data from combinatorial libraries. npj Comput Mater 3, 4 (2017). https://doi.org/10.1038/s41524-017-0006-2

• Optmization of Rietveld refinements:

  • Ozaki, Y., Suzuki, Y., Hawai, T. et al. Automated crystal structure analysis based on blackbox optimisation. npj Comput Mater 6, 75 (2020). https://doi.org/10.1038/s41524-020-0330-9

Plus our own pattern removal iterative process coupled with quick rietveld refinements that allows for multiphase characterization.

Installation

In this section we will briefly introduce how to install Xerus in the easiest manner possible.

Requirements

Before installing Xerus OS and Services Requeriment:

System OS

• Xerus only supports Linux based and macOS systems. Xerus was mostly developed in Ubuntu 20.04 and have been also tested in CentOS 7.x and MacOS systems (Intel) (M1 machines not available for testing.)

NOTE: As of version 1.1b we started PARTIALLY supporting Windows (currently under testing). All features related to PHASE MATCHING and SEARCHING seem to be working (Win10 python 3.8, Win11 python 3.8). However, refinement optimization seems to not work in Windows yet. There is no ETA to support this. We recommend still using UNIX based systems (Linux/macOS).

Materials Project APIKey

Xerus relies on the Materials Project API for downloading crystal structures with requested chemical space. Therefore, please register and obtain an suitable API key (Free) at:
www.materialsproject.org
After registering, you can check your API Key by clicking the API tab at the upper right side of the website.

MongoDB

Xerus relies on a MongoDB server for caching crystal structures downloaded from the providing databases (COD, AFLOW and MP)
To install the community version (Free) and run please follow the steps listed in:

• Ubuntu Installation Steps
• MacOS Installation Steps
• Windows Installation Steps

Xerus

Package Installation

Xerus currently can only be installed via conda. Therefore, if you do not have conda, please follow the install instructions here.
To install Xerus using a virtual enviroment with Python 3.8 follow this steps:

conda create -n Xerus python==3.8 anaconda
conda activate Xerus
git clone http://www.github.com/pedrobcst/Xerus/
cd Xerus
pip install -e .

⚠️ You might have trouble installing pymatgen if gcc is not present in your system. You can them for example do sudo apt install g++ to install in Ubuntu, then run pip install -e . again.

Windows Installation (Beta)

1. Install Microsoft C++ Build Tools
2. Install Anaconda
3. Clone or Download this repository.
4. Open anaconda shell (not windows cmd, but anaconda shell) and cd into the downloaded folder of Xerus.
5. Do the following commands:

conda create -n Xerus python==3.8 anaconda
conda activate Xerus
pip install -e .

6. Proceed to set the settings as describe below. =======

Configuration

If all the packages installation are successful, it is needed to correctly set the configuration file at Xerus/settings/config.conf:

Necessary

• [mongodb]

  • host: defaults to localhost
    • Enter ip address to mongodb server.
  • user: username (if necessary)
    • If configuraed to use authentication, please provide the username here
  • password: username password (if necessary)

• [mp]

  • apikey: Materials project API key.
    • Please provide your materials project API key here

Optional

• Extra config:
  • [gsasii]

    • instr_params: Path to .instrprm (GSASII)

      • Xerus by default comes with an .instprm file obtained from fitting NIST Si in our XRD Machine (Rigaku MiniFlex 600). It is recommended that you follow the GSASII tutorial for obtaining an .instrprm for your own machine but probably not necessary.

    • testxrd:

      • Xerus by default use one of the Examples data for testing purposed of obtained CIFs from the repositories. Feel free to change this to any of your liking

Testing installation

If all the above steps were done sucessfuly (pip install, mongo running [locally] and API key set), please do the following:

cd tests
pytest -vvv

If all tests sucessfuly pass, Xerus should be ready for use.

⚠️ This process might take a while.

Usage

• To learn how to use Xerus, please follow the Notebook, located at Examples/Examples.ipynb

⚠️ Make sure that before running the examples, you have started the MongoDB server.

Streamlit Interface (BETA)

As of release 1.1b we are providing a beta Streamlit interface that can help you interactively use XERUS (and its features). Altough not as flexible as using through Jupyter, it can provide a zero code alternative (or even be hosted in a main server where other users can directly use from their browser)

To start it, after installation do:

streamlit run app/app.py

Citing

If you use Xerus please also cite the following papers:

• If you use only phase matching:

  • Baptista de Castro, P., Terashima, K., Esparza Echevarria, M.G., Takeya, H. and Takano, Y. (2022), XERUS: An Open-Source Tool for Quick XRD Phase Identification and Refinement Automation. Adv. Theory Simul. 2100588. https://doi.org/10.1002/adts.202100588
  • Toby, B. H., & Von Dreele, R. B. (2013). "GSAS-II: the genesis of a modern open-source all purpose crystallography software package". Journal of Applied Crystallography, 46(2), 544-549. ​doi:10.1107/S0021889813003531

• If you use blackbox method for refinement please also cite:

  • Ozaki, Y., Suzuki, Y., Hawai, T. et al. Automated crystal structure analysis based on blackbox optimisation. npj Comput Mater 6, 75 (2020). https://doi.org/10.1038/s41524-020-0330-9

License

The code is licensed under an MIT license. The data used for benchmarking is licensed under CC4.0 and was taken from

Szymanski, N. J., Bartel, C. J., Zeng, Y., Tu, Q., & Ceder, G. (2021). Probabilistic Deep Learning Approach to Automate the Interpretation of Multi-phase Diffraction Spectra. Chemistry of Materials.