This page details using the command-line version of ParmEd, which is the
primary front-end program using the
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
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
parmed on the command-line, or fed via pipes through standard
input. You can provide an input file using the
All actions should be specified on the
parmed command-line in the
ActionName arg1 arg2 arg3 ... argN [parm <idx|name>]
Arguments should be whitespace-delimited, the
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.
Action commands are available in ParmEd. The information here
is available via the help_ command in the
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.
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:
All defaults come from Ref.
Pengfei Li and Kenneth M. Merz, J. Chem. Theory Comput., 2014, 10,
Pengfei Li, Lin F. Song and Kenneth M. Merz, J. Phys. Chem. B, 2015,
Pengfei Li, Lin F. Song and Kenneth M. Merz, J. Chem. Theory Comput.,
2015, 11, 1645-1657.
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 <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
<mask3>in each dihedral
<mask3>: Selection of the other middle atom bonded to
<mask4>: Selection of the other end-atom in each dihedral
<phi_k>: Force constant in kcal/mol
<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 <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 <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 <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_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_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.
Changes to a new directory like UNIX ‘cd’
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.
-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 <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 <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 <mask1> <mask2> <Rmin> <epsilon>
Changes a particular Lennard Jones pair based on a given (pre-combined) epsilon/Rmin
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 <mask> <state #>
Changes the protonation state of a given titratable residue that can be treated via constant pH MD in Amber.
- Changes intrinsic GB radii to the specified set: Allowed values are
amber6, bondi, mbondi, mbondi2, mbondi3
changeRedoxState <mask> <state #>
Changes the reduction state of a given titratable residue that can be treated via constant redox potential MD in Amber.
Basic checks for prmtop validity.
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 <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 <mask1> <mask2> <mask3> <mask4>
Deletes the dihedral around
<mask3> in which the end-groups are
<mask4> For multi-term dihedrals, it removes each term.
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:
<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>: 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.
<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
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
# 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 <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/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 [<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 <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
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
Lists all of the loaded topology files
Adjusts Lennard Jones parameters to work with the LMOD code in Amber (changes LJ A coefficients that are 0 to 1000).
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
Gromacs GRO file
Loads a restart file so we have coordinates. Necessary for distance-based mask criteria and writeOFF
ls [Unix ls options]
Lists directory contents. Like UNIX ‘ls’
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
omm Use OpenMM instead of sander+scipy to minimize
<cutoff>Nonbonded cutoff in Angstroms
<tolerance>The largest energy difference between successive steps in the minimization allow the minimization to stop (Default 0.001)
<cycles>The maximum number of minimization cycles permitted. No limit by default (minimization stops when tolerance is satisfied)
Implicit Solvent options
<IGB>GB model to use (0=No GB, 1,2,5,7,8 correspond to Amber models)
<conc>Salt concentration for GB in Molarity
<mask>Selection of atoms to restrain
<k>Weight of positional restraints (kcal/mol/A^2)
norun Do not run the calculation
<script>Name of the Python script to write to run this calculation
<platform>Which compute platform to use. Options are CUDA, OpenCL, CPU, and Reference. Consult OpenMM docs for more information
<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.
Prints the total charge of all of the atoms given by the mask. Defaults to all atoms
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 <file> [norenumber] [charmm] [anisou]
Write a PDBx/mmCIF file from the currently active system to
<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 <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 <file> [norenumber] [charmm] [anisou]
Write a PDB file from the currently active system to
<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 <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 <prmtop_name> [<inpcrd_name>] [netcdf]
Final prmtop written after all actions are complete
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 [<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.
Returns information about all atoms in a given mask
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.
Prints all %FLAGs found in the topology file
Prints all prmtop data corresponding to the given %FLAG
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 [<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.
Prints a list of all the POINTERS and their values
scale <FLAG> <factor>
Multiplies all values in a particular section of an Amber prmtop by a scalar factor
Sets the 1-4 EEL scaling factor in the prmtop
Sets the 1-4 VDW scaling factor in the prmtop
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 <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 [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.
Necessary to overwrite original topology file name.
Sources a file with a list of parmed commands
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).
Prints out a summary of prmtop contents
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 <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
.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.
Writes an frcmod file from all of the parameters in the topology file.
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.
: 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
: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.
@ 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
@% 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
The first example selects all atom types with the label “CT” or “CX”, while the second chooses the atom types “N” or “H”.
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.
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
operator (see below), but it is so common that there is a shortcut for doing
this, shown below:
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.
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
!). 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
A simple example is shown below (input follows the prompts
$ 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
!! lines and interprets it as one string, preserving indentation, then
executes it. On the other hand, a single
! immediately runs that one line
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
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.type <BondType; k=570.000, Req=1.229> > !! py >>> amber_prmtop.parm.bonds.type.k = 500.0 py >>> print amber_prmtop.parm.bonds.type py >>> print amber_prmtop.parm.bonds py >>> !! <BondType; k=500.000, Req=1.229> <Bond <Atom C ; In SER 0>--<Atom O ; 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
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
type(self), but only in Python
3, since it is an old-style class in Python 2 by virtue of deriving from
So you can attach your function to the
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
> !! 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
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!
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
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
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.