`scan3d` (3D restrained grid scan)¶

scan3d relaxes every point of a grid over three coordinates with harmonic restraints, records the energy without the restraints, and draws the energy volume as isosurfaces in an HTML page.

What it is for¶

Reactions that involve three coordinates at once: see the energy landscape when, for example, a bond forms, another breaks, and a proton moves in the same step.
Redrawing a finished grid: plot an existing surface.csv again over another energy range (--csv).

The default backend is UMA (Meta); -b/--backend also selects ORB, MACE, AIMNet2, or DFT (dft). For a single path driven by one or more coordinates, use scan; for two coordinates, use scan2d.

Examples¶

The examples use input.pdb, the cluster model cut from the bundled enzyme structure with extract, and take its charge from -l 'SAM:1,GPP:-3'.

pdb2reaction extract -i examples/1.R.pdb -c 'SAM,GPP,MG' -l 'SAM:1,GPP:-3' -o input.pdb

Its PDB has an empty chain column, so an atom is written as residue name, residue number, and atom name, in any order, separated by commas or spaces.

1. From a YAML spec¶

Write the three ranges under pairs: and add --out-json to also get result.json. With the default step of 0.2 Å, this file gives a 9 × 9 × 7 grid (567 points).

# scan3d.yaml
pairs:
  - ["SAM,320,CS1", "GPP,321,C7", 1.50, 3.00]
  - ["GPP,321,H11", "GLU,186,OE2", 0.90, 2.50]
  - ["SAM,320,SD", "SAM,320,CS1", 1.80, 3.00]

pdb2reaction scan3d -i input.pdb -l 'SAM:1,GPP:-3' -s scan3d.yaml --out-json -o ./result_scan3d/

Open result_scan3d/scan3d_density.html in a browser for the isosurfaces; result.json gives scientific_status and the number of usable points (n_points_usable).

2. Inline literal¶

The same three ranges can be written on the command line as one literal.

pdb2reaction scan3d -i input.pdb -l 'SAM:1,GPP:-3' \
    -s '[("SAM,320,CS1","GPP,321,C7",1.50,3.00),("GPP,321,H11","GLU,186,OE2",0.90,2.50),("SAM,320,SD","SAM,320,CS1",1.80,3.00)]'

3. Pre-optimize and dump¶

Optimize the input before the scan and keep the inner-loop trajectories.

pdb2reaction scan3d -i input.pdb -l 'SAM:1,GPP:-3' \
    -s '[("SAM,320,CS1","GPP,321,C7",1.50,3.00),("GPP,321,H11","GLU,186,OE2",0.90,2.50),("SAM,320,SD","SAM,320,CS1",1.80,3.00)]' \
    --dump -o ./result_scan3d/ --preopt

4. Re-plot an existing surface.csv¶

Redraw the isosurfaces of a finished grid over −10 to 40 kcal/mol; no energy is computed. A separate -o keeps the files of the original scan.

pdb2reaction scan3d --csv ./result_scan3d/surface.csv --zmin -10 --zmax 40 -o ./result_scan3d_replot/

How it works¶

Starting structure and grid: The charge comes from -q or -l. With --preopt, the input is first optimized without restraints; if that does not converge, the input geometry is used. Each axis gets ceil(|high − low| / h) + 1 evenly spaced values, both ends included, where h is --max-step-size (Å) for a distance and --max-angle-step-size or --max-dihedral-step-size (degrees) for an angle or dihedral. The values are visited from the one closest to the starting structure.
Three nested loops: For each d₁ value, the structure is relaxed with only the d₁ restraint; for each d₂ value, with the d₁ and d₂ restraints; the inner loop then scans d₃ with all three restraints. Each relaxation starts from the nearest structure that has already converged in the same loop; until one has, it starts from the structure the enclosing loop produced (the starting structure for d₁).
Relaxation at each point: A harmonic restraint E = ½ k (q − q_target)² holds each coordinate q at its target (k is --restraint-k), and L-BFGS (--opt-mode grad, default) or RFO (--opt-mode hess) relaxes the rest. The energy is then computed without the restraints, and the structure is written under grid/.
Table and figure: After the last point, all points go into surface.csv. The usable points are interpolated with radial basis functions (RBF) on a 50 × 50 × 50 grid, and eight semi-transparent isosurfaces with banded colors are drawn in scan3d_density.html. With --csv, only this step runs, on the given table.

