CifEnsemble

CifEnsemble#

Folder of .cif files: unique attributes, count stats, path filters, copy/move, and matplotlib histograms.

from cifkit import CifEnsemble, Example

ensemble = CifEnsemble(Example.demo_cif_folder_path)  # or any folder path
print(ensemble.file_count, ensemble.unique_formulas)
paths = ensemble.filter_by_formulas(["GdSb"])
ensemble.copy_cif_files(paths, "out")
ensemble.generate_structure_histogram(output_dir="histograms")

Filter methods (exact names): filter_by_formulas, filter_by_structures, filter_by_space_group_names, filter_by_space_group_numbers, filter_by_elements_containing, filter_by_elements_exact_matching, filter_by_tags, filter_by_composition_types, filter_by_site_mixing_types, filter_by_min_distance, filter_by_supercell_count, filter_by_CN_min_dist_method_containing, filter_by_CN_min_dist_method_exact_matching, filter_by_CN_best_methods_containing, filter_by_CN_best_methods_exact_matching.

Histograms: generate_structure_histogram, generate_formula_histogram, generate_tag_histogram, generate_space_group_name_histogram, generate_space_group_number_histogram, generate_elements_histogram, generate_supercell_size_histogram, generate_composition_type_histogram, generate_site_mixing_type_histogram, generate_CN_by_min_dist_method_histogram, generate_CN_by_best_methods_histogram.

Calibrated tables: API quick reference.
Tutorial: Statistics over many CIFs.
LLM recipes: llms.txt.

Full autodoc#

class cifkit.models.cif_ensemble.CifEnsemble(cif_dir_path: str, add_nested_files=False, preprocess=True, logging_enabled=False, supercell_size=3, compute_CN=False)#

Bases: object

Initialize a CifEnsemble object, containing a collection of Cif objects.

Parameters:

cif_dir_path (str) – Path to the folder path containing .cif file(s).
add_nested_files (bool, optional) – Option to include .cif files contained in sub-directories within cif_dir_path , by default False
preprocess (bool, optional) – Option to edit .cif files before initializing each into a Cif object, by default True. Preprocess modifies atomic site labels in atom_site_label. Some site labels may contain a comma or a symbol like M due to atomic mixing. It reformats each atom_site_label so it can be parsed into an element type matching atom_site_type_symbol. For PCD databases, addresses in publ_author_address often have an incorrect format requiring manual modifications. It also relocates any ill-formatted files, such as those with duplicate labels in atom_site_label, missing fractional coordinates, or files requiring supercell generation.
compute_CN (bool, optional) – Option to compute coordination numbers for each Cif object.
logging_enabled (bool, optional) – Option to log while pre-processing Cif objects, by default False

dir_path#

The path to the folder containing .cif files

Type:: str

file_paths#

The pist of file paths to .cif files

Type:: list[str]

cifs#

The list of Cif objects

Type:: list[Cif]

file_count#

The number of .cif files in the folder

Type:: int

logging_enabled#

The option to log while pre-processing Cif objects

Type:: bool

property unique_formulas: set[str]#

Get unique formulas from all .cif files in the folder.

Returns:: unique formulas
Return type:: set[str]

Examples

>>> cif_ensemble.unique_formulas
{"EuIr2Ge2", "CeRu2Ge2", "LaRu2Ge2", "Mo"}

property unique_structures: set[str]#

Get unique structures from all .cif files in the folder.

Examples

>>> cif_ensemble.unique_structures
{"CeAl2Ga2", "W"}

property unique_tags: set[str]#

Get unique formulas from all .cif files in the folder.

Examples

>>> cif_ensemble.unique_tags
{"hex", "rt", "rt_hex", ""}

property unique_space_group_names: set[str]#

Get unique space groups from all .cif files in the folder.

Examples

>>> cif_ensemble.unique_space_group_names
{"I4/mmm", "Im-3m"}

property unique_space_group_numbers: set[str]#

Get unique space groups from all .cif files in the folder.

Examples

>>> cif_ensemble.unique_space_group_numbers
{139, 229}

property unique_site_mixing_types: set[int]#

Get unique site mixing types from all .cif files in the folder.

Examples

>>> cif_ensemble.unique_site_mixing_types
{"deficiency_without_atomic_mixing", "full_occupancy"}

property unique_composition_types: set[int]#

Get unique composition types from all .cif files in the folder.

Examples

>>> cif_ensemble.unique_composition_types
{1, 3}

property unique_elements: set[str]#

Get unique elements from all .cif files in the folder.

Examples

>>> cif_ensemble.unique_elements_stats
{
    "Ce": 1,
    "Eu": 1,
    "Ge": 3,
    "Ir": 1,
    "La": 1,
    "Mo": 3,
    "Ru": 2,
}

property CN_unique_values_by_min_dist_method: set[str]#

Returns:: Unique coordination number values by minimum distance method from all .cif files.
Return type:: set[str]

