TNG API  1.7.8
A flexible binary trajectory format
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
TNG: A flexible binary trajectory format

Introduction

The TNG format is developed as part of the ScalaLife EU project. It is flexible by design to allow parallel writing, custom data blocks, different output frequencies and different compression algorithms.

Each block can contain MD5 hashes to verify data integrity and the file can be signed by the user to ensure that the origin is correct.

The intention is that the API and ABI should be stable, but it is still possible that future changes might make that impossible, in which case that will be clarified.

The API and all examples are released without any warranties. Use them at your own risk.

Authors

The TNG trajectory format is developed by:

Magnus Lundborg magnu.nosp@m.s.lu.nosp@m.ndbor.nosp@m.g@sc.nosp@m.ilife.nosp@m.lab..nosp@m.se

Daniel SpÄngberg danie.nosp@m.ls@m.nosp@m.kem.u.nosp@m.u.se

Rossen Apostolov rosse.nosp@m.n@kt.nosp@m.h.se

The API is implemented mainly by:

Magnus Lundborg

License

Copyright (c) 2012, The GROMACS development team. check out http://www.gromacs.org for more information.

The TNG API is released under the Revised BSD License and is free to redistribute according to that license.

A license file (named COPYING) should be included with each copy of the API.

Installation

* mkdir build
*
* cd build
*
* cmake ..
*
* make
*
* make install
*

Test by running:

* bin/tests/tng_testing
*

Change Log

See git log for full revision history.

Revisions

v. 1.7 - Fifth stable release of the API

   - Added function tng_util_num_frames_with_data_of_block_id_get().
   - Merged some functions and data structures
     to make less difference between data blocks.
   - Bugs fixed

v. 1.6 - Fourth stable release of the API.

   - Removed OpenMP option when building.
   - Functionality for migrating data blocks.
   - Improved handling of molecules.
   - Improved installation of TNG documentation.
   - Enhancements to CMake usage.
   - Required CMake version raised to 2.8.8.
   - Bugs fixed.

v. 1.5 - Third stable release of the API.

   - Fortran wrapper split into separate file
   - Added more block IDs.
   - Some new functions and utility functions added.
   - Improved compression precision settings.
   - Improved tests.
   - Make appending to file work better.
   - Modified CMake settings
   - Bugs fixed

v. 1.4 - Changed from LGPL to the Revised BSD License.

   - More flexible support for digital signatures in header.
   - Block ID numbers changed.

v. 1.3 - Second stable release of the API.

 - Added multiplication factor for coordinate units to general info.
 - Added time stamps and time per frame in frame sets.
 - High-level API functions added (not for managing molecules yet)
 - Added functions for reading data blocks into 1D arrays.
 - TNG compression added.
 - C++ interface added.
 - Avoid memory allocation if no data is submitted when adding data
   blocks.
 - Added function tng_num_frames_per_frame_set_set
 - Added data block IDs for charges, b-factors and occupancy.
 - GZIP compression added.
 - Fixed bug when updating MD5 hashes of data blocks.
 - Fixed bug in chain_name_of_particle_get(...)
 - Update frame set pointers properly.
 - Moved fortran wrapper from header file to source file.
 - Write sparse data in mdrun examples.
 - Fixed bugs related to reading and writing sparse data.
 - Fixed memory leak for non-trajectory particle data blocks.
 - Fixed bug when writing data blocks.
 - Fixed wrong values in dependency constants
 - Write box shape, partial charges and annotation data in tng_testing
 - Bug fixes in tng_testing (frame sets not written before)

v. 1.0 - First stable release of the API.

Examples

There are some examples of how to use the library located in src/tests/

TNG files

The build directory contains an example_files directory, which in turn contains a very short example of a TNG file containing a few water molecules, a box shape description and positions in 10 frames.

It is also possible to run the bin/examples/md_openmp_util (see src/tests/md_openmp_util.c) testing program, which will save MD simulations output to a new file (saved in the example_files directory).

These files can be read using the bin/examples/tng_io_read_pos_util program.

C

Example writing data to a TNG file (just an excerpt):

* for ( step = 1; step < step_num; step++ )
* {
* compute ( np, nd, pos, vel, mass, force, &potential, &kinetic );
*
* if(step % step_save == 0)
* {
* // Write positions, velocities and forces
* if(tng_util_pos_write(traj, step, pos) != TNG_SUCCESS)
* {
* printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
* break;
* }
* if(tng_util_vel_write(traj, step, vel) != TNG_SUCCESS)
* {
* printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
* break;
* }
* if(tng_util_force_write(traj, step, force) != TNG_SUCCESS)
* {
* printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
* break;
* }
* }
* update ( np, nd, pos, vel, force, acc, mass, dt );
* }
*

Example reading positions from a TNG file:

* #include <stdlib.h>
* #include <stdio.h>
* #include "tng/tng_io.h"
*
* int main(int argc, char **argv)
* {
* // Assume that the data is stored as floats. The data is placed in 1-D
* // arrays
* float *positions = 0, *box_shape = 0;
* int64_t n_particles, n_frames, tot_n_frames, stride_length, i, j;
* // Set a default frame range
* int64_t first_frame = 0, last_frame = 5000;
* int k;
*
* // A reference must be passed to allocate memory
* tng_util_trajectory_open(argv[1], 'r', &traj);
*
* if(tng_num_frames_get(traj, &tot_n_frames) != TNG_SUCCESS)
* {
* printf("Cannot determine the number of frames in the file\n");
* exit(1);
* }
*
* if(tng_num_particles_get(traj, &n_particles) != TNG_SUCCESS)
* {
* printf("Cannot determine the number of particles in the file\n");
* exit(1);
* }
*
* printf("%"PRId64" frames in file\n", tot_n_frames);
*
* if(last_frame > tot_n_frames - 1)
* {
* last_frame = tot_n_frames - 1;
* }
*
* if(tng_util_box_shape_read(traj, &box_shape, &stride_length) ==
* {
* printf("Simulation box shape: ");
* for(i=0; i < 9; i++)
* {
* printf("%f ", box_shape[i]);
* }
* printf("\n");
* }
* else
* {
* printf("Simulation box shape not set in the file (or could not be read)\n");
* }
*
* n_frames = last_frame - first_frame + 1;
*
*
* // Get the positions of all particles in the requested frame range.
* // The positions are stored in the positions array.
* // N.B. No proper error checks.
* if(tng_util_pos_read_range(traj, 0, last_frame, &positions, &stride_length)
* {
* // Print the positions of the wanted particle (zero based)
* for(i=0; i < n_frames; i += stride_length)
* {
* printf("\nFrame %"PRId64":\n", first_frame + i);
* for(j=0; j < n_particles; j++)
* {
* printf("Atom nr: %"PRId64"", j);
* for(k=0; k < 3; k++)
* {
* printf("\t%f", positions[i/stride_length*n_particles*
* 3+j*3+k]);
* }
* printf("\n");
* }
* }
* }
* else
* {
* printf("Cannot read positions\n");
* }
*
* // Free memory
* if(positions)
* {
* free(positions);
* }
*
* return(0);
* }
*
*

Fortran

The TNG library can be used from Fortran. It requires cray pointers, which are not part of the Fortran 77 standard, but available in most compilers.

To compile the fortran example -DTNG_BUILD_FORTRAN=ON needs to be specified when running cmake.