Structure

The main entry point for coarse-graining with chic is the Structure class:

class chic.Structure

The Structure class is a subclass of pymatgen Structure. It is used to store the structure of a material and to perform operations on it pertinent to structural coarse-graining.

register_methods()

Register methods from the main coarse-graining methods directory.

property neighbour_list: Dict[int, list]

Return the computed neighbour list.

property atomic_clusters: Dict[str, AtomicCluster]

Return the determined atomic clusters.

remove_sites_by_symbol(symbol: str) → None

get_neighbours_by_cutoff(rcut: float = 1.8, by_element_pair: Dict[Tuple[str, str], float | Tuple[float, float]] | None = None) → None

Compute the neighbourlist with potentially different radial cut-offs for different element pairs. The cutoffs for specific pairs can be defined in by_element_pair dictionary with tuples of element symbols as keys and values as either a single max cutoff or a tuple of (min_cutoff, max_cutoff).

Parameters:

• rcut – a single global cut-off to use for all pairs of atoms. If per-atom-pair cut-offs are set to larger than this value, it will be overwritten.

• by_element_pair – specific atom pair distances. Can either be a float indicating a cut-off for that pair, or a tuple of floats, which act as a distance window (rmin, rmax).

classmethod from_structure(structure: Structure, atomic_clusters=None, **kwargs) → Structure

Create a new Structure object from an existing pymatgen Structure.

Parameters:

• structure – An existing pymatgen Structure object.

• atomic_clusters – Dictionary of precomputed atomic clusters. Each key corresponds to a site type and each value is an AtomicCluster object.

Returns:

A new Structure object.

classmethod from_ase_atoms(atoms: Atoms) → Structure

Create a new Structure object from an ASE Atoms object.

Parameters:

atoms – An ASE Atoms object.

Returns:

A new Structure object.

classmethod from_cif(filename: str, **kwargs) → Structure

Read structures from CIF.

Parameters:

filename – Path to CIF file.

Returns:

Structure object.

classmethod from_lammps_data(filename: str, **kwargs) → Structure

Read structures from LAMMPS data file.

Parameters:

filename – Path to LAMMPS data file.

Returns:

Structure object.

append_lammps_trajectory(filename: str, intramolecular_cutoff: float = 2.0, start: int = 0, end: int | None = None, step: int = 1, verbose: bool = False, gather_columns=None)

Append a LAMMPS trajectory file to the current structure object. For each cluster, the atomic clusters are updated to reflect the snapshot’s structure. Only snapshots in the given range are returned.

Parameters:

• filename – Path to the LAMMPS trajectory file.

• intramolecular_cutoff – Cutoff for determining atomic clusters.

• start – Starting snapshot index.

• end – Ending snapshot index. If None, process full trajectory.

• step – Step size between snapshots.

• verbose – Whether to instantiate the new chic class with timing.

Returns:

Generator of Structure objects.

find_metal_clusters(elements: List[str] | None = None) → None

Find metal clusters in structure. This assumes that the standard single-node approach has been used to find atomic clusters, such that isolated metal atoms and isolated oxygen atoms are left after the organic linkers have been found.

Parameters:

elements – List of elements to consider as metal. If None, elements from A-type sites plus oxygen are used.

Returns:

List of metal clusters.

get_beads(bead_type_to_element_mapping: Dict[str, str] = {'X': 'Ce', 'a': 'Si', 'b': 'O'}, skip_non_framework: bool = True, energy_key: str = 'c_pe_per_atom') → List[Bead]

Gather beads and assign species according to the mapping.

Parameters:

• bead_type_to_element_mapping – Mapping of bead types to elements.

• skip_non_framework – Whether to skip non-framework atoms.

Returns:

List of Bead objects.

overlay_cg_atomistic_representations(filename: str | None = None, bead_type_to_element_mapping: Dict[str, str] = {'X': 'Be', 'a': 'Si', 'b': 'Ce'}, crystal_toolkit: bool = False, skip_non_framework: bool = True) → None

Overlays the atomistic representation ontop of the coarse-grained representation of the struture. This is useful for visualising the atomistic structure in the context of the coarse-grained structure (and that the coarse-graining was correct).

Parameters:

• filename – path to CIF to write.

• bead_type_to_element_mapping – mapping of bead types to elements.

• crystal_toolkit – whether to display the structure in crystal toolkit.

• skip_non_framework – whether to skip non-framework atoms.

to_ase() → Atoms

Convert structure to ASE Atoms object.

