1 /* This code is part of the tng binary trajectory format.
3 * Written by Magnus Lundborg
4 * Copyright (c) 2012-2014, The GROMACS development team.
5 * Check out http://www.gromacs.org for more information.
8 * This program is free software; you can redistribute it and/or
9 * modify it under the terms of the Revised BSD License.
13 * @brief API for input and output of tng trajectory files
14 * @mainpage TNG: A flexible binary trajectory format
15 * @section intro_sec Introduction
17 * The TNG format is developed as part of the ScalaLife EU project.
18 * It is flexible by design to allow parallel writing, custom data blocks,
19 * different output frequencies and different compression algorithms.
21 * Each block can contain MD5 hashes to verify data integrity and the file
22 * can be signed by the user to ensure that the origin is correct.
24 * The intention is that the API and ABI should be stable, but it is
25 * still possible that future changes might make that impossible, in which
26 * case that will be clarified.
28 * The API and all examples are released without any warranties. Use them at
31 * @section authors_sec Authors
33 * The TNG trajectory format is developed by:
35 * Magnus Lundborg magnus.lundborg@scilifelab.se
37 * Daniel SpÄngberg daniels@mkem.uu.se
39 * Rossen Apostolov rossen@kth.se
41 * The API is implemented mainly by:
47 * Copyright (c) 2012, The GROMACS development team.
48 * check out http://www.gromacs.org for more information.
50 * The TNG API is released under the Revised BSD License and is free to
51 * redistribute according to that license.
53 * A license file (named COPYING) should be included with each copy of the API.
55 * @section install_sec Installation
70 * bin/tests/tng_testing
73 * @section change_sec Change Log
75 * See git log for full revision history.
79 * v. 1.7 - Fifth stable release of the API
81 * - Added function tng_util_num_frames_with_data_of_block_id_get().
82 * - Merged some functions and data structures
83 * to make less difference between data blocks.
86 * v. 1.6 - Fourth stable release of the API.
88 * - Removed OpenMP option when building.
89 * - Functionality for migrating data blocks.
90 * - Improved handling of molecules.
91 * - Improved installation of TNG documentation.
92 * - Enhancements to CMake usage.
93 * - Required CMake version raised to 2.8.8.
96 * v. 1.5 - Third stable release of the API.
98 * - Fortran wrapper split into separate file
99 * - Added more block IDs.
100 * - Some new functions and utility functions added.
101 * - Improved compression precision settings.
103 * - Make appending to file work better.
104 * - Modified CMake settings
107 * v. 1.4 - Changed from LGPL to the Revised BSD License.
109 * - More flexible support for digital signatures in header.
110 * - Block ID numbers changed.
112 * v. 1.3 - Second stable release of the API.
114 * - Added multiplication factor for coordinate units to general info.
115 * - Added time stamps and time per frame in frame sets.
116 * - High-level API functions added (not for managing molecules yet)
117 * - Added functions for reading data blocks into 1D arrays.
118 * - TNG compression added.
119 * - C++ interface added.
120 * - Avoid memory allocation if no data is submitted when adding data
122 * - Added function tng_num_frames_per_frame_set_set
123 * - Added data block IDs for charges, b-factors and occupancy.
124 * - GZIP compression added.
125 * - Fixed bug when updating MD5 hashes of data blocks.
126 * - Fixed bug in chain_name_of_particle_get(...)
127 * - Update frame set pointers properly.
128 * - Moved fortran wrapper from header file to source file.
129 * - Write sparse data in mdrun examples.
130 * - Fixed bugs related to reading and writing sparse data.
131 * - Fixed memory leak for non-trajectory particle data blocks.
132 * - Fixed bug when writing data blocks.
133 * - Fixed wrong values in dependency constants
134 * - Write box shape, partial charges and annotation data in tng_testing
135 * - Bug fixes in tng_testing (frame sets not written before)
137 * v. 1.0 - First stable release of the API.
140 * @section examples_sec Examples
142 * There are some examples of how to use the library located in src/tests/
144 * @subsection tng_subsec TNG files
146 * The build directory contains an example_files directory, which in turn
147 * contains a very short example of a TNG file containing a few water molecules,
148 * a box shape description and positions in 10 frames.
150 * It is also possible to run the bin/examples/md_openmp_util
151 * (see src/tests/md_openmp_util.c)
152 * testing program, which will save MD simulations output to a new file
153 * (saved in the example_files directory).
155 * These files can be read using the bin/examples/tng_io_read_pos_util
158 * @subsection c_subsec C
160 * Example writing data to a TNG file (just an excerpt):
162 * for ( step = 1; step < step_num; step++ )
164 * compute ( np, nd, pos, vel, mass, force, &potential, &kinetic );
166 * if(step % step_save == 0)
168 * // Write positions, velocities and forces
169 * if(tng_util_pos_write(traj, step, pos) != TNG_SUCCESS)
171 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
174 * if(tng_util_vel_write(traj, step, vel) != TNG_SUCCESS)
176 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
179 * if(tng_util_force_write(traj, step, force) != TNG_SUCCESS)
181 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
185 * update ( np, nd, pos, vel, force, acc, mass, dt );
189 * Example reading positions from a TNG file:
191 * #include <stdlib.h>
193 * #include "tng/tng_io.h"
195 * int main(int argc, char **argv)
197 * tng_trajectory_t traj;
198 * // Assume that the data is stored as floats. The data is placed in 1-D
200 * float *positions = 0, *box_shape = 0;
201 * int64_t n_particles, n_frames, tot_n_frames, stride_length, i, j;
202 * // Set a default frame range
203 * int64_t first_frame = 0, last_frame = 5000;
206 * // A reference must be passed to allocate memory
207 * tng_util_trajectory_open(argv[1], 'r', &traj);
209 * if(tng_num_frames_get(traj, &tot_n_frames) != TNG_SUCCESS)
211 * printf("Cannot determine the number of frames in the file\n");
212 * tng_util_trajectory_close(&traj);
216 * if(tng_num_particles_get(traj, &n_particles) != TNG_SUCCESS)
218 * printf("Cannot determine the number of particles in the file\n");
219 * tng_util_trajectory_close(&traj);
223 * printf("%"PRId64" frames in file\n", tot_n_frames);
225 * if(last_frame > tot_n_frames - 1)
227 * last_frame = tot_n_frames - 1;
230 * if(tng_util_box_shape_read(traj, &box_shape, &stride_length) ==
233 * printf("Simulation box shape: ");
234 * for(i=0; i < 9; i++)
236 * printf("%f ", box_shape[i]);
242 * printf("Simulation box shape not set in the file (or could not be read)\n");
245 * n_frames = last_frame - first_frame + 1;
248 * // Get the positions of all particles in the requested frame range.
249 * // The positions are stored in the positions array.
250 * // N.B. No proper error checks.
251 * if(tng_util_pos_read_range(traj, 0, last_frame, &positions, &stride_length)
254 * // Print the positions of the wanted particle (zero based)
255 * for(i=0; i < n_frames; i += stride_length)
257 * printf("\nFrame %"PRId64":\n", first_frame + i);
258 * for(j=0; j < n_particles; j++)
260 * printf("Atom nr: %"PRId64"", j);
261 * for(k=0; k < 3; k++)
263 * printf("\t%f", positions[i/stride_length*n_particles*
272 * printf("Cannot read positions\n");
280 * tng_util_trajectory_close(&traj);
287 * @subsection fortran_subsec Fortran
289 * The TNG library can be used from Fortran. It requires cray pointers, which
290 * are not part of the Fortran 77 standard, but available in most compilers.
292 * To compile the fortran example -DTNG_BUILD_FORTRAN=ON needs to be specified when
304 #include "tng_io_fwd.h"
306 #ifdef USE_STD_INTTYPES_H
307 #include <inttypes.h>
309 /* Visual Studio does not contain inttypes.h and stdint.h. Some defines and
310 * typedefs are used from the GNU C Library */
313 typedef __int32 int32_t;
314 typedef unsigned __int32 uint32_t;
315 typedef __int64 int64_t;
316 typedef unsigned __int64 uint64_t;
320 #endif /* _MSC_VER */
322 /* This is from inttypes.h (GNU C Library) */
323 /* The ISO C99 standard specifies that these macros must only be
324 defined if explicitly requested. */
325 #if !defined __cplusplus || defined __STDC_FORMAT_MACROS
327 # if __WORDSIZE == 64
328 # define __PRI64_PREFIX "l"
329 # define __PRIPTR_PREFIX "l"
331 # define __PRI64_PREFIX "ll"
332 # define __PRIPTR_PREFIX
335 /* From stdint.h (GNU C Library) */
336 /* Macros for printing format specifiers. */
337 /* Decimal notation. */
339 # define PRId64 __PRI64_PREFIX "d"
343 # define PRIu64 __PRI64_PREFIX "u"
348 #endif /* USE_STD_INTTYPES_H */
351 #if defined(WIN32) || defined(_WIN32) || defined(WIN64) || defined(_WIN64)
353 #endif /* win32... */
354 #endif /* not defined USE_WINDOWS */
356 #ifndef DECLSPECDLLEXPORT
358 #define DECLSPECDLLEXPORT __declspec(dllexport)
359 #else /* USE_WINDOWS */
360 #define DECLSPECDLLEXPORT
361 #endif /* USE_WINDOWS */
362 #endif /* DECLSPECDLLEXPORT */
364 /** Flag to indicate frame dependent data. */
365 #define TNG_FRAME_DEPENDENT 1
366 /** Flag to indicate particle dependent data. */
367 #define TNG_PARTICLE_DEPENDENT 2
369 /** The maximum length of a date string */
370 #define TNG_MAX_DATE_STR_LEN 24
371 /** The length of an MD5 hash */
372 #define TNG_MD5_HASH_LEN 16
373 /** The maximum allowed length of a string */
374 #define TNG_MAX_STR_LEN 1024
377 #define TNG_ASSERT(cnd, msg) if(!(cnd)) {printf("%s\n", msg); assert(cnd);}
379 #define TNG_ASSERT(cnd, msg) (void)0;
382 /** Flag to specify the endianness of a TNG file */
383 typedef enum {TNG_BIG_ENDIAN,
384 TNG_LITTLE_ENDIAN} tng_file_endianness;
386 /** Flag to specify the endianness of 32 bit values of the current architecture. */
387 typedef enum {TNG_BIG_ENDIAN_32,
388 TNG_LITTLE_ENDIAN_32,
389 TNG_BYTE_PAIR_SWAP_32} tng_endianness_32;
391 /** Flag to specify the endianness of 64 bit values of the current architecture. */
392 typedef enum {TNG_BIG_ENDIAN_64,
393 TNG_LITTLE_ENDIAN_64,
395 TNG_BYTE_PAIR_SWAP_64,
396 TNG_BYTE_SWAP_64} tng_endianness_64;
398 /** Compression mode is specified in each data block */
399 typedef enum {TNG_UNCOMPRESSED,
402 TNG_GZIP_COMPRESSION} tng_compression;
405 typedef enum {TNG_NO_HASH,
407 TNG_SHA256} tng_hash_type;
409 /** Non trajectory blocks come before the first frame set block */
410 typedef enum {TNG_NON_TRAJECTORY_BLOCK, TNG_TRAJECTORY_BLOCK} tng_block_type;
412 /** @defgroup def1 Standard non-trajectory blocks
413 * Block IDs of standard non-trajectory blocks.
416 #define TNG_GENERAL_INFO 0x0000000000000000LL
417 #define TNG_MOLECULES 0x0000000000000001LL
418 #define TNG_TRAJECTORY_FRAME_SET 0x0000000000000002LL
419 #define TNG_PARTICLE_MAPPING 0x0000000000000003LL
422 /** @defgroup def2 Standard trajectory blocks
423 * Block IDs of standard trajectory blocks. Box shape and partial charges can
424 * be either trajectory blocks or non-trajectory blocks
427 #define TNG_TRAJ_BOX_SHAPE 0x0000000010000000LL
428 #define TNG_TRAJ_POSITIONS 0x0000000010000001LL
429 #define TNG_TRAJ_VELOCITIES 0x0000000010000002LL
430 #define TNG_TRAJ_FORCES 0x0000000010000003LL
431 #define TNG_TRAJ_PARTIAL_CHARGES 0x0000000010000004LL
432 #define TNG_TRAJ_FORMAL_CHARGES 0x0000000010000005LL
433 #define TNG_TRAJ_B_FACTORS 0x0000000010000006LL
434 #define TNG_TRAJ_ANISOTROPIC_B_FACTORS 0x0000000010000007LL
435 #define TNG_TRAJ_OCCUPANCY 0x0000000010000008LL
436 #define TNG_TRAJ_GENERAL_COMMENTS 0x0000000010000009LL
440 /** @defgroup def3 GROMACS data block IDs
441 * Block IDs of data blocks specific to GROMACS.
444 #define TNG_GMX_LAMBDA 0x1000000010000000LL
445 #define TNG_GMX_ENERGY_ANGLE 0x1000000010000001LL
446 #define TNG_GMX_ENERGY_RYCKAERT_BELL 0x1000000010000002LL
447 #define TNG_GMX_ENERGY_LJ_14 0x1000000010000003LL
448 #define TNG_GMX_ENERGY_COULOMB_14 0x1000000010000004LL
449 #define TNG_GMX_ENERGY_LJ_(SR) 0x1000000010000005LL
450 #define TNG_GMX_ENERGY_COULOMB_(SR) 0x1000000010000006LL
451 #define TNG_GMX_ENERGY_COUL_RECIP 0x1000000010000007LL
452 #define TNG_GMX_ENERGY_POTENTIAL 0x1000000010000008LL
453 #define TNG_GMX_ENERGY_KINETIC_EN 0x1000000010000009LL
454 #define TNG_GMX_ENERGY_TOTAL_ENERGY 0x1000000010000010LL
455 #define TNG_GMX_ENERGY_TEMPERATURE 0x1000000010000011LL
456 #define TNG_GMX_ENERGY_PRESSURE 0x1000000010000012LL
457 #define TNG_GMX_ENERGY_CONSTR_RMSD 0x1000000010000013LL
458 #define TNG_GMX_ENERGY_BOX_X 0x1000000010000014LL
459 #define TNG_GMX_ENERGY_BOX_Y 0x1000000010000015LL
460 #define TNG_GMX_ENERGY_BOX_Z 0x1000000010000016LL
461 #define TNG_GMX_ENERGY_VOLUME 0x1000000010000017LL
462 #define TNG_GMX_ENERGY_DENSITY 0x1000000010000018LL
463 #define TNG_GMX_ENERGY_PV 0x1000000010000019LL
464 #define TNG_GMX_ENERGY_ENTHALPY 0x1000000010000020LL
465 #define TNG_GMX_ENERGY_VIR_XX 0x1000000010000021LL
466 #define TNG_GMX_ENERGY_VIR_XY 0x1000000010000022LL
467 #define TNG_GMX_ENERGY_VIR_XZ 0x1000000010000023LL
468 #define TNG_GMX_ENERGY_VIR_YX 0x1000000010000024LL
469 #define TNG_GMX_ENERGY_VIR_YY 0x1000000010000025LL
470 #define TNG_GMX_ENERGY_VIR_YZ 0x1000000010000026LL
471 #define TNG_GMX_ENERGY_VIR_ZX 0x1000000010000027LL
472 #define TNG_GMX_ENERGY_VIR_ZY 0x1000000010000028LL
473 #define TNG_GMX_ENERGY_VIR_ZZ 0x1000000010000029LL
474 #define TNG_GMX_ENERGY_PRES_XX 0x1000000010000030LL
475 #define TNG_GMX_ENERGY_PRES_XY 0x1000000010000031LL
476 #define TNG_GMX_ENERGY_PRES_XZ 0x1000000010000032LL
477 #define TNG_GMX_ENERGY_PRES_YX 0x1000000010000033LL
478 #define TNG_GMX_ENERGY_PRES_YY 0x1000000010000034LL
479 #define TNG_GMX_ENERGY_PRES_YZ 0x1000000010000035LL
480 #define TNG_GMX_ENERGY_PRES_ZX 0x1000000010000036LL
481 #define TNG_GMX_ENERGY_PRES_ZY 0x1000000010000037LL
482 #define TNG_GMX_ENERGY_PRES_ZZ 0x1000000010000038LL
483 #define TNG_GMX_ENERGY_SURFXSURFTEN 0x1000000010000039LL
484 #define TNG_GMX_ENERGY_T_SYSTEM 0x1000000010000040LL
485 #define TNG_GMX_ENERGY_LAMB_SYSTEM 0x1000000010000041LL
486 #define TNG_GMX_SELECTION_GROUP_NAMES 0x1000000010000042LL
487 #define TNG_GMX_ATOM_SELECTION_GROUP 0x1000000010000043LL
490 /** Flag to specify if a data block contains data related to particles or not.*/
491 typedef enum {TNG_NON_PARTICLE_BLOCK_DATA,
492 TNG_PARTICLE_BLOCK_DATA} tng_particle_dependency;
495 typedef enum {TNG_FALSE, TNG_TRUE} tng_bool;
497 /** Flag to specify if the number of atoms change throughout the trajectory or
498 * if it is constant. */
499 typedef enum {TNG_CONSTANT_N_ATOMS, TNG_VARIABLE_N_ATOMS}
500 tng_variable_n_atoms_flag;
502 /** Return values of API functions. TNG_SUCCESS means that the operation
503 * was successful. TNG_FAILURE means that the operation failed for some
504 * reason, but it is possible to try to continue anyhow. TNG_CRITICAL
505 * means that the error is irrecoverable. */
506 typedef enum {TNG_SUCCESS, TNG_FAILURE, TNG_CRITICAL} tng_function_status;
508 /** If tng_hash_mode == TNG_USE_HASH md5 hashes will be written to output files
509 * and when reading a file the md5 hashes of the contents will be compared to
510 * those in the file (for each block) in order to ensure data integrity */
511 typedef enum {TNG_SKIP_HASH, TNG_USE_HASH} tng_hash_mode;
513 /** Possible formats of data block contents */
514 typedef enum {TNG_CHAR_DATA,
517 TNG_DOUBLE_DATA} tng_data_type;
520 struct tng_trajectory;
526 struct tng_gen_block;
527 struct tng_particle_mapping;
528 struct tng_trajectory_frame_set;
529 struct tng_particle_data;
530 struct tng_non_particle_data;
532 /** Data can be either double, float, int or a string */
546 /** @defgroup group1 Low-level API
547 * These functions give detailed control of the TNG data management. Most
548 * things can be done using the more convenient high-level API functions
554 * @brief Get the major version of the TNG library.
555 * @param tng_data is a trajectory data container, it does not have
556 * to be initialized beforehand.
557 * @param version is pointing to a value set to the major version of
559 * @return TNG_SUCCESS (0) if successful.
561 tng_function_status DECLSPECDLLEXPORT tng_version_major
562 (const tng_trajectory_t tng_data,
566 * @brief Get the minor version of the TNG library.
567 * @param tng_data is a trajectory data container, it does not have
568 * to be initialized beforehand.
569 * @param version is pointing to a value set to the minor version of
571 * @return TNG_SUCCESS (0) if successful.
573 tng_function_status DECLSPECDLLEXPORT tng_version_minor
574 (const tng_trajectory_t tng_data,
578 * @brief Get the patch level of the TNG library.
579 * @param tng_data is a trajectory data container, it does not have
580 * to be initialized beforehand.
581 * @param patch_level is the string to fill with the full version,
582 * memory must be allocated before.
583 * @return TNG_SUCCESS (0) if successful.
585 tng_function_status DECLSPECDLLEXPORT tng_version_patchlevel
586 (const tng_trajectory_t tng_data,
590 * @brief Get the full version string of the TNG library.
591 * @param tng_data is a trajectory data container, it does not have
592 * to be initialized beforehand.
593 * @param version is pointing to a value set to the major version of
595 * @param max_len maximum char length of the string, i.e. how much memory has
596 * been reserved for version. This includes \0 terminating character.
597 * @pre \code version != 0 \endcode The pointer to the name string
598 * must not be a NULL pointer.
599 * @return TNG_SUCCESS (0) if successful.
601 tng_function_status DECLSPECDLLEXPORT tng_version
602 (const tng_trajectory_t tng_data,
607 * @brief Setup a trajectory data container.
608 * @param tng_data_p a pointer to memory to initialise as a trajectory.
609 * @pre tng_data_p must not be pointing at a reserved memory block.
610 * @details Memory is allocated during initialisation.
611 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
614 tng_function_status DECLSPECDLLEXPORT tng_trajectory_init
615 (tng_trajectory_t *tng_data_p);
618 * @brief Clean up a trajectory data container.
619 * @param tng_data_p a pointer to the trajectory data to destroy.
620 * @details All allocated memory in the data structure is freed, as well as
622 * @return TNG_SUCCESS (0) if successful.
624 tng_function_status DECLSPECDLLEXPORT tng_trajectory_destroy
625 (tng_trajectory_t *tng_data_p);
628 * @brief Copy a trajectory data container (dest is setup as well).
629 * @details This initialises dest and copies only what is absolute necessary for
630 * parallel i/o. This can be used inside pragma omp for setting up a thread
631 * local copy of src. It can be freed (using tng_trajectory_destroy) at the
632 * end of the parallel block.
633 * @param src the original trajectory.
634 * @param dest_p a pointer to memory to initialise as a trajectory.
635 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
636 * must be initialised before using it.
637 * @pre tng_data_p must not be pointing at a reserved memory block.
638 * @details Memory is allocated during initialisation.
639 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
642 tng_function_status DECLSPECDLLEXPORT tng_trajectory_init_from_src
643 (const tng_trajectory_t src, tng_trajectory_t *dest_p);
646 * @brief Get the name of the input file.
647 * @param tng_data the trajectory of which to get the input file name.
648 * @param file_name the string to fill with the name of the input file,
649 * memory must be allocated before.
650 * @param max_len maximum char length of the string, i.e. how much memory has
651 * been reserved for file_name. This includes \0 terminating character.
652 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
653 * must be initialised before using it.
654 * @pre \code file_name != 0 \endcode The pointer to the file name string
655 * must not be a NULL pointer.
656 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
657 * has occurred (source string longer than destination string).
659 tng_function_status DECLSPECDLLEXPORT tng_input_file_get
660 (const tng_trajectory_t tng_data,
661 char *file_name, const int max_len);
664 * @brief Set the name of the input file.
665 * @param tng_data the trajectory of which to set the input file name.
666 * @param file_name the name of the input file.
667 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
668 * must be initialised before using it.
669 * @pre \code file_name != 0 \endcode The pointer to the file name string
670 * must not be a NULL pointer.
671 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
674 tng_function_status DECLSPECDLLEXPORT tng_input_file_set
675 (const tng_trajectory_t tng_data,
676 const char *file_name);
679 * @brief Get the name of the output file.
680 * @param tng_data the trajectory of which to get the input file name.
681 * @param file_name the string to fill with the name of the output file,
682 * memory must be allocated before.
683 * @param max_len maximum char length of the string, i.e. how much memory has
684 * been reserved for file_name. This includes \0 terminating character.
685 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
686 * must be initialised before using it.
687 * @pre \code file_name != 0 \endcode The pointer to the file name string
688 * must not be a NULL pointer.
689 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
690 * has occurred (source string longer than destination string).
692 tng_function_status DECLSPECDLLEXPORT tng_output_file_get
693 (const tng_trajectory_t tng_data,
694 char *file_name, const int max_len);
697 * @brief Set the name of the output file.
698 * @param tng_data the trajectory of which to set the output file name.
699 * @param file_name the name of the output file.
700 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
701 * must be initialised before using it.
702 * @pre \code file_name != 0 \endcode The pointer to the file name string
703 * must not be a NULL pointer.
704 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
707 tng_function_status DECLSPECDLLEXPORT tng_output_file_set
708 (const tng_trajectory_t tng_data,
709 const char *file_name);
712 * @brief Set the name of the output file for appending. The output file
713 * will not be overwritten.
714 * @param tng_data the trajectory of which to set the output file name.
715 * @param file_name the name of the output file to append to.
716 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
717 * must be initialised before using it.
718 * @pre \code file_name != 0 \endcode The pointer to the file name string
719 * must not be a NULL pointer.
720 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
723 tng_function_status DECLSPECDLLEXPORT tng_output_append_file_set
724 (const tng_trajectory_t tng_data,
725 const char *file_name);
728 * @brief Get the endianness of the output file.
729 * @param tng_data the trajectory of which to get the endianness of the current
731 * @param endianness will contain the enumeration of the endianness.
732 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
733 * must be initialised before using it.
734 * @pre \code endianness != 0 \endcode The pointer to the endianness container
735 * must not be a NULL pointer.
736 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness
737 * could not be retrieved.
739 tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_get
740 (const tng_trajectory_t tng_data, tng_file_endianness *endianness);
743 * @brief Set the endianness of the output file.
744 * @param tng_data the trajectory of which to set the endianness of the current
746 * @param endianness the enumeration of the endianness, can be either
747 * TNG_BIG_ENDIAN (0) or TNG_LITTLE_ENDIAN (1).
748 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
749 * must be initialised before using it.
750 * @details The endianness cannot be changed after file output has started.
751 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness
754 tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_set
755 (const tng_trajectory_t tng_data,
756 const tng_file_endianness endianness);
759 * @brief Get the name of the program used when creating the trajectory.
760 * @param tng_data the trajectory of which to get the program name.
761 * @param name the string to fill with the name of the program,
762 * memory must be allocated before.
763 * @param max_len maximum char length of the string, i.e. how much memory has
764 * been reserved for name. This includes \0 terminating character.
765 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
766 * must be initialised before using it.
767 * @pre \code name != 0 \endcode The pointer to the name string
768 * must not be a NULL pointer.
769 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
770 * has occurred (source string longer than destination string).
772 tng_function_status DECLSPECDLLEXPORT tng_first_program_name_get
773 (const tng_trajectory_t tng_data,
774 char *name, const int max_len);
777 * @brief Set the name of the program used when creating the trajectory.
778 * @param tng_data the trajectory of which to set the program name.
779 * @param new_name is a string containing the wanted name.
780 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
781 * must be initialised before using it.
782 * @pre \code new_name != 0 \endcode The pointer to the new_name string
783 * must not be a NULL pointer.
784 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
787 tng_function_status DECLSPECDLLEXPORT tng_first_program_name_set
788 (const tng_trajectory_t tng_data,
789 const char *new_name);
792 * @brief Get the name of the program used when last modifying the trajectory.
793 * @param tng_data the trajectory of which to get the program name.
794 * @param name the string to fill with the name of the program,
795 * memory must be allocated before.
796 * @param max_len maximum char length of the string, i.e. how much memory has
797 * been reserved for name. This includes \0 terminating character.
798 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
799 * must be initialised before using it.
800 * @pre \code name != 0 \endcode The pointer to the name string
801 * must not be a NULL pointer.
802 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
803 * has occurred (source string longer than destination string).
805 tng_function_status DECLSPECDLLEXPORT tng_last_program_name_get
806 (const tng_trajectory_t tng_data,
807 char *name, const int max_len);
810 * @brief Set the name of the program used when last modifying the trajectory.
811 * @param tng_data the trajectory of which to set the program name.
812 * @param new_name is a string containing the wanted name.
813 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
814 * must be initialised before using it.
815 * @pre \code new_name != 0 \endcode The pointer to the new_name string
816 * must not be a NULL pointer.
817 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
820 tng_function_status DECLSPECDLLEXPORT tng_last_program_name_set
821 (const tng_trajectory_t tng_data,
822 const char *new_name);
825 * @brief Get the name of the user who created the trajectory.
826 * @param tng_data the trajectory of which to get the user name.
827 * @param name the string to fill with the name of the user,
828 * memory must be allocated before.
829 * @param max_len maximum char length of the string, i.e. how much memory has
830 * been reserved for name. This includes \0 terminating character.
831 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
832 * must be initialised before using it.
833 * @pre \code name != 0 \endcode The pointer to the name string
834 * must not be a NULL pointer.
835 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
836 * has occurred (source string longer than destination string).
838 tng_function_status DECLSPECDLLEXPORT tng_first_user_name_get
839 (const tng_trajectory_t tng_data,
840 char *name, const int max_len);
843 * @brief Set the name of the user who created the trajectory.
844 * @param tng_data the trajectory of which to set the user name.
845 * @param new_name is a string containing the wanted name.
846 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
847 * must be initialised before using it.
848 * @pre \code new_name != 0 \endcode The pointer to the new_name string
849 * must not be a NULL pointer.
850 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
853 tng_function_status DECLSPECDLLEXPORT tng_first_user_name_set
854 (const tng_trajectory_t tng_data,
855 const char *new_name);
858 * @brief Get the name of the user who last modified the trajectory.
859 * @param tng_data the trajectory of which to get the user name.
860 * @param name the string to fill with the name of the user,
861 * memory must be allocated before.
862 * @param max_len maximum char length of the string, i.e. how much memory has
863 * been reserved for name. This includes \0 terminating character.
864 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
865 * must be initialised before using it.
866 * @pre \code name != 0 \endcode The pointer to the name string
867 * must not be a NULL pointer.
868 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
869 * has occurred (source string longer than destination string).
871 tng_function_status DECLSPECDLLEXPORT tng_last_user_name_get
872 (const tng_trajectory_t tng_data,
873 char *name, const int max_len);
876 * @brief Set the name of the user who last modified the trajectory.
877 * @param tng_data the trajectory of which to set the user name.
878 * @param new_name is a string containing the wanted name.
879 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
880 * must be initialised before using it.
881 * @pre \code new_name != 0 \endcode The pointer to the new_name string
882 * must not be a NULL pointer.
883 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
886 tng_function_status DECLSPECDLLEXPORT tng_last_user_name_set
887 (const tng_trajectory_t tng_data,
888 const char *new_name);
891 * @brief Get the name of the computer used when creating the trajectory.
892 * @param tng_data the trajectory of which to get the computer name.
893 * @param name the string to fill with the name of the computer,
894 * memory must be allocated before.
895 * @param max_len maximum char length of the string, i.e. how much memory has
896 * been reserved for name. This includes \0 terminating character.
897 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
898 * must be initialised before using it.
899 * @pre \code name != 0 \endcode The pointer to the name string
900 * must not be a NULL pointer.
901 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
902 * has occurred (source string longer than destination string).
904 tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_get
905 (const tng_trajectory_t tng_data,
906 char *name, const int max_len);
909 * @brief Set the name of the computer used when creating the trajectory.
910 * @param tng_data the trajectory of which to set the computer name.
911 * @param new_name is a string containing the wanted name.
912 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
913 * must be initialised before using it.
914 * @pre \code new_name != 0 \endcode The pointer to the new_name string
915 * must not be a NULL pointer.
916 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
919 tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_set
920 (const tng_trajectory_t tng_data,
921 const char *new_name);
924 * @brief Get the name of the computer used when last modifying the trajectory.
925 * @param tng_data the trajectory of which to get the computer name.
926 * @param name the string to fill with the name of the computer,
927 * memory must be allocated before.
928 * @param max_len maximum char length of the string, i.e. how much memory has
929 * been reserved for name. This includes \0 terminating character.
930 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
931 * must be initialised before using it.
932 * @pre \code name != 0 \endcode The pointer to the name string
933 * must not be a NULL pointer.
934 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
935 * has occurred (source string longer than destination string).
937 tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_get
938 (const tng_trajectory_t tng_data,
939 char *name, const int max_len);
942 * @brief Set the name of the computer used when last modifying the trajectory.
943 * @param tng_data the trajectory of which to set the computer name.
944 * @param new_name is a string containing the wanted name.
945 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
946 * must be initialised before using it.
947 * @pre \code new_name != 0 \endcode The pointer to the new_name string
948 * must not be a NULL pointer.
949 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
952 tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_set
953 (const tng_trajectory_t tng_data,
954 const char *new_name);
957 * @brief Get the pgp_signature of the user creating the trajectory.
958 * @param tng_data the trajectory of which to get the computer name.
959 * @param signature the string to fill with the signature,
960 * memory must be allocated before.
961 * @param max_len maximum char length of the string, i.e. how much memory has
962 * been reserved for name. This includes \0 terminating character.
963 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
964 * must be initialised before using it.
965 * @pre \code signature != 0 \endcode The pointer to the signature
966 * must not be a NULL pointer.
967 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
968 * has occurred (source string longer than destination string).
970 tng_function_status DECLSPECDLLEXPORT tng_first_signature_get
971 (const tng_trajectory_t tng_data,
972 char *signature, const int max_len);
975 * @brief Set the pgp_signature of the user creating the trajectory.
976 * @param tng_data the trajectory of which to set the computer name.
977 * @param signature is a string containing the pgp_signature.
978 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
979 * must be initialised before using it.
980 * @pre \code signature != 0 \endcode The pointer to the signature
981 * must not be a NULL pointer.
982 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
985 tng_function_status DECLSPECDLLEXPORT tng_first_signature_set
986 (const tng_trajectory_t tng_data,
987 const char *signature);
990 * @brief Get the pgp_signature of the user last modifying the trajectory.
991 * @param tng_data the trajectory of which to get the computer name.
992 * @param signature the string to fill with the signature,
993 * memory must be allocated before.
994 * @param max_len maximum char length of the string, i.e. how much memory has
995 * been reserved for name. This includes \0 terminating character.
996 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
997 * must be initialised before using it.
998 * @pre \code signature != 0 \endcode The pointer to the signature
999 * must not be a NULL pointer.
1000 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1001 * has occurred (source string longer than destination string).
1003 tng_function_status DECLSPECDLLEXPORT tng_last_signature_get
1004 (const tng_trajectory_t tng_data,
1005 char *signature, const int max_len);
1008 * @brief Set the pgp_signature of the user last modifying the trajectory.
1009 * @param tng_data the trajectory of which to set the computer name.
1010 * @param signature is a string containing the pgp_signature.
1011 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1012 * must be initialised before using it.
1013 * @pre \code signature != 0 \endcode The pointer to the signature
1014 * must not be a NULL pointer.
1015 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1016 * error has occured.
1018 tng_function_status DECLSPECDLLEXPORT tng_last_signature_set
1019 (const tng_trajectory_t tng_data,
1020 const char *signature);
1023 * @brief Get the name of the forcefield used in the trajectory.
1024 * @param tng_data the trajectory of which to get the forcefield name.
1025 * @param name the string to fill with the name of the forcefield,
1026 * memory must be allocated before.
1027 * @param max_len maximum char length of the string, i.e. how much memory has
1028 * been reserved for name. This includes \0 terminating character.
1029 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1030 * must be initialised before using it.
1031 * @pre \code name != 0 \endcode The pointer to the name string
1032 * must not be a NULL pointer.
1033 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1034 * has occurred (source string longer than destination string).
1036 tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_get
1037 (const tng_trajectory_t tng_data,
1038 char *name, const int max_len);
1041 * @brief Set the name of the forcefield used in the trajectory.
1042 * @param tng_data the trajectory of which to set the forcefield name.
1043 * @param new_name is a string containing the wanted name.
1044 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1045 * must be initialised before using it.
1046 * @pre \code new_name != 0 \endcode The pointer to the new_name string
1047 * must not be a NULL pointer.
1048 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1049 * error has occured.
1051 tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_set
1052 (const tng_trajectory_t tng_data,
1053 const char *new_name);
1056 * @brief Get the medium stride length of the trajectory.
1057 * @param tng_data is the trajectory from which to get the stride length.
1058 * @param len is pointing to a value set to the stride length.
1059 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1060 * must be initialised before using it.
1061 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer.
1062 * @return TNG_SUCCESS (0) if successful.
1064 tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_get
1065 (const tng_trajectory_t tng_data,
1069 * @brief Set the medium stride length of the trajectory.
1070 * @param tng_data is the trajectory of which to set the stride length.
1071 * @param len is the wanted medium stride length.
1072 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1073 * must be initialised before using it.
1074 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1077 tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_set
1078 (const tng_trajectory_t tng_data,
1082 * @brief Get the long stride length of the trajectory.
1083 * @param tng_data is the trajectory from which to get the stride length.
1084 * @param len is pointing to a value set to the stride length.
1085 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1086 * must be initialised before using it.
1087 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer.
1088 * @return TNG_SUCCESS (0) if successful.
1090 tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_get
1091 (const tng_trajectory_t tng_data,
1095 * @brief Set the long stride length of the trajectory.
1096 * @param tng_data is the trajectory of which to set the stride length.
1097 * @param len is the wanted long stride length.
1098 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1099 * must be initialised before using it.
1100 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1103 tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_set
1104 (const tng_trajectory_t tng_data,
1108 * @brief Get the current time per frame of the trajectory.
1109 * @param tng_data is the trajectory from which to get the time per frame.
1110 * @param time is pointing to a value set to the time per frame.
1111 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1112 * must be initialised before using it.
1113 * @pre \code time != 0 \endcode The pointer to time must not be a NULL pointer.
1114 * @return TNG_SUCCESS (0) if successful.
1116 tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_get
1117 (const tng_trajectory_t tng_data,
1121 * @brief Set the time per frame of the trajectory.
1122 * @param tng_data is the trajectory of which to set the time per frame.
1123 * @param time is the new time per frame.
1124 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1125 * must be initialised before using it.
1126 * @pre \code time > 0 \endcode The time per frame must be >= 0.
1127 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1130 tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_set
1131 (const tng_trajectory_t tng_data,
1135 * @brief Get the length of the input file.
1136 * @param tng_data is the trajectory from which to get the input file length.
1137 * @param len is pointing to a value set to the file length.
1138 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1139 * must be initialised before using it.
1140 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer.
1141 * @return TNG_SUCCESS (0) if successful.
1143 tng_function_status DECLSPECDLLEXPORT tng_input_file_len_get
1144 (const tng_trajectory_t tng_data,
1148 * @brief Get the number of frames in the trajectory
1149 * @param tng_data is the trajectory of which to get the number of frames.
1150 * @param n is pointing to a value set to the number of frames.
1151 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1152 * must be initialised before using it.
1153 * @pre \code tng_data->input_file != 0 \endcode An input file must be open
1154 * to find the next frame set.
1155 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1156 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1157 * has occurred (could not find last frame set).
1159 tng_function_status DECLSPECDLLEXPORT tng_num_frames_get
1160 (const tng_trajectory_t tng_data,
1164 * @brief Get the precision of lossy compression.
1165 * @param tng_data is the trajectory of which to get the compression precision.
1166 * @param precision will be pointing to the retrieved compression precision.
1167 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1168 * must be initialised before using it.
1169 * @details A compression precision of 0.001 (the default) means that the
1170 * compressed values are accurate to the third decimal. This function does
1171 * not check actual precision of compressed data, but just returns what has
1172 * previously been set using tng_compression_precision_set().
1173 * @return TNG_SUCCESS (0) if successful.
1175 tng_function_status DECLSPECDLLEXPORT tng_compression_precision_get
1176 (const tng_trajectory_t tng_data,
1180 * @brief Set the precision of lossy compression.
1181 * @param tng_data is the trajectory of which to set the compression precision.
1182 * @param precision is the new compression precision.
1183 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1184 * must be initialised before using it.
1185 * @details A compression precision of 0.001 (the default) means that the
1186 * compressed values are accurate to the third decimal.
1187 * @return TNG_SUCCESS (0) if successful.
1189 tng_function_status DECLSPECDLLEXPORT tng_compression_precision_set
1190 (const tng_trajectory_t tng_data,
1191 const double precision);
1194 * @brief Set the number of particles, in the case no molecular system is used.
1195 * @param tng_data is the trajectory of which to get the number of particles.
1196 * @param n is the number of particles to use.
1197 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1198 * must be initialised before using it.
1199 * @details When creating a molecular system the number of particles are set
1200 * automatically. This should only be used when there is no molecular system
1201 * specified or if the number of atoms needs to be overridden for some reason.
1202 * @return TNG_SUCCESS (0) if successful.
1204 tng_function_status DECLSPECDLLEXPORT tng_implicit_num_particles_set
1205 (const tng_trajectory_t tng_data,
1209 * @brief Get the current number of particles.
1210 * @param tng_data is the trajectory from which to get the number of particles.
1211 * @param n is pointing to a value set to the number of particles.
1212 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1213 * must be initialised before using it.
1214 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1215 * @details If variable number of particles are used this function will return
1216 * the number of particles in the current frame set.
1217 * @return TNG_SUCCESS (0) if successful.
1219 tng_function_status DECLSPECDLLEXPORT tng_num_particles_get
1220 (const tng_trajectory_t tng_data,
1224 * @brief Get if the number of particle can be varied during the simulation.
1225 * @param tng_data is the trajectory from which to get the number of particles.
1226 * @param variable is pointing to a value set to TNG_CONSTANT_N_ATOMS if the
1227 * number of particles cannot change or TNG_VARIABLE_N_ATOMS if the number of
1228 * particles can change.
1229 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1230 * must be initialised before using it.
1231 * @pre \code variable != 0 \endcode The pointer to variable must not be
1233 * @return TNG_SUCCESS (0) if successful.
1235 tng_function_status DECLSPECDLLEXPORT tng_num_particles_variable_get
1236 (const tng_trajectory_t tng_data,
1240 * @brief Get the number of molecule types (length of tng_data->molecules).
1241 * @param tng_data is the trajectory from which to get the number of molecules.
1242 * @param n is pointing to a value set to the number of molecule types.
1243 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1244 * must be initialised before using it.
1245 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1246 * @return TNG_SUCCESS (0) if successful.
1248 tng_function_status DECLSPECDLLEXPORT tng_num_molecule_types_get
1249 (const tng_trajectory_t tng_data,
1253 * @brief Get the current total number of molecules.
1254 * @param tng_data is the trajectory from which to get the number of molecules.
1255 * @param n is pointing to a value set to the number of molecules.
1256 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1257 * must be initialised before using it.
1258 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1259 * @details If variable number of particles are used this function will return
1260 * the total number of molecules in the current frame set.
1261 * @return TNG_SUCCESS (0) if successful.
1263 tng_function_status DECLSPECDLLEXPORT tng_num_molecules_get
1264 (const tng_trajectory_t tng_data,
1267 /** @brief Get the list of the count of each molecule.
1268 * @param tng_data is the trajectory from which to get the molecule count list.
1269 * @param mol_cnt_list is a list of the count of each molecule in the
1270 * mol system. This is a pointer to the list in the TNG container, which
1271 * means that it should be handled carefully, e.g. not freed.
1272 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1273 * must be initialised before using it.
1274 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE(1) if the list of
1275 * molecule counts was not valid.
1277 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_list_get
1278 (const tng_trajectory_t tng_data,
1279 int64_t **mol_cnt_list);
1282 * @brief Get the exponent used for distances in the trajectory.
1283 * @param tng_data is the trajectory from which to get the information.
1284 * @param exp is pointing to a value set to the distance unit exponent.
1285 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1286 * must be initialised before using it.
1287 * @pre \code exp != 0 \endcode The pointer to exp must not be a NULL pointer.
1288 * @details Example: If the distances are specified in nm (default) exp is -9.
1289 * If the distances are specified in Ă
exp is -10.
1290 * @return TNG_SUCCESS (0) if successful.
1292 tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_get
1293 (const tng_trajectory_t tng_data,
1297 * @brief Set the exponent used for distances in the trajectory.
1298 * @param tng_data is the trajectory of which to set the unit exponent.
1299 * @param exp is the distance unit exponent to use.
1300 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1301 * must be initialised before using it.
1302 * @details Example: If the distances are specified in nm (default) exp is -9.
1303 * If the distances are specified in Ă
exp is -10.
1304 * @return TNG_SUCCESS (0) if successful.
1306 tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_set
1307 (const tng_trajectory_t tng_data,
1311 * @brief Get the number of frames per frame set.
1312 * @param tng_data is the trajectory from which to get the number of frames
1314 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1315 * must be initialised before using it.
1316 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1317 * @param n is pointing to a value set to the number of frames per frame set.
1318 * @return TNG_SUCCESS (0) if successful.
1320 tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_get
1321 (const tng_trajectory_t tng_data,
1325 * @brief Set the number of frames per frame set.
1326 * @param tng_data is the trajectory of which to set the number of frames
1328 * @param n is the number of frames per frame set.
1329 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1330 * must be initialised before using it.
1331 * @details This does not affect already existing frame sets. For
1332 * consistency the number of frames per frame set should be set
1333 * betfore creating any frame sets.
1334 * @return TNG_SUCCESS (0) if successful.
1336 tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_set
1337 (const tng_trajectory_t tng_data,
1341 * @brief Get the number of frame sets.
1342 * @details This updates tng_data->n_trajectory_frame_sets before returning it.
1343 * @param tng_data is the trajectory from which to get the number of frame sets.
1344 * @param n is pointing to a value set to the number of frame sets.
1345 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1346 * must be initialised before using it.
1347 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1348 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1349 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1351 tng_function_status DECLSPECDLLEXPORT tng_num_frame_sets_get
1352 (const tng_trajectory_t tng_data,
1356 * @brief Get the current trajectory frame set.
1357 * @param tng_data is the trajectory from which to get the frame set.
1358 * @param frame_set_p will be set to point at the memory position of
1359 * the found frame set.
1360 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1361 * must be initialised before using it.
1362 * @return TNG_SUCCESS (0) if successful.
1364 tng_function_status DECLSPECDLLEXPORT tng_current_frame_set_get
1365 (const tng_trajectory_t tng_data,
1366 tng_trajectory_frame_set_t *frame_set_p);
1369 * @brief Find the requested frame set number.
1370 * @param tng_data is the trajectory from which to get the frame set.
1371 * @param nr is the frame set number to search for.
1372 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1373 * must be initialised before using it.
1374 * @pre \code nr >= 0 \endcode The frame set number (nr) must be >= 0.
1375 * @details tng_data->current_trajectory_frame_set will contain the
1376 * found trajectory if successful.
1377 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1378 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1380 tng_function_status DECLSPECDLLEXPORT tng_frame_set_nr_find
1381 (const tng_trajectory_t tng_data,
1385 * @brief Find the frame set containing a specific frame.
1386 * @param tng_data is the trajectory from which to get the frame set.
1387 * @param frame is the frame number to search for.
1388 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1389 * must be initialised before using it.
1390 * @pre \code frame >= 0 \endcode The frame number must be >= 0.
1391 * @details tng_data->current_trajectory_frame_set will contain the
1392 * found trajectory if successful.
1393 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1394 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1396 tng_function_status DECLSPECDLLEXPORT tng_frame_set_of_frame_find
1397 (const tng_trajectory_t tng_data,
1398 const int64_t frame);
1401 * @brief Get the file position of the next frame set in the input file.
1402 * @param tng_data is a trajectory data container.
1403 * @param frame_set is the frame set of which to get the position of the
1404 * following frame set.
1405 * @param pos is pointing to a value set to the file position.
1406 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1407 * must be initialised before using it.
1408 * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer.
1409 * @return TNG_SUCCESS (0) if successful.
1411 tng_function_status DECLSPECDLLEXPORT tng_frame_set_next_frame_set_file_pos_get
1412 (const tng_trajectory_t tng_data,
1413 const tng_trajectory_frame_set_t frame_set,
1417 * @brief Get the file position of the previous frame set in the input file.
1418 * @param tng_data is a trajectory data container.
1419 * @param frame_set is the frame set of which to get the position of the
1420 * previous frame set.
1421 * @param pos is pointing to a value set to the file position.
1422 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1423 * must be initialised before using it.
1424 * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer.
1425 * @return TNG_SUCCESS (0) if successful.
1427 tng_function_status DECLSPECDLLEXPORT tng_frame_set_prev_frame_set_file_pos_get
1428 (const tng_trajectory_t tng_data,
1429 const tng_trajectory_frame_set_t frame_set,
1433 * @brief Get the first and last frames of the frame set.
1434 * @param tng_data is a trajectory data container.
1435 * @param frame_set is the frame set of which to get the frame range.
1436 * @param first_frame is set to the first frame of the frame set.
1437 * @param last_frame is set to the last frame of the frame set.
1438 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1439 * must be initialised before using it.
1440 * @pre \code first_frame != 0 \endcode The pointer to first_frame must
1441 * not be a NULL pointer.
1442 * @pre \code last_frame != 0 \endcode The pointer to last_frame must
1443 * not be a NULL pointer.
1444 * @return TNG_SUCCESS (0) if successful.
1446 tng_function_status DECLSPECDLLEXPORT tng_frame_set_frame_range_get
1447 (const tng_trajectory_t tng_data,
1448 const tng_trajectory_frame_set_t frame_set,
1449 int64_t *first_frame,
1450 int64_t *last_frame);
1453 * @brief Allocate memory for and setup a molecule container.
1454 * @param tng_data is a trajectory data container.
1455 * @param molecule_p is a pointer to molecule to allocate and initialise.
1456 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1457 * error has occured.
1459 tng_function_status DECLSPECDLLEXPORT tng_molecule_alloc(const tng_trajectory_t tng_data,
1460 tng_molecule_t *molecule_p);
1463 * @brief Clean up a molecule container and free its allocated memory.
1464 * @param tng_data is a trajectory data container.
1465 * @param molecule_p is the molecule to destroy.
1466 * @details All allocated memory in the data structure is freed and also the memory
1467 * of the molecule itself.
1468 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1469 * error has occured.
1471 tng_function_status DECLSPECDLLEXPORT tng_molecule_free(const tng_trajectory_t tng_data,
1472 tng_molecule_t *molecule_p);
1475 * @brief Setup a molecule container.
1476 * @param tng_data is a trajectory data container.
1477 * @param molecule is the molecule to initialise. Memory must be preallocated.
1478 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1479 * error has occured.
1481 tng_function_status DECLSPECDLLEXPORT tng_molecule_init
1482 (const tng_trajectory_t tng_data,
1483 const tng_molecule_t molecule);
1486 * @brief Clean up a molecule container.
1487 * @param tng_data is a trajectory data container.
1488 * @param molecule is the molecule to destroy.
1489 * @details All allocated memory in the data structure is freed, but not the
1490 * memory of molecule itself.
1491 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1492 * error has occured.
1494 tng_function_status DECLSPECDLLEXPORT tng_molecule_destroy
1495 (const tng_trajectory_t tng_data,
1496 const tng_molecule_t molecule);
1499 * @brief Add a molecule to the trajectory.
1500 * @param tng_data is the trajectory data container containing the block..
1501 * @param name is a pointer to the string containing the name of the new molecule.
1502 * @param molecule is a pointer to the newly created molecule.
1503 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1504 * must be initialised before using it.
1505 * @pre \code name != 0 \endcode The pointer to the name string
1506 * must not be a NULL pointer.
1507 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1508 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1510 tng_function_status DECLSPECDLLEXPORT tng_molecule_add
1511 (const tng_trajectory_t tng_data,
1513 tng_molecule_t *molecule);
1516 * @brief Add a molecule with a specific ID to the trajectory.
1517 * @param tng_data is the trajectory data container containing the block..
1518 * @param name is a pointer to the string containing the name of the new molecule.
1519 * @param id is the ID of the created molecule.
1520 * @param molecule is a pointer to the newly created molecule.
1521 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1522 * must be initialised before using it.
1523 * @pre \code name != 0 \endcode The pointer to the name string
1524 * must not be a NULL pointer.
1525 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1526 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1528 tng_function_status DECLSPECDLLEXPORT tng_molecule_w_id_add
1529 (const tng_trajectory_t tng_data,
1532 tng_molecule_t *molecule);
1535 * @brief Add an existing molecule (from a molecule container) to the trajectory.
1536 * @param tng_data is the trajectory data container containing the block..
1537 * @param molecule is a pointer to the molecule to add to the trajectory and will
1538 * afterwards point to the molecule in the trajectory.
1539 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1540 * must be initialised before using it.
1541 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error
1544 tng_function_status DECLSPECDLLEXPORT tng_molecule_existing_add
1545 (const tng_trajectory_t tng_data,
1546 tng_molecule_t *molecule);
1549 * @brief Get the name of a molecule.
1550 * @param tng_data the trajectory containing the molecule.
1551 * @param molecule the molecule of which to get the name.
1552 * @param name the string to fill with the name of the molecule,
1553 * memory must be allocated before.
1554 * @param max_len maximum char length of the string, i.e. how much memory has
1555 * been reserved for name. This includes \0 terminating character.
1556 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1557 * @pre \code name != 0 \endcode The pointer to the name string
1558 * must not be a NULL pointer.
1559 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1560 * has occurred (source string longer than destination string).
1562 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_get
1563 (const tng_trajectory_t tng_data,
1564 const tng_molecule_t molecule,
1569 * @brief Set the name of a molecule.
1570 * @param tng_data is the trajectory data container containing the molecule..
1571 * @param molecule is the molecule to rename.
1572 * @param new_name is a string containing the wanted name.
1573 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1574 * must be initialised before using it.
1575 * @pre \code new_name != 0 \endcode The pointer to the name string
1576 * must not be a NULL pointer.
1577 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1578 * error has occured.
1580 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_set
1581 (const tng_trajectory_t tng_data,
1582 const tng_molecule_t molecule,
1583 const char *new_name);
1586 * @brief Get the count of a molecule.
1587 * @param tng_data is the trajectory data container containing the molecule..
1588 * @param molecule is the molecule of which to get the count.
1589 * @param cnt is a pointer to the variable to be populated with the count.
1590 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1591 * must be initialised before using it.
1592 * @pre \code cnt != 0 \endcode The pointer to the molecule count
1593 * must not be a NULL pointer.
1594 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1595 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1597 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_get
1598 (const tng_trajectory_t tng_data,
1599 const tng_molecule_t molecule,
1603 * @brief Set the count of a molecule.
1604 * @param tng_data is the trajectory data container containing the molecule..
1605 * @param molecule is the molecule of which to set the count.
1606 * @param cnt is the number of instances of this molecule.
1607 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1608 * must be initialised before using it.
1609 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1610 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1612 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_set
1613 (const tng_trajectory_t tng_data,
1614 const tng_molecule_t molecule,
1618 * @brief Find a molecule.
1619 * @param tng_data is the trajectory data container containing the molecule.
1620 * @param name is a string containing the name of the molecule. If name is empty
1621 * only id will be used for finding the molecule.
1622 * @param id is the id of the molecule to look for. If id is -1 only the name of
1623 * the molecule will be used for finding the molecule.
1624 * @param molecule is a pointer to the molecule if it was found - otherwise 0.
1625 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1626 * must be initialised before using it.
1627 * @pre \code name != 0 \endcode The pointer to the name string
1628 * must not be a NULL pointer.
1629 * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the
1630 * molecule is not found.
1631 * @details If name is an empty string and id == -1 the first residue will
1634 tng_function_status DECLSPECDLLEXPORT tng_molecule_find
1635 (const tng_trajectory_t tng_data,
1638 tng_molecule_t *molecule);
1641 * @brief Retrieve the molecule with specified index in the list of molecules.
1642 * @param tng_data is the trajectory data container containing the molecule.
1643 * @param index is the index (in tng_data->molecules) of the molecule to return
1644 * @param molecule is a pointer to the molecule if it was found - otherwise 0.
1645 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1646 * must be initialised before using it.
1647 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1648 * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the
1649 * molecule is not found.
1651 tng_function_status DECLSPECDLLEXPORT tng_molecule_of_index_get
1652 (const tng_trajectory_t tng_data,
1653 const int64_t index,
1654 tng_molecule_t *molecule);
1657 * @brief Copy all molecules and the molecule counts from one TNG trajectory
1659 * @param tng_data_src is the source trajectory containing the molecular
1661 * @param tng_data_dest is the destination trajectory.
1662 * @pre \code tng_data_src != 0 \endcode The trajectory container (tng_data_src)
1663 * must be initialised before using it.
1664 * @pre \code tng_data_dest != 0 \endcode The trajectory container (tng_data_dest)
1665 * must be initialised before using it.
1666 * @details The molecular system in tng_data_dest will be overwritten.
1667 * @return TNG_SUCCESS(0) if the copying is successful, TNG_FAILURE if a minor
1668 * error has occured or TNG_CRITICAL(2) if a major error has occured.
1670 tng_function_status DECLSPECDLLEXPORT tng_molecule_system_copy(const tng_trajectory_t tng_data_src,
1671 const tng_trajectory_t tng_data_dest);
1674 * @brief Get the number of chains in a molecule.
1675 * @param tng_data is the trajectory containing the molecule.
1676 * @param molecule is the molecule of which to get the number of chains.
1677 * @param n is pointing to a value set to the number of chains.
1678 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1679 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1680 * @return TNG_SUCCESS (0) if successful.
1682 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_chains_get
1683 (const tng_trajectory_t tng_data,
1684 const tng_molecule_t molecule,
1688 * @brief Retrieve the chain of a molecule with specified index in the list
1690 * @param tng_data is the trajectory data container containing the molecule.
1691 * @param index is the index (in molecule->chains) of the chain to return
1692 * @param molecule is the molecule from which to get the chain.
1693 * @param chain is a pointer to the chain if it was found - otherwise 0.
1694 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1695 * @pre \code chain != 0 \endcode chain must not be a NULL pointer.
1696 * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the
1697 * chain is not found.
1699 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_of_index_get
1700 (const tng_trajectory_t tng_data,
1701 const tng_molecule_t molecule,
1702 const int64_t index,
1703 tng_chain_t *chain);
1706 * @brief Get the number of residues in a molecule.
1707 * @param tng_data is the trajectory containing the molecule.
1708 * @param molecule is the molecule of which to get the number residues.
1709 * @param n is pointing to a value set to the number of residues.
1710 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1711 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1712 * @return TNG_SUCCESS (0) if successful.
1714 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_residues_get
1715 (const tng_trajectory_t tng_data,
1716 const tng_molecule_t molecule,
1720 * @brief Retrieve the residue of a molecule with specified index in the list
1722 * @param tng_data is the trajectory data container containing the molecule.
1723 * @param index is the index (in molecule->residues) of the residue to return
1724 * @param molecule is the molecule from which to get the residue.
1725 * @param residue is a pointer to the residue if it was found - otherwise 0.
1726 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1727 * @pre \code residue != 0 \endcode residue must not be a NULL pointer.
1728 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the
1729 * residue is not found.
1731 tng_function_status DECLSPECDLLEXPORT tng_molecule_residue_of_index_get
1732 (const tng_trajectory_t tng_data,
1733 const tng_molecule_t molecule,
1734 const int64_t index,
1735 tng_residue_t *residue);
1738 * @brief Get the number of atoms in a molecule.
1739 * @param tng_data is the trajectory containing the molecule.
1740 * @param molecule is the molecule of which to get the number of atoms.
1741 * @param n is pointing to a value set to the number of atoms.
1742 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1743 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1744 * @return TNG_SUCCESS (0) if successful.
1746 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_atoms_get
1747 (const tng_trajectory_t tng_data,
1748 const tng_molecule_t molecule,
1752 * @brief Retrieve the atom of a molecule with specified index in the list
1754 * @param tng_data is the trajectory data container containing the molecule.
1755 * @param index is the index (in molecule->atoms) of the atom to return
1756 * @param molecule is the molecule from which to get the atom.
1757 * @param atom is a pointer to the atom if it was found - otherwise 0.
1758 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1759 * @pre \code atom != 0 \endcode atom must not be a NULL pointer.
1760 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the
1761 * atom is not found.
1763 tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_of_index_get
1764 (const tng_trajectory_t tng_data,
1765 const tng_molecule_t molecule,
1766 const int64_t index,
1770 * @brief Find a chain in a molecule.
1771 * @param tng_data is the trajectory data container containing the molecule.
1772 * @param molecule is the molecule in which to search for the chain.
1773 * @param name is a string containing the name of the chain. If name is empty
1774 * only id will be used for finding the chain.
1775 * @param id is the id of the chain to look for. If id is -1 only the name of
1776 * the chain will be used for finding the chain.
1777 * @param chain is a pointer to the chain if it was found - otherwise 0.
1778 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1779 * must be initialised before using it.
1780 * @pre \code name != 0 \endcode The pointer to the name string
1781 * must not be a NULL pointer.
1782 * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the
1783 * chain is not found.
1784 * @details If name is an empty string and id == -1 the first residue will
1787 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_find
1788 (const tng_trajectory_t tng_data,
1789 const tng_molecule_t molecule,
1792 tng_chain_t *chain);
1795 * @brief Add a chain to a molecule.
1796 * @param tng_data is the trajectory data container containing the molecule..
1797 * @param molecule is the molecule to add a chain to.
1798 * @param name is a string containing the name of the chain.
1799 * @param chain is a pointer to the newly created chain.
1800 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1801 * must be initialised before using it.
1802 * @pre \code name != 0 \endcode The pointer to the name string
1803 * must not be a NULL pointer.
1804 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1805 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1807 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_add
1808 (const tng_trajectory_t tng_data,
1809 const tng_molecule_t molecule,
1811 tng_chain_t *chain);
1814 * @brief Add a chain with a specific id to a molecule.
1815 * @param tng_data is the trajectory data container containing the molecule..
1816 * @param molecule is the molecule to add a chain to.
1817 * @param name is a string containing the name of the chain.
1818 * @param id is the ID of the created chain.
1819 * @param chain is a pointer to the newly created chain.
1820 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1821 * must be initialised before using it.
1822 * @pre \code name != 0 \endcode The pointer to the name string
1823 * must not be a NULL pointer.
1824 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1825 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1827 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_w_id_add
1828 (const tng_trajectory_t tng_data,
1829 const tng_molecule_t molecule,
1832 tng_chain_t *chain);
1835 * @brief Add a bond between two atoms to a molecule.
1836 * @param tng_data is the trajectory data container containing the molecule.
1837 * @param molecule is the molecule containing the atoms to connect.
1838 * @param from_atom_id is the id of one of the two atoms in the bond.
1839 * @param to_atom_id is the id of the other atom in the bond.
1840 * @param bond is a pointer to the newly created bond.
1841 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1842 * must be initialised before using it.
1843 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (!) if a minor error
1844 * has occured or TNG_CRITICAL (2) if a major error has occured.
1846 tng_function_status DECLSPECDLLEXPORT tng_molecule_bond_add
1847 (const tng_trajectory_t tng_data,
1848 const tng_molecule_t molecule,
1849 const int64_t from_atom_id,
1850 const int64_t to_atom_id,
1854 * @brief Find an atom in a molecule.
1855 * @param tng_data is the trajectory data container containing the molecule.
1856 * @param molecule is the molecule in which to search for the atom.
1857 * @param name is a string containing the name of the atom. If name is an
1858 * empty string only id will be used for searching.
1859 * @param id is the id of the atom to find. If id == -1 the first atom
1860 * that matches the specified name will be found.
1861 * @param atom is a pointer to the atom if it was found - otherwise 0.
1862 * @pre \code name != 0 \endcode The pointer to the name string
1863 * must not be a NULL pointer.
1864 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the
1865 * atom is not found.
1866 * @details If name is an empty string and id == -1 the first residue will
1869 tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_find
1870 (const tng_trajectory_t tng_data,
1871 const tng_molecule_t molecule,
1877 * @brief Get the name of a chain.
1878 * @param tng_data the trajectory containing the chain.
1879 * @param chain the chain of which to get the name.
1880 * @param name the string to fill with the name of the chain,
1881 * memory must be allocated before.
1882 * @param max_len maximum char length of the string, i.e. how much memory has
1883 * been reserved for name. This includes \0 terminating character.
1884 * @pre \code chain != 0 \endcode The chain must not be NULL.
1885 * @pre \code name != 0 \endcode The pointer to the name string
1886 * must not be a NULL pointer.
1887 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1888 * has occurred (source string longer than destination string).
1890 tng_function_status DECLSPECDLLEXPORT tng_chain_name_get
1891 (const tng_trajectory_t tng_data,
1892 const tng_chain_t chain,
1897 * @brief Set the name of a chain.
1898 * @param tng_data is the trajectory data container containing the atom..
1899 * @param chain is the chain to rename.
1900 * @param new_name is a string containing the wanted name.
1901 * @pre \code new_name != 0 \endcode The pointer to the name string
1902 * must not be a NULL pointer.
1903 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1904 * error has occured.
1906 tng_function_status DECLSPECDLLEXPORT tng_chain_name_set
1907 (const tng_trajectory_t tng_data,
1908 const tng_chain_t chain,
1909 const char *new_name);
1912 * @brief Get the number of residues in a molecule chain.
1913 * @param tng_data is the trajectory containing the chain.
1914 * @param chain is the chain of which to get the number of residues.
1915 * @param n is pointing to a value set to the number of residues.
1916 * @pre \code chain != 0 \endcode The chain must not be NULL.
1917 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1918 * @return TNG_SUCCESS (0) if successful.
1920 tng_function_status DECLSPECDLLEXPORT tng_chain_num_residues_get
1921 (const tng_trajectory_t tng_data,
1922 const tng_chain_t chain,
1926 * @brief Retrieve the residue of a chain with specified index in the list
1928 * @param tng_data is the trajectory data container containing the chain.
1929 * @param index is the index (in chain->residues) of the residue to return
1930 * @param chain is the chain from which to get the residue.
1931 * @param residue is a pointer to the residue if it was found - otherwise 0.
1932 * @pre \code chain != 0 \endcode chain must not be a NULL pointer.
1933 * @pre \code residue != 0 \endcode residue must not be a NULL pointer.
1934 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the
1935 * residue is not found.
1937 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_of_index_get
1938 (const tng_trajectory_t tng_data,
1939 const tng_chain_t chain,
1940 const int64_t index,
1941 tng_residue_t *residue);
1944 * @brief Find a residue in a chain.
1945 * @param tng_data is the trajectory data container containing the chain.
1946 * @param chain is the chain in which to search for the residue.
1947 * @param name is a string containing the name of the residue. If name is an
1948 * empty string only id will be used for searching.
1949 * @param id is the id of the residue to find. If id == -1 the first residue
1950 * that matches the specified name will be found.
1951 * @param residue is a pointer to the residue if it was found - otherwise 0.
1952 * @pre \code name != 0 \endcode The pointer to the name string
1953 * must not be a NULL pointer.
1954 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the
1955 * residue is not found.
1956 * @details If name is an empty string and id == -1 the first residue will
1959 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_find
1960 (const tng_trajectory_t tng_data,
1961 const tng_chain_t chain,
1964 tng_residue_t *residue);
1967 * @brief Add a residue to a chain.
1968 * @param tng_data is the trajectory data container containing the chain..
1969 * @param chain is the chain to add a residue to.
1970 * @param name is a string containing the name of the residue.
1971 * @param residue is a pointer to the newly created residue.
1972 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1973 * must be initialised before using it.
1974 * @pre \code name != 0 \endcode The pointer to the name string
1975 * must not be a NULL pointer.
1976 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1977 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1979 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_add
1980 (const tng_trajectory_t tng_data,
1981 const tng_chain_t chain,
1983 tng_residue_t *residue);
1986 * @brief Add a residue with a specific ID to a chain.
1987 * @param tng_data is the trajectory data container containing the chain..
1988 * @param chain is the chain to add a residue to.
1989 * @param name is a string containing the name of the residue.
1990 * @param id is the ID of the created residue.
1991 * @param residue is a pointer to the newly created residue.
1992 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1993 * must be initialised before using it.
1994 * @pre \code name != 0 \endcode The pointer to the name string
1995 * must not be a NULL pointer.
1996 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1997 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1999 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_w_id_add
2000 (const tng_trajectory_t tng_data,
2001 const tng_chain_t chain,
2004 tng_residue_t *residue);
2007 * @brief Get the name of a residue.
2008 * @param tng_data the trajectory containing the residue.
2009 * @param residue the residue of which to get the name.
2010 * @param name the string to fill with the name of the residue,
2011 * memory must be allocated before.
2012 * @param max_len maximum char length of the string, i.e. how much memory has
2013 * been reserved for name. This includes \0 terminating character.
2014 * @pre \code residue != 0 \endcode The residue must not be NULL.
2015 * @pre \code name != 0 \endcode The pointer to the name string
2016 * must not be a NULL pointer.
2017 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2018 * has occurred (source string longer than destination string).
2020 tng_function_status DECLSPECDLLEXPORT tng_residue_name_get
2021 (const tng_trajectory_t tng_data,
2022 const tng_residue_t residue,
2027 * @brief Set the name of a residue.
2028 * @param tng_data is the trajectory data container containing the residue.
2029 * @param residue is the residue to rename.
2030 * @param new_name is a string containing the wanted name.
2031 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2032 * must be initialised before using it.
2033 * @pre \code new_name != 0 \endcode The new name to set (new_name) must
2034 * not be a NULL pointer.
2035 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2036 * error has occured.
2038 tng_function_status DECLSPECDLLEXPORT tng_residue_name_set
2039 (const tng_trajectory_t tng_data,
2040 const tng_residue_t residue,
2041 const char *new_name);
2044 * @brief Get the number of atoms in a residue.
2045 * @param tng_data is the trajectory containing the residue.
2046 * @param residue is the residue of which to get the number atoms.
2047 * @param n is pointing to a value set to the number of atoms.
2048 * @pre \code residue != 0 \endcode The residue must not be NULL.
2049 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
2050 * @return TNG_SUCCESS (0) if successful.
2052 tng_function_status DECLSPECDLLEXPORT tng_residue_num_atoms_get
2053 (const tng_trajectory_t tng_data,
2054 const tng_residue_t residue,
2058 * @brief Retrieve the atom of a residue with specified index in the list
2060 * @param tng_data is the trajectory data container containing the residue.
2061 * @param index is the index (in residue->atoms) of the atom to return
2062 * @param residue is the residue from which to get the atom.
2063 * @param atom is a pointer to the atom if it was found - otherwise 0.
2064 * @pre \code residue != 0 \endcode residue must not be a NULL pointer.
2065 * @pre \code atom != 0 \endcode atom must not be a NULL pointer.
2066 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the
2067 * atom is not found.
2069 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_of_index_get
2070 (const tng_trajectory_t tng_data,
2071 const tng_residue_t residue,
2072 const int64_t index,
2076 * @brief Add an atom to a residue.
2077 * @param tng_data is the trajectory containing the residue.
2078 * @param residue is the residue to add an atom to.
2079 * @param atom_name is a string containing the name of the atom.
2080 * @param atom_type is a string containing the atom type of the atom.
2081 * @param atom is a pointer to the newly created atom.
2082 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2083 * must be initialised before using it.
2084 * @pre \code atom_name != 0 \endcode The pointer to the atom name string
2085 * must not be a NULL pointer.
2086 * @pre \code atom_type != 0 \endcode The pointer to the atom_type string
2087 * must not be a NULL pointer.
2088 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
2089 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
2091 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_add
2092 (const tng_trajectory_t tng_data,
2093 const tng_residue_t residue,
2094 const char *atom_name,
2095 const char *atom_type,
2099 * @brief Add an atom with a specific ID to a residue.
2100 * @param tng_data is the trajectory containing the residue.
2101 * @param residue is the residue to add an atom to.
2102 * @param atom_name is a string containing the name of the atom.
2103 * @param atom_type is a string containing the atom type of the atom.
2104 * @param id is the ID of the created atom.
2105 * @param atom is a pointer to the newly created atom.
2106 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2107 * must be initialised before using it.
2108 * @pre \code atom_name != 0 \endcode The pointer to the atom name string
2109 * must not be a NULL pointer.
2110 * @pre \code atom_type != 0 \endcode The pointer to the atom_type string
2111 * must not be a NULL pointer.
2112 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
2113 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
2115 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_w_id_add
2116 (const tng_trajectory_t tng_data,
2117 const tng_residue_t residue,
2118 const char *atom_name,
2119 const char *atom_type,
2124 * @brief Get the residue of an atom.
2125 * @param tng_data the trajectory containing the atom.
2126 * @param atom the atom of which to get the name.
2127 * @param residue is set to the residue of the atom.
2128 * @pre \code atom != 0 \endcode The atom must not be NULL.
2129 * @return TNG_SUCCESS (0) if successful.
2131 tng_function_status tng_atom_residue_get(const tng_trajectory_t tng_data,
2132 const tng_atom_t atom,
2133 tng_residue_t *residue);
2136 * @brief Get the name of an atom.
2137 * @param tng_data the trajectory containing the atom.
2138 * @param atom the atom of which to get the name.
2139 * @param name the string to fill with the name of the atom,
2140 * memory must be allocated before.
2141 * @param max_len maximum char length of the string, i.e. how much memory has
2142 * been reserved for name. This includes \0 terminating character.
2143 * @pre \code atom != 0 \endcode The atom must not be NULL.
2144 * @pre \code name != 0 \endcode The pointer to the name string
2145 * must not be a NULL pointer.
2146 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2147 * has occurred (source string longer than destination string).
2149 tng_function_status DECLSPECDLLEXPORT tng_atom_name_get
2150 (const tng_trajectory_t tng_data,
2151 const tng_atom_t atom,
2156 * @brief Set the name of an atom.
2157 * @param tng_data is the trajectory data container containing the atom.
2158 * @param atom is the atom to rename.
2159 * @param new_name is a string containing the wanted name.
2160 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2161 * must be initialised before using it.
2162 * @pre \code new_name != 0 \endcode The pointer to the name string
2163 * must not be a NULL pointer.
2164 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2165 * error has occured.
2167 tng_function_status DECLSPECDLLEXPORT tng_atom_name_set
2168 (const tng_trajectory_t tng_data,
2169 const tng_atom_t atom,
2170 const char *new_name);
2173 * @brief Get the type of an atom.
2174 * @param tng_data the trajectory containing the atom.
2175 * @param atom the atom of which to get the type.
2176 * @param type the string to fill with the type of the atom,
2177 * memory must be allocated before.
2178 * @param max_len maximum char length of the string, i.e. how much memory has
2179 * been reserved for type. This includes \0 terminating character.
2180 * @pre \code atom != 0 \endcode The atom must not be NULL.
2181 * @pre \code type != 0 \endcode The pointer to the type string
2182 * must not be a NULL pointer.
2183 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2184 * has occurred (source string longer than destination string).
2186 tng_function_status DECLSPECDLLEXPORT tng_atom_type_get
2187 (const tng_trajectory_t tng_data,
2188 const tng_atom_t atom,
2193 * @brief Set the atom type of an atom.
2194 * @param tng_data is the trajectory data container containing the atom.
2195 * @param atom is the atom to change.
2196 * @param new_type is a string containing the atom type.
2197 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2198 * must be initialised before using it.
2199 * @pre \code new_type != 0 \endcode The pointer to the atom type string
2200 * must not be a NULL pointer.
2201 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2202 * error has occured.
2204 tng_function_status DECLSPECDLLEXPORT tng_atom_type_set
2205 (const tng_trajectory_t tng_data,
2206 const tng_atom_t atom,
2207 const char *new_type);
2210 * @brief Get the molecule name of real particle number (number in mol system).
2211 * @param tng_data is the trajectory data container containing the atom.
2212 * @param nr is the real number of the particle in the molecular system.
2213 * @param name is a string, which is set to the name of the molecule. Memory
2214 * must be reserved beforehand.
2215 * @param max_len is the maximum length of name.
2216 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2217 * must be initialised before using it.
2218 * @pre \code name != 0 \endcode The pointer to the name string
2219 * must not be a NULL pointer.
2220 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2223 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_of_particle_nr_get
2224 (const tng_trajectory_t tng_data,
2230 * @brief Get the molecule id of real particle number (number in mol system).
2231 * @param tng_data is the trajectory data container containing the atom.
2232 * @param nr is the real number of the particle in the molecular system.
2233 * @param id is will be set to the id of the molecule.
2234 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2235 * must be initialised before using it.
2236 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer.
2237 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2240 tng_function_status DECLSPECDLLEXPORT tng_molecule_id_of_particle_nr_get
2241 (const tng_trajectory_t tng_data,
2246 * @brief Get the bonds of the current molecular system.
2247 * @param tng_data is the trajectory data container containing the molecular
2249 * @param n_bonds is set to the number of bonds in the molecular system and
2250 * thereby also the lengths of the two lists: from_atoms and to_atoms.
2251 * @param from_atoms is a list (memory reserved by this function) of atoms
2252 * (number of atom in mol system) in bonds.
2253 * @param to_atoms is a list (memory reserved by this function) of atoms
2254 * (number of atom in mol system) in bonds.
2255 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2256 * must be initialised before using it.
2257 * @pre \code n_bonds != 0 \endcode The pointer to n_bonds must not be a
2259 * @pre \code from_atoms != 0 \endcode The pointer to from_atoms must not
2260 * be a NULL pointer.
2261 * @pre \code to_atoms != 0 \endcode The pointer to to_atoms must not
2262 * be a NULL pointer.
2263 * @details The two lists of atoms use the same index, i.e. from_atoms[0]
2264 * and to_atoms[0] are linked with a bond. Since memory is reserved in
2265 * this function it must be freed afterwards.
2266 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2267 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2269 tng_function_status DECLSPECDLLEXPORT tng_molsystem_bonds_get
2270 (const tng_trajectory_t tng_data,
2272 int64_t **from_atoms,
2273 int64_t **to_atoms);
2276 * @brief Get the chain name of real particle number (number in mol system).
2277 * @param tng_data is the trajectory data container containing the atom.
2278 * @param nr is the real number of the particle in the molecular system.
2279 * @param name is a string, which is set to the name of the chain. Memory
2280 * must be reserved beforehand.
2281 * @param max_len is the maximum length of name.
2282 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2283 * must be initialised before using it.
2284 * @pre \code name != 0 \endcode The pointer to the name string
2285 * must not be a NULL pointer.
2286 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2289 tng_function_status DECLSPECDLLEXPORT tng_chain_name_of_particle_nr_get
2290 (const tng_trajectory_t tng_data,
2296 * @brief Get the residue name of real particle number (number in mol system).
2297 * @param tng_data is the trajectory data container containing the atom.
2298 * @param nr is the real number of the particle in the molecular system.
2299 * @param name is a string, which is set to the name of the residue. Memory
2300 * must be reserved beforehand.
2301 * @param max_len is the maximum length of name.
2302 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2303 * must be initialised before using it.
2304 * @pre \code name != 0 \endcode The pointer to the name string
2305 * must not be a NULL pointer.
2306 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2309 tng_function_status DECLSPECDLLEXPORT tng_residue_name_of_particle_nr_get
2310 (const tng_trajectory_t tng_data,
2316 * @brief Get the residue id (local to molecule) of real particle number
2317 * (number in mol system).
2318 * @param tng_data is the trajectory data container containing the atom.
2319 * @param nr is the real number of the particle in the molecular system.
2320 * @param id is a pointer to the variable, which will be set to the ID.
2321 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2322 * must be initialised before using it.
2323 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer.
2324 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2327 tng_function_status DECLSPECDLLEXPORT tng_residue_id_of_particle_nr_get
2328 (const tng_trajectory_t tng_data,
2333 * @brief Get the residue id (based on other molecules and molecule counts)
2334 * of real particle number (number in mol system).
2335 * @param tng_data is the trajectory data container containing the atom.
2336 * @param nr is the real number of the particle in the molecular system.
2337 * @param id is a pointer to the variable, which will be set to the ID.
2338 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2339 * must be initialised before using it.
2340 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer.
2341 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2344 tng_function_status DECLSPECDLLEXPORT tng_global_residue_id_of_particle_nr_get
2345 (const tng_trajectory_t tng_data,
2350 * @brief Get the atom name of real particle number (number in mol system).
2351 * @param tng_data is the trajectory data container containing the atom.
2352 * @param nr is the real number of the particle in the molecular system.
2353 * @param name is a string, which is set to the name of the atom. Memory
2354 * must be reserved beforehand.
2355 * @param max_len is the maximum length of name.
2356 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2357 * must be initialised before using it.
2358 * @pre \code name != 0 \endcode The pointer to the name string
2359 * must not be a NULL pointer.
2360 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2363 tng_function_status DECLSPECDLLEXPORT tng_atom_name_of_particle_nr_get
2364 (const tng_trajectory_t tng_data,
2370 * @brief Get the atom type of real particle number (number in mol system).
2371 * @param tng_data is the trajectory data container containing the atom.
2372 * @param nr is the real number of the particle in the molecular system.
2373 * @param type is a string, which is set to the type of the atom. Memory
2374 * must be reserved beforehand.
2375 * @param max_len is the maximum length of type.
2376 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2377 * must be initialised before using it.
2378 * @pre \code type != 0 \endcode The pointer to the type string
2379 * must not be a NULL pointer.
2380 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2383 tng_function_status DECLSPECDLLEXPORT tng_atom_type_of_particle_nr_get
2384 (const tng_trajectory_t tng_data,
2390 * @brief Add a particle mapping table.
2391 * @details Each particle mapping table will be written as a separate block,
2392 * followed by the data blocks for the corresponding particles. In most cases
2393 * there is one particle mapping block for each thread writing the trajectory.
2394 * @param tng_data is the trajectory, with the frame set to which to add
2395 * the mapping block.
2396 * @details The mapping information is added to the currently active frame set
2398 * @param num_first_particle is the first particle number of this mapping
2400 * @param n_particles is the number of particles in this mapping block.
2401 * @param mapping_table is a list of the real particle numbers (i.e. the numbers
2402 * used in the molecular system). The list is n_particles long.
2403 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2404 * must be initialised before using it.
2405 * @details mapping_table[0] is the real particle number of the first particle
2406 * in the following data blocks.
2407 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2408 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2410 tng_function_status DECLSPECDLLEXPORT tng_particle_mapping_add
2411 (const tng_trajectory_t tng_data,
2412 const int64_t num_first_particle,
2413 const int64_t n_particles,
2414 const int64_t *mapping_table);
2417 * @brief Remove all particle mappings (in memory) from the current frame set.
2418 * @details Clears the currently setup particle mappings of the current frame
2420 * @param tng_data is the trajectory, with the frame set of which to clear
2421 * all particle mappings.
2422 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2423 * must be initialised before using it.
2424 * @return TNG_SUCCESS (0) if successful.
2426 tng_function_status DECLSPECDLLEXPORT tng_frame_set_particle_mapping_free
2427 (const tng_trajectory_t tng_data);
2430 * @brief Read the header blocks from the input_file of tng_data.
2431 * @details The trajectory blocks must be read separately and iteratively in chunks
2433 * @param tng_data is a trajectory data container.
2434 * @details tng_data->input_file_path specifies
2435 * which file to read from. If the file (input_file) is not open it will be
2437 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2438 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2439 * compared to the md5 hash of the read contents to ensure valid data.
2440 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2441 * must be initialised before using it.
2442 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2443 * error has occured.
2445 tng_function_status DECLSPECDLLEXPORT tng_file_headers_read
2446 (const tng_trajectory_t tng_data,
2447 const char hash_mode);
2450 * @brief Write the header blocks to the output_file of tng_data.
2451 * @details The trajectory blocks must be written separately and iteratively in chunks
2453 * @param tng_data is a trajectory data container.
2454 * @details tng_data->output_file_path
2455 * specifies which file to write to. If the file (output_file) is not open it
2457 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2458 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
2459 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2460 * must be initialised before using it.
2461 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2462 * error has occured.
2464 tng_function_status DECLSPECDLLEXPORT tng_file_headers_write
2465 (const tng_trajectory_t tng_data,
2466 const char hash_mode);
2469 * @brief Read one (the next) block (of any kind) from the input_file of tng_data.
2470 * @param tng_data is a trajectory data container.
2471 * @details tng_data->input_file_path specifies
2472 * which file to read from. If the file (input_file) is not open it will be
2474 * @param block_data is a pointer to the struct which will be populated with the
2476 * @details If block_data->input_file_pos > 0 it is the position from where the
2477 * reading starts otherwise it starts from the current position.
2478 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2479 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2480 * compared to the md5 hash of the read contents to ensure valid data.
2481 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2482 * must be initialised before using it.
2483 * @pre \code block != 0 \endcode The block container (block) must be
2484 * initialised before using it.
2485 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2486 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2488 tng_function_status DECLSPECDLLEXPORT tng_block_read_next
2489 (const tng_trajectory_t tng_data,
2490 const tng_gen_block_t block_data,
2491 const char hash_mode);
2494 * @brief Read one frame set, including all particle mapping blocks and data
2495 * blocks, starting from the current file position.
2496 * @param tng_data is a trajectory data container.
2497 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2498 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2499 * compared to the md5 hash of the read contents to ensure valid data.
2500 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2501 * must be initialised before using it.
2502 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2503 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2505 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read
2506 (const tng_trajectory_t tng_data,
2507 const char hash_mode);
2510 * @brief Read data from the current frame set from the input_file. Only read
2511 * particle mapping and data blocks matching the specified block_id.
2512 * @param tng_data is a trajectory data container.
2513 * @details tng_data->input_file_path specifies
2514 * which file to read from. If the file (input_file) is not open it will be
2516 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2517 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2518 * compared to the md5 hash of the read contents to ensure valid data.
2519 * @param block_id is the ID of the data block to read from file.
2520 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2521 * must be initialised before using it.
2522 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2523 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2525 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_current_only_data_from_block_id
2526 (const tng_trajectory_t tng_data,
2527 const char hash_mode,
2528 const int64_t block_id);
2531 * @brief Read one (the next) frame set, including particle mapping and related data blocks
2532 * from the input_file of tng_data.
2533 * @param tng_data is a trajectory data container.
2534 * @details tng_data->input_file_path specifies
2535 * which file to read from. If the file (input_file) is not open it will be
2537 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2538 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2539 * compared to the md5 hash of the read contents to ensure valid data.
2540 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2541 * must be initialised before using it.
2542 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2543 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2545 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next
2546 (const tng_trajectory_t tng_data,
2547 const char hash_mode);
2550 * @brief Read one (the next) frame set, including particle mapping and data blocks with a
2551 * specific block id from the input_file of tng_data.
2552 * @param tng_data is a trajectory data container.
2553 * @details tng_data->input_file_path specifies
2554 * which file to read from. If the file (input_file) is not open it will be
2556 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2557 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2558 * compared to the md5 hash of the read contents to ensure valid data.
2559 * @param block_id is the ID number of the blocks that should be read from file.
2560 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2561 * must be initialised before using it.
2562 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2563 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2565 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next_only_data_from_block_id
2566 (const tng_trajectory_t tng_data,
2567 const char hash_mode,
2568 const int64_t block_id);
2571 * @brief Write one frame set, including mapping and related data blocks
2572 * to the output_file of tng_data.
2573 * @param tng_data is a trajectory data container.
2574 * @details tng_data->output_file_path specifies
2575 * which file to write to. If the file (output_file) is not open it will be
2577 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2578 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
2579 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2580 * must be initialised before using it.
2581 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2582 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2584 tng_function_status DECLSPECDLLEXPORT tng_frame_set_write
2585 (const tng_trajectory_t tng_data,
2586 const char hash_mode);
2589 * @brief Write one frame set even if it does not have as many frames as
2590 * expected. The function also writes mapping and related data blocks
2591 * to the output_file of tng_data.
2592 * @param tng_data is a trajectory data container.
2593 * @details tng_data->output_file_path specifies
2594 * which file to write to. If the file (output_file) is not open it will be
2596 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2597 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
2598 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2599 * must be initialised before using it.
2600 * @details The number of frames in the frame set is set to the number of
2601 * frames of the data blocks before writing it to disk.
2602 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2603 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2605 tng_function_status DECLSPECDLLEXPORT tng_frame_set_premature_write
2606 (const tng_trajectory_t tng_data,
2607 const char hash_mode);
2610 * @brief Create and initialise a frame set.
2611 * @details Particle mappings are retained from previous frame set (if any).
2612 * To explicitly clear particle mappings use tng_frame_set_particle_mapping_free().
2613 * @param tng_data is the trajectory data container in which to add the frame
2615 * @param first_frame is the first frame of the frame set.
2616 * @param n_frames is the number of frames in the frame set.
2617 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2618 * must be initialised before using it.
2619 * @pre \code first_frame >= 0 \endcode The first frame must not be negative.
2620 * @pre \code n_frames >= 0 \endcode The number of frames must not be negative.
2621 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2622 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2624 tng_function_status DECLSPECDLLEXPORT tng_frame_set_new
2625 (const tng_trajectory_t tng_data,
2626 const int64_t first_frame,
2627 const int64_t n_frames);
2630 * @brief Create and initialise a frame set with the time of the first frame
2632 * @param tng_data is the trajectory data container in which to add the frame
2634 * @param first_frame is the first frame of the frame set.
2635 * @param n_frames is the number of frames in the frame set.
2636 * @param first_frame_time is the time stamp of the first frame (in seconds).
2637 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2638 * must be initialised before using it.
2639 * @pre \code first_frame >= 0 \endcode The first frame must not be negative.
2640 * @pre \code n_frames >= 0 \endcode The number of frames must not be negative.
2641 * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame
2642 * must not be negative.
2643 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2644 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2646 tng_function_status DECLSPECDLLEXPORT tng_frame_set_with_time_new
2647 (const tng_trajectory_t tng_data,
2648 const int64_t first_frame,
2649 const int64_t n_frames,
2650 const double first_frame_time);
2653 * @brief Set the time stamp of the first frame of the current frame set.
2654 * @param tng_data is the trajectory containing the frame set.
2655 * @param first_frame_time is the time stamp of the first frame in the
2657 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2658 * must be initialised before using it.
2659 * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame
2660 * must not be negative.
2661 * @return TNG_SUCCESS (0) if successful.
2663 tng_function_status DECLSPECDLLEXPORT tng_frame_set_first_frame_time_set
2664 (const tng_trajectory_t tng_data,
2665 const double first_frame_time);
2668 * @brief Read the number of the first frame of the next frame set.
2669 * @param tng_data is the trajectory containing the frame set.
2670 * @param frame is set to the frame number of the first frame in the
2672 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2673 * must be initialised before using it.
2674 * @pre \code tng_data->input_file != 0 \endcode An input file must be open
2675 * to find the next frame set.
2676 * @pre \code frame != 0 \endcode The pointer to the frame must not be a NULL
2678 * @return TNG_SUCCESS(0) if successful, TNG_FAILURE(1) if there is no next
2679 * frame set or TNG_CRITICAL(2) if a major error has occured.
2681 tng_function_status DECLSPECDLLEXPORT tng_first_frame_nr_of_next_frame_set_get
2682 (const tng_trajectory_t tng_data,
2686 * @brief Add a non-particle dependent data block.
2687 * @param tng_data is the trajectory data container in which to add the data
2689 * @param id is the block ID of the block to add.
2690 * @param block_name is a descriptive name of the block to add
2691 * @param datatype is the datatype of the data in the block (e.g. int/float)
2692 * @param block_type_flag indicates if this is a non-trajectory block (added
2693 * directly to tng_data) or if it is a trajectory block (added to the
2695 * @param n_frames is the number of frames of the data block (automatically
2696 * set to 1 if adding a non-trajectory data block)
2697 * @param n_values_per_frame is how many values a stored each frame (e.g. 9
2698 * for a box shape block)
2699 * @param stride_length is how many frames are between each entry in the
2701 * @param codec_id is the ID of the codec to compress the data.
2702 * @param new_data is an array of data values to add.
2703 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2704 * must be initialised before using it.
2705 * @pre \code block_name != 0 \endcode The pointer to the block name must
2706 * not be a NULL pointer.
2707 * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be
2708 * a positive integer.
2709 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2710 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2712 tng_function_status DECLSPECDLLEXPORT tng_data_block_add
2713 (const tng_trajectory_t tng_data,
2715 const char *block_name,
2716 const char datatype,
2717 const char block_type_flag,
2719 const int64_t n_values_per_frame,
2720 int64_t stride_length,
2721 const int64_t codec_id,
2725 * @brief Add a particle dependent data block.
2726 * @param tng_data is the trajectory data container in which to add the data
2728 * @param id is the block ID of the block to add.
2729 * @param block_name is a descriptive name of the block to add
2730 * @param datatype is the datatype of the data in the block (e.g. int/float)
2731 * @param block_type_flag indicates if this is a non-trajectory block (added
2732 * directly to tng_data) or if it is a trajectory block (added to the
2734 * @param n_frames is the number of frames of the data block (automatically
2735 * set to 1 if adding a non-trajectory data block)
2736 * @param n_values_per_frame is how many values a stored each frame (e.g. 9
2737 * for a box shape block)
2738 * @param stride_length is how many frames are between each entry in the
2740 * @param num_first_particle is the number of the first particle stored
2741 * in this data block
2742 * @param n_particles is the number of particles stored in this data block
2743 * @param codec_id is the ID of the codec to compress the data.
2744 * @param new_data is an array of data values to add.
2745 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2746 * must be initialised before using it.
2747 * @pre \code block_name != 0 \endcode The pointer to the block name must
2748 * not be a NULL pointer.
2749 * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be
2750 * a positive integer.
2751 * @pre \code num_first_particle >= 0 \endcode The number of the
2752 * first particle must be >= 0.
2753 * @pre \code n_particles >= 0 \endcode n_particles must be >= 0.
2754 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2755 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2757 tng_function_status DECLSPECDLLEXPORT tng_particle_data_block_add
2758 (const tng_trajectory_t tng_data,
2760 const char *block_name,
2761 const char datatype,
2762 const char block_type_flag,
2764 const int64_t n_values_per_frame,
2765 int64_t stride_length,
2766 const int64_t num_first_particle,
2767 const int64_t n_particles,
2768 const int64_t codec_id,
2771 /** @brief Get the name of a data block of a specific ID.
2772 * @param tng_data is the trajectory data container.
2773 * @param block_id is the ID of the data block of which to get the name.
2774 * @param name is a string, which is set to the name of the data block.
2775 * Memory must be reserved beforehand.
2776 * @param max_len is the maximum length of name.
2777 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2778 * must be initialised before using it.
2779 * @pre \code name != 0 \endcode The pointer to the name string
2780 * must not be a NULL pointer.
2781 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1)
2782 * if a minor error has occured or the data block is not found or
2783 * TNG_CRITICAL (2) if a major error has occured.
2785 tng_function_status DECLSPECDLLEXPORT tng_data_block_name_get
2786 (const tng_trajectory_t tng_data,
2787 const int64_t block_id,
2791 /** @brief Get the dependency of a data block of a specific ID.
2792 * @param tng_data is the trajectory data container.
2793 * @param block_id is the ID of the data block of which to get the name.
2794 * @param block_dependency is a pointer to the dependency of the data block.
2795 * If the block is frame dependent it will be set to TNG_FRAME_DEPENDENT,
2796 * if it is particle dependent it will be set to TNG_PARTICLE_DEPENDENT and
2797 * if it is both it will be set to TNG_FRAME_DEPENDENT & TNG_PARTICLE_DEPENDENT.
2798 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2799 * must be initialised before using it.
2800 * @pre \code block_dependency != 0 \endcode The pointer to the block dependency
2801 * must not be a NULL pointer.
2802 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1)
2803 * if a minor error has occured or the data block is not found or
2804 * TNG_CRITICAL (2) if a major error has occured.
2806 tng_function_status DECLSPECDLLEXPORT tng_data_block_dependency_get
2807 (const tng_trajectory_t tng_data,
2808 const int64_t block_id,
2809 int *block_dependency);
2811 /** @brief Get the number of values per frame of a data block of a specific ID.
2812 * @param tng_data is the trajectory data container.
2813 * @param block_id is the ID of the data block of which to get the name.
2814 * @param n_values_per_frame is a pointer set to the number of values per frame.
2815 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2816 * must be initialised before using it.
2817 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of values
2818 * per frame must not be a NULL pointer.
2819 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1)
2820 * if a minor error has occured or the data block is not found or
2821 * TNG_CRITICAL (2) if a major error has occured.
2823 tng_function_status DECLSPECDLLEXPORT tng_data_block_num_values_per_frame_get
2824 (const tng_trajectory_t tng_data,
2825 const int64_t block_id,
2826 int64_t *n_values_per_frame);
2829 * @brief Write data of one trajectory frame to the output_file of tng_data.
2830 * @param tng_data is a trajectory data container. tng_data->output_file_path
2831 * specifies which file to write to. If the file (output_file) is not open it
2833 * @param frame_nr is the index number of the frame to write.
2834 * @param block_id is the ID of the data block to write the data to.
2835 * @param values is an array of data to write. The length of the array should
2836 * equal n_values_per_frame.
2837 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2838 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2839 * compared to the md5 hash of the read contents to ensure valid data.
2840 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2841 * must be initialised before using it.
2842 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
2843 * @pre \code values != 0 \endcode The pointer to the values must not be a NULL
2845 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2846 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2848 tng_function_status DECLSPECDLLEXPORT tng_frame_data_write
2849 (const tng_trajectory_t tng_data,
2850 const int64_t frame_nr,
2851 const int64_t block_id,
2853 const char hash_mode);
2856 * @brief Write particle data of one trajectory frame to the output_file of
2858 * @param tng_data is a trajectory data container. tng_data->output_file_path
2859 * specifies which file to write to. If the file (output_file) is not open it
2861 * @param frame_nr is the index number of the frame to write.
2862 * @param block_id is the ID of the data block to write the data to.
2863 * @param val_first_particle is the number of the first particle in the data
2865 * @param val_n_particles is the number of particles in the data array.
2866 * @param values is a 1D-array of data to write. The length of the array should
2867 * equal n_particles * n_values_per_frame.
2868 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2869 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2870 * compared to the md5 hash of the read contents to ensure valid data.
2871 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2872 * must be initialised before using it.
2873 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
2874 * @pre \code val_first_particle >= 0 \endcode The number of the
2875 * first particle must be >= 0.
2876 * @pre \code val_n_particles >= 0 \endcode The number of particles must be >= 0.
2877 * @pre \code values != 0 \endcode The pointer to the values must not be a NULL
2879 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2880 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2882 tng_function_status DECLSPECDLLEXPORT tng_frame_particle_data_write
2883 (const tng_trajectory_t tng_data,
2884 const int64_t frame_nr,
2885 const int64_t block_id,
2886 const int64_t val_first_particle,
2887 const int64_t val_n_particles,
2889 const char hash_mode);
2892 * @brief Free data of an array of values (2D).
2893 * @param tng_data is a trajectory data container.
2894 * @param values is the 2D array to free and will be set to 0 afterwards.
2895 * @param n_frames is the number of frames in the data array.
2896 * @param n_values_per_frame is the number of values per frame in the data array.
2897 * @param type is the data type of the data in the array (e.g. int/float/char).
2898 * @details This function should not be used. The data_values union is obsolete.
2899 * This function also causes memory leaks, but its signature cannot be changed
2900 * without disturbing the API.
2901 * @return TNG_SUCCESS (0) if successful.
2903 tng_function_status DECLSPECDLLEXPORT tng_data_values_free
2904 (const tng_trajectory_t tng_data,
2905 union data_values **values,
2906 const int64_t n_frames,
2907 const int64_t n_values_per_frame,
2911 * @brief Free data of an array of values (3D).
2912 * @param tng_data is a trajectory data container.
2913 * @param values is the array to free and will be set to 0 afterwards.
2914 * @param n_frames is the number of frames in the data array.
2915 * @param n_particles is the number of particles in the data array.
2916 * @param n_values_per_frame is the number of values per frame in the data array.
2917 * @param type is the data type of the data in the array (e.g. int/float/char).
2918 * @details This function should not be used. The data_values union is obsolete.
2919 * This function also causes memory leaks, but its signature cannot be changed
2920 * without disturbing the API.
2921 * @return TNG_SUCCESS (0) if successful.
2923 tng_function_status DECLSPECDLLEXPORT tng_particle_data_values_free
2924 (const tng_trajectory_t tng_data,
2925 union data_values ***values,
2926 const int64_t n_frames,
2927 const int64_t n_particles,
2928 const int64_t n_values_per_frame,
2932 * @brief Retrieve non-particle data, from the last read frame set. Obsolete!
2933 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
2934 * which file to read from. If the file (input_file) is not open it will be
2936 * @param block_id is the id number of the particle data block to read.
2937 * @param values is a pointer to a 2-dimensional array (memory unallocated), which
2938 * will be filled with data. The array will be sized
2939 * (n_frames * n_values_per_frame).
2940 * Since ***values is allocated in this function it is the callers
2941 * responsibility to free the memory.
2942 * @param n_frames is set to the number of frames in the returned data. This is
2943 * needed to properly reach and/or free the data afterwards.
2944 * @param n_values_per_frame is set to the number of values per frame in the data.
2945 * This is needed to properly reach and/or free the data afterwards.
2946 * @param type is set to the data type of the data in the array.
2947 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2948 * must be initialised before using it.
2949 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
2950 * must not be a NULL pointer.
2951 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
2952 * values per frame must not be a NULL pointer.
2953 * @pre \code type != 0 \endcode The pointer to the data type must not
2954 * be a NULL pointer.
2955 * @details This function is obsolete and only retained for compatibility. Use
2956 * tng_data_vector_get() instead.
2957 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2958 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2960 tng_function_status DECLSPECDLLEXPORT tng_data_get(const tng_trajectory_t tng_data,
2961 const int64_t block_id,
2962 union data_values ***values,
2964 int64_t *n_values_per_frame,
2968 * @brief Retrieve a vector (1D array) of non-particle data, from the last read frame set.
2969 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
2970 * which file to read from. If the file (input_file) is not open it will be
2972 * @param block_id is the id number of the particle data block to read.
2973 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
2974 * will be filled with data. The length of the array will be (n_frames * n_values_per_frame).
2975 * Since **values is allocated in this function it is the callers
2976 * responsibility to free the memory.
2977 * @param n_frames is set to the number of particles in the returned data. This is
2978 * needed to properly reach and/or free the data afterwards.
2979 * @param stride_length is set to the stride length of the returned data.
2980 * @param n_values_per_frame is set to the number of values per frame in the data.
2981 * This is needed to properly reach and/or free the data afterwards.
2982 * @param type is set to the data type of the data in the array.
2983 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2984 * must be initialised before using it.
2985 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
2986 * must not be a NULL pointer.
2987 * @pre \code stride_length != 0 \endcode The pointer to the stride length
2988 * must not be a NULL pointer.
2989 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
2990 * values per frame must not be a NULL pointer.
2991 * @pre \code type != 0 \endcode The pointer to the data type must not
2992 * be a NULL pointer.
2993 * @details This does only work for numerical (int, float, double) data.
2994 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2995 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2997 tng_function_status DECLSPECDLLEXPORT tng_data_vector_get
2998 (const tng_trajectory_t tng_data,
2999 const int64_t block_id,
3002 int64_t *stride_length,
3003 int64_t *n_values_per_frame,
3007 * @brief Read and retrieve non-particle data, in a specific interval. Obsolete!
3008 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
3009 * which file to read from. If the file (input_file) is not open it will be
3011 * @param block_id is the id number of the particle data block to read.
3012 * @param start_frame_nr is the index number of the first frame to read.
3013 * @param end_frame_nr is the index number of the last frame to read.
3014 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3015 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3016 * compared to the md5 hash of the read contents to ensure valid data.
3017 * @param values is a pointer to a 2-dimensional array (memory unallocated), which
3018 * will be filled with data. The array will be sized
3019 * (n_frames * n_values_per_frame).
3020 * Since ***values is allocated in this function it is the callers
3021 * responsibility to free the memory.
3022 * @param n_values_per_frame is set to the number of values per frame in the data.
3023 * This is needed to properly reach and/or free the data afterwards.
3024 * @param type is set to the data type of the data in the array.
3025 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3026 * must be initialised before using it.
3027 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3029 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3030 * values per frame must not be a NULL pointer.
3031 * @pre \code type != 0 \endcode The pointer to the data type must not
3032 * be a NULL pointer.
3033 * @details This function is obsolete and only retained for compatibility. Use
3034 * tng_data_vector_interval_get() instead.
3035 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3036 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3038 tng_function_status DECLSPECDLLEXPORT tng_data_interval_get
3039 (const tng_trajectory_t tng_data,
3040 const int64_t block_id,
3041 const int64_t start_frame_nr,
3042 const int64_t end_frame_nr,
3043 const char hash_mode,
3044 union data_values ***values,
3045 int64_t *n_values_per_frame,
3049 * @brief Read and retrieve a vector (1D array) of non-particle data,
3050 * in a specific interval.
3051 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
3052 * which file to read from. If the file (input_file) is not open it will be
3054 * @param block_id is the id number of the particle data block to read.
3055 * @param start_frame_nr is the index number of the first frame to read.
3056 * @param end_frame_nr is the index number of the last frame to read.
3057 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3058 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3059 * compared to the md5 hash of the read contents to ensure valid data.
3060 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
3061 * will be filled with data. The length of the array will be (n_frames * n_values_per_frame).
3062 * Since **values is allocated in this function it is the callers
3063 * responsibility to free the memory.
3064 * @param stride_length is set to the stride length (writing interval) of
3066 * @param n_values_per_frame is set to the number of values per frame in the data.
3067 * This is needed to properly reach and/or free the data afterwards.
3068 * @param type is set to the data type of the data in the array.
3069 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3070 * must be initialised before using it.
3071 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3073 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3074 * must not be a NULL pointer.
3075 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3076 * values per frame must not be a NULL pointer.
3077 * @pre \code type != 0 \endcode The pointer to the data type must not
3078 * be a NULL pointer.
3079 * @details This does only work for numerical (int, float, double) data.
3080 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3081 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3083 tng_function_status DECLSPECDLLEXPORT tng_data_vector_interval_get
3084 (const tng_trajectory_t tng_data,
3085 const int64_t block_id,
3086 const int64_t start_frame_nr,
3087 const int64_t end_frame_nr,
3088 const char hash_mode,
3090 int64_t *stride_length,
3091 int64_t *n_values_per_frame,
3095 * @brief Retrieve particle data, from the last read frame set. Obsolete!
3096 * @details The particle dimension of the returned values array is translated
3097 * to real particle numbering, i.e. the numbering of the actual molecular
3099 * @param tng_data is a trajectory data container. tng_data->input_file_path
3100 * specifies which file to read from. If the file (input_file) is not open it
3102 * @param block_id is the id number of the particle data block to read.
3103 * @param values is a pointer to a 3-dimensional array (memory unallocated), which
3104 * will be filled with data. The array will be sized
3105 * (n_frames * n_particles * n_values_per_frame).
3106 * Since ****values is allocated in this function it is the callers
3107 * responsibility to free the memory.
3108 * @param n_frames is set to the number of frames in the returned data. This is
3109 * needed to properly reach and/or free the data afterwards.
3110 * @param n_particles is set to the number of particles in the returned data. This is
3111 * needed to properly reach and/or free the data afterwards.
3112 * @param n_values_per_frame is set to the number of values per frame in the data.
3113 * This is needed to properly reach and/or free the data afterwards.
3114 * @param type is set to the data type of the data in the array.
3115 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3116 * must be initialised before using it.
3117 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
3118 * must not be a NULL pointer.
3119 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3120 * not be a NULL pointer.
3121 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3122 * values per frame must not be a NULL pointer.
3123 * @pre \code type != 0 \endcode The pointer to the data type must not
3124 * be a NULL pointer.
3125 * @details This function is obsolete and only retained for compatibility. Use
3126 * tng_particle_data_vector_get() instead.
3127 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3128 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3130 tng_function_status DECLSPECDLLEXPORT tng_particle_data_get
3131 (const tng_trajectory_t tng_data,
3132 const int64_t block_id,
3133 union data_values ****values,
3135 int64_t *n_particles,
3136 int64_t *n_values_per_frame,
3140 * @brief Retrieve a vector (1D array) of particle data, from the last read frame set.
3141 * @details The particle dimension of the returned values array is translated
3142 * to real particle numbering, i.e. the numbering of the actual molecular
3144 * @param tng_data is a trajectory data container. tng_data->input_file_path
3145 * specifies which file to read from. If the file (input_file) is not open it
3147 * @param block_id is the id number of the particle data block to read.
3148 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
3149 * will be filled with data. The length of the array will be
3150 * (n_frames * n_particles * n_values_per_frame).
3151 * Since **values is allocated in this function it is the callers
3152 * responsibility to free the memory.
3153 * @param n_frames is set to the number of frames in the returned data. This is
3154 * needed to properly reach and/or free the data afterwards.
3155 * @param stride_length is set to the stride length of the returned data.
3156 * @param n_particles is set to the number of particles in the returned data. This is
3157 * needed to properly reach and/or free the data afterwards.
3158 * @param n_values_per_frame is set to the number of values per frame in the data.
3159 * This is needed to properly reach and/or free the data afterwards.
3160 * @param type is set to the data type of the data in the array.
3161 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3162 * must be initialised before using it.
3163 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3164 * not be a NULL pointer.
3165 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3166 * must not be a NULL pointer.
3167 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3168 * values per frame must not be a NULL pointer.
3169 * @pre \code type != 0 \endcode The pointer to the data type must not
3170 * be a NULL pointer.
3171 * @details This does only work for numerical (int, float, double) data.
3172 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3173 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3175 tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_get
3176 (const tng_trajectory_t tng_data,
3177 const int64_t block_id,
3180 int64_t *stride_length,
3181 int64_t *n_particles,
3182 int64_t *n_values_per_frame,
3186 * @brief Read and retrieve particle data, in a specific interval. Obsolete!
3187 * @details The particle dimension of the returned values array is translated
3188 * to real particle numbering, i.e. the numbering of the actual molecular
3190 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
3191 * which file to read from. If the file (input_file) is not open it will be
3193 * @param block_id is the id number of the particle data block to read.
3194 * @param start_frame_nr is the index number of the first frame to read.
3195 * @param end_frame_nr is the index number of the last frame to read.
3196 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3197 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3198 * compared to the md5 hash of the read contents to ensure valid data.
3199 * @param values is a pointer to a 3-dimensional array (memory unallocated), which
3200 * will be filled with data. The array will be sized
3201 * (n_frames * n_particles * n_values_per_frame).
3202 * Since ****values is allocated in this function it is the callers
3203 * responsibility to free the memory.
3204 * @param n_particles is set to the number of particles in the returned data. This is
3205 * needed to properly reach and/or free the data afterwards.
3206 * @param n_values_per_frame is set to the number of values per frame in the data.
3207 * This is needed to properly reach and/or free the data afterwards.
3208 * @param type is set to the data type of the data in the array.
3209 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3210 * must be initialised before using it.
3211 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
3212 * must not be a NULL pointer.
3213 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3215 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3216 * not be a NULL pointer.
3217 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3218 * values per frame must not be a NULL pointer.
3219 * @pre \code type != 0 \endcode The pointer to the data type must not
3220 * be a NULL pointer.
3221 * @details This function is obsolete and only retained for compatibility. Use
3222 * tng_particle_data_vector_interval_get() instead.
3223 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3224 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3226 tng_function_status DECLSPECDLLEXPORT tng_particle_data_interval_get
3227 (const tng_trajectory_t tng_data,
3228 const int64_t block_id,
3229 const int64_t start_frame_nr,
3230 const int64_t end_frame_nr,
3231 const char hash_mode,
3232 union data_values ****values,
3233 int64_t *n_particles,
3234 int64_t *n_values_per_frame,
3238 * @brief Read and retrieve a vector (1D array) particle data, in a
3239 * specific interval.
3240 * @details The particle dimension of the returned values array is translated
3241 * to real particle numbering, i.e. the numbering of the actual molecular
3243 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
3244 * which file to read from. If the file (input_file) is not open it will be
3246 * @param block_id is the id number of the particle data block to read.
3247 * @param start_frame_nr is the index number of the first frame to read.
3248 * @param end_frame_nr is the index number of the last frame to read.
3249 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3250 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3251 * compared to the md5 hash of the read contents to ensure valid data.
3252 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
3253 * will be filled with data. The length of the array will be
3254 * (n_frames * n_particles * n_values_per_frame).
3255 * Since **values is allocated in this function it is the callers
3256 * responsibility to free the memory.
3257 * @param stride_length is set to the stride length (writing interval) of
3259 * @param n_particles is set to the number of particles in the returned data. This is
3260 * needed to properly reach and/or free the data afterwards.
3261 * @param n_values_per_frame is set to the number of values per frame in the data.
3262 * This is needed to properly reach and/or free the data afterwards.
3263 * @param type is set to the data type of the data in the array.
3264 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3265 * must be initialised before using it.
3266 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3268 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3269 * not be a NULL pointer.
3270 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3271 * must not be a NULL pointer.
3272 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3273 * values per frame must not be a NULL pointer.
3274 * @pre \code type != 0 \endcode The pointer to the data type must not
3275 * be a NULL pointer.
3276 * @details This does only work for numerical (int, float, double) data.
3277 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3278 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3280 tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_interval_get
3281 (const tng_trajectory_t tng_data,
3282 const int64_t block_id,
3283 const int64_t start_frame_nr,
3284 const int64_t end_frame_nr,
3285 const char hash_mode,
3287 int64_t *n_particles,
3288 int64_t *stride_length,
3289 int64_t *n_values_per_frame,
3293 * @brief Get the stride length of a specific data (particle dependency does not matter)
3294 * block, either in the current frame set or of a specific frame.
3295 * @param tng_data is the trajectory data container.
3296 * @param block_id is the block ID of the data block, of which to retrieve the
3297 * stride length of the data.
3298 * @param frame is the frame from which to get the stride length. If frame is set to -1
3299 * no specific frame will be used, but instead the first frame, starting from the last read
3300 * frame set, containing the data block will be used.
3301 * @param stride_length is set to the value of the stride length of the data block.
3302 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3303 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3305 tng_function_status DECLSPECDLLEXPORT tng_data_get_stride_length
3306 (const tng_trajectory_t tng_data,
3307 const int64_t block_id,
3309 int64_t *stride_length);
3312 * @brief Get the date and time of initial file creation in ISO format (string).
3313 * @param tng_data is a trajectory data container.
3314 * @param time is a pointer to the string in which the date will be stored. Memory
3315 * must be reserved beforehand.
3316 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3317 * must be initialised before using it.
3318 * @pre \code time != 0 \endcode The pointer to the time must not be a NULL
3320 * @return TNG_SUCCESS (0) if successful.
3322 tng_function_status DECLSPECDLLEXPORT tng_time_get_str
3323 (const tng_trajectory_t tng_data,
3325 /** @} */ /* end of group1 */
3327 /** @defgroup group2 High-level API
3328 * These functions make it easier to access and output TNG data. They
3329 * are recommended unless there is a special reason to use the more
3330 * detailed functions available in the low-level API.
3335 * @brief High-level function for opening and initializing a TNG trajectory.
3336 * @param filename is a string containing the name of the trajectory to open.
3337 * @param mode specifies the file mode of the trajectory. Can be set to 'r',
3338 * 'w' or 'a' for reading, writing or appending respectively.
3339 * @param tng_data_p is a pointer to the opened trajectory. This will be
3340 * allocated by the TNG library. The trajectory must be
3341 * closed by the user, whereby memory is freed.
3342 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3343 * must be initialised before using it.
3344 * @pre \code filename != 0 \endcode The pointer to the filename must not be a
3346 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3347 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3350 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_open
3351 (const char *filename,
3353 tng_trajectory_t *tng_data_p);
3356 * @brief High-level function for closing a TNG trajectory.
3357 * @param tng_data_p is a pointer to the trajectory to close. The memory
3358 * will be freed after finalising the writing.
3359 * @return TNG_SUCCESS (0) if successful.
3361 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_close
3362 (tng_trajectory_t *tng_data_p);
3365 * @brief High-level function for getting the time (in seconds) of a frame.
3366 * @param tng_data is the trajectory containing the frame.
3367 * @param frame_nr is the frame number of which to get the time.
3368 * @param time is set to the time (in seconds) of the specified frame.
3369 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3370 * must be initialised before using it.
3371 * @pre \code time != 0 \endcode The pointer to the time must not be a
3373 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if a
3374 * minor error has occured.
3376 tng_function_status DECLSPECDLLEXPORT tng_util_time_of_frame_get
3377 (const tng_trajectory_t tng_data,
3378 const int64_t frame_nr,
3382 * @brief High-level function for getting the molecules in the mol system.
3383 * @param tng_data is the trajectory containing the mol system.
3384 * @param n_mols is set to the number of molecules in the system.
3385 * @param molecule_cnt_list will be pointing to the list of counts of each molecule
3386 * in the mol system.
3387 * @param mols pointing to the list of molecules in the mol system.
3388 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3389 * must be initialised before using it.
3390 * @pre \code n_mols != 0 \endcode The pointer to the number of molecules must
3391 * not be a NULL pointer.
3392 * @return TNG_SUCCESS (0) if successful.
3394 /*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecules_get
3395 (const tng_trajectory_t tng_data,
3397 int64_t **molecule_cnt_list,
3398 tng_molecule_t *mols);
3401 * @brief High-level function for adding a molecule to the mol system.
3402 * @param tng_data is the trajectory containing the mol system.
3403 * @param name is the name of the molecule to add.
3404 * @param cnt is the count of the molecule.
3405 * @param mol is set to point to the newly created molecule.
3406 * @pre \code name != 0 \endcode The pointer to the name must not be a
3408 * @pre \code cnt >= 0 \endcode The requested count must be >= 0.
3409 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3410 * has occured or TNG_CRITICAL (2) if a major error has occured.
3412 /*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecule_add
3413 (const tng_trajectory_t tng_data,
3416 tng_molecule_t *mol);
3419 // tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_get
3420 // (const tng_trajectory_t tng_data,
3421 // const tng_molecule_t mol,
3422 // int64_t *n_particles,
3425 // char ***res_names,
3426 // int64_t **res_ids,
3427 // char ***chain_names,
3428 // int64_t **chain_ids);
3430 // tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_set
3431 // (const tng_trajectory_t tng_data,
3432 // tng_molecule_t mol,
3433 // const int64_t n_particles,
3434 // const char **names,
3435 // const char **types,
3436 // const char **res_names,
3437 // const int64_t *res_ids,
3438 // const char **chain_names,
3439 // const int64_t *chain_ids);
3442 * @brief High-level function for reading the positions of all particles
3444 * @param tng_data is the trajectory to read from.
3445 * @param positions will be set to point at a 1-dimensional array of floats,
3446 * which will contain the positions. The data is stored sequentially in order
3447 * of frames. For each frame the positions (x, y and z coordinates) are stored.
3448 * The variable may point at already allocated memory or be a NULL pointer.
3449 * The memory must be freed afterwards.
3450 * @param stride_length will be set to the writing interval of the stored data.
3451 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3452 * must be initialised before using it.
3453 * @pre \code positions != 0 \endcode The pointer to the positions array
3454 * must not be a NULL pointer.
3455 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3456 * must not be a NULL pointer.
3457 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3458 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3461 tng_function_status DECLSPECDLLEXPORT tng_util_pos_read
3462 (const tng_trajectory_t tng_data,
3464 int64_t *stride_length);
3467 * @brief High-level function for reading the velocities of all particles
3469 * @param tng_data is the trajectory to read from.
3470 * @param velocities will be set to point at a 1-dimensional array of floats,
3471 * which will contain the velocities. The data is stored sequentially in order
3472 * of frames. For each frame the velocities (in x, y and z) are stored. The
3473 * variable may point at already allocated memory or be a NULL pointer.
3474 * The memory must be freed afterwards.
3475 * @param stride_length will be set to the writing interval of the stored data.
3476 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3477 * must be initialised before using it.
3478 * @pre \code velocities != 0 \endcode The pointer to the velocities array
3479 * must not be a NULL pointer.
3480 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3481 * must not be a NULL pointer.
3482 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3483 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3486 tng_function_status DECLSPECDLLEXPORT tng_util_vel_read
3487 (const tng_trajectory_t tng_data,
3489 int64_t *stride_length);
3492 * @brief High-level function for reading the forces of all particles
3494 * @param tng_data is the trajectory to read from.
3495 * @param forces will be set to point at a 1-dimensional array of floats,
3496 * which will contain the forces. The data is stored sequentially in order
3497 * of frames. For each frame the forces (in x, y and z) are stored. The
3498 * variable may point at already allocated memory or be a NULL pointer.
3499 * The memory must be freed afterwards.
3500 * @param stride_length will be set to the writing interval of the stored data.
3501 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3502 * must be initialised before using it.
3503 * @pre \code forces != 0 \endcode The pointer to the forces array
3504 * must not be a NULL pointer.
3505 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3506 * must not be a NULL pointer.
3507 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3508 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3511 tng_function_status DECLSPECDLLEXPORT tng_util_force_read
3512 (const tng_trajectory_t tng_data,
3514 int64_t *stride_length);
3517 * @brief High-level function for reading the box shape from all frames.
3518 * @param tng_data is the trajectory to read from.
3519 * @param box_shape will be set to point at a 1-dimensional array of floats,
3520 * which will contain the box shape. The data is stored sequentially in order
3521 * of frames. The variable may point at already allocated memory or be a NULL pointer.
3522 * If the box shape is not modified during the trajectory, but as general data,
3523 * that will be returned instead.
3524 * @param stride_length will be set to the writing interval of the stored data.
3525 * @details This function should only be used if number of values used to specify
3526 * the box shape is known (by default TNG uses 9 values) since it does not
3527 * return the number of values in the array. It is recommended to use
3528 * tng_data_vector_interval_get() instead.
3529 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3530 * must be initialised before using it.
3531 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array
3532 * must not be a NULL pointer.
3533 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3534 * must not be a NULL pointer.
3535 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3536 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3539 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read
3540 (const tng_trajectory_t tng_data,
3542 int64_t *stride_length);
3545 * @brief High-level function for reading the next frame of particle-dependent
3546 * data of a specific type.
3547 * @param tng_data is the trajectory to read from.
3548 * @param block_id is the ID number of the block containing the data of interest.
3549 * @param values will be set to point at a 1-dimensional array containing the
3550 * requested data. The variable may point at already allocated memory or be a
3551 * NULL pointer. The memory must be freed afterwards.
3552 * @param data_type will be pointing to a character indicating the size of the
3553 * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA.
3554 * @param retrieved_frame_number will be pointing at the frame number of the
3556 * @param retrieved_time will be pointing at the time stamp of the returned
3558 * @details If no frame has been read before the first frame of the trajectory
3560 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3561 * must be initialised before using it.
3562 * @pre \code values != 0 \endcode The pointer to the values array
3563 * must not be a NULL pointer.
3564 * @pre \code data_type != 0 \endcode The pointer to the data type of the
3565 * returned data must not be a NULL pointer.
3566 * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame
3567 * number of the returned data must not be a NULL pointer.
3568 * @pre \code retrieved_time != 0 \endcode The pointer to the time of the
3569 * returned data must not be a NULL pointer.
3570 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3571 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3574 tng_function_status DECLSPECDLLEXPORT tng_util_particle_data_next_frame_read
3575 (const tng_trajectory_t tng_data,
3576 const int64_t block_id,
3579 int64_t *retrieved_frame_number,
3580 double *retrieved_time);
3583 * @brief High-level function for reading the next frame of non-particle-dependent
3584 * data of a specific type.
3585 * @param tng_data is the trajectory to read from.
3586 * @param block_id is the ID number of the block containing the data of interest.
3587 * @param values will be set to point at a 1-dimensional array containing the
3588 * requested data. The variable may point at already allocated memory or be a
3589 * NULL pointer. The memory must be freed afterwards.
3590 * @param data_type will be pointing to a character indicating the size of the
3591 * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA.
3592 * @param retrieved_frame_number will be pointing at the frame number of the
3594 * @param retrieved_time will be pointing at the time stamp of the returned
3596 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3597 * must be initialised before using it.
3598 * @pre \code values != 0 \endcode The pointer to the values array
3599 * must not be a NULL pointer.
3600 * @pre \code data_type != 0 \endcode The pointer to the data type of the
3601 * returned data must not be a NULL pointer.
3602 * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame
3603 * number of the returned data must not be a NULL pointer.
3604 * @pre \code retrieved_time != 0 \endcode The pointer to the time of the
3605 * returned data must not be a NULL pointer.
3606 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3607 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3610 tng_function_status DECLSPECDLLEXPORT tng_util_non_particle_data_next_frame_read
3611 (const tng_trajectory_t tng_data,
3612 const int64_t block_id,
3615 int64_t *retrieved_frame_number,
3616 double *retrieved_time);
3619 * @brief High-level function for reading the positions of all particles
3620 * from a specific range of frames.
3621 * @param tng_data is the trajectory to read from.
3622 * @param first_frame is the first frame to return position data from.
3623 * @param last_frame is the last frame to return position data from.
3624 * @param positions will be set to point at a 1-dimensional array of floats,
3625 * which will contain the positions. The data is stored sequentially in order
3626 * of frames. For each frame the positions (x, y and z coordinates) are stored.
3627 * The variable may point at already allocated memory or be a NULL pointer.
3628 * The memory must be freed afterwards.
3629 * @param stride_length will be set to the writing interval of the stored data.
3630 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3631 * must be initialised before using it.
3632 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3634 * @pre \code positions != 0 \endcode The pointer to the positions array
3635 * must not be a NULL pointer.
3636 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3637 * must not be a NULL pointer.
3638 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3639 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3642 tng_function_status DECLSPECDLLEXPORT tng_util_pos_read_range
3643 (const tng_trajectory_t tng_data,
3644 const int64_t first_frame,
3645 const int64_t last_frame,
3647 int64_t *stride_length);
3650 * @brief High-level function for reading the velocities of all particles
3651 * from a specific range of frames.
3652 * @param tng_data is the trajectory to read from.
3653 * @param first_frame is the first frame to return position data from.
3654 * @param last_frame is the last frame to return position data from.
3655 * @param velocities will be set to point at a 1-dimensional array of floats,
3656 * which will contain the velocities. The data is stored sequentially in order
3657 * of frames. For each frame the velocities (in x, y and z) are stored. The
3658 * variable may point at already allocated memory or be a NULL pointer.
3659 * The memory must be freed afterwards.
3660 * @param stride_length will be set to the writing interval of the stored data.
3661 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3662 * must be initialised before using it.
3663 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3665 * @pre \code velocities != 0 \endcode The pointer to the velocities array
3666 * must not be a NULL pointer.
3667 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3668 * must not be a NULL pointer.
3669 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3670 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3673 tng_function_status DECLSPECDLLEXPORT tng_util_vel_read_range
3674 (const tng_trajectory_t tng_data,
3675 const int64_t first_frame,
3676 const int64_t last_frame,
3678 int64_t *stride_length);
3681 * @brief High-level function for reading the forces of all particles
3682 * from a specific range of frames.
3683 * @param tng_data is the trajectory to read from.
3684 * @param first_frame is the first frame to return position data from.
3685 * @param last_frame is the last frame to return position data from.
3686 * @param forces will be set to point at a 1-dimensional array of floats,
3687 * which will contain the forces. The data is stored sequentially in order
3688 * of frames. For each frame the forces (in x, y and z) are stored. The
3689 * variable may point at already allocated memory or be a NULL pointer.
3690 * The memory must be freed afterwards.
3691 * @param stride_length will be set to the writing interval of the stored data.
3692 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3693 * must be initialised before using it.
3694 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3696 * @pre \code forces != 0 \endcode The pointer to the forces array
3697 * must not be a NULL pointer.
3698 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3699 * must not be a NULL pointer.
3700 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3701 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3704 tng_function_status DECLSPECDLLEXPORT tng_util_force_read_range
3705 (const tng_trajectory_t tng_data,
3706 const int64_t first_frame,
3707 const int64_t last_frame,
3709 int64_t *stride_length);
3712 * @brief High-level function for reading the box shape
3713 * from a specific range of frames.
3714 * @param tng_data is the trajectory to read from.
3715 * @param first_frame is the first frame to return position data from.
3716 * @param last_frame is the last frame to return position data from.
3717 * @param box_shape will be set to point at a 1-dimensional array of floats,
3718 * which will contain the box shape. The data is stored sequentially in order
3720 * If the box shape is not modified during the trajectory, but as general data,
3721 * that will be returned instead. The
3722 * variable may point at already allocated memory or be a NULL pointer.
3723 * The memory must be freed afterwards.
3724 * @param stride_length will be set to the writing interval of the stored data.
3725 * @details This function should only be used if number of values used to specify
3726 * the box shape is known (by default TNG uses 9 values) since it does not
3727 * return the number of values in the array. It is recommended to use
3728 * tng_data_vector_interval_get() instead.
3729 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3730 * must be initialised before using it.
3731 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3733 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array
3734 * must not be a NULL pointer.
3735 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3736 * must not be a NULL pointer.
3737 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3738 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3741 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read_range
3742 (const tng_trajectory_t tng_data,
3743 const int64_t first_frame,
3744 const int64_t last_frame,
3746 int64_t *stride_length);
3749 * @brief High-level function for setting the writing interval of data blocks.
3750 * @param tng_data is the trajectory to use.
3751 * @param i is the output interval, i.e. i == 10 means data written every 10th
3753 * @param n_values_per_frame is the number of values to store per frame. If the
3754 * data is particle dependent there will be n_values_per_frame stored per
3755 * particle each frame.
3756 * @param block_id is the ID of the block, of which to set the output interval.
3757 * @param block_name is a string that will be used as name of the block. Only
3758 * required if the block did not exist, i.e. a new block is created.
3759 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
3760 * data is not related to specific particles (e.g. box shape) or
3761 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
3762 * positions). Only required if the block did not exist, i.e. a new block is
3764 * @param compression is the compression routine to use when writing the data.
3765 * Only required if the block did not exist, i.e. a new block is created.
3766 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3767 * must be initialised before using it.
3768 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3769 * @details n_values_per_frame, block_name, particle_dependency and
3770 * compression are only used if the data block did not exist before calling
3771 * this function, in which case it is created.
3772 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3773 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3776 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_set
3777 (const tng_trajectory_t tng_data,
3779 const int64_t n_values_per_frame,
3780 const int64_t block_id,
3781 const char *block_name,
3782 const char particle_dependency,
3783 const char compression);
3786 * @brief High-level function for setting the writing interval of data blocks
3787 * containing double precision data.
3788 * @param tng_data is the trajectory to use.
3789 * @param i is the output interval, i.e. i == 10 means data written every 10th
3791 * @param n_values_per_frame is the number of values to store per frame. If the
3792 * data is particle dependent there will be n_values_per_frame stored per
3793 * particle each frame.
3794 * @param block_id is the ID of the block, of which to set the output interval.
3795 * @param block_name is a string that will be used as name of the block. Only
3796 * required if the block did not exist, i.e. a new block is created.
3797 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
3798 * data is not related to specific particles (e.g. box shape) or
3799 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
3800 * positions). Only required if the block did not exist, i.e. a new block is
3802 * @param compression is the compression routine to use when writing the data.
3803 * Only required if the block did not exist, i.e. a new block is created.
3804 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3805 * must be initialised before using it.
3806 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3807 * @details n_values_per_frame, block_name, particle_dependency and
3808 * compression are only used if the data block did not exist before calling
3809 * this function, in which case it is created.
3810 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3811 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3814 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_double_set
3815 (const tng_trajectory_t tng_data,
3817 const int64_t n_values_per_frame,
3818 const int64_t block_id,
3819 const char *block_name,
3820 const char particle_dependency,
3821 const char compression);
3824 * @brief High-level function for setting the writing interval of data blocks.
3825 * Obsolete! Use tng_util_generic_write_interval_set()
3826 * @param tng_data is the trajectory to use.
3827 * @param i is the output interval, i.e. i == 10 means data written every 10th
3829 * @param n_values_per_frame is the number of values to store per frame. If the
3830 * data is particle dependent there will be n_values_per_frame stored per
3831 * particle each frame.
3832 * @param block_id is the ID of the block, of which to set the output interval.
3833 * @param block_name is a string that will be used as name of the block. Only
3834 * required if the block did not exist, i.e. a new block is created.
3835 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
3836 * data is not related to specific particles (e.g. box shape) or
3837 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
3838 * positions). Only required if the block did not exist, i.e. a new block is
3840 * @param compression is the compression routine to use when writing the data.
3841 * Only required if the block did not exist, i.e. a new block is created.
3842 * @details n_values_per_frame, block_name, particle_dependency and
3843 * compression are only used if the data block did not exist before calling
3844 * this function, in which case it is created.
3845 * This function is replaced by the more correcly named
3846 * tng_util_generic_write_interval_set(), but is kept for compatibility.
3847 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3848 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3851 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_frequency_set
3852 (const tng_trajectory_t tng_data,
3854 const int64_t n_values_per_frame,
3855 const int64_t block_id,
3856 const char *block_name,
3857 const char particle_dependency,
3858 const char compression);
3861 * @brief High-level function for setting the writing interval of position
3863 * @param tng_data is the trajectory to use.
3864 * @param i is the output interval, i.e. i == 10 means data written every 10th
3866 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3867 * must be initialised before using it.
3868 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3869 * @details This function uses tng_util_generic_write_interval_set() and will
3870 * create a positions data block if none exists.
3871 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3872 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3875 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_set
3876 (const tng_trajectory_t tng_data,
3880 * @brief High-level function for setting the writing interval of position
3881 * data blocks containing double precision data.
3882 * @param tng_data is the trajectory to use.
3883 * @param i is the output interval, i.e. i == 10 means data written every 10th
3885 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3886 * must be initialised before using it.
3887 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3888 * @details This function uses tng_util_generic_write_interval_set() and will
3889 * create a positions data block if none exists.
3890 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3891 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3894 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_double_set
3895 (const tng_trajectory_t tng_data,
3899 * @brief High-level function for setting the writing interval of position
3900 * data blocks. Obsolete! Use tng_util_pos_write_interval_set()
3901 * @param tng_data is the trajectory to use.
3902 * @param i is the output interval, i.e. i == 10 means data written every 10th
3904 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3905 * must be initialised before using it.
3906 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3907 * @details This function uses tng_util_generic_write_interval_set() and will
3908 * create a positions data block if none exists.
3909 * This function is replaced by the more correcly named
3910 * tng_util_pos_write_interval_set(), but is kept for compatibility.
3911 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3912 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3915 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_frequency_set
3916 (const tng_trajectory_t tng_data,
3920 * @brief High-level function for setting the writing interval of velocity
3922 * @param tng_data is the trajectory to use.
3923 * @param i is the output interval, i.e. i == 10 means data written every 10th
3925 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3926 * must be initialised before using it.
3927 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3928 * @details This function uses tng_util_generic_write_interval_set() and will
3929 * create a velocities data block if none exists.
3930 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3931 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3934 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_set
3935 (const tng_trajectory_t tng_data,
3939 * @brief High-level function for setting the writing interval of velocity
3940 * data blocks containing double precision data.
3941 * @param tng_data is the trajectory to use.
3942 * @param i is the output interval, i.e. i == 10 means data written every 10th
3944 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3945 * must be initialised before using it.
3946 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3947 * @details This function uses tng_util_generic_write_interval_set() and will
3948 * create a velocities data block if none exists.
3949 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3950 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3953 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_double_set
3954 (const tng_trajectory_t tng_data,
3958 * @brief High-level function for setting the writing interval of velocity
3959 * data blocks. Obsolete! Use tng_util_vel_write_interval_set()
3960 * @param tng_data is the trajectory to use.
3961 * @param i is the output interval, i.e. i == 10 means data written every 10th
3963 * @details This function uses tng_util_generic_write_interval_set() and will
3964 * create a velocities data block if none exists.
3965 * This function is replaced by the more correcly named
3966 * tng_util_vel_write_interval_set(), but is kept for compatibility.
3967 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3968 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3971 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_frequency_set
3972 (const tng_trajectory_t tng_data,
3976 * @brief High-level function for setting the writing interval of force
3978 * @param tng_data is the trajectory to use.
3979 * @param i is the output interval, i.e. i == 10 means data written every 10th
3981 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3982 * must be initialised before using it.
3983 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3984 * @details This function uses tng_util_generic_write_interval_set() and will
3985 * create a forces data block if none exists.
3986 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3987 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3990 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_set
3991 (const tng_trajectory_t tng_data,
3995 * @brief High-level function for setting the writing interval of force
3996 * data blocks containing double precision data.
3997 * @param tng_data is the trajectory to use.
3998 * @param i is the output interval, i.e. i == 10 means data written every 10th
4000 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4001 * must be initialised before using it.
4002 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
4003 * @details This function uses tng_util_generic_write_interval_set() and will
4004 * create a forces data block if none exists.
4005 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4006 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4009 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_double_set
4010 (const tng_trajectory_t tng_data,
4014 * @brief High-level function for setting the writing interval of force
4015 * data blocks. Obsolete! Use tng_util_force_write_interval_set()
4016 * @param tng_data is the trajectory to use.
4017 * @param i is the output interval, i.e. i == 10 means data written every 10th
4019 * @details This function uses tng_util_generic_write_interval_set() and will
4020 * create a forces data block if none exists.
4021 * This function is replaced by the more correcly named
4022 * tng_util_force_write_interval_set(), but is kept for compatibility.
4023 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4024 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4027 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_frequency_set
4028 (const tng_trajectory_t tng_data,
4032 * @brief High-level function for setting the writing interval of box shape
4034 * @param tng_data is the trajectory to use.
4035 * @param i is the output interval, i.e. i == 10 means data written every 10th
4037 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4038 * must be initialised before using it.
4039 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
4040 * @details This function uses tng_util_generic_write_interval_set() and will
4041 * create a box shape data block if none exists.
4042 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4043 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4046 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_set
4047 (const tng_trajectory_t tng_data,
4051 * @brief High-level function for setting the writing interval of box shape
4052 * data blocks containing double precision data.
4053 * @param tng_data is the trajectory to use.
4054 * @param i is the output interval, i.e. i == 10 means data written every 10th
4056 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4057 * must be initialised before using it.
4058 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
4059 * @details This function uses tng_util_generic_write_interval_set() and will
4060 * create a box shape data block if none exists.
4061 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4062 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4065 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_double_set
4066 (const tng_trajectory_t tng_data,
4070 * @brief High-level function for setting the writing interval of velocity
4071 * data blocks. Obsolete! Use tng_util_box_shape_write_interval_set()
4072 * @param tng_data is the trajectory to use.
4073 * @param i is the output interval, i.e. i == 10 means data written every 10th
4075 * @details This function uses tng_util_generic_write_interval_set() and will
4076 * create a box shape data block if none exists.
4077 * This function is replaced by the more correcly named
4078 * tng_util_box_shape_write_interval_set(), but is kept for compatibility.
4079 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4080 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4083 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_frequency_set
4084 (const tng_trajectory_t tng_data,
4088 * @brief High-level function for writing data of one frame to a data block.
4089 * @param tng_data is the trajectory to use.
4090 * @param frame_nr is the frame number of the data. If frame_nr < 0 the
4091 * data is written as non-trajectory data.
4092 * @param values is a 1D array of data to add. The array should be of length
4093 * n_particles * n_values_per_frame if writing particle related data, otherwise
4094 * it should be n_values_per_frame.
4095 * @param n_values_per_frame is the number of values to store per frame. If the
4096 * data is particle dependent there will be n_values_per_frame stored per
4097 * particle each frame.
4098 * @param block_id is the ID of the block, of which to set the output interval.
4099 * @param block_name is a string that will be used as name of the block. Only
4100 * required if the block did not exist, i.e. a new block is created.
4101 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4102 * data is not related to specific particles (e.g. box shape) or
4103 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4104 * positions). Only required if the block did not exist, i.e. a new block is
4106 * @param compression is the compression routine to use when writing the data.
4107 * Only required if the block did not exist, i.e. a new block is created.
4108 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4109 * must be initialised before using it.
4110 * @pre \code values != 0 \endcode The pointer to the values array must not
4111 * be a NULL pointer.
4112 * @details n_values_per_frame, block_name, particle_dependency and
4113 * compression are only used if the data block did not exist before calling
4114 * this function, in which case it is created.
4115 * N.b. Data is written a whole block at a time. The data is not
4116 * actually written to disk until the frame set is finished or the TNG
4117 * trajectory is closed.
4118 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4119 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4122 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write
4123 (const tng_trajectory_t tng_data,
4124 const int64_t frame_nr,
4125 const float *values,
4126 const int64_t n_values_per_frame,
4127 const int64_t block_id,
4128 const char *block_name,
4129 const char particle_dependency,
4130 const char compression);
4133 * @brief High-level function for writing data of one frame to a double precision
4135 * @param tng_data is the trajectory to use.
4136 * @param frame_nr is the frame number of the data. If frame_nr < 0 the
4137 * data is written as non-trajectory data.
4138 * @param values is a 1D array of data to add. The array should be of length
4139 * n_particles * n_values_per_frame if writing particle related data, otherwise
4140 * it should be n_values_per_frame.
4141 * @param n_values_per_frame is the number of values to store per frame. If the
4142 * data is particle dependent there will be n_values_per_frame stored per
4143 * particle each frame.
4144 * @param block_id is the ID of the block, of which to set the output interval.
4145 * @param block_name is a string that will be used as name of the block. Only
4146 * required if the block did not exist, i.e. a new block is created.
4147 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4148 * data is not related to specific particles (e.g. box shape) or
4149 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4150 * positions). Only required if the block did not exist, i.e. a new block is
4152 * @param compression is the compression routine to use when writing the data.
4153 * Only required if the block did not exist, i.e. a new block is created.
4154 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4155 * must be initialised before using it.
4156 * @pre \code values != 0 \endcode The pointer to the values array must not
4157 * be a NULL pointer.
4158 * @details n_values_per_frame, block_name, particle_dependency and
4159 * compression are only used if the data block did not exist before calling
4160 * this function, in which case it is created.
4161 * N.b. Data is written a whole block at a time. The data is not
4162 * actually written to disk until the frame set is finished or the TNG
4163 * trajectory is closed.
4164 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4165 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4168 tng_function_status DECLSPECDLLEXPORT tng_util_generic_double_write
4169 (const tng_trajectory_t tng_data,
4170 const int64_t frame_nr,
4171 const double *values,
4172 const int64_t n_values_per_frame,
4173 const int64_t block_id,
4174 const char *block_name,
4175 const char particle_dependency,
4176 const char compression);
4179 * @brief High-level function for adding data to positions data blocks.
4180 * @param tng_data is the trajectory to use.
4181 * @param frame_nr is the frame number of the data. If frame_nr < 0 the
4182 * data is written as non-trajectory data.
4183 * @param positions is a 1D array of data to add. The array should be of length
4185 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4186 * must be initialised before using it.
4187 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4188 * be a NULL pointer.
4189 * @details This function uses tng_util_generic_write() and will
4190 * create a positions data block if none exists. Positions are stored as three
4191 * values per frame and compressed using TNG compression.
4192 * N.b. Since compressed data is written a whole block at a time the data is not
4193 * actually written to disk until the frame set is finished or the TNG
4194 * trajectory is closed.
4195 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4196 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4199 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write
4200 (const tng_trajectory_t tng_data,
4201 const int64_t frame_nr,
4202 const float *positions);
4205 * @brief High-level function for adding data to positions data blocks at double
4207 * @param tng_data is the trajectory to use.
4208 * @param frame_nr is the frame number of the data. If frame_nr < 0 the
4209 * data is written as non-trajectory data.
4210 * @param positions is a 1D array of data to add. The array should be of length
4212 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4213 * must be initialised before using it.
4214 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4215 * be a NULL pointer.
4216 * @details This function uses tng_util_generic_write() and will
4217 * create a positions data block if none exists. Positions are stored as three
4218 * values per frame and compressed using TNG compression.
4219 * N.b. Since compressed data is written a whole block at a time the data is not
4220 * actually written to disk until the frame set is finished or the TNG
4221 * trajectory is closed.
4222 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4223 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4226 tng_function_status DECLSPECDLLEXPORT tng_util_pos_double_write
4227 (const tng_trajectory_t tng_data,
4228 const int64_t frame_nr,
4229 const double *positions);
4232 * @brief High-level function for adding data to velocities data blocks.
4233 * @param tng_data is the trajectory to use.
4234 * @param frame_nr is the frame number of the data. If frame_nr < 0 the
4235 * data is written as non-trajectory data.
4236 * @param velocities is a 1D array of data to add. The array should be of length
4238 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4239 * must be initialised before using it.
4240 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4241 * be a NULL pointer.
4242 * @details This function uses tng_util_generic_write() and will
4243 * create a velocities data block if none exists. Velocities are stored as three
4244 * values per frame and compressed using TNG compression.
4245 * N.b. Since compressed data is written a whole block at a time the data is not
4246 * actually written to disk until the frame set is finished or the TNG
4247 * trajectory is closed.
4248 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4249 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4252 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write
4253 (const tng_trajectory_t tng_data,
4254 const int64_t frame_nr,
4255 const float *velocities);
4258 * @brief High-level function for adding data to velocities data blocks at double
4260 * @param tng_data is the trajectory to use.
4261 * @param frame_nr is the frame number of the data. If frame_nr < 0 the
4262 * data is written as non-trajectory data.
4263 * @param velocities is a 1D array of data to add. The array should be of length
4265 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4266 * must be initialised before using it.
4267 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4268 * be a NULL pointer.
4269 * @details This function uses tng_util_generic_write() and will
4270 * create a velocities data block if none exists. Velocities are stored as three
4271 * values per frame and compressed using TNG compression.
4272 * N.b. Since compressed data is written a whole block at a time the data is not
4273 * actually written to disk until the frame set is finished or the TNG
4274 * trajectory is closed.
4275 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4276 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4279 tng_function_status DECLSPECDLLEXPORT tng_util_vel_double_write
4280 (const tng_trajectory_t tng_data,
4281 const int64_t frame_nr,
4282 const double *velocities);
4285 * @brief High-level function for adding data to forces data blocks.
4286 * @param tng_data is the trajectory to use.
4287 * @param frame_nr is the frame number of the data. If frame_nr < 0 the
4288 * data is written as non-trajectory data.
4289 * @param forces is a 1D array of data to add. The array should be of length
4291 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4292 * must be initialised before using it.
4293 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4294 * be a NULL pointer.
4295 * @details This function uses tng_util_generic_write() and will
4296 * create a forces data block if none exists. Forces are stored as three
4297 * values per frame and compressed using gzip compression.
4298 * N.b. Since compressed data is written a whole block at a time the data is not
4299 * actually written to disk until the frame set is finished or the TNG
4300 * trajectory is closed.
4301 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4302 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4305 tng_function_status DECLSPECDLLEXPORT tng_util_force_write
4306 (const tng_trajectory_t tng_data,
4307 const int64_t frame_nr,
4308 const float *forces);
4311 * @brief High-level function for adding data to forces data blocks at double
4313 * @param tng_data is the trajectory to use.
4314 * @param frame_nr is the frame number of the data. If frame_nr < 0 the
4315 * data is written as non-trajectory data.
4316 * @param forces is a 1D array of data to add. The array should be of length
4318 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4319 * must be initialised before using it.
4320 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4321 * be a NULL pointer.
4322 * @details This function uses tng_util_generic_write() and will
4323 * create a forces data block if none exists. Forces are stored as three
4324 * values per frame and compressed using gzip compression.
4325 * N.b. Since compressed data is written a whole block at a time the data is not
4326 * actually written to disk until the frame set is finished or the TNG
4327 * trajectory is closed.
4328 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4329 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4332 tng_function_status DECLSPECDLLEXPORT tng_util_force_double_write
4333 (const tng_trajectory_t tng_data,
4334 const int64_t frame_nr,
4335 const double *forces);
4338 * @brief High-level function for adding data to box shape data blocks.
4339 * @param tng_data is the trajectory to use.
4340 * @param frame_nr is the frame number of the data. If frame_nr < 0 the
4341 * data is written as non-trajectory data.
4342 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4343 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4344 * must be initialised before using it.
4345 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4346 * be a NULL pointer.
4347 * @details This function uses tng_util_generic_write() and will
4348 * create a box shape data block if none exists. Box shapes are stored as 9
4349 * values per frame and compressed using TNG compression.
4350 * N.b. Since compressed data is written a whole block at a time the data is not
4351 * actually written to disk until the frame set is finished or the TNG
4352 * trajectory is closed.
4353 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4354 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4357 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write
4358 (const tng_trajectory_t tng_data,
4359 const int64_t frame_nr,
4360 const float *box_shape);
4363 * @brief High-level function for adding data to box shape data blocks at double
4365 * @param tng_data is the trajectory to use.
4366 * @param frame_nr is the frame number of the data. If frame_nr < 0 the
4367 * data is written as non-trajectory data.
4368 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4369 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4370 * must be initialised before using it.
4371 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4372 * be a NULL pointer.
4373 * @details This function uses tng_util_generic_write() and will
4374 * create a box shape data block if none exists. Box shapes are stored as 9
4375 * values per frame and compressed using TNG compression.
4376 * N.b. Since compressed data is written a whole block at a time the data is not
4377 * actually written to disk until the frame set is finished or the TNG
4378 * trajectory is closed.
4379 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4380 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4383 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_double_write
4384 (const tng_trajectory_t tng_data,
4385 const int64_t frame_nr,
4386 const double *box_shape);
4389 * @brief High-level function for writing data of one frame to a data block.
4390 * If the frame is at the beginning of a frame set the time stamp of the frame
4392 * @param tng_data is the trajectory to use.
4393 * @param frame_nr is the frame number of the data.
4394 * @param time is the time stamp of the frame (in seconds).
4395 * @param values is a 1D array of data to add. The array should be of length
4396 * n_particles * n_values_per_frame if writing particle related data, otherwise
4397 * it should be n_values_per_frame.
4398 * @param n_values_per_frame is the number of values to store per frame. If the
4399 * data is particle dependent there will be n_values_per_frame stored per
4400 * particle each frame.
4401 * @param block_id is the ID of the block, of which to set the output interval.
4402 * @param block_name is a string that will be used as name of the block. Only
4403 * required if the block did not exist, i.e. a new block is created.
4404 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4405 * data is not related to specific particles (e.g. box shape) or
4406 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4407 * positions). Only required if the block did not exist, i.e. a new block is
4409 * @param compression is the compression routine to use when writing the data.
4410 * Only required if the block did not exist, i.e. a new block is created.
4411 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4412 * must be initialised before using it.
4413 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4414 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4415 * @pre \code values != 0 \endcode The pointer to the values array must not
4416 * be a NULL pointer.
4417 * @details n_values_per_frame, block_name, particle_dependency and
4418 * compression are only used if the data block did not exist before calling
4419 * this function, in which case it is created.
4420 * N.b. Data is written a whole block at a time. The data is not
4421 * actually written to disk until the frame set is finished or the TNG
4422 * trajectory is closed.
4423 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4424 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4427 tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_write
4428 (const tng_trajectory_t tng_data,
4429 const int64_t frame_nr,
4431 const float *values,
4432 const int64_t n_values_per_frame,
4433 const int64_t block_id,
4434 const char *block_name,
4435 const char particle_dependency,
4436 const char compression);
4439 * @brief High-level function for writing data of one frame to a double precision
4440 * data block. If the frame is at the beginning of a frame set the time stamp of
4441 * the frame set is set.
4442 * @param tng_data is the trajectory to use.
4443 * @param frame_nr is the frame number of the data.
4444 * @param time is the time stamp of the frame (in seconds).
4445 * @param values is a 1D array of data to add. The array should be of length
4446 * n_particles * n_values_per_frame if writing particle related data, otherwise
4447 * it should be n_values_per_frame.
4448 * @param n_values_per_frame is the number of values to store per frame. If the
4449 * data is particle dependent there will be n_values_per_frame stored per
4450 * particle each frame.
4451 * @param block_id is the ID of the block, of which to set the output interval.
4452 * @param block_name is a string that will be used as name of the block. Only
4453 * required if the block did not exist, i.e. a new block is created.
4454 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4455 * data is not related to specific particles (e.g. box shape) or
4456 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4457 * positions). Only required if the block did not exist, i.e. a new block is
4459 * @param compression is the compression routine to use when writing the data.
4460 * Only required if the block did not exist, i.e. a new block is created.
4461 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4462 * must be initialised before using it.
4463 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4464 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4465 * @pre \code values != 0 \endcode The pointer to the values array must not
4466 * be a NULL pointer.
4467 * @details n_values_per_frame, block_name, particle_dependency and
4468 * compression are only used if the data block did not exist before calling
4469 * this function, in which case it is created.
4470 * N.b. Data is written a whole block at a time. The data is not
4471 * actually written to disk until the frame set is finished or the TNG
4472 * trajectory is closed.
4473 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4474 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4477 tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_double_write
4478 (const tng_trajectory_t tng_data,
4479 const int64_t frame_nr,
4481 const double *values,
4482 const int64_t n_values_per_frame,
4483 const int64_t block_id,
4484 const char *block_name,
4485 const char particle_dependency,
4486 const char compression);
4489 * @brief High-level function for adding data to positions data blocks. If the
4490 * frame is at the beginning of a frame set the time stamp of the frame set
4492 * @param tng_data is the trajectory to use.
4493 * @param frame_nr is the frame number of the data.
4494 * @param time is the time stamp of the frame (in seconds).
4495 * @param positions is a 1D array of data to add. The array should be of length
4497 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4498 * must be initialised before using it.
4499 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4500 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4501 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4502 * be a NULL pointer.
4503 * @details This function uses tng_util_generic_with_time_write() and will
4504 * create a positions data block if none exists. Positions are stored as three
4505 * values per frame and compressed using TNG compression.
4506 * N.b. Since compressed data is written a whole block at a time the data is not
4507 * actually written to disk until the frame set is finished or the TNG
4508 * trajectory is closed.
4509 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4510 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4513 tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_write
4514 (const tng_trajectory_t tng_data,
4515 const int64_t frame_nr,
4517 const float *positions);
4520 * @brief High-level function for adding data to positions data blocks at double
4521 * precision. If the frame is at the beginning of a frame set the time stamp of
4522 * the frame set is set.
4523 * @param tng_data is the trajectory to use.
4524 * @param frame_nr is the frame number of the data.
4525 * @param time is the time stamp of the frame (in seconds).
4526 * @param positions is a 1D array of data to add. The array should be of length
4528 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4529 * must be initialised before using it.
4530 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4531 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4532 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4533 * be a NULL pointer.
4534 * @details This function uses tng_util_generic_with_time_double_write() and will
4535 * create a positions data block if none exists. Positions are stored as three
4536 * values per frame and compressed using TNG compression.
4537 * N.b. Since compressed data is written a whole block at a time the data is not
4538 * actually written to disk until the frame set is finished or the TNG
4539 * trajectory is closed.
4540 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4541 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4544 tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_double_write
4545 (const tng_trajectory_t tng_data,
4546 const int64_t frame_nr,
4548 const double *positions);
4551 * @brief High-level function for adding data to velocities data blocks. If the
4552 * frame is at the beginning of a frame set the time stamp of the frame set
4554 * @param tng_data is the trajectory to use.
4555 * @param frame_nr is the frame number of the data.
4556 * @param time is the time stamp of the frame (in seconds).
4557 * @param velocities is a 1D array of data to add. The array should be of length
4559 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4560 * must be initialised before using it.
4561 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4562 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4563 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4564 * be a NULL pointer.
4565 * @details This function uses tng_util_generic_with_time_write() and will
4566 * create a velocities data block if none exists. Velocities are stored as three
4567 * values per frame and compressed using TNG compression.
4568 * N.b. Since compressed data is written a whole block at a time the data is not
4569 * actually written to disk until the frame set is finished or the TNG
4570 * trajectory is closed.
4571 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4572 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4575 tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_write
4576 (const tng_trajectory_t tng_data,
4577 const int64_t frame_nr,
4579 const float *velocities);
4582 * @brief High-level function for adding data to velocities data blocks at
4583 * double precision. If the frame is at the beginning of a frame set the
4584 * time stamp of the frame set is set.
4585 * @param tng_data is the trajectory to use.
4586 * @param frame_nr is the frame number of the data.
4587 * @param time is the time stamp of the frame (in seconds).
4588 * @param velocities is a 1D array of data to add. The array should be of length
4590 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4591 * must be initialised before using it.
4592 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4593 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4594 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4595 * be a NULL pointer.
4596 * @details This function uses tng_util_generic_with_time_double_write() and will
4597 * create a velocities data block if none exists. Velocities are stored as three
4598 * values per frame and compressed using TNG compression.
4599 * N.b. Since compressed data is written a whole block at a time the data is not
4600 * actually written to disk until the frame set is finished or the TNG
4601 * trajectory is closed.
4602 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4603 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4606 tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_double_write
4607 (const tng_trajectory_t tng_data,
4608 const int64_t frame_nr,
4610 const double *velocities);
4613 * @brief High-level function for adding data to forces data blocks. If the
4614 * frame is at the beginning of a frame set the time stamp of the frame set
4616 * @param tng_data is the trajectory to use.
4617 * @param frame_nr is the frame number of the data.
4618 * @param time is the time stamp of the frame (in seconds).
4619 * @param forces is a 1D array of data to add. The array should be of length
4621 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4622 * must be initialised before using it.
4623 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4624 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4625 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4626 * be a NULL pointer.
4627 * @details This function uses tng_util_generic_with_time_write() and will
4628 * create a forces data block if none exists. Forces are stored as three
4629 * values per frame and compressed using gzip compression.
4630 * N.b. Since compressed data is written a whole block at a time the data is not
4631 * actually written to disk until the frame set is finished or the TNG
4632 * trajectory is closed.
4633 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4634 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4637 tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_write
4638 (const tng_trajectory_t tng_data,
4639 const int64_t frame_nr,
4641 const float *forces);
4644 * @brief High-level function for adding data to forces data blocks at
4645 * double precision. If the frame is at the beginning of a frame set
4646 * the time stamp of the frame set is set.
4647 * @param tng_data is the trajectory to use.
4648 * @param frame_nr is the frame number of the data.
4649 * @param time is the time stamp of the frame (in seconds).
4650 * @param forces is a 1D array of data to add. The array should be of length
4652 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4653 * must be initialised before using it.
4654 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4655 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4656 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4657 * be a NULL pointer.
4658 * @details This function uses tng_util_generic_with_time_double_write() and will
4659 * create a forces data block if none exists. Forces are stored as three
4660 * values per frame and compressed using gzip compression.
4661 * N.b. Since compressed data is written a whole block at a time the data is not
4662 * actually written to disk until the frame set is finished or the TNG
4663 * trajectory is closed.
4664 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4665 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4668 tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_double_write
4669 (const tng_trajectory_t tng_data,
4670 const int64_t frame_nr,
4672 const double *forces);
4675 * @brief High-level function for adding data to box shape data blocks. If the
4676 * frame is at the beginning of a frame set the time stamp of the frame set
4678 * @param tng_data is the trajectory to use.
4679 * @param frame_nr is the frame number of the data.
4680 * @param time is the time stamp of the frame (in seconds).
4681 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4682 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4683 * must be initialised before using it.
4684 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4685 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4686 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4687 * be a NULL pointer.
4688 * @details This function uses tng_util_generic_with_time_write() and will
4689 * create a box shape data block if none exists. Box shapes are stored as 9
4690 * values per frame and compressed using TNG compression.
4691 * N.b. Since compressed data is written a whole block at a time the data is not
4692 * actually written to disk until the frame set is finished or the TNG
4693 * trajectory is closed.
4694 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4695 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4698 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_write
4699 (const tng_trajectory_t tng_data,
4700 const int64_t frame_nr,
4702 const float *box_shape);
4705 * @brief High-level function for adding data to box shape data blocks at
4706 * double precision. If the frame is at the beginning of a frame set the
4707 * time stamp of the frame set is set.
4708 * @param tng_data is the trajectory to use.
4709 * @param frame_nr is the frame number of the data.
4710 * @param time is the time stamp of the frame (in seconds).
4711 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4712 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4713 * must be initialised before using it.
4714 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4715 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4716 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4717 * be a NULL pointer.
4718 * @details This function uses tng_util_generic_with_time_double_write() and will
4719 * create a box shape data block if none exists. Box shapes are stored as 9
4720 * values per frame and compressed using TNG compression.
4721 * N.b. Since compressed data is written a whole block at a time the data is not
4722 * actually written to disk until the frame set is finished or the TNG
4723 * trajectory is closed.
4724 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4725 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4728 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_double_write
4729 (const tng_trajectory_t tng_data,
4730 const int64_t frame_nr,
4732 const double *box_shape);
4735 * @brief High-level function for getting the compression method and
4736 * multiplication factor of the last read frame of a specific data block.
4737 * @param tng_data is the trajectory to use.
4738 * @param block_id is the ID number of the block containing the data of
4740 * @param codec_id will be set to the value of the codec_id of the
4741 * compression of the data block. See tng_compression for more details.
4742 * @param factor will be set to the multiplication factor applied to
4743 * the values before compression, in order to get integers from them.
4744 * factor is 1/precision.
4745 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4746 * must be initialised before using it.
4747 * @pre \code codec_id != 0 \endcode The pointer to the returned codec id
4748 * must not be a NULL pointer.
4749 * @pre \code factor != 0 \endcode The pointer to the returned multiplication
4750 * factor must not be a NULL pointer.
4751 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4752 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4755 tng_function_status DECLSPECDLLEXPORT tng_util_frame_current_compression_get
4756 (const tng_trajectory_t tng_data,
4757 const int64_t block_id,
4761 /** @brief High-level function for determining the next frame with data and what
4762 * data blocks have data for that frame. The search can be limited to certain
4764 * @param tng_data is the trajectory to use.
4765 * @param current_frame is the frame that was last read, from where to start
4767 * @param n_requested_data_block_ids is the number of data blocks listed in
4768 * requested_data_block_ids. If this is 0 all data blocks will be taken into
4770 * @param requested_data_block_ids is an array of data blocks to look for.
4771 * @param next_frame will be set to the next frame with data.
4772 * @param n_data_blocks_in_next_frame is set to the number of data blocks with
4773 * data for next_frame.
4774 * @param data_block_ids_in_next_frame is set to an array (of length
4775 * n_data_blocks_in_next_frame) that lists the data block IDs with data for
4776 * next_frame. It must be pointing at NULL or previously allocated memory.
4777 * Memory for the array is allocated by this function.
4778 * The memory must be freed by the client afterwards or
4779 * there will be a memory leak.
4780 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4781 * must be initialised before using it.
4782 * @pre \code next_frame != 0 \endcode The pointer to the next frame must not
4784 * @pre \code n_data_blocks_in_next_frame != 0 \endcode The pointer to
4785 * n_data_blocks_in_next_frame must not be NULL.
4786 * @pre \code *data_block_ids_in_next_frame != 0 \endcode The pointer to the
4787 * list of data block IDs must not be NULL.
4788 * @pre \code n_requested_data_block_ids == 0 || requested_data_block_ids != 0 \endcode
4789 * If the number of requested data blocks != 0 then the array of data block IDs must not be NULL.
4790 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4791 * has occured or TNG_CRITICAL (2) if a major error
4794 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_next_frame_present_data_blocks_find
4795 (const tng_trajectory_t tng_data,
4796 int64_t current_frame,
4797 const int64_t n_requested_data_block_ids,
4798 const int64_t *requested_data_block_ids,
4799 int64_t *next_frame,
4800 int64_t *n_data_blocks_in_next_frame,
4801 int64_t **data_block_ids_in_next_frame);
4803 /* @brief High-level function for getting all data block ids and their names
4804 * and stride lengths.
4805 * @param tng_data is the trajectory to use.
4806 * @param n_data_blocks is set to the number of data blocks in the trajectory.
4807 * @param data_block_ids is set to an array (of length
4808 * n_data_blocks) that lists the data block IDs in the trajectory.
4809 * It must be pointing at NULL or previously allocated memory.
4810 * Memory for the array is allocated by this function.
4811 * The memory must be freed by the client afterwards or
4812 * there will be a memory leak.
4813 * @param data_block_names is set to an array (of length
4814 * n_data_blocks) that contains the names of the data blocks.
4815 * It must be pointing at NULL or previously allocated memory.
4816 * Memory for the array is allocated by this function.
4817 * The memory must be freed by the client afterwards or
4818 * there will be a memory leak.
4819 * @param stride_lengths is set to an array (of length
4820 * n_data_blocks) that lists the stride lengths of the data blocks.
4821 * It must be pointing at NULL or previously allocated memory.
4822 * Memory for the array is allocated by this function.
4823 * The memory must be freed by the client afterwards or
4824 * there will be a memory leak.
4825 * @param n_values_per_frame is set to an array (of length
4826 * n_data_blocks) that lists the number of values per frame of the data blocks.
4827 * It must be pointing at NULL or previously allocated memory.
4828 * Memory for the array is allocated by this function.
4829 * The memory must be freed by the client afterwards or
4830 * there will be a memory leak.
4831 * @param block_types is set to an array (of length
4832 * n_data_blocks) that lists the block types of the data blocks.
4833 * It must be pointing at NULL or previously allocated memory.
4834 * Memory for the array is allocated by this function.
4835 * The memory must be freed by the client afterwards or
4836 * there will be a memory leak.
4837 * @param dependencies is set to an array (of length
4838 * n_data_blocks) that lists the dependencies of the data blocks.
4839 * It must be pointing at NULL or previously allocated memory.
4840 * Memory for the array is allocated by this function.
4841 * The memory must be freed by the client afterwards or
4842 * there will be a memory leak.
4843 * @param compressions is set to an array (of length
4844 * n_data_blocks) that lists the compressions of the data blocks.
4845 * It must be pointing at NULL or previously allocated memory.
4846 * Memory for the array is allocated by this function.
4847 * The memory must be freed by the client afterwards or
4848 * there will be a memory leak.
4849 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4850 * must be initialised before using it.
4851 * @pre \code n_data_blocks != 0 \endcode The pointer to
4852 * n_data_blocks must not be NULL.
4853 * @pre \code data_block_ids != 0 \endcode The pointer to the
4854 * list of data block IDs must not be NULL.
4855 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4856 * has occured or TNG_CRITICAL (2) if a major error
4860 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_all_data_block_types_get
4861 (const tng_trajectory_t tng_data,
4862 int64_t *n_data_blocks,
4863 int64_t **data_block_ids,
4864 char ***data_block_names,
4865 int64_t **stride_lengths,
4866 int64_t **n_values_per_frame,
4868 char **dependencies,
4869 char **compressions);
4872 /** @brief Finds the frame set of the specified frame in order to prepare for writing
4874 * @param tng_data is the trajectory to use.
4875 * @param prev_frame is the frame after which to start appending.
4876 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4877 * must be initialised before using it.
4878 * @pre \code prev_frame >= 0 \endcode The previous frame must not be negative.
4879 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4880 * has occured (such as not finding the requested frame) or TNG_CRITICAL (2)
4881 * if a major error has occured.
4883 tng_function_status DECLSPECDLLEXPORT tng_util_prepare_append_after_frame
4884 (const tng_trajectory_t tng_data,
4885 const int64_t prev_frame);
4888 /** @brief Get the number of frames containing data of a specific type.
4889 * @param tng_data is the trajectory to use.
4890 * @param block_id is the id of the block of the data type.
4891 * @param n_frames is set to the number of frames containing data of
4892 * the requested data type.
4893 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
4894 * error has occured.
4896 tng_function_status DECLSPECDLLEXPORT tng_util_num_frames_with_data_of_block_id_get
4897 (const tng_trajectory_t tng_data,
4898 const int64_t block_id,
4900 /** @} */ /* end of group2 */
4904 } /* end extern "C" */
4907 #endif /* TNG_IO_H */