CADDForge Toolbox

caddforge is a metadata-only distribution that installs the complete public CADDForge toolbox. It contains no Python modules or commands: caddforge-core owns the caddforge Python package and command line interface.

The first public-repository bundle source tag was v0.23.0, followed by published bundle 0.23.1, continuing the version sequence after the inherited 0.22.1 development baseline. The 0.x series remains initial development: the public API and supported component set may change. Version 1.0.0 is reserved for a future stable API commitment. Bundle and component versions evolve independently. The bundle includes the installed documentation viewer. These public sources start fresh Git histories; earlier development tags are not included.

Installation

This source prepares 0.24.0. Bundle 0.23.1 was the latest verified PyPI release on 2026-10-19; the new core, MD and docs publications are being prepared separately. This command selects the latest available published bundle, which need not yet be 0.24.0:

python -m pip install caddforge
python -m pip check
caddforge list-tools
caddforge docs

This includes the core, data science, descriptors, docking, FEP, GUI, MD, ML, QM, and docs distributions. GUI integrations, MD's minimize and gamd extras, and ML's ui extra are enabled by default. The docs package ships the built site and enables caddforge docs without documentation build tools or internet access. Test and documentation authoring extras are not installed. The private caddforge-idorsia plugin is excluded and remains a separate private installation.

For a smaller installation, install caddforge-core or an individual plugin:

python -m pip install caddforge-core
python -m pip install caddforge-qm

For documentation in a selective installation, add caddforge-docs separately. Run caddforge docs to open the installed site; use --host, --port, or --no-browser to configure the viewer.

All public plugin dependencies and user-facing extras are installed automatically. Existing external scientific runtimes, licensed programs, GPU drivers, and Slurm infrastructure remain separate prerequisites; this package does not install a complete OpenFE/OpenFF/AmberTools environment. Install recommended conda-managed runtimes before pip packages. Initial full-bundle validation targets Linux on Python 3.10 and 3.12; other environments are not yet advertised as fully supported.

Migration from the old core distribution

Previously, caddforge installed only the core. Use a fresh environment whenever possible. To migrate an existing environment, first remove that old distribution:

python -m pip uninstall caddforge
python -m pip install --upgrade caddforge
python -m pip check
caddforge list-tools

For a minimal installation, replace the install command with python -m pip install --upgrade caddforge-core and upgrade each retained plugin to its migrated release. Old plugin releases depend on the former caddforge core; keep them in their original environments. Do not install renamed core alongside the old core distribution: both own the same Python files. If that already happened, uninstall the old distribution and reinstall caddforge-core with --force-reinstall. Upgrade the private plugin separately if it is installed.

Python imports, commands, configuration files, job registries, results, and plugin entry-point groups retain their existing names. Query the runtime version with importlib.metadata.version("caddforge-core"); version("caddforge") now reports the optional bundle version. MD provenance records both separately and historical records remain readable. Uninstalling the new metadata-only bundle leaves core and plugins installed; pip does not recursively remove dependencies.

Release set and local validation

The single source of truth for the component set is project.dependencies in pyproject.toml. Bundle 0.24.0 pins these source release versions:

Core v0.23.0, MD v0.14.0 and docs v0.3.1 identify the new component sources. Bundle v0.24.0 is an annotated local source tag; it has not been pushed or published by this work. Component publication is separate from source tagging and must finish before public-index installation of this bundle succeeds. The other seven component pins and their extras retain the published versions checked on 2026-10-19. The documentation version matrix records source tags and verified publication independently.

Changes in 0.24.0

• Core 0.23.0 adds shared task graphs, durable execution attempts, resilient publication and combined job monitoring.
• MD 0.14.0 adds GaMD with a shared NPT pilot, independent replicas, fixed-bias reweighting diagnostics, complete production exports and XTC as the default. The new gamd extra enforces its supported OpenMM range alongside gui and minimize; AmberTools and CUDA drivers remain external prerequisites.
• Docs 0.3.1 describes the new protocol, APIs, configuration and scientific qualifications. It remains a runtime viewer dependency without authoring extras.

