Skip to content

molforge.cache

cache

Result caching for molforge engines.

Engines (folding, docking, generative) take minutes-to-hours per call. Recomputing identical inputs is wasteful, and molforge's :class:Provenance makes it trivial to detect when a recomputation is identical: hash the engine + parameters + inputs + parent chain, look up the result.

Integration on the engine side is a few lines per method::

provenance = self._build_provenance(...)
cache = get_default_cache()
cached = cache.get(provenance, "protein")
if cached is not None:
    return cached
result = self._actually_compute(...)
cache.put(provenance, result, "protein")
return result
What gets cached
  • :class:molforge.core.Protein from folding wrappers.
  • list[DesignedSequence] from generative wrappers.
  • :class:molforge.docking.DockingResult from docking wrappers (Vina, Gnina, DiffDock). Extra result types register via :func:register_serializer.

What deliberately doesn't get cached: - :class:molforge.md.Trajectory. Multi-GB per simulation; users who want this should use the upstream MD framework's checkpointing.

Cache location
  • Default: ~/.cache/molforge/ (XDG convention).
  • Overridable via MOLFORGE_CACHE_DIR.
  • Disable globally with MOLFORGE_CACHE=disabled.
Cache layout

One subdirectory per entry, named by SHA-256 of the canonical key. Each entry holds:

  • type: text file with the type tag
  • meta.json: Protein name + metadata (with arrays + Provenance replaced by markers)
  • structure.cif (for Protein only): the AtomArray as mmCIF
  • payload.json (for DesignedSequence list): the design list
  • receptor.cif + pose_{i}.cif (for DockingResult): the receptor and each pose ligand as mmCIF, with scalar pose fields and metadata in payload.json
  • arrays.npz: numpy arrays from metadata when present
Safety
  • Corrupted entries are treated as misses and logged; never crash.
  • Molforge major.minor version is part of the key — version upgrades invalidate transparently.
  • Timestamps are excluded from the key — different runs of the same computation share a slot.
  • Writes go to a .tmp directory and rename atomically.

Cache 

Cache(
    directory: Path | str | None = None,
    *,
    enabled: bool | None = None,
)

File-system-backed cache for engine results.

Parameters:

Name Type Description Default
directory Path | str | None

Cache directory. None uses :func:default_cache_dir.

 None
enabled bool | None

Master switch. None defers to $MOLFORGE_CACHE env var.

 None

get 

get(provenance: Provenance, type_tag: str) -> Any | None

Look up a cached result. Returns None on miss or any error.

put 

put(
    provenance: Provenance, result: Any, type_tag: str
) -> None

Store a result. Errors are logged, never propagate.

contains 

contains(provenance: Provenance) -> bool

True if a cache entry exists for this Provenance.

path_for 

path_for(provenance: Provenance) -> Path

On-disk path for an entry. May not exist (cache miss).

clear 

clear() -> int

Delete every entry. Only removes hex-named directories (defensive — never touches anything else in the cache dir).

cache_key 

cache_key(provenance: Provenance) -> str

Return the canonical 64-char hex cache key for a Provenance.

Mixes the molforge major.minor version into the hash so version upgrades invalidate transparently. Timestamps are excluded so two runs of the same computation share a slot.

default_cache_dir 

default_cache_dir() -> Path

Resolve the default cache directory.

Order: $MOLFORGE_CACHE_DIR → $XDG_CACHE_HOME/molforge → ~/.cache/molforge.

register_serializer 

register_serializer(
    type_tag: str,
    serializer: Serializer,
    deserializer: Deserializer,
) -> None

Register a serializer/deserializer for a result type.

The type_tag is stored alongside the entry and dispatched on lookup, so changing it invalidates previously-cached entries of the same shape. Pick a stable string.

Re-registering overwrites; tests rely on that for cleanup.

get_default_cache 

get_default_cache() -> Cache

Return a process-wide :class:Cache rooted at :func:default_cache_dir.

Singleton — engines call this each time they want to consult the cache. MOLFORGE_CACHE=disabled is honoured at first-call time.