robocrys package

Subpackages

• robocrys.condense package
  • Submodules
  • robocrys.condense.component module
    • components_are_isomorphic()
    • components_are_vdw_heterostructure()
    • filter_molecular_components()
    • get_component_formula()
    • get_component_formula_and_factor()
    • get_formula_from_components()
    • get_formula_inequiv_components()
    • get_reconstructed_structure()
    • get_structure_inequiv_components()
    • get_sym_inequiv_components()
    • get_vdw_heterostructure_information()
  • robocrys.condense.condenser module
    • StructureCondenser
      • StructureCondenser.condense_structure()
  • robocrys.condense.fingerprint module
    • get_fingerprint_distance()
    • get_site_fingerprints()
    • get_structure_fingerprint()
  • robocrys.condense.mineral module
    • MineralMatcher
      • MineralMatcher.get_aflow_matches()
      • MineralMatcher.get_best_mineral_name()
      • MineralMatcher.get_fingerprint_matches()
  • robocrys.condense.molecule module
    • MoleculeNamer
      • MoleculeNamer.get_name_from_molecule_graph()
      • MoleculeNamer.get_name_from_pubchem()
      • MoleculeNamer.molecule_graph_to_smiles()
      • MoleculeNamer.name_sources
  • robocrys.condense.site module
    • SiteAnalyzer
      • SiteAnalyzer.symmetry_labels
      • SiteAnalyzer.equivalent_sites
      • SiteAnalyzer.get_all_bond_distance_summaries()
      • SiteAnalyzer.get_all_connectivity_angle_summaries()
      • SiteAnalyzer.get_all_nnn_distance_summaries()
      • SiteAnalyzer.get_all_site_summaries()
      • SiteAnalyzer.get_bond_distance_summary()
      • SiteAnalyzer.get_connectivity_angle_summary()
      • SiteAnalyzer.get_inequivalent_site_indices()
      • SiteAnalyzer.get_nearest_neighbors()
      • SiteAnalyzer.get_next_nearest_neighbors()
      • SiteAnalyzer.get_nnn_distance_summary()
      • SiteAnalyzer.get_site_geometry()
      • SiteAnalyzer.get_site_summary()
    • geometries_match()
    • nn_summaries_match()
    • nnn_summaries_match()
  • Module contents
• robocrys.describe package
  • Submodules
  • robocrys.describe.adapter module
    • ComponentDetails
      • ComponentDetails.count
      • ComponentDetails.dimensionality
      • ComponentDetails.formula
      • ComponentDetails.index
      • ComponentDetails.molecule_name
      • ComponentDetails.nsites
      • ComponentDetails.orientation
    • ComponentGroup
      • ComponentGroup.components
      • ComponentGroup.count
      • ComponentGroup.dimensionality
      • ComponentGroup.formula
      • ComponentGroup.molecule_name
      • ComponentGroup.nsites
    • DescriptionAdapter
      • DescriptionAdapter.sym_labels
      • DescriptionAdapter.use_iupac_ordering
      • DescriptionAdapter.get_component_details()
      • DescriptionAdapter.get_component_groups()
      • DescriptionAdapter.get_component_site_groups()
      • DescriptionAdapter.get_nearest_neighbor_details()
      • DescriptionAdapter.get_next_nearest_neighbor_details()
      • DescriptionAdapter.get_sym_label()
    • NeighborSiteDetails
      • NeighborSiteDetails.count
      • NeighborSiteDetails.element
      • NeighborSiteDetails.sites
      • NeighborSiteDetails.sym_label
    • NextNeighborSiteDetails
      • NextNeighborSiteDetails.connectivity
      • NextNeighborSiteDetails.count
      • NextNeighborSiteDetails.element
      • NextNeighborSiteDetails.geometry
      • NextNeighborSiteDetails.poly_formula
      • NextNeighborSiteDetails.sites
      • NextNeighborSiteDetails.sym_label
    • SiteGroup
      • SiteGroup.count
      • SiteGroup.element
      • SiteGroup.sites
  • robocrys.describe.describer module
    • StructureDescriber
      • StructureDescriber.describe()
      • StructureDescriber.get_all_component_descriptions()
      • StructureDescriber.get_bond_length_description()
      • StructureDescriber.get_component_description()
      • StructureDescriber.get_component_makeup_summary()
      • StructureDescriber.get_mineral_description()
      • StructureDescriber.get_octahedral_tilt_description()
      • StructureDescriber.get_site_description()
    • get_mineral_name()
  • Module contents
