f_timeseries.py

Extracts meta-data from MD trajectories. This tool comes with an powerful interpreter of reverse polish notation to represent complex system properties in a condensed way.

Reverse polish notation

A compact notation to express arbitrary mathematical operations while refraining from the extensive usage of braces is called the reverse polish notation. In general, it is a postfix syntax, that is, the operator is written after the operands. For example the first line becomes

(3 + 4) * (5 + 6) / 7
3 4 + 5 6 + * 7 /

The list of the operands waiting to be consumed by an operator is called stack. Objects can be placed on the stack arbitrarily. However, this implementation requires you to end with a single entry on the stack. Each of the objects can be both a scalar and a vector.

Examples

Suppose you have a molecule with three points of interest, which shall be called A, B, and C. You are interested in the angle of the vectors BA and CB with the z-axis and the angle between these two vectors. Then the following lines will give you three angles in radians per frame.

f_timeseries.py input.psf input.dcd --periodic  \
        --cmd 'selection A:com; selection B:com;diff;0,0,1;angle' \
        --cmd 'selection B:com; selection C:com;diff;0,0,1;angle' \
        --cmd 'selection A:com; selection B:com;diff;selection B:com; selection C:com;diff;angle'

Shortcuts

Sometimes a command will be used frequently. Hence, there are shortcuts in this case. The following shortcuts are available. Each time, the two lines are identical.

# prints the side lengths (x, y, z) of the unit cell
box
boxdimen;1,1,1,0,0,0;mask;3;pile

Supported formats

All file formats of MDAnalysis are supported. Input files may be compressed using gzip or bzip2.

Note

File formats are recognized by file extension. Therefore, you have to stick to the standard file extensions.

Warning

Only rectangular simulation boxes are currently supported.

Todo

Guess input file format.

Command line interface

topology

The topology file to work with.

coordinates

The coordinate file to work with.

--frames

The zero-based frame selection that allows for slicing. The general syntax is ‘start:stop:step’ which would select all frames from start to stop (excluding stop) while skipping step frames inbetween. Selecting single frames by specifying a single number is possible. Negative indices count backwards from the end of the trajectory.

--periodic

Whether to wrap atoms for spatial selection criteria back to the original cell.

--indexfile

Files that contain named groups of atoms based on their indices. Files have to be in GROMACS ndx-Format. Can be used multiple times.

--cmd

String concatenating the operators using reverse polish notation together with atom selectors. This command can be issued multiple times on the command line. Every option will result in an additional entry printed in the resulting line per frame. The general notation is

selection:cmd;selection2:cmd2

There are some operators that do not support selections. They are meant to be used this way

:cmd;:cmd2

You can put elements on the stack by yourself. They have to be numeric, but can be either a comma-separated vector or a scalar. The selection syntax is decribed separately. Please refer to the section on atom selections. The available operators are

  • com calculates the center of mass of the given selection. If the selection is empty, the center of mass of all atoms in the whole system is calculated. The result is a vector in cartesian coordinates. com does not consume any stack elements but rather adds another one.
id 1-10:com
  • dist calculates the distance between two points in cartesian coordinates. The last two stack elements will be consumed and have to be vectors. The resulting scalar is put back on the stack. This operator does not support selections.
1,1,1; 2,2,2; dist
id 1-10:com; id 11-20:com; dist
  • diff calculates the difference of the two last stack entries which only have to be of the same dimension. This operator does not support selections.
3;4;diff
id 1-10:com; id 11-20:com; diff
  • stacklen adds the number of current stack elements to the stack.
stacklen
  • framenum prints the number of the current frame in the trajectory. Selections are not supported. Please keep in mind that this frame number does not necessarily correspond with a simulation step and that the indices are zero-based.
framenum
  • boxdimen puts the system box dimensions on the stack. The unit cell is defined by six elements: the length of the x, y, and z vector and the angles inbetween (alpha, beta, and gamma).
boxdimen
  • mask discards some of the elements on the stack. The last element of the stack has to be a vector which is to be aligned with the end of the stack. Only stack elements with a non-zero mask entry are kept. For example, if you are intested in the x and y axis of the box dimensions only, you may use:
