opt

Relaxes a single structure toward a local minimum, optionally with distance restraints or imaginary-mode flattening. Use --opt-mode grad (alias lbfgs, default) for L-BFGS minimization or --opt-mode hess (alias rfo) for RFOptimizer. The optimizer comes from pysisyphus, while an MLIP backend (UMA by default; ORB, MACE, and AIMNet2 also available via -b/--backend) provides energies, gradients, and Hessians. Supply one geometry as PDB/mmCIF, XYZ, or GJF; extract a desired trajectory frame to .xyz first.

Examples

Command form:

pdb2reaction opt -i INPUT.{pdb|cif|mmcif|xyz|gjf} [-q CHARGE] [-l, --ligand-charge <number|'RES:Q,...'>] [-m MULT] \
 [-b/--backend uma|orb|mace|aimnet2] \
 [--opt-mode grad|hess|lbfgs|rfo] [--flatten/--no-flatten] [--freeze-links/--no-freeze-links] \
 [--dist-freeze '[(i,j,target_Å),...]'] [--one-based|--zero-based] \
 [--bias-k K_eV_per_Ų] [--dump/--no-dump] [-o/--out-dir DIR] \
 [--convert-files/--no-convert-files] [--ref-pdb FILE]

Basic minimization:

pdb2reaction opt -i input.pdb -q 0 -m 1 --out-dir ./result_opt

Tighter threshold and keep trajectory dumps:

pdb2reaction opt -i input.pdb -q 0 -m 1 --thresh gau_tight --dump \
 --out-dir ./result_opt_tight

Add a harmonic distance restraint. The example uses --bias-k 20.0 (a loose restraint suitable for gently guiding the structure toward the target distance); the default bias.k is 300 eV·Å⁻² and is better when you want the restraint to dominate during optimization:

pdb2reaction opt -i input.pdb -q 0 -m 1 \
 --dist-freeze '[(1,5,2.0)]' --bias-k 20.0 --out-dir ./result_opt_rest
# 2-tuple form restrains atoms 1 and 5 to their current distance: --dist-freeze '[(1,5)]'

Switch explicitly to RFO mode:

pdb2reaction opt -i input.pdb -q 0 -m 1 --opt-mode hess \
 --out-dir ./result_opt_hess

Workflow

• Optimizer naming: the CLI accepts grad|lbfgs and hess|rfo; in the YAML opt_mode key, use lbfgs or rfo directly. See --opt-mode (subcommand-dependent) for the per-subcommand token→algorithm mapping.

• Flatten loop: --flatten enables post-optimization flattening of imaginary vibrational modes. In opt, all detected imaginary modes are flattened each iteration until none remain or the internal loop cap is reached. Its PHVA eigensolver always uses the constrained rigid-mode treatment.

• Restraints: --dist-freeze consumes Python-literal tuples (i, j, target_Å) where target_Å is the target distance in Å; omitting the third element restrains the starting distance. --bias-k sets a global harmonic strength (eV·Å⁻²). Indices default to 1-based but can be flipped to 0-based with --zero-based.

• Charge/spin resolution: Charge is resolved via the standard priority chain (see CLI Conventions: Charge specification for details).

• Freeze atoms: When --freeze-links is active, cap-hydrogen parent atoms are automatically frozen (see Cap hydrogen and frozen atoms).

• Dumping & conversion: --dump mirrors opt.dump=True and writes optimization_trj.xyz; when conversion is enabled, PDB inputs receive .pdb companions and mmCIF/oversized-PDB bridge inputs receive both .pdb and .cif. opt.dump_restart can emit restart YAML snapshots.

• Exit codes: See Exit codes in CLI Conventions.

Outputs

out_dir/
├─ final_geometry.xyz # Always written
├─ final_geometry.pdb # PDB/mmCIF topology input, conversion enabled
├─ final_geometry.cif # mmCIF/oversized-PDB bridge input, conversion enabled
├─ final_geometry.gjf # When a Gaussian template was detected and conversion is enabled
├─ optimization_trj.xyz # Only if dumping is enabled
├─ optimization.pdb # PDB conversion of the trajectory (topology input, conversion enabled)
├─ optimization.cif # Bridge-input trajectory with original IDs restored
└─ restart*.yml # Optional restarts when opt.dump_restart is set

The console prints the resolved geom, calc, opt, and lbfgs/rfo blocks, along with cycle-by-cycle progress and total runtime.

See CLI Conventions: Configuration precedence for the full resolution order.

CLI options

The full flag list is in the generated command reference; the table below covers the options that need explanation, and the exhaustive list is not hand-duplicated here.

