Metadata-Version: 2.5
Name: caddforge
Version: 0.23.1
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.22.0
Requires-Dist: caddforge-datascience==0.5.0
Requires-Dist: caddforge-descriptors==0.11.0
Requires-Dist: caddforge-docking[gui]==0.7.0
Requires-Dist: caddforge-docs==0.3.0
Requires-Dist: caddforge-fep[gui]==0.7.0
Requires-Dist: caddforge-gui==0.6.0
Requires-Dist: caddforge-md[gui,minimize]==0.13.0
Requires-Dist: caddforge-ml[ui]==0.4.0
Requires-Dist: caddforge-qm==0.3.0
Description-Content-Type: text/markdown

# 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:

```bash
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:

```bash
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:

```bash
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:

| Component | Version | Enabled extras |
| --- | --- | --- |
| Core | `0.22.0` | None |
| Data science | `0.5.0` | None |
| Descriptors | `0.11.0` | None |
| Docs | `0.3.0` | None |
| Docking | `0.7.0` | `gui` |
| FEP | `0.7.0` | `gui` |
| GUI | `0.6.0` | None |
| MD | `0.13.0` | `gui`, `minimize` |
| ML | `0.4.0` | `ui` |
| QM | `0.3.0` | None |

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:

```bash
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:

```bash
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.

```bash
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](https://packaging.python.org/en/latest/discussions/distribution-package-vs-import-package/)
- [Hatch metadata-only wheel support](https://hatch.pypa.io/latest/plugins/builder/wheel/)
- [PyPI dependency restrictions](https://setuptools.pypa.io/en/stable/userguide/dependency_management.html)
- [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/using-a-publisher/)
