Given an input chemical structure, all parameters can be automatically assigned from a database or derived via fitting to ab initio data generated on the fly.
Walker, B., Liu, C., Wait, E., Ren, P., J. Comput. Chem. 2022, 1. https://doi.org/10.1002/jcc.26954
Wu JC, Chattree G, Ren P. Automation of AMOEBA polarizable force field parameterization for small molecules. Theor Chem Acc. 2012 Feb 26;131(3):1138. doi: 10.1007/s00214-012-1138-6. PMID: 22505837; PMCID: PMC3322661.
- Please read 👇🙏
- Parameterization Input Features
- Automated total charge assignment
- Dominant ionization state enumeration (pH=7) / tautomer enumeration
- Smart memory resource defaults for QM jobs
- Parameterization Features
- Molecule fragmenter to speed up QM calculations
- Parallelized job submission for QM jobs
- Psi4/Gaussian quantum package support
- QM dimer data generation for vdW fitting
- Torsion-Torsion coupling
- Expanded torsion database
- Parameterization Input Preparation
- Ligand Protonation State Generation
- Minimum Example Usage Parameterization
- Default Resource Consumption
- Parameterization Sanity Checks
- Keyword Reference — every
poltype.inikeyword recognized bypoltype.py - 💻 Advanced Program Usage — curated walkthroughs and recommended-input recipes
- Parameterization Output Files
- Parameterization Examples
- Automated AMOEBA Ligand Parameterization How It Works
- The input structure can be given as a filetype with bond order information (sdf, mol, mol2, etc.)
- Cartesian XYZ, tinker XYZ and PDB are not recommended; they will be converted to an SDF file and bond orders will be guessed based on atomic distances.
- If a 2D structure is given, Poltype will generate 3D coordinates for you.
- Total charge is determined by computing the formal charge for each atom.
- Formal atom charge will be assigned via the input number of bonds and bond order for surrounding bonds and element of each atom.
- Optional keywords exist to add missing hydrogens.
- If carbon or nitrogen are negatively charged, then Poltype will assume you meant to have hydrogens on those atoms and protonate to neutral charge. For all other elements, if there exists a formal charge (due to input bond order and valence electrons of element), then Poltype will detect the formal charge for you and compute total charge from sum of each formal atom charge. A warning message is printed when hydrogen atoms are added.
- Special radical charge states require additional information in the input file specifying which atom is a radical.
- If you do not want charged atoms to be protonated then use
addhydrogentocharged=False.
- Dominant ionization states at pH 7 are enumerated and SDF files are generated via Dimorphite-DL (
IonizationState_0.sdf,IonizationState_1.sdf, ...). - Tautomer states are enumerated via rdkit and the first tautomer is the canonical tautomer
TautomerState_0.sdf. - Use
genprotstatesonlyto quit the program after generating dominant ionization states at pH=7 and tautomers.
All input arguments are specified in a poltype.ini file
structure=methylamine.sdf
- Navigate to the directory containing
poltype.iniand the.sdffile, and run:
nohup python /path_to_poltype/poltype.py &final.xyz and final.key are the resulting structure and parameter files you will need.
- After Poltype finishes, check the
OPENMEfolder for torsion-fitting and ESP-fitting results.
- By default, Poltype computes the number of fragment Poltype jobs (or any QM job if the fragmenter is not being used) to run in parallel as the floor of the input number of cores divided by the number of cores per job (default of 2).
- RAM, cores, and disk space can all be detected and a consumption ratio of 80% is used by default. Fragment RAM, disk, and cores are divided evenly by the number of Poltype jobs in parallel.
- MM = Molecular Mechanics (AMOEBA model), QM = Quantum Mechanics
- Check for 2D coordinates and generate 3D coordinates at the beginning of the program.
- Check to ensure refined multipoles enable MM to model the QM potential grid well; raise an error if not.
- Check to ensure QM and MM dipoles are very similar; raise an error if not.
- Check to ensure the final minimized MM structure is similar to the QM-optimized geometry; raise an error if not.
- Check for any missing van der Waals parameters at the end of the program; raise an error.
- Check for any missing multipole parameters at the end of the program; raise an error.
- Check for any zeroed-out torsion parameters in the final key file; check if the fragmenter is transferring torsions properly.
This section describes every keyword recognized by poltype.py when reading a poltype.ini configuration file. Each entry lists the keyword's purpose, accepted value type, and default.
Conventions
- Booleans accept
True/False(case-insensitive). Writing the keyword alone (no=) is treated asTrue. - Three-state PCM switches (
optpcm,toroptpcm,torsppcm) additionally acceptauto(encoded internally as-1). - List keywords are comma-separated; index lists use space-separated entries inside each comma-separated element (e.g.
onlyrotbndslist=1 2, 3 4). - "Vestigial" means the keyword is parsed by
poltype.pybut no downstream code reads the resulting attribute; setting it has no effect.
Keyword categories
- Required Input
- Resource and Job Control
- Run Mode / Workflow Gates
- Protonation State
- QM Package Selection
- Atom Typing
- Geometry Optimization
- Distributed Multipole Analysis (DMA) and ESP
- Database Matching / Pre-fit Key Output
- Torsion Parameterization
- Fragmenter
- Van der Waals Parameterization
- QM Output File Names
- Tolerances and Error Reporting
- Legacy / External-Workflow Keywords
SDF input molecule for parameterization. Must contain bond orders consistent with the desired total charge. Required. Default: None.
Integer net charge of the molecule. If unset, Poltype infers it from the input SDF. Default: None.
Number of processor cores Poltype is allowed to use. Default: ~80% of node cores.
Maximum RAM available to QM jobs (e.g. 20GB). Default: ~80% of node memory.
Maximum scratch disk allotted to QM jobs (e.g. 100GB). Default: ~80% of free scratch.
Float in (0,1] controlling what fraction of node resources Poltype auto-claims when numproc / maxmem / maxdisk are unset. Default: 0.8.
Number of cores per parallel sub-job (e.g. one fragment QM job). Default: 2.
Number of top-level Poltype jobs sharing the same host. Poltype divides resources by this number. Default: 1.
Hours a log file must be idle before Poltype assumes the associated job has died. Default: 1.
Polling interval (seconds) between job-status checks. Default: 0.1.
Absolute path to a bash startup script Poltype sources before invoking external QM engines. Default: None.
If True, validate the input and exit without running any QM. Default: False.
If True, write all QM input files but do not submit jobs. Default: False.
If True, only prepare fragment subdirectories/inputs, then stop. Default: False.
If True, perform only database parameter assignment and exit (no QM, no fitting). Default: False.
If True, run all QM calculations and stop before final parameter fitting. Default: False.
Tells Poltype the initial geometry optimization is already complete; resume from DMA. Default: False.
Marker that the current run is a fragment sub-job (set internally by Poltype). Default: False.
Enable verbose debugging in the fragmenter. Default: False.
Enable verbose debugging during torsion optimization. Default: False.
Enable verbose debugging during torsion fitting. Default: False.
Enable verbose top-level debugging in the parameterization driver. Matched only when none of fragmenterdebugmode / tordebugmode / toroptdebugmode is on the line. Default: False.
Stream QM/Tinker tool output to stdout in addition to log files. Default: False.
Clean up auxiliary scratch (non-QM output) when finished. Default: False.
Maximum number of QM sub-jobs running in parallel on the host. 0 (default) means auto-compute as floor(numproc/coresperjob), capped at maxjobsatsametime=10. Default: 0.
Run only the initial geometry optimization and stop. The match excludes lines containing gaus so it does not collide with use_gausoptonly. Default: False.
Vestigial — assigned in the ini reader and never read elsewhere. Default (if set bare): True.
Vestigial — assigned in the ini reader and never read elsewhere. Default (if set bare): True.
Add hydrogens to unprotonated heavy atoms before parameterization. Default: False.
Add hydrogens to charged-looking atoms (C with valence < 4, N with valence 2). Default: True.
Write protonation states at pH 7 to ProtonationState_*.mol files and exit. Default: False.
Use Gaussian for all QM steps (opt, DMA, ESP, torsion). Matched only when opt is not in the line so it does not collide with use_gausoptonly. Default: False.
Use Gaussian only for the initial geometry optimization; use Psi4 for everything else. Default: False.
Use Gaussian's PCM implementation rather than Psi4's. Default: False.
Use Gaussian for vdW dimer single-point energies. Default: False.
Use Psi4's GeomeTRIC engine for optimization. Default: True.
Disable the PySCF backend. Default: False.
Use the post-QM-opt geometry (not the AMOEBA-minimized one) when sampling vdW dimers. Default: False.
Maximum SCF iterations for QM single points. Default: 500.
Maximum geometry-optimization steps. Default: 400.
Gaussian-style coordinate keyword inserted into the optimization route line (e.g. cartesian). Default: empty.
Intended PySCF optimization functional. Caveat: the ini reader assigns to self.pyscf_opt_met (no h), but downstream pyscf_setup.py reads self.pyscf_opt_meth (with h, which is the dataclass field). The ini keyword therefore does not propagate — the dataclass default is what gets used. Default: wb97x_d3.
PySCF implicit-solvent model: IEF-PCM, C-PCM, SS(V)PE, or COSMO. Default: IEF-PCM.
PySCF solvent dielectric constant. Default: 78.3553 (water).
Alias of prmstartidx — starting number for assigned AMOEBA type indices. Default: 401.
Starting AMOEBA type index. Default: 401.
Use molecular symmetry to merge equivalent atom types. Default: True.
Path to a custom file mapping 1-indexed atom numbers to target type numbers (one mapping per line). Default: None.
File providing multipole-frame definitions (in the same format as the first key file) instead of Poltype's automatic detection. Default: None.
Force-field label written into the resulting key file. Default: AMOEBA.
Path to the header parameter file appended to the top of the output key file. Default: ParameterFiles/amoebabio18_header.prm.
Absolute path to the base AMOEBA .prm library used for typing. Default: ParameterFiles/amoebabio18.prm.
Override the parent-molecule label used when this run is a fragment of a larger molecule. Default: derived from input filename.
Override the Poltype installation path used internally. Matched only when poltypepathlist is not on the line. Default: directory containing poltype.py.
Vestigial — assigned in the ini reader and never read elsewhere. Default: unset.
QM method for geometry optimization. Default: MP2.
Basis set for geometry optimization. Default: 6-31G*.
Use PCM for optimization. True / False / auto. auto enables PCM for zwitterions. Default: auto (encoded as -1).
Master switch for automatic PCM activation on zwitterions. Default: True.
Logical inverse of pcm_auto — disables automatic PCM. Default: False.
Use Psi4 GAU_LOOSE convergence criteria for opt and torsion opt. Default: True.
Convergence preset (uppercased on read). Values handled in optimization.py / torsiongenerator.py: LOOSE (GAU_LOOSE criteria), VERYLOOSE (loose gradient only), NULL (default Psi4/Gaussian criteria). Default: LOOSE.
Run a vibrational-frequency calculation after optimization. Default: False.
Generate an extended starting conformer (torsions trans-restrained) for opt. Default: True.
Use the conformer from the input SDF directly with torsions restrained (skips extended-conf generation). Default: False.
Path to a Tinker XYZ already-optimized geometry; Poltype skips opt and proceeds to DMA. Default: empty.
Generate symmetric-fragment conformers during conformer expansion. Default: False.
Force planar c-NH2 (sp2 anilines); also assigns anglep / opbend. Used with use_gaus. Default: False.
Force non-planar phenol geometry. Default: False.
QM method for the DMA single point. Default: MP2.
Basis set for the DMA single point. Default: 6-311G**.
QM method for ESP fitting. Default: MP2.
Basis set for ESP fitting. Default: aug-cc-pVTZ.
Basis set used for the Gaussian population-analysis (Pop=SaveMixed) step in ESP setup. No class-level default — must be set in poltype.ini if that code path is used.
Fit electrostatic parameters to the QM ESP grid. Default: True.
Restraint weight (written as RESP-WEIGHT) applied to derived multipoles relative to the DMA initial guess during ESP fitting. Default: 1.
Convergence-gradient setting passed to the Tinker potential executable during ESP fitting. Default: 0.1.
Comma-separated list of extra conformer files (SDF or equivalent, same atom order) to add to the ESP fit. Default: empty.
Vestigial — assigned in the ini reader and never read elsewhere. The multi-conformer ESP-fitting path appears to have been replaced by espextraconflist. Default: 1.
Run QM only once for DMA and reuse the wavefunction for ESP. Default: False.
Downgrade aug-cc-pVTZ to aug-cc-pVDZ when the molecule has ≥20 heavy atoms. Default: False.
Use the new grid-based DMA4 algorithm (experimental). Also auto-enables scaleandfixdipole. Default: False.
Free-form prefix to inject additional GDMA commands. gdmacommand_Radius_S=0.80 becomes Radius S 0.80. Default: none.
For DMA4: scale and fix dipole components flagged as overly large (e.g. COO atoms). Default: False (auto-enabled by new_gdma=True).
When DMA produces unusually large multipoles, scale them down before high-level ESP fitting. Default: False.
When DMA produces unusually large multipoles, derive replacements from a smaller fragment. Default: True.
Comma-separated atom indices to treat as "Big-ID multipole" atoms with fragbigmultipole. Default: empty.
Use POLEDIT-style frame definitions instead of Poltype's frame detection. Default: True.
Offset (written as potential-offset) applied when matching grid potentials. Default: 1.0.
Absolute magnitude above which an atomic monopole is flagged as a "big multipole" candidate for scaling or fragment-based replacement. Only C and N atoms are considered. Default: 1.5.
Absolute magnitude above which any atomic dipole component is flagged as a "big multipole". Default: 1.5.
Absolute magnitude above which any atomic quadrupole component is flagged as a "big multipole". Default: 2.4.
Add the QM molecular dipole as an additional restraint during ESP fitting. Default: False.
Relative tolerance (|qm-mm|/qm) for the molecular-dipole comparison. Default: 0.5 (i.e. 50%).
Absolute tolerance (D) on |qm-mm|. An error is raised only when both the relative (dipoletol) and absolute (absdipoletol) gates are exceeded. Default: 0.5.
Demote dipole-mismatch errors to warnings. Default: False.
Write database-matched multipole terms into the pre-fit key file. Default: True.
Write database-matched bond terms. Default: True.
Write database-matched angle terms. Default: True.
Write database-matched polarize terms. Default: True.
Write database-matched torsion terms. Default: True.
External .key file whose contents are appended to the database-matched key. Default: None. The file is copied to inputkey.key for safety.
Comma-separated list of parameter-modification patch files (.mod). See ParameterFiles/dma4_hfe2023.mod. Default: empty.
Use a faster, less exhaustive database-matching strategy. Default: False.
Percent tolerance on MM-vs-QM bond-length deviation (|qm-mm|*100/qm) before flagging. Default: 0.5 (%).
Percent tolerance on MM-vs-QM equilibrium-angle deviation (|qm-mm|*100/qm) before flagging. Default: 0.5 (%).
Skip torsion parameterization entirely. Default: False.
Run torsion QM but skip the actual fitting. Default: False.
Force a QM scan of every rotatable bond, even those matched in the database. Default: False.
Method for torsion-scan optimizations. Values: xtb, ANI, AMOEBA, or any QM method recognized by Psi4/Gaussian. Default: xtb.
Comma-separated list of opt methods to compare torsion profiles across. Default: [toroptmethod].
Method for torsion single-point energies. Default: wB97X-D.
Comma-separated list of SP methods to compare. Default: [torspmethod].
Basis set for torsion optimizations. Default: 6-311G.
Basis set for torsion single points. Default: 6-311+G*.
PCM for torsion opt: True / False / auto. Default: auto (-1).
PCM for torsion SP: True / False / auto. Default: auto (-1).
GFN-xTB Hamiltonian version (1, 2, or FF). Default: 2 (GFN2-xTB).
xTB torsion-restraint force constant (kcal/mol/deg²). Default: 5.
Force constant (kcal/mol/rad²) restraining non-scanned dihedrals around the active rotatable bond. Default: 1641.4 (0.5 kcal/mol/deg²).
L1 regularization weight on torsion-parameter magnitudes during fitting. Default: 0.1.
L2 regularization weight on torsion-parameter magnitudes during fitting. Default: 0.1.
Number of Fourier terms used in the torsion fit. Default: 3.
Number of grid points sampled along each dihedral. Default: 12 (auto-increases if more torsion parameters need fitting).
Upper bound on torsion-scan grid points. Default: 40.
Restrict torsion sampling to listed bonds. Format: i j, k l, .... Default: empty.
Skip torsion sampling on listed bonds (useful for AA backbone). Format: i j, k l, .... Default: empty.
Restrict tortor sampling to listed triples (b c d from a b c d e). Default: empty.
Comma-separated tuples of torsion indices to fit jointly. Default: empty.
Pucker non-aromatic rings and refine the in-ring torsion parameters. Default: False.
Cut and 1D-scan a non-aromatic-ring torsion (instead of transferring alkane parameters). Default: False.
Allow a phase offset on the first cosine term of the torsion fit. Default: False.
Number of dihedral restraints per N-containing rotatable bond. Default: 2.
Sample the 2D torsion-torsion potential-energy surface for adjacent rotatable dihedrals. Matched only when only is not in the line so it does not collide with onlyrottortorlist. Default: False.
Effective temperature (in kcal/mol) used for Boltzmann weighting exp(-E/T) of torsion conformers during fitting. Default: 8.
Demote torsion-fit errors to warnings. Default: False.
Maximum allowed RMSD (Å) between QM and MM optimized geometries. Default: 1.
Maximum allowed RMS potential deviation in the ESP fit. Default: 1.
Maximum allowed RMS deviation between QM and MM torsion energy profiles. Default: 1.
Relative version of maxtorRMSPD. Default: 0.1.
Disable fragmenting; parameterize the whole molecule as-is. Default: False.
Maximum fragment-growth iterations before stopping. Default: 4.
Maximum allowed Wiberg-bond-order difference between parent and fragment. Default: 0.05.
Use the small-molecule-tuned fragmentation path. Default: False.
Continue past ESP-fit errors raised in fragment jobs. Default: False.
Name of the Fennix neural-network model checkpoint used for fragment energies (resolved as <fennixmodeldir>/<fennixmodelname>.fnx). Default: ani2x_model0.
Refine database vdW parameters by fitting to ab initio dimer scan data. Default: False.
Restrict vdW refinement to listed atom indices. Default: None.
Refine a single vdW atom (by 1-indexed atom number). Default: None.
Comma-separated vdW types whose radii are frozen during fitting. Default: empty.
Which vdW parameters to fit: subset of S (sigma/radius), T (well depth), R (reduction factor). Default: ['S', 'T'].
Also fit the hydrogen reduction factor. Default: False.
Add lone-pair vdW sites for halogens/heteroatoms with sigma holes. Default: False.
Use MP2/CBS counterpoise on aug-cc-pV[TQ]Z for dimer SPs (slow but accurate). Default: False.
Generate homodimer scans (same molecule + same molecule). Default: False.
These override default file names for resuming or feeding pre-computed QM output. All default to internally generated paths derived from the molecule name (see assign_filenames in poltype.py).
Geometry-optimization log file.
DMA single-point log file.
ESP single-point log file.
DMA Gaussian formatted-checkpoint (fchk) file.
ESP fchk file.
DMA chk file.
ESP chk file.
Formatted-checkpoint output file produced by formchk.
GDMA output file containing distributed multipoles.
Most tolerance keywords are documented in their parent sections above. They are listed here together for cross-reference:
chargethreshold,dipolethreshold,quadrupolethreshold— magnitude thresholds for flagging "big multipole" atoms.dipoletol,absdipoletol— molecular-dipole tolerances (both relative and absolute gates must trigger).mmbondtol,mmangletol— MM-vs-QM bonded-geometry percent tolerances.maxRMSD,maxRMSPD,maxtorRMSPD,maxtorRMSPDRel— geometry / potential / torsion RMS limits.WBOtol— Wiberg bond-order tolerance for fragments.suppressdipoleerr,suppresstorfiterr,skipespfiterror— demote specific error classes to warnings.
These keywords are parsed by poltype.py but are not used by the core parameterization pipeline. They are reserved for downstream solvation / BAR free-energy workflows and ligand-binding pipelines that consume Poltype output.
PDB filename of the apo protein structure for binding-affinity setup.
Comma-separated list of ligand identifiers belonging to a binding study.
Template ligand structure (SDF/MOL) for alignment in a binding setup.
Template ligand Tinker XYZ used for atom-index mapping.
Lambda-window interval for Bennett Acceptance Ratio (BAR) free-energy calculations.
Convergence threshold for enthalpy error in liquid-property fitting.
Convergence threshold for density error in liquid-property fitting.
Weight of the enthalpy term in liquid-property fitting.
Weight of the density term in liquid-property fitting.