CcdCache — OpenFF Pablo 0.0.0.dev0+versionmissing documentation

class openff.pablo.ccd.CcdCache(library_paths: Iterable[Path | str], cache_path: Path | str = Path(xdg_base_dir.save_cache_path('openff-pablo'), 'ccd_cache'), preload: list[str] = [], patches: Iterable[Mapping[str, Callable[[ResidueDefinition], list[ResidueDefinition]]]] = {}, extra_definitions: Mapping[str, Iterable[ResidueDefinition]] = {})[source]

Bases: Mapping[str, tuple[ResidueDefinition, …]]

Caches, patches, and presents the CCD as a Python Mapping.

This class is a wrapper around a dict that stores residue definitions. When a residue is requested via the indexing syntax (for example, my_ccd_cache["ALA"]) or the in operator, this dictionary is checked first. If the residue is not present, the CCD is then checked. If the residue cannot be retrieved from the inner dict or the CCD, a KeyError is raised or False is returned as appropriate.

Iterating over the mapping, checking its length, or otherwise treating the CcdCache as a mapping other than with the indexing syntax or in operator works only on the inner dict. As a result, accessing a residue via indexing may return a value even if these other methods suggest it won’t.

CcdCache can apply patches to the entries it downloads from the CCD. This is used to work around known errors, deficiencies and inconsistencies in the CCD definitions. Patches are specified as functions that take a single residue definition and return a list of them.

The extra_definitions and the with_() and with_replaced methods allow custom definitions to be added to a CcdCache. These custom definitions are not patched. Since they are stored alongside cached entries in the inner dictionary, custom definitions supercede any that have not already been downloaded from the CCD.

When a CCD entry is downloaded, the corresponding CIF file is stored in the cache_path. This means that each entry will be downloaded only once, even across multiple Python invocations. All entries in the cache are loaded (and patches applied) when a new CcdCache is created. CcdCache assumes that the files in the cache path were downloaded from the CCD and may do unexpected things if they are edited by hand.

Users may provide additional CCD entries by specifying library paths. By default, this is used to ship commonly used residues with Pablo. At the moment, patches are applied to files in library paths, but it is likely that in the future they won’t be and residues shipped with Pablo will be shipped pre-patched to speed up load times. Like with the cache, files from library paths are loaded when a CcdCache is created.

Accessing the CCD requires internet access. Without internet access, entries from the cache or library paths can still be loaded, as can any entries added to an instance of this class.

Parameters:

library_paths¶ – Paths to search for user-provided or packaged CCD entries. All paths are searched.
cache_path¶ – The path to which to download CCD entries. This path is searched in addition to library_paths.
preload¶ – A list of residue names to download when initializing the class.
patches¶ – Functions to call on ResidueDefinitions downloaded from the CCD before they are returned or added to the inner dict. An iterable of maps from residue names each to a single callable. Each map is applied to residues with the given name in the order they are iterated over. Any patches corresponding to key "*" will be applied to all residues before the more specific patches in its map.
extra_definitions¶ – Additional residue definitions to add to the cache. Note that patches are not applied to these definitions.

Instance and Static Methods

`with_`	Get a copy of this `CcdCache` with additional definitions added.
`with_patch`	Add a patch to the residues loaded via a copy of this `CcdCache`.
`with_replaced`	Get a copy of this `CcdCache` with some definitions replaced.
`with_varied_protonation`	Get a copy of `self` with all combinations of some protonation states.
`with_virtual_sites`	Copy `self`, adding new residue definitions requiring some virtual sites.
`with_vsite_water`	Copy `self`, adding new definitions for common multisite water models.
`without`	Get a copy of this `CcdCache` lacking any definitions with some names.

with_(definitions: Mapping[str, Sequence[ResidueDefinition]] | Sequence[ResidueDefinition]) → Self[source]

Get a copy of this CcdCache with additional definitions added.

Definitions may be supplied as a mapping from residue names to sequences of residue definitions, or as a sequence of residue definitions. In the latter case, the residue names are taken from the residue definitions themselves.

Note that patches are not applied to the new definitions.

Examples

Add a custom definition to the STD_CCD_CACHE. We use a 4-letter residue code as they are supported by Pablo’s PDB reader and do not clash with the CCD’s definitions.

>>> from openff.pablo import STD_CCD_CACHE, ResidueDefinition
>>> my_ccd_cache = STD_CCD_CACHE.with_([
...     ResidueDefinition.from_smiles(
...         "[H:1][O:2][O:3][H:4]",
...         {1: "H1", 2: "O1", 3: "O2", 4: "H2"},
...         "HOOH",
...     )
... ])

Add protonation variants of a residue by specifying acidic and basic atoms.

>>> from openff.pablo import STD_CCD_CACHE, ResidueDefinition
>>>
>>> # Get the GABA (γ-amino butanoic acid) residue definition from CCD
>>> gaba_resdef = STD_CCD_CACHE["ABU"][0]
>>>
>>> # Generate the variants and add them to a new cache
>>> my_ccd_cache = STD_CCD_CACHE.with_({
...     "ABU": gaba_resdef.vary_protonation(
...         acidic=["HXT"], # Atom name of abstractable proton
...         basic=[("N", "H3")], # Atom to protonate, name of new proton
...     )[1:], # Skip the first entry, which is already in the cache
... })
>>> # Should have added three variants - positive, negative, zwitterion
>>> len(my_ccd_cache["ABU"]) - len(STD_CCD_CACHE["ABU"])
3