to_net(bead_type_to_element_mapping: Dict[str, str] = {'X': 'Ce', 'a': 'Si', 'b': 'O'}, name: str = 'Net', supercell: Tuple[int, int, int] | None = None) → Net

Convert the coarse-grained net to a chic.Net object.

In order to instantiate the Net class, we need to provide the lattice, species, fractional coordinates, and the bonding information. The bonding information needs to be a list of tuples, where each tuple is of the format:

((atom1, atom2), (image1, image2))

where atom1 and atom2 are the labels of the atoms that are bonded, and image1 and image2 are the periodic images of the atoms that are bonded. The periodic images are given as a tuple of integers, where each integer represents the number of unit cells in each direction.

Parameters:

• bead_type_to_element_mapping – mapping of bead types to elements.

• name – name of the net.

• supercell – whether to make a supercell of the net. If specified, should be a tuple of three integers, where each integer represents the number of unit cells in each direction.

Returns:

Net object.

net_to_cif(filename: str, write_bonds: bool = True, bead_type_to_element_mapping: Dict[str, str] = {'X': 'Ce', 'a': 'Si', 'b': 'O'}, name: str = 'net', skip_non_framework: bool = True) → None

Write the coarse-grained structure to a (Topo)CIF file.

Parameters:

• filename – path to CIF to write.

• write_bonds – whether to write bonds to the CIF.

• bead_type_to_element_mapping – mapping of bead types to elements.

• name – name of the network.

• skip_non_framework – whether to skip non-framework atoms.

net_to_lammps_data(filename: str, write_bonds: bool = True, write_angles: bool = False, two_way_bonds: bool = False, atom_style: str = 'full', bead_type_to_element_mapping: Dict[str, str] = {'a': 'Si', 'b': 'O'}, name: str = 'net') → None

Write the coarse-grained structure to a LAMMPS data file.

Parameters:

• filename – Path to LAMMPS data file to write.

• write_bonds – Whether to write bonds to the LAMMPS data file.

• two_way_bonds – Whether to write bonds in both directions.

• atom_style – Atom style to use. Either ‘full’ or ‘atomic’.

• bead_type_to_element_mapping – Mapping of bead types to elements.

• name – Name of the network.

net_to_lammps_dump(filename: str, bead_type_to_element_mapping: Dict[str, str] = {'a': 'Si', 'b': 'O'}, **kwargs) → None

Write the coarse-grained structure to a LAMMPS dump file.

Parameters:

• filename – Path to LAMMPS dump file to write.

• bead_type_to_element_mapping – Mapping of bead types to elements.

• **kwargs – Keyword arguments to pass to the writer.

net_to_struct(bead_type_to_element_mapping: Dict[str, str] = {'a': 'Si', 'b': 'O'}) → Structure

Convert the coarse-grained structure to a pymatgen Structure object.

Parameters:

bead_type_to_element_mapping – mapping of bead types to elements.

Returns:

PymatgenStructure object.

net_to_ase_atoms() → Atoms

Convert the coarse-grained structure to an ASE atoms object.

Returns:

ASE atoms object.

net_to(filename: str, fmt: str = '', **kwargs) → None

Use Pymatgen’s writer to write the coarse-grained structure to file.

Parameters:

• filename – Path to file to write.

• fmt – Format to write to. If not specified, will be inferred from the file extension.

• kwargs – Keyword arguments to pass to the writer.

net_to_ase_to(filename: str, fmt: str | None = None, **kwargs) → None

Use ASE’s writer to write the coarse-grained structure to file.

Parameters:

• filename – Path to file to write.

• fmt – Format to write to. If not specified, will be inferred from the file extension.

• kwargs – Keyword arguments to pass to the writer.

net_to_extxyz(filename: str, bead_type_to_element_mapping: Dict[str, str] = {'a': 'Si', 'b': 'O'}, info_dict: dict | None = None, append: bool = False) → None

Write coarse-grained structure to extxyz file. This will attempt to add any bead energies and forces, if provided, to the file.

net_to_gulp_framework_nodes(filename: str, keywords: list | None = None, commands: list | None = None, **kwargs) → None

Reduce the coarse-grained AB2 net to the bare framework consisting of the A nodes only. Then write to a GULP input file.

Parameters:

• filename – Path to GULP input file to write.

• **kwargs – Keyword arguments to pass to the writer.

pickle_neighbourlist(filename: str)

Write the current computed neighbour list to a pickle-d file.

Parameters:

filename – name of file to write.

tidy()

” Force clearance of the pickled data.