NCAA Tutorial

Before you start: AmberTools and Gaussian 16 for every case

Every case needs AmberTools and Gaussian 16 (g16) on PATH. These inputs set iqm=false, but the charges still come from RESP — the default chg_fit=resp — and Gaussian evaluates the ESP. Check before the first run: type tleap antechamber g16 must not report not found.

MAPLE does not check for Gaussian at launch; it looks for g16 only when the first Gaussian job starts, so a missing g16 stops a run partway through. Each Gaussian job requests qm_nproc=8 cores and qm_mem=24 GB by default; set lower values in the sidecar config on a smaller machine (see the hub’s General Settings). The hub’s Requirements and QM Reference sections explain when each program is needed.

Overview

This tutorial walks through the NCAA route of parmfit(method=ncaa) in three cases on Morus alba Diels–Alderase (MaDA; Protein Data Bank ID 6JQH), a flavin adenine dinucleotide (FAD)-dependent enzyme whose FAD cofactor is covalently linked to a histidine residue. The input structure MaDA.pdb carries that residue as _89:HIF; it has no force-field template and becomes the exported residue HF1. Case 1 builds the template with torsion fitting off; Case 2 switches torsion fitting on with explicit bonds; Case 3 declares a second residue alongside the first. Every excerpt below is taken from verified runs of the inputs shown here.

Overall structure of MaDA (PDB ID 6JQH) showing the covalent linkage between the histidine residue and the FAD cofactor — Fig. 1 — Overall structure of MaDA showing the covalent linkage between the histidine residue and the FAD.

Every run writes a <base>.parmfitrun.in file next to the output that echoes your configuration with defaults filled in; watch the log for Unknown left-hand warnings, which flag keys that no builder consumed. The reference definition of every key lives in the NCAA manual page and the shared sections of the ParmFit hub; software and input requirements are summarized in the hub's Requirements section.

Example Files

Follow the cases below and save the files you need from their links, or download the complete run archive, including every _work/ directory, from Zenodo: 10.5281/zenodo.23126301. It has one zip per case — Case1.zip (138 MB), Case2.zip (139 MB), and Case3.zip (151 MB) — and each unpacks to a folder of the same name. The Refinement and MetalAA archives use the same zip names, so keep each tutorial in its own folder. To rerun a case, start from its input files in a new folder: inside an unpacked archive folder, TorsionFit would read the archived scans instead of running its own scan (see the hub’s Scan Reuse).

Case 1 — The basic input: building from FAD

Goal. Build a deployable Amber template for one noncanonical residue (here HIF89, exported as HF1) with default fitting: chg_fit=resp, bonded=mseminario, pro_ff=ff14SB. Torsion fitting — on by default — is explicitly switched off here so the first run isolates the charge and template pipeline.

Input. The selector picks the target residue, ncaa_resnames renames it for export, and ncaa_charges pairs with it one to one. The route keys live in the sidecar:

NCAA1.inpreads the structure fromMaDA.pdb

#model=uma(size=uma-s-1p1)
#parmfit(method=ncaa,input=NCAA1.in)
#device=gpu0

PDB MaDA.pdb

NCAA1.in

# NCAA route settings; declare method=ncaa in #parmfit(...) and reference this file via input=
# Only non-default entries are listed; the generated parmfitrun.in shows every resolved value.

ncaa_resids=HIF89
ncaa_charges=-2
ncaa_resnames=HF1
chg_level=HF/6-31G(d)
torsionfit=false

Run. In the folder that holds NCAA1.inp, NCAA1.in, and MaDA.pdb:

maple NCAA1.inp NCAA1.out    # or simply: maple NCAA1.inp

The second argument names the log; without it, MAPLE derives the log name from the input, so both forms write NCAA1.out. The run also writes the resolved configuration NCAA1.parmfitrun.in and the work directory NCAA1_work/. A run has finished normally when the result block reads Status: completed and the log ends with a TOTAL RUN TIME line; on the tutorial hardware Case 1 takes about 11 min.

