Molgeom and vmd2molgeom


Molgeom is a python code to measure distances, angles and dihedral angles between atoms. Measures can be done on a single molecular structure or along a molecular dynamic simulations. molgeom can read XYZ/XMOL and TINKER files, but subroutine to read more file formats can be easily added. The next version of molgeom will use a modular approach, that easily allows to add new modules to read more file formats. Measurements can be done on system modeled using periodic boundary conditions.

vmd2molgeom is a bash utility to create a file out of the molecular viewer VMD, that is used by molgeom to perform multiple measurements.


Molgeom requires python and numpy installed. vmd2molgeom is a bash script, therefore it requires a bash shell


molgeom [options] input_file



show program's version number and exit

-h, —help

show this help message and exit

-c, —credits

display credits

-l, —listformats

list available formats

-f FORMAT, —format=FORMAT

specify the format of the input structure, [default:arc]. It can be a trajectory from MD calculations or a single structure.


perform all the measurements in the specified file. e.g.: molgeom -e filedata inputfile


calculate the distance between two atoms. Te atoms are specified by using their progressive number in the structure. e.g.: molgeom -d 1 5 inputfile to calculate distance between atoms 1 and 5.

-a ANGLE, —angle=ANGLE

calculate the angle between three atoms. The atoms are specified by using their progressive number in the structure. e.g.: molgeom -a 1 3 5 inputfile to calculate angle between atoms 1, 3 and 5 in inputfile

calculate the dihedral angle between four atoms. The atoms are specified by using their progressive number in the structure. e.g.: molgeom -t 1 3 5 10 360 inputfile to calculate dihedral angle between atoms 1, 3, 5 and 10. Dihedral angles are defined as the angle between the planes defined by the atoms 1 3 5 and 3 5 10. The fifth number is the period used to express the torsions:360 means the torsions are expressed as angles in the interval 0 to 360 deg, 180 means torsions are given in the interval 0 to 180 deg and so on.


molgeom can calculate distances, angles and dihedral angles in periodic systems. In this case, the size of the unit cell must be given by specifying the length of the three unit vectors a, b, c (in angstrom) and the angles alpha, beta, gamma (in degrees) between those vectors.

How to manage more file formats

You can manage more file formats by adding subroutines to read the new file formats. It is important for you to understand and respect the structure, and the type of data returned by, the following default subroutine for XYZ format:

    def read_xyz(file,offset=None):
        parse data from xyz file or xmol trajectory
        The trajectory is read one frame at a time by
        passing the offset.
        if offset != None:
        line=file.readline() #read fist line: number of atoms and optional comment
        if len(line)==0: #reached end of file: stop
                return "EOF"
        if offset == None:
        file.readline() #!skip line    
        while linecount<at_number:
            coordinates[linecount,0]=junk[1] #get X-coords
            coordinates[linecount,1]=junk[2] #get Y-coords
            coordinates[linecount,2]=junk[3] #get Z-coords
            if offset == None:
                at_symbols.append(junk[0])  #get atomic symbol
        if offset==None:
            return coordinates, newoffset, at_symbols
            return coordinates, newoffset

Input parameters:

file: the _OBJECT_ inputfile offset: the file offset (None as default)


EOF: if end of file is reached coordinates: matrix of cartesian coordinates for all the atoms in the structure (or trajectory frame) newoffset: the current position in file at_symbol: list of atomic symbols (returned only if offset=None)

If input file is a trajectory file, in order to read the entire trajectory, the subroutine above must be called for each frame. In other words, trajectories are red frame-by-frame: every time the subroutine is called, the offset is used to
jump to the beginning of the new frame in the trajectory. All the data that are constant along teh trajectory (e.g. the atomic symbols, atom names, connectivity, …) are returned only when the 1st frame is red.

NOTE: Please note that this approach has been used since is the most general. For the purpose of calculate distances, angles, dihedrals and others geometric parameters, coordinates are the only data you need to retrieve from the input file.

Do not forget to update the string list_of_formats="XYZ/XMOL, TINKER XYZ/ARC" in the parse_cmd() subroutine with the new formats, so to be displayed by the -l flag.


From the command line, only a single measurement can be perform. In order to make more measurements, a file must be prepared as follow:

  1. one line must be written for each measurements:

#to measure a distance, only the two atomic progressive numbers must be specified;
to measure an angle, only the three atomic progressive numbers must be specified;
to measure a dihedral angle, only the four atomic progressive numbers must be specified.


1 5
1 3
1 3 5
1 4 8 9 180

Running molgeom with the option -e and the file as in the example above will result in measuring the distances between atoms 1 and 5 and 1 and 3, the angle 1-3-5 and the dihedral angle 1-4-8-9. For dihedral angles, a fifth number can be used a period can be used to express the torsion in a give interval, e.g. 0 to 180 deg (360 by default, when a period is not specify).

A convenient way to create this file is to open the structure with VMD and make the measurements you are interested in. Saving the VMD state will write a file containing information about your measurements. Use then the bash utility
vmd2molgeom to extract those information from the file containing VMD state and write them in a file in the format readable by molgeom: the output file will contain all the atomic progressive numbers (starting from 1 and not from 0 as
in VMD) for the requested measure (distance, angle or dihedral). A line containing the atomic progressive numbers is written for each measure.


vmd2molgeom -d/-a/-t/-all <input_file> <out_file>


-d: get distances (search for "add Bonds")
-a: get angles (search for "add Angles")
-t: get torsions (search for "add Dihedrals")
-all: get all bonds, angles and torsions


input_file: VMD saved state
out_file: a text file; if exists, data can be appended or the old file can be removed or backuped

Output files can be used directly with molgeom to calculate distances, angles, torsions in periodic and non-periodic calculations.


This script has been developed by Andrea Minoia. The author can be contacted by mail at


You are free to use, modify and redistribute molgeom and vmd2molgeom as far as you keep them free as in beer.
As free(as in beer)ware software, molgeom and vmd2molgeom come with _ABSOLUTE_ _NO_ (as in NOTHING, NADA, NICTHS, NIENTE, RIEN) WARRANTY. The author is _NOT_ responsible if those software will erase your hard disks, empty your bank account, stole your car, seduce your wife, shave your dog or make any kind of mess and damages, including loss of data or worst. By using molgeom and vmd2molgeom, you _ACCEPT_ these terms.


Download here molgeom and vmd2molgeom

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License