Using parmed

This page details using the command-line version of ParmEd, which is the primary front-end program using the parmed and parmed.tools packages to provide a set of Actions by which you can modify a system topology and parameters (it currently only works for Amber topology files, although support for the entire Structure hierarchy is planned).

There are two ways in which ParmEd can be run—in batch reading from an input file or script, and with an interactive interpreter. A script can either be given to parmed on the command-line, or fed via pipes through standard input. You can provide an input file using the -i/--input flag.

Command syntax

All actions should be specified on the parmed command-line in the following format:

ActionName arg1 arg2 arg3 ... argN [parm <idx|name>]

Arguments should be whitespace-delimited, the ActionName is case-insensitive, and every action (if it uses a parm object) can be applied to a specific parameter-topology instance that has been loaded.

Note that in many Actions, you need to select a subset of the atoms upon which to perform the action. The way in which these atom selections are specified is using the Amber mask syntax described in the section Atom Selection Masks below.

Available commands

The following Action commands are available in ParmEd. The information here is available via the help_ command in the parmed interpreter.

add12_6_4

add12_6_4 [<divalent ion mask>] [c4file <C4 Param. File> | watermodel <water model>] [polfile <Pol. Param File> [tunfactor <tunfactor>]
Adds the LENNARD_JONES_CCOEF term for the new divalent metal ion 12-6-4 Lennard-Jones potential term. If provided, the mask will allow you to specify which ions are divalent. The C4 parameter between the metal ion and water can either be taken from Ref. [1] for the requested [watermodel] (TIP3P, TIP4PEW, or SPCE) or provided in the file specified by the c4file keyword. The polarizabilities must be present in the the polfile file. The chemical symbol of the element will be used to determine the atom type. Parameters are expected in a file with 2 columns:
<atom type> <parameter>

All defaults come from Ref. [1] [2] and [3]

[1] Pengfei Li and Kenneth M. Merz, J. Chem. Theory Comput., 2014, 10,
289-297
[2] Pengfei Li, Lin F. Song and Kenneth M. Merz, J. Phys. Chem. B, 2015,
119, 883-895
[3] Pengfei Li, Lin F. Song and Kenneth M. Merz, J. Chem. Theory Comput.,
2015, 11, 1645-1657.

addAtomicNumber

addAtomicNumber

Adds the atomic number of each atom to a new section titled “ATOMIC_NUMBER” in the topology file. Elements are identified by the atomic mass found in the MASS section of the topology files. Elements are matched by picking the element whose average atomic mass in the periodic table is closest to each atom, which should work appropriately for all isotopes of all atoms, except possibly Tritium

addDihedral

addDihedral <mask1> <mask2> <mask3> <mask4> <phi_k> <per> <phase> [<scee>] [<scnb>] [type <type>]

Adds a dihedral between mask1, mask2, mask3, and mask4. Each mask must specify the same number of atoms, and the dihedral is defined around the bond between atoms in mask 2 and 3. If each mask selects 2 atoms, for instance, a dihedral will be placed around atom1 in mask 1, atom1 in mask 2, atom1 in mask 3, and atom1 in mask 4. A second dihedral will be placed around atom2 in mask 1, atom2 in mask 2, atom2 in mask 3, and atom2 in mask4.

  • <mask1> : Selection of one of the end-atoms for each dihedral
  • <mask2> : Selection of the middle atom bonded to <mask1> and <mask3> in each dihedral
  • <mask3> : Selection of the other middle atom bonded to <mask2> and <mask4>
  • <mask4> : Selection of the other end-atom in each dihedral
  • <phi_k> : Force constant in kcal/mol
  • <per> : Periodicity
  • <phase> : Torsion phase shift
  • <scnb> : 1-4 Lennard-Jones scaling constant (default 2.0)
  • <scee> : 1-4 electrostatic scaling constant (default 1.2)
  • <type> : Type of dihedral, either “improper” or “normal”. Default is “normal”

addExclusions

addExclusions <mask1> <mask2>

Allows you to add arbitrary exclusions to the exclusion list. Every atom in <mask2> is added to the exclusion list for each atom in <mask1> so that non-bonded interactions between those atom pairs will not be computed. NOTE that this ONLY applies to direct-space (short-range) non-bonded potentials. For PME simulations, long-range electrostatics between these atom pairs are still computed (in different unit cells).

addLJType

addLJType <mask> [radius <new_radius>] [epsilon <new_epsilon>] [radius_14 <new_radius14>] [epsilon_14 <new_epsilon14>]

Turns given mask into a new LJ atom type. It uses the radius and Rmin from the first atom type in <mask> if new_radius or new_epsilon aren’t provided

addPDB

addPDB <filename> [elem] [strict] [allicodes]

Adds PDB information to new flags in an Amber topology file to enable analyses based on the original residue information in the PDB file, <filename> It adds the flags:

Residue Properties

  • RESIDUE_CHAINID: The chain ID of each residue (* if LEaP added it)
  • RESIDUE_ICODE: Insertion code, if it exists
  • RESIDUE_NUMBER: Original residue serial number in the PDB

Atom Properties

  • ATOM_ELEMENT: Atomic element (redundant now, not printed by default)
  • ATOM_OCCUPANCY: The occupancy of each atom
  • ATOM_BFACTOR: The temperature factor of each atom
  • ATOM_NUMBER: The original atom serial number in the PDB

The ‘strict’ keyword turns residue mismatches (NOT solvent) into errors The ‘elem’ keyword will force printing of the element names. The ‘allicodes’ keyword forces insertion codes to be printed, even if every one will be blank (so that parsers can count on that section existing).

Residues not in the PDB will be assigned a CHAINID of ‘*’ and RESIDUE_NUMBER of 0. Any occupancy or temperature (B) factor that is not present in the input PDB file is assigned a number of 0

Historical info:
This action is based on, and reproduces the key results of, the historical ‘add_pdb’ program. It is a bit more flexible, though.

cd

cd <directory>

Changes to a new directory like UNIX ‘cd’

chamber

chamber -top <RTF> -param <PAR> [-str <STR>] -psf <PSF> [-crd <CRD>] [-nocmap] [-box a,b,c[,alpha,beta,gamma]|bounding] [-radii <radiusset>] [nosettle]

This action will read CHARMM parameter, topology (RTF), and stream (STR) files and apply those parameters to a structure defined in a CHARMM PSF (protein structure file). XPLOR, CHARMM, and VMD-generated PSF files are all supported. You may specify -top, -param, and -str as many times as you want to provide multiple parameter files. All topology files are read first (in the order they are specified), followed by all parameter files, and finally all stream files are read in. Topology files are only necessary if the parameter files do not define the atom types (newer CHARMM force fields define atom types directly in the parameter file. Environment variables and shell wild-cards (* and ?), as well as the home shortcut character ~ are properly expanded when looking for files.

Options

  • -top CHARMM topology, or Residue Topology File (RTF) file
  • -param CHARMM parameter file
  • -str CHARMM stream file. Only RTF and parameter sections read
  • -toppar CHARMM topology, parameter, and/or stream file(s). File type is detected from extension (or in the case of .inp files, the presence of ‘top’, ‘par’ in the name)
  • -psf CHARMM PSF file
  • -crd Coordinate file (PDB, CHARMM CRD, Amber restart, etc.)
  • -nocmap Do not use any CMAP parameters
  • -box Box dimensions. If no angles are defined, they are assumed to be 90 degrees (orthorhombic box). Alternatively, you can use the word ‘bounding’ to define a box that encloses the centers of all atoms.
  • -radii Implicit solvent solvation radii. <radiusset> can be amber6, bondi, mbondi, mbondi2, mbondi3 Same effect as the changeRadii command. Default is mbondi.
  • nosettle This avoids changing the names of the water residue and oxygen atoms from TIP3 and OH2 to WAT and O

If the PDB file has a CRYST1 record, the box information will be set from there. Any box info given on the command-line will override the box found in the crd file.

change

change <property> <mask> <new_value> [quiet]

Changes the property of given atoms to a new value. <property> can be CHARGE, MASS, RADII, SCREEN, ATOM_NAME, ATOM_TYPE, ATOM_TYPE_INDEX, or ATOMIC_NUMBER (note, changing elements with this command will NOT change their assignment for SHAKE!).

If given, the [quiet] keyword will prevent ParmEd from printing out a summary with every property changed for every atom that was changed useful for suppressing overwhelming output if you are zeroing every charge, for instance)

changeLJ14Pair

changeLJ14Pair <mask1> <mask2> <Rmin> <epsilon>

Changes a particular 1-4 Lennard Jones pair based on a given (pre-combined) epsilon/Rmin. Only valid for CHAMBER prmtops

changeLJPair

changeLJPair <mask1> <mask2> <Rmin> <epsilon>

Changes a particular Lennard Jones pair based on a given (pre-combined) epsilon/Rmin

changeLJSingleType

changeLJSingleType <mask> <radius> <depth>

Allows you to change the radius/well depth of a single LJ type specified by <mask> Note, this may change more than the atoms selected in just the mask! To find out what else will be changed, look at the output of printLJTypes.

Use addLJType to change the Lennard-Jones parameters on a set of specific atoms.

  • <mask> : The selection of atoms to change the LJ type for. All atoms selected must have the same LJ type
  • <radius> : Rmin/2 (van der Waals radius of the new type)
  • <depth> : Well-depth (a.k.a., epsilon)

changeProtState

changeProtState <mask> <state #>

Changes the protonation state of a given titratable residue that can be treated via constant pH MD in Amber.

changeRadii

changeRadii <radii_set>
Changes intrinsic GB radii to the specified set: Allowed values are
amber6, bondi, mbondi, mbondi2, mbondi3

checkValidity

checkValidity

Basic checks for prmtop validity.

defineSolvent

defineSolvent <residue_list>

Allows you to change what parmed will consider to be “solvent”. <residue list> must be a comma-separated set of residue names with no spaces between them.

deleteBond

deleteBond <mask1> <mask2>

This action deletes any bonds that occur between the atoms in two masks.

  • <mask1> : Amber mask defining one of the atoms in a bond
  • <mask2> : Amber mask defining the other atom in the bond
  • [verbose] : Print out every bond that is deleted as well as the number of other valence terms that were eliminated.

All bonds will be matched in which one atom comes from <mask1> and the other atom comes from <mask2> This action will also delete any other valence term (like angles and dihedrals) that would get severed by the deletion of one of the bonds.

deleteDihedral

deleteDihedral <mask1> <mask2> <mask3> <mask4>

Deletes the dihedral around <mask2> and <mask3> in which the end-groups are <mask1> and <mask4> For multi-term dihedrals, it removes each term.

deletePDB

deletePDB

This action deletes the flags added by addPDB if they are present.

energy

energy [cutoff <cut>] [[igb <IGB>] [saltcon <conc>] | [Ewald]] [nodisper] [omm] [applayer] [platform <platform>] [precision <precision model>] [decompose]

This action will compute a single-point energy for the loaded structure (you must use ‘loadRestart’ prior to this command to load coordinates). The following options and keywords are supported:

Options

  • cutoff <cut> : The size of the non-bonded cutoff, in Angstroms. Default 8 A for periodic systems or infinite for nonperiodic systems

For systems with no periodic box information

  • igb <IGB> : An integer corresponding to the desired GB model. May be 1, 2, 5, 7, or 8 as described by the sander and pmemd manual. Default 5.
  • saltcon <conc> : The salt concentration, in mol/L, modeled by a Debye screening parameter. Default 0.0

For periodic systems

  • Ewald : Use an Ewald sum to compute long-range electrostatics instead of PME
  • nodisper : Do not use a long-range vdW dispersion correction

OpenMM-specific options

  • omm : If present, this keyword will instruct ParmEd to use OpenMM to compute the energies (and optionally forces) using OpenMM instead of sander.
  • platform <platform> : OpenMM compute platform to use. Options are CUDA, OpenCL, Reference, and CPU. Consult the OpenMM manual for details (only used if ‘omm’ is provided)
  • precision <precision model> : Precision model to use. Options are single, double, and mixed. Reference platform is always double and CPU platform is always single. Mixed (default) uses single precision for calculations and double for accumulation (only used if ‘omm’ is provided)
  • decompose : Print bond, angle, dihedral, and nonbonded energies separately
  • applayer : Use OpenMM’s class to compute the energy

Examples

# Using AMBER import parmed as pmd parm = pmd.load_file(‘prmtop’, xyz=’rst7’) pmd.tools.energy(parm, ‘igb 8’).execute()

# Using Openmm pmd.tools.energy(parm, ‘igb 5 omm’).execute()

gromber

gromber <top_file> [<coord_file>] [define <DEFINE[=VAR]>] [topdir <directory>] [radii <radiusset>]

Load a Gromacs topology file with parameters as an Amber-formatted system. Note, if your Gromacs topology file requires any include topology files, you will need to have Gromacs installed for this to work.

  • <top_file>: The Gromacs topology file to load
  • <coord_file>: The coordinate file to load into the system. Can be any recognized format (GRO, PDB, mmCIF, inpcrd, etc.)
  • define <DEFINE[=VAR]>: Preprocessor defines that control the processing of the Gromacs topology file.
  • topdir <directory>: The directory containing all Gromacs include topology files. This is only necessary if Gromacs is not installed in a location that ParmEd can find.
  • radii <radiusset>: The GB radius set to use. Can be ‘mbondi’, ‘bondi’, ‘mbondi2’, or ‘amber6’. Default is mbondi

Gromacs topology files do not store the unit cell information. Therefore, in order to make sure that unit cell information is properly assigned to the resulting system, the provided <coord_file> should contain unit cell information (e.g., GRO, PDB, PDBx/mmCIF, and inpcrd files can all store box information).

ParmEd will try to locate the Gromacs topology directory using either the GMXDATA or GMXBIN environment variables (which should point to the $PREFIX/share/gromacs or $PREFIX/bin directories, respectively, where $PREFIX is the install prefix). If neither is set, the topology directory is located relative to the location of the gmx (Gromacs 5+) or pdb2gmx (Gromacs 4 or older) in the user’s PATH. If none of the above is true, the default installation location (/usr/local/gromacs/share/gromacs/top) is used. Any provided topdir will override default choices (but only for this particular command – future gromber actions will use the default location again).

You can provide as many defines as you wish, and the ordering you specify them is preserved. The default value assigned to each define is “1”. To provide multiple defines, use the define keyword multiple times, for example:

define MYVAR=something define MYVAR2=something_else ...

HMassRepartition

HMassRepartition [<mass>] [dowater]

This action implements hydrogen mass repartitioning in the system by changing the mass of each hydrogen to the desired value (the default new hydrogen mass is 3.024 daltons) and adjusting the mass of the atom to which it is bonded by the amount required to leave the total mass unchanged. By default, water hydrogen masses are unchanged (the SETTLE algorithm for implementing constraints on water molecules is analytical). Water masses can be repartitioned as well with the ‘dowater’ keyword.

interpolate

interpolate <nparm> [parm2 <other_parm>] [eleconly] [prefix <prefix>] [startnum <num>]

Interpolates between two topology files (VDW and electrostatic terms only). If [eleconly] is present, only the charges will be interpolated. <nparm> is the number of ‘interpolated’ topology files you want (in addition to the two end-points). The second prmtop must be specified if there are more than 2 parms currently loaded in the ParmEd parm list. startnum has no effect on the generated prmtops, but it can be used to control the names of the outputted topology files.

  • <nparm> : Number of topology files that will be generated
  • <other_parm> : The other parm object used in interpolation if more than 2 parms are present (first parm is active one)
  • eleconly : Only do charge interpolation
  • <prefix> : Generated parm objects will be written as <prefix>.#, where # starts from <num> and increases by 1
  • <num> : Starting number for file names (see <prefix> above)

listParms

listParms

Lists all of the loaded topology files

lmod

lmod

Adjusts Lennard Jones parameters to work with the LMOD code in Amber (changes LJ A coefficients that are 0 to 1000).

loadCoordinates

loadCoordinates <filename>

Reads a coordinate file and loads the first set of coordinates found into the active structure. File type is auto-detected. Supported file formats include:

  • Amber restart file
  • Amber NetCDF restart file
  • CHARMM coordinate file
  • CHARMM restart file
  • Amber mdcrd trajectory
  • Amber NetCDF trajectory
  • PDB file
  • PDBx/mmCIF file
  • Gromacs GRO file
  • Mol2 file

loadRestrt

loadRestrt <restrt_filename>

Loads a restart file so we have coordinates. Necessary for distance-based mask criteria and writeOFF

ls

ls [Unix ls options]

Lists directory contents. Like UNIX ‘ls’

minimize

minimize [cutoff <cut>] [[igb <IGB>] [saltcon <conc>]] [[restrain <mask>] [weight <k>]] [norun] [script <script_file.py>] [platform <platform>] [precision <precision model>] [tol <tolerance>] [maxcyc <cycles>] [omm]

This action takes a structure and minimizes the energy using either scipy.optimize.minimize (with BFGS) and the sander API or OpenMM. Following this action, the coordinates stored in the topology will be the minimized structure

General Options

  • omm Use OpenMM instead of sander+scipy to minimize
  • cutoff <cutoff> Nonbonded cutoff in Angstroms
  • tol <tolerance> The largest energy difference between successive steps in the minimization allow the minimization to stop (Default 0.001)
  • maxcyc <cycles> The maximum number of minimization cycles permitted. No limit by default (minimization stops when tolerance is satisfied)

Implicit Solvent options

  • igb <IGB> GB model to use (0=No GB, 1,2,5,7,8 correspond to Amber models)
  • saltcon <conc> Salt concentration for GB in Molarity

OpenMM-specific options

  • restrain <mask> Selection of atoms to restrain
  • weight <k> Weight of positional restraints (kcal/mol/A^2)
  • norun Do not run the calculation
  • script <script> Name of the Python script to write to run this calculation
  • platform <platform> Which compute platform to use. Options are CUDA, OpenCL, CPU, and Reference. Consult OpenMM docs for more information
  • precision <precision_model> Which precision model to use. Can be “single”, “double”, or “mixed”, and only has an effect on the CUDA and OpenCL platforms.

The implicit solvent options will be ignored for systems with periodic boundary conditions. The precision option will be ignored for platforms that do not support user-specified precision. The platform, precision, and script arguments will be ignored unless omm is specified.

netCharge

netCharge [<mask>]

Prints the total charge of all of the atoms given by the mask. Defaults to all atoms

OpenMM

OpenMM [-p <parm>|<parm index>] [sander/pmemd options] [-platform <platform>] [-precision <precision model>] [dcd] [progress] [script <script_file.py>] [norun]

This class will read a sander/pmemd input file and run an equivalent simulation using the OpenMM Python API. It uses a topology file that has been defined (and/or modified) here. The command-line flags are identical to those used for sander and pmemd (described in the Amber manual). You can additionally specify a computational platform available through OpenMM such as CUDA, OpenCL, Reference, and CPU.

The default prmtop will be the ‘active’ parm. The prmtop can be changed using either the ‘parm’ keyword or the ‘-p’ flag, but it must resolve to one of the stored topology files. Any parm given with the ‘-p’ flag has precedence. If present, the ‘dcd’ keyword triggers writting DCD-formatted trajectory files instead of NetCDF when ioutfm=1. The DCD trajectory writing offers binary trajectory support without requiring a NetCDF-Python library.

The ‘progress’ keyword triggers printing of ParmEd’s progress in setting up and starting the calculation.

The ‘script’ keyword provides a file to write an OpenMM script that performs the same calculation requested by this ParmEd command. The ‘norun’ command will prevent anything from actually being run and can only be used when a script file is provided.

outCIF

outCIF <file> [norenumber] [charmm] [anisou]

Write a PDBx/mmCIF file from the currently active system to <file>

  • <file>: The PDBx/mmCIF file to write
  • [norenumber]: Use the original atom and residue numbering if available
  • [anisou]: Write anisotropic B-factors if available

outparm

outparm <prmtop_name> [<inpcrd_name>] [netcdf]

Prints a new prmtop like parmout, but keeps its place in the action stack so several can be written out in 1 parmed session

outPDB

outPDB <file> [norenumber] [charmm] [anisou]

Write a PDB file from the currently active system to <file>

  • <file>: The PDB file to write
  • [norenumber]: Use the original atom and residue numbering if available
  • [charmm]: Put the SEGID, if available, in columns 72 to 76
  • [anisou]: Write anisotropic B-factors if available

parm

parm <filename> [<filename> [<filename> ...]] || parm copy <filename>|<index> || parm select <filename>|<index>

Either adds a new parm to the list of available parms to edit in ParmEd, or it sets a new ‘active’ parm to edit by default with new commands

parmout

parmout <prmtop_name> [<inpcrd_name>] [netcdf]

Final prmtop written after all actions are complete

printAngles

printAngles [<mask> [<mask> [<mask>] ] ]

Prints all of the angles (with their details) for the given atoms in the mask. If a second mask is given, only atoms whose central atom is in the second mask and another atom is in the first mask is printed. If a third mask is given, the central atom must be in the second mask and the other two atoms must appear in the first and third masks (in any order).

If coordinates and parameter types are present, the value of the angle (in degrees) and its energy (in kcal/mol) are reported for each printed angle.

printBonds

printBonds [<mask> [<mask>] ]

Prints all of the bonds (with their details) for the given atoms in the mask. If a second mask is given, only bonds in which one atom appears in each list will be printed. If coordinates and parameter types are present, also print the actual distance (in Angstroms) and energy (in kcal/mol) for each printed bond.

printDetails

printDetails <mask>

Returns information about all atoms in a given mask

printDihedrals

printDihedrals [<mask> [<mask> [<mask> [<mask>] ] ] ]

Prints all of the dihedrals (with their details) for the given atoms in the mask. If multiple masks are given, only dihedrals that have one atom in each mask are printed. Ordering is important here, so the first atom must be in the first mask, the second atom in the second, etc. The order can be precisely reversed, but no other ordering is recognized.

If coordinates and parameter types are present, the value of the torsion angle (in degrees) and the energy of each dihedral (in kcal/mol) are reported for each printed dihedral.

printFlags

printFlags

Prints all %FLAGs found in the topology file

printInfo

printInfo <flag>

Prints all prmtop data corresponding to the given %FLAG

printLJMatrix

printLJMatrix <mask>|<index>

This function prints out how every atom type interacts with the atom type(s) in <mask> The atom types are printed as all type names that have at least one atom with the Lennard Jones index given in square brackets at the end. Alternatively, you can request a particular atom type index

printLJTypes

printLJTypes [<mask>|<type idx>]

Prints the Lennard Jones type index for the given atom mask or, if no value is given, the LJ type index for each atom.

printPointers

printPointers

Prints a list of all the POINTERS and their values

scale

scale <FLAG> <factor>

Multiplies all values in a particular section of an Amber prmtop by a scalar factor

scee

scee <scee_value>

Sets the 1-4 EEL scaling factor in the prmtop

scnb

scnb <scnb_value>

Sets the 1-4 VDW scaling factor in the prmtop

setAngle

setAngle <mask1> <mask2> <mask3> <k> <THETeq>

Changes (or adds a non-existent) angle in the topology file. Each mask must select the same number of atoms, and an angle will be placed between the atoms in mask1, mask2, and mask3 (one angle between atom1 from mask1, atom1 from mask2, and atom1 from mask3, another angle between atom2 from mask1, atom2 from mask2, and atom2 from mask3, etc.)

  • <mask1> : The selection of one of the end-atoms in each angle
  • <mask2> : The selection of central atoms in each angle
  • <mask3> : The selection of other end-atoms in each angle
  • <k> : Force constant in kcal/mol/radians^2 in energy expression k(THET - THETeq)^2
  • <THETeq> : Equilibrium angle (in degrees)

setBond

setBond <mask1> <mask2> <k> <Req>

Changes (or adds a non-existent) bond in the topology file. Each mask must select the same number of atoms, and a bond will be placed between the atoms in mask1 and mask2 (one bond between atom1 from mask1 and atom1 from mask2 and another bond between atom2 from mask1 and atom2 from mask2, etc.)

  • <mask1> : Selection of first atoms in each bond
  • <mask2> : Selection of second atoms in each bond
  • <k> : Force constant (kcal/mol/A^2) in energy expression k(R-Req)^2
  • <Req> : Equilibrium distance (A)

setMolecules

setMolecules [solute_ions True|False]

Determines the molecularity of the system based on the bonding network and correctly determines the SOLVENT_POINTERS and ATOMS_PER_MOLECULE sections of the topology file. It will consider the ions to be part of the solute if True is passed or not if False is passed. Defaults to True.

setOverwrite

setOverwrite [True|False]

Necessary to overwrite original topology file name.

source

source <file>

Sources a file with a list of parmed commands

strip

strip <mask> [nobox]

Deletes the atoms specified by <mask> from the topology file and rebuilds the topology file according to the parameters that remain. If nobox is provided, the unit cell information is discarded (useful when stripping solvent to run an aperiodic implicit solvent calculation).

summary

summary

Prints out a summary of prmtop contents

tiMerge

tiMerge <mol1mask> <mol2mask> <scmask1> <scmask2> [<scmask1N>] [<scmask2N>] [tol <tol>]

Merges molecules removing redundant bonding terms. Input amber masks corresponding to molecules 1/2 <mol1mask>/<mol2mask> and the soft core atoms in each molecule as <scmask1>/<scmask2> The input topology can be created using leap, with the two molecules to be merged adjacent to each other in residue number. This improves the efficiency for pmemd TI when only part of a molecule is being perturbed.

<scmask1/2N> are for softcore molecules that are not going to be merged. These options will just add these atoms to the timask output, correcting for any changes in atom number.

This can also be used for non-softcore simulations, where <scmask1>/<scmask2> represent the perturbed atoms. The output will give the scmask1/scmask2 flags, which can just be ignored.

<tol> is the tolerence to use when matching coordinates (default 0.01). This is used when the atoms in molecules 1/2 are not in the same order and for checking the input coordinates.

writeCoordinates

writeCoordinates <filename> [netcdftraj | netcdf | pdb | cif | restart | mdcrd | mol2]

Writes the coordinates of the active structure to a coordinate file. The format of the file is detected from filename extension, with the following extensions being recognized:

  • .nc: Amber NetCDF trajectory with a single frame
  • .ncrst: Amber NetCDF restart file
  • .pdb: PDB file
  • .cif: PDBx/mmCIF file
  • .rst7, .restrt, .inpcrd: Amber restart file
  • .mdcrd: Amber mdcrd file
  • .mol2: Sybyl Mol2 file
  • Default is Amber restart file

Alternatively, the following keywords can be used to override the filename extension:

  • netcdftraj: Amber NetCDF trajectory with a single frame
  • netcdf: Amber NetCDF restart file
  • pdb: PDB file
  • cif: PDBx/mmCIF file
  • restart: Amber restart/inpcrd file
  • mdcrd: Amber mdcrd file
  • mol2: Sybyl mol2 file

Note, NetCDF files require scipy or netCDF4 to be installed.

writeFrcmod

writeFrcmod <frcmod_name>

Writes an frcmod file from all of the parameters in the topology file.

writeOFF

writeOFF <OFF_filename>

Writes an Amber OFF Library with all of the residues found in the topology

Atom Selection Masks

Atoms within a system are selected according to the Amber mask specification. The selection syntax is described in detail in the Amber user’s manual, with numerous examples in the cpptraj and ambmask sections. I will include a brief primer here for reference.

Residue Selections

The : character is used to select specific residues by name and/or number. The residues you wish to select may be a comma-separated list of numbers, number ranges, names, or a mixed list of both. Note that the residue number selections apply to a numbering scheme in which the first residue is residue 1 and the numbers increment sequentially from there (i.e., any original numbering in the starting file is ignored in standard mask selections). Examples are shown below:

:1-5,10,ALA,TYR
:101
:ASP,GLU,HIS,LYS,TYR

The first example selects all atoms in residues 1 through 5, residue 10, and any residues with the names “ALA” or “TYR” in the system. The second example selects only residue number 101. The final mask selects all residues with names ASP, GLU, HIS, LYS, or TYR.

Atom selections

The @ character is used to select specific atoms by name and/or number. The atoms you wish to select may be a comma-separated list of numbers, number ranges, names, or a mixed list of both. Like the residue selection above, atoms are numbered sequentially starting from 1. Examples are shown below:

@1-5,10,CA,CB
@101
@CA,CB,HA1,HA2,HA3

The first example selects the first five atoms, the 10th atom, and all atoms with the names “CA” or “CB”. The second mask selects only the 101st atom. The final mask selects all atoms with names CA, CB, HA1, HA2, or HA3.

Many atoms also have type names associated with them, that are often used to distinguish chemical environments. These are really just force field implementation details, as types often change between generations of force fields to allow for increased parameter fitting flexibility. However, the two characters @% allow you to select atoms based on type name instead of name (note, integer indices have no meaning for atom type names, so every type in the list following @% is interpreted as a string-like name). Examples include:

@%CT,CX
@%N,H

The first example selects all atom types with the label “CT” or “CX”, while the second chooses the atom types “N” or “H”.

Wild-cards

You can also use so-called wild-cards when selecting atoms. For instance, suppose you want to select all hydrogen atoms, which you know all start with the letter ‘H’, or all carbons which you know start with ‘C’. The following masks will do these two tasks:

The “=” character works as a wild-card, as does the ‘*’ (so the above examples could have been written with a ‘*’ instead). If either ‘=’ or ‘*’ is part of the atom name, you can use the “” character to escape it and have the mask parser interpret it as a character literal.

Residue-Atom Selections

A frequent requirement is to select all atoms of a particular name from a given residue (or set of residues). This can be done with the | binary operator (see below), but it is so common that there is a shortcut for doing this, shown below:

:ALA@CA,CB
:ASP@OD=

The first mask selects all CA and CB atoms from all ALA residues. The second selects all atoms whose names start with the two letters OD (such as OD1 and OD2) from all ASP residues.

Distance-based masks

Still other times you want to select all atoms (or all residues) within a particular distance around a particular subset of atoms. This syntax can be confusing, so I will try to walk through it carefully.

Limited Embedded Python Interpreter

parmed also comes equipped with a fully-fledged Python interpreter under the hood. You can run individual Python commands by starting the command with a bang (!). A double-bang (!!) indicates to parmed that a multi-line Python code segment follows, and to interpret everything that comes afterwards as Python code until another double-bang line (!!) appears. If you are typing at the prompt inside the interpreter, the prompt changes to py >>> to indicate you are in the Python interpreter.

Note that running Python code can be insecure if the source of that code is untrusted. As a result, parmed will refuse to execute raw Python code unless you explicitly give the interpreter permission to do so with the -e command-line flag.

A simple example is shown below (input follows the prompts > and py >>>):

$ parmed -e

                                  /^^^/           /]
                                 /   ]           / ]
                         _______/    ]___       /  ]
                        /                \_____/   /
                      _/   [@]  \ \                \
                     /..         | |                ]
                      VVVvvv\    | |         _/\    ]
          P A R M E D       |               /    \  ]
                     AAA^^^^^              /       \]
                      \_________\   \_____/
                                \    \
                                 \____\