• robocrys.featurize package
  • Submodules
  • robocrys.featurize.adapter module
    • FeaturizerAdapter
      • FeaturizerAdapter.all_bond_lengths()
      • FeaturizerAdapter.average_anion_coordination_number
      • FeaturizerAdapter.average_cation_coordination_number
      • FeaturizerAdapter.average_coordination_number
      • FeaturizerAdapter.average_corner_sharing_octahedral_tilt_angle
      • FeaturizerAdapter.component_dimensionalities
      • FeaturizerAdapter.contains_connected_geometry()
      • FeaturizerAdapter.contains_corner_sharing_polyhedra
      • FeaturizerAdapter.contains_edge_sharing_polyhedra
      • FeaturizerAdapter.contains_face_sharing_polyhedra
      • FeaturizerAdapter.contains_geometry_type()
      • FeaturizerAdapter.contains_molecule()
      • FeaturizerAdapter.contains_named_molecule
      • FeaturizerAdapter.contains_polyhedra
      • FeaturizerAdapter.frac_site_geometry()
      • FeaturizerAdapter.frac_sites_n_coordinate()
      • FeaturizerAdapter.frac_sites_polyhedra
      • FeaturizerAdapter.is_dimensionality()
      • FeaturizerAdapter.is_intercalated
      • FeaturizerAdapter.is_interpenetrated
  • robocrys.featurize.featurizer module
    • RobocrysFeaturizer
      • RobocrysFeaturizer.citations()
      • RobocrysFeaturizer.feature_labels()
      • RobocrysFeaturizer.featurize()
      • RobocrysFeaturizer.implementors()
  • Module contents

Submodules

robocrys.adapter module

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

class robocrys.adapter.BaseAdapter(condensed_structure)

Bases: object

Base adapter class for facilitating access to condensed structure data.

elements

The site elements.

Parameters:

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

property angles: dict[int, dict[int, dict[str, list[float]]]]

The angle data.

See robocrys.condense.StructureCondenser.condense_structure() for more details.

property component_makeup: list[int]

The component makeup of the structure.

See robocrys.condense.StructureCondenser.condense_structure() for more details.

property components: dict[int, dict[str, Any]]

The component data.

See robocrys.condense.StructureCondenser.condense_structure() for more details.

property crystal_system: str

The crystal system.

See robocrys.condense.StructureCondenser.condense_structure() for more details.

property dimensionality: int

The overall dimensionality.

See robocrys.condense.StructureCondenser.condense_structure() for more details.

property distances: dict[int, dict[int, list[float]]]

The distance data.

See robocrys.condense.StructureCondenser.condense_structure() for more details.

property formula: str

The structure formula.

See robocrys.condense.StructureCondenser.condense_structure() for more details.

get_angle_details(from_site, to_sites, connectivity)

Gets the connectivity angles between two sets of sites.

Parameters:

• from_site (int) – An inequivalent site index.

• to_sites (int | list[int]) – One or more inequivalent site indices.

• connectivity (str) – The site connectivity type. I.e. “corner”, “edge”, or “face”.

Return type:

list[float]

Returns:

The distances between the sites.

get_distance_details(from_site, to_sites)

Gets the bond lengths between two sets of sites.

Parameters:

• from_site (int) – An inequivalent site index.

• to_sites (int | list[int]) – One or more inequivalent site indices.

Return type:

list[float]

Returns:

The distances between the sites.

property is_vdw_heterostructure: bool

Whether the structure is a vdw heterostructure.

See robocrys.condense.StructureCondenser.condense_structure() for more details.

property mineral: dict[str, str | int | bool]

The mineral data.

See robocrys.condense.StructureCondenser.condense_structure() for more details.

property sites: dict[int, dict[str, Any]]

The site data.

See robocrys.condense.StructureCondenser.condense_structure() for more details.

property spg_symbol: str

The space group symbol.

See robocrys.condense.StructureCondenser.condense_structure() for more details.

robocrys.cli module

This module contains a script for using robocrys from the command line.

robocrys.cli.main()

robocrys.cli.robocrystallographer(structure, condenser_kwargs=None, describer_kwargs=None)

Gets the robocrystallographer description of a structure.

Parameters:

• structure (Structure) – A structure.

• condenser_kwargs (Optional[dict]) – Keyword arguments that will be passed to robocrys.condense.StructureCondenser.

• describer_kwargs (Optional[dict]) – Keyword arguments that will be passed to robocrys.describe.StructureDescriber.

Return type:

str

Returns:

The description.

robocrys.util module

Miscellaneous utility functions and common data.

robocrys.util.common_formulas

A set of common formulas. The keys to the data are strings from pymatgen.core.composition.Composition.reduced_formula.

robocrys.util.connected_geometries

A list of geometries that are considered “connectable” polyhedra. E.g. Their face-sharing, edge-sharing, etc properties are of interest.

robocrys.util.geometry_to_polyhedra

A mapping from geometry type (e.g. octahedral) to the plural polyhedra name (e.g. octahedra).

robocrys.util.dimensionality_to_shape

A mapping from dimensionality to the component shape.

robocrys.util.defaultdict_to_dict(dictionary)

