# qfit

qFit 3 — automated multiconformer model building for X-ray
crystallography and cryo-EM (`qfit_protein`, `qfit_ligand`,
`qfit_covalent_ligand`, ...). Repo is named `qfit-3.0`; module
follows the name/version rule as `qfit/<version>`.

- Upstream: https://github.com/ExcitedStates/qfit-3.0
- License: MIT

## Versions

- **2025.3** (Dec 2025) — current. Post-2024-paper qFit-ligand
  (RDKit `-sm SMILES` route, `-em` flag). Python 3.12, solvers
  cvxpy + pyscipopt (SCIP) declared in `install_requires` — no
  CPLEX size cap. One extra: `cctbx-base` (structure I/O imports
  iotbx/scitbx/cctbx/mmtbx but upstream lists it only in conda's
  `environment.yml`; the PyPI manylinux_2_28 wheel works on Ra
  RHEL8 — no conda involved, anaconda repo is unreachable from Ra).
- **3.2.2** (Aug 2022) — legacy, pre-paper qfit_ligand algorithm.
  Python 3.10 (`numpy<1.22`), cvxopt + CPLEX Community Edition
  pip-installed as extras. Last upstream tag with the `v` prefix —
  its `urls:` is overridden per-version in `config.yaml`.

## How it is built

uv route (careless-style) from the sha-pinned GitHub tag tarball into
`$PREFIX/venv`. The small C extension (`_extensions.c`) builds with
the gcc/12.3.0 module (plain C, no gcc runtime dep). Both eras need
`SETUPTOOLS_SCM_PRETEND_VERSION` (`use_scm_version=True` but the
tarball has no `.git`). 3.x-only quirks (solver extras, `setuptools<81`
for the runtime `pkg_resources` import) are branched on `V_PKG` in
`build`; upstream fixed both by 2024.3.

**CPLEX caveat (3.x only)**: the pip `cplex` wheel is the IBM Community
Edition, limited to 1000 variables/constraints. 2024.3+ uses SCIP and
has no such cap.

`uv` must be on the build host (default `~/.local/bin/uv`, override
with `UV=/path/to/uv`).

## Building on Ra

```sh
module use unstable && module load modbuild/2.1.3
cd qfit
modbuild build \
    --tmpdir=/das/work/p21/p21515/.cache/Pmodules \
    --distdir=/das/work/p21/p21515/.cache/Pmodules \
    2025.3
module use MX unstable && module load qfit/2025.3
```

## Verifying the install

```sh
which qfit_protein                     # -> .../qfit/2025.3/venv/bin/qfit_protein
qfit_protein --help                    # argparse usage, no traceback
qfit_ligand --help                     # should list -sm/--smiles (2024.3+)
"$QFIT_ENV/bin/python" -c "import qfit, iotbx, pyscipopt, cvxpy; print(qfit.__version__)"
```

The post-refinement scripts (`qfit_final_refine_xray.sh`) call phenix:
`module load phenix` before using them.

## Adding a new version

Add version + tarball sha256 in `files/config.yaml` (`sha256sum` the
downloaded `<ver>.tar.gz` — tags have no `v` prefix since 2024), check
whether upstream relaxed the numpy pin further (may allow a newer venv
Python), then build as above.