amd.io module

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

class amd.io.CifReader(path, reader='ase', remove_hydrogens=False, disorder='skip', heaviest_component=False, show_warnings=True)

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 periodicset.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 for parsing. Default is ase, to use csd-python-api change to ccdc. 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 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 sites with disorder or all_sites include all sites regardless.

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

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

Yields

periodicset.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 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_one()

# List of AMDs (k=100) of crystals in a .CIF
amds = [amd.AMD(periodic_set, 100) for periodic_set in amd.CifReader('mycif.cif')]
class amd.io.CSDReader(refcodes=None, families=False, remove_hydrogens=False, disorder='skip', heaviest_component=False, show_warnings=True)

Bases: amd.io._Reader

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

Parameters

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

  • families (bool, optional) – Read all entries whose refcode starts with the given strings, or ‘families’ (e.g. giving ‘DEBXIT’ reads all entries starting with DEBXIT).

  • 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 sites with disorder or all_sites include all sites regardless.

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

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

Yields

periodicset.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)
refcode_families = ['ACSALA', 'HXACAN']
structures = list(amd.CSDReader(refcode_families, families=True))

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

# Giving the reader nothing reads from the whole CSD.
reader = amd.CSDReader()

# looping over this generic reader will yield all CSD entries
for periodic_set in reader:
    ...

# or, read structures by refcode on demand
debxit01 = reader.entry('DEBXIT01')
entry(refcode: str, **kwargs) → amd.periodicset.PeriodicSet

Read a crystal given a CSD refcode, returning a periodicset.PeriodicSet. If given kwargs, overrides the kwargs given to the Reader.

family(refcode_family: str, **kwargs)
amd.io.entry_to_periodicset(entry, remove_hydrogens=False, disorder='skip', heaviest_component=False) → amd.periodicset.PeriodicSet

ccdc.entry.Entry –> amd.periodicset.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 sites with disorder or all_sites include all sites regardless.

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

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

periodicset.PeriodicSet

Raises

_ParseError : – Raised if the structure can/should not be parsed for the following reasons: 1. entry.has_3d_structure is False, 2. disorder == ‘skip’ and any of: (a) any disorder flag is True, (b) any atom has fractional occupancy, (c) any atom’s label ends with ‘?’, 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. motif is empty after removing H, disordered sites or solvents.

amd.io.cifblock_to_periodicset(block, remove_hydrogens=False, disorder='skip') → amd.periodicset.PeriodicSet

ase.io.cif.CIFBlock –> amd.periodicset.PeriodicSet. CIFBlock is the type returned by ase.io.cif.parse_cif.

Parameters

  • block (ase.io.cif.CIFBlock) – 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 sites with disorder or all_sites include all sites regardless.

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

periodicset.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 H or disordered sites, 2. a site has missing coordinates, 3. disorder == ‘skip’ and any of: (a) any atom has fractional occupancy, (b) any atom’s label ends with ‘?’.