molforge.versions

versions

One place to ask what is installed here.

:class:~molforge.core.provenance.Provenance answers "what produced this output", but it can only record a version the wrapper managed to read at the time. Wrappers that shell out to a native binary — fpocket, P2Rank, GROMACS, sander, gnina — record no version at all, so a manifest covering them has blanks exactly where a reader most wants a number. And there is no way to ask the question before a run, which is what you need when one output is going to be attributed to thousands of predictions.

This module is that question, answered once::

>>> from molforge import engine_versions
>>> backends = engine_versions()                        # doctest: +SKIP
>>> backends["OpenMM"].version                          # doctest: +SKIP
'8.1.1'
>>> [b.name for b in backends.values() if b.available]  # doctest: +SKIP
['OpenMM', 'RDKit', 'NumPy', 'molforge']

Three kinds of backend, because they fail to have a version for three different reasons and a manifest should not conflate them:

python A pip/conda distribution. Read from :mod:importlib.metadata — free, exact, no subprocess.

executable A native binary found on $PATH. Presence comes from :func:shutil.which; the version, where the tool exposes one, comes from running it with a known flag. Some of these tools ship no version flag at all (fpocket, tleap), so they report available=True with an empty version and a :attr:~BackendVersion.detail saying why. That is a different fact from "not installed", and it is recorded as one.

repo Run from a checkout the caller points at (RoseTTAFold, DiffDock, ProteinMPNN, RFdiffusion take a repo_dir). There is nothing global to inspect, so molforge cannot detect these at all and says so rather than reporting a confident False.

Nothing here raises. A backend that cannot be inspected reports available=False and an empty version — the registry's whole job is to be safe to call on any machine, including one with none of this installed.

See also

:func:molforge.wrappers._versions.engine_version, the per-wrapper lookup this builds on, and :func:molforge.wrappers._versions.check_engine_version, which warns when a wrapper's parser is outside its tested range.

BackendVersion dataclass

BackendVersion(
    name: str,
    category: str,
    kind: str,
    requirement: str,
    available: bool,
    version: str = "",
    location: str = "",
    detail: str = "",
)

What molforge can determine about one engine or backend.

Attributes:

Name	Type	Description
name	str	molforge's name for the backend, matching the engine field a wrapper writes into :class:Provenance ("Boltz", "fpocket", "GROMACS").
category	str	Which part of molforge drives it — "folding", "docking", "pockets", "md", "freeenergy", "generative", or "runtime" for the shared numeric and chemistry libraries whose version changes results everywhere.
kind	str	"python", "executable", or "repo". See the module docstring — these are three different reasons a version can be missing.
requirement	str	What was looked for: the distribution name that resolved, or the executable name searched for on $PATH.
available	bool	Whether molforge can find this backend right now. Always False for repo backends, which molforge cannot detect without the repo_dir the caller supplies.
version	str	The detected version, or "". Empty is never an error — read :attr:detail for which of the several reasons applies.
location	str	Resolved path for an executable backend; "" otherwise.
detail	str	Plain-language reason :attr:version is empty, or "" when a version was found.

to_dict

to_dict() -> dict[str, Any]

Convert to a JSON-serialisable plain dict.

Keys with nothing to say (location, detail) are omitted so an embedded manifest block stays readable.

engine_versions

engine_versions(
    *,
    category: str | None = None,
    probe_executables: bool = True,
    timeout: float = DEFAULT_PROBE_TIMEOUT,
    refresh: bool = False,
) -> dict[str, BackendVersion]

Report every engine and backend molforge knows how to drive.

Parameters:

Name	Type	Description	Default
category	str | None	Return only this category ("folding", "docking", "pockets", "md", "freeenergy", "generative", "runtime"). None returns all of them.	None
probe_executables	bool	Run each installed native binary's version flag. False skips every subprocess: executables are still reported as available or not via $PATH, but with an empty version. Use it when you want the sweep to cost nothing, or in a sandbox where spawning processes is unwelcome.	True
timeout	float	Seconds to wait for one probe. A tool that exceeds it is reported as available with no version, never as an error.	DEFAULT_PROBE_TIMEOUT
refresh	bool	Re-probe instead of reusing the memoized sweep. The result is cached because the answer only changes when something is installed, and a caller emitting one manifest per output would otherwise re-run every binary on the machine.	False

Returns:

Type	Description
dict[str, BackendVersion]	class:BackendVersion per backend, keyed by
dict[str, BackendVersion]	attr:BackendVersion.name and ordered by category. Every known
dict[str, BackendVersion]	backend appears, installed or not — an absent engine is a fact
dict[str, BackendVersion]	about the environment worth recording.

Raises:

Type	Description
ValueError	If category isn't one molforge uses. A typo would otherwise silently return nothing, which reads as "nothing is installed".

Example

from molforge import engine_versions md = engine_versions(category="md", probe_executables=False) sorted(md) ['AMBER', 'GROMACS', 'OpenMM', 'tleap']