ParmEd: a Parameter file Editor


Reading input from STDIN...
> !!
py >>> def print_hello_world():
py >>>     print "Hello World"
py >>>
py >>> print_hello_world()
py >>> !!
Hello World
> !print "7 + 4 = %d" % (7 + 4)
7 + 4 = 11

Notice that immediately after the closing !! in the first Python code block, the Python code is executed. The interpreter takes the entire code typed between the !! lines and interprets it as one string, preserving indentation, then executes it. On the other hand, a single ! immediately runs that one line of Python.

One “gotcha” here is that Python objects that you create in this interpreter are not persistent—that is, the function print_hello_world no longer exists after that code block closes, so you can’t use it in a later Python code block:

> !print_hello_world()
NameError: name 'print_hello_world' is not defined

So the lesson here is that you either need to be able to encapsulate all Python activity in a single code block, use the ParmEd API directly in your own Python script, or make use of A very dirty trick that should make any Pythonista wince.

Perhaps of the most importance, however, is that the topology file list is made available to you in the Python interpreter namespace as the name amber_prmtop, which is an instance of ParmList. So amber_prmtop.parm is the currently active parameter-topology object.

Let’s have a look at how we might be able to use that:

> !print amber_prmtop.parm.bonds[0].type
<BondType; k=570.000, Req=1.229>
> !!
py >>> amber_prmtop.parm.bonds[0].type.k = 500.0
py >>> print amber_prmtop.parm.bonds[0].type
py >>> print amber_prmtop.parm.bonds[0]
py >>> !!
<BondType; k=500.000, Req=1.229>
<Bond <Atom C [11]; In SER 0>--<Atom O [12]; In SER 0>; type=<BondType; k=500.000, Req=1.229>>
> printBonds @12 @13
Atom 1               Atom 2               R eq       Frc Cnst
     12    C (   C)      13    O (   O)     1.2290   500.0000

