amd.io module

Tools for reading crystals from files, or from the CSD with csd-python-api. The readers return amd.PeriodicSet objects representing the crystal which can be passed to amd.AMD() and amd.PDD().

class amd.io.CifReader(path: Union[str, os.PathLike], reader: str = 'gemmi', remove_hydrogens: bool = False, disorder: str = 'skip', heaviest_component: bool = False, molecular_centres: bool = False, show_warnings: bool = True, verbose: bool = False)

Bases: amd.io._Reader

Read all structures in a .cif file or all files in a folder with ase or csd-python-api (if installed), yielding amd.PeriodicSet s.

Parameters

  • path (str) – Path to a .CIF file or directory. (Other files are accepted when using reader='ccdc', if csd-python-api is installed.)

  • reader (str, optional) – The backend package used to parse the CIF. The default is gemmi, pymatgen and ase are also accepted, as well as ccdc if csd-python-api is installed. The ccdc reader should be able to read any format accepted by ccdc.io.EntryReader, though only CIFs have been tested.

  • remove_hydrogens (bool, optional) – Remove Hydrogens from the crystals.

  • disorder (str, optional) – Controls how disordered structures are handled. Default is skip which skips any crystal with disorder, since disorder conflicts with the periodic set model. To read disordered structures anyway, choose either ordered_sites to remove atoms with disorder or all_sites include all atoms regardless of disorder.

  • heaviest_component (bool, optional) – csd-python-api only. Removes all but the heaviest molecule in the asymmeric unit, intended for removing solvents.

  • molecular_centres (bool, default False) – csd-python-api only. Extract the centres of molecules in the unit cell and store in the attribute molecular_centres.

  • show_warnings (bool, optional) – Controls whether warnings that arise during reading are printed.

  • verbose (bool, default False) – If True, prints a progress bar showing the number of items processed.

Yields

amd.PeriodicSet – Represents the crystal as a periodic set, consisting of a finite set of points (motif) and lattice (unit cell). Contains other data, e.g. the crystal’s name and information about the asymmetric unit.

Examples

# Put all crystals in a .CIF in a list
structures = list(amd.CifReader('mycif.cif'))

# Can also accept path to a directory, reading all files inside
structures = list(amd.CifReader('path/to/folder'))

# Reads just one if the .CIF has just one crystal
periodic_set = amd.CifReader('mycif.cif').read()

# List of AMDs (k=100) of crystals in a .CIF
amds = [amd.AMD(item, 100) for item in amd.CifReader('mycif.cif')]
class amd.io.CSDReader(refcodes: Optional[Union[str, List[str]]] = None, refcode_families: bool = False, remove_hydrogens: bool = False, disorder: str = 'skip', heaviest_component: bool = False, molecular_centres: bool = False, show_warnings: bool = True, verbose: bool = False)

Bases: amd.io._Reader

Read structures from the CSD with csd-python-api, yielding amd.PeriodicSet s.

Parameters

  • refcodes (str or List[str], optional) – Single or list of CSD refcodes to read. If None or ‘CSD’, iterates over the whole CSD.

  • refcode_families (bool, optional) – Interpret refcodes as one or more refcode families, reading all entries whose refcode starts with the given strings.

  • remove_hydrogens (bool, optional) – Remove hydrogens from the crystals.

  • disorder (str, optional) – Controls how disordered structures are handled. Default is skip which skips any crystal with disorder, since disorder conflicts with the periodic set model. To read disordered structures anyway, choose either ordered_sites to remove atoms with disorder or all_sites include all atoms regardless of disorder.

  • heaviest_component (bool, optional) – Removes all but the heaviest molecule in the asymmeric unit, intended for removing solvents.

  • molecular_centres (bool, default False) – Extract the centres of molecules in the unit cell and store in attribute molecular_centres.

  • show_warnings (bool, optional) – Controls whether warnings that arise during reading are printed.

  • verbose (bool, default False) – If True, prints a progress bar showing the number of items processed.

Yields

amd.PeriodicSet – Represents the crystal as a periodic set, consisting of a finite set of points (motif) and lattice (unit cell). Contains other useful data, e.g. the crystal’s name and information about the asymmetric unit for calculation.

Examples

# Put these entries in a list
refcodes = ['DEBXIT01', 'DEBXIT05', 'HXACAN01']
structures = list(amd.CSDReader(refcodes))

# Read refcode families (any whose refcode starts with strings in the list)
families = ['ACSALA', 'HXACAN']
structures = list(amd.CSDReader(families, refcode_families=True))

# Get AMDs (k=100) for crystals in these families
refcodes = ['ACSALA', 'HXACAN']
amds = []
for periodic_set in amd.CSDReader(refcodes, refcode_families=True):
    amds.append(amd.AMD(periodic_set, 100))