What happens.

Graph matching. Standard residues are matched against the active ff14SB templates, receiving canonical atom names, types, and net charges; whether each cysteine stays CYX or becomes CYM is decided by disulfide detection.
Capped models. ACE (acetyl)–target–NME (N-methylamide) α and β conformers are built and optimized with an MLIP (machine-learned interatomic potential), backbone and caps frozen, so only the sidechain relaxes — the backbone is rotated to the α/β targets (φ,ψ) ≈ (−60°, −40°) and (−120°, 140°) for an L residue, with the signs reversed for a D residue.
Charges. Gaussian evaluates the ESP (electrostatic potential) of both capped conformers; AmberTools then performs one joint two-stage RESP (restrained electrostatic potential) fit over them.
AmberTools template. antechamber/prepgen/parmchk2 build the initial prepin/frcmod.
Refinement. An MLIP Hessian + mSeminario update bond/angle terms. TorsionFit is skipped.
Deployment. Refined templates, processed PDB (Protein Data Bank), and tleap input are written, and tleap validation runs.

Three-panel render of a simplified ACE-HIS-NME capped model: the initial sidechain conformation at top with rotation arrows at the sidechain anchor, a flipping arrow in the middle, and the optimized alpha and beta conformers below — Fig. 2 — The conformer build, demonstrated on a simplified ACE–HIS–NME capped model (the covalently linked FAD cofactor is omitted purely to display the conformations): the initial sidechain conformation flips into the α and β conformers, whose joint ESP feeds the two-stage RESP fit.

The resolved configuration. Next to NCAA1.out, MAPLE writes NCAA1.parmfitrun.in:

# parmfitrun.in - resolved parmfit configuration for method=ncaa
# Generated by MAPLE parmfit; values are the user config entries with defaults filled in.
# This file is itself a valid parmfit config and can be referenced via input=.
# residues declared for the NCAA flow (built, then folded or frozen)
ncaa_resids              = HIF89
# extra altloc selectors
keep                     = 
# residues force-added to the site
add_resid                = 

# NCAA run
# Non-standard amino acid declaration and residue building
# 1:1 with ncaa_resids
ncaa_charges             = -2
# 1:1 with ncaa_resids; keep within 3 characters (PDB limit)
ncaa_resnames            = HF1
# multiplicity for the NCAA QM jobs
ncaa_mults               = 
# (ff14SB, ff19SB)
pro_ff                   = ff14SB
... (open the real file after a run to see every resolved key)

Reading the output. The banner's PDB diagnostics sort every residue into one of three buckets. matched counts residues whose complete graph matched an active Amber template — they receive canonical names, atom types, and charges. backbone_only counts residues whose connected peptide backbone was recognized but which matched no complete template — the NCAA candidates; the target appears there. unmatched counts residues with no template at all, typically nonprotein ligands or cofactors — they are reported for explicit declaration (lig_resids in MetalAA, or a separate NCAA run) rather than guessed. Disulfide decisions appear under template overrides:

======================================================================
                           Parmfit NCAA
======================================================================
Target: _89:HIF (protein)
  PDB residue templates: matched=516, backbone_only=1, unmatched=0
    non-standard (matched backbone only): _89:HIF (target)
    template overrides (renamed): _10:CYM (CYX->CYM), _74:CYM (CYX->CYM)
  PDB target charge: _89:HIF = -2 (from your input)

The start lines and stage trace follow:

  [NCAA] MLIP model preparation + reference optimization ...
  NCAA target selector: HIF89
  residue name: HF1
  chirality: L
  net charge / spin multiplicity: -2 1
  protein ff: ff14SB
  bonded refinement: mseminario
  charge fitting: resp
  charge level: HF/6-31G(d)
  [NCAA] atomic charge fitting (resp) ...
  [NCAA] AmberTools template build ...
  [NCAA] MLIP Hessian + mSeminario ...
  [NCAA] TorsionFit skipped ...
  [NCAA] writing refined templates + tleap input ...
  [NCAA] tleap validation ...
  [NCAA] route completed; final summary follows.