Notice here how we changed our active prmtop by changing the bond force constant of the first bond in the system (between atoms 12 and 13 when indexing from 1) from 570 kcal/mol to 500 kcal/mol!

A very dirty trick

There is a small trick you can play to get objects you create to persist. I only include this section because I find it entertaining and a possibly helpful pedagogical diversion. I would highly recommend that you use the ParmEd API in your own script before resorting to anything shown in this section.

The three objects available to you are amber_prmtop, line, and self. The line object is the currently parsed input line (not very useful), and self is the instance of the Python interpreter that is collecting your input (and will be destroyed after the interpreter is finished).

So the only object that will persist past the destruction of the temporary Python interpreter is amber_prmtop (and type(self), but only in Python 3, since it is an old-style class in Python 2 by virtue of deriving from cmd.Cmd).

So you can attach your function to the ParmList object amber_prmtop and retrieve it from there later. Be careful not to clobber a critical attribute of that class, though! This trick is demonstrated continuing from the interpreter session from above:

> !!
py >>> def print_hello_world():
py >>>     print "Hello world!"
py >>>
py >>> amber_prmtop.custom_func = print_hello_world
py >>> !!
> !amber_prmtop.custom_func()
Hello world!

Notice that by keeping a reference to our function in the amber_prmtop namespace, we could refer back to it later.

The clever Pythonista could figure out how to use other introspective commands to gain control of other mechanisms as well—for instance, I used to disallow import by blocking import foo or from foo import bar, but quickly found that this alternative also worked:

> !!
py >>> sys = __builtins__['__import__']('sys')
py >>> print repr(sys.version_info)
py >>> !!
sys.version_info(major=2, minor=7, micro=9, releaselevel='final', serial=0)

So it seemed rather fruitless to prohibit behavior that was so easy to work around!

Using xparmed

An alternative to running the command-line-based parmed program is to use the Tkinter-based GUI front-end, xparmed. Note that not all actions have been implemented in xparmed—if the one you need gives a message to this effect, you will need to use parmed instead.

xparmed is significantly more limited. It cannot be scripted, and it cannot process multiple topology files in the same session. It may, however, help you learn ParmEd better as well as lessen the learning curve for performing basic tasks.

You can find more extensive documentation by clicking here to go to my wiki.

You can right-click on any of the buttons to get the same help printed above on that action.