Cif

Cif#

One .cif file: parse structure metadata, interatomic distances, coordination numbers (four methods), polyhedron metrics, bond fractions, site mixing, and polyhedron plots.

from cifkit import Cif, Example

cif = Cif(Example.GdSb_file_path)           # or Cif("/path/to/file.cif")
cif = Cif(path, supercell_size=3, compute_CN=False, is_formatted=False)

Parameter	Default	Role
`file_path`	required	Path to the `.cif`
`is_formatted`	`False`	If `False`, preprocess for gemmi compatibility
`logging_enabled`	`False`	Verbose logging
`supercell_size`	`3`	`3` → ±1 shifts (3×3×3 supercell)
`compute_CN`	`False`	If `True`, run coordination at init

Calibrated attribute / method tables: API quick reference.
Tutorial: Parse physical features from a .cif.
LLM recipes: llms.txt.

Common attributes (GdSb demo types)#

Name	Type	Example / notes
`formula`	`str`	`'GdSb'`
`structure`	`str`	`'NaCl'`
`space_group_name`	`str`	`'Fm-3m'`
`space_group_number`	`int`	`225`
`unitcell_lengths`	`list[float]`	`[6.21, 6.21, 6.21]`
`unitcell_angles`	`list[float]`	radians, not degrees
`site_labels`	`list[str]`	`['Sb', 'Gd']`
`shortest_distance`	`float`	Å
`shortest_bond_pair_distance`	`dict`	`{('Gd','Sb'): 3.105, …}`
`connections`	`dict`	per-site neighbor lists
`CN_best_methods`	`dict`	after `compute_CN()`
`CN_bond_fractions_by_min_dist_method`	`dict`	after `compute_CN()`
`site_mixing_type`	`str`	e.g. `'full_occupancy'`

Methods#

compute_connections() - neighbor search (also lazy)
compute_CN() - four CN methods + best method + polyhedron metrics
plot_polyhedron(label, show_labels=True, is_displayed=False, output_dir=None)
get_polyhedron_labels_by_CN_min_dist_method / …_by_CN_best_methods

Full autodoc#

class cifkit.models.cif.Cif(file_path: str, is_formatted=False, logging_enabled=False, supercell_size=3, compute_CN=False)#

Bases: object

Initialize an object from a .cif file.

Parameters:

file_path (str) – Path to the .cif file.
is_formatted (bool, default) – If False, preprocess the .cif file to ensure compatibility with the gemmi library.
logging_enabled (bool, default False) – Enables detailed logging during initialization and for distance calculations.
supercell_size (int, default 3) – Size of the supercell to be generated. Default is 3. Method 1 - No shifts Method 2 - ±1 shifts (3x3x3 of the unit cell) Method 3 - ±2 shifts (5×5×5 of the unit cell)
compute_CN (bool, default False) – Option to compute CN related metrics for each Cif object.

file_path#

Path to the CIF file from which data is loaded.

Type:: str

logging_enabled#

Enables detailed logging for initialization and distance alculations if set to True.

Type:: bool

file_name#

Base name of the CIF file, extracted from file_path.

Type:: str

file_name_without_ext#

File name without its extension, useful for referencing or generating derivative files.

Type:: str

db_source#

Source database (e.g., ICSD, MP, CCDC, PCD) from which the CIF file originates, determined at runtime.

Type:: str

unitcell_lengths#

List of unit cell lengths for the crystal structure, typically in Angstroms.

Type:: list[float]

unitcell_angles#

List of unit cell angles in radians, ordered by alpha, beta, gamma.

Type:: list[float]

site_labels#

Lists all unique atomic site labels.

Type:: list[str]

unique_elements#

Set of unique chemical elements present in the CIF file.

Type:: set[str]

atom_site_info#

Dictionary containing detailed information about each atomic site including element, site occupancy, fractional coordinates, symmetry, and multiplicity.

Type:: dict[str, any]

composition_type#

Number of unique elements present in the .cif file, e.g., 1 for unary, 2 for binary, etc.

Type:: int

tag#

Additional tag associated with the CIF data, parsed from the third line of PCD .cif files.

Type:: str

bond_pairs#

Set of tuples representing bonded pairs of elements.

Type:: set[tuple[str, str]]

site_label_pairs#

Set of tuples representing pairs of atomic site labels.

Type:: set[tuple[str, str]]

bond_pairs_sorted_by_mendeleev#

Set of bonded pairs sorted according to Mendeleev Numbers.

