# 5.10. ITP topology parser

Reads a GROMACS ITP or TOP file to build the system. The topology will contain atom IDs, segids, residue IDs, residue names, atom names, atom types, charges, chargegroups, masses, moltypes, and molnums. Any masses that are in the file will be read; any missing values will be guessed. Bonds, angles, dihedrals and impropers are also read from the file.

If an ITP file is passed without a `[ molecules ]` directive, passing `infer_system=True` (the default option) will create a Universe with 1 molecule of each defined `moleculetype`. If a `[ molecules ]` section is present, `infer_system` is ignored.

If files are included with the #include directive, they will also be read. If they are not in the working directory, ITPParser will look for them in the `include_dir` directory. By default, this is set to `include_dir="/usr/local/gromacs/share/gromacs/top/"`. Variables can be defined with the #define directive in files, or by passing in keyword arguments.

Examples

    import MDAnalysis as mda
    from MDAnalysis.tests.datafiles import ITP_tip5p

    #  override charge of HW2 atom (defined in file as HW2_CHARGE)
    u = mda.Universe(ITP_tip5p, HW2_CHARGE=2, infer_system=True)

Note

AMBER also uses topology files with the .top extension. To use ITPParser to read GROMACS top files, pass `topology_format='ITP'`.

    import MDAnalysis as mda
    u = mda.Universe('topol.top', topology_format='ITP')

## 5.10.1. Preprocessor variables

ITP files are often defined with lines that depend on whether a keyword flag is given. For example, this modified TIP5P water file:

    [ moleculetype ]
    ; molname       nrexcl
    SOL             2

    #ifndef HW1_CHARGE
        #define HW1_CHARGE 0.241
    #endif

    #define HW2_CHARGE 0.241

    [ atoms ]
    ; id    at type res nr  residu name     at name         cg nr   charge
    1       opls_118     1       SOL              OW             1       0
    2       opls_119     1       SOL             HW1             1       HW1_CHARGE
    3       opls_119     1       SOL             HW2             1       HW2_CHARGE
    4       opls_120     1       SOL             LP1             1      -0.241
    5       opls_120     1       SOL             LP2             1      -0.241
    #ifdef EXTRA_ATOMS  ; added for keyword tests
    6       opls_120     1       SOL             LP3             1      -0.241
    7       opls_120     1       SOL             LP4             1       0.241
    #endif

Define these preprocessor variables by passing keyword arguments. Any arguments that you pass in override any variables defined in the file. For example, the universe below will have charges of 3 for the HW1 and HW2 atoms:

    import MDAnalysis as mda
    from MDAnalysis.tests.datafiles import ITP_tip5p

    u = mda.Universe(ITP_tip5p, EXTRA_ATOMS=True, HW1_CHARGE=3, HW2_CHARGE=3)

These keyword variables are case-sensitive. Note that if you set keywords to `False` or `None`, they will be treated as if they are not defined in #ifdef conditions.

For example, the universe below will only have 5 atoms.

    u = mda.Universe(ITP_tip5p, EXTRA_ATOMS=False)

## 5.10.2. Classes

class MDAnalysis.topology.ITPParser.ITPParser(filename)

  Read topology information from a GROMACS ITP or TOP file.

  Creates a Topology with the following Attributes: - ids - names - types - masses - charges - chargegroups - resids - resnames - segids - moltypes - molnums - bonds - angles - dihedrals - impropers

  Note

  By default, atomtypes and masses will be guessed on Universe creation if they are not read from the input file. This may change in release 3.0. See Guesser modules for more information.

  Changed in version 2.2.0: no longer adds angles for water molecules with SETTLE constraint

  Changed in version 2.8.0: Removed mass guessing (attributes guessing takes place now through universe.guess_TopologyAttrs() API). Added guessed elements if all elements are valid to preserve partial mass guessing behavior

  close()

    Close the trajectory file.

  convert_forces_from_native(force, inplace=True)

    Conversion of forces array force from native to base units

    Parameters:

      - force (array_like) – Forces to transform

      - inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

    Note

    By default, the input force is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

    Added in version 0.7.7.

  convert_forces_to_native(force, inplace=True)

    Conversion of force array force from base to native units.

    Parameters:

      - force (array_like) – Forces to transform

      - inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

    Note

    By default, the input force is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

    Added in version 0.7.7.

  convert_pos_from_native(x, inplace=True)

    Conversion of coordinate array x from native units to base units.

    Parameters:

      - x (array_like) – Positions to transform

      - inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

    Note

    By default, the input x is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

    Changed in version 0.7.5: Keyword inplace can be set to `False` so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

  convert_pos_to_native(x, inplace=True)

    Conversion of coordinate array x from base units to native units.

    Parameters:

      - x (array_like) – Positions to transform

      - inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

    Note

    By default, the input x is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

    Changed in version 0.7.5: Keyword inplace can be set to `False` so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

  convert_time_from_native(t, inplace=True)

    Convert time t from native units to base units.

    Parameters:

      - t (array_like) – Time values to transform

      - inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

    Note

    By default, the input t is modified in place and also returned (although note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.) In-place operations improve performance because allocating new arrays is avoided.

    Changed in version 0.7.5: Keyword inplace can be set to `False` so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

  convert_time_to_native(t, inplace=True)

    Convert time t from base units to native units.

    Parameters:

      - t (array_like) – Time values to transform

      - inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data

    Note

    By default, the input t is modified in place and also returned. (Also note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.)

    Changed in version 0.7.5: Keyword inplace can be set to `False` so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

  convert_velocities_from_native(v, inplace=True)

    Conversion of velocities array v from native to base units

    Parameters:

      - v (array_like) – Velocities to transform

      - inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

    Note

    By default, the input v is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

    Added in version 0.7.5.

  convert_velocities_to_native(v, inplace=True)

    Conversion of coordinate array v from base to native units

    Parameters:

      - v (array_like) – Velocities to transform

      - inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

    Note

    By default, the input v is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

    Added in version 0.7.5.

  parse(include_dir='/usr/local/gromacs/share/gromacs/top/', infer_system=True, **kwargs)

    Parse ITP file into Topology

    Parameters:

      - include_dir (str, optional) – A directory in which to look for other files included from the original file, if the files are not first found in the current directory. Default: “/usr/local/gromacs/share/gromacs/top/”

      - infer_system (bool, optional (default True)) – If a `[ molecules ]` directive is not found within the the topology file, create a Topology with one of every `[ moleculetype ]` defined. If a `[ molecules ]` directive is found, this keyword is ignored.

    Return type:

      MDAnalysis Topology object

  units = {'length': None, 'time': None, 'velocity': None}

    dict with units of of time and length (and velocity, force, … for formats that support it)