Reading surface.csv¶

surface.csv has one row per grid point and one reference row.

Column	Meaning
`i`, `j`, `k`	Grid indices. Index 0 is the value closest to the starting structure, so the indices follow the visiting order, not ascending values
`d1_A`, `d2_A`, `d3_A` (also `q1`, `q2`, `q3`)	Coordinate values measured after the relaxation. The `_A` names are kept for every axis, so an angle axis holds degrees; `q1_unit`, `q2_unit`, and `q3_unit` give the unit (`angstrom` or `degree`)
`target_d1_A`, `target_d2_A`, `target_d3_A` (also `target_q1`, `target_q2`, `target_q3`)	Restraint targets of the point
`energy_hartree`	Energy without the restraints (Hartree)
`bias_converged`	Whether the restrained relaxation converged
`is_preopt`	`true` only for the reference row
`energy_kcal`	Energy relative to the baseline (kcal/mol)
`d1_label`, `d2_label`, `d3_label`	Axis labels used in the figure

Usable points: a point is usable when its relaxation converged, its energy is finite, and its structure was written. Only usable points set the baseline and enter the figure.
Verdict: in result.json (--out-json), scientific_status is success when every grid point is usable, partial when only some are (exit status 0), and failed when none is (exit status 1). n_points_attempted and n_points_usable give the counts. For points that do not converge, see max_cycles and plateau stops.
Next step: the isosurfaces are interpolated, so pass a computed point near the saddle, grid/point_*.pdb, to tsopt (for .xyz, add --ref-pdb). Points in the reactant and product basins can be inputs for path-search.

Output files¶

After a run, --out-dir contains the following files.

result_scan3d/
├─ surface.csv                          # grid table with the reference row
├─ scan3d_density.html                  # 3D isosurfaces (open in a browser)
├─ grid/
│  ├─ point_i150_j090_k180.xyz          # relaxed structure of each grid point
│  ├─ preopt_iDDD_jDDD_kDDD.xyz         # starting structure (the reference row)
│  └─ inner_path_d1_000_d2_000_trj.xyz  # inner-loop trajectory for each (d₁, d₂) pair (--dump)
└─ result.json                          # summary (--out-json); summary.json holds the same content

Start with scan3d_density.html and surface.csv; the structure of each point is under grid/. In result.json, grid_points[] maps each grid index to its values, targets, energy, convergence, and structure file.

File names: the number after i, j, or k (the tag DDD) is the target × 100 (Å, or degrees for an angle), padded to at least three digits, not the grid index of surface.csv: d1 = 1.50 Å, d2 = 0.90 Å, d3 = 1.80 Å gives point_i150_j090_k180.xyz, and an angle of 120° gives 12000. When two points round to the same tag, the later file name gets _grid_III_JJJ_KKK with the point’s i, j, and k from surface.csv; the numbers in inner_path_d1_000_d2_000 are the i and j of the pair.
Other formats: with PDB or mmCIF input, each structure is also written as .pdb, and with Gaussian input as .gjf. mmCIF input also gets .cif with the original identifiers.
With --csv: only scan3d_density.html is written, plus result.json (without grid_points) with --out-json.

Main options¶

