ParmFit Refinement

Overview

Refinement refines the parameters of a molecule supplied as a mol2 topology. MAPLE starts from GAFF2 parameters, optionally optimizes the structure and updates bonded terms from a Cartesian Hessian, applies the selected atomic-charge source, optionally refits proper torsions, and exports Amber and GROMACS files. With the default chg_fit=none, the charges of the input mol2 are kept; charge fitting replaces them at runtime (see ChargeFit).

For a worked walkthrough, see the Refinement tutorial.

Rebuild the topology with ParmEd before SHAKE

tleap identifies hydrogen atoms by the leading character of their atom type, which MAPLE types do not carry, so tleap writes an empty %FLAG BONDS_INC_HYDROGEN section and SHAKE (ntc=2) would constrain nothing. Run the exported tleap input, then normalize the topology with ParmEd and use its output:

tleap -f <base>_maple_tleap.in
parmed -p <base>_maple_gas.prmtop <<<$'outparm <base>_maple_gas_parmed.prmtop\nquit'

Initial Prepare

The input mol2 must carry GAFF2 atom types. Pre-generate it with antechamber -at gaff2 -fi <fmt> -fo mol2 -i <input> -o <output>, or omit mol2= entirely: MAPLE then writes the inline coordinates to <base>_work/ante.pdb and types them into <base>_work/<base>_ff.mol2 (residue LIG). The generated mol2 carries zero placeholder charges, so chg_fit then defaults to abcg2 — an explicit resp, MLIP, or Antechamber method is honored unchanged.

Workflow

The route in outline:

Algorithm 1 — Refinement: small-molecule GAFF2 correction (bond/angle/proper)

Require: typed mol2 (GAFF2; auto-generated when omitted); config
Ensure: corrected parameters (amber topology files, gromacs topology files)
Load the mol2 as the initial parameter set.
Optimize the geometry with the MLIP.
Optional QM reference: optimize + frequency job. ▹ iqm
Derive bonded terms with Seminario / mSeminario. ▹ mseminario, seminario, none
Optional charge fitting. ▹ resp, MLIP models, abcg2, …
Optional torsion fitting: constrained MLIP scans per rotatable bond, QM references per qm_mode, then TorsionFit.
If qm_compare: run the parallel MLIP-reference charge and torsion branches.
Export .mol2/.frcmod and .top/.gro.

Initial parameters. Run parmchk2 -s gaff2 -a Y from the input mol2 to build *_original.frcmod.
Optimization and reference. Optimize the structure and prepare the MLIP or optional QM reference geometry required by the enabled refinement stages.
Bonded correction or skip. Use Seminario or modified Seminario to update bond and angle terms, or retain the original terms when bonded=none.
Atomic charges. Preserve the input charges or calculate new charges with RESP, a charge-capable MLIP, or an Antechamber method.
TorsionFit. Scan selected proper torsions; fit the relative profile without changing nonbonded or topology terms.
Export. Write refined Amber mol2/frcmod and GROMACS top/gro files.

Charge-only operation

If bonded=none and torsionfit=false, MAPLE skips geometry optimization and Hessian evaluation. Charge fitting still runs on the supplied coordinates. With chg_fit=none, the input mol2 charges and the original frcmod are kept unchanged; any other charge method updates the final mol2 charges and keeps the original atom types and frcmod.

Core Parameters

Parameter	Default	Description
`mol2`	Optional	Input topology and atom typing. When omitted, MAPLE auto-generates `<base>_work/<base>_ff.mol2` from the inline coordinates via antechamber (GAFF2 typing, zero placeholder charges); `chg_fit` then defaults to `abcg2`.
`bonded`	`mseminario`	Bond/angle update method: `mseminario`, `seminario`, or `none`.
`vib_scale`	`1.0`	Vibrational frequency scale factor for Hessian-based fitting.
`chg_fit`	`none`	Charge source: input mol2 charges, `resp`, a charge-capable MLIP, or a value passed to `antechamber -c`; defaults to `abcg2` when the mol2 is auto-generated.
`chg_level`	`HF/6-31G(d)`	Gaussian ESP level used only when `chg_fit=resp`.
`chg_route`	Empty	Additional Gaussian route text for RESP ESP jobs.
`iqm`	`false`	Use external QM reference optimization/Hessian and torsion references when enabled. See the main ParmFit page for details.
`torsion_bonds`	Auto	Optional explicit rotatable bonds; otherwise MAPLE selects rotatable single bonds from the mol2 topology.

For TorsionFit parameters, QM job resources, MLIP optimization controls, and levels of theory, see the TorsionFit, General Settings, and QM Reference sections of the main ParmFit page.

Preserving original GAFF2 parameters

Bond/angle and torsion refinement are controlled separately. Setting bonded=none preserves the original BOND/ANGLE terms; setting torsionfit=false preserves the original DIHE terms. With both disabled, Refinement exports the parmchk2/GAFF2 parameters without refinement. When either refinement is enabled, atom types are automatically reassigned (MAPLE Z0/Z1, etc.).

ChargeFit

