Metadata-Version: 2.5
Name: caddforge-qm
Version: 0.3.0
Summary: Quantum mechanics workflows for the CADDForge toolbox.
Author-email: Manuel Sellner <manuel.sellner@idorsia.com>, Christoph Sager <christoph.sager@idorsia.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: caddforge-core>=0.21.0
Requires-Dist: caddforge-opencosmors==0.0.1
Requires-Dist: geometric==1.1
Requires-Dist: numpy>=1.26.0
Requires-Dist: plotly==6.5.0
Requires-Dist: pyocl-idor>=0.8.3
Requires-Dist: pyscf==2.9.0
Requires-Dist: rdkit>=2024.03.1
Description-Content-Type: text/markdown

# 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<sub>tr</sub>(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)
```yaml
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
```bash
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.
