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.6 - Fourth stable release of the API.
81 * - Removed OpenMP option when building.
82 * - Functionality for migrating data blocks.
83 * - Improved handling of molecules.
84 * - Improved installation of TNG documentation.
85 * - Enhancements to CMake usage.
86 * - Required CMake version raised to 2.8.8.
89 * v. 1.5 - Third stable release of the API.
91 * - Fortran wrapper split into separate file
92 * - Added more block IDs.
93 * - Some new functions and utility functions added.
94 * - Improved compression precision settings.
96 * - Make appending to file work better.
97 * - Modified CMake settings
100 * v. 1.4 - Changed from LGPL to the Revised BSD License.
102 * - More flexible support for digital signatures in header.
103 * - Block ID numbers changed.
105 * v. 1.3 - Second stable release of the API.
107 * - Added multiplication factor for coordinate units to general info.
108 * - Added time stamps and time per frame in frame sets.
109 * - High-level API functions added (not for managing molecules yet)
110 * - Added functions for reading data blocks into 1D arrays.
111 * - TNG compression added.
112 * - C++ interface added.
113 * - Avoid memory allocation if no data is submitted when adding data
115 * - Added function tng_num_frames_per_frame_set_set
116 * - Added data block IDs for charges, b-factors and occupancy.
117 * - GZIP compression added.
118 * - Fixed bug when updating MD5 hashes of data blocks.
119 * - Fixed bug in chain_name_of_particle_get(...)
120 * - Update frame set pointers properly.
121 * - Moved fortran wrapper from header file to source file.
122 * - Write sparse data in mdrun examples.
123 * - Fixed bugs related to reading and writing sparse data.
124 * - Fixed memory leak for non-trajectory particle data blocks.
125 * - Fixed bug when writing data blocks.
126 * - Fixed wrong values in dependency constants
127 * - Write box shape, partial charges and annotation data in tng_testing
128 * - Bug fixes in tng_testing (frame sets not written before)
130 * v. 1.0 - First stable release of the API.
133 * @section examples_sec Examples
135 * There are some examples of how to use the library located in src/tests/
137 * @subsection tng_subsec TNG files
139 * The build directory contains an example_files directory, which in turn
140 * contains a very short example of a TNG file containing a few water molecules,
141 * a box shape description and positions in 10 frames.
143 * It is also possible to run the bin/examples/md_openmp_util
144 * (see src/tests/md_openmp_util.c)
145 * testing program, which will save MD simulations output to a new file
146 * (saved in the example_files directory).
148 * These files can be read using the bin/examples/tng_io_read_pos_util
151 * @subsection c_subsec C
153 * Example writing data to a TNG file (just an excerpt):
155 * for ( step = 1; step < step_num; step++ )
157 * compute ( np, nd, pos, vel, mass, force, &potential, &kinetic );
159 * if(step % step_save == 0)
161 * // Write positions, velocities and forces
162 * if(tng_util_pos_write(traj, step, pos) != TNG_SUCCESS)
164 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
167 * if(tng_util_vel_write(traj, step, vel) != TNG_SUCCESS)
169 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
172 * if(tng_util_force_write(traj, step, force) != TNG_SUCCESS)
174 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
178 * update ( np, nd, pos, vel, force, acc, mass, dt );
182 * Example reading positions from a TNG file:
184 * #include <stdlib.h>
186 * #include "tng/tng_io.h"
188 * int main(int argc, char **argv)
190 * tng_trajectory_t traj;
191 * // Assume that the data is stored as floats. The data is placed in 1-D
193 * float *positions = 0, *box_shape = 0;
194 * int64_t n_particles, n_frames, tot_n_frames, stride_length, i, j;
195 * // Set a default frame range
196 * int64_t first_frame = 0, last_frame = 5000;
199 * // A reference must be passed to allocate memory
200 * tng_util_trajectory_open(argv[1], 'r', &traj);
202 * if(tng_num_frames_get(traj, &tot_n_frames) != TNG_SUCCESS)
204 * printf("Cannot determine the number of frames in the file\n");
205 * tng_util_trajectory_close(&traj);
209 * if(tng_num_particles_get(traj, &n_particles) != TNG_SUCCESS)
211 * printf("Cannot determine the number of particles in the file\n");
212 * tng_util_trajectory_close(&traj);
216 * printf("%"PRId64" frames in file\n", tot_n_frames);
218 * if(last_frame > tot_n_frames - 1)
220 * last_frame = tot_n_frames - 1;
223 * if(tng_util_box_shape_read(traj, &box_shape, &stride_length) ==
226 * printf("Simulation box shape: ");
227 * for(i=0; i < 9; i++)
229 * printf("%f ", box_shape[i]);
235 * printf("Simulation box shape not set in the file (or could not be read)\n");
238 * n_frames = last_frame - first_frame + 1;
241 * // Get the positions of all particles in the requested frame range.
242 * // The positions are stored in the positions array.
243 * // N.B. No proper error checks.
244 * if(tng_util_pos_read_range(traj, 0, last_frame, &positions, &stride_length)
247 * // Print the positions of the wanted particle (zero based)
248 * for(i=0; i < n_frames; i += stride_length)
250 * printf("\nFrame %"PRId64":\n", first_frame + i);
251 * for(j=0; j < n_particles; j++)
253 * printf("Atom nr: %"PRId64"", j);
254 * for(k=0; k < 3; k++)
256 * printf("\t%f", positions[i/stride_length*n_particles*
265 * printf("Cannot read positions\n");
273 * tng_util_trajectory_close(&traj);
280 * @subsection fortran_subsec Fortran
282 * The TNG library can be used from Fortran. It requires cray pointers, which
283 * are not part of the Fortran 77 standard, but available in most compilers.
285 * To compile the fortran example -DTNG_BUILD_FORTRAN=ON needs to be specified when
297 #include "tng_io_fwd.h"
299 #ifdef USE_STD_INTTYPES_H
300 #include <inttypes.h>
302 /* Visual Studio does not contain inttypes.h and stdint.h. Some defines and
303 * typedefs are used from the GNU C Library */
306 typedef __int32 int32_t;
307 typedef unsigned __int32 uint32_t;
308 typedef __int64 int64_t;
309 typedef unsigned __int64 uint64_t;
313 #endif /* _MSC_VER */
315 /* This is from inttypes.h (GNU C Library) */
316 /* The ISO C99 standard specifies that these macros must only be
317 defined if explicitly requested. */
318 #if !defined __cplusplus || defined __STDC_FORMAT_MACROS
320 # if __WORDSIZE == 64
321 # define __PRI64_PREFIX "l"
322 # define __PRIPTR_PREFIX "l"
324 # define __PRI64_PREFIX "ll"
325 # define __PRIPTR_PREFIX
328 /* From stdint.h (GNU C Library) */
329 /* Macros for printing format specifiers. */
330 /* Decimal notation. */
332 # define PRId64 __PRI64_PREFIX "d"
335 # define PRIu64 __PRI64_PREFIX "u"
340 #endif /* USE_STD_INTTYPES_H */
343 #if defined(WIN32) || defined(_WIN32) || defined(WIN64) || defined(_WIN64)
345 #endif /* win32... */
346 #endif /* not defined USE_WINDOWS */
349 #define TNG_PRIsize "Iu"
351 #define TNG_PRIsize "zu"
354 #ifndef DECLSPECDLLEXPORT
356 #define DECLSPECDLLEXPORT __declspec(dllexport)
357 #else /* USE_WINDOWS */
358 #define DECLSPECDLLEXPORT
359 #endif /* USE_WINDOWS */
360 #endif /* DECLSPECDLLEXPORT */
362 /** Flag to indicate frame dependent data. */
363 #define TNG_FRAME_DEPENDENT 1
364 /** Flag to indicate particle dependent data. */
365 #define TNG_PARTICLE_DEPENDENT 2
367 /** The maximum length of a date string */
368 #define TNG_MAX_DATE_STR_LEN 24
369 /** The length of an MD5 hash */
370 #define TNG_MD5_HASH_LEN 16
371 /** The maximum allowed length of a string */
372 #define TNG_MAX_STR_LEN 1024
375 #define TNG_ASSERT(cnd, msg) if(!(cnd)) {printf("%s\n", msg); assert(cnd);}
377 #define TNG_ASSERT(cnd, msg) (void)0;
380 /** Flag to specify the endianness of a TNG file */
381 typedef enum {TNG_BIG_ENDIAN,
382 TNG_LITTLE_ENDIAN} tng_file_endianness;
384 /** Flag to specify the endianness of 32 bit values of the current architecture. */
385 typedef enum {TNG_BIG_ENDIAN_32,
386 TNG_LITTLE_ENDIAN_32,
387 TNG_BYTE_PAIR_SWAP_32} tng_endianness_32;
389 /** Flag to specify the endianness of 64 bit values of the current architecture. */
390 typedef enum {TNG_BIG_ENDIAN_64,
391 TNG_LITTLE_ENDIAN_64,
393 TNG_BYTE_PAIR_SWAP_64,
394 TNG_BYTE_SWAP_64} tng_endianness_64;
396 /** Compression mode is specified in each data block */
397 typedef enum {TNG_UNCOMPRESSED,
400 TNG_GZIP_COMPRESSION} tng_compression;
403 typedef enum {TNG_NO_HASH,
405 TNG_SHA256} tng_hash_type;
407 /** Non trajectory blocks come before the first frame set block */
408 typedef enum {TNG_NON_TRAJECTORY_BLOCK, TNG_TRAJECTORY_BLOCK} tng_block_type;
410 /** @defgroup def1 Standard non-trajectory blocks
411 * Block IDs of standard non-trajectory blocks.
414 #define TNG_GENERAL_INFO 0x0000000000000000LL
415 #define TNG_MOLECULES 0x0000000000000001LL
416 #define TNG_TRAJECTORY_FRAME_SET 0x0000000000000002LL
417 #define TNG_PARTICLE_MAPPING 0x0000000000000003LL
420 /** @defgroup def2 Standard trajectory blocks
421 * Block IDs of standard trajectory blocks. Box shape and partial charges can
422 * be either trajectory blocks or non-trajectory blocks
425 #define TNG_TRAJ_BOX_SHAPE 0x0000000010000000LL
426 #define TNG_TRAJ_POSITIONS 0x0000000010000001LL
427 #define TNG_TRAJ_VELOCITIES 0x0000000010000002LL
428 #define TNG_TRAJ_FORCES 0x0000000010000003LL
429 #define TNG_TRAJ_PARTIAL_CHARGES 0x0000000010000004LL
430 #define TNG_TRAJ_FORMAL_CHARGES 0x0000000010000005LL
431 #define TNG_TRAJ_B_FACTORS 0x0000000010000006LL
432 #define TNG_TRAJ_ANISOTROPIC_B_FACTORS 0x0000000010000007LL
433 #define TNG_TRAJ_OCCUPANCY 0x0000000010000008LL
434 #define TNG_TRAJ_GENERAL_COMMENTS 0x0000000010000009LL
438 /** @defgroup def3 GROMACS data block IDs
439 * Block IDs of data blocks specific to GROMACS.
442 #define TNG_GMX_LAMBDA 0x1000000010000000LL
443 #define TNG_GMX_ENERGY_ANGLE 0x1000000010000001LL
444 #define TNG_GMX_ENERGY_RYCKAERT_BELL 0x1000000010000002LL
445 #define TNG_GMX_ENERGY_LJ_14 0x1000000010000003LL
446 #define TNG_GMX_ENERGY_COULOMB_14 0x1000000010000004LL
447 #define TNG_GMX_ENERGY_LJ_(SR) 0x1000000010000005LL
448 #define TNG_GMX_ENERGY_COULOMB_(SR) 0x1000000010000006LL
449 #define TNG_GMX_ENERGY_COUL_RECIP 0x1000000010000007LL
450 #define TNG_GMX_ENERGY_POTENTIAL 0x1000000010000008LL
451 #define TNG_GMX_ENERGY_KINETIC_EN 0x1000000010000009LL
452 #define TNG_GMX_ENERGY_TOTAL_ENERGY 0x1000000010000010LL
453 #define TNG_GMX_ENERGY_TEMPERATURE 0x1000000010000011LL
454 #define TNG_GMX_ENERGY_PRESSURE 0x1000000010000012LL
455 #define TNG_GMX_ENERGY_CONSTR_RMSD 0x1000000010000013LL
456 #define TNG_GMX_ENERGY_BOX_X 0x1000000010000014LL
457 #define TNG_GMX_ENERGY_BOX_Y 0x1000000010000015LL
458 #define TNG_GMX_ENERGY_BOX_Z 0x1000000010000016LL
459 #define TNG_GMX_ENERGY_VOLUME 0x1000000010000017LL
460 #define TNG_GMX_ENERGY_DENSITY 0x1000000010000018LL
461 #define TNG_GMX_ENERGY_PV 0x1000000010000019LL
462 #define TNG_GMX_ENERGY_ENTHALPY 0x1000000010000020LL
463 #define TNG_GMX_ENERGY_VIR_XX 0x1000000010000021LL
464 #define TNG_GMX_ENERGY_VIR_XY 0x1000000010000022LL
465 #define TNG_GMX_ENERGY_VIR_XZ 0x1000000010000023LL
466 #define TNG_GMX_ENERGY_VIR_YX 0x1000000010000024LL
467 #define TNG_GMX_ENERGY_VIR_YY 0x1000000010000025LL
468 #define TNG_GMX_ENERGY_VIR_YZ 0x1000000010000026LL
469 #define TNG_GMX_ENERGY_VIR_ZX 0x1000000010000027LL
470 #define TNG_GMX_ENERGY_VIR_ZY 0x1000000010000028LL
471 #define TNG_GMX_ENERGY_VIR_ZZ 0x1000000010000029LL
472 #define TNG_GMX_ENERGY_PRES_XX 0x1000000010000030LL
473 #define TNG_GMX_ENERGY_PRES_XY 0x1000000010000031LL
474 #define TNG_GMX_ENERGY_PRES_XZ 0x1000000010000032LL
475 #define TNG_GMX_ENERGY_PRES_YX 0x1000000010000033LL
476 #define TNG_GMX_ENERGY_PRES_YY 0x1000000010000034LL
477 #define TNG_GMX_ENERGY_PRES_YZ 0x1000000010000035LL
478 #define TNG_GMX_ENERGY_PRES_ZX 0x1000000010000036LL
479 #define TNG_GMX_ENERGY_PRES_ZY 0x1000000010000037LL
480 #define TNG_GMX_ENERGY_PRES_ZZ 0x1000000010000038LL
481 #define TNG_GMX_ENERGY_SURFXSURFTEN 0x1000000010000039LL
482 #define TNG_GMX_ENERGY_T_SYSTEM 0x1000000010000040LL
483 #define TNG_GMX_ENERGY_LAMB_SYSTEM 0x1000000010000041LL
484 #define TNG_GMX_SELECTION_GROUP_NAMES 0x1000000010000042LL
485 #define TNG_GMX_ATOM_SELECTION_GROUP 0x1000000010000043LL
488 /** Flag to specify if a data block contains data related to particles or not.*/
489 typedef enum {TNG_NON_PARTICLE_BLOCK_DATA,
490 TNG_PARTICLE_BLOCK_DATA} tng_particle_dependency;
493 typedef enum {TNG_FALSE, TNG_TRUE} tng_bool;
495 /** Flag to specify if the number of atoms change throughout the trajectory or
496 * if it is constant. */
497 typedef enum {TNG_CONSTANT_N_ATOMS, TNG_VARIABLE_N_ATOMS}
498 tng_variable_n_atoms_flag;
500 /** Return values of API functions. TNG_SUCCESS means that the operation
501 * was successful. TNG_FAILURE means that the operation failed for some
502 * reason, but it is possible to try to continue anyhow. TNG_CRITICAL
503 * means that the error is irrecoverable. */
504 typedef enum {TNG_SUCCESS, TNG_FAILURE, TNG_CRITICAL} tng_function_status;
506 /** If tng_hash_mode == TNG_USE_HASH md5 hashes will be written to output files
507 * and when reading a file the md5 hashes of the contents will be compared to
508 * those in the file (for each block) in order to ensure data integrity */
509 typedef enum {TNG_SKIP_HASH, TNG_USE_HASH} tng_hash_mode;
511 /** Possible formats of data block contents */
512 typedef enum {TNG_CHAR_DATA,
515 TNG_DOUBLE_DATA} tng_data_type;
518 struct tng_trajectory;
524 struct tng_gen_block;
525 struct tng_particle_mapping;
526 struct tng_trajectory_frame_set;
527 struct tng_particle_data;
528 struct tng_non_particle_data;
530 /** Data can be either double, float, int or a string */
544 /** @defgroup group1 Low-level API
545 * These functions give detailed control of the TNG data management. Most
546 * things can be done using the more convenient high-level API functions
552 * @brief Get the major version of the TNG library.
553 * @param tng_data is a trajectory data container, it does not have
554 * to be initialized beforehand.
555 * @param version is pointing to a value set to the major version of
557 * @return TNG_SUCCESS (0) if successful.
559 tng_function_status DECLSPECDLLEXPORT tng_version_major
560 (const tng_trajectory_t tng_data,
564 * @brief Get the minor version of the TNG library.
565 * @param tng_data is a trajectory data container, it does not have
566 * to be initialized beforehand.
567 * @param version is pointing to a value set to the minor version of
569 * @return TNG_SUCCESS (0) if successful.
571 tng_function_status DECLSPECDLLEXPORT tng_version_minor
572 (const tng_trajectory_t tng_data,
576 * @brief Get the patch level of the TNG library.
577 * @param tng_data is a trajectory data container, it does not have
578 * to be initialized beforehand.
579 * @param patch_level is the string to fill with the full version,
580 * memory must be allocated before.
581 * @return TNG_SUCCESS (0) if successful.
583 tng_function_status DECLSPECDLLEXPORT tng_version_patchlevel
584 (const tng_trajectory_t tng_data,
588 * @brief Get the full version string of the TNG library.
589 * @param tng_data is a trajectory data container, it does not have
590 * to be initialized beforehand.
591 * @param version is pointing to a value set to the major version of
593 * @param max_len maximum char length of the string, i.e. how much memory has
594 * been reserved for version. This includes \0 terminating character.
595 * @pre \code version != 0 \endcode The pointer to the name string
596 * must not be a NULL pointer.
597 * @return TNG_SUCCESS (0) if successful.
599 tng_function_status DECLSPECDLLEXPORT tng_version
600 (const tng_trajectory_t tng_data,
605 * @brief Setup a trajectory data container.
606 * @param tng_data_p a pointer to memory to initialise as a trajectory.
607 * @pre tng_data_p must not be pointing at a reserved memory block.
608 * @details Memory is allocated during initialisation.
609 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
612 tng_function_status DECLSPECDLLEXPORT tng_trajectory_init
613 (tng_trajectory_t *tng_data_p);
616 * @brief Clean up a trajectory data container.
617 * @param tng_data_p a pointer to the trajectory data to destroy.
618 * @details All allocated memory in the data structure is freed, as well as
620 * @return TNG_SUCCESS (0) if successful.
622 tng_function_status DECLSPECDLLEXPORT tng_trajectory_destroy
623 (tng_trajectory_t *tng_data_p);
626 * @brief Copy a trajectory data container (dest is setup as well).
627 * @details This initialises dest and copies only what is absolute necessary for
628 * parallel i/o. This can be used inside pragma omp for setting up a thread
629 * local copy of src. It can be freed (using tng_trajectory_destroy) at the
630 * end of the parallel block.
631 * @param src the original trajectory.
632 * @param dest_p a pointer to memory to initialise as a trajectory.
633 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
634 * must be initialised before using it.
635 * @pre tng_data_p must not be pointing at a reserved memory block.
636 * @details Memory is allocated during initialisation.
637 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
640 tng_function_status DECLSPECDLLEXPORT tng_trajectory_init_from_src
641 (tng_trajectory_t src, tng_trajectory_t *dest_p);
644 * @brief Get the name of the input file.
645 * @param tng_data the trajectory of which to get the input file name.
646 * @param file_name the string to fill with the name of the input file,
647 * memory must be allocated before.
648 * @param max_len maximum char length of the string, i.e. how much memory has
649 * been reserved for file_name. This includes \0 terminating character.
650 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
651 * must be initialised before using it.
652 * @pre \code file_name != 0 \endcode The pointer to the file name string
653 * must not be a NULL pointer.
654 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
655 * has occurred (source string longer than destination string).
657 tng_function_status DECLSPECDLLEXPORT tng_input_file_get
658 (const tng_trajectory_t tng_data,
659 char *file_name, const int max_len);
662 * @brief Set the name of the input file.
663 * @param tng_data the trajectory of which to set the input file name.
664 * @param file_name the name of the input file.
665 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
666 * must be initialised before using it.
667 * @pre \code file_name != 0 \endcode The pointer to the file name string
668 * must not be a NULL pointer.
669 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
672 tng_function_status DECLSPECDLLEXPORT tng_input_file_set
673 (tng_trajectory_t tng_data,
674 const char *file_name);
677 * @brief Get the name of the output file.
678 * @param tng_data the trajectory of which to get the input file name.
679 * @param file_name the string to fill with the name of the output file,
680 * memory must be allocated before.
681 * @param max_len maximum char length of the string, i.e. how much memory has
682 * been reserved for file_name. This includes \0 terminating character.
683 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
684 * must be initialised before using it.
685 * @pre \code file_name != 0 \endcode The pointer to the file name string
686 * must not be a NULL pointer.
687 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
688 * has occurred (source string longer than destination string).
690 tng_function_status DECLSPECDLLEXPORT tng_output_file_get
691 (const tng_trajectory_t tng_data,
692 char *file_name, const int max_len);
695 * @brief Set the name of the output file.
696 * @param tng_data the trajectory of which to set the output file name.
697 * @param file_name the name of the output file.
698 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
699 * must be initialised before using it.
700 * @pre \code file_name != 0 \endcode The pointer to the file name string
701 * must not be a NULL pointer.
702 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
705 tng_function_status DECLSPECDLLEXPORT tng_output_file_set
706 (tng_trajectory_t tng_data,
707 const char *file_name);
710 * @brief Set the name of the output file for appending. The output file
711 * will not be overwritten.
712 * @param tng_data the trajectory of which to set the output file name.
713 * @param file_name the name of the output file to append to.
714 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
715 * must be initialised before using it.
716 * @pre \code file_name != 0 \endcode The pointer to the file name string
717 * must not be a NULL pointer.
718 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
721 tng_function_status DECLSPECDLLEXPORT tng_output_append_file_set
722 (tng_trajectory_t tng_data,
723 const char *file_name);
726 * @brief Get the endianness of the output file.
727 * @param tng_data the trajectory of which to get the endianness of the current
729 * @param endianness will contain the enumeration of the endianness.
730 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
731 * must be initialised before using it.
732 * @pre \code endianness != 0 \endcode The pointer to the endianness container
733 * must not be a NULL pointer.
734 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness
735 * could not be retrieved.
737 tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_get
738 (const tng_trajectory_t tng_data, tng_file_endianness *endianness);
741 * @brief Set the endianness of the output file.
742 * @param tng_data the trajectory of which to set the endianness of the current
744 * @param endianness the enumeration of the endianness, can be either
745 * TNG_BIG_ENDIAN (0) or TNG_LITTLE_ENDIAN (1).
746 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
747 * must be initialised before using it.
748 * @details The endianness cannot be changed after file output has started.
749 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness
752 tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_set
753 (tng_trajectory_t tng_data,
754 const tng_file_endianness endianness);
757 * @brief Get the name of the program used when creating the trajectory.
758 * @param tng_data the trajectory of which to get the program name.
759 * @param name the string to fill with the name of the program,
760 * memory must be allocated before.
761 * @param max_len maximum char length of the string, i.e. how much memory has
762 * been reserved for name. This includes \0 terminating character.
763 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
764 * must be initialised before using it.
765 * @pre \code name != 0 \endcode The pointer to the name string
766 * must not be a NULL pointer.
767 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
768 * has occurred (source string longer than destination string).
770 tng_function_status DECLSPECDLLEXPORT tng_first_program_name_get
771 (const tng_trajectory_t tng_data,
772 char *name, const int max_len);
775 * @brief Set the name of the program used when creating the trajectory.
776 * @param tng_data the trajectory of which to set the program name.
777 * @param new_name is a string containing the wanted name.
778 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
779 * must be initialised before using it.
780 * @pre \code new_name != 0 \endcode The pointer to the new_name string
781 * must not be a NULL pointer.
782 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
785 tng_function_status DECLSPECDLLEXPORT tng_first_program_name_set
786 (tng_trajectory_t tng_data,
787 const char *new_name);
790 * @brief Get the name of the program used when last modifying the trajectory.
791 * @param tng_data the trajectory of which to get the program name.
792 * @param name the string to fill with the name of the program,
793 * memory must be allocated before.
794 * @param max_len maximum char length of the string, i.e. how much memory has
795 * been reserved for name. This includes \0 terminating character.
796 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
797 * must be initialised before using it.
798 * @pre \code name != 0 \endcode The pointer to the name string
799 * must not be a NULL pointer.
800 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
801 * has occurred (source string longer than destination string).
803 tng_function_status DECLSPECDLLEXPORT tng_last_program_name_get
804 (const tng_trajectory_t tng_data,
805 char *name, const int max_len);
808 * @brief Set the name of the program used when last modifying the trajectory.
809 * @param tng_data the trajectory of which to set the program name.
810 * @param new_name is a string containing the wanted name.
811 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
812 * must be initialised before using it.
813 * @pre \code new_name != 0 \endcode The pointer to the new_name string
814 * must not be a NULL pointer.
815 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
818 tng_function_status DECLSPECDLLEXPORT tng_last_program_name_set
819 (tng_trajectory_t tng_data,
820 const char *new_name);
823 * @brief Get the name of the user who created the trajectory.
824 * @param tng_data the trajectory of which to get the user name.
825 * @param name the string to fill with the name of the user,
826 * memory must be allocated before.
827 * @param max_len maximum char length of the string, i.e. how much memory has
828 * been reserved for name. This includes \0 terminating character.
829 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
830 * must be initialised before using it.
831 * @pre \code name != 0 \endcode The pointer to the name string
832 * must not be a NULL pointer.
833 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
834 * has occurred (source string longer than destination string).
836 tng_function_status DECLSPECDLLEXPORT tng_first_user_name_get
837 (const tng_trajectory_t tng_data,
838 char *name, const int max_len);
841 * @brief Set the name of the user who created the trajectory.
842 * @param tng_data the trajectory of which to set the user name.
843 * @param new_name is a string containing the wanted name.
844 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
845 * must be initialised before using it.
846 * @pre \code new_name != 0 \endcode The pointer to the new_name string
847 * must not be a NULL pointer.
848 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
851 tng_function_status DECLSPECDLLEXPORT tng_first_user_name_set
852 (tng_trajectory_t tng_data,
853 const char *new_name);
856 * @brief Get the name of the user who last modified the trajectory.
857 * @param tng_data the trajectory of which to get the user name.
858 * @param name the string to fill with the name of the user,
859 * memory must be allocated before.
860 * @param max_len maximum char length of the string, i.e. how much memory has
861 * been reserved for name. This includes \0 terminating character.
862 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
863 * must be initialised before using it.
864 * @pre \code name != 0 \endcode The pointer to the name string
865 * must not be a NULL pointer.
866 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
867 * has occurred (source string longer than destination string).
869 tng_function_status DECLSPECDLLEXPORT tng_last_user_name_get
870 (const tng_trajectory_t tng_data,
871 char *name, const int max_len);
874 * @brief Set the name of the user who last modified the trajectory.
875 * @param tng_data the trajectory of which to set the user name.
876 * @param new_name is a string containing the wanted name.
877 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
878 * must be initialised before using it.
879 * @pre \code new_name != 0 \endcode The pointer to the new_name string
880 * must not be a NULL pointer.
881 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
884 tng_function_status DECLSPECDLLEXPORT tng_last_user_name_set
885 (tng_trajectory_t tng_data,
886 const char *new_name);
889 * @brief Get the name of the computer used when creating the trajectory.
890 * @param tng_data the trajectory of which to get the computer name.
891 * @param name the string to fill with the name of the computer,
892 * memory must be allocated before.
893 * @param max_len maximum char length of the string, i.e. how much memory has
894 * been reserved for name. This includes \0 terminating character.
895 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
896 * must be initialised before using it.
897 * @pre \code name != 0 \endcode The pointer to the name string
898 * must not be a NULL pointer.
899 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
900 * has occurred (source string longer than destination string).
902 tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_get
903 (const tng_trajectory_t tng_data,
904 char *name, const int max_len);
907 * @brief Set the name of the computer used when creating the trajectory.
908 * @param tng_data the trajectory of which to set the computer name.
909 * @param new_name is a string containing the wanted name.
910 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
911 * must be initialised before using it.
912 * @pre \code new_name != 0 \endcode The pointer to the new_name string
913 * must not be a NULL pointer.
914 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
917 tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_set
918 (tng_trajectory_t tng_data,
919 const char *new_name);
922 * @brief Get the name of the computer used when last modifying the trajectory.
923 * @param tng_data the trajectory of which to get the computer name.
924 * @param name the string to fill with the name of the computer,
925 * memory must be allocated before.
926 * @param max_len maximum char length of the string, i.e. how much memory has
927 * been reserved for name. This includes \0 terminating character.
928 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
929 * must be initialised before using it.
930 * @pre \code name != 0 \endcode The pointer to the name string
931 * must not be a NULL pointer.
932 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
933 * has occurred (source string longer than destination string).
935 tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_get
936 (const tng_trajectory_t tng_data,
937 char *name, const int max_len);
940 * @brief Set the name of the computer used when last modifying the trajectory.
941 * @param tng_data the trajectory of which to set the computer name.
942 * @param new_name is a string containing the wanted name.
943 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
944 * must be initialised before using it.
945 * @pre \code new_name != 0 \endcode The pointer to the new_name string
946 * must not be a NULL pointer.
947 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
950 tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_set
951 (tng_trajectory_t tng_data,
952 const char *new_name);
955 * @brief Get the pgp_signature of the user creating the trajectory.
956 * @param tng_data the trajectory of which to get the computer name.
957 * @param signature the string to fill with the signature,
958 * memory must be allocated before.
959 * @param max_len maximum char length of the string, i.e. how much memory has
960 * been reserved for name. This includes \0 terminating character.
961 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
962 * must be initialised before using it.
963 * @pre \code signature != 0 \endcode The pointer to the signature
964 * must not be a NULL pointer.
965 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
966 * has occurred (source string longer than destination string).
968 tng_function_status DECLSPECDLLEXPORT tng_first_signature_get
969 (const tng_trajectory_t tng_data,
970 char *signature, const int max_len);
973 * @brief Set the pgp_signature of the user creating the trajectory.
974 * @param tng_data the trajectory of which to set the computer name.
975 * @param signature is a string containing the pgp_signature.
976 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
977 * must be initialised before using it.
978 * @pre \code signature != 0 \endcode The pointer to the signature
979 * must not be a NULL pointer.
980 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
983 tng_function_status DECLSPECDLLEXPORT tng_first_signature_set
984 (tng_trajectory_t tng_data,
985 const char *signature);
988 * @brief Get the pgp_signature of the user last modifying the trajectory.
989 * @param tng_data the trajectory of which to get the computer name.
990 * @param signature the string to fill with the signature,
991 * memory must be allocated before.
992 * @param max_len maximum char length of the string, i.e. how much memory has
993 * been reserved for name. This includes \0 terminating character.
994 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
995 * must be initialised before using it.
996 * @pre \code signature != 0 \endcode The pointer to the signature
997 * must not be a NULL pointer.
998 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
999 * has occurred (source string longer than destination string).
1001 tng_function_status DECLSPECDLLEXPORT tng_last_signature_get
1002 (const tng_trajectory_t tng_data,
1003 char *signature, const int max_len);
1006 * @brief Set the pgp_signature of the user last modifying the trajectory.
1007 * @param tng_data the trajectory of which to set the computer name.
1008 * @param signature is a string containing the pgp_signature.
1009 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1010 * must be initialised before using it.
1011 * @pre \code signature != 0 \endcode The pointer to the signature
1012 * must not be a NULL pointer.
1013 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1014 * error has occured.
1016 tng_function_status DECLSPECDLLEXPORT tng_last_signature_set
1017 (tng_trajectory_t tng_data,
1018 const char *signature);
1021 * @brief Get the name of the forcefield used in the trajectory.
1022 * @param tng_data the trajectory of which to get the forcefield name.
1023 * @param name the string to fill with the name of the forcefield,
1024 * memory must be allocated before.
1025 * @param max_len maximum char length of the string, i.e. how much memory has
1026 * been reserved for name. This includes \0 terminating character.
1027 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1028 * must be initialised before using it.
1029 * @pre \code name != 0 \endcode The pointer to the name string
1030 * must not be a NULL pointer.
1031 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1032 * has occurred (source string longer than destination string).
1034 tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_get
1035 (const tng_trajectory_t tng_data,
1036 char *name, const int max_len);
1039 * @brief Set the name of the forcefield used in the trajectory.
1040 * @param tng_data the trajectory of which to set the forcefield name.
1041 * @param new_name is a string containing the wanted name.
1042 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1043 * must be initialised before using it.
1044 * @pre \code new_name != 0 \endcode The pointer to the new_name string
1045 * must not be a NULL pointer.
1046 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1047 * error has occured.
1049 tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_set
1050 (tng_trajectory_t tng_data,
1051 const char *new_name);
1054 * @brief Get the medium stride length of the trajectory.
1055 * @param tng_data is the trajectory from which to get the stride length.
1056 * @param len is pointing to a value set to the stride length.
1057 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1058 * must be initialised before using it.
1059 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer.
1060 * @return TNG_SUCCESS (0) if successful.
1062 tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_get
1063 (const tng_trajectory_t tng_data,
1067 * @brief Set the medium stride length of the trajectory.
1068 * @param tng_data is the trajectory of which to set the stride length.
1069 * @param len is the wanted medium stride length.
1070 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1071 * must be initialised before using it.
1072 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1075 tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_set
1076 (tng_trajectory_t tng_data,
1080 * @brief Get the long stride length of the trajectory.
1081 * @param tng_data is the trajectory from which to get the stride length.
1082 * @param len is pointing to a value set to the stride length.
1083 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1084 * must be initialised before using it.
1085 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer.
1086 * @return TNG_SUCCESS (0) if successful.
1088 tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_get
1089 (const tng_trajectory_t tng_data,
1093 * @brief Set the long stride length of the trajectory.
1094 * @param tng_data is the trajectory of which to set the stride length.
1095 * @param len is the wanted long stride length.
1096 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1097 * must be initialised before using it.
1098 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1101 tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_set
1102 (tng_trajectory_t tng_data,
1106 * @brief Get the current time per frame of the trajectory.
1107 * @param tng_data is the trajectory from which to get the time per frame.
1108 * @param time is pointing to a value set to the time per frame.
1109 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1110 * must be initialised before using it.
1111 * @pre \code time != 0 \endcode The pointer to time must not be a NULL pointer.
1112 * @return TNG_SUCCESS (0) if successful.
1114 tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_get
1115 (const tng_trajectory_t tng_data,
1119 * @brief Set the time per frame of the trajectory.
1120 * @param tng_data is the trajectory of which to set the time per frame.
1121 * @param time is the new time per frame.
1122 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1123 * must be initialised before using it.
1124 * @pre \code time > 0 \endcode The time per frame must be >= 0.
1125 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1128 tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_set
1129 (tng_trajectory_t tng_data,
1133 * @brief Get the length of the input file.
1134 * @param tng_data is the trajectory from which to get the input file length.
1135 * @param len is pointing to a value set to the file length.
1136 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1137 * must be initialised before using it.
1138 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer.
1139 * @return TNG_SUCCESS (0) if successful.
1141 tng_function_status DECLSPECDLLEXPORT tng_input_file_len_get
1142 (const tng_trajectory_t tng_data,
1146 * @brief Get the number of frames in the trajectory
1147 * @param tng_data is the trajectory of which to get the number of frames.
1148 * @param n is pointing to a value set to the number of frames.
1149 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1150 * must be initialised before using it.
1151 * @pre \code tng_data->input_file != 0 \endcode An input file must be open
1152 * to find the next frame set.
1153 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1154 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1155 * has occurred (could not find last frame set).
1157 tng_function_status DECLSPECDLLEXPORT tng_num_frames_get
1158 (const tng_trajectory_t tng_data,
1162 * @brief Get the precision of lossy compression.
1163 * @param tng_data is the trajectory of which to get the compression precision.
1164 * @param precision will be pointing to the retrieved compression precision.
1165 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1166 * must be initialised before using it.
1167 * @details A compression precision of 0.001 (the default) means that the
1168 * compressed values are accurate to the third decimal. This function does
1169 * not check actual precision of compressed data, but just returns what has
1170 * previously been set using tng_compression_precision_set().
1171 * @return TNG_SUCCESS (0) if successful.
1173 tng_function_status DECLSPECDLLEXPORT tng_compression_precision_get
1174 (const tng_trajectory_t tng_data,
1178 * @brief Set the precision of lossy compression.
1179 * @param tng_data is the trajectory of which to set the compression precision.
1180 * @param precision is the new compression precision.
1181 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1182 * must be initialised before using it.
1183 * @details A compression precision of 0.001 (the default) means that the
1184 * compressed values are accurate to the third decimal.
1185 * @return TNG_SUCCESS (0) if successful.
1187 tng_function_status DECLSPECDLLEXPORT tng_compression_precision_set
1188 (tng_trajectory_t tng_data,
1189 const double precision);
1192 * @brief Set the number of particles, in the case no molecular system is used.
1193 * @param tng_data is the trajectory of which to get the number of particles.
1194 * @param n is the number of particles to use.
1195 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1196 * must be initialised before using it.
1197 * @details When creating a molecular system the number of particles are set
1198 * automatically. This should only be used when there is no molecular system
1199 * specified or if the number of atoms needs to be overridden for some reason.
1200 * @return TNG_SUCCESS (0) if successful.
1202 tng_function_status DECLSPECDLLEXPORT tng_implicit_num_particles_set
1203 (tng_trajectory_t tng_data,
1207 * @brief Get the current number of particles.
1208 * @param tng_data is the trajectory from which to get the number of particles.
1209 * @param n is pointing to a value set to the number of particles.
1210 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1211 * must be initialised before using it.
1212 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1213 * @details If variable number of particles are used this function will return
1214 * the number of particles in the current frame set.
1215 * @return TNG_SUCCESS (0) if successful.
1217 tng_function_status DECLSPECDLLEXPORT tng_num_particles_get
1218 (const tng_trajectory_t tng_data,
1222 * @brief Get if the number of particle can be varied during the simulation.
1223 * @param tng_data is the trajectory from which to get the number of particles.
1224 * @param variable is pointing to a value set to TNG_CONSTANT_N_ATOMS if the
1225 * number of particles cannot change or TNG_VARIABLE_N_ATOMS if the number of
1226 * particles can change.
1227 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1228 * must be initialised before using it.
1229 * @pre \code variable != 0 \endcode The pointer to variable must not be
1231 * @return TNG_SUCCESS (0) if successful.
1233 tng_function_status DECLSPECDLLEXPORT tng_num_particles_variable_get
1234 (const tng_trajectory_t tng_data,
1238 * @brief Get the number of molecule types (length of tng_data->molecules).
1239 * @param tng_data is the trajectory from which to get the number of molecules.
1240 * @param n is pointing to a value set to the number of molecule types.
1241 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1242 * must be initialised before using it.
1243 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1244 * @return TNG_SUCCESS (0) if successful.
1246 tng_function_status DECLSPECDLLEXPORT tng_num_molecule_types_get
1247 (const tng_trajectory_t tng_data,
1251 * @brief Get the current total number of molecules.
1252 * @param tng_data is the trajectory from which to get the number of molecules.
1253 * @param n is pointing to a value set to the number of molecules.
1254 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1255 * must be initialised before using it.
1256 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1257 * @details If variable number of particles are used this function will return
1258 * the total number of molecules in the current frame set.
1259 * @return TNG_SUCCESS (0) if successful.
1261 tng_function_status DECLSPECDLLEXPORT tng_num_molecules_get
1262 (const tng_trajectory_t tng_data,
1265 /** @brief Get the list of the count of each molecule.
1266 * @param tng_data is the trajectory from which to get the molecule count list.
1267 * @param mol_cnt_list is a list of the count of each molecule in the
1268 * mol system. This is a pointer to the list in the TNG container, which
1269 * means that it should be handled carefully, e.g. not freed.
1270 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1271 * must be initialised before using it.
1272 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE(1) if the list of
1273 * molecule counts was not valid.
1275 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_list_get
1276 (const tng_trajectory_t tng_data,
1277 int64_t **mol_cnt_list);
1280 * @brief Get the exponent used for distances in the trajectory.
1281 * @param tng_data is the trajectory from which to get the information.
1282 * @param exp is pointing to a value set to the distance unit exponent.
1283 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1284 * must be initialised before using it.
1285 * @pre \code exp != 0 \endcode The pointer to exp must not be a NULL pointer.
1286 * @details Example: If the distances are specified in nm (default) exp is -9.
1287 * If the distances are specified in Ă
exp is -10.
1288 * @return TNG_SUCCESS (0) if successful.
1290 tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_get
1291 (const tng_trajectory_t tng_data,
1295 * @brief Set the exponent used for distances in the trajectory.
1296 * @param tng_data is the trajectory of which to set the unit exponent.
1297 * @param exp is the distance unit exponent to use.
1298 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1299 * must be initialised before using it.
1300 * @details Example: If the distances are specified in nm (default) exp is -9.
1301 * If the distances are specified in Ă
exp is -10.
1302 * @return TNG_SUCCESS (0) if successful.
1304 tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_set
1305 (const tng_trajectory_t tng_data,
1309 * @brief Get the number of frames per frame set.
1310 * @param tng_data is the trajectory from which to get the number of frames
1312 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1313 * must be initialised before using it.
1314 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1315 * @param n is pointing to a value set to the number of frames per frame set.
1316 * @return TNG_SUCCESS (0) if successful.
1318 tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_get
1319 (const tng_trajectory_t tng_data,
1323 * @brief Set the number of frames per frame set.
1324 * @param tng_data is the trajectory of which to set the number of frames
1326 * @param n is the number of frames per frame set.
1327 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1328 * must be initialised before using it.
1329 * @details This does not affect already existing frame sets. For
1330 * consistency the number of frames per frame set should be set
1331 * betfore creating any frame sets.
1332 * @return TNG_SUCCESS (0) if successful.
1334 tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_set
1335 (const tng_trajectory_t tng_data,
1339 * @brief Get the number of frame sets.
1340 * @details This updates tng_data->n_trajectory_frame_sets before returning it.
1341 * @param tng_data is the trajectory from which to get the number of frame sets.
1342 * @param n is pointing to a value set to the number of frame sets.
1343 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1344 * must be initialised before using it.
1345 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1346 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1347 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1349 tng_function_status DECLSPECDLLEXPORT tng_num_frame_sets_get
1350 (const tng_trajectory_t tng_data,
1354 * @brief Get the current trajectory frame set.
1355 * @param tng_data is the trajectory from which to get the frame set.
1356 * @param frame_set_p will be set to point at the memory position of
1357 * the found frame set.
1358 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1359 * must be initialised before using it.
1360 * @return TNG_SUCCESS (0) if successful.
1362 tng_function_status DECLSPECDLLEXPORT tng_current_frame_set_get
1363 (const tng_trajectory_t tng_data,
1364 tng_trajectory_frame_set_t *frame_set_p);
1367 * @brief Find the requested frame set number.
1368 * @param tng_data is the trajectory from which to get the frame set.
1369 * @param nr is the frame set number to search for.
1370 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1371 * must be initialised before using it.
1372 * @pre \code nr >= 0 \endcode The frame set number (nr) must be >= 0.
1373 * @details tng_data->current_trajectory_frame_set will contain the
1374 * found trajectory if successful.
1375 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1376 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1378 tng_function_status DECLSPECDLLEXPORT tng_frame_set_nr_find
1379 (tng_trajectory_t tng_data,
1383 * @brief Find the frame set containing a specific frame.
1384 * @param tng_data is the trajectory from which to get the frame set.
1385 * @param frame is the frame number to search for.
1386 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1387 * must be initialised before using it.
1388 * @pre \code frame >= 0 \endcode The frame number must be >= 0.
1389 * @details tng_data->current_trajectory_frame_set will contain the
1390 * found trajectory if successful.
1391 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1392 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1394 tng_function_status DECLSPECDLLEXPORT tng_frame_set_of_frame_find
1395 (tng_trajectory_t tng_data,
1396 const int64_t frame);
1399 * @brief Get the file position of the next frame set in the input file.
1400 * @param tng_data is a trajectory data container.
1401 * @param frame_set is the frame set of which to get the position of the
1402 * following frame set.
1403 * @param pos is pointing to a value set to the file position.
1404 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1405 * must be initialised before using it.
1406 * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer.
1407 * @return TNG_SUCCESS (0) if successful.
1409 tng_function_status DECLSPECDLLEXPORT tng_frame_set_next_frame_set_file_pos_get
1410 (const tng_trajectory_t tng_data,
1411 const tng_trajectory_frame_set_t frame_set,
1415 * @brief Get the file position of the previous frame set in the input file.
1416 * @param tng_data is a trajectory data container.
1417 * @param frame_set is the frame set of which to get the position of the
1418 * previous frame set.
1419 * @param pos is pointing to a value set to the file position.
1420 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1421 * must be initialised before using it.
1422 * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer.
1423 * @return TNG_SUCCESS (0) if successful.
1425 tng_function_status DECLSPECDLLEXPORT tng_frame_set_prev_frame_set_file_pos_get
1426 (const tng_trajectory_t tng_data,
1427 const tng_trajectory_frame_set_t frame_set,
1431 * @brief Get the first and last frames of the frame set.
1432 * @param tng_data is a trajectory data container.
1433 * @param frame_set is the frame set of which to get the frame range.
1434 * @param first_frame is set to the first frame of the frame set.
1435 * @param last_frame is set to the last frame of the frame set.
1436 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1437 * must be initialised before using it.
1438 * @pre \code first_frame != 0 \endcode The pointer to first_frame must
1439 * not be a NULL pointer.
1440 * @pre \code last_frame != 0 \endcode The pointer to last_frame must
1441 * not be a NULL pointer.
1442 * @return TNG_SUCCESS (0) if successful.
1444 tng_function_status DECLSPECDLLEXPORT tng_frame_set_frame_range_get
1445 (const tng_trajectory_t tng_data,
1446 const tng_trajectory_frame_set_t frame_set,
1447 int64_t *first_frame,
1448 int64_t *last_frame);
1451 * @brief Allocate memory for and setup a molecule container.
1452 * @param tng_data is a trajectory data container.
1453 * @param molecule_p is a pointer to molecule to allocate and initialise.
1454 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1455 * error has occured.
1457 tng_function_status DECLSPECDLLEXPORT tng_molecule_alloc(const tng_trajectory_t tng_data,
1458 tng_molecule_t *molecule_p);
1461 * @brief Clean up a molecule container and free its allocated memory.
1462 * @param tng_data is a trajectory data container.
1463 * @param molecule_p is the molecule to destroy.
1464 * @details All allocated memory in the data structure is freed and also the memory
1465 * of the molecule itself.
1466 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1467 * error has occured.
1469 tng_function_status DECLSPECDLLEXPORT tng_molecule_free(const tng_trajectory_t tng_data,
1470 tng_molecule_t *molecule_p);
1473 * @brief Setup a molecule container.
1474 * @param tng_data is a trajectory data container.
1475 * @param molecule is the molecule to initialise. Memory must be preallocated.
1476 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1477 * error has occured.
1479 tng_function_status DECLSPECDLLEXPORT tng_molecule_init
1480 (const tng_trajectory_t tng_data,
1481 tng_molecule_t molecule);
1484 * @brief Clean up a molecule container.
1485 * @param tng_data is a trajectory data container.
1486 * @param molecule is the molecule to destroy.
1487 * @details All allocated memory in the data structure is freed, but not the
1488 * memory of molecule itself.
1489 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1490 * error has occured.
1492 tng_function_status DECLSPECDLLEXPORT tng_molecule_destroy
1493 (const tng_trajectory_t tng_data,
1494 tng_molecule_t molecule);
1497 * @brief Add a molecule to the trajectory.
1498 * @param tng_data is the trajectory data container containing the block..
1499 * @param name is a pointer to the string containing the name of the new molecule.
1500 * @param molecule is a pointer to the newly created molecule.
1501 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1502 * must be initialised before using it.
1503 * @pre \code name != 0 \endcode The pointer to the name string
1504 * must not be a NULL pointer.
1505 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1506 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1508 tng_function_status DECLSPECDLLEXPORT tng_molecule_add
1509 (tng_trajectory_t tng_data,
1511 tng_molecule_t *molecule);
1514 * @brief Add a molecule with a specific ID to the trajectory.
1515 * @param tng_data is the trajectory data container containing the block..
1516 * @param name is a pointer to the string containing the name of the new molecule.
1517 * @param id is the ID of the created molecule.
1518 * @param molecule is a pointer to the newly created molecule.
1519 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1520 * must be initialised before using it.
1521 * @pre \code name != 0 \endcode The pointer to the name string
1522 * must not be a NULL pointer.
1523 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1524 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1526 tng_function_status DECLSPECDLLEXPORT tng_molecule_w_id_add
1527 (tng_trajectory_t tng_data,
1530 tng_molecule_t *molecule);
1533 * @brief Add an existing molecule (from a molecule container) to the trajectory.
1534 * @param tng_data is the trajectory data container containing the block..
1535 * @param molecule is a pointer to the molecule to add to the trajectory and will
1536 * afterwards point to the molecule in the trajectory.
1537 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1538 * must be initialised before using it.
1539 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error
1542 tng_function_status DECLSPECDLLEXPORT tng_molecule_existing_add
1543 (tng_trajectory_t tng_data,
1544 tng_molecule_t *molecule);
1547 * @brief Get the name of a molecule.
1548 * @param tng_data the trajectory containing the molecule.
1549 * @param molecule the molecule of which to get the name.
1550 * @param name the string to fill with the name of the molecule,
1551 * memory must be allocated before.
1552 * @param max_len maximum char length of the string, i.e. how much memory has
1553 * been reserved for name. This includes \0 terminating character.
1554 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1555 * @pre \code name != 0 \endcode The pointer to the name string
1556 * must not be a NULL pointer.
1557 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1558 * has occurred (source string longer than destination string).
1560 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_get
1561 (const tng_trajectory_t tng_data,
1562 const tng_molecule_t molecule,
1567 * @brief Set the name of a molecule.
1568 * @param tng_data is the trajectory data container containing the molecule..
1569 * @param molecule is the molecule to rename.
1570 * @param new_name is a string containing the wanted name.
1571 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1572 * must be initialised before using it.
1573 * @pre \code new_name != 0 \endcode The pointer to the name string
1574 * must not be a NULL pointer.
1575 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1576 * error has occured.
1578 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_set
1579 (tng_trajectory_t tng_data,
1580 tng_molecule_t molecule,
1581 const char *new_name);
1584 * @brief Get the count of a molecule.
1585 * @param tng_data is the trajectory data container containing the molecule..
1586 * @param molecule is the molecule of which to get the count.
1587 * @param cnt is a pointer to the variable to be populated with the count.
1588 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1589 * must be initialised before using it.
1590 * @pre \code cnt != 0 \endcode The pointer to the molecule count
1591 * must not be a NULL pointer.
1592 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1593 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1595 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_get
1596 (const tng_trajectory_t tng_data,
1597 const tng_molecule_t molecule,
1601 * @brief Set the count of a molecule.
1602 * @param tng_data is the trajectory data container containing the molecule..
1603 * @param molecule is the molecule of which to set the count.
1604 * @param cnt is the number of instances of this molecule.
1605 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1606 * must be initialised before using it.
1607 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1608 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1610 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_set
1611 (tng_trajectory_t tng_data,
1612 tng_molecule_t molecule,
1616 * @brief Find a molecule.
1617 * @param tng_data is the trajectory data container containing the molecule.
1618 * @param name is a string containing the name of the molecule. If name is empty
1619 * only id will be used for finding the molecule.
1620 * @param id is the id of the molecule to look for. If id is -1 only the name of
1621 * the molecule will be used for finding the molecule.
1622 * @param molecule is a pointer to the molecule if it was found - otherwise 0.
1623 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1624 * must be initialised before using it.
1625 * @pre \code name != 0 \endcode The pointer to the name string
1626 * must not be a NULL pointer.
1627 * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the
1628 * molecule is not found.
1629 * @details If name is an empty string and id == -1 the first residue will
1632 tng_function_status DECLSPECDLLEXPORT tng_molecule_find
1633 (tng_trajectory_t tng_data,
1636 tng_molecule_t *molecule);
1639 * @brief Retrieve the molecule with specified index in the list of molecules.
1640 * @param tng_data is the trajectory data container containing the molecule.
1641 * @param index is the index (in tng_data->molecules) of the molecule to return
1642 * @param molecule is a pointer to the molecule if it was found - otherwise 0.
1643 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1644 * must be initialised before using it.
1645 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1646 * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the
1647 * molecule is not found.
1649 tng_function_status DECLSPECDLLEXPORT tng_molecule_of_index_get
1650 (tng_trajectory_t tng_data,
1652 tng_molecule_t *molecule);
1655 * @brief Copy all molecules and the molecule counts from one TNG trajectory
1657 * @param tng_data_src is the source trajectory containing the molecular
1659 * @param tng_data_dest is the destination trajectory.
1660 * @pre \code tng_data_src != 0 \endcode The trajectory container (tng_data_src)
1661 * must be initialised before using it.
1662 * @pre \code tng_data_dest != 0 \endcode The trajectory container (tng_data_dest)
1663 * must be initialised before using it.
1664 * @details The molecular system in tng_data_dest will be overwritten.
1665 * @return TNG_SUCCESS(0) if the copying is successful, TNG_FAILURE if a minor
1666 * error has occured or TNG_CRITICAL(2) if a major error has occured.
1668 tng_function_status DECLSPECDLLEXPORT tng_molecule_system_copy(tng_trajectory_t tng_data_src,
1669 tng_trajectory_t tng_data_dest);
1672 * @brief Get the number of chains in a molecule.
1673 * @param tng_data is the trajectory containing the molecule.
1674 * @param molecule is the molecule of which to get the number of chains.
1675 * @param n is pointing to a value set to the number of chains.
1676 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1677 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1678 * @return TNG_SUCCESS (0) if successful.
1680 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_chains_get
1681 (const tng_trajectory_t tng_data,
1682 const tng_molecule_t molecule,
1686 * @brief Retrieve the chain of a molecule with specified index in the list
1688 * @param tng_data is the trajectory data container containing the molecule.
1689 * @param index is the index (in molecule->chains) of the chain to return
1690 * @param molecule is the molecule from which to get the chain.
1691 * @param chain is a pointer to the chain if it was found - otherwise 0.
1692 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1693 * @pre \code chain != 0 \endcode chain must not be a NULL pointer.
1694 * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the
1695 * chain is not found.
1697 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_of_index_get
1698 (tng_trajectory_t tng_data,
1699 tng_molecule_t molecule,
1701 tng_chain_t *chain);
1704 * @brief Get the number of residues in a molecule.
1705 * @param tng_data is the trajectory containing the molecule.
1706 * @param molecule is the molecule of which to get the number residues.
1707 * @param n is pointing to a value set to the number of residues.
1708 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1709 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1710 * @return TNG_SUCCESS (0) if successful.
1712 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_residues_get
1713 (const tng_trajectory_t tng_data,
1714 const tng_molecule_t molecule,
1718 * @brief Retrieve the residue of a molecule with specified index in the list
1720 * @param tng_data is the trajectory data container containing the molecule.
1721 * @param index is the index (in molecule->residues) of the residue to return
1722 * @param molecule is the molecule from which to get the residue.
1723 * @param residue is a pointer to the residue if it was found - otherwise 0.
1724 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1725 * @pre \code residue != 0 \endcode residue must not be a NULL pointer.
1726 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the
1727 * residue is not found.
1729 tng_function_status DECLSPECDLLEXPORT tng_molecule_residue_of_index_get
1730 (const tng_trajectory_t tng_data,
1731 const tng_molecule_t molecule,
1732 const int64_t index,
1733 tng_residue_t *residue);
1736 * @brief Get the number of atoms in a molecule.
1737 * @param tng_data is the trajectory containing the molecule.
1738 * @param molecule is the molecule of which to get the number of atoms.
1739 * @param n is pointing to a value set to the number of atoms.
1740 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1741 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1742 * @return TNG_SUCCESS (0) if successful.
1744 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_atoms_get
1745 (const tng_trajectory_t tng_data,
1746 const tng_molecule_t molecule,
1750 * @brief Retrieve the atom of a molecule with specified index in the list
1752 * @param tng_data is the trajectory data container containing the molecule.
1753 * @param index is the index (in molecule->atoms) of the atom to return
1754 * @param molecule is the molecule from which to get the atom.
1755 * @param atom is a pointer to the atom if it was found - otherwise 0.
1756 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1757 * @pre \code atom != 0 \endcode atom must not be a NULL pointer.
1758 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the
1759 * atom is not found.
1761 tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_of_index_get
1762 (const tng_trajectory_t tng_data,
1763 const tng_molecule_t molecule,
1764 const int64_t index,
1768 * @brief Find a chain in a molecule.
1769 * @param tng_data is the trajectory data container containing the molecule.
1770 * @param molecule is the molecule in which to search for the chain.
1771 * @param name is a string containing the name of the chain. If name is empty
1772 * only id will be used for finding the chain.
1773 * @param id is the id of the chain to look for. If id is -1 only the name of
1774 * the chain will be used for finding the chain.
1775 * @param chain is a pointer to the chain if it was found - otherwise 0.
1776 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1777 * must be initialised before using it.
1778 * @pre \code name != 0 \endcode The pointer to the name string
1779 * must not be a NULL pointer.
1780 * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the
1781 * chain is not found.
1782 * @details If name is an empty string and id == -1 the first residue will
1785 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_find
1786 (tng_trajectory_t tng_data,
1787 tng_molecule_t molecule,
1790 tng_chain_t *chain);
1793 * @brief Add a chain to a molecule.
1794 * @param tng_data is the trajectory data container containing the molecule..
1795 * @param molecule is the molecule to add a chain to.
1796 * @param name is a string containing the name of the chain.
1797 * @param chain is a pointer to the newly created chain.
1798 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1799 * must be initialised before using it.
1800 * @pre \code name != 0 \endcode The pointer to the name string
1801 * must not be a NULL pointer.
1802 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1803 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1805 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_add
1806 (tng_trajectory_t tng_data,
1807 tng_molecule_t molecule,
1809 tng_chain_t *chain);
1812 * @brief Add a chain with a specific id to a molecule.
1813 * @param tng_data is the trajectory data container containing the molecule..
1814 * @param molecule is the molecule to add a chain to.
1815 * @param name is a string containing the name of the chain.
1816 * @param id is the ID of the created chain.
1817 * @param chain is a pointer to the newly created chain.
1818 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1819 * must be initialised before using it.
1820 * @pre \code name != 0 \endcode The pointer to the name string
1821 * must not be a NULL pointer.
1822 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1823 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1825 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_w_id_add
1826 (tng_trajectory_t tng_data,
1827 tng_molecule_t molecule,
1830 tng_chain_t *chain);
1833 * @brief Add a bond between two atoms to a molecule.
1834 * @param tng_data is the trajectory data container containing the molecule.
1835 * @param molecule is the molecule containing the atoms to connect.
1836 * @param from_atom_id is the id of one of the two atoms in the bond.
1837 * @param to_atom_id is the id of the other atom in the bond.
1838 * @param bond is a pointer to the newly created bond.
1839 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1840 * must be initialised before using it.
1841 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (!) if a minor error
1842 * has occured or TNG_CRITICAL (2) if a major error has occured.
1844 tng_function_status DECLSPECDLLEXPORT tng_molecule_bond_add
1845 (const tng_trajectory_t tng_data,
1846 tng_molecule_t molecule,
1847 const int64_t from_atom_id,
1848 const int64_t to_atom_id,
1852 * @brief Find an atom in a molecule.
1853 * @param tng_data is the trajectory data container containing the molecule.
1854 * @param molecule is the molecule in which to search for the atom.
1855 * @param name is a string containing the name of the atom. If name is an
1856 * empty string only id will be used for searching.
1857 * @param id is the id of the atom to find. If id == -1 the first atom
1858 * that matches the specified name will be found.
1859 * @param atom is a pointer to the atom if it was found - otherwise 0.
1860 * @pre \code name != 0 \endcode The pointer to the name string
1861 * must not be a NULL pointer.
1862 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the
1863 * atom is not found.
1864 * @details If name is an empty string and id == -1 the first residue will
1867 tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_find
1868 (tng_trajectory_t tng_data,
1869 tng_molecule_t molecule,
1875 * @brief Get the name of a chain.
1876 * @param tng_data the trajectory containing the chain.
1877 * @param chain the chain of which to get the name.
1878 * @param name the string to fill with the name of the chain,
1879 * memory must be allocated before.
1880 * @param max_len maximum char length of the string, i.e. how much memory has
1881 * been reserved for name. This includes \0 terminating character.
1882 * @pre \code chain != 0 \endcode The chain must not be NULL.
1883 * @pre \code name != 0 \endcode The pointer to the name string
1884 * must not be a NULL pointer.
1885 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1886 * has occurred (source string longer than destination string).
1888 tng_function_status DECLSPECDLLEXPORT tng_chain_name_get
1889 (const tng_trajectory_t tng_data,
1890 const tng_chain_t chain,
1895 * @brief Set the name of a chain.
1896 * @param tng_data is the trajectory data container containing the atom..
1897 * @param chain is the chain to rename.
1898 * @param new_name is a string containing the wanted name.
1899 * @pre \code new_name != 0 \endcode The pointer to the name string
1900 * must not be a NULL pointer.
1901 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1902 * error has occured.
1904 tng_function_status DECLSPECDLLEXPORT tng_chain_name_set
1905 (tng_trajectory_t tng_data,
1907 const char *new_name);
1910 * @brief Get the number of residues in a molecule chain.
1911 * @param tng_data is the trajectory containing the chain.
1912 * @param chain is the chain of which to get the number of residues.
1913 * @param n is pointing to a value set to the number of residues.
1914 * @pre \code chain != 0 \endcode The chain must not be NULL.
1915 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1916 * @return TNG_SUCCESS (0) if successful.
1918 tng_function_status DECLSPECDLLEXPORT tng_chain_num_residues_get
1919 (const tng_trajectory_t tng_data,
1920 const tng_chain_t chain,
1924 * @brief Retrieve the residue of a chain with specified index in the list
1926 * @param tng_data is the trajectory data container containing the chain.
1927 * @param index is the index (in chain->residues) of the residue to return
1928 * @param chain is the chain from which to get the residue.
1929 * @param residue is a pointer to the residue if it was found - otherwise 0.
1930 * @pre \code chain != 0 \endcode chain must not be a NULL pointer.
1931 * @pre \code residue != 0 \endcode residue must not be a NULL pointer.
1932 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the
1933 * residue is not found.
1935 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_of_index_get
1936 (const tng_trajectory_t tng_data,
1937 const tng_chain_t chain,
1938 const int64_t index,
1939 tng_residue_t *residue);
1942 * @brief Find a residue in a chain.
1943 * @param tng_data is the trajectory data container containing the chain.
1944 * @param chain is the chain in which to search for the residue.
1945 * @param name is a string containing the name of the residue. If name is an
1946 * empty string only id will be used for searching.
1947 * @param id is the id of the residue to find. If id == -1 the first residue
1948 * that matches the specified name will be found.
1949 * @param residue is a pointer to the residue if it was found - otherwise 0.
1950 * @pre \code name != 0 \endcode The pointer to the name string
1951 * must not be a NULL pointer.
1952 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the
1953 * residue is not found.
1954 * @details If name is an empty string and id == -1 the first residue will
1957 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_find
1958 (tng_trajectory_t tng_data,
1962 tng_residue_t *residue);
1965 * @brief Add a residue to a chain.
1966 * @param tng_data is the trajectory data container containing the chain..
1967 * @param chain is the chain to add a residue to.
1968 * @param name is a string containing the name of the residue.
1969 * @param residue is a pointer to the newly created residue.
1970 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1971 * must be initialised before using it.
1972 * @pre \code name != 0 \endcode The pointer to the name string
1973 * must not be a NULL pointer.
1974 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1975 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1977 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_add
1978 (tng_trajectory_t tng_data,
1981 tng_residue_t *residue);
1984 * @brief Add a residue with a specific ID to a chain.
1985 * @param tng_data is the trajectory data container containing the chain..
1986 * @param chain is the chain to add a residue to.
1987 * @param name is a string containing the name of the residue.
1988 * @param id is the ID of the created residue.
1989 * @param residue is a pointer to the newly created residue.
1990 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1991 * must be initialised before using it.
1992 * @pre \code name != 0 \endcode The pointer to the name string
1993 * must not be a NULL pointer.
1994 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1995 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1997 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_w_id_add
1998 (tng_trajectory_t tng_data,
2002 tng_residue_t *residue);
2005 * @brief Get the name of a residue.
2006 * @param tng_data the trajectory containing the residue.
2007 * @param residue the residue of which to get the name.
2008 * @param name the string to fill with the name of the residue,
2009 * memory must be allocated before.
2010 * @param max_len maximum char length of the string, i.e. how much memory has
2011 * been reserved for name. This includes \0 terminating character.
2012 * @pre \code residue != 0 \endcode The residue must not be NULL.
2013 * @pre \code name != 0 \endcode The pointer to the name string
2014 * must not be a NULL pointer.
2015 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2016 * has occurred (source string longer than destination string).
2018 tng_function_status DECLSPECDLLEXPORT tng_residue_name_get
2019 (const tng_trajectory_t tng_data,
2020 const tng_residue_t residue,
2025 * @brief Set the name of a residue.
2026 * @param tng_data is the trajectory data container containing the residue.
2027 * @param residue is the residue to rename.
2028 * @param new_name is a string containing the wanted name.
2029 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2030 * must be initialised before using it.
2031 * @pre \code new_name != 0 \endcode The new name to set (new_name) must
2032 * not be a NULL pointer.
2033 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2034 * error has occured.
2036 tng_function_status DECLSPECDLLEXPORT tng_residue_name_set
2037 (tng_trajectory_t tng_data,
2038 tng_residue_t residue,
2039 const char *new_name);
2042 * @brief Get the number of atoms in a residue.
2043 * @param tng_data is the trajectory containing the residue.
2044 * @param residue is the residue of which to get the number atoms.
2045 * @param n is pointing to a value set to the number of atoms.
2046 * @pre \code residue != 0 \endcode The residue must not be NULL.
2047 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
2048 * @return TNG_SUCCESS (0) if successful.
2050 tng_function_status DECLSPECDLLEXPORT tng_residue_num_atoms_get
2051 (const tng_trajectory_t tng_data,
2052 const tng_residue_t residue,
2056 * @brief Retrieve the atom of a residue with specified index in the list
2058 * @param tng_data is the trajectory data container containing the residue.
2059 * @param index is the index (in residue->atoms) of the atom to return
2060 * @param residue is the residue from which to get the atom.
2061 * @param atom is a pointer to the atom if it was found - otherwise 0.
2062 * @pre \code residue != 0 \endcode residue must not be a NULL pointer.
2063 * @pre \code atom != 0 \endcode atom must not be a NULL pointer.
2064 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the
2065 * atom is not found.
2067 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_of_index_get
2068 (const tng_trajectory_t tng_data,
2069 const tng_residue_t residue,
2070 const int64_t index,
2074 * @brief Add an atom to a residue.
2075 * @param tng_data is the trajectory containing the residue.
2076 * @param residue is the residue to add an atom to.
2077 * @param atom_name is a string containing the name of the atom.
2078 * @param atom_type is a string containing the atom type of the atom.
2079 * @param atom is a pointer to the newly created atom.
2080 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2081 * must be initialised before using it.
2082 * @pre \code atom_name != 0 \endcode The pointer to the atom name string
2083 * must not be a NULL pointer.
2084 * @pre \code atom_type != 0 \endcode The pointer to the atom_type string
2085 * must not be a NULL pointer.
2086 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
2087 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
2089 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_add
2090 (tng_trajectory_t tng_data,
2091 tng_residue_t residue,
2092 const char *atom_name,
2093 const char *atom_type,
2097 * @brief Add an atom with a specific ID to a residue.
2098 * @param tng_data is the trajectory containing the residue.
2099 * @param residue is the residue to add an atom to.
2100 * @param atom_name is a string containing the name of the atom.
2101 * @param atom_type is a string containing the atom type of the atom.
2102 * @param id is the ID of the created atom.
2103 * @param atom is a pointer to the newly created atom.
2104 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2105 * must be initialised before using it.
2106 * @pre \code atom_name != 0 \endcode The pointer to the atom name string
2107 * must not be a NULL pointer.
2108 * @pre \code atom_type != 0 \endcode The pointer to the atom_type string
2109 * must not be a NULL pointer.
2110 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
2111 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
2113 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_w_id_add
2114 (tng_trajectory_t tng_data,
2115 tng_residue_t residue,
2116 const char *atom_name,
2117 const char *atom_type,
2122 * @brief Get the residue of an atom.
2123 * @param tng_data the trajectory containing the atom.
2124 * @param atom the atom of which to get the name.
2125 * @param residue is set to the residue of the atom.
2126 * @pre \code atom != 0 \endcode The atom must not be NULL.
2127 * @return TNG_SUCCESS (0) if successful.
2129 tng_function_status tng_atom_residue_get(const tng_trajectory_t tng_data,
2130 const tng_atom_t atom,
2131 tng_residue_t *residue);
2134 * @brief Get the name of an atom.
2135 * @param tng_data the trajectory containing the atom.
2136 * @param atom the atom of which to get the name.
2137 * @param name the string to fill with the name of the atom,
2138 * memory must be allocated before.
2139 * @param max_len maximum char length of the string, i.e. how much memory has
2140 * been reserved for name. This includes \0 terminating character.
2141 * @pre \code atom != 0 \endcode The atom must not be NULL.
2142 * @pre \code name != 0 \endcode The pointer to the name string
2143 * must not be a NULL pointer.
2144 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2145 * has occurred (source string longer than destination string).
2147 tng_function_status DECLSPECDLLEXPORT tng_atom_name_get
2148 (const tng_trajectory_t tng_data,
2149 const tng_atom_t atom,
2154 * @brief Set the name of an atom.
2155 * @param tng_data is the trajectory data container containing the atom.
2156 * @param atom is the atom to rename.
2157 * @param new_name is a string containing the wanted name.
2158 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2159 * must be initialised before using it.
2160 * @pre \code new_name != 0 \endcode The pointer to the name string
2161 * must not be a NULL pointer.
2162 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2163 * error has occured.
2165 tng_function_status DECLSPECDLLEXPORT tng_atom_name_set
2166 (tng_trajectory_t tng_data,
2168 const char *new_name);
2171 * @brief Get the type of an atom.
2172 * @param tng_data the trajectory containing the atom.
2173 * @param atom the atom of which to get the type.
2174 * @param type the string to fill with the type of the atom,
2175 * memory must be allocated before.
2176 * @param max_len maximum char length of the string, i.e. how much memory has
2177 * been reserved for type. This includes \0 terminating character.
2178 * @pre \code atom != 0 \endcode The atom must not be NULL.
2179 * @pre \code type != 0 \endcode The pointer to the type string
2180 * must not be a NULL pointer.
2181 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2182 * has occurred (source string longer than destination string).
2184 tng_function_status DECLSPECDLLEXPORT tng_atom_type_get
2185 (const tng_trajectory_t tng_data,
2186 const tng_atom_t atom,
2191 * @brief Set the atom type of an atom.
2192 * @param tng_data is the trajectory data container containing the atom.
2193 * @param atom is the atom to change.
2194 * @param new_type is a string containing the atom type.
2195 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2196 * must be initialised before using it.
2197 * @pre \code new_type != 0 \endcode The pointer to the atom type string
2198 * must not be a NULL pointer.
2199 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2200 * error has occured.
2202 tng_function_status DECLSPECDLLEXPORT tng_atom_type_set
2203 (tng_trajectory_t tng_data,
2205 const char *new_type);
2208 * @brief Get the molecule name of real particle number (number in mol system).
2209 * @param tng_data is the trajectory data container containing the atom.
2210 * @param nr is the real number of the particle in the molecular system.
2211 * @param name is a string, which is set to the name of the molecule. Memory
2212 * must be reserved beforehand.
2213 * @param max_len is the maximum length of name.
2214 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2215 * must be initialised before using it.
2216 * @pre \code name != 0 \endcode The pointer to the name string
2217 * must not be a NULL pointer.
2218 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2221 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_of_particle_nr_get
2222 (const tng_trajectory_t tng_data,
2228 * @brief Get the molecule id of real particle number (number in mol system).
2229 * @param tng_data is the trajectory data container containing the atom.
2230 * @param nr is the real number of the particle in the molecular system.
2231 * @param id is will be set to the id of the molecule.
2232 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2233 * must be initialised before using it.
2234 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer.
2235 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2238 tng_function_status DECLSPECDLLEXPORT tng_molecule_id_of_particle_nr_get
2239 (const tng_trajectory_t tng_data,
2244 * @brief Get the bonds of the current molecular system.
2245 * @param tng_data is the trajectory data container containing the molecular
2247 * @param n_bonds is set to the number of bonds in the molecular system and
2248 * thereby also the lengths of the two lists: from_atoms and to_atoms.
2249 * @param from_atoms is a list (memory reserved by this function) of atoms
2250 * (number of atom in mol system) in bonds.
2251 * @param to_atoms is a list (memory reserved by this function) of atoms
2252 * (number of atom in mol system) in bonds.
2253 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2254 * must be initialised before using it.
2255 * @pre \code n_bonds != 0 \endcode The pointer to n_bonds must not be a
2257 * @pre \code from_atoms != 0 \endcode The pointer to from_atoms must not
2258 * be a NULL pointer.
2259 * @pre \code to_atoms != 0 \endcode The pointer to to_atoms must not
2260 * be a NULL pointer.
2261 * @details The two lists of atoms use the same index, i.e. from_atoms[0]
2262 * and to_atoms[0] are linked with a bond. Since memory is reserved in
2263 * this function it must be freed afterwards.
2264 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2265 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2267 tng_function_status DECLSPECDLLEXPORT tng_molsystem_bonds_get
2268 (const tng_trajectory_t tng_data,
2270 int64_t **from_atoms,
2271 int64_t **to_atoms);
2274 * @brief Get the chain name of real particle number (number in mol system).
2275 * @param tng_data is the trajectory data container containing the atom.
2276 * @param nr is the real number of the particle in the molecular system.
2277 * @param name is a string, which is set to the name of the chain. Memory
2278 * must be reserved beforehand.
2279 * @param max_len is the maximum length of name.
2280 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2281 * must be initialised before using it.
2282 * @pre \code name != 0 \endcode The pointer to the name string
2283 * must not be a NULL pointer.
2284 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2287 tng_function_status DECLSPECDLLEXPORT tng_chain_name_of_particle_nr_get
2288 (const tng_trajectory_t tng_data,
2294 * @brief Get the residue name of real particle number (number in mol system).
2295 * @param tng_data is the trajectory data container containing the atom.
2296 * @param nr is the real number of the particle in the molecular system.
2297 * @param name is a string, which is set to the name of the residue. Memory
2298 * must be reserved beforehand.
2299 * @param max_len is the maximum length of name.
2300 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2301 * must be initialised before using it.
2302 * @pre \code name != 0 \endcode The pointer to the name string
2303 * must not be a NULL pointer.
2304 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2307 tng_function_status DECLSPECDLLEXPORT tng_residue_name_of_particle_nr_get
2308 (const tng_trajectory_t tng_data,
2314 * @brief Get the residue id (local to molecule) of real particle number
2315 * (number in mol system).
2316 * @param tng_data is the trajectory data container containing the atom.
2317 * @param nr is the real number of the particle in the molecular system.
2318 * @param id is a pointer to the variable, which will be set to the ID.
2319 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2320 * must be initialised before using it.
2321 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer.
2322 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2325 tng_function_status DECLSPECDLLEXPORT tng_residue_id_of_particle_nr_get
2326 (const tng_trajectory_t tng_data,
2331 * @brief Get the residue id (based on other molecules and molecule counts)
2332 * of real particle number (number in mol system).
2333 * @param tng_data is the trajectory data container containing the atom.
2334 * @param nr is the real number of the particle in the molecular system.
2335 * @param id is a pointer to the variable, which will be set to the ID.
2336 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2337 * must be initialised before using it.
2338 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer.
2339 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2342 tng_function_status DECLSPECDLLEXPORT tng_global_residue_id_of_particle_nr_get
2343 (const tng_trajectory_t tng_data,
2348 * @brief Get the atom name of real particle number (number in mol system).
2349 * @param tng_data is the trajectory data container containing the atom.
2350 * @param nr is the real number of the particle in the molecular system.
2351 * @param name is a string, which is set to the name of the atom. Memory
2352 * must be reserved beforehand.
2353 * @param max_len is the maximum length of name.
2354 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2355 * must be initialised before using it.
2356 * @pre \code name != 0 \endcode The pointer to the name string
2357 * must not be a NULL pointer.
2358 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2361 tng_function_status DECLSPECDLLEXPORT tng_atom_name_of_particle_nr_get
2362 (const tng_trajectory_t tng_data,
2368 * @brief Get the atom type of real particle number (number in mol system).
2369 * @param tng_data is the trajectory data container containing the atom.
2370 * @param nr is the real number of the particle in the molecular system.
2371 * @param type is a string, which is set to the type of the atom. Memory
2372 * must be reserved beforehand.
2373 * @param max_len is the maximum length of type.
2374 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2375 * must be initialised before using it.
2376 * @pre \code type != 0 \endcode The pointer to the type string
2377 * must not be a NULL pointer.
2378 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2381 tng_function_status DECLSPECDLLEXPORT tng_atom_type_of_particle_nr_get
2382 (const tng_trajectory_t tng_data,
2388 * @brief Add a particle mapping table.
2389 * @details Each particle mapping table will be written as a separate block,
2390 * followed by the data blocks for the corresponding particles. In most cases
2391 * there is one particle mapping block for each thread writing the trajectory.
2392 * @param tng_data is the trajectory, with the frame set to which to add
2393 * the mapping block.
2394 * @details The mapping information is added to the currently active frame set
2396 * @param num_first_particle is the first particle number of this mapping
2398 * @param n_particles is the number of particles in this mapping block.
2399 * @param mapping_table is a list of the real particle numbers (i.e. the numbers
2400 * used in the molecular system). The list is n_particles long.
2401 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2402 * must be initialised before using it.
2403 * @details mapping_table[0] is the real particle number of the first particle
2404 * in the following data blocks.
2405 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2406 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2408 tng_function_status DECLSPECDLLEXPORT tng_particle_mapping_add
2409 (tng_trajectory_t tng_data,
2410 const int64_t num_first_particle,
2411 const int64_t n_particles,
2412 const int64_t *mapping_table);
2415 * @brief Remove all particle mappings (in memory) from the current frame set.
2416 * @details Clears the currently setup particle mappings of the current frame
2418 * @param tng_data is the trajectory, with the frame set of which to clear
2419 * all particle mappings.
2420 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2421 * must be initialised before using it.
2422 * @return TNG_SUCCESS (0) if successful.
2424 tng_function_status DECLSPECDLLEXPORT tng_frame_set_particle_mapping_free
2425 (tng_trajectory_t tng_data);
2428 * @brief Read the header blocks from the input_file of tng_data.
2429 * @details The trajectory blocks must be read separately and iteratively in chunks
2431 * @param tng_data is a trajectory data container.
2432 * @details tng_data->input_file_path specifies
2433 * which file to read from. If the file (input_file) is not open it will be
2435 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2436 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2437 * compared to the md5 hash of the read contents to ensure valid data.
2438 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2439 * must be initialised before using it.
2440 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2441 * error has occured.
2443 tng_function_status DECLSPECDLLEXPORT tng_file_headers_read
2444 (tng_trajectory_t tng_data,
2445 const char hash_mode);
2448 * @brief Write the header blocks to the output_file of tng_data.
2449 * @details The trajectory blocks must be written separately and iteratively in chunks
2451 * @param tng_data is a trajectory data container.
2452 * @details tng_data->output_file_path
2453 * specifies which file to write to. If the file (output_file) is not open it
2455 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2456 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
2457 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2458 * must be initialised before using it.
2459 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2460 * error has occured.
2462 tng_function_status DECLSPECDLLEXPORT tng_file_headers_write
2463 (tng_trajectory_t tng_data,
2464 const char hash_mode);
2467 * @brief Read one (the next) block (of any kind) from the input_file of tng_data.
2468 * @param tng_data is a trajectory data container.
2469 * @details tng_data->input_file_path specifies
2470 * which file to read from. If the file (input_file) is not open it will be
2472 * @param block_data is a pointer to the struct which will be populated with the
2474 * @details If block_data->input_file_pos > 0 it is the position from where the
2475 * reading starts otherwise it starts from the current position.
2476 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2477 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2478 * compared to the md5 hash of the read contents to ensure valid data.
2479 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2480 * must be initialised before using it.
2481 * @pre \code block != 0 \endcode The block container (block) must be
2482 * initialised before using it.
2483 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2484 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2486 tng_function_status DECLSPECDLLEXPORT tng_block_read_next
2487 (tng_trajectory_t tng_data,
2488 tng_gen_block_t block_data,
2489 const char hash_mode);
2492 * @brief Read one frame set, including all particle mapping blocks and data
2493 * blocks, starting from the current file position.
2494 * @param tng_data is a trajectory data container.
2495 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2496 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2497 * compared to the md5 hash of the read contents to ensure valid data.
2498 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2499 * must be initialised before using it.
2500 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2501 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2503 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read
2504 (tng_trajectory_t tng_data,
2505 const char hash_mode);
2508 * @brief Read data from the current frame set from the input_file. Only read
2509 * particle mapping and data blocks matching the specified block_id.
2510 * @param tng_data is a trajectory data container.
2511 * @details tng_data->input_file_path specifies
2512 * which file to read from. If the file (input_file) is not open it will be
2514 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2515 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2516 * compared to the md5 hash of the read contents to ensure valid data.
2517 * @param block_id is the ID of the data block to read from file.
2518 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2519 * must be initialised before using it.
2520 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2521 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2523 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_current_only_data_from_block_id
2524 (tng_trajectory_t tng_data,
2525 const char hash_mode,
2526 const int64_t block_id);
2529 * @brief Read one (the next) frame set, including particle mapping and related data blocks
2530 * from the input_file of tng_data.
2531 * @param tng_data is a trajectory data container.
2532 * @details tng_data->input_file_path specifies
2533 * which file to read from. If the file (input_file) is not open it will be
2535 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2536 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2537 * compared to the md5 hash of the read contents to ensure valid data.
2538 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2539 * must be initialised before using it.
2540 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2541 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2543 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next
2544 (tng_trajectory_t tng_data,
2545 const char hash_mode);
2548 * @brief Read one (the next) frame set, including particle mapping and data blocks with a
2549 * specific block id from the input_file of tng_data.
2550 * @param tng_data is a trajectory data container.
2551 * @details tng_data->input_file_path specifies
2552 * which file to read from. If the file (input_file) is not open it will be
2554 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2555 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2556 * compared to the md5 hash of the read contents to ensure valid data.
2557 * @param block_id is the ID number of the blocks that should be read from file.
2558 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2559 * must be initialised before using it.
2560 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2561 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2563 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next_only_data_from_block_id
2564 (tng_trajectory_t tng_data,
2565 const char hash_mode,
2566 const int64_t block_id);
2569 * @brief Write one frame set, including mapping and related data blocks
2570 * to the output_file of tng_data.
2571 * @param tng_data is a trajectory data container.
2572 * @details tng_data->output_file_path specifies
2573 * which file to write to. If the file (output_file) is not open it will be
2575 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2576 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
2577 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2578 * must be initialised before using it.
2579 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2580 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2582 tng_function_status DECLSPECDLLEXPORT tng_frame_set_write
2583 (tng_trajectory_t tng_data,
2584 const char hash_mode);
2587 * @brief Write one frame set even if it does not have as many frames as
2588 * expected. The function also writes mapping and related data blocks
2589 * to the output_file of tng_data.
2590 * @param tng_data is a trajectory data container.
2591 * @details tng_data->output_file_path specifies
2592 * which file to write to. If the file (output_file) is not open it will be
2594 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2595 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
2596 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2597 * must be initialised before using it.
2598 * @details The number of frames in the frame set is set to the number of
2599 * frames of the data blocks before writing it to disk.
2600 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2601 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2603 tng_function_status DECLSPECDLLEXPORT tng_frame_set_premature_write
2604 (tng_trajectory_t tng_data,
2605 const char hash_mode);
2608 * @brief Create and initialise a frame set.
2609 * @details Particle mappings are retained from previous frame set (if any).
2610 * To explicitly clear particle mappings use tng_frame_set_particle_mapping_free().
2611 * @param tng_data is the trajectory data container in which to add the frame
2613 * @param first_frame is the first frame of the frame set.
2614 * @param n_frames is the number of frames in the frame set.
2615 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2616 * must be initialised before using it.
2617 * @pre \code first_frame >= 0 \endcode The first frame must not be negative.
2618 * @pre \code n_frames >= 0 \endcode The number of frames must not be negative.
2619 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2620 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2622 tng_function_status DECLSPECDLLEXPORT tng_frame_set_new
2623 (tng_trajectory_t tng_data,
2624 const int64_t first_frame,
2625 const int64_t n_frames);
2628 * @brief Create and initialise a frame set with the time of the first frame
2630 * @param tng_data is the trajectory data container in which to add the frame
2632 * @param first_frame is the first frame of the frame set.
2633 * @param n_frames is the number of frames in the frame set.
2634 * @param first_frame_time is the time stamp of the first frame (in seconds).
2635 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2636 * must be initialised before using it.
2637 * @pre \code first_frame >= 0 \endcode The first frame must not be negative.
2638 * @pre \code n_frames >= 0 \endcode The number of frames must not be negative.
2639 * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame
2640 * must not be negative.
2641 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2642 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2644 tng_function_status DECLSPECDLLEXPORT tng_frame_set_with_time_new
2645 (tng_trajectory_t tng_data,
2646 const int64_t first_frame,
2647 const int64_t n_frames,
2648 const double first_frame_time);
2651 * @brief Set the time stamp of the first frame of the current frame set.
2652 * @param tng_data is the trajectory containing the frame set.
2653 * @param first_frame_time is the time stamp of the first frame in the
2655 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2656 * must be initialised before using it.
2657 * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame
2658 * must not be negative.
2659 * @return TNG_SUCCESS (0) if successful.
2661 tng_function_status DECLSPECDLLEXPORT tng_frame_set_first_frame_time_set
2662 (tng_trajectory_t tng_data,
2663 const double first_frame_time);
2666 * @brief Read the number of the first frame of the next frame set.
2667 * @param tng_data is the trajectory containing the frame set.
2668 * @param frame is set to the frame number of the first frame in the
2670 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2671 * must be initialised before using it.
2672 * @pre \code tng_data->input_file != 0 \endcode An input file must be open
2673 * to find the next frame set.
2674 * @pre \code frame != 0 \endcode The pointer to the frame must not be a NULL
2676 * @return TNG_SUCCESS(0) if successful, TNG_FAILURE(1) if there is no next
2677 * frame set or TNG_CRITICAL(2) if a major error has occured.
2679 tng_function_status DECLSPECDLLEXPORT tng_first_frame_nr_of_next_frame_set_get
2680 (const tng_trajectory_t tng_data,
2684 * @brief Add a non-particle dependent data block.
2685 * @param tng_data is the trajectory data container in which to add the data
2687 * @param id is the block ID of the block to add.
2688 * @param block_name is a descriptive name of the block to add
2689 * @param datatype is the datatype of the data in the block (e.g. int/float)
2690 * @param block_type_flag indicates if this is a non-trajectory block (added
2691 * directly to tng_data) or if it is a trajectory block (added to the
2693 * @param n_frames is the number of frames of the data block (automatically
2694 * set to 1 if adding a non-trajectory data block)
2695 * @param n_values_per_frame is how many values a stored each frame (e.g. 9
2696 * for a box shape block)
2697 * @param stride_length is how many frames are between each entry in the
2699 * @param codec_id is the ID of the codec to compress the data.
2700 * @param new_data is an array of data values to add.
2701 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2702 * must be initialised before using it.
2703 * @pre \code block_name != 0 \endcode The pointer to the block name must
2704 * not be a NULL pointer.
2705 * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be
2706 * a positive integer.
2707 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2708 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2710 tng_function_status DECLSPECDLLEXPORT tng_data_block_add
2711 (tng_trajectory_t tng_data,
2713 const char *block_name,
2714 const char datatype,
2715 const char block_type_flag,
2717 const int64_t n_values_per_frame,
2718 int64_t stride_length,
2719 const int64_t codec_id,
2723 * @brief Add a particle dependent data block.
2724 * @param tng_data is the trajectory data container in which to add the data
2726 * @param id is the block ID of the block to add.
2727 * @param block_name is a descriptive name of the block to add
2728 * @param datatype is the datatype of the data in the block (e.g. int/float)
2729 * @param block_type_flag indicates if this is a non-trajectory block (added
2730 * directly to tng_data) or if it is a trajectory block (added to the
2732 * @param n_frames is the number of frames of the data block (automatically
2733 * set to 1 if adding a non-trajectory data block)
2734 * @param n_values_per_frame is how many values a stored each frame (e.g. 9
2735 * for a box shape block)
2736 * @param stride_length is how many frames are between each entry in the
2738 * @param num_first_particle is the number of the first particle stored
2739 * in this data block
2740 * @param n_particles is the number of particles stored in this data block
2741 * @param codec_id is the ID of the codec to compress the data.
2742 * @param new_data is an array of data values to add.
2743 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2744 * must be initialised before using it.
2745 * @pre \code block_name != 0 \endcode The pointer to the block name must
2746 * not be a NULL pointer.
2747 * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be
2748 * a positive integer.
2749 * @pre \code num_first_particle >= 0 \endcode The number of the
2750 * first particle must be >= 0.
2751 * @pre \code n_particles >= 0 \endcode n_particles must be >= 0.
2752 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2753 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2755 tng_function_status DECLSPECDLLEXPORT tng_particle_data_block_add
2756 (tng_trajectory_t tng_data,
2758 const char *block_name,
2759 const char datatype,
2760 const char block_type_flag,
2762 const int64_t n_values_per_frame,
2763 int64_t stride_length,
2764 const int64_t num_first_particle,
2765 const int64_t n_particles,
2766 const int64_t codec_id,
2769 /** @brief Get the name of a data block of a specific ID.
2770 * @param tng_data is the trajectory data container.
2771 * @param block_id is the ID of the data block of which to get the name.
2772 * @param name is a string, which is set to the name of the data block.
2773 * Memory must be reserved beforehand.
2774 * @param max_len is the maximum length of name.
2775 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2776 * must be initialised before using it.
2777 * @pre \code name != 0 \endcode The pointer to the name string
2778 * must not be a NULL pointer.
2779 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1)
2780 * if a minor error has occured or the data block is not found or
2781 * TNG_CRITICAL (2) if a major error has occured.
2783 tng_function_status DECLSPECDLLEXPORT tng_data_block_name_get
2784 (tng_trajectory_t tng_data,
2789 /** @brief Get the dependency of a data block of a specific ID.
2790 * @param tng_data is the trajectory data container.
2791 * @param block_id is the ID of the data block of which to get the name.
2792 * @param block_dependency is a pointer to the dependency of the data block.
2793 * If the block is frame dependent it will be set to TNG_FRAME_DEPENDENT,
2794 * if it is particle dependent it will be set to TNG_PARTICLE_DEPENDENT and
2795 * if it is both it will be set to TNG_FRAME_DEPENDENT & TNG_PARTICLE_DEPENDENT.
2796 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2797 * must be initialised before using it.
2798 * @pre \code block_dependency != 0 \endcode The pointer to the block dependency
2799 * must not be a NULL pointer.
2800 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1)
2801 * if a minor error has occured or the data block is not found or
2802 * TNG_CRITICAL (2) if a major error has occured.
2804 tng_function_status DECLSPECDLLEXPORT tng_data_block_dependency_get
2805 (const tng_trajectory_t tng_data,
2807 int *block_dependency);
2809 /** @brief Get the number of values per frame of a data block of a specific ID.
2810 * @param tng_data is the trajectory data container.
2811 * @param block_id is the ID of the data block of which to get the name.
2812 * @param n_values_per_frame is a pointer set to the number of values per frame.
2813 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2814 * must be initialised before using it.
2815 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of values
2816 * per frame must not be a NULL pointer.
2817 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1)
2818 * if a minor error has occured or the data block is not found or
2819 * TNG_CRITICAL (2) if a major error has occured.
2821 tng_function_status DECLSPECDLLEXPORT tng_data_block_num_values_per_frame_get
2822 (const tng_trajectory_t tng_data,
2824 int64_t *n_values_per_frame);
2827 * @brief Write data of one trajectory frame to the output_file of tng_data.
2828 * @param tng_data is a trajectory data container. tng_data->output_file_path
2829 * specifies which file to write to. If the file (output_file) is not open it
2831 * @param frame_nr is the index number of the frame to write.
2832 * @param block_id is the ID of the data block to write the data to.
2833 * @param values is an array of data to write. The length of the array should
2834 * equal n_values_per_frame.
2835 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2836 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2837 * compared to the md5 hash of the read contents to ensure valid data.
2838 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2839 * must be initialised before using it.
2840 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
2841 * @pre \code values != 0 \endcode The pointer to the values must not be a NULL
2843 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2844 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2846 tng_function_status DECLSPECDLLEXPORT tng_frame_data_write
2847 (tng_trajectory_t tng_data,
2848 const int64_t frame_nr,
2849 const int64_t block_id,
2851 const char hash_mode);
2854 * @brief Write particle data of one trajectory frame to the output_file of
2856 * @param tng_data is a trajectory data container. tng_data->output_file_path
2857 * specifies which file to write to. If the file (output_file) is not open it
2859 * @param frame_nr is the index number of the frame to write.
2860 * @param block_id is the ID of the data block to write the data to.
2861 * @param val_first_particle is the number of the first particle in the data
2863 * @param val_n_particles is the number of particles in the data array.
2864 * @param values is a 1D-array of data to write. The length of the array should
2865 * equal n_particles * n_values_per_frame.
2866 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2867 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2868 * compared to the md5 hash of the read contents to ensure valid data.
2869 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2870 * must be initialised before using it.
2871 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
2872 * @pre \code val_first_particle >= 0 \endcode The number of the
2873 * first particle must be >= 0.
2874 * @pre \code val_n_particles >= 0 \endcode The number of particles must be >= 0.
2875 * @pre \code values != 0 \endcode The pointer to the values must not be a NULL
2877 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2878 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2880 tng_function_status DECLSPECDLLEXPORT tng_frame_particle_data_write
2881 (tng_trajectory_t tng_data,
2882 const int64_t frame_nr,
2883 const int64_t block_id,
2884 const int64_t val_first_particle,
2885 const int64_t val_n_particles,
2887 const char hash_mode);
2890 * @brief Free data of an array of values (2D).
2891 * @param tng_data is a trajectory data container.
2892 * @param values is the 2D array to free and will be set to 0 afterwards.
2893 * @param n_frames is the number of frames in the data array.
2894 * @param n_values_per_frame is the number of values per frame in the data array.
2895 * @param type is the data type of the data in the array (e.g. int/float/char).
2896 * @return TNG_SUCCESS (0) if successful.
2898 tng_function_status DECLSPECDLLEXPORT tng_data_values_free
2899 (const tng_trajectory_t tng_data,
2900 union data_values **values,
2901 const int64_t n_frames,
2902 const int64_t n_values_per_frame,
2906 * @brief Free data of an array of values (3D).
2907 * @param tng_data is a trajectory data container.
2908 * @param values is the array to free and will be set to 0 afterwards.
2909 * @param n_frames is the number of frames in the data array.
2910 * @param n_particles is the number of particles in the data array.
2911 * @param n_values_per_frame is the number of values per frame in the data array.
2912 * @param type is the data type of the data in the array (e.g. int/float/char).
2913 * @return TNG_SUCCESS (0) if successful.
2915 tng_function_status DECLSPECDLLEXPORT tng_particle_data_values_free
2916 (const tng_trajectory_t tng_data,
2917 union data_values ***values,
2918 const int64_t n_frames,
2919 const int64_t n_particles,
2920 const int64_t n_values_per_frame,
2924 * @brief Retrieve non-particle data, from the last read frame set. Obsolete!
2925 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
2926 * which file to read from. If the file (input_file) is not open it will be
2928 * @param block_id is the id number of the particle data block to read.
2929 * @param values is a pointer to a 2-dimensional array (memory unallocated), which
2930 * will be filled with data. The array will be sized
2931 * (n_frames * n_values_per_frame).
2932 * Since ***values is allocated in this function it is the callers
2933 * responsibility to free the memory.
2934 * @param n_frames is set to the number of frames in the returned data. This is
2935 * needed to properly reach and/or free the data afterwards.
2936 * @param n_values_per_frame is set to the number of values per frame in the data.
2937 * This is needed to properly reach and/or free the data afterwards.
2938 * @param type is set to the data type of the data in the array.
2939 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2940 * must be initialised before using it.
2941 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
2942 * must not be a NULL pointer.
2943 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
2944 * values per frame must not be a NULL pointer.
2945 * @pre \code type != 0 \endcode The pointer to the data type must not
2946 * be a NULL pointer.
2947 * @details This function is obsolete and only retained for compatibility. Use
2948 * tng_data_vector_get() instead.
2949 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2950 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2952 tng_function_status DECLSPECDLLEXPORT tng_data_get(tng_trajectory_t tng_data,
2953 const int64_t block_id,
2954 union data_values ***values,
2956 int64_t *n_values_per_frame,
2960 * @brief Retrieve a vector (1D array) of non-particle data, from the last read frame set.
2961 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
2962 * which file to read from. If the file (input_file) is not open it will be
2964 * @param block_id is the id number of the particle data block to read.
2965 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
2966 * will be filled with data. The length of the array will be (n_frames * n_values_per_frame).
2967 * Since **values is allocated in this function it is the callers
2968 * responsibility to free the memory.
2969 * @param n_frames is set to the number of particles in the returned data. This is
2970 * needed to properly reach and/or free the data afterwards.
2971 * @param stride_length is set to the stride length of the returned data.
2972 * @param n_values_per_frame is set to the number of values per frame in the data.
2973 * This is needed to properly reach and/or free the data afterwards.
2974 * @param type is set to the data type of the data in the array.
2975 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2976 * must be initialised before using it.
2977 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
2978 * must not be a NULL pointer.
2979 * @pre \code stride_length != 0 \endcode The pointer to the stride length
2980 * must not be a NULL pointer.
2981 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
2982 * values per frame must not be a NULL pointer.
2983 * @pre \code type != 0 \endcode The pointer to the data type must not
2984 * be a NULL pointer.
2985 * @details This does only work for numerical (int, float, double) data.
2986 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2987 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2989 tng_function_status DECLSPECDLLEXPORT tng_data_vector_get
2990 (tng_trajectory_t tng_data,
2991 const int64_t block_id,
2994 int64_t *stride_length,
2995 int64_t *n_values_per_frame,
2999 * @brief Read and retrieve non-particle data, in a specific interval. Obsolete!
3000 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
3001 * which file to read from. If the file (input_file) is not open it will be
3003 * @param block_id is the id number of the particle data block to read.
3004 * @param start_frame_nr is the index number of the first frame to read.
3005 * @param end_frame_nr is the index number of the last frame to read.
3006 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3007 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3008 * compared to the md5 hash of the read contents to ensure valid data.
3009 * @param values is a pointer to a 2-dimensional array (memory unallocated), which
3010 * will be filled with data. The array will be sized
3011 * (n_frames * n_values_per_frame).
3012 * Since ***values is allocated in this function it is the callers
3013 * responsibility to free the memory.
3014 * @param n_values_per_frame is set to the number of values per frame in the data.
3015 * This is needed to properly reach and/or free the data afterwards.
3016 * @param type is set to the data type of the data in the array.
3017 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3018 * must be initialised before using it.
3019 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3021 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3022 * values per frame must not be a NULL pointer.
3023 * @pre \code type != 0 \endcode The pointer to the data type must not
3024 * be a NULL pointer.
3025 * @details This function is obsolete and only retained for compatibility. Use
3026 * tng_data_vector_interval_get() instead.
3027 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3028 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3030 tng_function_status DECLSPECDLLEXPORT tng_data_interval_get
3031 (tng_trajectory_t tng_data,
3032 const int64_t block_id,
3033 const int64_t start_frame_nr,
3034 const int64_t end_frame_nr,
3035 const char hash_mode,
3036 union data_values ***values,
3037 int64_t *n_values_per_frame,
3041 * @brief Read and retrieve a vector (1D array) of non-particle data,
3042 * in a specific interval.
3043 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
3044 * which file to read from. If the file (input_file) is not open it will be
3046 * @param block_id is the id number of the particle data block to read.
3047 * @param start_frame_nr is the index number of the first frame to read.
3048 * @param end_frame_nr is the index number of the last frame to read.
3049 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3050 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3051 * compared to the md5 hash of the read contents to ensure valid data.
3052 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
3053 * will be filled with data. The length of the array will be (n_frames * n_values_per_frame).
3054 * Since **values is allocated in this function it is the callers
3055 * responsibility to free the memory.
3056 * @param stride_length is set to the stride length (writing interval) of
3058 * @param n_values_per_frame is set to the number of values per frame in the data.
3059 * This is needed to properly reach and/or free the data afterwards.
3060 * @param type is set to the data type of the data in the array.
3061 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3062 * must be initialised before using it.
3063 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3065 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3066 * must not be a NULL pointer.
3067 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3068 * values per frame must not be a NULL pointer.
3069 * @pre \code type != 0 \endcode The pointer to the data type must not
3070 * be a NULL pointer.
3071 * @details This does only work for numerical (int, float, double) data.
3072 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3073 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3075 tng_function_status DECLSPECDLLEXPORT tng_data_vector_interval_get
3076 (tng_trajectory_t tng_data,
3077 const int64_t block_id,
3078 const int64_t start_frame_nr,
3079 const int64_t end_frame_nr,
3080 const char hash_mode,
3082 int64_t *stride_length,
3083 int64_t *n_values_per_frame,
3087 * @brief Retrieve particle data, from the last read frame set. Obsolete!
3088 * @details The particle dimension of the returned values array is translated
3089 * to real particle numbering, i.e. the numbering of the actual molecular
3091 * @param tng_data is a trajectory data container. tng_data->input_file_path
3092 * specifies which file to read from. If the file (input_file) is not open it
3094 * @param block_id is the id number of the particle data block to read.
3095 * @param values is a pointer to a 3-dimensional array (memory unallocated), which
3096 * will be filled with data. The array will be sized
3097 * (n_frames * n_particles * n_values_per_frame).
3098 * Since ****values is allocated in this function it is the callers
3099 * responsibility to free the memory.
3100 * @param n_frames is set to the number of frames in the returned data. This is
3101 * needed to properly reach and/or free the data afterwards.
3102 * @param n_particles is set to the number of particles in the returned data. This is
3103 * needed to properly reach and/or free the data afterwards.
3104 * @param n_values_per_frame is set to the number of values per frame in the data.
3105 * This is needed to properly reach and/or free the data afterwards.
3106 * @param type is set to the data type of the data in the array.
3107 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3108 * must be initialised before using it.
3109 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
3110 * must not be a NULL pointer.
3111 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3112 * not be a NULL pointer.
3113 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3114 * values per frame must not be a NULL pointer.
3115 * @pre \code type != 0 \endcode The pointer to the data type must not
3116 * be a NULL pointer.
3117 * @details This function is obsolete and only retained for compatibility. Use
3118 * tng_particle_data_vector_get() instead.
3119 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3120 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3122 tng_function_status DECLSPECDLLEXPORT tng_particle_data_get
3123 (tng_trajectory_t tng_data,
3124 const int64_t block_id,
3125 union data_values ****values,
3127 int64_t *n_particles,
3128 int64_t *n_values_per_frame,
3132 * @brief Retrieve a vector (1D array) of particle data, from the last read frame set.
3133 * @details The particle dimension of the returned values array is translated
3134 * to real particle numbering, i.e. the numbering of the actual molecular
3136 * @param tng_data is a trajectory data container. tng_data->input_file_path
3137 * specifies which file to read from. If the file (input_file) is not open it
3139 * @param block_id is the id number of the particle data block to read.
3140 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
3141 * will be filled with data. The length of the array will be
3142 * (n_frames * n_particles * n_values_per_frame).
3143 * Since **values is allocated in this function it is the callers
3144 * responsibility to free the memory.
3145 * @param n_frames is set to the number of frames in the returned data. This is
3146 * needed to properly reach and/or free the data afterwards.
3147 * @param stride_length is set to the stride length of the returned data.
3148 * @param n_particles is set to the number of particles in the returned data. This is
3149 * needed to properly reach and/or free the data afterwards.
3150 * @param n_values_per_frame is set to the number of values per frame in the data.
3151 * This is needed to properly reach and/or free the data afterwards.
3152 * @param type is set to the data type of the data in the array.
3153 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3154 * must be initialised before using it.
3155 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3156 * not be a NULL pointer.
3157 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3158 * must not be a NULL pointer.
3159 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3160 * values per frame must not be a NULL pointer.
3161 * @pre \code type != 0 \endcode The pointer to the data type must not
3162 * be a NULL pointer.
3163 * @details This does only work for numerical (int, float, double) data.
3164 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3165 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3167 tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_get
3168 (tng_trajectory_t tng_data,
3169 const int64_t block_id,
3172 int64_t *stride_length,
3173 int64_t *n_particles,
3174 int64_t *n_values_per_frame,
3178 * @brief Read and retrieve particle data, in a specific interval. Obsolete!
3179 * @details The particle dimension of the returned values array is translated
3180 * to real particle numbering, i.e. the numbering of the actual molecular
3182 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
3183 * which file to read from. If the file (input_file) is not open it will be
3185 * @param block_id is the id number of the particle data block to read.
3186 * @param start_frame_nr is the index number of the first frame to read.
3187 * @param end_frame_nr is the index number of the last frame to read.
3188 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3189 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3190 * compared to the md5 hash of the read contents to ensure valid data.
3191 * @param values is a pointer to a 3-dimensional array (memory unallocated), which
3192 * will be filled with data. The array will be sized
3193 * (n_frames * n_particles * n_values_per_frame).
3194 * Since ****values is allocated in this function it is the callers
3195 * responsibility to free the memory.
3196 * @param n_particles is set to the number of particles in the returned data. This is
3197 * needed to properly reach and/or free the data afterwards.
3198 * @param n_values_per_frame is set to the number of values per frame in the data.
3199 * This is needed to properly reach and/or free the data afterwards.
3200 * @param type is set to the data type of the data in the array.
3201 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3202 * must be initialised before using it.
3203 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
3204 * must not be a NULL pointer.
3205 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3207 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3208 * not be a NULL pointer.
3209 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3210 * values per frame must not be a NULL pointer.
3211 * @pre \code type != 0 \endcode The pointer to the data type must not
3212 * be a NULL pointer.
3213 * @details This function is obsolete and only retained for compatibility. Use
3214 * tng_particle_data_vector_interval_get() instead.
3215 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3216 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3218 tng_function_status DECLSPECDLLEXPORT tng_particle_data_interval_get
3219 (tng_trajectory_t tng_data,
3220 const int64_t block_id,
3221 const int64_t start_frame_nr,
3222 const int64_t end_frame_nr,
3223 const char hash_mode,
3224 union data_values ****values,
3225 int64_t *n_particles,
3226 int64_t *n_values_per_frame,
3230 * @brief Read and retrieve a vector (1D array) particle data, in a
3231 * specific interval.
3232 * @details The particle dimension of the returned values array is translated
3233 * to real particle numbering, i.e. the numbering of the actual molecular
3235 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
3236 * which file to read from. If the file (input_file) is not open it will be
3238 * @param block_id is the id number of the particle data block to read.
3239 * @param start_frame_nr is the index number of the first frame to read.
3240 * @param end_frame_nr is the index number of the last frame to read.
3241 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3242 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3243 * compared to the md5 hash of the read contents to ensure valid data.
3244 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
3245 * will be filled with data. The length of the array will be
3246 * (n_frames * n_particles * n_values_per_frame).
3247 * Since **values is allocated in this function it is the callers
3248 * responsibility to free the memory.
3249 * @param stride_length is set to the stride length (writing interval) of
3251 * @param n_particles is set to the number of particles in the returned data. This is
3252 * needed to properly reach and/or free the data afterwards.
3253 * @param n_values_per_frame is set to the number of values per frame in the data.
3254 * This is needed to properly reach and/or free the data afterwards.
3255 * @param type is set to the data type of the data in the array.
3256 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3257 * must be initialised before using it.
3258 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3260 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3261 * not be a NULL pointer.
3262 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3263 * must not be a NULL pointer.
3264 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3265 * values per frame must not be a NULL pointer.
3266 * @pre \code type != 0 \endcode The pointer to the data type must not
3267 * be a NULL pointer.
3268 * @details This does only work for numerical (int, float, double) data.
3269 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3270 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3272 tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_interval_get
3273 (tng_trajectory_t tng_data,
3274 const int64_t block_id,
3275 const int64_t start_frame_nr,
3276 const int64_t end_frame_nr,
3277 const char hash_mode,
3279 int64_t *n_particles,
3280 int64_t *stride_length,
3281 int64_t *n_values_per_frame,
3285 * @brief Get the stride length of a specific data (particle dependency does not matter)
3286 * block, either in the current frame set or of a specific frame.
3287 * @param tng_data is the trajectory data container.
3288 * @param block_id is the block ID of the data block, of which to retrieve the
3289 * stride length of the data.
3290 * @param frame is the frame from which to get the stride length. If frame is set to -1
3291 * no specific frame will be used, but instead the first frame, starting from the last read
3292 * frame set, containing the data block will be used.
3293 * @param stride_length is set to the value of the stride length of the data block.
3294 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3295 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3297 tng_function_status DECLSPECDLLEXPORT tng_data_get_stride_length
3298 (const tng_trajectory_t tng_data,
3299 const int64_t block_id,
3301 int64_t *stride_length);
3304 * @brief Get the date and time of initial file creation in ISO format (string).
3305 * @param tng_data is a trajectory data container.
3306 * @param time is a pointer to the string in which the date will be stored. Memory
3307 * must be reserved beforehand.
3308 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3309 * must be initialised before using it.
3310 * @pre \code time != 0 \endcode The pointer to the time must not be a NULL
3312 * @return TNG_SUCCESS (0) if successful.
3314 tng_function_status DECLSPECDLLEXPORT tng_time_get_str
3315 (const tng_trajectory_t tng_data,
3317 /** @} */ /* end of group1 */
3319 /** @defgroup group2 High-level API
3320 * These functions make it easier to access and output TNG data. They
3321 * are recommended unless there is a special reason to use the more
3322 * detailed functions available in the low-level API.
3327 * @brief High-level function for opening and initializing a TNG trajectory.
3328 * @param filename is a string containing the name of the trajectory to open.
3329 * @param mode specifies the file mode of the trajectory. Can be set to 'r',
3330 * 'w' or 'a' for reading, writing or appending respectively.
3331 * @param tng_data_p is a pointer to the opened trajectory. This will be
3332 * allocated by the TNG library. The trajectory must be
3333 * closed by the user, whereby memory is freed.
3334 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3335 * must be initialised before using it.
3336 * @pre \code filename != 0 \endcode The pointer to the filename must not be a
3338 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3339 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3342 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_open
3343 (const char *filename,
3345 tng_trajectory_t *tng_data_p);
3348 * @brief High-level function for closing a TNG trajectory.
3349 * @param tng_data_p is a pointer to the trajectory to close. The memory
3350 * will be freed after finalising the writing.
3351 * @return TNG_SUCCESS (0) if successful.
3353 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_close
3354 (tng_trajectory_t *tng_data_p);
3357 * @brief High-level function for getting the time (in seconds) of a frame.
3358 * @param tng_data is the trajectory containing the frame.
3359 * @param frame_nr is the frame number of which to get the time.
3360 * @param time is set to the time (in seconds) of the specified frame.
3361 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3362 * must be initialised before using it.
3363 * @pre \code time != 0 \endcode The pointer to the time must not be a
3365 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if a
3366 * minor error has occured.
3368 tng_function_status DECLSPECDLLEXPORT tng_util_time_of_frame_get
3369 (tng_trajectory_t tng_data,
3370 const int64_t frame_nr,
3374 * @brief High-level function for getting the molecules in the mol system.
3375 * @param tng_data is the trajectory containing the mol system.
3376 * @param n_mols is set to the number of molecules in the system.
3377 * @param molecule_cnt_list will be pointing to the list of counts of each molecule
3378 * in the mol system.
3379 * @param mols pointing to the list of molecules in the mol system.
3380 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3381 * must be initialised before using it.
3382 * @pre \code n_mols != 0 \endcode The pointer to the number of molecules must
3383 * not be a NULL pointer.
3384 * @return TNG_SUCCESS (0) if successful.
3386 /*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecules_get
3387 (tng_trajectory_t tng_data,
3389 int64_t **molecule_cnt_list,
3390 tng_molecule_t *mols);
3393 * @brief High-level function for adding a molecule to the mol system.
3394 * @param tng_data is the trajectory containing the mol system.
3395 * @param name is the name of the molecule to add.
3396 * @param cnt is the count of the molecule.
3397 * @param mol is set to point to the newly created molecule.
3398 * @pre \code name != 0 \endcode The pointer to the name must not be a
3400 * @pre \code cnt >= 0 \endcode The requested count must be >= 0.
3401 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3402 * has occured or TNG_CRITICAL (2) if a major error has occured.
3404 /*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecule_add
3405 (tng_trajectory_t tng_data,
3408 tng_molecule_t *mol);
3411 // tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_get
3412 // (tng_trajectory_t tng_data,
3413 // const tng_molecule_t mol,
3414 // int64_t *n_particles,
3417 // char ***res_names,
3418 // int64_t **res_ids,
3419 // char ***chain_names,
3420 // int64_t **chain_ids);
3422 // tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_set
3423 // (tng_trajectory_t tng_data,
3424 // tng_molecule_t mol,
3425 // const int64_t n_particles,
3426 // const char **names,
3427 // const char **types,
3428 // const char **res_names,
3429 // const int64_t *res_ids,
3430 // const char **chain_names,
3431 // const int64_t *chain_ids);
3434 * @brief High-level function for reading the positions of all particles
3436 * @param tng_data is the trajectory to read from.
3437 * @param positions will be set to point at a 1-dimensional array of floats,
3438 * which will contain the positions. The data is stored sequentially in order
3439 * of frames. For each frame the positions (x, y and z coordinates) are stored.
3440 * The variable may point at already allocated memory or be a NULL pointer.
3441 * The memory must be freed afterwards.
3442 * @param stride_length will be set to the writing interval of the stored data.
3443 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3444 * must be initialised before using it.
3445 * @pre \code positions != 0 \endcode The pointer to the positions array
3446 * must not be a NULL pointer.
3447 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3448 * must not be a NULL pointer.
3449 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3450 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3453 tng_function_status DECLSPECDLLEXPORT tng_util_pos_read
3454 (tng_trajectory_t tng_data,
3456 int64_t *stride_length);
3459 * @brief High-level function for reading the velocities of all particles
3461 * @param tng_data is the trajectory to read from.
3462 * @param velocities will be set to point at a 1-dimensional array of floats,
3463 * which will contain the velocities. The data is stored sequentially in order
3464 * of frames. For each frame the velocities (in x, y and z) are stored. The
3465 * variable may point at already allocated memory or be a NULL pointer.
3466 * The memory must be freed afterwards.
3467 * @param stride_length will be set to the writing interval of the stored data.
3468 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3469 * must be initialised before using it.
3470 * @pre \code velocities != 0 \endcode The pointer to the velocities array
3471 * must not be a NULL pointer.
3472 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3473 * must not be a NULL pointer.
3474 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3475 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3478 tng_function_status DECLSPECDLLEXPORT tng_util_vel_read
3479 (tng_trajectory_t tng_data,
3481 int64_t *stride_length);
3484 * @brief High-level function for reading the forces of all particles
3486 * @param tng_data is the trajectory to read from.
3487 * @param forces will be set to point at a 1-dimensional array of floats,
3488 * which will contain the forces. The data is stored sequentially in order
3489 * of frames. For each frame the forces (in x, y and z) are stored. The
3490 * variable may point at already allocated memory or be a NULL pointer.
3491 * The memory must be freed afterwards.
3492 * @param stride_length will be set to the writing interval of the stored data.
3493 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3494 * must be initialised before using it.
3495 * @pre \code forces != 0 \endcode The pointer to the forces array
3496 * must not be a NULL pointer.
3497 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3498 * must not be a NULL pointer.
3499 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3500 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3503 tng_function_status DECLSPECDLLEXPORT tng_util_force_read
3504 (tng_trajectory_t tng_data,
3506 int64_t *stride_length);
3509 * @brief High-level function for reading the box shape from all frames.
3510 * @param tng_data is the trajectory to read from.
3511 * @param box_shape will be set to point at a 1-dimensional array of floats,
3512 * which will contain the box shape. The data is stored sequentially in order
3513 * of frames. The variable may point at already allocated memory or be a NULL pointer.
3514 * If the box shape is not modified during the trajectory, but as general data,
3515 * that will be returned instead.
3516 * @param stride_length will be set to the writing interval of the stored data.
3517 * @details This function should only be used if number of values used to specify
3518 * the box shape is known (by default TNG uses 9 values) since it does not
3519 * return the number of values in the array. It is recommended to use
3520 * tng_data_vector_interval_get() instead.
3521 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3522 * must be initialised before using it.
3523 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array
3524 * must not be a NULL pointer.
3525 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3526 * must not be a NULL pointer.
3527 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3528 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3531 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read
3532 (tng_trajectory_t tng_data,
3534 int64_t *stride_length);
3537 * @brief High-level function for reading the next frame of particle-dependent
3538 * data of a specific type.
3539 * @param tng_data is the trajectory to read from.
3540 * @param block_id is the ID number of the block containing the data of interest.
3541 * @param values will be set to point at a 1-dimensional array containing the
3542 * requested data. The variable may point at already allocated memory or be a
3543 * NULL pointer. The memory must be freed afterwards.
3544 * @param data_type will be pointing to a character indicating the size of the
3545 * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA.
3546 * @param retrieved_frame_number will be pointing at the frame number of the
3548 * @param retrieved_time will be pointing at the time stamp of the returned
3550 * @details If no frame has been read before the first frame of the trajectory
3552 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3553 * must be initialised before using it.
3554 * @pre \code values != 0 \endcode The pointer to the values array
3555 * must not be a NULL pointer.
3556 * @pre \code data_type != 0 \endcode The pointer to the data type of the
3557 * returned data must not be a NULL pointer.
3558 * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame
3559 * number of the returned data must not be a NULL pointer.
3560 * @pre \code retrieved_time != 0 \endcode The pointer to the time of the
3561 * returned data must not be a NULL pointer.
3562 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3563 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3566 tng_function_status DECLSPECDLLEXPORT tng_util_particle_data_next_frame_read
3567 (tng_trajectory_t tng_data,
3568 const int64_t block_id,
3571 int64_t *retrieved_frame_number,
3572 double *retrieved_time);
3575 * @brief High-level function for reading the next frame of non-particle-dependent
3576 * data of a specific type.
3577 * @param tng_data is the trajectory to read from.
3578 * @param block_id is the ID number of the block containing the data of interest.
3579 * @param values will be set to point at a 1-dimensional array containing the
3580 * requested data. The variable may point at already allocated memory or be a
3581 * NULL pointer. The memory must be freed afterwards.
3582 * @param data_type will be pointing to a character indicating the size of the
3583 * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA.
3584 * @param retrieved_frame_number will be pointing at the frame number of the
3586 * @param retrieved_time will be pointing at the time stamp of the returned
3588 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3589 * must be initialised before using it.
3590 * @pre \code values != 0 \endcode The pointer to the values array
3591 * must not be a NULL pointer.
3592 * @pre \code data_type != 0 \endcode The pointer to the data type of the
3593 * returned data must not be a NULL pointer.
3594 * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame
3595 * number of the returned data must not be a NULL pointer.
3596 * @pre \code retrieved_time != 0 \endcode The pointer to the time of the
3597 * returned data must not be a NULL pointer.
3598 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3599 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3602 tng_function_status DECLSPECDLLEXPORT tng_util_non_particle_data_next_frame_read
3603 (tng_trajectory_t tng_data,
3604 const int64_t block_id,
3607 int64_t *retrieved_frame_number,
3608 double *retrieved_time);
3611 * @brief High-level function for reading the positions of all particles
3612 * from a specific range of frames.
3613 * @param tng_data is the trajectory to read from.
3614 * @param first_frame is the first frame to return position data from.
3615 * @param last_frame is the last frame to return position data from.
3616 * @param positions will be set to point at a 1-dimensional array of floats,
3617 * which will contain the positions. The data is stored sequentially in order
3618 * of frames. For each frame the positions (x, y and z coordinates) are stored.
3619 * The variable may point at already allocated memory or be a NULL pointer.
3620 * The memory must be freed afterwards.
3621 * @param stride_length will be set to the writing interval of the stored data.
3622 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3623 * must be initialised before using it.
3624 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3626 * @pre \code positions != 0 \endcode The pointer to the positions array
3627 * must not be a NULL pointer.
3628 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3629 * must not be a NULL pointer.
3630 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3631 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3634 tng_function_status DECLSPECDLLEXPORT tng_util_pos_read_range
3635 (tng_trajectory_t tng_data,
3636 const int64_t first_frame,
3637 const int64_t last_frame,
3639 int64_t *stride_length);
3642 * @brief High-level function for reading the velocities of all particles
3643 * from a specific range of frames.
3644 * @param tng_data is the trajectory to read from.
3645 * @param first_frame is the first frame to return position data from.
3646 * @param last_frame is the last frame to return position data from.
3647 * @param velocities will be set to point at a 1-dimensional array of floats,
3648 * which will contain the velocities. The data is stored sequentially in order
3649 * of frames. For each frame the velocities (in x, y and z) are stored. The
3650 * variable may point at already allocated memory or be a NULL pointer.
3651 * The memory must be freed afterwards.
3652 * @param stride_length will be set to the writing interval of the stored data.
3653 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3654 * must be initialised before using it.
3655 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3657 * @pre \code velocities != 0 \endcode The pointer to the velocities array
3658 * must not be a NULL pointer.
3659 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3660 * must not be a NULL pointer.
3661 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3662 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3665 tng_function_status DECLSPECDLLEXPORT tng_util_vel_read_range
3666 (tng_trajectory_t tng_data,
3667 const int64_t first_frame,
3668 const int64_t last_frame,
3670 int64_t *stride_length);
3673 * @brief High-level function for reading the forces of all particles
3674 * from a specific range of frames.
3675 * @param tng_data is the trajectory to read from.
3676 * @param first_frame is the first frame to return position data from.
3677 * @param last_frame is the last frame to return position data from.
3678 * @param forces will be set to point at a 1-dimensional array of floats,
3679 * which will contain the forces. The data is stored sequentially in order
3680 * of frames. For each frame the forces (in x, y and z) are stored. The
3681 * variable may point at already allocated memory or be a NULL pointer.
3682 * The memory must be freed afterwards.
3683 * @param stride_length will be set to the writing interval of the stored data.
3684 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3685 * must be initialised before using it.
3686 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3688 * @pre \code forces != 0 \endcode The pointer to the forces array
3689 * must not be a NULL pointer.
3690 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3691 * must not be a NULL pointer.
3692 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3693 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3696 tng_function_status DECLSPECDLLEXPORT tng_util_force_read_range
3697 (tng_trajectory_t tng_data,
3698 const int64_t first_frame,
3699 const int64_t last_frame,
3701 int64_t *stride_length);
3704 * @brief High-level function for reading the box shape
3705 * from a specific range of frames.
3706 * @param tng_data is the trajectory to read from.
3707 * @param first_frame is the first frame to return position data from.
3708 * @param last_frame is the last frame to return position data from.
3709 * @param box_shape will be set to point at a 1-dimensional array of floats,
3710 * which will contain the box shape. The data is stored sequentially in order
3712 * If the box shape is not modified during the trajectory, but as general data,
3713 * that will be returned instead. The
3714 * variable may point at already allocated memory or be a NULL pointer.
3715 * The memory must be freed afterwards.
3716 * @param stride_length will be set to the writing interval of the stored data.
3717 * @details This function should only be used if number of values used to specify
3718 * the box shape is known (by default TNG uses 9 values) since it does not
3719 * return the number of values in the array. It is recommended to use
3720 * tng_data_vector_interval_get() instead.
3721 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3722 * must be initialised before using it.
3723 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3725 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array
3726 * must not be a NULL pointer.
3727 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3728 * must not be a NULL pointer.
3729 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3730 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3733 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read_range
3734 (tng_trajectory_t tng_data,
3735 const int64_t first_frame,
3736 const int64_t last_frame,
3738 int64_t *stride_length);
3741 * @brief High-level function for setting the writing interval of data blocks.
3742 * @param tng_data is the trajectory to use.
3743 * @param i is the output interval, i.e. i == 10 means data written every 10th
3745 * @param n_values_per_frame is the number of values to store per frame. If the
3746 * data is particle dependent there will be n_values_per_frame stored per
3747 * particle each frame.
3748 * @param block_id is the ID of the block, of which to set the output interval.
3749 * @param block_name is a string that will be used as name of the block. Only
3750 * required if the block did not exist, i.e. a new block is created.
3751 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
3752 * data is not related to specific particles (e.g. box shape) or
3753 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
3754 * positions). Only required if the block did not exist, i.e. a new block is
3756 * @param compression is the compression routine to use when writing the data.
3757 * Only required if the block did not exist, i.e. a new block is created.
3758 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3759 * must be initialised before using it.
3760 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3761 * @details n_values_per_frame, block_name, particle_dependency and
3762 * compression are only used if the data block did not exist before calling
3763 * this function, in which case it is created.
3764 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3765 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3768 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_set
3769 (tng_trajectory_t tng_data,
3771 const int64_t n_values_per_frame,
3772 const int64_t block_id,
3773 const char *block_name,
3774 const char particle_dependency,
3775 const char compression);
3778 * @brief High-level function for setting the writing interval of data blocks
3779 * containing double precision data.
3780 * @param tng_data is the trajectory to use.
3781 * @param i is the output interval, i.e. i == 10 means data written every 10th
3783 * @param n_values_per_frame is the number of values to store per frame. If the
3784 * data is particle dependent there will be n_values_per_frame stored per
3785 * particle each frame.
3786 * @param block_id is the ID of the block, of which to set the output interval.
3787 * @param block_name is a string that will be used as name of the block. Only
3788 * required if the block did not exist, i.e. a new block is created.
3789 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
3790 * data is not related to specific particles (e.g. box shape) or
3791 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
3792 * positions). Only required if the block did not exist, i.e. a new block is
3794 * @param compression is the compression routine to use when writing the data.
3795 * Only required if the block did not exist, i.e. a new block is created.
3796 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3797 * must be initialised before using it.
3798 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3799 * @details n_values_per_frame, block_name, particle_dependency and
3800 * compression are only used if the data block did not exist before calling
3801 * this function, in which case it is created.
3802 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3803 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3806 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_double_set
3807 (tng_trajectory_t tng_data,
3809 const int64_t n_values_per_frame,
3810 const int64_t block_id,
3811 const char *block_name,
3812 const char particle_dependency,
3813 const char compression);
3816 * @brief High-level function for setting the writing interval of data blocks.
3817 * Obsolete! Use tng_util_generic_write_interval_set()
3818 * @param tng_data is the trajectory to use.
3819 * @param i is the output interval, i.e. i == 10 means data written every 10th
3821 * @param n_values_per_frame is the number of values to store per frame. If the
3822 * data is particle dependent there will be n_values_per_frame stored per
3823 * particle each frame.
3824 * @param block_id is the ID of the block, of which to set the output interval.
3825 * @param block_name is a string that will be used as name of the block. Only
3826 * required if the block did not exist, i.e. a new block is created.
3827 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
3828 * data is not related to specific particles (e.g. box shape) or
3829 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
3830 * positions). Only required if the block did not exist, i.e. a new block is
3832 * @param compression is the compression routine to use when writing the data.
3833 * Only required if the block did not exist, i.e. a new block is created.
3834 * @details n_values_per_frame, block_name, particle_dependency and
3835 * compression are only used if the data block did not exist before calling
3836 * this function, in which case it is created.
3837 * This function is replaced by the more correcly named
3838 * tng_util_generic_write_interval_set(), but is kept for compatibility.
3839 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3840 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3843 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_frequency_set
3844 (tng_trajectory_t tng_data,
3846 const int64_t n_values_per_frame,
3847 const int64_t block_id,
3848 const char *block_name,
3849 const char particle_dependency,
3850 const char compression);
3853 * @brief High-level function for setting the writing interval of position
3855 * @param tng_data is the trajectory to use.
3856 * @param i is the output interval, i.e. i == 10 means data written every 10th
3858 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3859 * must be initialised before using it.
3860 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3861 * @details This function uses tng_util_generic_write_interval_set() and will
3862 * create a positions data block if none exists.
3863 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3864 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3867 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_set
3868 (tng_trajectory_t tng_data,
3872 * @brief High-level function for setting the writing interval of position
3873 * data blocks containing double precision data.
3874 * @param tng_data is the trajectory to use.
3875 * @param i is the output interval, i.e. i == 10 means data written every 10th
3877 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3878 * must be initialised before using it.
3879 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3880 * @details This function uses tng_util_generic_write_interval_set() and will
3881 * create a positions data block if none exists.
3882 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3883 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3886 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_double_set
3887 (tng_trajectory_t tng_data,
3891 * @brief High-level function for setting the writing interval of position
3892 * data blocks. Obsolete! Use tng_util_pos_write_interval_set()
3893 * @param tng_data is the trajectory to use.
3894 * @param i is the output interval, i.e. i == 10 means data written every 10th
3896 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3897 * must be initialised before using it.
3898 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3899 * @details This function uses tng_util_generic_write_interval_set() and will
3900 * create a positions data block if none exists.
3901 * This function is replaced by the more correcly named
3902 * tng_util_pos_write_interval_set(), but is kept for compatibility.
3903 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3904 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3907 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_frequency_set
3908 (tng_trajectory_t tng_data,
3912 * @brief High-level function for setting the writing interval of velocity
3914 * @param tng_data is the trajectory to use.
3915 * @param i is the output interval, i.e. i == 10 means data written every 10th
3917 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3918 * must be initialised before using it.
3919 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3920 * @details This function uses tng_util_generic_write_interval_set() and will
3921 * create a velocities data block if none exists.
3922 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3923 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3926 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_set
3927 (tng_trajectory_t tng_data,
3931 * @brief High-level function for setting the writing interval of velocity
3932 * data blocks containing double precision data.
3933 * @param tng_data is the trajectory to use.
3934 * @param i is the output interval, i.e. i == 10 means data written every 10th
3936 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3937 * must be initialised before using it.
3938 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3939 * @details This function uses tng_util_generic_write_interval_set() and will
3940 * create a velocities data block if none exists.
3941 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3942 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3945 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_double_set
3946 (tng_trajectory_t tng_data,
3950 * @brief High-level function for setting the writing interval of velocity
3951 * data blocks. Obsolete! Use tng_util_vel_write_interval_set()
3952 * @param tng_data is the trajectory to use.
3953 * @param i is the output interval, i.e. i == 10 means data written every 10th
3955 * @details This function uses tng_util_generic_write_interval_set() and will
3956 * create a velocities data block if none exists.
3957 * This function is replaced by the more correcly named
3958 * tng_util_vel_write_interval_set(), but is kept for compatibility.
3959 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3960 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3963 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_frequency_set
3964 (tng_trajectory_t tng_data,
3968 * @brief High-level function for setting the writing interval of force
3970 * @param tng_data is the trajectory to use.
3971 * @param i is the output interval, i.e. i == 10 means data written every 10th
3973 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3974 * must be initialised before using it.
3975 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3976 * @details This function uses tng_util_generic_write_interval_set() and will
3977 * create a forces data block if none exists.
3978 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3979 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3982 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_set
3983 (tng_trajectory_t tng_data,
3987 * @brief High-level function for setting the writing interval of force
3988 * data blocks containing double precision data.
3989 * @param tng_data is the trajectory to use.
3990 * @param i is the output interval, i.e. i == 10 means data written every 10th
3992 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3993 * must be initialised before using it.
3994 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3995 * @details This function uses tng_util_generic_write_interval_set() and will
3996 * create a forces data block if none exists.
3997 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3998 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4001 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_double_set
4002 (tng_trajectory_t tng_data,
4006 * @brief High-level function for setting the writing interval of force
4007 * data blocks. Obsolete! Use tng_util_force_write_interval_set()
4008 * @param tng_data is the trajectory to use.
4009 * @param i is the output interval, i.e. i == 10 means data written every 10th
4011 * @details This function uses tng_util_generic_write_interval_set() and will
4012 * create a forces data block if none exists.
4013 * This function is replaced by the more correcly named
4014 * tng_util_force_write_interval_set(), but is kept for compatibility.
4015 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4016 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4019 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_frequency_set
4020 (tng_trajectory_t tng_data,
4024 * @brief High-level function for setting the writing interval of box shape
4026 * @param tng_data is the trajectory to use.
4027 * @param i is the output interval, i.e. i == 10 means data written every 10th
4029 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4030 * must be initialised before using it.
4031 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
4032 * @details This function uses tng_util_generic_write_interval_set() and will
4033 * create a box shape data block if none exists.
4034 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4035 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4038 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_set
4039 (tng_trajectory_t tng_data,
4043 * @brief High-level function for setting the writing interval of box shape
4044 * data blocks containing double precision data.
4045 * @param tng_data is the trajectory to use.
4046 * @param i is the output interval, i.e. i == 10 means data written every 10th
4048 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4049 * must be initialised before using it.
4050 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
4051 * @details This function uses tng_util_generic_write_interval_set() and will
4052 * create a box shape data block if none exists.
4053 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4054 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4057 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_double_set
4058 (tng_trajectory_t tng_data,
4062 * @brief High-level function for setting the writing interval of velocity
4063 * data blocks. Obsolete! Use tng_util_box_shape_write_interval_set()
4064 * @param tng_data is the trajectory to use.
4065 * @param i is the output interval, i.e. i == 10 means data written every 10th
4067 * @details This function uses tng_util_generic_write_interval_set() and will
4068 * create a box shape data block if none exists.
4069 * This function is replaced by the more correcly named
4070 * tng_util_box_shape_write_interval_set(), but is kept for compatibility.
4071 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4072 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4075 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_frequency_set
4076 (tng_trajectory_t tng_data,
4080 * @brief High-level function for writing data of one frame to a data block.
4081 * @param tng_data is the trajectory to use.
4082 * @param frame_nr is the frame number of the data.
4083 * @param values is a 1D array of data to add. The array should be of length
4084 * n_particles * n_values_per_frame if writing particle related data, otherwise
4085 * it should be n_values_per_frame.
4086 * @param n_values_per_frame is the number of values to store per frame. If the
4087 * data is particle dependent there will be n_values_per_frame stored per
4088 * particle each frame.
4089 * @param block_id is the ID of the block, of which to set the output interval.
4090 * @param block_name is a string that will be used as name of the block. Only
4091 * required if the block did not exist, i.e. a new block is created.
4092 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4093 * data is not related to specific particles (e.g. box shape) or
4094 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4095 * positions). Only required if the block did not exist, i.e. a new block is
4097 * @param compression is the compression routine to use when writing the data.
4098 * Only required if the block did not exist, i.e. a new block is created.
4099 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4100 * must be initialised before using it.
4101 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4102 * @pre \code values != 0 \endcode The pointer to the values array must not
4103 * be a NULL pointer.
4104 * @details n_values_per_frame, block_name, particle_dependency and
4105 * compression are only used if the data block did not exist before calling
4106 * this function, in which case it is created.
4107 * N.b. Data is written a whole block at a time. The data is not
4108 * actually written to disk until the frame set is finished or the TNG
4109 * trajectory is closed.
4110 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4111 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4114 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write
4115 (tng_trajectory_t tng_data,
4116 const int64_t frame_nr,
4117 const float *values,
4118 const int64_t n_values_per_frame,
4119 const int64_t block_id,
4120 const char *block_name,
4121 const char particle_dependency,
4122 const char compression);
4125 * @brief High-level function for writing data of one frame to a double precision
4127 * @param tng_data is the trajectory to use.
4128 * @param frame_nr is the frame number of the data.
4129 * @param values is a 1D array of data to add. The array should be of length
4130 * n_particles * n_values_per_frame if writing particle related data, otherwise
4131 * it should be n_values_per_frame.
4132 * @param n_values_per_frame is the number of values to store per frame. If the
4133 * data is particle dependent there will be n_values_per_frame stored per
4134 * particle each frame.
4135 * @param block_id is the ID of the block, of which to set the output interval.
4136 * @param block_name is a string that will be used as name of the block. Only
4137 * required if the block did not exist, i.e. a new block is created.
4138 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4139 * data is not related to specific particles (e.g. box shape) or
4140 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4141 * positions). Only required if the block did not exist, i.e. a new block is
4143 * @param compression is the compression routine to use when writing the data.
4144 * Only required if the block did not exist, i.e. a new block is created.
4145 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4146 * must be initialised before using it.
4147 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4148 * @pre \code values != 0 \endcode The pointer to the values array must not
4149 * be a NULL pointer.
4150 * @details n_values_per_frame, block_name, particle_dependency and
4151 * compression are only used if the data block did not exist before calling
4152 * this function, in which case it is created.
4153 * N.b. Data is written a whole block at a time. The data is not
4154 * actually written to disk until the frame set is finished or the TNG
4155 * trajectory is closed.
4156 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4157 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4160 tng_function_status DECLSPECDLLEXPORT tng_util_generic_double_write
4161 (tng_trajectory_t tng_data,
4162 const int64_t frame_nr,
4163 const double *values,
4164 const int64_t n_values_per_frame,
4165 const int64_t block_id,
4166 const char *block_name,
4167 const char particle_dependency,
4168 const char compression);
4171 * @brief High-level function for adding data to positions data blocks.
4172 * @param tng_data is the trajectory to use.
4173 * @param frame_nr is the frame number of the data.
4174 * @param positions is a 1D array of data to add. The array should be of length
4176 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4177 * must be initialised before using it.
4178 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4179 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4180 * be a NULL pointer.
4181 * @details This function uses tng_util_generic_write() and will
4182 * create a positions data block if none exists. Positions are stored as three
4183 * values per frame and compressed using TNG compression.
4184 * N.b. Since compressed data is written a whole block at a time the data is not
4185 * actually written to disk until the frame set is finished or the TNG
4186 * trajectory is closed.
4187 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4188 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4191 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write
4192 (tng_trajectory_t tng_data,
4193 const int64_t frame_nr,
4194 const float *positions);
4197 * @brief High-level function for adding data to positions data blocks at double
4199 * @param tng_data is the trajectory to use.
4200 * @param frame_nr is the frame number of the data.
4201 * @param positions is a 1D array of data to add. The array should be of length
4203 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4204 * must be initialised before using it.
4205 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4206 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4207 * be a NULL pointer.
4208 * @details This function uses tng_util_generic_write() and will
4209 * create a positions data block if none exists. Positions are stored as three
4210 * values per frame and compressed using TNG compression.
4211 * N.b. Since compressed data is written a whole block at a time the data is not
4212 * actually written to disk until the frame set is finished or the TNG
4213 * trajectory is closed.
4214 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4215 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4218 tng_function_status DECLSPECDLLEXPORT tng_util_pos_double_write
4219 (tng_trajectory_t tng_data,
4220 const int64_t frame_nr,
4221 const double *positions);
4224 * @brief High-level function for adding data to velocities data blocks.
4225 * @param tng_data is the trajectory to use.
4226 * @param frame_nr is the frame number of the data.
4227 * @param velocities is a 1D array of data to add. The array should be of length
4229 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4230 * must be initialised before using it.
4231 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4232 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4233 * be a NULL pointer.
4234 * @details This function uses tng_util_generic_write() and will
4235 * create a velocities data block if none exists. Velocities are stored as three
4236 * values per frame and compressed using TNG compression.
4237 * N.b. Since compressed data is written a whole block at a time the data is not
4238 * actually written to disk until the frame set is finished or the TNG
4239 * trajectory is closed.
4240 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4241 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4244 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write
4245 (tng_trajectory_t tng_data,
4246 const int64_t frame_nr,
4247 const float *velocities);
4250 * @brief High-level function for adding data to velocities data blocks at double
4252 * @param tng_data is the trajectory to use.
4253 * @param frame_nr is the frame number of the data.
4254 * @param velocities is a 1D array of data to add. The array should be of length
4256 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4257 * must be initialised before using it.
4258 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4259 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4260 * be a NULL pointer.
4261 * @details This function uses tng_util_generic_write() and will
4262 * create a velocities data block if none exists. Velocities are stored as three
4263 * values per frame and compressed using TNG compression.
4264 * N.b. Since compressed data is written a whole block at a time the data is not
4265 * actually written to disk until the frame set is finished or the TNG
4266 * trajectory is closed.
4267 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4268 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4271 tng_function_status DECLSPECDLLEXPORT tng_util_vel_double_write
4272 (tng_trajectory_t tng_data,
4273 const int64_t frame_nr,
4274 const double *velocities);
4277 * @brief High-level function for adding data to forces data blocks.
4278 * @param tng_data is the trajectory to use.
4279 * @param frame_nr is the frame number of the data.
4280 * @param forces is a 1D array of data to add. The array should be of length
4282 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4283 * must be initialised before using it.
4284 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4285 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4286 * be a NULL pointer.
4287 * @details This function uses tng_util_generic_write() and will
4288 * create a forces data block if none exists. Forces are stored as three
4289 * values per frame and compressed using gzip compression.
4290 * N.b. Since compressed data is written a whole block at a time the data is not
4291 * actually written to disk until the frame set is finished or the TNG
4292 * trajectory is closed.
4293 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4294 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4297 tng_function_status DECLSPECDLLEXPORT tng_util_force_write
4298 (tng_trajectory_t tng_data,
4299 const int64_t frame_nr,
4300 const float *forces);
4303 * @brief High-level function for adding data to forces data blocks at double
4305 * @param tng_data is the trajectory to use.
4306 * @param frame_nr is the frame number of the data.
4307 * @param forces is a 1D array of data to add. The array should be of length
4309 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4310 * must be initialised before using it.
4311 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4312 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4313 * be a NULL pointer.
4314 * @details This function uses tng_util_generic_write() and will
4315 * create a forces data block if none exists. Forces are stored as three
4316 * values per frame and compressed using gzip compression.
4317 * N.b. Since compressed data is written a whole block at a time the data is not
4318 * actually written to disk until the frame set is finished or the TNG
4319 * trajectory is closed.
4320 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4321 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4324 tng_function_status DECLSPECDLLEXPORT tng_util_force_double_write
4325 (tng_trajectory_t tng_data,
4326 const int64_t frame_nr,
4327 const double *forces);
4330 * @brief High-level function for adding data to box shape data blocks.
4331 * @param tng_data is the trajectory to use.
4332 * @param frame_nr is the frame number of the data.
4333 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4334 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4335 * must be initialised before using it.
4336 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4337 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4338 * be a NULL pointer.
4339 * @details This function uses tng_util_generic_write() and will
4340 * create a box shape data block if none exists. Box shapes are stored as 9
4341 * values per frame and compressed using TNG compression.
4342 * N.b. Since compressed data is written a whole block at a time the data is not
4343 * actually written to disk until the frame set is finished or the TNG
4344 * trajectory is closed.
4345 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4346 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4349 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write
4350 (tng_trajectory_t tng_data,
4351 const int64_t frame_nr,
4352 const float *box_shape);
4355 * @brief High-level function for adding data to box shape data blocks at double
4357 * @param tng_data is the trajectory to use.
4358 * @param frame_nr is the frame number of the data.
4359 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4360 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4361 * must be initialised before using it.
4362 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4363 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4364 * be a NULL pointer.
4365 * @details This function uses tng_util_generic_write() and will
4366 * create a box shape data block if none exists. Box shapes are stored as 9
4367 * values per frame and compressed using TNG compression.
4368 * N.b. Since compressed data is written a whole block at a time the data is not
4369 * actually written to disk until the frame set is finished or the TNG
4370 * trajectory is closed.
4371 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4372 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4375 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_double_write
4376 (tng_trajectory_t tng_data,
4377 const int64_t frame_nr,
4378 const double *box_shape);
4381 * @brief High-level function for writing data of one frame to a data block.
4382 * If the frame is at the beginning of a frame set the time stamp of the frame
4384 * @param tng_data is the trajectory to use.
4385 * @param frame_nr is the frame number of the data.
4386 * @param time is the time stamp of the frame (in seconds).
4387 * @param values is a 1D array of data to add. The array should be of length
4388 * n_particles * n_values_per_frame if writing particle related data, otherwise
4389 * it should be n_values_per_frame.
4390 * @param n_values_per_frame is the number of values to store per frame. If the
4391 * data is particle dependent there will be n_values_per_frame stored per
4392 * particle each frame.
4393 * @param block_id is the ID of the block, of which to set the output interval.
4394 * @param block_name is a string that will be used as name of the block. Only
4395 * required if the block did not exist, i.e. a new block is created.
4396 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4397 * data is not related to specific particles (e.g. box shape) or
4398 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4399 * positions). Only required if the block did not exist, i.e. a new block is
4401 * @param compression is the compression routine to use when writing the data.
4402 * Only required if the block did not exist, i.e. a new block is created.
4403 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4404 * must be initialised before using it.
4405 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4406 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4407 * @pre \code values != 0 \endcode The pointer to the values array must not
4408 * be a NULL pointer.
4409 * @details n_values_per_frame, block_name, particle_dependency and
4410 * compression are only used if the data block did not exist before calling
4411 * this function, in which case it is created.
4412 * N.b. Data is written a whole block at a time. The data is not
4413 * actually written to disk until the frame set is finished or the TNG
4414 * trajectory is closed.
4415 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4416 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4419 tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_write
4420 (tng_trajectory_t tng_data,
4421 const int64_t frame_nr,
4423 const float *values,
4424 const int64_t n_values_per_frame,
4425 const int64_t block_id,
4426 const char *block_name,
4427 const char particle_dependency,
4428 const char compression);
4431 * @brief High-level function for writing data of one frame to a double precision
4432 * data block. If the frame is at the beginning of a frame set the time stamp of
4433 * the frame set is set.
4434 * @param tng_data is the trajectory to use.
4435 * @param frame_nr is the frame number of the data.
4436 * @param time is the time stamp of the frame (in seconds).
4437 * @param values is a 1D array of data to add. The array should be of length
4438 * n_particles * n_values_per_frame if writing particle related data, otherwise
4439 * it should be n_values_per_frame.
4440 * @param n_values_per_frame is the number of values to store per frame. If the
4441 * data is particle dependent there will be n_values_per_frame stored per
4442 * particle each frame.
4443 * @param block_id is the ID of the block, of which to set the output interval.
4444 * @param block_name is a string that will be used as name of the block. Only
4445 * required if the block did not exist, i.e. a new block is created.
4446 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4447 * data is not related to specific particles (e.g. box shape) or
4448 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4449 * positions). Only required if the block did not exist, i.e. a new block is
4451 * @param compression is the compression routine to use when writing the data.
4452 * Only required if the block did not exist, i.e. a new block is created.
4453 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4454 * must be initialised before using it.
4455 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4456 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4457 * @pre \code values != 0 \endcode The pointer to the values array must not
4458 * be a NULL pointer.
4459 * @details n_values_per_frame, block_name, particle_dependency and
4460 * compression are only used if the data block did not exist before calling
4461 * this function, in which case it is created.
4462 * N.b. Data is written a whole block at a time. The data is not
4463 * actually written to disk until the frame set is finished or the TNG
4464 * trajectory is closed.
4465 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4466 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4469 tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_double_write
4470 (tng_trajectory_t tng_data,
4471 const int64_t frame_nr,
4473 const double *values,
4474 const int64_t n_values_per_frame,
4475 const int64_t block_id,
4476 const char *block_name,
4477 const char particle_dependency,
4478 const char compression);
4481 * @brief High-level function for adding data to positions data blocks. If the
4482 * frame is at the beginning of a frame set the time stamp of the frame set
4484 * @param tng_data is the trajectory to use.
4485 * @param frame_nr is the frame number of the data.
4486 * @param time is the time stamp of the frame (in seconds).
4487 * @param positions is a 1D array of data to add. The array should be of length
4489 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4490 * must be initialised before using it.
4491 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4492 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4493 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4494 * be a NULL pointer.
4495 * @details This function uses tng_util_generic_with_time_write() and will
4496 * create a positions data block if none exists. Positions are stored as three
4497 * values per frame and compressed using TNG compression.
4498 * N.b. Since compressed data is written a whole block at a time the data is not
4499 * actually written to disk until the frame set is finished or the TNG
4500 * trajectory is closed.
4501 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4502 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4505 tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_write
4506 (tng_trajectory_t tng_data,
4507 const int64_t frame_nr,
4509 const float *positions);
4512 * @brief High-level function for adding data to positions data blocks at double
4513 * precision. If the frame is at the beginning of a frame set the time stamp of
4514 * the frame set is set.
4515 * @param tng_data is the trajectory to use.
4516 * @param frame_nr is the frame number of the data.
4517 * @param time is the time stamp of the frame (in seconds).
4518 * @param positions is a 1D array of data to add. The array should be of length
4520 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4521 * must be initialised before using it.
4522 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4523 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4524 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4525 * be a NULL pointer.
4526 * @details This function uses tng_util_generic_with_time_double_write() and will
4527 * create a positions data block if none exists. Positions are stored as three
4528 * values per frame and compressed using TNG compression.
4529 * N.b. Since compressed data is written a whole block at a time the data is not
4530 * actually written to disk until the frame set is finished or the TNG
4531 * trajectory is closed.
4532 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4533 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4536 tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_double_write
4537 (tng_trajectory_t tng_data,
4538 const int64_t frame_nr,
4540 const double *positions);
4543 * @brief High-level function for adding data to velocities data blocks. If the
4544 * frame is at the beginning of a frame set the time stamp of the frame set
4546 * @param tng_data is the trajectory to use.
4547 * @param frame_nr is the frame number of the data.
4548 * @param time is the time stamp of the frame (in seconds).
4549 * @param velocities is a 1D array of data to add. The array should be of length
4551 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4552 * must be initialised before using it.
4553 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4554 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4555 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4556 * be a NULL pointer.
4557 * @details This function uses tng_util_generic_with_time_write() and will
4558 * create a velocities data block if none exists. Velocities are stored as three
4559 * values per frame and compressed using TNG compression.
4560 * N.b. Since compressed data is written a whole block at a time the data is not
4561 * actually written to disk until the frame set is finished or the TNG
4562 * trajectory is closed.
4563 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4564 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4567 tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_write
4568 (tng_trajectory_t tng_data,
4569 const int64_t frame_nr,
4571 const float *velocities);
4574 * @brief High-level function for adding data to velocities data blocks at
4575 * double precision. If the frame is at the beginning of a frame set the
4576 * time stamp of the frame set is set.
4577 * @param tng_data is the trajectory to use.
4578 * @param frame_nr is the frame number of the data.
4579 * @param time is the time stamp of the frame (in seconds).
4580 * @param velocities is a 1D array of data to add. The array should be of length
4582 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4583 * must be initialised before using it.
4584 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4585 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4586 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4587 * be a NULL pointer.
4588 * @details This function uses tng_util_generic_with_time_double_write() and will
4589 * create a velocities data block if none exists. Velocities are stored as three
4590 * values per frame and compressed using TNG compression.
4591 * N.b. Since compressed data is written a whole block at a time the data is not
4592 * actually written to disk until the frame set is finished or the TNG
4593 * trajectory is closed.
4594 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4595 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4598 tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_double_write
4599 (tng_trajectory_t tng_data,
4600 const int64_t frame_nr,
4602 const double *velocities);
4605 * @brief High-level function for adding data to forces data blocks. If the
4606 * frame is at the beginning of a frame set the time stamp of the frame set
4608 * @param tng_data is the trajectory to use.
4609 * @param frame_nr is the frame number of the data.
4610 * @param time is the time stamp of the frame (in seconds).
4611 * @param forces is a 1D array of data to add. The array should be of length
4613 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4614 * must be initialised before using it.
4615 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4616 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4617 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4618 * be a NULL pointer.
4619 * @details This function uses tng_util_generic_with_time_write() and will
4620 * create a forces data block if none exists. Forces are stored as three
4621 * values per frame and compressed using gzip compression.
4622 * N.b. Since compressed data is written a whole block at a time the data is not
4623 * actually written to disk until the frame set is finished or the TNG
4624 * trajectory is closed.
4625 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4626 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4629 tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_write
4630 (tng_trajectory_t tng_data,
4631 const int64_t frame_nr,
4633 const float *forces);
4636 * @brief High-level function for adding data to forces data blocks at
4637 * double precision. If the frame is at the beginning of a frame set
4638 * the time stamp of the frame set is set.
4639 * @param tng_data is the trajectory to use.
4640 * @param frame_nr is the frame number of the data.
4641 * @param time is the time stamp of the frame (in seconds).
4642 * @param forces is a 1D array of data to add. The array should be of length
4644 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4645 * must be initialised before using it.
4646 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4647 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4648 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4649 * be a NULL pointer.
4650 * @details This function uses tng_util_generic_with_time_double_write() and will
4651 * create a forces data block if none exists. Forces are stored as three
4652 * values per frame and compressed using gzip compression.
4653 * N.b. Since compressed data is written a whole block at a time the data is not
4654 * actually written to disk until the frame set is finished or the TNG
4655 * trajectory is closed.
4656 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4657 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4660 tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_double_write
4661 (tng_trajectory_t tng_data,
4662 const int64_t frame_nr,
4664 const double *forces);
4667 * @brief High-level function for adding data to box shape data blocks. If the
4668 * frame is at the beginning of a frame set the time stamp of the frame set
4670 * @param tng_data is the trajectory to use.
4671 * @param frame_nr is the frame number of the data.
4672 * @param time is the time stamp of the frame (in seconds).
4673 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4674 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4675 * must be initialised before using it.
4676 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4677 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4678 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4679 * be a NULL pointer.
4680 * @details This function uses tng_util_generic_with_time_write() and will
4681 * create a box shape data block if none exists. Box shapes are stored as 9
4682 * values per frame and compressed using TNG compression.
4683 * N.b. Since compressed data is written a whole block at a time the data is not
4684 * actually written to disk until the frame set is finished or the TNG
4685 * trajectory is closed.
4686 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4687 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4690 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_write
4691 (tng_trajectory_t tng_data,
4692 const int64_t frame_nr,
4694 const float *box_shape);
4697 * @brief High-level function for adding data to box shape data blocks at
4698 * double precision. If the frame is at the beginning of a frame set the
4699 * time stamp of the frame set is set.
4700 * @param tng_data is the trajectory to use.
4701 * @param frame_nr is the frame number of the data.
4702 * @param time is the time stamp of the frame (in seconds).
4703 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4704 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4705 * must be initialised before using it.
4706 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4707 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4708 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4709 * be a NULL pointer.
4710 * @details This function uses tng_util_generic_with_time_double_write() and will
4711 * create a box shape data block if none exists. Box shapes are stored as 9
4712 * values per frame and compressed using TNG compression.
4713 * N.b. Since compressed data is written a whole block at a time the data is not
4714 * actually written to disk until the frame set is finished or the TNG
4715 * trajectory is closed.
4716 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4717 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4720 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_double_write
4721 (tng_trajectory_t tng_data,
4722 const int64_t frame_nr,
4724 const double *box_shape);
4727 * @brief High-level function for getting the compression method and
4728 * multiplication factor of the last read frame of a specific data block.
4729 * @param tng_data is the trajectory to use.
4730 * @param block_id is the ID number of the block containing the data of
4732 * @param codec_id will be set to the value of the codec_id of the
4733 * compression of the data block. See tng_compression for more details.
4734 * @param factor will be set to the multiplication factor applied to
4735 * the values before compression, in order to get integers from them.
4736 * factor is 1/precision.
4737 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4738 * must be initialised before using it.
4739 * @pre \code codec_id != 0 \endcode The pointer to the returned codec id
4740 * must not be a NULL pointer.
4741 * @pre \code factor != 0 \endcode The pointer to the returned multiplication
4742 * factor must not be a NULL pointer.
4743 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4744 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4747 tng_function_status DECLSPECDLLEXPORT tng_util_frame_current_compression_get
4748 (tng_trajectory_t tng_data,
4749 const int64_t block_id,
4753 /** @brief High-level function for determining the next frame with data and what
4754 * data blocks have data for that frame. The search can be limited to certain
4756 * @param tng_data is the trajectory to use.
4757 * @param current_frame is the frame that was last read, from where to start
4759 * @param n_requested_data_block_ids is the number of data blocks listed in
4760 * requested_data_block_ids. If this is 0 all data blocks will be taken into
4762 * @param requested_data_block_ids is an array of data blocks to look for.
4763 * @param next_frame will be set to the next frame with data.
4764 * @param n_data_blocks_in_next_frame is set to the number of data blocks with
4765 * data for next_frame.
4766 * @param data_block_ids_in_next_frame is set to an array (of length
4767 * n_data_blocks_in_next_frame) that lists the data block IDs with data for
4768 * next_frame. It must be pointing at NULL or previously allocated memory.
4769 * Memory for the array is allocated by this function.
4770 * The memory must be freed by the client afterwards or
4771 * there will be a memory leak.
4772 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4773 * must be initialised before using it.
4774 * @pre \code next_frame != 0 \endcode The pointer to the next frame must not
4776 * @pre \code n_data_blocks_in_next_frame != 0 \endcode The pointer to
4777 * n_data_blocks_in_next_frame must not be NULL.
4778 * @pre \code *data_block_ids_in_next_frame != 0 \endcode The pointer to the
4779 * list of data block IDs must not be NULL.
4780 * @pre \code n_requested_data_block_ids == 0 || requested_data_block_ids != 0 \endcode
4781 * If the number of requested data blocks != 0 then the array of data block IDs must not be NULL.
4782 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4783 * has occured or TNG_CRITICAL (2) if a major error
4786 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_next_frame_present_data_blocks_find
4787 (tng_trajectory_t tng_data,
4788 int64_t current_frame,
4789 const int64_t n_requested_data_block_ids,
4790 const int64_t *requested_data_block_ids,
4791 int64_t *next_frame,
4792 int64_t *n_data_blocks_in_next_frame,
4793 int64_t **data_block_ids_in_next_frame);
4795 /* @brief High-level function for getting all data block ids and their names
4796 * and stride lengths.
4797 * @param tng_data is the trajectory to use.
4798 * @param n_data_blocks is set to the number of data blocks in the trajectory.
4799 * @param data_block_ids is set to an array (of length
4800 * n_data_blocks) that lists the data block IDs in the trajectory.
4801 * It must be pointing at NULL or previously allocated memory.
4802 * Memory for the array is allocated by this function.
4803 * The memory must be freed by the client afterwards or
4804 * there will be a memory leak.
4805 * @param data_block_names is set to an array (of length
4806 * n_data_blocks) that contains the names of the data blocks.
4807 * It must be pointing at NULL or previously allocated memory.
4808 * Memory for the array is allocated by this function.
4809 * The memory must be freed by the client afterwards or
4810 * there will be a memory leak.
4811 * @param stride_lengths is set to an array (of length
4812 * n_data_blocks) that lists the stride lengths of the data blocks.
4813 * It must be pointing at NULL or previously allocated memory.
4814 * Memory for the array is allocated by this function.
4815 * The memory must be freed by the client afterwards or
4816 * there will be a memory leak.
4817 * @param n_values_per_frame is set to an array (of length
4818 * n_data_blocks) that lists the number of values per frame of the data blocks.
4819 * It must be pointing at NULL or previously allocated memory.
4820 * Memory for the array is allocated by this function.
4821 * The memory must be freed by the client afterwards or
4822 * there will be a memory leak.
4823 * @param block_types is set to an array (of length
4824 * n_data_blocks) that lists the block types of the data blocks.
4825 * It must be pointing at NULL or previously allocated memory.
4826 * Memory for the array is allocated by this function.
4827 * The memory must be freed by the client afterwards or
4828 * there will be a memory leak.
4829 * @param dependencies is set to an array (of length
4830 * n_data_blocks) that lists the dependencies of the data blocks.
4831 * It must be pointing at NULL or previously allocated memory.
4832 * Memory for the array is allocated by this function.
4833 * The memory must be freed by the client afterwards or
4834 * there will be a memory leak.
4835 * @param compressions is set to an array (of length
4836 * n_data_blocks) that lists the compressions of the data blocks.
4837 * It must be pointing at NULL or previously allocated memory.
4838 * Memory for the array is allocated by this function.
4839 * The memory must be freed by the client afterwards or
4840 * there will be a memory leak.
4841 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4842 * must be initialised before using it.
4843 * @pre \code n_data_blocks != 0 \endcode The pointer to
4844 * n_data_blocks must not be NULL.
4845 * @pre \code data_block_ids != 0 \endcode The pointer to the
4846 * list of data block IDs must not be NULL.
4847 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4848 * has occured or TNG_CRITICAL (2) if a major error
4852 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_all_data_block_types_get
4853 (tng_trajectory_t tng_data,
4854 int64_t *n_data_blocks,
4855 int64_t **data_block_ids,
4856 char ***data_block_names,
4857 int64_t **stride_lengths,
4858 int64_t **n_values_per_frame,
4860 char **dependencies,
4861 char **compressions);
4864 /** @brief Finds the frame set of the specified frame in order to prepare for writing
4866 * @param tng_data is the trajectory to use.
4867 * @param prev_frame is the frame after which to start appending.
4868 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4869 * must be initialised before using it.
4870 * @pre \code prev_frame >= 0 \endcode The previous frame must not be negative.
4871 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4872 * has occured (such as not finding the requested frame) or TNG_CRITICAL (2)
4873 * if a major error has occured.
4875 tng_function_status DECLSPECDLLEXPORT tng_util_prepare_append_after_frame
4876 (tng_trajectory_t tng_data,
4877 const int64_t prev_frame);
4879 /** @} */ /* end of group2 */
4883 } /* end extern "C" */
4886 #endif /* TNG_IO_H */