How to use a custom force field with amber.build#

Goal#

Pass non-default force field, topology, or parameter files to htmd.builder.amber.build() so tLeap parameterizes residues that aren’t covered by the built-in AMBER defaults (custom ligands, post-translational modifications, modified bases, etc.).

Minimal example#

from htmd.builder import amber

amber.build(
    mol,
    outdir="./build",
    ff=["leaprc.protein.ff14SB", "leaprc.gaff2", "leaprc.water.tip3p"],
    topo=["./ligand.cif"],          # one .prepi / .prep / .in / .cif / .mol2 per residue
    param=["./ligand.frcmod"],      # one .frcmod per residue
)

Each of the three arguments independently overrides its corresponding default - passing topo=... doesn’t affect ff, etc. The defaults are:

  • ff defaults to defaultFf() = ["leaprc.protein.ff14SB", "leaprc.lipid21", "leaprc.gaff2", "leaprc.RNA.OL3", "leaprc.DNA.bsc1", "leaprc.water.tip3p"]. Replacing it drops all bundled parameters; re-add the leaprc entries you still need.

  • topo and param default to empty lists (defaultTopo(), defaultParam()). The bundled GAFF / RNA / DNA / lipid21 parameters all come from the leaprc files in ff, not from topo / param. Appending is the usual mode: topo=[..., "./ligand.cif"].

Tip

tLeap pairs parameters to atoms by the atom-type names inside the files - the topo and param filenames don’t have to match each other for the build to succeed. However, a useful convention is to name each pair after the residue’s resname (LIG.cif + LIG.frcmod for a residue LIG): when HTMD’s built-in cofactor / NCAA / PTM library contains an entry with the same name, the auto-load logic detects the user-supplied LIG.frcmod and skips re-adding the built-in LIG parameters on top - avoiding duplicate-atomtype errors when your custom parameters reuse atom types that collide with the built-in set.

Parameters that matter#

Parameter

What it does

ff

List of leaprc.* file paths or names. Overrides the entire default protein/water/ion stack.

topo

List of topology files - one per non-canonical residue. .prepi / .prep / .in are loaded with tLeap’s loadamberprep; .cif / .mol2 are loaded with loadmol2 (the CIF is converted to mol2 internally first, no prepgen involved).

param

List of .frcmod files containing the bond / angle / dihedral / VdW parameters for the residues in topo.

atomtypes

Extra atom-type triplets (type, element, hybrid) passed to tLeap’s addAtomTypes. Example: atomtypes=[("C1", "C", "sp2"), ("CI", "C", "sp3")].

offlibraries

Additional AMBER OFF / LIB residue libraries to load via loadoff.

Common variations#

Combining custom topologies with the defaults#

from htmd.builder import amber

amber.build(
    mol,
    outdir="./build",
    topo=["./ligand.cif"],          # defaultTopo() is empty, so no re-adding needed
    param=["./ligand.frcmod"],      # ditto defaultParam()
)

defaultTopo() and defaultParam() are both empty lists, so appending is unnecessary — just pass the new files. The protein-with-ligand tutorial does this directly via parameterizeFromSpecs()’s out.topo_paths / out.frcmod_paths.

Using a different protein force field#

amber.build(mol, outdir="./build", ff=[
    "leaprc.protein.ff19SB",
    "leaprc.gaff2",
    "leaprc.water.opc",
])

ff19SB + OPC is the AMBER-recommended modern stack (replacing ff14SB + TIP3P). Make sure leaprc.water.opc and leaprc.protein.ff19SB are in your tLeap search path - htmd.builder.amber.listFiles() lists what’s available.

Gotchas#

  • The default topo / param lists are empty; all bundled parameters (water, GAFF, lipid21, RNA, DNA) come from the leaprc entries in ff. So you usually only need to append to topo / param for new residues - no re-adding of defaults required. If you replace ff, on the other hand, re-add the leaprc entries you still need or tLeap will fail on residues whose parameters aren’t loaded.

  • The order of leaprc.* files in ff matters: tLeap applies them in sequence, so later entries can shadow earlier ones. Put leaprc.water.<model> last so the water model isn’t overwritten by an earlier protein/lipid leaprc.

See also#