Type:: set[tuple[str, str]]

site_label_pairs_sorted_by_mendeleev#

Set of site label pairs sorted by Mendeleev Numbers.

Type:: set[tuple[str, str]]

site_mixing_type#

Descriptor of the mixing type, categorized into four types: Full occupancy is assigned when a single atomic site occupies the fractional coordinate with an occupancy value of 1. Full occupancy with mixing is assigned when multiple atomic sites collectively occupy the fractional coordinate to a sum of 1. Deficiency without mixing is assigned when a single atomic site occupying the fractional coordinate with a sum less than 1. Deficiency with atomic mixing is assigned when multiple atomic sites occupy the fractional coordinate with a sum less than 1.

Type:: str

is_radius_data_available#

Indicates whether Pauling and CIF atomic radii are available for all elements in the .cif file.

Type:: bool

mixing_info_per_label_pair#

Dictionary mapping pairs of labels to their mixing information.

Type:: dict

mixing_info_per_label_pair_sorted_by_mendeleev#

Same as mixing_info_per_label_pair, but sorted according to Mendeleev numbers.

Type:: dict

unitcell_points#

List of points defining the unit cell; each point contains fractional coordinates and a site label.

Type:: list[list[tuple[float, float, float, str]]]

supercell_points#

List of points defining the supercell of the cell For each .cif file, a unit cell is generated by applying the symmetry operations. A supercell is generated by applying ±1 shifts from the unit cell.

Type:: list[list[tuple[float, float, float, str]]]

unitcell_atom_count#

Total count of atoms within the unit cell.

Type:: int

supercell_atom_count#

Total count of atoms within the generated supercell incorporating ±1, ±1, ±1 translations.

Type:: int

connections#

Initially None, intended to store connection data related to the crystal structure. Connections are computed lazily and are only calculated when first needed by a method or property requiring them.

Type:: None or dict

compute_connections(cutoff_radius=10.0) → None#

Compute onnection network, shortest distances, bond counts, and coordination numbers (CN). These prperties are lazily loaded to avoid unnecessary computation during the initialization and pre-processing step.

Parameters:: cutoff_radius (float, default=10.0) – The distance threshold in Angstroms used to consider two atoms as connected.

compute_CN() → None#

Compute onnection network, shortest distances, bond counts, and coordination numbers (CN). These prperties are lazily loaded to avoid unnecessary computation during the initialization and pre-processing step.

Parameters:: cutoff_radius (float, default=10.0) – The distance threshold in Angstroms used to consider two atoms as connected.

property shortest_distance#

property connections_flattened#

property shortest_bond_pair_distance#

property shortest_site_pair_distance#

property radius_values#

property radius_sum#

property CN_max_gap_per_site#

Determines the maximum gap in coordination number (CN) for each atomic site.

For each atomic site, considers the first 20 nearest neighbors. The distances to these neighbors are normalized based on four methods:

dist_by_shortest_dist: Normalization by the shortest distance from the site.
dist_by_CIF_radius_sum: Normalization by the sum of CIF radii.
dist_by_CIF_radius_refined_sum: Normalization by the sum of refined CIF radii.
dist_by_Pauling_radius_sum: Normalization by the sum of Pauling radii.

The radius sums are calculated for each element pair involved. For each normalization method, the maximum gap is determined as the largest difference between consecutive normalized distances (i.e., the difference between the nth and (n-1)th neighbors).

This CN gap provides insight into the bonding relevance for each site.

Returns:

A dictionary where each key represents an atomic site, mapping to another dictionary with normalization methods as keys. Each normalization method contains a dictionary with:

max_gap (float): The maximum gap in the normalized distances.
CN (int): Coordination number based on the normalization method.

Return type:

dict of dict of dict

Examples