# Giving the reader nothing reads from the whole CSD.
for periodic_set in amd.CSDReader():
    ...
exception amd.io.ParseError

Bases: ValueError

Raised when an item cannot be parsed into a periodic set.

amd.io.periodicset_from_gemmi_block(block, remove_hydrogens: bool = False, disorder: str = 'skip') → amd.periodicset.PeriodicSet

Convert a gemmi.cif.Block object to a amd.PeriodicSet. gemmi.cif.Block is the type returned by gemmi.cif.read_file().

Parameters

  • block (gemmi.cif.Block) – An ase CIFBlock object representing a crystal.

  • remove_hydrogens (bool, optional) – Remove Hydrogens from the crystal.

  • disorder (str, optional) – Controls how disordered structures are handled. Default is skip which skips any crystal with disorder, since disorder conflicts with the periodic set model. To read disordered structures anyway, choose either ordered_sites to remove atoms with disorder or all_sites include all atoms regardless of disorder.

Returns

Represents the crystal as a periodic set, consisting of a finite set of points (motif) and lattice (unit cell). Contains other useful data, e.g. the crystal’s name and information about the asymmetric unit for calculation.

Return type

amd.PeriodicSet

Raises

ParseError – Raised if the structure fails to be parsed for any of the following: 1. Required data is missing (e.g. cell parameters), 2. :code:disorder == 'skip' and disorder is found on any atom, 3. The motif is empty after removing H or disordered sites.

amd.io.periodicset_from_ase_cifblock(block, remove_hydrogens: bool = False, disorder: str = 'skip') → amd.periodicset.PeriodicSet

Convert a ase.io.cif.CIFBlock object to a amd.PeriodicSet. ase.io.cif.CIFBlock is the type returned by ase.io.cif.parse_cif().

Parameters

  • block (ase.io.cif.CIFBlock) – An ase ase.io.cif.CIFBlock object representing a crystal.

  • remove_hydrogens (bool, optional) – Remove Hydrogens from the crystal.

  • disorder (str, optional) – Controls how disordered structures are handled. Default is skip which skips any crystal with disorder, since disorder conflicts with the periodic set model. To read disordered structures anyway, choose either ordered_sites to remove atoms with disorder or all_sites include all atoms regardless of disorder.

Returns

Represents the crystal as a periodic set, consisting of a finite set of points (motif) and lattice (unit cell). Contains other useful data, e.g. the crystal’s name and information about the asymmetric unit for calculation.

Return type

amd.PeriodicSet

Raises

ParseError – Raised if the structure fails to be parsed for any of the following: 1. Required data is missing (e.g. cell parameters), 2. The motif is empty after removing H or disordered sites, 3. :code:disorder == 'skip' and disorder is found on any atom.

amd.io.periodicset_from_pymatgen_cifblock(block, remove_hydrogens: bool = False, disorder: str = 'skip') → amd.periodicset.PeriodicSet

Convert a pymatgen.io.cif.CifBlock object to a amd.PeriodicSet. pymatgen.io.cif.CifBlock is the type returned by pymatgen.io.cif.CifFile.

Parameters

  • block (pymatgen.io.cif.CifBlock) – A pymatgen CifBlock object representing a crystal.

  • remove_hydrogens (bool, optional) – Remove Hydrogens from the crystal.

  • disorder (str, optional) – Controls how disordered structures are handled. Default is skip which skips any crystal with disorder, since disorder conflicts with the periodic set model. To read disordered structures anyway, choose either ordered_sites to remove atoms with disorder or all_sites include all atoms regardless of disorder.

Returns

Represents the crystal as a periodic set, consisting of a finite set of points (motif) and lattice (unit cell). Contains other useful data, e.g. the crystal’s name and information about the asymmetric unit for calculation.

Return type

amd.PeriodicSet

Raises

ParseError – Raised if the structure can/should not be parsed for the following reasons: 1. No sites found or motif is empty after removing Hydrogens & disorder, 2. A site has missing coordinates, 3. :code:disorder == 'skip' and disorder is found on any atom.

amd.io.periodicset_from_ase_atoms(atoms, remove_hydrogens: bool = False) → amd.periodicset.PeriodicSet

Convert an ase.atoms.Atoms object to a amd.PeriodicSet. Does not have the option to remove disorder.

Parameters

  • atoms (ase.atoms.Atoms) – An ase ase.atoms.Atoms object representing a crystal.

  • remove_hydrogens (bool, optional) – Remove Hydrogens from the crystal.

Returns

