Getting started

Start the server, open the page it prints, and load a PDB entry.

Requirements

The ADCP distribution's Python environment (adcpsuite). It provides ADFR, MolKit2, ProDy, Open Babel and reduce, which do all of the chemistry. bin/adapt finds it by itself: $ADCPSUITE, $ADS_ROOT, the environment of an adcp or agfr on your PATH, then the usual conda / micromamba locations. Set ADCPSUITE=/path/to/env to choose one.
A current browser. In Chrome and Edge, Open PDB… remembers the folder you last opened a file from. Firefox and Safari work too, but their file dialog chooses its own starting folder.
For Fetch from RCSB, access to files.rcsb.org from the machine that runs the server.

Check the installation with:

bin/adapt check          # "ADapt is ready", or what is missing

Start ADapt

bin/adapt serve

The server prints a URL such as http://127.0.0.1:8766/?t=…. Open it; the token at the end is required, and the page refuses requests without it. The server listens on this machine only.

To use ADapt from another computer, forward the port from that computer and open the same URL there:

ssh -L 8766:127.0.0.1:8766 <host running ADapt>

Keep a fixed port. The browser keeps what it remembers for a page (the Open PDB folder, the light or dark theme) per host and port. The default port 8766, or any --port N, keeps that memory; --port 0 picks a new port on each run and the memory starts empty.

Load a structure

Fetch from RCSB: type an id (e.g. 1FV1) and press Enter. The file is downloaded once and kept in a cache under the output folder. Entries the RCSB distributes only as mmCIF (the largest assemblies) are reported rather than opened, because ADapt reads PDB-format files.
Open PDB… or drop a file on the page: .pdb, .ent, .pdb.gz or .ent.gz. Keep the PDB id as the file name (6ggd.pdb): ADFR looks up the known ligands of the entry by it.

ADapt opens on Biomol 1 when the file defines biological assemblies, otherwise on the ASU. ADFR's own test files are a good set of examples; bin/adapt examples prints where they are installed.

Where the files go

Each loaded file gets a session folder under the output folder (default ~/adapt_runs/, or --outdir, or $ADAPT_OUTDIR; /tmp is refused):

6ggd_20260929-143042_9acda1/
  6ggd.pdb              the input, as loaded
  save_001_rec/         every save in its own numbered folder: nothing is overwritten
    6ggd_rec.pdbqt
    6ggd_rec_H.pdb      the receptor with all of reduce's hydrogens, and its His/Asn/Gln choices
  save_002_lig/
    6ggd_lig.pdbqt
  session.json          ADFR version and source checksums, every edit in order, every file with its md5

See Writing the PDBQT files for what the files and the record contain.

Embedding ADapt

A program that starts ADapt, as ADCP_docking does, can open the page on a given entry or session, serve it under a path of its own, and fetch the files written.

Opening the page on an entry or a session

Next to the token, the page URL takes:

Parameter	Effect
`pdb=6GGD`	fetches the entry from the RCSB (or the cache) and opens it, as Fetch from RCSB does.
`session=<id>`	opens a session the server already holds, for instance one made by a program through `/api/upload`.
`tab=Biomol%202`	with either of the above, switches to that tab (`ASU`, `Biomol N`, …).

http://127.0.0.1:8766/?t=…&pdb=6GGD&tab=Biomol%202

Once a file is open, the address bar shows session= and tab=, so a reload, or the URL copied elsewhere, reopens the same session. Sessions live in the server's memory: after a restart, an old session id gets no such session; load the PDB file again (its folder and files are still on disk).

Requests

Every request carries the token, t=….

Request	Returns
`POST api/upload?name=6ggd.pdb`, the file as the body	a new session: its `session` id, tabs and tree.
`GET api/sessions`	the sessions the server holds, newest first: id, PDB id, tabs, current tab, folder, number of saves.
`GET api/session?s=<id>`	one session, as `api/upload` returns it, with the saves made so far and their files.
`POST api/save`, body `{"s": "<id>", "kind": "receptor"}` (or `"ligand"`)	writes the files of the current tab, as the save buttons do, and returns the save number and its files.
`GET api/download?s=<id>&save=<n>&file=<name>`	one file of a save, e.g. `file=6ggd_rec_H.pdb`. Without `file`, a save of one file returns it, and a save of several returns a zip.

Under a path prefix

The page and its script use relative paths only (api/…, static/…, docs/…). A page served at /adapt/?t=… therefore sends its requests to /adapt/api/… by itself, and a proxy can forward /adapt/… to ADapt without rewriting anything. Two cases:

A proxy that removes the prefix before forwarding needs nothing more; keep the slash in /adapt/?t=….
A proxy that forwards the full path: start ADapt with --base-path /adapt (or ADAPT_BASE_PATH=/adapt). ADapt then takes the prefix off each request, redirects /adapt?t=… to /adapt/?t=…, and prints its URL with the prefix. Requests without the prefix are still served.

← Overview The tree and the 3D view →