Packaging checks validate the metadata-only bundle and the required GaMD extra. Local validation on 2026-10-19 passed 32 packaging/release-metadata tests, the wheel ownership/public-metadata check, wheel/sdist version checks, and pip check with locally built tagged components. Public-index migration could not fetch core 0.23.0 in that environment. The reused scientific development environment also contained a separately installed private plugin, so the public-install smoke check correctly rejected it. These are not successful clean-public-install or public-index migration results. The public-index ownership-migration test and complete clean-install checks must pass against the actual published components before bundle publication. Local wheel or inherited-environment smoke checks do not establish public-index installability. Release CI retains these gates on Python 3.10 and 3.12.

Earlier 0.23.1 packaging and full-install results apply only to its old component set. This release retains its runner disk-space cleanup, explicit --no-cache-dir flags and failure-time disk diagnostics.

For sibling source checkouts, use a separate build environment:

python -m pip install --upgrade build hatchling hatch-vcs packaging pytest twine 'tomli; python_version < "3.11"'
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
python -m twine check /tmp/caddforge-candidates/*
python scripts/run_ci_tests.py

build_workspace.py overrides VCS versions only in its build subprocesses to produce local candidates at the declared pins. It does not create release tags or publish packages. Do not publish those local builds: release component artifacts must be built from their corresponding new public tags, reviewed, and tested. The public component tags now exist; use their published wheels when testing public-index installation. The migration test builds a small synthetic legacy distribution and the candidate bundle locally, then downloads the exact core wheel pinned in pyproject.toml from public PyPI. It checks pip file ownership, bundle uninstallation, CLI availability, and historical result loading without requiring another repository, Git history, or version overrides. The test runner installs that published core and its runtime dependencies before running the tests; the migration check fails rather than skipping if its wheel cannot be downloaded.

After installing the bundle into a clean environment, run:

python -m pip --isolated install --index-url https://pypi.org/simple --find-links /tmp/caddforge-candidates 'caddforge==0.24.0'
python -m pip check
python scripts/check_install.py

For the bundle-only candidate, build with python -m build and install its wheel without --find-links so all components resolve from public PyPI. Do not use --no-deps to claim a complete installation passed.

Public release gates

The pinned QM and docking releases use the published maintained dependencies caddforge-opencosmors==0.0.1 and caddforge-unidock-tools==1.1.3, respectively, replacing the previous Git URL requirements. The bundle pins the public component releases containing these changes. Scientific dependency availability and compatibility must pass a clean installation without private indexes. PyOCL is now available publicly as pyocl-idor; the pinned QM, descriptors, and docking releases require pyocl-idor>=0.8.3, while Python imports remain pyocl. Its runtime requires Java 21 or newer; the affected GitHub workflows provision Java 21. Install Java 21 or newer before running tool discovery or scientific workflows; Python packages do not install the JVM. Package metadata declares MIT and each package includes the project license text. Review bundled third-party files under their own terms before release.

python scripts/check_wheels.py /tmp/caddforge-candidates --complete --public

This command checks the candidate wheels for public metadata and index-installable dependencies. The complete installation smoke test also rejects private packages and references to them in the installed dependency metadata.

GitHub Actions builds one wheel/source archive pair, tests its packaging on Python 3.10 and 3.12, and runs the ownership migration against the pinned core wheel from public PyPI. No cross-repository checkout or additional GitHub credentials are required. Publish the pinned core version before running this job. Manually dispatch release.yml with full_install: true for clean Linux resolution, tool discovery, configuration templates, GUI assets, and installed documentation checks. Pushed v* release tags always require that full installation job.

A pushed v* tag publishes the tested artifacts through PyPI Trusted Publishing. Branch pushes, pull requests, and manual runs never publish. Before pushing release tags, verify distribution ownership, choose a bundle version above existing caddforge releases, complete the release checks, and configure the Trusted Publisher for the repository, release.yml workflow, and pypi GitHub environment. No PYPI_PUBLISH_ENABLED variable is required. Release core first, then independent plugins and GUI, then docking/descriptors before MD, and data-science before docs. Publish the bundle after all pinned components. The bundle version is explicit in pyproject.toml; update it and its pins before creating the matching annotated tag. No credentials are embedded.

Packaging references

• Distribution names and Python import names
• Hatch metadata-only wheel support
• PyPI dependency restrictions
• PyPI Trusted Publishing