pyecif 0.1.2.post1

ECIF file format tools for Python.

ECIF

Extended Crystallographic Information File, which allows you to put multiple crystal structures into the same .ecif file and add additional properties to facilitate various usage scenarios, such as machine learning data. Inspired by the SDF(structure data files) and RDkit PandasTools.

ECIFPandasTools

This Python module provides some tools for handling the conversion between ECIF files and pandas dataframes. ECIF files are a file format used for storing formatted crystal structure information, while pandas dataframes are a data structure used for data analysis.

Installation

You can install the pyecif module via pip. To do this, you need to run the following command in your terminal:

pip install pyecif

Features

• WriteEcif(df, out, idName='ID', cifColName='CIF', properties=None): Writes a pandas dataframe to an ECIF file. Each row in the dataframe is converted into an ECIF block, each block contains a CIF part and some additional properties.

• LoadEcif(ecif_file, idName='ID', cifColName='CIF'): Loads data from an ECIF file into a pandas dataframe. Each ECIF block is converted into a row in the dataframe.

• CifBlock: This is a class for handling ECIF blocks. It provides some methods for setting and getting properties, adding CIF lines, adding CIF from pymatgen structures, getting CIF, getting the entire block, getting pymatgen structures from CIF, adding the entire block, and writing to CIF files.

Usage

First, you need to have a pandas dataframe that contains some pymatgen Structure objects. Then, you can use the WriteEcif function to write this dataframe to an ECIF file. For example:

from pyecif import WriteEcif

# Assume you have a dataframe named df, which contains a column of Structure objects named 'CIF'
WriteEcif(df, 'output.ecif', cifColName='CIF', properties=df.columns)

Then, you can use the LoadEcif function to load data from the ECIF file into a new dataframe. For example:

from pyecif import LoadEcif

df = LoadEcif('output.ecif', cifColName='CIF')

Note that both of these functions accept some optional parameters for specifying the names of certain columns in the dataframe, as well as additional properties to be included in the ECIF file.

Below is a snapshot of our data frame (df). It contains the fields ID, exfoliation energy (exfoliation_en) and crystal structure (CIF).

ID	exfoliation_en	CIF
mb-jdft2d-001	63.593833	<gemmi.SmallStructure: SrSbSe2F>
mb-jdft2d-002	134.86375	<gemmi.SmallStructure: AgI>
mb-jdft2d-003	43.114667	<gemmi.SmallStructure: Mg(ReO4)2>
mb-jdft2d-004	240.715488	<gemmi.SmallStructure: Si3H>
mb-jdft2d-005	67.442833	<gemmi.SmallStructure: CoO2>
...	...	...
mb-jdft2d-632	26.426545	<gemmi.SmallStructure: HgBr2
mb-jdft2d-633	43.574286	<gemmi.SmallStructure: FeCl3
mb-jdft2d-634	88.808659	<gemmi.SmallStructure: HoBrO
mb-jdft2d-635	132.26525	<gemmi.SmallStructure: GaHO2
mb-jdft2d-636	63.564333	<gemmi.SmallStructure: TaCoTe2

The default is to use gemmi to load the data, one can also choose pymatgen to load the data.

from pyecif import LoadEcif

df = LoadEcif('output.ecif', cifColName='CIF', type='pymatgen')

To better understand the contents of the CIF field, the details of df['CIF'][0] is as below with pymatgen. This is an example describing the position of the elements Hf, Si and Te in the crystal structure, which is the pymatgen.core.Structure class:

Structure Summary
Lattice
    abc : 3.66730534 3.66730534 27.311209
 angles : 90.0 90.0 90.0
 volume : 367.31195815130786
      A : 3.66730534 0.0 2.245576873063498e-16
      B : -2.245576873063498e-16 3.66730534 2.245576873063498e-16
      C : 0.0 0.0 27.311209
    pbc : True True True
PeriodicSite: Hf0 (Hf) (1.493, 3.327, 7.263) [0.4072, 0.9072, 0.2659]
PeriodicSite: Hf1 (Hf) (3.327, 1.493, 3.049) [0.9072, 0.4072, 0.1116]
PeriodicSite: Si2 (Si) (3.327, 3.327, 5.156) [0.9072, 0.9072, 0.1888]
PeriodicSite: Si3 (Si) (1.493, 1.493, 5.156) [0.4072, 0.4072, 0.1888]
PeriodicSite: Te4 (Te) (3.327, 1.493, 8.659) [0.9072, 0.4072, 0.3171]
PeriodicSite: Te5 (Te) (1.493, 3.327, 1.652) [0.4072, 0.9072, 0.06049]

Matbench

Matbench is a benchmark dataset for materials science. You can easily obtain the ECIF format of the Matbench dataset using the example script scripts/get_matbench_jdft2d.py.

Time cost

Total time: 27.1109 s for 106201 structure (matbench_mp_e_form:train)