The result block closes with the production tleap command and its Tleap status:

======================================================================
                       PARMFIT NCAA RESULT
======================================================================
Status: completed
Route: NCAA
Target: _89:HIF
Residue name: HF1
Chirality: L
Protein ff: ff14SB
Res charge/spin-multi: -2 1
Charge fitting: resp
Charge level: HF/6-31G(d)
Target charge: -2
Actual charge: -2.00000000
Charge MOL2: NCAA1_work/ncaa/HIF89/NCAA1_capped.mol2

Main products:
  refined prepin: NCAA1_work/HF1_maple.prepin
  refined frcmod: NCAA1_work/HF1_maple.frcmod
  tleap PDB:      NCAA1_work/NCAA1_ncaa_tleap.pdb
  tleap input:    NCAA1_work/NCAA1_ncaa_tleap.in

Stage timing:
  charge fitting                    7m 46s
  Hessian + mSeminario              1m 30s
  model preparation + reference        49s
  tleap validation                     11s
  AmberTools template build             0s
  final export                          0s

Next step:
  cd NCAA1_work
  tleap -s -f NCAA1_ncaa_tleap.in |tee NCAA1_ncaa_tleap.out

Tleap status:
  Errors: 0
  Warnings: 3
  Notes: 0
  ...

The tleap warnings. Tleap status counts the warnings of the validation run, logged in NCAA1_ncaa_tleap.out. In this run none of the three concerns the new template:

tleap message	Cause	Action
`The unperturbed charge of the unit (-4.000000) is not zero.`	Net charge of the protein before ions are added: the declared −2 of the target residue plus Cys10 and Cys74, which the run deploys as `CYM` (−1 each; see `template overrides` above). The other charged residues cancel.	None for tleap, which adds 4 Na⁺ next. Check that the CYM assignment and the declared target charge are what you intend.
`Converting N-terminal residue name to PDB format: NTHR -> THR`	Saving a PDB writes the standard name of the terminal residue.	None.
`Converting C-terminal residue name to PDB format: CLEU -> LEU`	The same for the C terminus.	None.

Checkpoint

Before moving on, confirm: the target residue appears in the diagnostics as backbone_only; tleap reports Errors: 0; the processed PDB (NCAA1_ncaa_tleap.pdb) carries the exported name HF1 at position 89; the per-residue work directory NCAA1_work/ncaa/HIF89/ holds the conformers and charge files. Read the tleap warnings of your own run against the table above.

Case 2 — Fitting torsions over declared bonds

What changed. This case changes two things: torsionfit=true returns to the default, and torsion_bonds names the four residue-local bonds to refit — here the two sidechain chi angles, the covalent His–FAD link, and the ribityl chain of the cofactor.

Input. NCAA2.inp differs from NCAA1.inp only in input=NCAA2.in:

NCAA2.inpreads the structure fromMaDA.pdb

#model=uma(size=uma-s-1p1)
#parmfit(method=ncaa,input=NCAA2.in)
#device=gpu0

PDB MaDA.pdb

In NCAA2.in, the Case 1 line torsionfit=false is replaced by torsionfit=true, and torsion_bonds is new. Edit the existing line rather than appending a second one: the run stops with a Duplicate parmfit config key error when a key appears twice. The changed lines:

# Sidechain torsion fitting on four representative residue-local bonds:
# 3-8 chi1 (CA-CB), 8-11 chi2 (CB-imidazole C4), 6-60 covalent His-FAD link (N2-CH2), 22-25 ribityl (C8-C9)
torsionfit=true
torsion_bonds=3-8,8-11,6-60,22-25

NCAA2.in

# NCAA route settings; declare method=ncaa in #parmfit(...) and reference this file via input=
# Only non-default entries are listed; the generated parmfitrun.in shows every resolved value.