property CN_unique_values_by_best_methods: set[str]#

Returns:: Unique coordination number by best methods from all .cif files.
Return type:: set[str]

property structure_stats: dict[str, int]#

property formula_stats: dict[str, int]#

property tag_stats: dict[str, int]#

property space_group_number_stats: dict[str, int]#

property space_group_name_stats: dict[str, int]#

property composition_type_stats: dict[str, int]#

property unique_elements_stats: dict[str, int]#

property site_mixing_type_stats: dict[str, int]#

property supercell_size_stats: dict[int, int]#

property unique_CN_values_by_min_dist_method_stat: dict[float, int]#

property unique_CN_values_by_method_methods_stat: dict[float, int]#

property minimum_distances: list[tuple[str, float]]#

property supercell_atom_counts: list[tuple[str, int]]#

filter_by_formulas(values: list[str]) → set[str]#

filter_by_structures(values: list[str]) → set[str]#

filter_by_space_group_names(values: list[str]) → set[str]#

filter_by_space_group_numbers(values: list[int]) → set[str]#

filter_by_site_mixing_types(values: list[str]) → set[str]#

filter_by_tags(values: list[str]) → set[str]#

filter_by_composition_types(values: list[int]) → set[str]#

filter_by_elements_containing(values: list[str]) → set[str]#

filter_by_elements_exact_matching(values: list[str]) → set[str]#

filter_by_CN_min_dist_method_containing(values: list[int]) → set[str]#

filter_by_CN_min_dist_method_exact_matching(values: list[int]) → set[str]#

filter_by_CN_best_methods_containing(values: list[int]) → set[str]#

filter_by_CN_best_methods_exact_matching(values: list[int]) → set[str]#

filter_by_min_distance(min_distance: float, max_distance: float) → set[str]#

filter_by_supercell_count(min_count: int, max_count: int) → set[str]#

move_cif_files(file_paths: set[str], to_directory_path: str) → None#

Move a set of CIF files to a destination directory.

Parameters:

file_paths (set[str]) – Set of file paths to CIF files.
to_directory_path (str) – Destination directory path.

Examples

>>> file_paths = {
    "tests/data/cif/ensemble_test/300169.cif",
    "tests/data/cif/ensemble_test/300170.cif",
}
>>> dest_dir_path = "tests/data/cif/ensemble_new_dir"
>>> cif_ensemble_test.move_cif_files(file_paths, dest_dir_path)

copy_cif_files(file_paths: set[str], to_directory_path: str) → None#

Copy a set of CIF files to a destination directory.

Parameters:

file_paths (set[str]) – Set of file paths to CIF files.
to_directory_path (str) – Destination directory path.

Examples

>>> file_paths = {
    "tests/data/cif/ensemble_test/300169.cif",
    "tests/data/cif/ensemble_test/300170.cif",
}
>>> dest_dir_path = "tests/data/cif/ensemble_new_dir"
>>> cif_ensemble_test.copy_cif_files(file_paths, dest_dir_path)

generate_structure_histogram(display=False, output_dir=None)#

Generate a histogram of the ‘structure’ property from CIF files.

This method creates a histogram based on the ‘structure’ statistics of the CIF files. If ‘output_dir’ is specified, the histogram image (.png) will be saved to that directory. If ‘output_dir’ is not specified, the image will be saved to the directory specified by ‘self.dir_path’.

Parameters:

display (bool, optional) – If True, the plot is displayed using plt.show(). Default is False.
output_dir (str, optional) – The directory path where the histogram should be saved. If None, the histogram is saved in the directory defined by ‘self.dir_path’.

generate_formula_histogram(display=False, output_dir=None)#

Generate a histogram of the ‘formula’ property from CIF files.

This method creates a histogram based on the ‘formula’ statistics of the CIF files. If ‘output_dir’ is specified, the histogram image (.png) will be saved to that directory. If ‘output_dir’ is not specified, the image will be saved to the directory specified by ‘self.dir_path’.

Parameters:

display (bool, optional) – If True, the plot is displayed using plt.show(). Default is False.
output_dir (str, optional) – The directory path where the histogram should be saved. If None, the histogram is saved in the directory defined by ‘self.dir_path’.

generate_tag_histogram(display=False, output_dir=None)#

Generate a histogram of the ‘tag’ property from CIF files.

This method creates a histogram based on the ‘tag’ statistics of the CIF files. If ‘output_dir’ is specified, the histogram image (.png) will be saved to that directory. If ‘output_dir’ is not specified, the image will be saved to the directory specified by ‘self.dir_path’.

Parameters:

display (bool, optional) – If True, the plot is displayed using plt.show(). Default is False.
output_dir (str, optional) – The directory path where the histogram should be saved. If None, the histogram is saved in the directory defined by ‘self.dir_path’.

generate_space_group_number_histogram(display=False, output_dir=None)#

Generate a histogram of the ‘space_group_number’ property from CIF files.

