search

bobleesj / cifkit

High-throughput .cif analysis made easy. Visit: https://bobleesj.github.io/cifkit/
https://bobleesj.github.io/cifkit/
MIT License
11 stars 0 forks source link
coordination-number crystallography high-throughput site-analysis solid-state

readme

cifkit

Integration Tests codecov Python 3.10 Python 3.11 Python 3.12 PyPi version License: MIT

Open Google Codelab

The documentation is available here: https://bobleesj.github.io/cifkit

Logo light mode Logo dark mode

cifkit is designed to provide a set of well-organized and fully-tested utility functions for handling large datasets, on the order of tens of thousands, of .cif files.

The current codebase and documentation are actively being improved as of July 8, 2024.

Motivation

In high-throughput analysis using .cif files, the research project has identified the folowing needs:

Quotes

Here is a quote illustrating how cifkit addresses one of the challenges mentioned above.

"I am building an X-Ray diffraction analysis (XRD) pattern visualization script for my lab using pymatgen. I feel like cifkit integrated really well into my existing stable of libraries, while surpassing some alternatives in preprocessing and parsing. For example, it was often unclear at what stage an error occurred—whether during pre-processing with CifParser, or XRD plot generation with diffraction.core in pymatgen. The pre-processing logic in cifkit was communicated clearly, both in documentation and in actual outputs, allowing me to catch errors in my data before it was used in my visualizations. I now use cifkit by default for processing CIFs before they pass through the rest of my pipeline." - Alex Vtorov

Overview

Designed for individuals with minimal programming experience, cifkit provides two primary objects: Cif and CifEnsemble.

Cif

Cif is initialized with a .cif file path. It parses the .cif file, generates supercells, and computes nearest neighbors. It also determines coordination numbers using four different methods and generates polyhedrons for each site.

from cifkit import Cif
from cifkit import Example

# Initalize with the example file provided
cif = Cif(Example.Er10Co9In20_file_path)

# Print attributes
print("File name:", cif.file_name)
print("Formula:", cif.formula)
print("Unique element:", cif.unique_elements)

CifEnsemble

CifEnsemble is initialized with a folder path containing .cif files. It identifies unique attributes, such as space groups and elements, across the .cif files, moves and copies files based on these attributes. It generates histograms for all attributes.

from cifkit import CifEnsemble
from cifkit import Example

# Initialize
ensemble = CifEnsemble(Example.ErCoIn_folder_path)

# Get unique attributes
ensemble.unique_formulas
ensemble.unique_structures
ensemble.unique_elements
ensemble.unique_space_group_names
ensemble.unique_space_group_numbers
ensemble.unique_tags
ensemble.minimum_distances
ensemble_test.supercell_atom_counts

Tutorial and documentation

You may use example .cif files that can be easily imported, and you can visit the documentation page here.

Installation

To install

pip install cifkit

You may need to download other dependencies:

pip install cifkit pyvista gemmi

gemmi is used for parsing .cif files. pyvista is used for plotting polyhedrons.

Please check the pyproject.toml file for the full list of dependencies.

Testing

To run test locally.

# Install all dependencies in editable mode
pip install -e .

# Run test
pytest

Visuals

Polyhedron

You can visualize the polyhedron generated from each atomic site based on the coordination number geometry. In our research, the goal is to map the structure and coordination number with the physical property.

from cifkit import Cif

# Example usage
cif = Cif("your_cif_file_path")
site_labels = cif.site_labels

# Loop through each site
for label in site_labels:
    # Dipslay each polyhedron, a file saved for each
    cif.plot_polyhedron(label, is_displayed=True)

Polyhedron generation

Histograms

You can use CifEnsemble to visualize distributions of file counts based on specific attributes, etc. Learn all features from the documentation provided here.

By formulas:

Histogram

By structures:

Histogram

Open-source projects using cifkit

How to ask for help

cifkit is also designed for experimental materials scientists and chemists.

How to contribute

Here is how you can contribute to the cifkit project if you found it helpful:

Contributors

cifkit has been greatly enhanced thanks to the contributions from a diverse group of researchers:

We welcome all forms of contributions from the community. Your ideas and improvements are valued and appreciated.

Citation

Please consider citing cifkit if it has been useful for your research: