robocrys.describe package

Submodules

robocrys.describe.adapter module

This module implements a class to resolve the symbolic references in condensed structure data.

class robocrys.describe.adapter.ComponentDetails(formula, count, dimensionality, molecule_name, orientation, nsites, index)

Bases: tuple

count

Alias for field number 1

dimensionality

Alias for field number 2

formula

Alias for field number 0

index

Alias for field number 6

molecule_name

Alias for field number 3

nsites

Alias for field number 5

orientation

Alias for field number 4

class robocrys.describe.adapter.ComponentGroup(formula, dimensionality, count, components, molecule_name, nsites)

Bases: tuple

components

Alias for field number 3

count

Alias for field number 2

dimensionality

Alias for field number 1

formula

Alias for field number 0

molecule_name

Alias for field number 4

nsites

Alias for field number 5

class robocrys.describe.adapter.DescriptionAdapter(condensed_structure, use_iupac_ordering=True)

Bases: BaseAdapter

Class to facilitate pulling data from the condensed structure dictionary.

sym_labels

The symmetry labels as strings.

use_iupac_ordering

Whether to order formulas by the iupac “electronegativity” series, defined in Table VI of “Nomenclature of Inorganic Chemistry (IUPAC Recommendations 2005)”. This ordering effectively follows the groups and rows of the periodic table, except the Lanthanides, Actanides and hydrogen. If set to False, the elements will be ordered according to the electronegativity values.

Type:

bool, optional

Parameters:

condensed_structure (dict[str, Any]) – The condensed structure data, formatted as produced by robocrys.condense.StructureCondenser.condense_structure().

get_component_details()

Gets a summary of all components.

Return type:

list[ComponentDetails]

Returns:

A list of ComponentDetails objects, each with the attributes:

• count (int): The number of these components in the structure.

• formula (str): The component formula.

• dimensionality (int): The component dimensionality.

• molecule_name (str or None): The molecule name if applicable, else None.

• orientation (tuple[int]): The component orientation.

• index (list[int]): The component inequivalent index.

get_component_groups()

Gets a summary of all components groups.

Return type:

list[ComponentGroup]

Returns:

The components, grouped together by formula, dimensionality and molecule name. The data will be returned as a list of ComponentGroup objects, each with the attributes:

• count (int): The total number of components in this group.

• formula (str): The formula of the components.

• dimensionality (int): The dimensionality of the components.

• molecule_name (str or None): The molecule name if applicable, else None.

• components (list[ComponentDetails]): The components in the group.

get_component_site_groups(component_index)

Gets a summary of the sites in a component.

Return type:

list[SiteGroup]

Returns:

The sites, grouped together by element. The data will be returned as a list of SiteGroup objects, each with the attributes:

• count (int): The total number of sites in this group.

• element (str): The site element.

• sites (list[int]): A list of site indices in this group.

get_nearest_neighbor_details(site_index, group=False)

Gets a summary of all the nearest neighbors to a site.

Parameters:

• site_index (int) – An inequivalent site index.

• group (bool) – Whether to group all nearest neighbor sites with the same element together.

Return type:

list[NeighborSiteDetails]

Returns:

A list of NeighborSiteDetails objects, each with the attributes:

• element (str): The element of the nearest neighbor site.

• count (int): The number of sites of this type.

• sym_label (str): The symmetry label.

• sites (list[int]): The site indices representing this nearest neighbor. Can be more than one site if group_by_element=True.

get_next_nearest_neighbor_details(site_index, group=False)

Gets a summary of all the next nearest neighbors to a site.

We only get the summaries for next nearest neighbor sites that have a geometry type listed in robocrys.util.connected_geometries and have a poly_formula.

Parameters:

• site_index (int) – An inequivalent site index.

• group (bool) – Whether to group together all next nearest neighbor sites with the same element, connectivity and geometry but different symmetry labels.

Return type:

list[NextNeighborSiteDetails]

Returns:

A list of NextNeighborSiteDetails objects, each with the attributes:

• element (str): The element of the next nearest neighbor site.

• connectivity (str): The connectivity type to this site.

• geometry (str): The geometry type of the next nearest neighbor.

• count (int): The number of sites of this type.

• sym_label (str): The symmetry label.

• sites (list[int]): The site indices representing this next nearest neighbor. Can be more than one site if group=True.

• poly_formula (str): The polyhedral formula.

get_sym_label(site_indices)

