acpype

ACPYPE

AnteChamber PYthon Parser interfacE

A tool based in Python to use Antechamber to generate topologies for chemical compounds and to interface with others python applications like CCPN and ARIA.

acpype is pronounced as ace + pipe

Topologies files to be generated so far: CNS/XPLOR, GROMACS, CHARMM and AMBER.

NB: Topologies generated by acpype/Antechamber are based on General Amber Force Field (GAFF) and should be used only with compatible forcefields like AMBER and its variant.

Several flavours of AMBER FF are ported already for GROMACS (see ffamber) as well as to XPLOR/CNS (see xplor-nih) and CHARMM.

This code is released under GNU General Public Licence V3.

See online documentation for more.

NO WARRANTY AT ALL

It was inspired by:

• amb2gmx.pl (Eric Sorin, David Mobley and John Chodera) and depends on Antechamber and OpenBabel

• YASARA Autosmiles (Elmar Krieger)

• topolbuild (Bruce Ray)

• xplo2d (G.J. Kleywegt)

For Non-uniform 1-4 scale factor conversion (e.g. if using GLYCAM06), please cite:

BERNARDI, A., FALLER, R., REITH, D., and KIRSCHNER, K. N. ACPYPE update for nonuniform 1–4 scale factors: Conversion of the GLYCAM06 force field from AMBER to GROMACS. SoftwareX 10 (2019), 100241. Doi: 10.1016/j.softx.2019.100241

For Antechamber, please cite:

1. WANG, J., WANG, W., KOLLMAN, P. A., and CASE, D. A. Automatic atom type and bond type perception in molecular mechanical calculations. Journal of Molecular Graphics and Modelling 25, 2 (2006), 247–260. Doi: 10.1016/j.jmgm.2005.12.005

2. WANG, J., WOLF, R. M., CALDWELL, J. W., KOLLMAN, P. A., and CASE, D. A. Development and testing of a General Amber Force Field. Journal of Computational Chemistry 25, 9 (2004), 1157–1174. Doi: 10.1002/jcc.20035

If you use this code, I am glad if you cite:

SOUSA DA SILVA, A. W. & VRANKEN, W. F. ACPYPE - AnteChamber PYthon Parser interfacE. BMC Research Notes 5 (2012), 367 Doi: 10.1186/1756-0500-5-367

and (optionally)

BATISTA, P. R.; WILTER, A.; DURHAM, E. H. A. B. & PASCUTTI, P. G. Molecular Dynamics Simulations Applied to the Study of Subtypes of HIV-1 Protease. Cell Biochemistry and Biophysics 44 (2006), 395-404. Doi: 10.1385/CBB:44:3:395

Alan Silva, DSc

alanwilter at gmail dot com

How To Use ACPYPE

What ACPYPE does in one command

acpype has two modes, and both are a single command.

Starting from a small molecule — a .mol2, .pdb, .mdl/.mol file, or even a SMILES string — acpype drives the whole AmberTools pipeline for you:

acpype -i molecule.mol2 -b MOL -c bcc -n 0 -a gaff2

That one line does the work of three separate AmberTools runs:

and then converts the result into GROMACS, CNS/XPLOR and CHARMM formats as well, all into a single MOL.acpype/ folder. There is no need to run antechamber, parmchk2 and tleap yourself, or to convert between formats afterwards.

Starting from existing AMBER files — if you already have a prmtop/inpcrd pair from LEaP, acpype converts them to GROMACS without needing AmberTools at all:

acpype -p FFF_AC.prmtop -x FFF_AC.inpcrd

