CADDForge QM Tool

Install this plugin with python -m pip install caddforge-qm. It depends directly on caddforge-core>=0.21.0; Python imports and CLI commands still use caddforge. For the complete public toolbox, including user-facing extras, install python -m pip install caddforge. When migrating an existing environment, uninstall the former caddforge core distribution before installing renamed core and updated plugins.

Quantum-mechanical workflows for CADDForge. This repo currently exposes a transfer free energy workflow backed by COSMO-RS (PySCF or xTB) and the openCOSMO-RS bindings.

Repo Layout

• src/cadd_qm/cosmors/: COSMO-RS engine, config, and workflow wiring.
• src/cadd_qm/tool.py: plugin registration for the qm/transfer-free-energy tool.
• tests/: lightweight tests and config validation.

Transfer free energy workflow

The qm/transfer-free-energy tool computes ΔG_tr(H₂O → organic) for a ligand in a target solvent. COSMO surfaces are generated with PySCF (default) or xTB and evaluated with opencosmorspy.

Example config (YAML or JSON)

ligand_sdf: ligand.sdf
solvent_sdf: octanol.sdf
n_confs: 3
basis: def2-TZVP
xc: BP86
par_model: default_turbomole
do_geomopt: true
temperature_K: 298.15
standard_state: x         # x (mole fraction) or c (molarity, requires solvent_density_g_ml)
cosmo_backend: dft        # or xtb
xtb_path: xtb

Running via CLI

caddforge run qm transfer-free-energy --config qm_cosmors.yaml
caddforge show-config qm transfer-free-energy   # prints an example dict

The workflow writes a standard run directory (runs/<date>/<job-id>/) with:

• config.json and metadata.json
• stdout.log
• results/results.json plus copied .cosmo surfaces under results/cosmo_surfaces/

COSMO backends

• dft (default): PySCF BP86/def2-TZVP with COSMO surface generation.
• xtb: GFN2-xTB with ddCOSMO(TM, ε=∞) and Turbomole-style COSMO files. The compute backend (backend in the shared BaseConfig: local/slurm) remains independent of cosmo_backend.

Dependencies

• PySCF (for DFT surface generation)
• xTB (optional backend, configured via xtb_path)
• RDKit, pyocl-idor>=0.8.3 (Python imports remain pyocl), numpy, and opencosmorspy
• Java 21 or newer, with JAVA_HOME configured for the PyOCL/OpenChemLib runtime

These are declared in pyproject.toml; install them with the package using pip.

Notes

• Geometry optimizations now use delocalized internal coordinates (dlc) in PySCF/geomopt to avoid KeyError: 'internal' with current geometric versions.

Compressed inputs

Transfer-free-energy ligand and solvent structures may be supplied as .sdf.gz. CADDForge expands them in job-local runtime scratch before the QM workflow starts and preserves the original paths in saved configuration.

Continuous integration and releases

.github/workflows/release.yml builds a wheel and source archive, validates metadata, and tests the installed wheel on Linux with Python 3.10 and 3.12. The lightweight test selection is recorded in scripts/ci_tests.json; external scientific engines are validated separately.

Pushing a matching v* release tag publishes the tested artifacts to PyPI. Branch pushes, pull requests and manual runs never publish. Configure a PyPI Trusted Publisher for the idorsia repository, release.yml workflow and pypi environment before pushing release tags. Runtime CADDForge dependencies must already be available publicly; publish core first, and publish docking/descriptors before MD.