Option	Description	Default
-i, --input PATH	One PDB/mmCIF, XYZ, or GJF geometry; extract a trajectory frame to .xyz first.	Required
-q, --charge INT	Net charge. Required unless a .gjf template or --ligand-charge/-l (PDB/mmCIF inputs or XYZ/GJF with --ref-pdb) supplies it. Overrides --ligand-charge/-l when both are set.	Required unless template/derivation applies
-l, --ligand-charge TEXT	Either a scalar integer (e.g., -1) for the total ligand charge, or a per-residue mapping (e.g., GPP:-3,SAM:1) that derives the total from PDB/mmCIF residue metadata. Used when -q is omitted (PDB/mmCIF inputs or XYZ/GJF with --ref-pdb).	None
--workers INT	UMA predictor parallelism. workers > 1 cannot be combined with an explicit analytical Hessian request; use workers = 1 or finite differences. See workers > 1 is incompatible with analytical Hessians (UMA backend).	1
--workers-per-node INT	Workers per node, forwarded to the parallel predictor.	1
-m, --multiplicity INT	Spin multiplicity (2S+1). Falls back to .gjf template or 1.	Template/1
--dist-freeze TEXT	Repeatable string parsed as Python literal describing (i,j,target_Å) tuples for harmonic restraints.	None
--one-based/--zero-based	Interpret --dist-freeze indices as 1-based (default) or 0-based.	True
--bias-k FLOAT	Harmonic bias strength applied to every --dist-freeze tuple (eV·Å⁻²).	300
--freeze-links/--no-freeze-links	Toggle cap-hydrogen parent freezing (PDB/mmCIF input or XYZ/GJF with --ref-pdb). See extract for cap-hydrogen details.	True
--freeze-atoms TEXT	Comma-separated 1-based atom indices to freeze explicitly (e.g., '1,3,5'). Complements --freeze-links; applies to any input format.	None
--max-cycles INT	Hard limit on optimization iterations (opt.max_cycles).	100000
--opt-mode TEXT	Optimizer preset: grad (lbfgs) or hess (rfo). Aliases lbfgs/rfo are accepted. On opt, grad = L-BFGS minimization; on tsopt, grad = Hessian-Guided Dimer TS search. For the full subcommand-dependent table, see --opt-mode (subcommand-dependent).	grad
--flatten/--no-flatten	Enable/disable the post-optimization imaginary-mode flattening loop.	False
--reject-uphill/--no-reject-uphill	Opt in to rejecting energy-raising RFO trial steps in hess mode with a 1e-4 Hartree tolerance (roll back to the lower-energy geometry and shrink the trust radius); ignored in grad/lbfgs mode. At the emergency trust floor, the retained geometry receives a final normal convergence check before a non-converged stop is reported.	False
--dump/--no-dump	Emit trajectory dumps (optimization_trj.xyz).	False
--convert-files/--no-convert-files	Enable or disable XYZ/TRJ → PDB/CIF companions for PDB/mmCIF topology inputs and XYZ → GJF companions for Gaussian templates.	True
--ref-pdb FILE	Reference PDB or mmCIF topology to use when the input is XYZ/GJF (keeps XYZ coordinates).	None
-o, --out-dir TEXT	Output directory for all files.	./result_opt/
--thresh TEXT	Override convergence preset (gau_loose, gau, gau_tight, gau_vtight, baker, never).	gau
--config FILE	Base YAML configuration file.	None
--show-config/--no-show-config	Print resolved YAML layer information before execution.	False
--out-json/--no-out-json	Write a machine-readable result.json to out_dir. See JSON Output Schema for the schema.	False
--dry-run/--no-dry-run	Validate options and print execution plan without running optimization.	False
-b, --backend {uma,orb,mace,aimnet2}	MLIP backend.	uma

YAML configuration

Shared sections reuse YAML Reference; adjust only the values you need to change. geom, calc, opt, and the optimizer-specific lbfgs/rfo blocks use the canonical keys and defaults — see geom, calc, opt, lbfgs, rfo. A minimal representative configuration:

geom:
  coord_type: cart        # or `dlc` for delocalized internal coordinates
  freeze_atoms: []        # 1-based frozen indices; merged with CLI cap detection
calc:
  charge: 0               # mirrors the CLI option; defaults from `.gjf` when present
  spin: 1
opt:
  thresh: gau
  max_cycles: 100000
  out_dir: ./result_opt/  # opt-specific default

The only opt-specific default is out_dir: ./result_opt/ (also applied to lbfgs.out_dir/rfo.out_dir).

Full schema (every key and default): YAML Reference.

Notes

Note

Energy plateau stop (opt-in, default off). With --stop-plateau (YAML energy_plateau: true), the optimizer terminates with status stalled (not converged) if the energy range (max − min) over the last --stop-plateau-window steps falls below --stop-plateau-thresh (default 1×10⁻⁴ au ≈ 0.06 kcal/mol over 50 steps). It saves cycles when the measured force noise/flatness prevents the selected force threshold from being reached; the noise level is backend/model/system dependent. A flat energy is not evidence of a stationary point, so this never reports convergence and --max-cycles remains the real bound. The stop is skipped for chain-of-states optimizers, which store per-image energy arrays.

The fixed constrained rigid-mode treatment applies only when --flatten runs; it does not change L-BFGS or RFO optimization steps. See Frozen Atoms.

See Also

• Common Error Recipes – Symptom-first failure routing

• Troubleshooting – Detailed troubleshooting guide

• tsopt — Optimize transition states (saddle points) instead of minima

• freq — Vibrational analysis to confirm optimization reached a minimum

• extract — Generate active site model (binding pocket) PDBs before optimization

• all — End-to-end workflow that pre-optimizes endpoints

• YAML Reference — Full opt, lbfgs, rfo configuration options

• Glossary — Definitions of L-BFGS, RFO