Useful options for the first mode: -c charge method (bcc, abcg2, gas, user — abcg2 is AmberTools' newer method, recommended for GAFF2), -n net charge, -a atom types (gaff2, gaff, amber, amber2), -o which topologies to write (all, gmx, cns, charmm), and -r the antechamber atom/bond type prediction index if the default perception struggles with your molecule. Run acpype -h for the full list and for what every output file is.

-a amber and -a amber2 type the molecule with the AMBER protein force field and fall back to GAFF (or GAFF2) only for parameters AMBER does not have. The protein force field is ff14SB by default, or ff99SB with -F/--protein_ff. ff14SB keys its backbone and side-chain torsions on atom types antechamber never emits (CX, CO, 2C, 3C, C8), so ACPYPE applies them itself after antechamber, from AMBER's own residue templates; atoms that match no amino-acid template keep antechamber's types. parmchk2 is then run twice, against AMBER alone and against AMBER plus GAFF, and GAFF values are kept only where AMBER has a genuine gap, because parmchk2 would otherwise replace AMBER's backbone torsions with GAFF analogues it scores as equivalent. This is validated by scripts/check_acpype.py: over the 22 standard tripeptides the bonded energies agree with GROMACS' own amber14sb.ff to within 0.05% for 21 of them and to 1% for tyrosine, where antechamber types the ring CZ differently, an exception on record in NOTE.txt since 2010.

amb2gmx converts ff19SB systems, CMAP backbone correction included. The prmtop's CMAP grids become [ cmaptypes ] keyed the way GROMACS' own amber19sb.ff port keys them, C-* N-ALA XC-ALA C-ALA N-*, which grompp matches on atom type and residue name; that syntax needs a GROMACS recent enough to ship that port (verified with 2026.3). Four-site waters such as OPC and TIP4P-Ew are written from the prmtop's own geometry and charges, settles plus a virtual site, rather than from a fixed template. On an ALA tripeptide in vacuum the CMAP energy matches pdb2gmx -ff amber19sb to five decimals on identical coordinates, and the same peptide in a box of OPC with ions reproduces pdb2gmx -water opc's total potential to 0.001%. The GROMACS 4 flavour (-z) cannot carry CMAP and is refused for such systems; the CNS and CHARMM writers warn that they drop it.

In amb2gmx mode, -S/--split_molecules writes one [ moleculetype ] per molecule that AMBER identified, instead of merging the whole solute into one. Converting a tleap system built as complex = combine { target ligand } then gives a separate block for the target and for the ligand, each usable on its own in [ molecules ]. The molecules come from the prmtop's ATOMS_PER_MOLECULE, so they match AMBER's own bonded connectivity; a prmtop with no box does not carry that record and is left as a single moleculetype. Charges are rounded per molecule when splitting, because AMBER's stored precision leaves an individual molecule off by ~1e-3 even when the system as a whole is exactly integral. That does alter the charges slightly -- a Zn2+ AMBER stored as +2.002 becomes exactly +2.000 -- so a single-point energy can differ from an unsplit run by a few parts per million.

CHARMM output needs charmmgen, which modern AmberTools dropped; ACPYPE keeps an old build and the wheels and the Docker image bundle it. An installation without that bundle, a conda one for instance, has none, and antechamber looks for it beside itself at $AMBERHOME/bin/charmmgen, so a copy merely on PATH is never used. ACPYPE now says so instead of announcing CHARMM files and writing none, and acpype --fetch-charmmgen downloads the right build for the platform, checksummed and pinned to a release tag, and installs it there. A topology run never reaches the network by itself. There are builds for macOS (universal, Intel and Apple Silicon) and Linux x86_64; elsewhere the Docker image ships a full AmberTools.

A note on -q, the quantum engine behind bcc and abcg2 charges: only sqm is bundled with ACPYPE. -q mopac and -q divcon are still accepted, but they need a full external AmberTools with AMBERHOME pointing at it, because antechamber drives them through its own mopac.sh/divcon wrapper scripts — and neither the AmberTools bundled here nor conda-forge's ambertools package ships those. For an open-shell system that sqm cannot converge, computing the charges elsewhere and reading them back from a mol2 with -c user is usually the easier route.

Introduction

We now have an up-to-date web service at Bio2Byte (but it does not have the amb2gmx functionality).

To run acpype, locally, with its all functionalities, you need ANTECHAMBER from package AmberTools and Open Babel if your input files are of PDB format.

However, if one wants acpype just to emulate amb2gmx.pl, one needs nothing at all but Python.

There are several ways of obtaining acpype:

1. Via CONDA:

   (It should be wholesome, fully functional, all batteries included)

   conda install -c conda-forge acpype
   

2. Via PyPI:

   pip install acpype
   

   acpype ships the AmberTools binaries it needs (currently AmberTools 26) as platform-specific wheels:

   Platform	Wheel	Batteries included
   Linux x86_64, glibc >= 2.35 (Ubuntu 22.04+, Debian 12+)	manylinux_2_35_x86_64	yes
   macOS Apple Silicon, macOS 11+	macosx_11_0_arm64	yes
   anything else (Intel macOS, Linux aarch64, Windows)	source distribution	no -- supply your own AmberTools

   On a platform with no wheel, pip falls back to the source distribution, which is the same ACPYPE without the bundled binaries. It works fine against an AmberTools you install yourself; if none is found, ACPYPE says so and points you at conda.

   On those two platforms pip install acpype is a complete solution. A handful of common system libraries are deliberately left to the host on Linux:

   # Ubuntu 22.04 / 24.04, Debian 12+ -- needed by the bundled AmberTools
   apt-get install -y libgfortran5 libstdc++6 libgomp1 libblas3 liblapack3 libcurl4
   
   # needed by the openbabel wheel that `pip install acpype` pulls in
   apt-get install -y libxrender1 libxext6 libsm6
   

   Anywhere else, install AmberTools yourself and, optionally but highly recommended, OpenBabel:

   # You can use conda to get the needed 3rd parties for example
   conda create -n acpype --channel conda-forge ambertools openbabel
   
   pip install acpype
   
   # or if you feel daring
   
   pip install git+https://github.com/alanwilter/acpype.git
   

   NB: If using OpenBabel python module, it's really CRITICAL to have it installed in the same Python environment of acpype.

3. By downloading it via git:

   (Make sure you have AmberTools and, optionally but highly recommended, OpenBabel)

   # You can use conda to get the needed 3rd parties for example
   conda create -n acpype --channel conda-forge ambertools openbabel
   
   # Or for Ubuntu 22.04 / 24.04:
   apt-get install -y openbabel python3-openbabel libgfortran5 libblas3 liblapack3
   
   git clone https://github.com/alanwilter/acpype.git
   

   NB: Using this mode, CHARMM topology files will not be generated.

4. Via Docker:

   (It should be wholesome, fully functional, all batteries included)

   If you have Docker installed, you can run acpype_docker.sh by:

   NOTE: first time may take some time as it pulls the acpype docker image.

   On Linux / macOS:

   ln -fsv "$PWD/acpype_docker.sh" /usr/local/bin/acpype_docker
   

   On Windows: Using Command Prompt:

   In the directory where the acpype_docker.bat file is found:

   setx /M path "%path%;%cd%"
   

   Commands:

   acpype_docker -i CCCC
   
   acpype_docker -i tests/DDD.pdb -c gas
   

NB: what you get depends on how you install:

• Via pip and via docker you get a stripped AmberTools 26 embedded -- only the binaries and libraries acpype needs -- so CHARMM topologies work out of the box. That applies to the Linux x86_64 and macOS Apple Silicon wheels (see the table above) and to the docker image. Elsewhere pip installs the source distribution, which carries no binaries and needs an AmberTools of your own.

• Via conda the build comes from the conda-forge feedstock, which lags this repository and so still carries the older embedded AmberTools. It also pulls ambertools and openbabel as conda packages, and it is that antechamber which ends up on your PATH.

• OpenBabel is 3.1.1 via conda/docker, and 3.1.0 via pip (from the openbabel-wheel dependency).

• charmmgen is not part of modern AmberTools, and conda-forge's ambertools does not ship it, so acpype builds its own from the source still maintained in AmberClassic: universal arm64 + x86_64 on macOS, x86_64 on Linux. See scripts/build_charmmgen.sh. If CHARMM output fails because the antechamber on your PATH cannot find it, copy the bundled one next to that antechamber:

  sys=$(python3 -c "import sys; print('macos' if sys.platform == 'darwin' else 'linux')")
  acp=$(python3 -c "import acpype, os; print(os.path.dirname(acpype.__file__))")
  cp "${acp}/amber_${sys}/bin/charmmgen" "$(dirname "$(which antechamber)")"
  

To Test, if doing via git

At folder acpype/, type:

./run_acpype.py -i tests/FFF.pdb

It'll create a folder called FFF.acpype, and inside it one may find topology files for GROMACS and CNS/XPLOR.

Or using a molecule in SMILES notation:

./run_acpype.py -i CCCC # smiles for C4H6 1,3-Butadiene compound

It'll create a folder called smiles_molecule.acpype.

To get help and more information, type:

./run_acpype.py -h

To Install

At folder acpype/, type:

  ln -fsv "$PWD/run_acpype.py" /usr/local/bin/acpype

Then re-login or start another shell session.

If via conda or pip, acpype should be in your $PATH.

To Verify with GMX

GROMACS < v.5.0

cd FFF.acpype/
grompp -c FFF_GMX.gro -p FFF_GMX.top -f em.mdp -o em.tpr
mdrun -v -deffnm em
# And if you have VMD
vmd em.gro em.trr

GROMACS > v.5.0

cd FFF.acpype/
gmx grompp -c FFF_GMX.gro -p FFF_GMX.top -f em.mdp -o em.tpr
gmx mdrun -v -deffnm em
# And if you have VMD
vmd em.gro em.trr

For MD, do

GROMACS < v.5.0

grompp -c em.gro -p FFF_GMX.top -f md.mdp -o md.tpr
mdrun -v -deffnm md
vmd md.gro md.trr

GROMACS > v.5.0

gmx grompp -c em.gro -p FFF_GMX.top -f md.mdp -o md.tpr
gmx mdrun -v -deffnm md
vmd md.gro md.trr

To Emulate amb2gmx.pl

For any given prmtop and inpcrd files (outputs from AMBER LEaP), type:

acpype -p FFF_AC.prmtop -x FFF_AC.inpcrd

The output files FFF_GMX.gro and FFF_GMX.top will be generated inside folder FFF_GMX.amb2gmx

To Verify with CNS/XPLOR

At folder FFF.acpype, type:

cns < FFF_CNS.inp

To Verify with NAMD

• see TutorialNAMD