chg_fit is independent of iqm. RESP derivation always uses Gaussian for the ESP and AmberTools for the RESP stages, reusing qm_nproc and qm_mem. Refinement reads the target charge and multiplicity from the input structure (an inline <charge> <mult> line, e.g. 0 1, or an XYZ <charge> <mult> <path> block); the report prints both the integer target from the input structure and the actual sum in the charged mol2 so that any mismatch is visible.

qm_compare (default false, Refinement only) repeats the charge and torsion branches against MLIP references: with iqm=true, qm_compare=true, and parameter refinement enabled, charge fitting follows both branch geometries. The primary result uses chargefit/qm_route_charged.mol2, while the MLIP comparison uses chargefit/mlip_route_charged.mol2. For chg_fit=none, ParmFit uses the charges recorded in the input mol2.

TorsionFit

Refinement auto-selects rotatable dihedrals from the mol2 topology: proper-torsion terms whose central bond is a single bond outside a ring. Use torsion_bonds to provide explicit overrides (e.g. 6-8,12-14). See the main ParmFit page for the two-stage fitting architecture and parameter details.

Input Files

Simple Input

A simple Refinement job declares method=refinement inline and lists its ParmFit options in a sidecar config. The inline coordinates provide the working geometry, while the mol2 file supplies topology, atom types, and starting charges.

#model=uma(size=uma-s-1p1,task=omol)
#parmfit(method=refinement,input=Refinement.in)
#device=gpu0

C   0.000000  1.520000  0.000000
...

Example simple ParmFit config

mol2=toluene_ff.mol2
chg_fit=none
bonded=mseminario
torsionfit=true

Full External Input

For a more complex setup, keep the MAPLE launcher short and move ParmFit parameters into an external .parmfit file. Declare method=refinement inline together with input=; the external config must not set method=. File paths such as mol2 are resolved relative to the .parmfit file.

#model=uma(size=uma-s-1p1,task=omol)
#parmfit(method=refinement,input=Refinement.parmfit)
#device=gpu0

C   0.000000  1.520000  0.000000
...

Full ParmFit config

Refinement.parmfit

mol2=toluene_ff.mol2

# QM reference for correction and TorsionFit
iqm=false
qm_engine=g16
opt_level=B3LYP/def2SVP
sp_level=B3LYP/def2SVP
opt_route=
sp_route=
qm_mode=1
qm_compare=false
qm_nproc=8
qm_mem=24

# Atomic charges
chg_fit=none
chg_level=HF/6-31G(d)
chg_route=

# Bond/angle correction
bonded=mseminario
vib_scale=1.0

# Geometry optimization LBFGS
memory=5
curvature=70.0
max_step=0.2
max_iter=256
write_traj=false
traj_every=1
verbose=1
use_projection=false
use_line_search=false
bond_constraints=
angle_constraints=
torsion_constraints=

# TorsionFit
torsionfit=true
torsion_bonds=
torsion_steps=36
backend=cgbs
constraint_mode=projected
stage1_weights=true
torsion_refine_rounds=3
torsion_refine_max_iter=256
torsion_refine_tol=1.0e-6
torsion_ensemble=false
torsion_ensemble_ratio=0.3
torsion_ensemble_weight=0.5

Output Files

When mol2= is omitted: <base>_work/ante.pdb and the antechamber-generated <base>_work/<base>_ff.mol2 (zero placeholder charges; chg_fit defaults to abcg2).
<base>_work/<base>_original.frcmod: Initial AmberTools/GAFF2 frcmod from parmchk2.
<base>_work/<base>_maple.mol2: Primary final mol2 with the selected charges; refined workflows use MAPLE atom type naming.
<base>_work/<base>_mlip_maple.mol2: Optional MLIP-comparison mol2 when qm_compare is active.
<base>_work/<base>_maple.frcmod: Refined Amber parameter file.
<base>_work/<base>_maple.top and <base>_work/<base>_maple.gro: GROMACS export for inspection and deployment.
<base>_work/<base>_maple_tleap.in: exported tleap input; running it produces the gas-phase topology <base>_maple_gas.prmtop/.inpcrd.
<base>_work/chargefit/{qm_route|mlip_route}_charged.mol2: Route-specific charged mol2 for RESP or charge-capable-MLIP fitting.
With chg_fit=none, no charge pipeline runs, so no chargefit/ directory is created; the input charges are carried into the final mol2. Antechamber methods write <base>_work/chargefit/antechamber_charged.mol2.
<base>_work/torsionfit/: Torsion scan outputs and fit diagnostics.

Requirements and Limits

mSeminario and Seminario update BOND and ANGLE terms only.
TorsionFit refits selected proper torsions; it does not rewrite topology or nonbonded terms.
Automatic rotatable-bond selection follows the input mol2 bond typing. Fix incorrect aromatic, amide, or double-bond labels in the mol2 before fitting.
The inline coordinates and the mol2 must list the same atoms in the same order, hydrogens included. MAPLE checks only that the atom counts match and then pairs atoms by position; it does not remap two files that were ordered independently. The coordinate values themselves need not match the mol2.