Represents the crystal as a periodic set, consisting of a finite set of points (motif) and lattice (unit cell). Contains other useful data, e.g. the crystal’s name and information about the asymmetric unit for calculation.

Return type

amd.PeriodicSet

Raises

ParseError – Raised if there are no valid sites in atoms.

amd.io.periodicset_from_pymatgen_structure(structure, remove_hydrogens: bool = False, disorder: str = 'skip') → amd.periodicset.PeriodicSet

Convert a pymatgen.core.structure.Structure object to a amd.PeriodicSet. Does not set the name of the periodic set, as pymatgen Structure objects seem to have no name attribute.

Parameters

  • structure (pymatgen.core.structure.Structure) – A pymatgen Structure object representing a crystal.

  • remove_hydrogens (bool, optional) – Remove Hydrogens from the crystal.

  • disorder (str, optional) – Controls how disordered structures are handled. Default is skip which skips any crystal with disorder, since disorder conflicts with the periodic set model. To read disordered structures anyway, choose either ordered_sites to remove atoms with disorder or all_sites include all atoms regardless of disorder.

Returns

Represents the crystal as a periodic set, consisting of a finite set of points (motif) and lattice (unit cell). Contains other useful data, e.g. the crystal’s name and information about the asymmetric unit for calculation.

Return type

amd.PeriodicSet

Raises

ParseError – Raised if the disorder == 'skip' and not structure.is_ordered

amd.io.periodicset_from_ccdc_entry(entry, remove_hydrogens: bool = False, disorder: str = 'skip', heaviest_component: bool = False, molecular_centres: bool = False) → amd.periodicset.PeriodicSet

Convert a ccdc.entry.Entry object to a amd.PeriodicSet. Entry is the type returned by ccdc.io.EntryReader.

Parameters

  • entry (ccdc.entry.Entry) – A ccdc Entry object representing a database entry.

  • remove_hydrogens (bool, optional) – Remove Hydrogens from the crystal.

  • disorder (str, optional) – Controls how disordered structures are handled. Default is skip which skips any crystal with disorder, since disorder conflicts with the periodic set model. To read disordered structures anyway, choose either ordered_sites to remove atoms with disorder or all_sites include all atoms regardless of disorder.

  • heaviest_component (bool, optional) – Removes all but the heaviest molecule in the asymmeric unit, intended for removing solvents.

  • molecular_centres (bool, default False) – Use molecular centres of mass as the motif instead of centres of atoms.

Returns

Represents the crystal as a periodic set, consisting of a finite set of points (motif) and lattice (unit cell). Contains other useful data, e.g. the crystal’s name and information about the asymmetric unit for calculation.

Return type

amd.PeriodicSet

Raises

ParseError – Raised if the structure fails parsing for any of the following: 1. entry.has_3d_structure is False, 2. :code:disorder == 'skip' and disorder is found on any atom, 3. entry.crystal.molecule.all_atoms_have_sites is False, 4. a.fractional_coordinates is None for any a in entry.crystal.disordered_molecule, 5. The motif is empty after removing Hydrogens and disordered sites.

amd.io.periodicset_from_ccdc_crystal(crystal, remove_hydrogens: bool = False, disorder: str = 'skip', heaviest_component: bool = False, molecular_centres: bool = False) → amd.periodicset.PeriodicSet

Convert a ccdc.crystal.Crystal object to a amd.PeriodicSet. Crystal is the type returned by ccdc.io.CrystalReader.

Parameters

  • crystal (ccdc.crystal.Crystal) – A ccdc Crystal object representing a crystal structure.

  • remove_hydrogens (bool, optional) – Remove Hydrogens from the crystal.

  • disorder (str, optional) – Controls how disordered structures are handled. Default is skip which skips any crystal with disorder, since disorder conflicts with the periodic set model. To read disordered structures anyway, choose either ordered_sites to remove atoms with disorder or all_sites include all atoms regardless of disorder.

  • heaviest_component (bool, optional) – Removes all but the heaviest molecule in the asymmeric unit, intended for removing solvents.

  • molecular_centres (bool, default False) – Use molecular centres of mass as the motif instead of centres of atoms.

Returns

Represents the crystal as a periodic set, consisting of a finite set of points (motif) and lattice (unit cell). Contains other useful data, e.g. the crystal’s name and information about the asymmetric unit for calculation.

Return type

amd.PeriodicSet

Raises

ParseError – Raised if the structure fails parsing for any of the following: 1. :code:disorder == 'skip' and disorder is found on any atom, 2. crystal.molecule.all_atoms_have_sites is False, 3. a.fractional_coordinates is None for any a in crystal.disordered_molecule, 4. The motif is empty after removing H, disordered sites or solvents.