ncaa_resids=HIF89
ncaa_charges=-2
ncaa_resnames=HF1
chg_level=HF/6-31G(d)

# Sidechain torsion fitting on four representative residue-local bonds:
# 3-8 chi1 (CA-CB), 8-11 chi2 (CB-imidazole C4), 6-60 covalent His-FAD link (N2-CH2), 22-25 ribityl (C8-C9)
torsionfit=true
torsion_bonds=3-8,8-11,6-60,22-25

Run. maple NCAA2.inp NCAA2.out, as in Case 1; on the tutorial hardware it takes about 2 h 04 min, and NCAA2.parmfitrun.in shows torsionfit and torsion_bonds resolved alongside their defaults.

What happens. Each listed bond is scanned and refitted. All of it is written to NCAA2_work/torsionfit/HIF89/:

NCAA2_work/torsionfit/HIF89/
  NCAA2_torsionfit_9-14_scan_final.xyz      # 3-8   chi1
  NCAA2_torsionfit_14-17_scan_final.xyz     # 8-11  chi2
  NCAA2_torsionfit_12-66_scan_final.xyz     # 6-60  His-FAD link
  NCAA2_torsionfit_28-31_scan_final.xyz     # 22-25 ribityl
  ... (per-bond .out logs, pos/neg trajectory and optimized xyz variants)

Watch the index space: torsion_bonds uses residue-local 1-based indices (ACE/NME caps not counted), but the scan files are named with the capped-model serials — the ACE cap contributes 6 atoms, so residue-local 3-8 appears as 9-14, 6-60 as 12-66, and so on. Each i-j entry names the central bond of the scanned dihedral — the order within a pair is free (6-10 and 10-6 are the same bond; scan files use the ascending form) — and the scanned dihedral is the proper-dihedral term the topology already defines over that bond.

The stage timing in NCAA2.out shows what the switch costs — TorsionFit simply takes far longer, becoming the most time-consuming stage of the run:

Stage timing:
  TorsionFit                      1h 53m 07s
  charge fitting                    7m 56s
  Hessian + mSeminario              1m 35s
  model preparation + reference     1m 04s
  tleap validation                      7s
  ...

Render of the capped HF1 residue with the four fitted rotatable dihedrals highlighted in different colors — chi1 and chi2 on the histidine sidechain, the covalent His-FAD link, and the ribityl chain C8-C9 — Fig. 3 — Case 2: the four fitted rotatable dihedrals, each highlighted in a different color.

Checkpoint

Confirm every declared bond has a scan file (translate residue-local to capped serials with the +6 offset of this ACE cap). Keep the explicit list short and meaningful — each bond costs a full constrained scan.

Case 3 — When there are multiple NCAA residues

TRP482 is a standard residue; it is declared here only to demonstrate a two-residue run, and in real work you normally declare only residues that have no Amber template.

What changed. A second residue — TRP482, exported as WF1 — is declared alongside the first, each with its own charge and exported name. ; now separates per-residue torsion-bond groups. Bold lines are new or have changed in this case.

Input.

NCAA3.inpreads the structure fromMaDA.pdb

#model=uma(size=uma-s-1p1)
#parmfit(method=ncaa,input=NCAA3.in)
#device=gpu0

PDB MaDA.pdb

External config.

NCAA3.in

# NCAA route settings; declare method=ncaa in #parmfit(...) and reference this file via input=
# Only non-default entries are listed; the generated parmfitrun.in shows every resolved value.

# Two residues declared together; charges/names pair 1:1 with ncaa_resids
ncaa_resids=HIF89,TRP482
ncaa_charges=-2,0
ncaa_resnames=HF1,WF1
chg_level=HF/6-31G(d)

# Per-residue torsion bond groups separated by ';':
# HIF89: 3-8 chi1, 8-11 chi2, 6-60 covalent His-FAD link, 22-25 ribityl
# TRP482: 5-6 (CB-CG)
torsionfit=true
torsion_bonds=3-8,8-11,6-60,22-25;5-6

