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 release is 0.23.0, 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

Once the reviewed public releases are published, install the public toolbox with:

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 extra, 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.23.1 pins these tagged public releases:

All ten component versions are published on public PyPI, checked on 2026-10-15. Source tag v0.23.1 identifies this bundle release; package-index publication remains pending. Release publication requires metadata, ownership-migration, and complete-installation checks. The documentation's version matrix records source tags and package-index publication separately.

Patch 0.23.1 keeps the 0.23.0 component pins and addresses runner disk exhaustion during the Python 3.10 full-install job, which prevented publication of 0.23.0. Full-install CI removes unused Android and .NET SDKs, disables pip caching with explicit --no-cache-dir flags, and reports disk usage even when installation fails. Dependencies and release validation gates remain unchanged.

Local 0.23.1 validation on 2026-10-15 passed all 32 installed-wheel packaging, release-metadata, and ownership-migration tests on Python 3.10 and 3.12. The unchanged component set previously passed clean public-PyPI installation checks as bundle 0.23.0 on both Python versions: pip check and discovery of all 26 tools and three GUI extensions. Configuration templates, GUI assets, the installed documentation viewer, and local workflow execution and result persistence passed. These checks do not run external scientific engines or download model weights. The runner storage fix must still pass the required full-install jobs on GitHub.

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.23.1'
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