Option	Type	Default	Description
`-i, --input`	path	`None`	Input structure (`.pdb`, `.cif`, `.mmcif`, `.xyz`, …). Required unless `--csv` is given
`-q, --charge`	integer	`None`	Total charge. Required unless `-l`, YAML `calc.charge`, or a `.gjf` input gives it
`-m, --multiplicity`	integer	`1`	Spin multiplicity (2S+1)
`-l, --ligand-charge`	text	`None`	Total ligand charge (e.g. `-1`) or per-residue charges (e.g. `'GPP:-3,SAM:1'`), used when `-q` is omitted (PDB/mmCIF input or `--ref-pdb`)
`-s, --scan-lists`	text	`None`	Three ranges as a YAML/JSON spec file or one inline literal: distance `(i,j,low,high)`, angle `(i,j,k,low,high)`, or dihedral `(i,j,k,l,low,high)`. Required unless `--csv` is given
`-o, --out-dir`	path	`./result_scan3d/`	Output directory
`--max-step-size`	float	`0.2`	Largest grid spacing of a distance axis (Å)
`--max-angle-step-size`	float	`5.0`	Largest grid spacing of an angle axis (degrees)
`--max-dihedral-step-size`	float	`10.0`	Largest grid spacing of a dihedral axis (degrees)
`--restraint-k`	float	`300.0`	Restraint strength k (eV/Å² for distances, eV/rad² for angles); alias `--bias-k`. When omitted, YAML `bias.k` applies
`--opt-mode`	`grad` / `hess`	`grad`	Relaxation of each point: L-BFGS / RFO
`--preopt/--no-preopt`	flag	`False`	Optimize the input without restraints before the scan
`--dump/--no-dump`	flag	`False`	Write the inner-loop (d₃) trajectory for each (d₁, d₂) pair under `grid/`
`--baseline`	`min` / `first`	`min`	Zero of `energy_kcal`: lowest usable point, or point `(0, 0, 0)`
`--zmin`, `--zmax`	float	interpolated min / max	Lower and upper ends of the energy range over which the eight isosurfaces are placed (kcal/mol)
`--thresh`	text	`baker`	Convergence preset of each relaxation (`gau_loose`, `gau`, `gau_tight`, `gau_vtight`, `baker`, `never`)
`--csv`	path	`None`	Read a finished `surface.csv` and only draw the figure; `-i`, `-s`, and `-q` are not needed
`--out-json/--no-out-json`	flag	`False`	Write a summary to `result.json` (JSON Output Reference)

See the generated CLI reference for every option.

Notes¶

Three ranges in one literal: -s takes exactly three ranges, in one inline literal or under pairs: in a YAML/JSON file. For staged scans, use scan.
PDB with chains: the positional form A:SAM:320:CS1 picks one atom without ambiguity.
Grid size: the number of relaxations is the product of the three axis lengths and grows quickly (567 for example 1). Start with a larger --max-step-size or narrower ranges.
--baseline first: zero is put at point (i, j, k) = (0, 0, 0) when it is usable; otherwise the run prints [baseline] 'first' requested but no eligible (i=0,j=0,k=0); using eligible minimum instead. and uses the lowest usable point.
Cap hydrogens: --freeze-links (default on) fixes the parent atoms of the cap hydrogens of an extracted cluster.
Check the spec without computing: --dry-run reads the input, the charge and spin, and -s, prints the plan, and exits without any optimization. With --csv, it checks only the options.
Cycle limit: --relax-max-cycles (default 100000) limits each relaxation; an explicit value overrides YAML opt.max_cycles.
Reference row: i = j = k = -1 and is_preopt = true hold the starting structure. The row stays in the table but is never a grid point, a baseline, or a plotted point.
Re-plotting a table (--csv): the table needs d1_A, d2_A, d3_A, and energy_hartree or energy_kcal. The reference row and rows with bias_converged = false or a non-finite energy are left out.
Too few usable points: with fewer than four usable points, or with all of them in one plane, only the figure is skipped. The run prints [plot] NOTE: Volume plot skipped: … and exits with status 0. With no usable point it prints [plot] No finite data for plotting. and exits with status 1.
Running again into the same --out-dir: whether it is a full scan or a --csv redraw, a run without --out-json removes result.json and summary.json from --out-dir, and a run with it overwrites them; every run replaces scan3d_density.html.

scan3d (3D restrained grid scan)¶