.. Do NOT modify this file directly. conf.py creates it.
.. modify conf.py instead

Using ``parmed``
================

This page details using the command-line version of ParmEd, which is the
primary front-end program using the :mod:`parmed` and :mod:`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 :class:`Structure <parmed.structure.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:

.. code-block:: none

    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
~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~

.. code-block:: none

    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
~~~~~~

.. code-block:: none

    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
~~

.. code-block:: none

    cd <directory>

Changes to a new directory like UNIX 'cd'

chamber
~~~~~~~

.. code-block:: none

    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
~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~~

.. code-block:: none

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

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

changeLJSingleType
~~~~~~~~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~~~~~

.. code-block:: none

    changeProtState <mask> <state #>

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

changeRadii
~~~~~~~~~~~

.. code-block:: none

    changeRadii <radii_set>

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

changeRedoxState
~~~~~~~~~~~~~~~~

.. code-block:: none

    changeRedoxState <mask> <state #>

Changes the reduction state of a given titratable residue that can be treated via constant redox potential MD in Amber.

checkValidity
~~~~~~~~~~~~~

.. code-block:: none

    checkValidity

Basic checks for prmtop validity.

defineSolvent
~~~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~

.. code-block:: none

    deletePDB

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

energy
~~~~~~

.. code-block:: none

    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
~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~

.. code-block:: none

    listParms

Lists all of the loaded topology files

lmod
~~~~

.. code-block:: none

    lmod

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

loadCoordinates
~~~~~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~

.. code-block:: none

    loadRestrt <restrt_filename>

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

ls
~~

.. code-block:: none

    ls [Unix ls options]

Lists directory contents. Like UNIX 'ls'

minimize
~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~

.. code-block:: none

    netCharge [<mask>]

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

OpenMM
~~~~~~

.. code-block:: none

    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
~~~~~~

.. code-block:: none

    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
~~~~~~~

.. code-block:: none

    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
~~~~~~

.. code-block:: none

    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
~~~~

.. code-block:: none

    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
~~~~~~~

.. code-block:: none

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

Final prmtop written after all actions are complete

printAngles
~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~~

.. code-block:: none

    printDetails <mask>

Returns information about all atoms in a given mask

printDihedrals
~~~~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~

.. code-block:: none

    printFlags

Prints all %FLAGs found in the topology file

printInfo
~~~~~~~~~

.. code-block:: none

    printInfo <flag>

Prints all prmtop data corresponding to the given %FLAG

printLJMatrix
~~~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~~~

.. code-block:: none

    printPointers

Prints a list of all the POINTERS and their values

scale
~~~~~

.. code-block:: none

    scale <FLAG> <factor>

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

scee
~~~~

.. code-block:: none

    scee <scee_value>

Sets the 1-4 EEL scaling factor in the prmtop

scnb
~~~~

.. code-block:: none

    scnb <scnb_value>

Sets the 1-4 VDW scaling factor in the prmtop

setAngle
~~~~~~~~

.. code-block:: none

    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
~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~~

.. code-block:: none

    setOverwrite [True|False]

Necessary to overwrite original topology file name.

source
~~~~~~

.. code-block:: none

    source <file>

Sources a file with a list of parmed commands

strip
~~~~~

.. code-block:: none

    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
~~~~~~~

.. code-block:: none

    summary

Prints out a summary of prmtop contents

tiMerge
~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~~~~~~

.. code-block:: none

    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
~~~~~~~~~~~

.. code-block:: none

    writeFrcmod <frcmod_name>

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

writeOFF
~~~~~~~~

.. code-block:: none

    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:

.. code-block:: none

    :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:

.. code-block:: none

    @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:

.. code-block:: none

    @%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:

.. code-block: none

    @H=
    @C=

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:

.. code-block:: none

    :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
>>>``):

.. code-block:: none

    $ 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:

.. code-block:: none

    > !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 :class:`ParmList
<parmed.tools.parmlist.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:

.. code-block:: none

    > !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 :class:`ParmList
<parmed.tools.parmlist.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:

.. code-block:: none

    > !!
    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:

.. code-block:: none

    > !!
    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
<http://jswails.wikidot.com/parmed#toc3>`_.

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