Recursively convert nested defaultdict to dict.

Parameters:

dictionary (defaultdict) – A defaultdict.

Return type:

dict

Returns:

The defaultdict as a dict.

robocrys.util.get_el(obj)

Utility method to get an element str from a symbol, Element, or Specie.

Parameters:

obj (Element | Species | str | int) – An arbitrary object. Supported objects are Element/Species objects, integers (representing atomic numbers), or strings (element symbols or species strings).

Return type:

str

Returns:

The element as a string.

robocrys.util.get_formatted_el(element, sym_label, use_oxi_state=True, use_sym_label=True, fmt='raw')

Formats an element string.

Performs a variety of functions, including:

• Changing “Sn+0” to “Sn”.

• Inserting the symmetry label between the element and oxidation state, if

  required.

• Removing the oxidation state if required.

• Latexifying the element and oxidation state.

• Unicodeifying the element and oxidation state.

• Converting the element and oxidation state to html.

Parameters:

• element (str) – The element string (possibly including the oxidation state. E.g. “Sn” or “Sn2+”.

• sym_label (str) – The symmetry label. E.g. “(1)”

• use_oxi_state (bool) – Whether to include the oxidation state, if present.

• use_sym_label (bool) – Whether to use the symmetry label.

• fmt (str) –

  How to format the element strings. Options are:

  • ”raw” (default): Don’t apply special formatting (e.g. “SnO2”).

  • ”unicode”: Format super/subscripts using unicode characters (e.g. SnO₂).

  • ”latex”: Use LaTeX markup for formatting (e.g. “SnO$_2$”).

  • ”html”: Use html markup for formatting (e.g. “SnO₂”).

Returns:

The formatted element string.

robocrys.util.htmlify_spacegroup(spacegroup_symbol)

Formats a spacegroup using unicode symbols.

E.g. P-42_1m -> P̅42₁m

Parameters:

spacegroup_symbol (str) – A spacegroup symbol.

Return type:

str

Returns:

The html formatted spacegroup symbol.

robocrys.util.load_condensed_structure_json(filename)

Load condensed structure data from a file.

Parameters:

filename (str) – The filename.

Return type:

dict[str, Any]

Returns:

The condensed structure data.

robocrys.util.superscript_number(string)

Converts a string containing numbers to superscript.

Will only convert the numbers 0-9, and the + and - characters.

Parameters:

string – A string containing the numbers 0-9 or +/- characters.

Returns:

The superscript string.

robocrys.util.unicodeify_spacegroup(spacegroup_symbol)

Formats a spacegroup using unicode symbols.

E.g. Fd-3m -> Fd̅3m

Parameters:

spacegroup_symbol (str) – A spacegroup symbol.

Return type:

str

Returns:

The unicode formatted spacegroup symbol.

Module contents

General imports.

isort:skip_file

class robocrys.StructureCondenser(use_conventional_cell=True, near_neighbors=None, mineral_matcher=None, use_symmetry_equivalent_sites=False, symprec=0.01, simplify_molecules=True, use_iupac_formula=True, use_common_formulas=True)

Bases: object

Class to transform a structure into an intermediate dict representation.

Parameters:

• use_conventional_cell (bool) – Whether to always use the convention cell representation of the structure.

• near_neighbors (Optional[NearNeighbors]) – A NearNeighbors instance used to calculate the bonding in the structure. For example, one of pymatgen.analysis.local_env.CrystalNN, pymatgen.analysis.local_env.VoronoiNN, etc. Defaults to None, in which case pymatgen.analysis.local_env.CrystalNN will be used.

• mineral_matcher (Optional[MineralMatcher]) – A MineralMatcher instance. Defaults to None in which case the default MineralMatcher settings will be used. If set to False, no mineral matching will occur.

• use_symmetry_equivalent_sites (bool) – Whether to use symmetry to determine if sites are inequivalent. If False, the site geometry and (next) nearest neighbor information will be used.

• symprec (float) – The tolerance used when determining the symmetry of the structure. The symmetry can used both to determine if multiple sites are symmetrically equivalent (if use_symmetry_equivalent_sites is True) and to obtain the symmetry labels for each site.

• use_iupac_formula (bool, optional) – 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.

• use_common_formulas (bool) – Whether to use the database of common formulas. The common formula will be used preferentially to the iupac or reduced formula.

condense_structure(structure)

Condenses the structure into an intermediate dict representation.

Parameters:

structure (Structure) – A pymatgen structure object.

Return type:

dict[str, Any]

Returns:

The condensed structure information. The data is formatted as a dict with a fixed set of keys. An up-to-date example of the, the condensed representation of MoS2 given in the documentation. See: robocrystallographer/docs_rst/source/format.rst or https://hackingmaterials.lbl.gov/robocrystallographer/format.html

class robocrys.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.