>>> cif.CN_max_gap_per_site
{
    "In1": {
        "dist_by_shortest_dist": {"max_gap": 0.306, "CN": 14},
        "dist_by_CIF_radius_sum": {"max_gap": 0.39, "CN": 14},
        "dist_by_CIF_radius_refined_sum": {"max_gap": 0.341, "CN": 12},
        "dist_by_Pauling_radius_sum": {"max_gap": 0.398, "CN": 14},
    },
    "U1": {
        "dist_by_shortest_dist": {"max_gap": 0.197, "CN": 11},
        "dist_by_CIF_radius_sum": {"max_gap": 0.312, "CN": 11},
        "dist_by_CIF_radius_refined_sum": {"max_gap": 0.27, "CN": 17},
        "dist_by_Pauling_radius_sum": {"max_gap": 0.256, "CN": 17},
    },
    "Rh1": {
        "dist_by_shortest_dist": {"max_gap": 0.315, "CN": 9},
        "dist_by_CIF_radius_sum": {"max_gap": 0.347, "CN": 9},
        "dist_by_CIF_radius_refined_sum": {"max_gap": 0.418, "CN": 9},
        "dist_by_Pauling_radius_sum": {"max_gap": 0.402, "CN": 9},
    },
    "Rh2": {
        "dist_by_shortest_dist": {"max_gap": 0.31, "CN": 9},
        "dist_by_CIF_radius_sum": {"max_gap": 0.324, "CN": 9},
        "dist_by_CIF_radius_refined_sum": {"max_gap": 0.397, "CN": 9},
        "dist_by_Pauling_radius_sum": {"max_gap": 0.380, "CN": 9},
    },
}

property CN_best_methods#

Determines the optimal coordination method for each atomic site.

For each atomic site, the coordination polyhedron is generated for each method in self.CN_max_gap_per_site. The method with the smallest value of polyhedron_metrics[“distance_from_avg_point_to_center”], indicating the highest symmetry of the polyhedron, is selected as the “best method” among the four methods used to determine the CN gap in self.CN_max_gap_per_site.

Returns:

Dictionary where each key represents an atomic site, and the corresponding value is a dictionary containing:

volume_of_polyhedron (float): The volume of the polyhedron surrounding the atomic site.
distance_from_avg_point_to_center (float): The average distance from the polyhedron’s vertices to its geometric center, used as a measure of symmetry.
number_of_vertices (int): The number of vertices in the coordination polyhedron.
number_of_edges (int): The number of edges connecting vertices in the polyhedron.
number_of_faces (int): The number of faces in the coordination polyhedron.
shortest_distance_to_face (float): The shortest distance between the atomic site and the nearest face.
shortest_distance_to_edge (float): The shortest distance between the atomic site and the nearest edge.
volume_of_inscribed_sphere (float): Volume of the largest sphere that can it inside the polyhedron.
packing_efficiency (float): A measure of how efficiently the polyhedron is packed around the atomic site.
method_used (str): The name of the chosen method (e.g., dist_by_shortest_dist) providing the highest symmetry based on distance_from_avg_point_to_center.

Return type:

dict[str, dict[str, float | int | str]]]

Examples

>>> CN_best_methods = cif_URhIn.CN_best_methods
>>> CN_best_methods["In1"]["number_of_vertices"] == 14
>>> CN_best_methods["Rh2"]["number_of_vertices"] == 9
>>> CN_best_methods["In1"]["method_used"] == "dist_by_shortest_dist"
>>> CN_best_methods["Rh2"]["method_used"] == "dist_by_shortest_dist"

property CN_connections_by_best_methods#

property CN_connections_by_min_dist_method#

property CN_bond_count_by_min_dist_method#

property CN_bond_count_by_best_methods#

property CN_bond_count_by_min_dist_method_sorted_by_mendeleev#

property CN_bond_count_by_best_methods_sorted_by_mendeleev#

property CN_bond_fractions_by_min_dist_method#

property CN_bond_fractions_by_best_methods#

property CN_bond_fractions_by_min_dist_method_sorted_by_mendeleev#

property CN_bond_fractions_by_best_methods_sorted_by_mendeleev#

property CN_unique_values_by_min_dist_method#

property CN_unique_values_by_best_methods#

property CN_avg_by_min_dist_method#

property CN_avg_by_best_methods#

property CN_max_by_min_dist_method#

property CN_max_by_best_methods#

property CN_min_by_min_dist_method#

property CN_min_by_best_methods#

get_polyhedron_labels_by_CN_min_dist_method(label: str) → tuple[list[list[float]], list[str]]#

get_polyhedron_labels_by_CN_best_methods(label: str) → tuple[list[list[float]], list[str]]#

plot_polyhedron(site_label: str, show_labels=True, is_displayed=False, output_dir=None) → None#

Function to plot a polyhedron structure and optionally saves it.

Parameters:

site_label (str) – Central site label for the polyhedron
show_labels (bool, optional) – Whether to display vertex labels, by default True
is_displayed (bool, optional) – Display plot interactively, by default False
output_dir (str, optional) – Directory to save the plot, by default None

Cif

Contents

Cif#

Common attributes (GdSb demo types)#

Methods#

Full autodoc#