This method creates a histogram based on the ‘space_group_number’ statistics of the CIF files. If ‘output_dir’ is specified, the histogram image (.png) will be saved to that directory. If ‘output_dir’ is not specified, the image will be saved to the directory specified by ‘self.dir_path’.

Parameters:

display (bool, optional) – If True, the plot is displayed using plt.show(). Default is False.
output_dir (str, optional) – The directory path where the histogram should be saved. If None, the histogram is saved in the directory defined by ‘self.dir_path’.

generate_space_group_name_histogram(display=False, output_dir=None)#

Generate a histogram of the ‘space_group_name’ property from CIF files.

This method creates a histogram based on the ‘space_group_name’ statistics of the CIF files. If ‘output_dir’ is specified, the histogram image (.png) will be saved to that directory. If ‘output_dir’ is not specified, the image will be saved to the directory specified by ‘self.dir_path’.

Parameters:

display (bool, optional) – If True, the plot is displayed using plt.show(). Default is False.
output_dir (str, optional) – The directory path where the histogram should be saved. If None, the histogram is saved in the directory defined by ‘self.dir_path’.

generate_supercell_size_histogram(display=False, output_dir=None)#

Generate a histogram of the ‘supercell_count’ property from CIF files.

This method creates a histogram based on the ‘supercell_count’ statistics of the CIF files. If ‘output_dir’ is specified, the histogram image (.png) will be saved to that directory. If ‘output_dir’ is not specified, the image will be saved to the directory specified by ‘self.dir_path’.

Parameters:

display (bool, optional) – If True, the plot is displayed using plt.show(). Default is False.
output_dir (str, optional) – The directory path where the histogram should be saved. If None, the histogram is saved in the directory defined by ‘self.dir_path’.

generate_elements_histogram(display=False, output_dir=None)#

Generate a histogram of the ‘unique_elements’ property from CIF files.

This method creates a histogram based on the ‘unique_elements’ statistics of the CIF files. If ‘output_dir’ is specified, the histogram image (.png) will be saved to that directory. If ‘output_dir’ is not specified, the image will be saved to the directory specified by ‘self.dir_path’.

Parameters:

display (bool, optional) – If True, the plot is displayed using plt.show(). Default is False.
output_dir (str, optional) – The directory path where the histogram should be saved. If None, the histogram is saved in the directory defined by ‘self.dir_path’.

generate_CN_by_min_dist_method_histogram(display=False, output_dir=None)#

Generate a histogram of the ‘CN_by_min’ property from CIF files.

This method creates a histogram based on the ‘CN_by_min’ statistics of the CIF files. If ‘output_dir’ is specified, the histogram image (.png) will be saved to that directory. If ‘output_dir’ is not specified, the image will be saved to the directory specified by ‘self.dir_path’.

Parameters:

display (bool, optional) – If True, the plot is displayed using plt.show(). Default is False.
output_dir (str, optional) – The directory path where the histogram should be saved. If None, the histogram is saved in the directory defined by ‘self.dir_path’.

generate_CN_by_best_methods_histogram(display=False, output_dir=None)#

Generate a histogram of the ‘CN_by_best_methods’ property from CIF files.

This method creates a histogram based on the ‘CN_by_best_methods’ statistics of the CIF files. If ‘output_dir’ is specified, the histogram image (.png) will be saved to that directory. If ‘output_dir’ is not specified, the image will be saved to the directory specified by ‘self.dir_path’.

Parameters:

display (bool, optional) – If True, the plot is displayed using plt.show(). Default is False.
output_dir (str, optional) – The directory path where the histogram should be saved. If None, the histogram is saved in the directory defined by ‘self.dir_path’.

generate_composition_type_histogram(display=False, output_dir=None)#

Generate a histogram of the ‘composition_type’ property from CIF files.

This method creates a histogram based on the ‘composition_type’ statistics of the CIF files. If ‘output_dir’ is specified, the histogram image (.png) will be saved to that directory. If ‘output_dir’ is not specified, the image will be saved to the directory specified by ‘self.dir_path’.

Parameters:

display (bool, optional) – If True, the plot is displayed using plt.show(). Default is False.
output_dir (str, optional) – The directory path where the histogram should be saved. If None, the histogram is saved in the directory defined by ‘self.dir_path’.

generate_site_mixing_type_histogram(display=False, output_dir=None)#

Generate a histogram of the ‘site_mixing_type’ property from CIF files.

This method creates a histogram based on the ‘site_mixing_type’ statistics of the CIF files. If ‘output_dir’ is specified, the histogram image (.png) will be saved to that directory. If ‘output_dir’ is not specified, the image will be saved to the directory specified by ‘self.dir_path’.

Parameters:

display (bool, optional) – If True, the plot is displayed using plt.show(). Default is False.
output_dir (str, optional) – The directory path where the histogram should be saved. If None, the histogram is saved in the directory defined by ‘self.dir_path’.

CifEnsemble

Contents

CifEnsemble#

Full autodoc#