boxdimen;1,1,0,0,0,0;mask
  • arraymask discards some of the elements’ elements on the stack. The last element of the stack has to be a vector which is to be aligned with the end of the stack. Only stack elements with a non-zero mask entry are kept. It acts like the mask operator where the mask is applied to each object on the stack in reverse order as long as the dimensions of the object on the stack matches the dimension of the mask.
  • prod calculates the product of the last two stack elements.
  • frac calculated the quotient of the last two stack elements. Please note that the last stack element is the numerator.
  • sum adds the last two stack elements.
  • pos puts the cartesian coordinates of the selected atoms as list of vectors on the stack.
  • scaledpos puts the coordinates of the selected atoms in terms of the lattice vectors of the respective frame on the stack.
  • flatten takes a single vector from the stack and pushes its elements back.
  • charge calculates the charge density profile along a given vector. This command calculates the charge density of all molecules that do not belong to a residue named UNK from 0 to 60 Angstroms along the 0,0,1 vector using 100 bins. The result is pushed onto the stack as a vector that has as many elements as bins were used.
0,60;100;0,0,1;not resname UNK:charge
  • fitplane fits a plane to the atom coordinates of the given selection. The normalized normal vector of the plane is pushed onto the stack.
type PL:fitplane

Note

The algorithm used is Singular Value Decomposition. Please make sure that you only have only atoms for one plane as multiple parallel planes in the underlying structure will lead to spurious errors.

  • pile takes the last element on the stack and inteprets it as number of elements to transform into a vector. The resulting vector is pushed onto the stack. The following would print the simulation cell dimensions.
boxdimen;1,1,1,0,0,0;mask;3;pile
  • dihedral calculates the dihedral angle in degrees of the selection which has to contain four atoms. Ordering is preserved.
id 2,5,7,8:dihedral

Internal functions

f_timeseries._abc_to_hmatrix(a, b, c, alpha, beta, gamma, degrees=True)[source]
f_timeseries._cartesian_to_scaled_coordinates(coordinates, h_matrix)[source]
f_timeseries._dimension_helper(val)[source]
f_timeseries._dump_stack(stack, output)[source]

Lists the current stack elements.

Parameters:

stack : iterable

The current stack.

output : output_tracker instance

Error reporting.

f_timeseries._execute(columns, command, framenum, universe, output)[source]

Reverse polish notation parser.

Parameters:

columns : iterable

Output of former --cmd arguments.

command : String

Current request in reverse polish notation to execute.

framenum : Integer

Current frame number. One-based.

universe : MDAnalysis.core.AtomGroup.Universe

The universe which trajectory is to be analyzed.

output : output_tracker instance

Error reporting.

Returns:

iterable :

Results of all --cmd requests processed so far.

f_timeseries._operator_angle(stack, output)[source]

Reverse polish notation operator that calculates the angle between the last two stack elements.

The last two stack elements have to be a vector.

Parameters:

stack : iterable

The current stack.

output : output_tracker instance

Error reporting.

Returns:

iterable :

The new stack.

f_timeseries._operator_arraymask(stack, output)[source]

Reverse polish notation operator that filters amongst the last stack elements as long as their shape is compatible with the mask.

Parameters:

stack : iterable

The current stack.

output : output_tracker instance

Error reporting.

Returns:

iterable :

The new stack.

f_timeseries._operator_boxdimen(stack, universe, framenum, output)[source]

Reverse polish notation operator that puts the simulation box dimensions on the stack.

Parameters:

stack : iterable

The current stack.

universe : MDAnalysis.core.AtomGroup.Universe

The universe which trajectory is to be analyzed.

framenum : Integer

Current frame number. One-based.

output : output_tracker instance

Error reporting.

f_timeseries._operator_charge(stack, selection, universe, framenum, output)[source]

Reverse polish notation operator that calculates the charge density profile.

Note

Only works correctly for charge density profiles along the z axis.

Todo

Implement vector choice.

Parameters:

stack : iterable

The current stack.

selection : String

The CHARMM-style selection request. May contain atom ids, as well.

universe : MDAnalysis.core.AtomGroup.Universe

The universe which trajectory is to be analyzed.

framenum : Integer

Current frame number. One-based.

