CcdCache — OpenFF Pablo 0.2.1.post35+g452b8cd documentation

class openff.pablo.ccd.CcdCache(library_paths: Iterable[Path | str], cache_path: Path | str | None = None, preload: list[str] = [], patches: Iterable[Mapping[str, Callable[[ResidueDefinition], list[ResidueDefinition]]]] = {}, extra_definitions: Mapping[str, Iterable[ResidueDefinition]] = {}, auto_download: bool = False)[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"]), this dictionary is checked first. If the residue is not present and the auto_download attribute is truthy, the CCD is then checked. If the residue cannot be retrieved from the inner dict or the CCD, a KeyError is raised.

Iterating over the mapping, checking its length, using the in operator, or otherwise treating the CcdCache as a mapping other than with the indexing syntax 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. If None, no on-disk cache is used, though the inner dictionary still functions as an in-memory cache.
preload¶ – A list of residue names to ensure are present when initializing the class. If absent from the library or cache directory, these are downloaded from the CCD even if auto_download is falsy. Note that a download failure will raise an error when the corresponding residue is first requested, not at instantiation.
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.
auto_download¶ – If True, automatically attempt to download unknown residues from the CCD. If False, raise KeyError when residues absent from the cache are requested.

Instance and Static Methods

`get_from_ccd`	Retrieve a residue definition from the CCD, adding it to the cache.
`with_`	Get a copy of this `CcdCache` with additional definitions added.
`with_crosslink`	Add a custom crosslink between residues.
`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.

get_from_ccd(res_name: str, patch: bool = True) → list[ResidueDefinition][source]

Retrieve a residue definition from the CCD, adding it to the cache.

Downloads the residue definition from the CCD, applies any patches, adds it to the cache, and returns the new, patched residue definitions. Does not return any definitions existing in the cache. Always downloads, even when the entry is already in the cache or auto_download is falsy.

Parameters:

res_name¶ – The 3-letter code for the residue.
patch¶ – If True, apply patches before adding to the cache and returning. If False, do not apply patches.

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