Run. maple NCAA3.inp NCAA3.out, as in Case 1; on the tutorial hardware it takes about 1 h 41 min, and NCAA3.parmfitrun.in resolves the two-residue declarations — ncaa_resids=HIF89,TRP482 with paired charges, exported names, and the ;-separated bond groups.

What happens. MAPLE runs the full Case-1/Case-2 pipeline for each declared residue independently — its own capped conformers, charge fit, template build, and torsion fitting — and the log, NCAA3.out, shows two complete stage blocks, one per selector:

Target: _89:HIF, _482:TRP (protein)
  PDB residue templates: matched=516, backbone_only=1, unmatched=0
    non-standard (matched backbone only): _89:HIF (also note)
    template overrides (renamed): _10:CYM (CYX->CYM), _74:CYM (CYX->CYM)
  PDB target charges: _89:HIF = -2, _482:TRP = 0 (from your input)
  [NCAA] MLIP model preparation + reference optimization ...
  NCAA target selector: HIF89
  residue name: HF1
  ...
  [NCAA] route completed; final summary follows.
  [NCAA] MLIP model preparation + reference optimization ...
  NCAA target selector: TRP482
  residue name: WF1
  ...
  [NCAA] route completed; final summary follows.
  [NCAA] tleap validation ...

Work products are per residue — ncaa/HIF89/ and ncaa/TRP482/, torsionfit/HIF89/ and torsionfit/TRP482/, HF1_maple.prepin/HF1_maple.frcmod and WF1_maple.prepin/WF1_maple.frcmod — but the deployment happens once: one combined NCAA3_ncaa_tleap.in loads both templates and validates them together. The result block reports the last residue, then the route adds a one-line build summary:

Status: completed
Route: NCAA
Target: _482:TRP
Residue name: WF1
  ...
Target charge: 0
Actual charge: 0.00000100
Charge MOL2: NCAA3_work/ncaa/TRP482/NCAA3_capped.mol2

Main products:
  refined prepin: NCAA3_work/WF1_maple.prepin
  refined frcmod: NCAA3_work/WF1_maple.frcmod
  tleap PDB:      NCAA3_work/NCAA3_ncaa_tleap.pdb
  tleap input:    NCAA3_work/NCAA3_ncaa_tleap.in
  ...
  NCAA residues built: _89:HIF -> HF1, _482:TRP -> WF1

Checkpoint

The result block reports Actual charge only for the last residue, so check every residue against its deployed template: the charges in HF1_maple.prepin and WF1_maple.prepin sum to −2.000001 and 0.000001 here, matching ncaa_charges=-2,0 — each residue's atoms form one charge group constrained to its own value. Verify both template pairs exist in the work root and that the combined tleap input loads both (HF1 and WF1). If a selector is not unique in the PDB, the run stops with an error before any QM (quantum-mechanical) work starts; add a chain id to disambiguate. Declaring a standard residue like TRP is legitimate when you deliberately want it rebuilt through the NCAA flow — residues with an $AMBERHOME template normally need no declaration.

Where to Go Next

The deployment is validated for you: the route ran tleap itself and reported Errors: 0, with the charge closure visible as Target charge versus Actual charge in each result block. Take the processed PDB NCAA1_ncaa_tleap.pdb and tleap input NCAA1_ncaa_tleap.in, build the solvated topology from them, and pass it through ParmEd before SHAKE, because the templates carry MAPLE’s reassigned atom types. The manual’s ParmEd note has the reason, and the ChargeFit section has the charge details.

NCAA manual — parameter reference, charge-fitting details, peptide boundary terms, and limits.
ChargeFit, QM reference, and TorsionFit on the ParmFit hub — the stages these routes share, documented once on the hub.
Refinement tutorial and MetalAA tutorial — simple worked examples for the other routes.