output : output_tracker instance

Error reporting.

Returns:

iterable :

The new stack.

f_timeseries._operator_com(selection, universe, output)[source]

Reverse polish notation operator that calculates the center of mass.

Parameters:

selection : String

The CHARMM-style selection request. May contain atom ids, as well.

universe : MDAnalysis.core.AtomGroup.Universe

The universe which trajectory is to be analyzed.

output : output_tracker instance

Error reporting.

Returns:

numpy.array :

Center of mass in cartesian coordinates. Length unit is Angstrom.

f_timeseries._operator_diff(stack, output)[source]

Reverse polish notation operator that calculates the difference between the last two stack elements.

Parameters:

stack : iterable

The current stack.

output : output_tracker instance

Error reporting.

Returns:

iterable :

The new stack.

f_timeseries._operator_dihedral(stack, selection, universe, output)[source]

Reverse polish notation operator that calculates the dihedral angle.

Parameters:

stack : iterable

The current stack.

selection : String

The CHARMM-style selection request. May contain atom ids, as well.

universe : MDAnalysis.core.AtomGroup.Universe

The universe which trajectory is to be analyzed.

output : output_tracker instance

Error reporting.

Returns:

iterable :

The new stack.

f_timeseries._operator_dist(stack, output)[source]

Reverse polish notation operator that calculates the distance between the last two stack elements.

Parameters:

stack : iterable

The current stack.

output : output_tracker instance

Error reporting.

Returns:

iterable :

The new stack.

f_timeseries._operator_fitplane(stack, selection, universe, framenum, output)[source]

Reverse polish notation operator that fits a plane to coordinates.

Parameters:

stack : iterable

The current stack.

selection : String

The CHARMM-style selection request. May contain atom ids, as well.

universe : MDAnalysis.core.AtomGroup.Universe

The universe which trajectory is to be analyzed.

framenum : Integer

Current frame number. One-based.

output : output_tracker instance

Error reporting.

Returns:

iterable :

The new stack.

f_timeseries._operator_flatten(stack, output)[source]

Reverse polish notation operator that puts every element of an vector on the stack separately.

Parameters:

stack : iterable

The current stack.

output : output_tracker instance

Error reporting.

Returns:

Iterable :

The new stack.

f_timeseries._operator_frac(stack, output)[source]

Reverse polish notation operator that calculates the quotient of the last two stack elements.

Note that the last stack element is treated as numerator.

Parameters:

stack : iterable

The current stack.

output : output_tracker instance

Error reporting.

Returns:

iterable :

The new stack.

f_timeseries._operator_mask(stack, output)[source]

Reverse polish notation operator that filters amongst the last stack elements.

Parameters:

stack : iterable

The current stack.

output : output_tracker instance

Error reporting.

Returns:

iterable :

The new stack.

f_timeseries._operator_pile(stack, output)[source]

Reverse polish notation operator that joins elements on the stack info one single vector.

Parameters:

stack : Iterable

The current stack.

output : output_tracker instance

Error reporting.

Returns:

Iterable :

The new stack.

f_timeseries._operator_pos(stack, selection, universe, output)[source]
f_timeseries._operator_prod(stack, output)[source]

Reverse polish notation operator that calculates the product of the last two stack elements.

Parameters:

stack : iterable

The current stack.

output : output_tracker instance

Error reporting.

Returns:

iterable :

The new stack.

f_timeseries._operator_scaledpos(stack, selection, universe, framenum, output)[source]
f_timeseries._operator_sum(stack, output)[source]

Reverse polish notation operator that calculates the sum of the last two stack elements.

Parameters:

stack : iterable

The current stack.

output : output_tracker instance

Error reporting.

Returns:

iterable :

The new stack.

f_timeseries._require_stack_length(stack, length, output)[source]

Takes the requested number of elements from the stack.

Parameters:

stack : iterable

The current stack.

length : int

The number of elements to take from the end of the stack.

output : output_tracker instance

Error reporting.

Returns:

tuple :

Tuple of length two with iterables: the new stack and the popped entries.

f_timeseries.main()[source]

Main wrapper.

Table Of Contents

Previous topic

f_extract.py

Next topic

Common information

This Page