Metadata-Version: 2.5
Name: caddforge
Version: 0.25.0
Summary: The complete public CADDForge toolbox: core, scientific plugins, GUI, and documentation.
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.24.0
Requires-Dist: caddforge-datascience==0.5.0
Requires-Dist: caddforge-descriptors[gui]==0.12.0
Requires-Dist: caddforge-docking[gui]==0.8.0
Requires-Dist: caddforge-docs==0.4.0
Requires-Dist: caddforge-fep[gui]==0.8.0
Requires-Dist: caddforge-gui==0.7.0
Requires-Dist: caddforge-md[gamd,gui,minimize]==0.15.0
Requires-Dist: caddforge-ml[ui]==0.4.0
Requires-Dist: caddforge-qm==0.3.0
Description-Content-Type: text/markdown

# CADDForge Toolbox

`caddforge==0.25.0` installs the complete public CADDForge toolbox. This is a
metadata-only distribution: `caddforge-core` owns the `caddforge` Python package
and CLI. Component versions evolve independently, and the `0.x` series permits
API changes before a future stable 1.0 release.

## Installation

Provision recommended conda-managed scientific runtimes first, then install:

```bash
python -m pip install caddforge==0.25.0
python -m pip check
caddforge list-tools
caddforge docs
```

The bundle enables descriptors, docking, FEP and MD GUI integrations, MD
minimization and GaMD, ML UI dependencies and the built offline documentation
viewer. It excludes authoring/test extras and the separately installed private
plugin. External scientific engines, OpenFE/OpenFF/AmberTools environments,
Java 21+, model weights, GPU drivers and Slurm remain separate prerequisites.
Release CI targets Linux on Python 3.10 and 3.12.

For a smaller installation, install `caddforge-core` or an individual plugin.
Add `caddforge-docs` separately to enable `caddforge docs`. The docs viewer needs
no checkout, documentation build tools or internet connection. It supports
`--host`, `--port` and `--no-browser`.

## Component set

The exact contract is `project.dependencies` in `pyproject.toml`.

| Component | Version | Enabled extras |
| --- | --- | --- |
| Core | `0.24.0` | None |
| GUI | `0.7.0` | None |
| Descriptors | `0.12.0` | `gui` |
| Docking | `0.8.0` | `gui` |
| MD | `0.15.0` | `gui`, `minimize`, `gamd` |
| FEP | `0.8.0` | `gui` |
| Docs | `0.4.0` | None |
| Data science | `0.5.0` | None |
| ML | `0.4.0` | `ui` |
| QM | `0.3.0` | None |

### Changes in 0.25.0

- Core 0.24.0 supplies shared workbench contracts, measured reporting, durable
  recovery, preparation pipelines, verified publication and artifact retirement.
- GUI 0.7.0 provides complete schema-driven setup, shared Local/Slurm compute,
  retained drafts and job actions, exact molecular scenes, native settings,
  trajectory/time-series/matrix diagnostics and paired alignment views.
- Descriptors 0.12.0 adds PheSA workbench inputs, SMILES files, candidate progress
  and exact candidate/reference pairs. Docking 0.8.0 adds shared pose manifests
  and optional rigid-PDB receptor preparation.
- MD 0.15.0 adds GaMD setup, analysis, calibration and checkpoint recovery,
  reusable trajectory analysis, verified preparation records and corrected
  continuous-coordinate OpenBPMD scoring with native CV agreement checks.
- FEP 0.8.0 adds ABFE/RBFE workbench execution, reviewed protocol settings,
  recorded diagnostics and capability-qualified OpenFE progress observation.
- Docs 0.4.0 covers the same component set. Data science, ML and QM retain their
  versions. Maintained scientific dependencies remain `caddforge-opencosmors==0.0.1`,
  `caddforge-unidock-tools==1.1.3` and `pyocl-idor>=0.8.3` (import `pyocl`).

Update controller and worker environments together and rebuild Slurm environment
packs. Existing processes retain their original code. Corrected OpenBPMD runs
require new outputs; old trajectories cannot establish native bias correctness.
Scientific qualification and GPU checks are separate from packaging validation.

## Migration from the old core distribution

Prefer a fresh environment. The former `caddforge` distribution owned core files;
remove it before installing the metadata-only bundle and renamed core:

```bash
python -m pip uninstall caddforge
python -m pip install caddforge==0.25.0
python -m pip check
caddforge list-tools
```

For a minimal installation, install `caddforge-core` and upgrade each retained
plugin. Old plugins depended on the legacy bundle name; keep them in their original
environments. If old and renamed core distributions already overlap, uninstall the
old distribution and force-reinstall `caddforge-core` afterwards. Upgrade private
plugins separately.

Imports, commands, registries, historical results and entry-point groups retain
names. `importlib.metadata.version("caddforge-core")` reports the runtime;
`version("caddforge")` reports the optional bundle. Uninstalling the new bundle
leaves its dependencies installed.

## Build and validation

Use a separate build environment for sibling checkouts:

```bash
python -m pip install build hatchling hatch-vcs packaging pytest twine
python -m pip install -r ../caddforge-docs/requirements.txt
python scripts/build_workspace.py --outdir /tmp/caddforge-candidates
python scripts/check_wheels.py /tmp/caddforge-candidates --complete --public
python -m twine check /tmp/caddforge-candidates/*
```

Local candidates use the bundle pins. Explicitly versioned sources build that
version without a tag; unchanged VCS-versioned components use a temporary build
override. These candidates are validation artifacts. Publication builds run on
matching annotated release tags and validate wheel/source metadata.

The metadata checker verifies exact pins, user-facing extras, public dependencies,
core file/CLI ownership, GUI assets and packaged docs. It rejects private packages
and direct URL dependencies. For clean public-index validation, install the bundle
wheel without `--find-links`, then run:

```bash
python -m pip check
python scripts/check_install.py
```

A complete installation must resolve all dependencies; `--no-deps` is insufficient.
GitHub Actions tests installed wheels on Python 3.10/3.12, runs ownership migration
against the exact pinned public core wheel, and requires complete public-index
installation on branch pushes and before publishing. The full-install job frees unused runner SDKs,
disables pip caches and reports disk/inode usage. Migration and full-install gates
remain mandatory. A manual `release.yml` run with `full_install: true` also runs
the complete installation job.

## Release workflow

Prepare all versions, dependency floors, documentation and pins before pushing.
Release core 0.24.0 → GUI 0.7.0 → descriptors 0.12.0 → docking 0.8.0 → MD 0.15.0
→ FEP 0.8.0 → docs 0.4.0 → bundle 0.25.0. For each repository, push `main` with
`--no-follow-tags`, wait for branch CI on the reviewed commit, create its matching
annotated tag on that commit, and push only that tag. Wait for publication before
moving to the next repository. Tag creation requires no source edits. Preserve
historical tags; avoid pushing all local tags.

Only pushed matching `v*` tags publish through PyPI Trusted Publishing after
required checks. Branch/PR/manual runs never publish. Configure the PyPI project,
GitHub owner `idorsia`, repository, workflow `release.yml` and environment `pypi`
before tag publication. The bundle's PyPI project is `caddforge` and its repository
is `caddforge-bundle`. These account settings are external to repository workflows.
See the documentation [version matrix](https://github.com/idorsia/caddforge-docs/blob/main/docs/plugins/version-matrix.md)
for the component contract and release sequence.