Convert site indices into a formatted symmetry label.

Parameters:

site_indices (int | list[int]) – THe site indices.

Return type:

str

Returns:

The formatted symmetry label. E.g., if the set of symmetry labels for the sites looks like (1, 2), the symmetry label will be (1,2).

class robocrys.describe.adapter.NeighborSiteDetails(element, count, sites, sym_label)

Bases: tuple

count

Alias for field number 1

element

Alias for field number 0

sites

Alias for field number 2

sym_label

Alias for field number 3

class robocrys.describe.adapter.NextNeighborSiteDetails(element, count, geometry, sites, sym_label, connectivity, poly_formula)

Bases: tuple

connectivity

Alias for field number 5

count

Alias for field number 1

element

Alias for field number 0

geometry

Alias for field number 2

poly_formula

Alias for field number 6

sites

Alias for field number 3

sym_label

Alias for field number 4

class robocrys.describe.adapter.SiteGroup(element, count, sites)

Bases: tuple

count

Alias for field number 1

element

Alias for field number 0

sites

Alias for field number 2

robocrys.describe.describer module

This module provides a class for generating descriptions of condensed structure data.

class robocrys.describe.describer.StructureDescriber(describe_mineral=True, describe_component_makeup=True, describe_components=True, describe_symmetry_labels=True, describe_oxidation_states=True, describe_bond_lengths=True, bond_length_decimal_places=2, distorted_tol=0.6, only_describe_cation_polyhedra_connectivity=True, only_describe_bonds_once=True, fmt='raw', return_parts=False)

Bases: object

describe(condensed_structure)

Convert a condensed structure into a text description.

Parameters:

condensed_structure (dict[str, Any]) – The condensed structure data, formatted as produced by StructureCondenser.condense_structure().

Return type:

str | dict[str, str]

Returns:

A description of the structure. If StructureDescriber.return_parts is False, the description will be returned as a str. If it is equal to True, the description will be returned as a dict with the keys ‘mineral’, ‘component_makeup’ and ‘components’, each containing the relevant part of the description.

get_all_component_descriptions()

Gets the descriptions of all components in the structure.

Return type:

str

Returns:

A description of all components in the structure.

get_bond_length_description(from_site, to_sites)

Gets a description of the bond lengths between two sets of sites.

Parameters:

• from_site (int) – An inequivalent site index.

• to_sites (list[int]) – A list of site indices. The site indices should all be for the same element.

Return type:

str

Returns:

A description of the bond lengths or an empty string if StructureDescriber.only_describe_bonds_once is True and all all bond lengths have already been described.

get_component_description(component_index, single_component=False)

Gets the descriptions of all sites in a component.

Parameters:

• component_index (int) – The index of the component

• single_component (bool) – Whether the structure contains only a single component.

Return type:

str

Returns:

The description for all sites in the components.

get_component_makeup_summary()

Gets a summary of the makeup of components in a structure.

Return type:

str

Returns:

A description of the number of components and their dimensionalities and orientations.

get_mineral_description()

Gets the mineral name and space group description.

If the structure is a perfect match for a known prototype (e.g. the distance parameter is -1, the mineral name is the prototype name. If a structure is not a perfect match but similar to a known mineral, “-like” will be added to the mineral name. If the structure is a good match to a mineral but contains a different number of element types than the mineral prototype, “-derived” will be added to the mineral name.

Return type:

str

Returns:

The description of the mineral name.

get_octahedral_tilt_description(site_index)

Gets a description of octahedral tilting angles between two sites.

Currently only implemented for corner-sharing octahedra. Will throw an error if the two sites are not next nearest neighbors.

Parameters:

site_index (int) – An inequivalent site index.

Return type:

str

Returns:

A description of the octahedral tilting angles.

get_site_description(site_index)

Gets a description of the geometry and bonding of a site.

If the site likeness (order parameter) is less than distorted_tol, “distorted” will be added to the geometry description.

Parameters:

site_index (int) – An inequivalent site index.

Return type:

str

Returns:

A description of the geometry and bonding of a site.

robocrys.describe.describer.get_mineral_name(mineral_dict)

Get the mineral name from a mineral dictionary.

Parameters:

mineral_dict (dict[str, Any]) – The mineral dictionary from the condensed description.

Return type:

Optional[str]

Returns:

If mineral_dict["type"] is set, the mineral name will be returned as a string, else None will be returned.

Module contents