1 /* This code is part of the tng binary trajectory format.
5 * Written by Magnus Lundborg
6 * Copyright (c) 2012-2013, The GROMACS development team.
7 * Check out http://www.gromacs.org for more information.
10 * This program is free software; you can redistribute it and/or
11 * modify it under the terms of the Revised BSD License.
15 * @brief API for input and output of tng trajectory files
16 * @mainpage TNG: A flexible binary trajectory format
17 * @section intro_sec Introduction
19 * The TNG format is developed as part of the ScalaLife EU project.
20 * It is flexible by design to allow parallel writing, custom data blocks,
21 * different output frequencies and different compression algorithms.
23 * Each block can contain MD5 hashes to verify data integrity and the file
24 * can be signed by the user to ensure that the origin is correct.
26 * This is version 1.4 of the TNG API. The intention is that this version of
27 * the API and ABI should be stable, but it is still possible that future
28 * changes might make that impossible, in which case that will be clarified.
30 * The API and all examples are released without any warranties. Use them at
33 * @section authors_sec Authors
35 * The TNG trajectory format is developed by:
37 * Magnus Lundborg magnus.lundborg@scilifelab.se
39 * Daniel SpÄngberg daniels@mkem.uu.se
41 * Rossen Apostolov rossen@kth.se
43 * The API is implemented mainly by:
49 * Copyright (c) 2012, The GROMACS development team.
50 * check out http://www.gromacs.org for more information.
52 * The TNG API is released under the Revised BSD License and is free to
53 * redistribute according to that license.
55 * A license file (named COPYING) should be included with each copy of the API.
57 * @section install_sec Installation
72 * bin/tests/tng_testing
75 * @section change_sec Change Log
77 * See git log for full revision history.
81 * v. 1.5 - Third stable release of the API.
83 * - Fortran wrapper split into separate file
84 * - Added more block IDs.
85 * - Some new functions and utility functions added.
86 * - Improved compression precision settings.
88 * - Make appending to file work better.
89 * - Modified CMake settings
92 * v. 1.4 - Changed from LGPL to the Revised BSD License.
94 * - More flexible support for digital signatures in header.
95 * - Block ID numbers changed.
97 * v. 1.3 - Second stable release of the API.
99 * - Added multiplication factor for coordinate units to general info.
100 * - Added time stamps and time per frame in frame sets.
101 * - High-level API functions added (not for managing molecules yet)
102 * - Added functions for reading data blocks into 1D arrays.
103 * - TNG compression added.
104 * - C++ interface added.
105 * - Avoid memory allocation if no data is submitted when adding data
107 * - Added function tng_num_frames_per_frame_set_set
108 * - Added data block IDs for charges, b-factors and occupancy.
109 * - GZIP compression added.
110 * - Fixed bug when updating MD5 hashes of data blocks.
111 * - Fixed bug in chain_name_of_particle_get(...)
112 * - Update frame set pointers properly.
113 * - Moved fortran wrapper from header file to source file.
114 * - Write sparse data in mdrun examples.
115 * - Fixed bugs related to reading and writing sparse data.
116 * - Fixed memory leak for non-trajectory particle data blocks.
117 * - Fixed bug when writing data blocks.
118 * - Fixed wrong values in dependency constants
119 * - Write box shape, partial charges and annotation data in tng_testing
120 * - Bug fixes in tng_testing (frame sets not written before)
122 * v. 1.0 - First stable release of the API.
125 * @section examples_sec Examples
127 * There are some examples of how to use the library located in src/tests/
129 * @subsection tng_subsec TNG files
131 * The build directory contains an example_files directory, which in turn
132 * contains a very short example of a TNG file containing a few water molecules,
133 * a box shape description and positions in 10 frames.
135 * It is also possible to run the bin/examples/md_openmp_util
136 * (see src/tests/md_openmp_util.c)
137 * testing program, which will save MD simulations output to a new file
138 * (saved in the example_files directory).
140 * These files can be read using the bin/examples/tng_io_read_pos_util
143 * @subsection c_subsec C
145 * Example writing data to a TNG file (just an excerpt):
147 * for ( step = 1; step < step_num; step++ )
149 * compute ( np, nd, pos, vel, mass, force, &potential, &kinetic );
151 * if(step % step_save == 0)
153 * // Write positions, velocities and forces
154 * if(tng_util_pos_write(traj, step, pos) != TNG_SUCCESS)
156 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
159 * if(tng_util_vel_write(traj, step, vel) != TNG_SUCCESS)
161 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
164 * if(tng_util_force_write(traj, step, force) != TNG_SUCCESS)
166 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
170 * update ( np, nd, pos, vel, force, acc, mass, dt );
174 * Example reading positions from a TNG file:
176 * #include <stdlib.h>
178 * #include "tng_io.h"
180 * int main(int argc, char **argv)
182 * tng_trajectory_t traj;
183 * // Assume that the data is stored as floats. The data is placed in 1-D
185 * float *positions = 0, *box_shape = 0;
186 * int64_t n_particles, n_frames, tot_n_frames, stride_length, i, j;
187 * // Set a default frame range
188 * int64_t first_frame = 0, last_frame = 5000;
191 * // A reference must be passed to allocate memory
192 * tng_util_trajectory_open(argv[1], 'r', &traj);
194 * if(tng_num_frames_get(traj, &tot_n_frames) != TNG_SUCCESS)
196 * printf("Cannot determine the number of frames in the file\n");
197 * tng_util_trajectory_close(&traj);
201 * if(tng_num_particles_get(traj, &n_particles) != TNG_SUCCESS)
203 * printf("Cannot determine the number of particles in the file\n");
204 * tng_util_trajectory_close(&traj);
208 * printf("%"PRId64" frames in file\n", tot_n_frames);
210 * if(last_frame > tot_n_frames - 1)
212 * last_frame = tot_n_frames - 1;
215 * if(tng_util_box_shape_read(traj, &box_shape, &stride_length) ==
218 * printf("Simulation box shape: ");
219 * for(i=0; i < 9; i++)
221 * printf("%f ", box_shape[i]);
227 * printf("Simulation box shape not set in the file (or could not be read)\n");
230 * n_frames = last_frame - first_frame + 1;
233 * // Get the positions of all particles in the requested frame range.
234 * // The positions are stored in the positions array.
235 * // N.B. No proper error checks.
236 * if(tng_util_pos_read_range(traj, 0, last_frame, &positions, &stride_length)
239 * // Print the positions of the wanted particle (zero based)
240 * for(i=0; i < n_frames; i += stride_length)
242 * printf("\nFrame %"PRId64":\n", first_frame + i);
243 * for(j=0; j < n_particles; j++)
245 * printf("Atom nr: %"PRId64"", j);
246 * for(k=0; k < 3; k++)
248 * printf("\t%f", positions[i/stride_length*n_particles*
257 * printf("Cannot read positions\n");
265 * tng_util_trajectory_close(&traj);
272 * @subsection fortran_subsec Fortran
274 * The TNG library can be used from Fortran. It requires cray pointers, which
275 * are not part of the Fortran 77 standard, but available in most compilers.
277 * To compile the fortran example -DTNG_BUILD_FORTRAN=ON needs to be specified when
289 #include "tng_io_fwd.h"
291 #ifdef USE_STD_INTTYPES_H
292 #include <inttypes.h>
294 /* Visual Studio does not contain inttypes.h and stdint.h. Some defines and
295 * typedefs are used from the GNU C Library */
298 typedef __int32 int32_t;
299 typedef unsigned __int32 uint32_t;
300 typedef __int64 int64_t;
301 typedef unsigned __int64 uint64_t;
305 #endif /* _MSC_VER */
307 /* This is from inttypes.h (GNU C Library) */
308 /* The ISO C99 standard specifies that these macros must only be
309 defined if explicitly requested. */
310 #if !defined __cplusplus || defined __STDC_FORMAT_MACROS
312 # if __WORDSIZE == 64
313 # define __PRI64_PREFIX "l"
314 # define __PRIPTR_PREFIX "l"
316 # define __PRI64_PREFIX "ll"
317 # define __PRIPTR_PREFIX
320 /* From stdint.h (GNU C Library) */
321 /* Macros for printing format specifiers. */
322 /* Decimal notation. */
324 # define PRId64 __PRI64_PREFIX "d"
329 #endif /* USE_STD_INTTYPES_H */
333 #if defined(WIN32) || defined(_WIN32) || defined(WIN64) || defined(_WIN64)
335 #endif /* win32... */
336 #endif /* not defined USE_WINDOWS */
338 #ifndef DECLSPECDLLEXPORT
340 #define DECLSPECDLLEXPORT __declspec(dllexport)
341 #else /* USE_WINDOWS */
342 #define DECLSPECDLLEXPORT
343 #endif /* USE_WINDOWS */
344 #endif /* DECLSPECDLLEXPORT */
347 /** The version of this TNG build */
348 #define TNG_VERSION 5 /* TNG_VERSION 4 => Api version 1.5 */
350 /** Flag to indicate frame dependent data. */
351 #define TNG_FRAME_DEPENDENT 1
352 /** Flag to indicate particle dependent data. */
353 #define TNG_PARTICLE_DEPENDENT 2
355 /** The maximum length of a date string */
356 #define TNG_MAX_DATE_STR_LEN 24
357 /** The length of an MD5 hash */
358 #define TNG_MD5_HASH_LEN 16
359 /** The maximum allowed length of a string */
360 #define TNG_MAX_STR_LEN 1024
363 #define TNG_ASSERT(cnd, msg) if(!(cnd)) {printf("%s\n", msg); assert(cnd);}
365 #define TNG_ASSERT(cnd, msg) (void)0;
368 /** Flag to specify the endianness of a TNG file */
369 typedef enum {TNG_BIG_ENDIAN,
370 TNG_LITTLE_ENDIAN} tng_file_endianness;
372 /** Flag to specify the endianness of 32 bit values of the current architecture. */
373 typedef enum {TNG_BIG_ENDIAN_32,
374 TNG_LITTLE_ENDIAN_32,
375 TNG_BYTE_PAIR_SWAP_32} tng_endianness_32;
377 /** Flag to specify the endianness of 64 bit values of the current architecture. */
378 typedef enum {TNG_BIG_ENDIAN_64,
379 TNG_LITTLE_ENDIAN_64,
381 TNG_BYTE_PAIR_SWAP_64,
382 TNG_BYTE_SWAP_64} tng_endianness_64;
384 /** Compression mode is specified in each data block */
385 typedef enum {TNG_UNCOMPRESSED,
388 TNG_GZIP_COMPRESSION} tng_compression;
391 typedef enum {TNG_NO_HASH,
393 TNG_SHA256} tng_hash_type;
395 /** Non trajectory blocks come before the first frame set block */
396 typedef enum {TNG_NON_TRAJECTORY_BLOCK, TNG_TRAJECTORY_BLOCK} tng_block_type;
398 /** @defgroup def1 Standard non-trajectory blocks
399 * Block IDs of standard non-trajectory blocks.
402 #define TNG_GENERAL_INFO 0x0000000000000000LL
403 #define TNG_MOLECULES 0x0000000000000001LL
404 #define TNG_TRAJECTORY_FRAME_SET 0x0000000000000002LL
405 #define TNG_PARTICLE_MAPPING 0x0000000000000003LL
408 /** @defgroup def2 Standard trajectory blocks
409 * Block IDs of standard trajectory blocks. Box shape and partial charges can
410 * be either trajectory blocks or non-trajectory blocks
413 #define TNG_TRAJ_BOX_SHAPE 0x0000000010000000LL
414 #define TNG_TRAJ_POSITIONS 0x0000000010000001LL
415 #define TNG_TRAJ_VELOCITIES 0x0000000010000002LL
416 #define TNG_TRAJ_FORCES 0x0000000010000003LL
417 #define TNG_TRAJ_PARTIAL_CHARGES 0x0000000010000004LL
418 #define TNG_TRAJ_FORMAL_CHARGES 0x0000000010000005LL
419 #define TNG_TRAJ_B_FACTORS 0x0000000010000006LL
420 #define TNG_TRAJ_ANISOTROPIC_B_FACTORS 0x0000000010000007LL
421 #define TNG_TRAJ_OCCUPANCY 0x0000000010000008LL
425 /** @defgroup def3 GROMACS data block IDs
426 * Block IDs of data blocks specific to GROMACS.
429 #define TNG_GMX_LAMBDA 0x1000000010000000LL
430 #define TNG_GMX_ENERGY_ANGLE 0x1000000010000001LL
431 #define TNG_GMX_ENERGY_RYCKAERT_BELL 0x1000000010000002LL
432 #define TNG_GMX_ENERGY_LJ_14 0x1000000010000003LL
433 #define TNG_GMX_ENERGY_COULOMB_14 0x1000000010000004LL
434 #define TNG_GMX_ENERGY_LJ_(SR) 0x1000000010000005LL
435 #define TNG_GMX_ENERGY_COULOMB_(SR) 0x1000000010000006LL
436 #define TNG_GMX_ENERGY_COUL_RECIP 0x1000000010000007LL
437 #define TNG_GMX_ENERGY_POTENTIAL 0x1000000010000008LL
438 #define TNG_GMX_ENERGY_KINETIC_EN 0x1000000010000009LL
439 #define TNG_GMX_ENERGY_TOTAL_ENERGY 0x1000000010000010LL
440 #define TNG_GMX_ENERGY_TEMPERATURE 0x1000000010000011LL
441 #define TNG_GMX_ENERGY_PRESSURE 0x1000000010000012LL
442 #define TNG_GMX_ENERGY_CONSTR_RMSD 0x1000000010000013LL
443 #define TNG_GMX_ENERGY_BOX_X 0x1000000010000014LL
444 #define TNG_GMX_ENERGY_BOX_Y 0x1000000010000015LL
445 #define TNG_GMX_ENERGY_BOX_Z 0x1000000010000016LL
446 #define TNG_GMX_ENERGY_VOLUME 0x1000000010000017LL
447 #define TNG_GMX_ENERGY_DENSITY 0x1000000010000018LL
448 #define TNG_GMX_ENERGY_PV 0x1000000010000019LL
449 #define TNG_GMX_ENERGY_ENTHALPY 0x1000000010000020LL
450 #define TNG_GMX_ENERGY_VIR_XX 0x1000000010000021LL
451 #define TNG_GMX_ENERGY_VIR_XY 0x1000000010000022LL
452 #define TNG_GMX_ENERGY_VIR_XZ 0x1000000010000023LL
453 #define TNG_GMX_ENERGY_VIR_YX 0x1000000010000024LL
454 #define TNG_GMX_ENERGY_VIR_YY 0x1000000010000025LL
455 #define TNG_GMX_ENERGY_VIR_YZ 0x1000000010000026LL
456 #define TNG_GMX_ENERGY_VIR_ZX 0x1000000010000027LL
457 #define TNG_GMX_ENERGY_VIR_ZY 0x1000000010000028LL
458 #define TNG_GMX_ENERGY_VIR_ZZ 0x1000000010000029LL
459 #define TNG_GMX_ENERGY_PRES_XX 0x1000000010000030LL
460 #define TNG_GMX_ENERGY_PRES_XY 0x1000000010000031LL
461 #define TNG_GMX_ENERGY_PRES_XZ 0x1000000010000032LL
462 #define TNG_GMX_ENERGY_PRES_YX 0x1000000010000033LL
463 #define TNG_GMX_ENERGY_PRES_YY 0x1000000010000034LL
464 #define TNG_GMX_ENERGY_PRES_YZ 0x1000000010000035LL
465 #define TNG_GMX_ENERGY_PRES_ZX 0x1000000010000036LL
466 #define TNG_GMX_ENERGY_PRES_ZY 0x1000000010000037LL
467 #define TNG_GMX_ENERGY_PRES_ZZ 0x1000000010000038LL
468 #define TNG_GMX_ENERGY_SURFXSURFTEN 0x1000000010000039LL
469 #define TNG_GMX_ENERGY_T_SYSTEM 0x1000000010000040LL
470 #define TNG_GMX_ENERGY_LAMB_SYSTEM 0x1000000010000041LL
471 #define TNG_GMX_SELECTION_GROUP_NAMES 0x1000000010000042LL
472 #define TNG_GMX_ATOM_SELECTION_GROUP 0x1000000010000043LL
475 /** Flag to specify if a data block contains data related to particles or not.*/
476 typedef enum {TNG_NON_PARTICLE_BLOCK_DATA,
477 TNG_PARTICLE_BLOCK_DATA} tng_particle_dependency;
480 typedef enum {TNG_FALSE, TNG_TRUE} tng_bool;
482 /** Flag to specify if the number of atoms change throughout the trajectory or
483 * if it is constant. */
484 typedef enum {TNG_CONSTANT_N_ATOMS, TNG_VARIABLE_N_ATOMS}
485 tng_variable_n_atoms_flag;
487 /** Return values of API functions. TNG_SUCCESS means that the operation
488 * was successful. TNG_FAILURE means that the operation failed for some
489 * reason, but it is possible to try to continue anyhow. TNG_CRITICAL
490 * means that the error is irrecoverable. */
491 typedef enum {TNG_SUCCESS, TNG_FAILURE, TNG_CRITICAL} tng_function_status;
493 /** If tng_hash_mode == TNG_USE_HASH md5 hashes will be written to output files
494 * and when reading a file the md5 hashes of the contents will be compared to
495 * those in the file (for each block) in order to ensure data integrity */
496 typedef enum {TNG_SKIP_HASH, TNG_USE_HASH} tng_hash_mode;
498 /** Possible formats of data block contents */
499 typedef enum {TNG_CHAR_DATA,
502 TNG_DOUBLE_DATA} tng_data_type;
505 struct tng_trajectory;
511 struct tng_gen_block;
512 struct tng_particle_mapping;
513 struct tng_trajectory_frame_set;
514 struct tng_particle_data;
515 struct tng_non_particle_data;
517 /** Data can be either double, float, int or a string */
531 /** @defgroup group1 Low-level API
532 * These functions give detailed control of the TNG data management. Most
533 * things can be done using the more convenient high-level API functions
539 * @brief Setup a trajectory data container.
540 * @param tng_data_p a pointer to memory to initialise as a trajectory.
541 * @pre tng_data_p must not be pointing at a reserved memory block.
542 * @details Memory is allocated during initialisation.
543 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
546 tng_function_status DECLSPECDLLEXPORT tng_trajectory_init
547 (tng_trajectory_t *tng_data_p);
550 * @brief Clean up a trajectory data container.
551 * @param tng_data_p a pointer to the trajectory data to destroy.
552 * @details All allocated memory in the data structure is freed, as well as
554 * @return TNG_SUCCESS (0) if successful.
556 tng_function_status DECLSPECDLLEXPORT tng_trajectory_destroy
557 (tng_trajectory_t *tng_data_p);
560 * @brief Copy a trajectory data container (dest is setup as well).
561 * @details This initialises dest and copies only what is absolute necessary for
562 * parallel i/o. This can be used inside pragma omp for setting up a thread
563 * local copy of src. It can be freed (using tng_trajectory_destroy) at the
564 * end of the parallel block.
565 * @param src the original trajectory.
566 * @param dest_p a pointer to memory to initialise as a trajectory.
567 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
568 * must be initialised before using it.
569 * @pre tng_data_p must not be pointing at a reserved memory block.
570 * @details Memory is allocated during initialisation.
571 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
574 tng_function_status DECLSPECDLLEXPORT tng_trajectory_init_from_src
575 (tng_trajectory_t src, tng_trajectory_t *dest_p);
578 * @brief Get the name of the input file.
579 * @param tng_data the trajectory of which to get the input file name.
580 * @param file_name the string to fill with the name of the input file,
581 * memory must be allocated before.
582 * @param max_len maximum char length of the string, i.e. how much memory has
583 * been reserved for file_name. This includes \0 terminating character.
584 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
585 * must be initialised before using it.
586 * @pre \code file_name != 0 \endcode The pointer to the file name string
587 * must not be a NULL pointer.
588 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
589 * has occurred (source string longer than destination string).
591 tng_function_status DECLSPECDLLEXPORT tng_input_file_get
592 (const tng_trajectory_t tng_data,
593 char *file_name, const int max_len);
596 * @brief Set the name of the input file.
597 * @param tng_data the trajectory of which to set the input file name.
598 * @param file_name the name of the input file.
599 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
600 * must be initialised before using it.
601 * @pre \code file_name != 0 \endcode The pointer to the file name string
602 * must not be a NULL pointer.
603 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
606 tng_function_status DECLSPECDLLEXPORT tng_input_file_set
607 (tng_trajectory_t tng_data,
608 const char *file_name);
611 * @brief Get the name of the output file.
612 * @param tng_data the trajectory of which to get the input file name.
613 * @param file_name the string to fill with the name of the output file,
614 * memory must be allocated before.
615 * @param max_len maximum char length of the string, i.e. how much memory has
616 * been reserved for file_name. This includes \0 terminating character.
617 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
618 * must be initialised before using it.
619 * @pre \code file_name != 0 \endcode The pointer to the file name string
620 * must not be a NULL pointer.
621 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
622 * has occurred (source string longer than destination string).
624 tng_function_status DECLSPECDLLEXPORT tng_output_file_get
625 (const tng_trajectory_t tng_data,
626 char *file_name, const int max_len);
629 * @brief Set the name of the output file.
630 * @param tng_data the trajectory of which to set the output file name.
631 * @param file_name the name of the output file.
632 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
633 * must be initialised before using it.
634 * @pre \code file_name != 0 \endcode The pointer to the file name string
635 * must not be a NULL pointer.
636 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
639 tng_function_status DECLSPECDLLEXPORT tng_output_file_set
640 (tng_trajectory_t tng_data,
641 const char *file_name);
644 * @brief Set the name of the output file for appending. The output file
645 * will not be overwritten.
646 * @param tng_data the trajectory of which to set the output file name.
647 * @param file_name the name of the output file to append to.
648 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
649 * must be initialised before using it.
650 * @pre \code file_name != 0 \endcode The pointer to the file name string
651 * must not be a NULL pointer.
652 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
655 tng_function_status DECLSPECDLLEXPORT tng_output_append_file_set
656 (tng_trajectory_t tng_data,
657 const char *file_name);
660 * @brief Get the endianness of the output file.
661 * @param tng_data the trajectory of which to get the endianness of the current
663 * @param endianness will contain the enumeration of the endianness.
664 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
665 * must be initialised before using it.
666 * @pre \code endianness != 0 \endcode The pointer to the endianness container
667 * must not be a NULL pointer.
668 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness
669 * could not be retrieved.
671 tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_get
672 (const tng_trajectory_t tng_data, tng_file_endianness *endianness);
675 * @brief Set the endianness of the output file.
676 * @param tng_data the trajectory of which to set the endianness of the current
678 * @param endianness the enumeration of the endianness, can be either
679 * TNG_BIG_ENDIAN (0) or TNG_LITTLE_ENDIAN (1).
680 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
681 * must be initialised before using it.
682 * @details The endianness cannot be changed after file output has started.
683 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness
686 tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_set
687 (tng_trajectory_t tng_data,
688 const tng_file_endianness endianness);
691 * @brief Get the name of the program used when creating the trajectory.
692 * @param tng_data the trajectory of which to get the program name.
693 * @param name the string to fill with the name of the program,
694 * memory must be allocated before.
695 * @param max_len maximum char length of the string, i.e. how much memory has
696 * been reserved for name. This includes \0 terminating character.
697 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
698 * must be initialised before using it.
699 * @pre \code name != 0 \endcode The pointer to the name string
700 * must not be a NULL pointer.
701 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
702 * has occurred (source string longer than destination string).
704 tng_function_status DECLSPECDLLEXPORT tng_first_program_name_get
705 (const tng_trajectory_t tng_data,
706 char *name, const int max_len);
709 * @brief Set the name of the program used when creating the trajectory.
710 * @param tng_data the trajectory of which to set the program name.
711 * @param new_name is a string containing the wanted name.
712 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
713 * must be initialised before using it.
714 * @pre \code new_name != 0 \endcode The pointer to the new_name string
715 * must not be a NULL pointer.
716 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
719 tng_function_status DECLSPECDLLEXPORT tng_first_program_name_set
720 (tng_trajectory_t tng_data,
721 const char *new_name);
724 * @brief Get the name of the program used when last modifying the trajectory.
725 * @param tng_data the trajectory of which to get the program name.
726 * @param name the string to fill with the name of the program,
727 * memory must be allocated before.
728 * @param max_len maximum char length of the string, i.e. how much memory has
729 * been reserved for name. This includes \0 terminating character.
730 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
731 * must be initialised before using it.
732 * @pre \code name != 0 \endcode The pointer to the name string
733 * must not be a NULL pointer.
734 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
735 * has occurred (source string longer than destination string).
737 tng_function_status DECLSPECDLLEXPORT tng_last_program_name_get
738 (const tng_trajectory_t tng_data,
739 char *name, const int max_len);
742 * @brief Set the name of the program used when last modifying the trajectory.
743 * @param tng_data the trajectory of which to set the program name.
744 * @param new_name is a string containing the wanted name.
745 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
746 * must be initialised before using it.
747 * @pre \code new_name != 0 \endcode The pointer to the new_name string
748 * must not be a NULL pointer.
749 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
752 tng_function_status DECLSPECDLLEXPORT tng_last_program_name_set
753 (tng_trajectory_t tng_data,
754 const char *new_name);
757 * @brief Get the name of the user who created the trajectory.
758 * @param tng_data the trajectory of which to get the user name.
759 * @param name the string to fill with the name of the user,
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_user_name_get
771 (const tng_trajectory_t tng_data,
772 char *name, const int max_len);
775 * @brief Set the name of the user who created the trajectory.
776 * @param tng_data the trajectory of which to set the user 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_user_name_set
786 (tng_trajectory_t tng_data,
787 const char *new_name);
790 * @brief Get the name of the user who last modified the trajectory.
791 * @param tng_data the trajectory of which to get the user name.
792 * @param name the string to fill with the name of the user,
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_user_name_get
804 (const tng_trajectory_t tng_data,
805 char *name, const int max_len);
808 * @brief Set the name of the user who last modified the trajectory.
809 * @param tng_data the trajectory of which to set the user 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_user_name_set
819 (tng_trajectory_t tng_data,
820 const char *new_name);
823 * @brief Get the name of the computer used when creating the trajectory.
824 * @param tng_data the trajectory of which to get the computer name.
825 * @param name the string to fill with the name of the computer,
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_computer_name_get
837 (const tng_trajectory_t tng_data,
838 char *name, const int max_len);
841 * @brief Set the name of the computer used when creating the trajectory.
842 * @param tng_data the trajectory of which to set the computer 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_computer_name_set
852 (tng_trajectory_t tng_data,
853 const char *new_name);
856 * @brief Get the name of the computer used when last modifying the trajectory.
857 * @param tng_data the trajectory of which to get the computer name.
858 * @param name the string to fill with the name of the computer,
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_computer_name_get
870 (const tng_trajectory_t tng_data,
871 char *name, const int max_len);
874 * @brief Set the name of the computer used when last modifying the trajectory.
875 * @param tng_data the trajectory of which to set the computer 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_computer_name_set
885 (tng_trajectory_t tng_data,
886 const char *new_name);
889 * @brief Get the pgp_signature of the user creating the trajectory.
890 * @param tng_data the trajectory of which to get the computer name.
891 * @param signature the string to fill with the signature,
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 signature != 0 \endcode The pointer to the signature
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_signature_get
903 (const tng_trajectory_t tng_data,
904 char *signature, const int max_len);
907 * @brief Set the pgp_signature of the user creating the trajectory.
908 * @param tng_data the trajectory of which to set the computer name.
909 * @param signature is a string containing the pgp_signature.
910 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
911 * must be initialised before using it.
912 * @pre \code signature != 0 \endcode The pointer to the signature
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_signature_set
918 (tng_trajectory_t tng_data,
919 const char *signature);
922 * @brief Get the pgp_signature of the user last modifying the trajectory.
923 * @param tng_data the trajectory of which to get the computer name.
924 * @param signature the string to fill with the signature,
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 signature != 0 \endcode The pointer to the signature
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_signature_get
936 (const tng_trajectory_t tng_data,
937 char *signature, const int max_len);
940 * @brief Set the pgp_signature of the user last modifying the trajectory.
941 * @param tng_data the trajectory of which to set the computer name.
942 * @param signature is a string containing the pgp_signature.
943 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
944 * must be initialised before using it.
945 * @pre \code signature != 0 \endcode The pointer to the signature
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_signature_set
951 (tng_trajectory_t tng_data,
952 const char *signature);
955 * @brief Get the name of the forcefield used in the trajectory.
956 * @param tng_data the trajectory of which to get the forcefield name.
957 * @param name the string to fill with the name of the forcefield,
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 name != 0 \endcode The pointer to the name string
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_forcefield_name_get
969 (const tng_trajectory_t tng_data,
970 char *name, const int max_len);
973 * @brief Set the name of the forcefield used in the trajectory.
974 * @param tng_data the trajectory of which to set the forcefield name.
975 * @param new_name is a string containing the wanted name.
976 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
977 * must be initialised before using it.
978 * @pre \code new_name != 0 \endcode The pointer to the new_name string
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_forcefield_name_set
984 (tng_trajectory_t tng_data,
985 const char *new_name);
988 * @brief Get the medium stride length of the trajectory.
989 * @param tng_data is the trajectory from which to get the stride length.
990 * @param len is pointing to a value set to the stride length.
991 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
992 * must be initialised before using it.
993 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer.
994 * @return TNG_SUCCESS (0) if successful.
996 tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_get
997 (const tng_trajectory_t tng_data,
1001 * @brief Set the medium stride length of the trajectory.
1002 * @param tng_data is the trajectory of which to set the stride length.
1003 * @param len is the wanted medium stride length.
1004 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1005 * must be initialised before using it.
1006 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1009 tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_set
1010 (tng_trajectory_t tng_data,
1014 * @brief Get the long stride length of the trajectory.
1015 * @param tng_data is the trajectory from which to get the stride length.
1016 * @param len is pointing to a value set to the stride length.
1017 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1018 * must be initialised before using it.
1019 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer.
1020 * @return TNG_SUCCESS (0) if successful.
1022 tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_get
1023 (const tng_trajectory_t tng_data,
1027 * @brief Set the long stride length of the trajectory.
1028 * @param tng_data is the trajectory of which to set the stride length.
1029 * @param len is the wanted long stride length.
1030 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1031 * must be initialised before using it.
1032 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1035 tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_set
1036 (tng_trajectory_t tng_data,
1040 * @brief Get the current time per frame of the trajectory.
1041 * @param tng_data is the trajectory from which to get the time per frame.
1042 * @param time is pointing to a value set to the time per frame.
1043 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1044 * must be initialised before using it.
1045 * @pre \code time != 0 \endcode The pointer to time must not be a NULL pointer.
1046 * @return TNG_SUCCESS (0) if successful.
1048 tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_get
1049 (const tng_trajectory_t tng_data,
1053 * @brief Set the time per frame of the trajectory.
1054 * @param tng_data is the trajectory of which to set the time per frame.
1055 * @param time is the new time per frame.
1056 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1057 * must be initialised before using it.
1058 * @pre \code time > 0 \endcode The time per frame must be >= 0.
1059 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1062 tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_set
1063 (tng_trajectory_t tng_data,
1067 * @brief Get the length of the input file.
1068 * @param tng_data is the trajectory from which to get the input file length.
1069 * @param len is pointing to a value set to the file length.
1070 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1071 * must be initialised before using it.
1072 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer.
1073 * @return TNG_SUCCESS (0) if successful.
1075 tng_function_status DECLSPECDLLEXPORT tng_input_file_len_get
1076 (const tng_trajectory_t tng_data,
1080 * @brief Get the number of frames in the trajectory
1081 * @param tng_data is the trajectory of which to get the number of frames.
1082 * @param n is pointing to a value set to the number of frames.
1083 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1084 * must be initialised before using it.
1085 * @pre \code tng_data->input_file != 0 \endcode An input file must be open
1086 * to find the next frame set.
1087 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1088 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1089 * has occurred (could not find last frame set).
1091 tng_function_status DECLSPECDLLEXPORT tng_num_frames_get
1092 (const tng_trajectory_t tng_data,
1096 * @brief Get the precision of lossy compression.
1097 * @param tng_data is the trajectory of which to get the compression precision.
1098 * @param precision will be pointing to the retrieved compression precision.
1099 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1100 * must be initialised before using it.
1101 * @details A compression precision of 0.001 (the default) means that the
1102 * compressed values are accurate to the third decimal. This function does
1103 * not check actual precision of compressed data, but just returns what has
1104 * previously been set using tng_compression_precision_set().
1105 * @return TNG_SUCCESS (0) if successful.
1107 tng_function_status DECLSPECDLLEXPORT tng_compression_precision_get
1108 (const tng_trajectory_t tng_data,
1112 * @brief Set the precision of lossy compression.
1113 * @param tng_data is the trajectory of which to set the compression precision.
1114 * @param precision is the new compression precision.
1115 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1116 * must be initialised before using it.
1117 * @details A compression precision of 0.001 (the default) means that the
1118 * compressed values are accurate to the third decimal.
1119 * @return TNG_SUCCESS (0) if successful.
1121 tng_function_status DECLSPECDLLEXPORT tng_compression_precision_set
1122 (tng_trajectory_t tng_data,
1123 const double precision);
1126 * @brief Set the number of particles, in the case no molecular system is used.
1127 * @param tng_data is the trajectory of which to get the number of particles.
1128 * @param n is the number of particles to use.
1129 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1130 * must be initialised before using it.
1131 * @details When creating a molecular system the number of particles are set
1132 * automatically. This should only be used when there is no molecular system
1133 * specified or if the number of atoms needs to be overridden for some reason.
1134 * @return TNG_SUCCESS (0) if successful.
1136 tng_function_status DECLSPECDLLEXPORT tng_implicit_num_particles_set
1137 (tng_trajectory_t tng_data,
1141 * @brief Get the current number of particles.
1142 * @param tng_data is the trajectory from which to get the number of particles.
1143 * @param n is pointing to a value set to the number of particles.
1144 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1145 * must be initialised before using it.
1146 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1147 * @details If variable number of particles are used this function will return
1148 * the number of particles in the current frame set.
1149 * @return TNG_SUCCESS (0) if successful.
1151 tng_function_status DECLSPECDLLEXPORT tng_num_particles_get
1152 (const tng_trajectory_t tng_data,
1156 * @brief Get if the number of particle can be varied during the simulation.
1157 * @param tng_data is the trajectory from which to get the number of particles.
1158 * @param variable is pointing to a value set to TNG_CONSTANT_N_ATOMS if the
1159 * number of particles cannot change or TNG_VARIABLE_N_ATOMS if the number of
1160 * particles can change.
1161 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1162 * must be initialised before using it.
1163 * @pre \code variable != 0 \endcode The pointer to variable must not be
1165 * @return TNG_SUCCESS (0) if successful.
1167 tng_function_status DECLSPECDLLEXPORT tng_num_particles_variable_get
1168 (const tng_trajectory_t tng_data,
1172 * @brief Get the number of molecule types (length of tng_data->molecules).
1173 * @param tng_data is the trajectory from which to get the number of molecules.
1174 * @param n is pointing to a value set to the number of molecule types.
1175 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1176 * must be initialised before using it.
1177 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1178 * @return TNG_SUCCESS (0) if successful.
1180 tng_function_status DECLSPECDLLEXPORT tng_num_molecule_types_get
1181 (const tng_trajectory_t tng_data,
1185 * @brief Get the current total number of molecules.
1186 * @param tng_data is the trajectory from which to get the number of molecules.
1187 * @param n is pointing to a value set to the number of molecules.
1188 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1189 * must be initialised before using it.
1190 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1191 * @details If variable number of particles are used this function will return
1192 * the total number of molecules in the current frame set.
1193 * @return TNG_SUCCESS (0) if successful.
1195 tng_function_status DECLSPECDLLEXPORT tng_num_molecules_get
1196 (const tng_trajectory_t tng_data,
1199 /** @brief Get the list of the count of each molecule.
1200 * @param tng_data is the trajectory from which to get the molecule count list.
1201 * @param mol_cnt_list is a list of the count of each molecule in the
1202 * mol system. This is a pointer to the list in the TNG container, which
1203 * means that it should be handled carefully, e.g. not freed.
1204 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1205 * must be initialised before using it.
1206 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE(1) if the list of
1207 * molecule counts was not valid.
1209 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_list_get
1210 (const tng_trajectory_t tng_data,
1211 int64_t **mol_cnt_list);
1214 * @brief Get the exponent used for distances in the trajectory.
1215 * @param tng_data is the trajectory from which to get the information.
1216 * @param exp is pointing to a value set to the distance unit exponent.
1217 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1218 * must be initialised before using it.
1219 * @pre \code exp != 0 \endcode The pointer to exp must not be a NULL pointer.
1220 * @details Example: If the distances are specified in nm (default) exp is -9.
1221 * If the distances are specified in Ă
exp is -10.
1222 * @return TNG_SUCCESS (0) if successful.
1224 tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_get
1225 (const tng_trajectory_t tng_data,
1229 * @brief Set the exponent used for distances in the trajectory.
1230 * @param tng_data is the trajectory of which to set the unit exponent.
1231 * @param exp is the distance unit exponent to use.
1232 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1233 * must be initialised before using it.
1234 * @details Example: If the distances are specified in nm (default) exp is -9.
1235 * If the distances are specified in Ă
exp is -10.
1236 * @return TNG_SUCCESS (0) if successful.
1238 tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_set
1239 (const tng_trajectory_t tng_data,
1243 * @brief Get the number of frames per frame set.
1244 * @param tng_data is the trajectory from which to get the number of frames
1246 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1247 * must be initialised before using it.
1248 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1249 * @param n is pointing to a value set to the number of frames per frame set.
1250 * @return TNG_SUCCESS (0) if successful.
1252 tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_get
1253 (const tng_trajectory_t tng_data,
1257 * @brief Set the number of frames per frame set.
1258 * @param tng_data is the trajectory of which to set the number of frames
1260 * @param n is the number of frames per frame set.
1261 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1262 * must be initialised before using it.
1263 * @details This does not affect already existing frame sets. For
1264 * consistency the number of frames per frame set should be set
1265 * betfore creating any frame sets.
1266 * @return TNG_SUCCESS (0) if successful.
1268 tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_set
1269 (const tng_trajectory_t tng_data,
1273 * @brief Get the number of frame sets.
1274 * @details This updates tng_data->n_trajectory_frame_sets before returning it.
1275 * @param tng_data is the trajectory from which to get the number of frame sets.
1276 * @param n is pointing to a value set to the number of frame sets.
1277 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1278 * must be initialised before using it.
1279 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1280 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1281 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1283 tng_function_status DECLSPECDLLEXPORT tng_num_frame_sets_get
1284 (const tng_trajectory_t tng_data,
1288 * @brief Get the current trajectory frame set.
1289 * @param tng_data is the trajectory from which to get the frame set.
1290 * @param frame_set_p will be set to point at the memory position of
1291 * the found frame set.
1292 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1293 * must be initialised before using it.
1294 * @return TNG_SUCCESS (0) if successful.
1296 tng_function_status DECLSPECDLLEXPORT tng_current_frame_set_get
1297 (const tng_trajectory_t tng_data,
1298 tng_trajectory_frame_set_t *frame_set_p);
1301 * @brief Find the requested frame set number.
1302 * @param tng_data is the trajectory from which to get the frame set.
1303 * @param nr is the frame set number to search for.
1304 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1305 * must be initialised before using it.
1306 * @pre \code nr >= 0 \endcode The frame set number (nr) must be >= 0.
1307 * @details tng_data->current_trajectory_frame_set will contain the
1308 * found trajectory if successful.
1309 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1310 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1312 tng_function_status DECLSPECDLLEXPORT tng_frame_set_nr_find
1313 (tng_trajectory_t tng_data,
1317 * @brief Find the frame set containing a specific frame.
1318 * @param tng_data is the trajectory from which to get the frame set.
1319 * @param frame is the frame number to search for.
1320 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1321 * must be initialised before using it.
1322 * @pre \code frame >= 0 \endcode The frame number must be >= 0.
1323 * @details tng_data->current_trajectory_frame_set will contain the
1324 * found trajectory if successful.
1325 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1326 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1328 tng_function_status DECLSPECDLLEXPORT tng_frame_set_of_frame_find
1329 (tng_trajectory_t tng_data,
1330 const int64_t frame);
1333 * @brief Get the file position of the next frame set in the input file.
1334 * @param tng_data is a trajectory data container.
1335 * @param frame_set is the frame set of which to get the position of the
1336 * following frame set.
1337 * @param pos is pointing to a value set to the file position.
1338 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1339 * must be initialised before using it.
1340 * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer.
1341 * @return TNG_SUCCESS (0) if successful.
1343 tng_function_status DECLSPECDLLEXPORT tng_frame_set_next_frame_set_file_pos_get
1344 (const tng_trajectory_t tng_data,
1345 const tng_trajectory_frame_set_t frame_set,
1349 * @brief Get the file position of the previous frame set in the input file.
1350 * @param tng_data is a trajectory data container.
1351 * @param frame_set is the frame set of which to get the position of the
1352 * previous frame set.
1353 * @param pos is pointing to a value set to the file position.
1354 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1355 * must be initialised before using it.
1356 * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer.
1357 * @return TNG_SUCCESS (0) if successful.
1359 tng_function_status DECLSPECDLLEXPORT tng_frame_set_prev_frame_set_file_pos_get
1360 (const tng_trajectory_t tng_data,
1361 const tng_trajectory_frame_set_t frame_set,
1365 * @brief Get the first and last frames of the frame set.
1366 * @param tng_data is a trajectory data container.
1367 * @param frame_set is the frame set of which to get the frame range.
1368 * @param first_frame is set to the first frame of the frame set.
1369 * @param last_frame is set to the last frame of the frame set.
1370 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1371 * must be initialised before using it.
1372 * @pre \code first_frame != 0 \endcode The pointer to first_frame must
1373 * not be a NULL pointer.
1374 * @pre \code last_frame != 0 \endcode The pointer to last_frame must
1375 * not be a NULL pointer.
1376 * @return TNG_SUCCESS (0) if successful.
1378 tng_function_status DECLSPECDLLEXPORT tng_frame_set_frame_range_get
1379 (const tng_trajectory_t tng_data,
1380 const tng_trajectory_frame_set_t frame_set,
1381 int64_t *first_frame,
1382 int64_t *last_frame);
1385 * @brief Allocate memory for and setup a molecule container.
1386 * @param tng_data is a trajectory data container.
1387 * @param molecule_p is a pointer to molecule to allocate and initialise.
1388 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1389 * error has occured.
1391 tng_function_status DECLSPECDLLEXPORT tng_molecule_alloc(const tng_trajectory_t tng_data,
1392 tng_molecule_t *molecule_p);
1395 * @brief Clean up a molecule container and free its allocated memory.
1396 * @param tng_data is a trajectory data container.
1397 * @param molecule_p is the molecule to destroy.
1398 * @details All allocated memory in the data structure is freed and also the memory
1399 * of the molecule itself.
1400 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1401 * error has occured.
1403 tng_function_status DECLSPECDLLEXPORT tng_molecule_free(const tng_trajectory_t tng_data,
1404 tng_molecule_t *molecule_p);
1407 * @brief Setup a molecule container.
1408 * @param tng_data is a trajectory data container.
1409 * @param molecule is the molecule to initialise. Memory must be preallocated.
1410 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1411 * error has occured.
1413 tng_function_status DECLSPECDLLEXPORT tng_molecule_init
1414 (const tng_trajectory_t tng_data,
1415 tng_molecule_t molecule);
1418 * @brief Clean up a molecule container.
1419 * @param tng_data is a trajectory data container.
1420 * @param molecule is the molecule to destroy.
1421 * @details All allocated memory in the data structure is freed, but not the
1422 * memory of molecule itself.
1423 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1424 * error has occured.
1426 tng_function_status DECLSPECDLLEXPORT tng_molecule_destroy
1427 (const tng_trajectory_t tng_data,
1428 tng_molecule_t molecule);
1431 * @brief Add a molecule to the trajectory.
1432 * @param tng_data is the trajectory data container containing the block..
1433 * @param name is a pointer to the string containing the name of the new molecule.
1434 * @param molecule is a pointer to the newly created molecule.
1435 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1436 * must be initialised before using it.
1437 * @pre \code name != 0 \endcode The pointer to the name string
1438 * must not be a NULL pointer.
1439 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1440 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1442 tng_function_status DECLSPECDLLEXPORT tng_molecule_add
1443 (tng_trajectory_t tng_data,
1445 tng_molecule_t *molecule);
1448 * @brief Add a molecule with a specific ID to the trajectory.
1449 * @param tng_data is the trajectory data container containing the block..
1450 * @param name is a pointer to the string containing the name of the new molecule.
1451 * @param id is the ID of the created molecule.
1452 * @param molecule is a pointer to the newly created molecule.
1453 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1454 * must be initialised before using it.
1455 * @pre \code name != 0 \endcode The pointer to the name string
1456 * must not be a NULL pointer.
1457 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1458 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1460 tng_function_status DECLSPECDLLEXPORT tng_molecule_w_id_add
1461 (tng_trajectory_t tng_data,
1464 tng_molecule_t *molecule);
1467 * @brief Add an existing molecule (from a molecule container) to the trajectory.
1468 * @param tng_data is the trajectory data container containing the block..
1469 * @param molecule is a pointer to the molecule to add to the trajectory and will
1470 * afterwards point to the molecule in the trajectory.
1471 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1472 * must be initialised before using it.
1473 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error
1476 tng_function_status DECLSPECDLLEXPORT tng_molecule_existing_add
1477 (tng_trajectory_t tng_data,
1478 tng_molecule_t *molecule);
1481 * @brief Get the name of a molecule.
1482 * @param tng_data the trajectory containing the molecule.
1483 * @param molecule the molecule of which to get the name.
1484 * @param name the string to fill with the name of the molecule,
1485 * memory must be allocated before.
1486 * @param max_len maximum char length of the string, i.e. how much memory has
1487 * been reserved for name. This includes \0 terminating character.
1488 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1489 * @pre \code name != 0 \endcode The pointer to the name string
1490 * must not be a NULL pointer.
1491 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1492 * has occurred (source string longer than destination string).
1494 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_get
1495 (const tng_trajectory_t tng_data,
1496 const tng_molecule_t molecule,
1501 * @brief Set the name of a molecule.
1502 * @param tng_data is the trajectory data container containing the molecule..
1503 * @param molecule is the molecule to rename.
1504 * @param new_name is a string containing the wanted name.
1505 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1506 * must be initialised before using it.
1507 * @pre \code new_name != 0 \endcode The pointer to the name string
1508 * must not be a NULL pointer.
1509 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1510 * error has occured.
1512 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_set
1513 (tng_trajectory_t tng_data,
1514 tng_molecule_t molecule,
1515 const char *new_name);
1518 * @brief Get the count of a molecule.
1519 * @param tng_data is the trajectory data container containing the molecule..
1520 * @param molecule is the molecule of which to get the count.
1521 * @param cnt is a pointer to the variable to be populated with the count.
1522 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1523 * must be initialised before using it.
1524 * @pre \code cnt != 0 \endcode The pointer to the molecule count
1525 * must not be a NULL pointer.
1526 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1527 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1529 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_get
1530 (const tng_trajectory_t tng_data,
1531 const tng_molecule_t molecule,
1535 * @brief Set the count of a molecule.
1536 * @param tng_data is the trajectory data container containing the molecule..
1537 * @param molecule is the molecule of which to set the count.
1538 * @param cnt is the number of instances of this molecule.
1539 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1540 * must be initialised before using it.
1541 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1542 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1544 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_set
1545 (tng_trajectory_t tng_data,
1546 tng_molecule_t molecule,
1550 * @brief Find a molecule.
1551 * @param tng_data is the trajectory data container containing the molecule.
1552 * @param name is a string containing the name of the molecule. If name is empty
1553 * only id will be used for finding the molecule.
1554 * @param id is the id of the molecule to look for. If id is -1 only the name of
1555 * the molecule will be used for finding the molecule.
1556 * @param molecule is a pointer to the molecule if it was found - otherwise 0.
1557 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1558 * must be initialised before using it.
1559 * @pre \code name != 0 \endcode The pointer to the name string
1560 * must not be a NULL pointer.
1561 * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the
1562 * molecule is not found.
1563 * @details If name is an empty string and id == -1 the first residue will
1566 tng_function_status DECLSPECDLLEXPORT tng_molecule_find
1567 (tng_trajectory_t tng_data,
1570 tng_molecule_t *molecule);
1573 * @brief Retrieve the molecule with specified index in the list of molecules.
1574 * @param tng_data is the trajectory data container containing the molecule.
1575 * @param index is the index (in tng_data->molecules) of the molecule to return
1576 * @param molecule is a pointer to the molecule if it was found - otherwise 0.
1577 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1578 * must be initialised before using it.
1579 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1580 * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the
1581 * molecule is not found.
1583 tng_function_status DECLSPECDLLEXPORT tng_molecule_of_index_get
1584 (tng_trajectory_t tng_data,
1586 tng_molecule_t *molecule);
1589 * @brief Copy all molecules and the molecule counts from one TNG trajectory
1591 * @param tng_data_src is the source trajectory containing the molecular
1593 * @param tng_data_dest is the destination trajectory.
1594 * @pre \code tng_data_src != 0 \endcode The trajectory container (tng_data_src)
1595 * must be initialised before using it.
1596 * @pre \code tng_data_dest != 0 \endcode The trajectory container (tng_data_dest)
1597 * must be initialised before using it.
1598 * @details The molecular system in tng_data_dest will be overwritten.
1599 * @return TNG_SUCCESS(0) if the copying is successful, TNG_FAILURE if a minor
1600 * error has occured or TNG_CRITICAL(2) if a major error has occured.
1602 tng_function_status DECLSPECDLLEXPORT tng_molecule_system_copy(tng_trajectory_t tng_data_src,
1603 tng_trajectory_t tng_data_dest);
1606 * @brief Get the number of chains in a molecule.
1607 * @param tng_data is the trajectory containing the molecule.
1608 * @param molecule is the molecule of which to get the number of chains.
1609 * @param n is pointing to a value set to the number of chains.
1610 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1611 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1612 * @return TNG_SUCCESS (0) if successful.
1614 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_chains_get
1615 (const tng_trajectory_t tng_data,
1616 const tng_molecule_t molecule,
1620 * @brief Retrieve the chain of a molecule with specified index in the list
1622 * @param tng_data is the trajectory data container containing the molecule.
1623 * @param index is the index (in molecule->chains) of the chain to return
1624 * @param molecule is the molecule from which to get the chain.
1625 * @param chain is a pointer to the chain if it was found - otherwise 0.
1626 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1627 * @pre \code chain != 0 \endcode chain must not be a NULL pointer.
1628 * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the
1629 * chain is not found.
1631 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_of_index_get
1632 (tng_trajectory_t tng_data,
1633 tng_molecule_t molecule,
1635 tng_chain_t *chain);
1638 * @brief Get the number of residues in a molecule.
1639 * @param tng_data is the trajectory containing the molecule.
1640 * @param molecule is the molecule of which to get the number residues.
1641 * @param n is pointing to a value set to the number of residues.
1642 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1643 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1644 * @return TNG_SUCCESS (0) if successful.
1646 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_residues_get
1647 (const tng_trajectory_t tng_data,
1648 const tng_molecule_t molecule,
1652 * @brief Retrieve the residue of a molecule with specified index in the list
1654 * @param tng_data is the trajectory data container containing the molecule.
1655 * @param index is the index (in molecule->residues) of the residue to return
1656 * @param molecule is the molecule from which to get the residue.
1657 * @param residue is a pointer to the residue if it was found - otherwise 0.
1658 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1659 * @pre \code residue != 0 \endcode residue must not be a NULL pointer.
1660 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the
1661 * residue is not found.
1663 tng_function_status DECLSPECDLLEXPORT tng_molecule_residue_of_index_get
1664 (const tng_trajectory_t tng_data,
1665 const tng_molecule_t molecule,
1666 const int64_t index,
1667 tng_residue_t *residue);
1670 * @brief Get the number of atoms in a molecule.
1671 * @param tng_data is the trajectory containing the molecule.
1672 * @param molecule is the molecule of which to get the number of atoms.
1673 * @param n is pointing to a value set to the number of atoms.
1674 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1675 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1676 * @return TNG_SUCCESS (0) if successful.
1678 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_atoms_get
1679 (const tng_trajectory_t tng_data,
1680 const tng_molecule_t molecule,
1684 * @brief Retrieve the atom of a molecule with specified index in the list
1686 * @param tng_data is the trajectory data container containing the molecule.
1687 * @param index is the index (in molecule->atoms) of the atom to return
1688 * @param molecule is the molecule from which to get the atom.
1689 * @param atom is a pointer to the atom if it was found - otherwise 0.
1690 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1691 * @pre \code atom != 0 \endcode atom must not be a NULL pointer.
1692 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the
1693 * atom is not found.
1695 tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_of_index_get
1696 (const tng_trajectory_t tng_data,
1697 const tng_molecule_t molecule,
1698 const int64_t index,
1702 * @brief Find a chain in a molecule.
1703 * @param tng_data is the trajectory data container containing the molecule.
1704 * @param molecule is the molecule in which to search for the chain.
1705 * @param name is a string containing the name of the chain. If name is empty
1706 * only id will be used for finding the chain.
1707 * @param id is the id of the chain to look for. If id is -1 only the name of
1708 * the chain will be used for finding the chain.
1709 * @param chain is a pointer to the chain if it was found - otherwise 0.
1710 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1711 * must be initialised before using it.
1712 * @pre \code name != 0 \endcode The pointer to the name string
1713 * must not be a NULL pointer.
1714 * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the
1715 * chain is not found.
1716 * @details If name is an empty string and id == -1 the first residue will
1719 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_find
1720 (tng_trajectory_t tng_data,
1721 tng_molecule_t molecule,
1724 tng_chain_t *chain);
1727 * @brief Add a chain to a molecule.
1728 * @param tng_data is the trajectory data container containing the molecule..
1729 * @param molecule is the molecule to add a chain to.
1730 * @param name is a string containing the name of the chain.
1731 * @param chain is a pointer to the newly created chain.
1732 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1733 * must be initialised before using it.
1734 * @pre \code name != 0 \endcode The pointer to the name string
1735 * must not be a NULL pointer.
1736 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1737 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1739 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_add
1740 (tng_trajectory_t tng_data,
1741 tng_molecule_t molecule,
1743 tng_chain_t *chain);
1746 * @brief Add a chain with a specific id to a molecule.
1747 * @param tng_data is the trajectory data container containing the molecule..
1748 * @param molecule is the molecule to add a chain to.
1749 * @param name is a string containing the name of the chain.
1750 * @param id is the ID of the created chain.
1751 * @param chain is a pointer to the newly created chain.
1752 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1753 * must be initialised before using it.
1754 * @pre \code name != 0 \endcode The pointer to the name string
1755 * must not be a NULL pointer.
1756 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1757 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1759 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_w_id_add
1760 (tng_trajectory_t tng_data,
1761 tng_molecule_t molecule,
1764 tng_chain_t *chain);
1767 * @brief Add a bond between two atoms to a molecule.
1768 * @param tng_data is the trajectory data container containing the molecule.
1769 * @param molecule is the molecule containing the atoms to connect.
1770 * @param from_atom_id is the id of one of the two atoms in the bond.
1771 * @param to_atom_id is the id of the other atom in the bond.
1772 * @param bond is a pointer to the newly created bond.
1773 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1774 * must be initialised before using it.
1775 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (!) if a minor error
1776 * has occured or TNG_CRITICAL (2) if a major error has occured.
1778 tng_function_status DECLSPECDLLEXPORT tng_molecule_bond_add
1779 (const tng_trajectory_t tng_data,
1780 tng_molecule_t molecule,
1781 const int64_t from_atom_id,
1782 const int64_t to_atom_id,
1786 * @brief Find an atom in a molecule.
1787 * @param tng_data is the trajectory data container containing the molecule.
1788 * @param molecule is the molecule in which to search for the atom.
1789 * @param name is a string containing the name of the atom. If name is an
1790 * empty string only id will be used for searching.
1791 * @param id is the id of the atom to find. If id == -1 the first atom
1792 * that matches the specified name will be found.
1793 * @param atom is a pointer to the atom if it was found - otherwise 0.
1794 * @pre \code name != 0 \endcode The pointer to the name string
1795 * must not be a NULL pointer.
1796 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the
1797 * atom is not found.
1798 * @details If name is an empty string and id == -1 the first residue will
1801 tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_find
1802 (tng_trajectory_t tng_data,
1803 tng_molecule_t molecule,
1809 * @brief Get the name of a chain.
1810 * @param tng_data the trajectory containing the chain.
1811 * @param chain the chain of which to get the name.
1812 * @param name the string to fill with the name of the chain,
1813 * memory must be allocated before.
1814 * @param max_len maximum char length of the string, i.e. how much memory has
1815 * been reserved for name. This includes \0 terminating character.
1816 * @pre \code chain != 0 \endcode The chain must not be NULL.
1817 * @pre \code name != 0 \endcode The pointer to the name string
1818 * must not be a NULL pointer.
1819 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1820 * has occurred (source string longer than destination string).
1822 tng_function_status DECLSPECDLLEXPORT tng_chain_name_get
1823 (const tng_trajectory_t tng_data,
1824 const tng_chain_t chain,
1829 * @brief Set the name of a chain.
1830 * @param tng_data is the trajectory data container containing the atom..
1831 * @param chain is the chain to rename.
1832 * @param new_name is a string containing the wanted name.
1833 * @pre \code new_name != 0 \endcode The pointer to the name string
1834 * must not be a NULL pointer.
1835 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1836 * error has occured.
1838 tng_function_status DECLSPECDLLEXPORT tng_chain_name_set
1839 (tng_trajectory_t tng_data,
1841 const char *new_name);
1844 * @brief Get the number of residues in a molecule chain.
1845 * @param tng_data is the trajectory containing the chain.
1846 * @param chain is the chain of which to get the number of residues.
1847 * @param n is pointing to a value set to the number of residues.
1848 * @pre \code chain != 0 \endcode The chain must not be NULL.
1849 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1850 * @return TNG_SUCCESS (0) if successful.
1852 tng_function_status DECLSPECDLLEXPORT tng_chain_num_residues_get
1853 (const tng_trajectory_t tng_data,
1854 const tng_chain_t chain,
1858 * @brief Retrieve the residue of a chain with specified index in the list
1860 * @param tng_data is the trajectory data container containing the chain.
1861 * @param index is the index (in chain->residues) of the residue to return
1862 * @param chain is the chain from which to get the residue.
1863 * @param residue is a pointer to the residue if it was found - otherwise 0.
1864 * @pre \code chain != 0 \endcode chain must not be a NULL pointer.
1865 * @pre \code residue != 0 \endcode residue must not be a NULL pointer.
1866 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the
1867 * residue is not found.
1869 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_of_index_get
1870 (const tng_trajectory_t tng_data,
1871 const tng_chain_t chain,
1872 const int64_t index,
1873 tng_residue_t *residue);
1876 * @brief Find a residue in a chain.
1877 * @param tng_data is the trajectory data container containing the chain.
1878 * @param chain is the chain in which to search for the residue.
1879 * @param name is a string containing the name of the residue. If name is an
1880 * empty string only id will be used for searching.
1881 * @param id is the id of the residue to find. If id == -1 the first residue
1882 * that matches the specified name will be found.
1883 * @param residue is a pointer to the residue if it was found - otherwise 0.
1884 * @pre \code name != 0 \endcode The pointer to the name string
1885 * must not be a NULL pointer.
1886 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the
1887 * residue is not found.
1888 * @details If name is an empty string and id == -1 the first residue will
1891 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_find
1892 (tng_trajectory_t tng_data,
1896 tng_residue_t *residue);
1899 * @brief Add a residue to a chain.
1900 * @param tng_data is the trajectory data container containing the chain..
1901 * @param chain is the chain to add a residue to.
1902 * @param name is a string containing the name of the residue.
1903 * @param residue is a pointer to the newly created residue.
1904 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1905 * must be initialised before using it.
1906 * @pre \code name != 0 \endcode The pointer to the name string
1907 * must not be a NULL pointer.
1908 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1909 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1911 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_add
1912 (tng_trajectory_t tng_data,
1915 tng_residue_t *residue);
1918 * @brief Add a residue with a specific ID to a chain.
1919 * @param tng_data is the trajectory data container containing the chain..
1920 * @param chain is the chain to add a residue to.
1921 * @param name is a string containing the name of the residue.
1922 * @param id is the ID of the created residue.
1923 * @param residue is a pointer to the newly created residue.
1924 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1925 * must be initialised before using it.
1926 * @pre \code name != 0 \endcode The pointer to the name string
1927 * must not be a NULL pointer.
1928 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1929 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1931 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_w_id_add
1932 (tng_trajectory_t tng_data,
1936 tng_residue_t *residue);
1939 * @brief Get the name of a residue.
1940 * @param tng_data the trajectory containing the residue.
1941 * @param residue the residue of which to get the name.
1942 * @param name the string to fill with the name of the residue,
1943 * memory must be allocated before.
1944 * @param max_len maximum char length of the string, i.e. how much memory has
1945 * been reserved for name. This includes \0 terminating character.
1946 * @pre \code residue != 0 \endcode The residue must not be NULL.
1947 * @pre \code name != 0 \endcode The pointer to the name string
1948 * must not be a NULL pointer.
1949 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1950 * has occurred (source string longer than destination string).
1952 tng_function_status DECLSPECDLLEXPORT tng_residue_name_get
1953 (const tng_trajectory_t tng_data,
1954 const tng_residue_t residue,
1959 * @brief Set the name of a residue.
1960 * @param tng_data is the trajectory data container containing the residue.
1961 * @param residue is the residue to rename.
1962 * @param new_name is a string containing the wanted name.
1963 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1964 * must be initialised before using it.
1965 * @pre \code new_name != 0 \endcode The new name to set (new_name) must
1966 * not be a NULL pointer.
1967 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1968 * error has occured.
1970 tng_function_status DECLSPECDLLEXPORT tng_residue_name_set
1971 (tng_trajectory_t tng_data,
1972 tng_residue_t residue,
1973 const char *new_name);
1976 * @brief Get the number of atoms in a residue.
1977 * @param tng_data is the trajectory containing the residue.
1978 * @param residue is the residue of which to get the number atoms.
1979 * @param n is pointing to a value set to the number of atoms.
1980 * @pre \code residue != 0 \endcode The residue must not be NULL.
1981 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1982 * @return TNG_SUCCESS (0) if successful.
1984 tng_function_status DECLSPECDLLEXPORT tng_residue_num_atoms_get
1985 (const tng_trajectory_t tng_data,
1986 const tng_residue_t residue,
1990 * @brief Retrieve the atom of a residue with specified index in the list
1992 * @param tng_data is the trajectory data container containing the residue.
1993 * @param index is the index (in residue->atoms) of the atom to return
1994 * @param residue is the residue from which to get the atom.
1995 * @param atom is a pointer to the atom if it was found - otherwise 0.
1996 * @pre \code residue != 0 \endcode residue must not be a NULL pointer.
1997 * @pre \code atom != 0 \endcode atom must not be a NULL pointer.
1998 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the
1999 * atom is not found.
2001 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_of_index_get
2002 (const tng_trajectory_t tng_data,
2003 const tng_residue_t residue,
2004 const int64_t index,
2008 * @brief Add an atom to a residue.
2009 * @param tng_data is the trajectory containing the residue.
2010 * @param residue is the residue to add an atom to.
2011 * @param atom_name is a string containing the name of the atom.
2012 * @param atom_type is a string containing the atom type of the atom.
2013 * @param atom is a pointer to the newly created atom.
2014 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2015 * must be initialised before using it.
2016 * @pre \code atom_name != 0 \endcode The pointer to the atom name string
2017 * must not be a NULL pointer.
2018 * @pre \code atom_type != 0 \endcode The pointer to the atom_type string
2019 * must not be a NULL pointer.
2020 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
2021 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
2023 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_add
2024 (tng_trajectory_t tng_data,
2025 tng_residue_t residue,
2026 const char *atom_name,
2027 const char *atom_type,
2031 * @brief Add an atom with a specific ID to a residue.
2032 * @param tng_data is the trajectory containing the residue.
2033 * @param residue is the residue to add an atom to.
2034 * @param atom_name is a string containing the name of the atom.
2035 * @param atom_type is a string containing the atom type of the atom.
2036 * @param id is the ID of the created atom.
2037 * @param atom is a pointer to the newly created atom.
2038 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2039 * must be initialised before using it.
2040 * @pre \code atom_name != 0 \endcode The pointer to the atom name string
2041 * must not be a NULL pointer.
2042 * @pre \code atom_type != 0 \endcode The pointer to the atom_type string
2043 * must not be a NULL pointer.
2044 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
2045 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
2047 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_w_id_add
2048 (tng_trajectory_t tng_data,
2049 tng_residue_t residue,
2050 const char *atom_name,
2051 const char *atom_type,
2056 * @brief Get the residue of an atom.
2057 * @param tng_data the trajectory containing the atom.
2058 * @param atom the atom of which to get the name.
2059 * @param residue is set to the residue of the atom.
2060 * @pre \code atom != 0 \endcode The atom must not be NULL.
2061 * @return TNG_SUCCESS (0) if successful.
2063 tng_function_status tng_atom_residue_get(const tng_trajectory_t tng_data,
2064 const tng_atom_t atom,
2065 tng_residue_t *residue);
2068 * @brief Get the name of an atom.
2069 * @param tng_data the trajectory containing the atom.
2070 * @param atom the atom of which to get the name.
2071 * @param name the string to fill with the name of the atom,
2072 * memory must be allocated before.
2073 * @param max_len maximum char length of the string, i.e. how much memory has
2074 * been reserved for name. This includes \0 terminating character.
2075 * @pre \code atom != 0 \endcode The atom must not be NULL.
2076 * @pre \code name != 0 \endcode The pointer to the name string
2077 * must not be a NULL pointer.
2078 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2079 * has occurred (source string longer than destination string).
2081 tng_function_status DECLSPECDLLEXPORT tng_atom_name_get
2082 (const tng_trajectory_t tng_data,
2083 const tng_atom_t atom,
2088 * @brief Set the name of an atom.
2089 * @param tng_data is the trajectory data container containing the atom.
2090 * @param atom is the atom to rename.
2091 * @param new_name is a string containing the wanted name.
2092 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2093 * must be initialised before using it.
2094 * @pre \code new_name != 0 \endcode The pointer to the name string
2095 * must not be a NULL pointer.
2096 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2097 * error has occured.
2099 tng_function_status DECLSPECDLLEXPORT tng_atom_name_set
2100 (tng_trajectory_t tng_data,
2102 const char *new_name);
2105 * @brief Get the type of an atom.
2106 * @param tng_data the trajectory containing the atom.
2107 * @param atom the atom of which to get the type.
2108 * @param type the string to fill with the type of the atom,
2109 * memory must be allocated before.
2110 * @param max_len maximum char length of the string, i.e. how much memory has
2111 * been reserved for type. This includes \0 terminating character.
2112 * @pre \code atom != 0 \endcode The atom must not be NULL.
2113 * @pre \code type != 0 \endcode The pointer to the type string
2114 * must not be a NULL pointer.
2115 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2116 * has occurred (source string longer than destination string).
2118 tng_function_status DECLSPECDLLEXPORT tng_atom_type_get
2119 (const tng_trajectory_t tng_data,
2120 const tng_atom_t atom,
2125 * @brief Set the atom type of an atom.
2126 * @param tng_data is the trajectory data container containing the atom.
2127 * @param atom is the atom to change.
2128 * @param new_type is a string containing the atom type.
2129 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2130 * must be initialised before using it.
2131 * @pre \code new_type != 0 \endcode The pointer to the atom type string
2132 * must not be a NULL pointer.
2133 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2134 * error has occured.
2136 tng_function_status DECLSPECDLLEXPORT tng_atom_type_set
2137 (tng_trajectory_t tng_data,
2139 const char *new_type);
2142 * @brief Get the molecule name of real particle number (number in mol system).
2143 * @param tng_data is the trajectory data container containing the atom.
2144 * @param nr is the real number of the particle in the molecular system.
2145 * @param name is a string, which is set to the name of the molecule. Memory
2146 * must be reserved beforehand.
2147 * @param max_len is the maximum length of name.
2148 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2149 * must be initialised before using it.
2150 * @pre \code name != 0 \endcode The pointer to the name string
2151 * must not be a NULL pointer.
2152 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2155 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_of_particle_nr_get
2156 (const tng_trajectory_t tng_data,
2162 * @brief Get the molecule id of real particle number (number in mol system).
2163 * @param tng_data is the trajectory data container containing the atom.
2164 * @param nr is the real number of the particle in the molecular system.
2165 * @param id is will be set to the id of the molecule.
2166 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2167 * must be initialised before using it.
2168 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer.
2169 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2172 tng_function_status DECLSPECDLLEXPORT tng_molecule_id_of_particle_nr_get
2173 (const tng_trajectory_t tng_data,
2178 * @brief Get the bonds of the current molecular system.
2179 * @param tng_data is the trajectory data container containing the molecular
2181 * @param n_bonds is set to the number of bonds in the molecular system and
2182 * thereby also the lengths of the two lists: from_atoms and to_atoms.
2183 * @param from_atoms is a list (memory reserved by this function) of atoms
2184 * (number of atom in mol system) in bonds.
2185 * @param to_atoms is a list (memory reserved by this function) of atoms
2186 * (number of atom in mol system) in bonds.
2187 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2188 * must be initialised before using it.
2189 * @pre \code n_bonds != 0 \endcode The pointer to n_bonds must not be a
2191 * @pre \code from_atoms != 0 \endcode The pointer to from_atoms must not
2192 * be a NULL pointer.
2193 * @pre \code to_atoms != 0 \endcode The pointer to to_atoms must not
2194 * be a NULL pointer.
2195 * @details The two lists of atoms use the same index, i.e. from_atoms[0]
2196 * and to_atoms[0] are linked with a bond. Since memory is reserved in
2197 * this function it must be freed afterwards.
2198 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2199 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2201 tng_function_status DECLSPECDLLEXPORT tng_molsystem_bonds_get
2202 (const tng_trajectory_t tng_data,
2204 int64_t **from_atoms,
2205 int64_t **to_atoms);
2208 * @brief Get the chain 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 chain. 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_chain_name_of_particle_nr_get
2222 (const tng_trajectory_t tng_data,
2228 * @brief Get the residue name 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 name is a string, which is set to the name of the residue. Memory
2232 * must be reserved beforehand.
2233 * @param max_len is the maximum length of name.
2234 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2235 * must be initialised before using it.
2236 * @pre \code name != 0 \endcode The pointer to the name string
2237 * must not be a NULL pointer.
2238 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2241 tng_function_status DECLSPECDLLEXPORT tng_residue_name_of_particle_nr_get
2242 (const tng_trajectory_t tng_data,
2248 * @brief Get the residue id (local to molecule) of real particle number
2249 * (number in mol system).
2250 * @param tng_data is the trajectory data container containing the atom.
2251 * @param nr is the real number of the particle in the molecular system.
2252 * @param id is a pointer to the variable, which will be set to the ID.
2253 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2254 * must be initialised before using it.
2255 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer.
2256 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2259 tng_function_status DECLSPECDLLEXPORT tng_residue_id_of_particle_nr_get
2260 (const tng_trajectory_t tng_data,
2265 * @brief Get the residue id (based on other molecules and molecule counts)
2266 * of real particle number (number in mol system).
2267 * @param tng_data is the trajectory data container containing the atom.
2268 * @param nr is the real number of the particle in the molecular system.
2269 * @param id is a pointer to the variable, which will be set to the ID.
2270 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2271 * must be initialised before using it.
2272 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer.
2273 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2276 tng_function_status DECLSPECDLLEXPORT tng_global_residue_id_of_particle_nr_get
2277 (const tng_trajectory_t tng_data,
2282 * @brief Get the atom name of real particle number (number in mol system).
2283 * @param tng_data is the trajectory data container containing the atom.
2284 * @param nr is the real number of the particle in the molecular system.
2285 * @param name is a string, which is set to the name of the atom. Memory
2286 * must be reserved beforehand.
2287 * @param max_len is the maximum length of name.
2288 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2289 * must be initialised before using it.
2290 * @pre \code name != 0 \endcode The pointer to the name string
2291 * must not be a NULL pointer.
2292 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2295 tng_function_status DECLSPECDLLEXPORT tng_atom_name_of_particle_nr_get
2296 (const tng_trajectory_t tng_data,
2302 * @brief Get the atom type of real particle number (number in mol system).
2303 * @param tng_data is the trajectory data container containing the atom.
2304 * @param nr is the real number of the particle in the molecular system.
2305 * @param type is a string, which is set to the type of the atom. Memory
2306 * must be reserved beforehand.
2307 * @param max_len is the maximum length of type.
2308 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2309 * must be initialised before using it.
2310 * @pre \code type != 0 \endcode The pointer to the type string
2311 * must not be a NULL pointer.
2312 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2315 tng_function_status DECLSPECDLLEXPORT tng_atom_type_of_particle_nr_get
2316 (const tng_trajectory_t tng_data,
2322 * @brief Add a particle mapping table.
2323 * @details Each particle mapping table will be written as a separate block,
2324 * followed by the data blocks for the corresponding particles. In most cases
2325 * there is one particle mapping block for each thread writing the trajectory.
2326 * @param tng_data is the trajectory, with the frame set to which to add
2327 * the mapping block.
2328 * @details The mapping information is added to the currently active frame set
2330 * @param num_first_particle is the first particle number of this mapping
2332 * @param n_particles is the number of particles in this mapping block.
2333 * @param mapping_table is a list of the real particle numbers (i.e. the numbers
2334 * used in the molecular system). The list is n_particles long.
2335 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2336 * must be initialised before using it.
2337 * @details mapping_table[0] is the real particle number of the first particle
2338 * in the following data blocks.
2339 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2340 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2342 tng_function_status DECLSPECDLLEXPORT tng_particle_mapping_add
2343 (tng_trajectory_t tng_data,
2344 const int64_t num_first_particle,
2345 const int64_t n_particles,
2346 const int64_t *mapping_table);
2349 * @brief Remove all particle mappings (in memory) from the current frame set.
2350 * @details Clears the currently setup particle mappings of the current frame
2352 * @param tng_data is the trajectory, with the frame set of which to clear
2353 * all particle mappings.
2354 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2355 * must be initialised before using it.
2356 * @return TNG_SUCCESS (0) if successful.
2358 tng_function_status DECLSPECDLLEXPORT tng_frame_set_particle_mapping_free
2359 (tng_trajectory_t tng_data);
2362 * @brief Read the header blocks from the input_file of tng_data.
2363 * @details The trajectory blocks must be read separately and iteratively in chunks
2365 * @param tng_data is a trajectory data container.
2366 * @details tng_data->input_file_path specifies
2367 * which file to read from. If the file (input_file) is not open it will be
2369 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2370 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2371 * compared to the md5 hash of the read contents to ensure valid data.
2372 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2373 * must be initialised before using it.
2374 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2375 * error has occured.
2377 tng_function_status DECLSPECDLLEXPORT tng_file_headers_read
2378 (tng_trajectory_t tng_data,
2379 const char hash_mode);
2382 * @brief Write the header blocks to the output_file of tng_data.
2383 * @details The trajectory blocks must be written separately and iteratively in chunks
2385 * @param tng_data is a trajectory data container.
2386 * @details tng_data->output_file_path
2387 * specifies which file to write to. If the file (output_file) is not open it
2389 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2390 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
2391 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2392 * must be initialised before using it.
2393 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2394 * error has occured.
2396 tng_function_status DECLSPECDLLEXPORT tng_file_headers_write
2397 (tng_trajectory_t tng_data,
2398 const char hash_mode);
2401 * @brief Read one (the next) block (of any kind) from the input_file of tng_data.
2402 * @param tng_data is a trajectory data container.
2403 * @details tng_data->input_file_path specifies
2404 * which file to read from. If the file (input_file) is not open it will be
2406 * @param block_data is a pointer to the struct which will be populated with the
2408 * @details If block_data->input_file_pos > 0 it is the position from where the
2409 * reading starts otherwise it starts from the current position.
2410 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2411 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2412 * compared to the md5 hash of the read contents to ensure valid data.
2413 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2414 * must be initialised before using it.
2415 * @pre \code block != 0 \endcode The block container (block) must be
2416 * initialised before using it.
2417 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2418 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2420 tng_function_status DECLSPECDLLEXPORT tng_block_read_next
2421 (tng_trajectory_t tng_data,
2422 tng_gen_block_t block_data,
2423 const char hash_mode);
2426 * @brief Read one frame set, including all particle mapping blocks and data
2427 * blocks, starting from the current file position.
2428 * @param tng_data is a trajectory data container.
2429 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2430 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2431 * compared to the md5 hash of the read contents to ensure valid data.
2432 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2433 * must be initialised before using it.
2434 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2435 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2437 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read
2438 (tng_trajectory_t tng_data,
2439 const char hash_mode);
2442 * @brief Read data from the current frame set from the input_file. Only read
2443 * particle mapping and data blocks matching the specified block_id.
2444 * @param tng_data is a trajectory data container.
2445 * @details tng_data->input_file_path specifies
2446 * which file to read from. If the file (input_file) is not open it will be
2448 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2449 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2450 * compared to the md5 hash of the read contents to ensure valid data.
2451 * @param block_id is the ID of the data block to read from file.
2452 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2453 * must be initialised before using it.
2454 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2455 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2457 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_current_only_data_from_block_id
2458 (tng_trajectory_t tng_data,
2459 const char hash_mode,
2460 const int64_t block_id);
2463 * @brief Read one (the next) frame set, including particle mapping and related data blocks
2464 * from the input_file of tng_data.
2465 * @param tng_data is a trajectory data container.
2466 * @details tng_data->input_file_path specifies
2467 * which file to read from. If the file (input_file) is not open it will be
2469 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2470 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2471 * compared to the md5 hash of the read contents to ensure valid data.
2472 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2473 * must be initialised before using it.
2474 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2475 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2477 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next
2478 (tng_trajectory_t tng_data,
2479 const char hash_mode);
2482 * @brief Read one (the next) frame set, including particle mapping and data blocks with a
2483 * specific block id from the input_file of tng_data.
2484 * @param tng_data is a trajectory data container.
2485 * @details tng_data->input_file_path specifies
2486 * which file to read from. If the file (input_file) is not open it will be
2488 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2489 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2490 * compared to the md5 hash of the read contents to ensure valid data.
2491 * @param block_id is the ID number of the blocks that should be read from file.
2492 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2493 * must be initialised before using it.
2494 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2495 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2497 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next_only_data_from_block_id
2498 (tng_trajectory_t tng_data,
2499 const char hash_mode,
2500 const int64_t block_id);
2503 * @brief Write one frame set, including mapping and related data blocks
2504 * to the output_file of tng_data.
2505 * @param tng_data is a trajectory data container.
2506 * @details tng_data->output_file_path specifies
2507 * which file to write to. If the file (output_file) is not open it will be
2509 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2510 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
2511 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2512 * must be initialised before using it.
2513 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2514 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2516 tng_function_status DECLSPECDLLEXPORT tng_frame_set_write
2517 (tng_trajectory_t tng_data,
2518 const char hash_mode);
2521 * @brief Write one frame set even if it does not have as many frames as
2522 * expected. The function also writes mapping and related data blocks
2523 * to the output_file of tng_data.
2524 * @param tng_data is a trajectory data container.
2525 * @details tng_data->output_file_path specifies
2526 * which file to write to. If the file (output_file) is not open it will be
2528 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2529 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
2530 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2531 * must be initialised before using it.
2532 * @details The number of frames in the frame set is set to the number of
2533 * frames of the data blocks before writing it to disk.
2534 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2535 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2537 tng_function_status DECLSPECDLLEXPORT tng_frame_set_premature_write
2538 (tng_trajectory_t tng_data,
2539 const char hash_mode);
2542 * @brief Create and initialise a frame set.
2543 * @details Particle mappings are retained from previous frame set (if any).
2544 * To explicitly clear particle mappings use tng_frame_set_particle_mapping_free().
2545 * @param tng_data is the trajectory data container in which to add the frame
2547 * @param first_frame is the first frame of the frame set.
2548 * @param n_frames is the number of frames in the frame set.
2549 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2550 * must be initialised before using it.
2551 * @pre \code first_frame >= 0 \endcode The first frame must not be negative.
2552 * @pre \code n_frames >= 0 \endcode The number of frames must not be negative.
2553 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2554 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2556 tng_function_status DECLSPECDLLEXPORT tng_frame_set_new
2557 (tng_trajectory_t tng_data,
2558 const int64_t first_frame,
2559 const int64_t n_frames);
2562 * @brief Create and initialise a frame set with the time of the first frame
2564 * @param tng_data is the trajectory data container in which to add the frame
2566 * @param first_frame is the first frame of the frame set.
2567 * @param n_frames is the number of frames in the frame set.
2568 * @param first_frame_time is the time stamp of the first frame (in seconds).
2569 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2570 * must be initialised before using it.
2571 * @pre \code first_frame >= 0 \endcode The first frame must not be negative.
2572 * @pre \code n_frames >= 0 \endcode The number of frames must not be negative.
2573 * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame
2574 * must not be negative.
2575 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2576 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2578 tng_function_status DECLSPECDLLEXPORT tng_frame_set_with_time_new
2579 (tng_trajectory_t tng_data,
2580 const int64_t first_frame,
2581 const int64_t n_frames,
2582 const double first_frame_time);
2585 * @brief Set the time stamp of the first frame of the current frame set.
2586 * @param tng_data is the trajectory containing the frame set.
2587 * @param first_frame_time is the time stamp of the first frame in the
2589 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2590 * must be initialised before using it.
2591 * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame
2592 * must not be negative.
2593 * @return TNG_SUCCESS (0) if successful.
2595 tng_function_status DECLSPECDLLEXPORT tng_frame_set_first_frame_time_set
2596 (tng_trajectory_t tng_data,
2597 const double first_frame_time);
2600 * @brief Read the number of the first frame of the next frame set.
2601 * @param tng_data is the trajectory containing the frame set.
2602 * @param frame is set to the frame number of the first frame in the
2604 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2605 * must be initialised before using it.
2606 * @pre \code tng_data->input_file != 0 \endcode An input file must be open
2607 * to find the next frame set.
2608 * @pre \code frame != 0 \endcode The pointer to the frame must not be a NULL
2610 * @return TNG_SUCCESS(0) if successful, TNG_FAILURE(1) if there is no next
2611 * frame set or TNG_CRITICAL(2) if a major error has occured.
2613 tng_function_status DECLSPECDLLEXPORT tng_first_frame_nr_of_next_frame_set_get
2614 (const tng_trajectory_t tng_data,
2618 * @brief Add a non-particle dependent data block.
2619 * @param tng_data is the trajectory data container in which to add the data
2621 * @param id is the block ID of the block to add.
2622 * @param block_name is a descriptive name of the block to add
2623 * @param datatype is the datatype of the data in the block (e.g. int/float)
2624 * @param block_type_flag indicates if this is a non-trajectory block (added
2625 * directly to tng_data) or if it is a trajectory block (added to the
2627 * @param n_frames is the number of frames of the data block (automatically
2628 * set to 1 if adding a non-trajectory data block)
2629 * @param n_values_per_frame is how many values a stored each frame (e.g. 9
2630 * for a box shape block)
2631 * @param stride_length is how many frames are between each entry in the
2633 * @param codec_id is the ID of the codec to compress the data.
2634 * @param new_data is an array of data values to add.
2635 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2636 * must be initialised before using it.
2637 * @pre \code block_name != 0 \endcode The pointer to the block name must
2638 * not be a NULL pointer.
2639 * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be
2640 * a positive integer.
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_data_block_add
2645 (tng_trajectory_t tng_data,
2647 const char *block_name,
2648 const char datatype,
2649 const char block_type_flag,
2651 const int64_t n_values_per_frame,
2652 int64_t stride_length,
2653 const int64_t codec_id,
2657 * @brief Add a particle dependent data block.
2658 * @param tng_data is the trajectory data container in which to add the data
2660 * @param id is the block ID of the block to add.
2661 * @param block_name is a descriptive name of the block to add
2662 * @param datatype is the datatype of the data in the block (e.g. int/float)
2663 * @param block_type_flag indicates if this is a non-trajectory block (added
2664 * directly to tng_data) or if it is a trajectory block (added to the
2666 * @param n_frames is the number of frames of the data block (automatically
2667 * set to 1 if adding a non-trajectory data block)
2668 * @param n_values_per_frame is how many values a stored each frame (e.g. 9
2669 * for a box shape block)
2670 * @param stride_length is how many frames are between each entry in the
2672 * @param num_first_particle is the number of the first particle stored
2673 * in this data block
2674 * @param n_particles is the number of particles stored in this data block
2675 * @param codec_id is the ID of the codec to compress the data.
2676 * @param new_data is an array of data values to add.
2677 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2678 * must be initialised before using it.
2679 * @pre \code block_name != 0 \endcode The pointer to the block name must
2680 * not be a NULL pointer.
2681 * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be
2682 * a positive integer.
2683 * @pre \code num_first_particle >= 0 \endcode The number of the
2684 * first particle must be >= 0.
2685 * @pre \code n_particles >= 0 \endcode n_particles must be >= 0.
2686 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2687 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2689 tng_function_status DECLSPECDLLEXPORT tng_particle_data_block_add
2690 (tng_trajectory_t tng_data,
2692 const char *block_name,
2693 const char datatype,
2694 const char block_type_flag,
2696 const int64_t n_values_per_frame,
2697 int64_t stride_length,
2698 const int64_t num_first_particle,
2699 const int64_t n_particles,
2700 const int64_t codec_id,
2703 /** @brief Get the name of a data block of a specific ID.
2704 * @param tng_data is the trajectory data container.
2705 * @param block_id is the ID of the data block of which to get the name.
2706 * @param name is a string, which is set to the name of the data block.
2707 * Memory must be reserved beforehand.
2708 * @param max_len is the maximum length of name.
2709 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2710 * must be initialised before using it.
2711 * @pre \code name != 0 \endcode The pointer to the name string
2712 * must not be a NULL pointer.
2713 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1)
2714 * if a minor error has occured or the data block is not found or
2715 * TNG_CRITICAL (2) if a major error has occured.
2717 tng_function_status DECLSPECDLLEXPORT tng_data_block_name_get
2718 (tng_trajectory_t tng_data,
2723 /** @brief Get the dependency of a data block of a specific ID.
2724 * @param tng_data is the trajectory data container.
2725 * @param block_id is the ID of the data block of which to get the name.
2726 * @param block_dependency is a pointer to the dependency of the data block.
2727 * If the block is frame dependent it will be set to TNG_FRAME_DEPENDENT,
2728 * if it is particle dependent it will be set to TNG_PARTICLE_DEPENDENT and
2729 * if it is both it will be set to TNG_FRAME_DEPENDENT & TNG_PARTICLE_DEPENDENT.
2730 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2731 * must be initialised before using it.
2732 * @pre \code block_dependency != 0 \endcode The pointer to the block dependency
2733 * must not be a NULL pointer.
2734 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1)
2735 * if a minor error has occured or the data block is not found or
2736 * TNG_CRITICAL (2) if a major error has occured.
2738 tng_function_status DECLSPECDLLEXPORT tng_data_block_dependency_get
2739 (const tng_trajectory_t tng_data,
2741 int *block_dependency);
2743 /** @brief Get the number of values per frame of a data block of a specific ID.
2744 * @param tng_data is the trajectory data container.
2745 * @param block_id is the ID of the data block of which to get the name.
2746 * @param n_values_per_frame is a pointer set to the number of values per frame.
2747 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2748 * must be initialised before using it.
2749 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of values
2750 * per frame must not be a NULL pointer.
2751 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1)
2752 * if a minor error has occured or the data block is not found or
2753 * TNG_CRITICAL (2) if a major error has occured.
2755 tng_function_status DECLSPECDLLEXPORT tng_data_block_num_values_per_frame_get
2756 (const tng_trajectory_t tng_data,
2758 int64_t *n_values_per_frame);
2761 * @brief Write data of one trajectory frame to the output_file of tng_data.
2762 * @param tng_data is a trajectory data container. tng_data->output_file_path
2763 * specifies which file to write to. If the file (output_file) is not open it
2765 * @param frame_nr is the index number of the frame to write.
2766 * @param block_id is the ID of the data block to write the data to.
2767 * @param values is an array of data to write. The length of the array should
2768 * equal n_values_per_frame.
2769 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2770 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2771 * compared to the md5 hash of the read contents to ensure valid data.
2772 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2773 * must be initialised before using it.
2774 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
2775 * @pre \code values != 0 \endcode The pointer to the values must not be a NULL
2777 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2778 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2780 tng_function_status DECLSPECDLLEXPORT tng_frame_data_write
2781 (tng_trajectory_t tng_data,
2782 const int64_t frame_nr,
2783 const int64_t block_id,
2785 const char hash_mode);
2788 * @brief Write particle data of one trajectory frame to the output_file of
2790 * @param tng_data is a trajectory data container. tng_data->output_file_path
2791 * specifies which file to write to. If the file (output_file) is not open it
2793 * @param frame_nr is the index number of the frame to write.
2794 * @param block_id is the ID of the data block to write the data to.
2795 * @param val_first_particle is the number of the first particle in the data
2797 * @param val_n_particles is the number of particles in the data array.
2798 * @param values is a 1D-array of data to write. The length of the array should
2799 * equal n_particles * n_values_per_frame.
2800 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2801 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2802 * compared to the md5 hash of the read contents to ensure valid data.
2803 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2804 * must be initialised before using it.
2805 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
2806 * @pre \code val_first_particle >= 0 \endcode The number of the
2807 * first particle must be >= 0.
2808 * @pre \code val_n_particles >= 0 \endcode The number of particles must be >= 0.
2809 * @pre \code values != 0 \endcode The pointer to the values must not be a NULL
2811 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2812 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2814 tng_function_status DECLSPECDLLEXPORT tng_frame_particle_data_write
2815 (tng_trajectory_t tng_data,
2816 const int64_t frame_nr,
2817 const int64_t block_id,
2818 const int64_t val_first_particle,
2819 const int64_t val_n_particles,
2821 const char hash_mode);
2824 * @brief Free data of an array of values (2D).
2825 * @param tng_data is a trajectory data container.
2826 * @param values is the 2D array to free and will be set to 0 afterwards.
2827 * @param n_frames is the number of frames in the data array.
2828 * @param n_values_per_frame is the number of values per frame in the data array.
2829 * @param type is the data type of the data in the array (e.g. int/float/char).
2830 * @return TNG_SUCCESS (0) if successful.
2832 tng_function_status DECLSPECDLLEXPORT tng_data_values_free
2833 (const tng_trajectory_t tng_data,
2834 union data_values **values,
2835 const int64_t n_frames,
2836 const int64_t n_values_per_frame,
2840 * @brief Free data of an array of values (3D).
2841 * @param tng_data is a trajectory data container.
2842 * @param values is the array to free and will be set to 0 afterwards.
2843 * @param n_frames is the number of frames in the data array.
2844 * @param n_particles is the number of particles in the data array.
2845 * @param n_values_per_frame is the number of values per frame in the data array.
2846 * @param type is the data type of the data in the array (e.g. int/float/char).
2847 * @return TNG_SUCCESS (0) if successful.
2849 tng_function_status DECLSPECDLLEXPORT tng_particle_data_values_free
2850 (const tng_trajectory_t tng_data,
2851 union data_values ***values,
2852 const int64_t n_frames,
2853 const int64_t n_particles,
2854 const int64_t n_values_per_frame,
2858 * @brief Retrieve non-particle data, from the last read frame set. Obsolete!
2859 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
2860 * which file to read from. If the file (input_file) is not open it will be
2862 * @param block_id is the id number of the particle data block to read.
2863 * @param values is a pointer to a 2-dimensional array (memory unallocated), which
2864 * will be filled with data. The array will be sized
2865 * (n_frames * n_values_per_frame).
2866 * Since ***values is allocated in this function it is the callers
2867 * responsibility to free the memory.
2868 * @param n_frames is set to the number of frames in the returned data. This is
2869 * needed to properly reach and/or free the data afterwards.
2870 * @param n_values_per_frame is set to the number of values per frame in the data.
2871 * This is needed to properly reach and/or free the data afterwards.
2872 * @param type is set to the data type of the data in the array.
2873 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2874 * must be initialised before using it.
2875 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
2876 * must not be a NULL pointer.
2877 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
2878 * values per frame must not be a NULL pointer.
2879 * @pre \code type != 0 \endcode The pointer to the data type must not
2880 * be a NULL pointer.
2881 * @details This function is obsolete and only retained for compatibility. Use
2882 * tng_data_vector_get() instead.
2883 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2884 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2886 tng_function_status DECLSPECDLLEXPORT tng_data_get(tng_trajectory_t tng_data,
2887 const int64_t block_id,
2888 union data_values ***values,
2890 int64_t *n_values_per_frame,
2894 * @brief Retrieve a vector (1D array) of non-particle data, from the last read frame set.
2895 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
2896 * which file to read from. If the file (input_file) is not open it will be
2898 * @param block_id is the id number of the particle data block to read.
2899 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
2900 * will be filled with data. The length of the array will be (n_frames * n_values_per_frame).
2901 * Since **values is allocated in this function it is the callers
2902 * responsibility to free the memory.
2903 * @param n_frames is set to the number of particles in the returned data. This is
2904 * needed to properly reach and/or free the data afterwards.
2905 * @param stride_length is set to the stride length of the returned data.
2906 * @param n_values_per_frame is set to the number of values per frame in the data.
2907 * This is needed to properly reach and/or free the data afterwards.
2908 * @param type is set to the data type of the data in the array.
2909 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2910 * must be initialised before using it.
2911 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
2912 * must not be a NULL pointer.
2913 * @pre \code stride_length != 0 \endcode The pointer to the stride length
2914 * must not be a NULL pointer.
2915 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
2916 * values per frame must not be a NULL pointer.
2917 * @pre \code type != 0 \endcode The pointer to the data type must not
2918 * be a NULL pointer.
2919 * @details This does only work for numerical (int, float, double) data.
2920 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2921 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2923 tng_function_status DECLSPECDLLEXPORT tng_data_vector_get
2924 (tng_trajectory_t tng_data,
2925 const int64_t block_id,
2928 int64_t *stride_length,
2929 int64_t *n_values_per_frame,
2933 * @brief Read and retrieve non-particle data, in a specific interval. Obsolete!
2934 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
2935 * which file to read from. If the file (input_file) is not open it will be
2937 * @param block_id is the id number of the particle data block to read.
2938 * @param start_frame_nr is the index number of the first frame to read.
2939 * @param end_frame_nr is the index number of the last frame to read.
2940 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2941 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
2942 * compared to the md5 hash of the read contents to ensure valid data.
2943 * @param values is a pointer to a 2-dimensional array (memory unallocated), which
2944 * will be filled with data. The array will be sized
2945 * (n_frames * n_values_per_frame).
2946 * Since ***values is allocated in this function it is the callers
2947 * responsibility to free the memory.
2948 * @param n_values_per_frame is set to the number of values per frame in the data.
2949 * This is needed to properly reach and/or free the data afterwards.
2950 * @param type is set to the data type of the data in the array.
2951 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2952 * must be initialised before using it.
2953 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
2955 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
2956 * values per frame must not be a NULL pointer.
2957 * @pre \code type != 0 \endcode The pointer to the data type must not
2958 * be a NULL pointer.
2959 * @details This function is obsolete and only retained for compatibility. Use
2960 * tng_data_vector_interval_get() instead.
2961 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2962 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2964 tng_function_status DECLSPECDLLEXPORT tng_data_interval_get
2965 (tng_trajectory_t tng_data,
2966 const int64_t block_id,
2967 const int64_t start_frame_nr,
2968 const int64_t end_frame_nr,
2969 const char hash_mode,
2970 union data_values ***values,
2971 int64_t *n_values_per_frame,
2975 * @brief Read and retrieve a vector (1D array) of non-particle data,
2976 * in a specific interval.
2977 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
2978 * which file to read from. If the file (input_file) is not open it will be
2980 * @param block_id is the id number of the particle data block to read.
2981 * @param start_frame_nr is the index number of the first frame to read.
2982 * @param end_frame_nr is the index number of the last frame to read.
2983 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2984 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
2985 * compared to the md5 hash of the read contents to ensure valid data.
2986 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
2987 * will be filled with data. The length of the array will be (n_frames * n_values_per_frame).
2988 * Since **values is allocated in this function it is the callers
2989 * responsibility to free the memory.
2990 * @param stride_length is set to the stride length (writing interval) of
2992 * @param n_values_per_frame is set to the number of values per frame in the data.
2993 * This is needed to properly reach and/or free the data afterwards.
2994 * @param type is set to the data type of the data in the array.
2995 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2996 * must be initialised before using it.
2997 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
2999 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3000 * must not be a NULL pointer.
3001 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3002 * values per frame must not be a NULL pointer.
3003 * @pre \code type != 0 \endcode The pointer to the data type must not
3004 * be a NULL pointer.
3005 * @details This does only work for numerical (int, float, double) data.
3006 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3007 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3009 tng_function_status DECLSPECDLLEXPORT tng_data_vector_interval_get
3010 (tng_trajectory_t tng_data,
3011 const int64_t block_id,
3012 const int64_t start_frame_nr,
3013 const int64_t end_frame_nr,
3014 const char hash_mode,
3016 int64_t *stride_length,
3017 int64_t *n_values_per_frame,
3021 * @brief Retrieve particle data, from the last read frame set. Obsolete!
3022 * @details The particle dimension of the returned values array is translated
3023 * to real particle numbering, i.e. the numbering of the actual molecular
3025 * @param tng_data is a trajectory data container. tng_data->input_file_path
3026 * specifies which file to read from. If the file (input_file) is not open it
3028 * @param block_id is the id number of the particle data block to read.
3029 * @param values is a pointer to a 3-dimensional array (memory unallocated), which
3030 * will be filled with data. The array will be sized
3031 * (n_frames * n_particles * n_values_per_frame).
3032 * Since ****values is allocated in this function it is the callers
3033 * responsibility to free the memory.
3034 * @param n_frames is set to the number of frames in the returned data. This is
3035 * needed to properly reach and/or free the data afterwards.
3036 * @param n_particles is set to the number of particles in the returned data. This is
3037 * needed to properly reach and/or free the data afterwards.
3038 * @param n_values_per_frame is set to the number of values per frame in the data.
3039 * This is needed to properly reach and/or free the data afterwards.
3040 * @param type is set to the data type of the data in the array.
3041 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3042 * must be initialised before using it.
3043 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
3044 * must not be a NULL pointer.
3045 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3046 * not be a NULL pointer.
3047 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3048 * values per frame must not be a NULL pointer.
3049 * @pre \code type != 0 \endcode The pointer to the data type must not
3050 * be a NULL pointer.
3051 * @details This function is obsolete and only retained for compatibility. Use
3052 * tng_particle_data_vector_get() instead.
3053 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3054 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3056 tng_function_status DECLSPECDLLEXPORT tng_particle_data_get
3057 (tng_trajectory_t tng_data,
3058 const int64_t block_id,
3059 union data_values ****values,
3061 int64_t *n_particles,
3062 int64_t *n_values_per_frame,
3066 * @brief Retrieve a vector (1D array) of particle data, from the last read frame set.
3067 * @details The particle dimension of the returned values array is translated
3068 * to real particle numbering, i.e. the numbering of the actual molecular
3070 * @param tng_data is a trajectory data container. tng_data->input_file_path
3071 * specifies which file to read from. If the file (input_file) is not open it
3073 * @param block_id is the id number of the particle data block to read.
3074 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
3075 * will be filled with data. The length of the array will be
3076 * (n_frames * n_particles * n_values_per_frame).
3077 * Since **values is allocated in this function it is the callers
3078 * responsibility to free the memory.
3079 * @param n_frames is set to the number of frames in the returned data. This is
3080 * needed to properly reach and/or free the data afterwards.
3081 * @param stride_length is set to the stride length of the returned data.
3082 * @param n_particles is set to the number of particles in the returned data. This is
3083 * needed to properly reach and/or free the data afterwards.
3084 * @param n_values_per_frame is set to the number of values per frame in the data.
3085 * This is needed to properly reach and/or free the data afterwards.
3086 * @param type is set to the data type of the data in the array.
3087 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3088 * must be initialised before using it.
3089 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3090 * not be a NULL pointer.
3091 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3092 * must not be a NULL pointer.
3093 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3094 * values per frame must not be a NULL pointer.
3095 * @pre \code type != 0 \endcode The pointer to the data type must not
3096 * be a NULL pointer.
3097 * @details This does only work for numerical (int, float, double) data.
3098 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3099 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3101 tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_get
3102 (tng_trajectory_t tng_data,
3103 const int64_t block_id,
3106 int64_t *stride_length,
3107 int64_t *n_particles,
3108 int64_t *n_values_per_frame,
3112 * @brief Read and retrieve particle data, in a specific interval. Obsolete!
3113 * @details The particle dimension of the returned values array is translated
3114 * to real particle numbering, i.e. the numbering of the actual molecular
3116 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
3117 * which file to read from. If the file (input_file) is not open it will be
3119 * @param block_id is the id number of the particle data block to read.
3120 * @param start_frame_nr is the index number of the first frame to read.
3121 * @param end_frame_nr is the index number of the last frame to read.
3122 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3123 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3124 * compared to the md5 hash of the read contents to ensure valid data.
3125 * @param values is a pointer to a 3-dimensional array (memory unallocated), which
3126 * will be filled with data. The array will be sized
3127 * (n_frames * n_particles * n_values_per_frame).
3128 * Since ****values is allocated in this function it is the callers
3129 * responsibility to free the memory.
3130 * @param n_particles is set to the number of particles in the returned data. This is
3131 * needed to properly reach and/or free the data afterwards.
3132 * @param n_values_per_frame is set to the number of values per frame in the data.
3133 * This is needed to properly reach and/or free the data afterwards.
3134 * @param type is set to the data type of the data in the array.
3135 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3136 * must be initialised before using it.
3137 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
3138 * must not be a NULL pointer.
3139 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3141 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3142 * not be a NULL pointer.
3143 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3144 * values per frame must not be a NULL pointer.
3145 * @pre \code type != 0 \endcode The pointer to the data type must not
3146 * be a NULL pointer.
3147 * @details This function is obsolete and only retained for compatibility. Use
3148 * tng_particle_data_vector_interval_get() instead.
3149 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3150 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3152 tng_function_status DECLSPECDLLEXPORT tng_particle_data_interval_get
3153 (tng_trajectory_t tng_data,
3154 const int64_t block_id,
3155 const int64_t start_frame_nr,
3156 const int64_t end_frame_nr,
3157 const char hash_mode,
3158 union data_values ****values,
3159 int64_t *n_particles,
3160 int64_t *n_values_per_frame,
3164 * @brief Read and retrieve a vector (1D array) particle data, in a
3165 * specific interval.
3166 * @details The particle dimension of the returned values array is translated
3167 * to real particle numbering, i.e. the numbering of the actual molecular
3169 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
3170 * which file to read from. If the file (input_file) is not open it will be
3172 * @param block_id is the id number of the particle data block to read.
3173 * @param start_frame_nr is the index number of the first frame to read.
3174 * @param end_frame_nr is the index number of the last frame to read.
3175 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3176 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3177 * compared to the md5 hash of the read contents to ensure valid data.
3178 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
3179 * will be filled with data. The length of the array will be
3180 * (n_frames * n_particles * n_values_per_frame).
3181 * Since **values is allocated in this function it is the callers
3182 * responsibility to free the memory.
3183 * @param stride_length is set to the stride length (writing interval) of
3185 * @param n_particles is set to the number of particles in the returned data. This is
3186 * needed to properly reach and/or free the data afterwards.
3187 * @param n_values_per_frame is set to the number of values per frame in the data.
3188 * This is needed to properly reach and/or free the data afterwards.
3189 * @param type is set to the data type of the data in the array.
3190 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3191 * must be initialised before using it.
3192 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3194 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3195 * not be a NULL pointer.
3196 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3197 * must not be a NULL pointer.
3198 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3199 * values per frame must not be a NULL pointer.
3200 * @pre \code type != 0 \endcode The pointer to the data type must not
3201 * be a NULL pointer.
3202 * @details This does only work for numerical (int, float, double) data.
3203 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3204 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3206 tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_interval_get
3207 (tng_trajectory_t tng_data,
3208 const int64_t block_id,
3209 const int64_t start_frame_nr,
3210 const int64_t end_frame_nr,
3211 const char hash_mode,
3213 int64_t *n_particles,
3214 int64_t *stride_length,
3215 int64_t *n_values_per_frame,
3219 * @brief Get the stride length of a specific data (particle dependency does not matter)
3220 * block, either in the current frame set or of a specific frame.
3221 * @param tng_data is the trajectory data container.
3222 * @param block_id is the block ID of the data block, of which to retrieve the
3223 * stride length of the data.
3224 * @param frame is the frame from which to get the stride length. If frame is set to -1
3225 * no specific frame will be used, but instead the first frame, starting from the last read
3226 * frame set, containing the data block will be used.
3227 * @param stride_length is set to the value of the stride length of the data block.
3228 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3229 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3231 tng_function_status DECLSPECDLLEXPORT tng_data_get_stride_length
3232 (const tng_trajectory_t tng_data,
3233 const int64_t block_id,
3235 int64_t *stride_length);
3238 * @brief Get the date and time of initial file creation in ISO format (string).
3239 * @param tng_data is a trajectory data container.
3240 * @param time is a pointer to the string in which the date will be stored. Memory
3241 * must be reserved beforehand.
3242 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3243 * must be initialised before using it.
3244 * @pre \code time != 0 \endcode The pointer to the time must not be a NULL
3246 * @return TNG_SUCCESS (0) if successful.
3248 tng_function_status DECLSPECDLLEXPORT tng_time_get_str
3249 (const tng_trajectory_t tng_data,
3251 /** @} */ /* end of group1 */
3253 /** @defgroup group2 High-level API
3254 * These functions make it easier to access and output TNG data. They
3255 * are recommended unless there is a special reason to use the more
3256 * detailed functions available in the low-level API.
3261 * @brief High-level function for opening and initializing a TNG trajectory.
3262 * @param filename is a string containing the name of the trajectory to open.
3263 * @param mode specifies the file mode of the trajectory. Can be set to 'r',
3264 * 'w' or 'a' for reading, writing or appending respectively.
3265 * @param tng_data_p is a pointer to the opened trajectory. This will be
3266 * allocated by the TNG library. The trajectory must be
3267 * closed by the user, whereby memory is freed.
3268 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3269 * must be initialised before using it.
3270 * @pre \code filename != 0 \endcode The pointer to the filename must not be a
3272 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3273 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3276 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_open
3277 (const char *filename,
3279 tng_trajectory_t *tng_data_p);
3282 * @brief High-level function for closing a TNG trajectory.
3283 * @param tng_data_p is a pointer to the trajectory to close. The memory
3284 * will be freed after finalising the writing.
3285 * @return TNG_SUCCESS (0) if successful.
3287 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_close
3288 (tng_trajectory_t *tng_data_p);
3291 * @brief High-level function for getting the time (in seconds) of a frame.
3292 * @param tng_data is the trajectory containing the frame.
3293 * @param frame_nr is the frame number of which to get the time.
3294 * @param time is set to the time (in seconds) of the specified frame.
3295 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3296 * must be initialised before using it.
3297 * @pre \code time != 0 \endcode The pointer to the time must not be a
3299 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if a
3300 * minor error has occured.
3302 tng_function_status DECLSPECDLLEXPORT tng_util_time_of_frame_get
3303 (tng_trajectory_t tng_data,
3304 const int64_t frame_nr,
3308 * @brief High-level function for getting the molecules in the mol system.
3309 * @param tng_data is the trajectory containing the mol system.
3310 * @param n_mols is set to the number of molecules in the system.
3311 * @param molecule_cnt_list will be pointing to the list of counts of each molecule
3312 * in the mol system.
3313 * @param mols pointing to the list of molecules in the mol system.
3314 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3315 * must be initialised before using it.
3316 * @pre \code n_mols != 0 \endcode The pointer to the number of molecules must
3317 * not be a NULL pointer.
3318 * @return TNG_SUCCESS (0) if successful.
3320 /*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecules_get
3321 (tng_trajectory_t tng_data,
3323 int64_t **molecule_cnt_list,
3324 tng_molecule_t *mols);
3327 * @brief High-level function for adding a molecule to the mol system.
3328 * @param tng_data is the trajectory containing the mol system.
3329 * @param name is the name of the molecule to add.
3330 * @param cnt is the count of the molecule.
3331 * @param mol is set to point to the newly created molecule.
3332 * @pre \code name != 0 \endcode The pointer to the name must not be a
3334 * @pre \code cnt >= 0 \endcode The requested count must be >= 0.
3335 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3336 * has occured or TNG_CRITICAL (2) if a major error has occured.
3338 /*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecule_add
3339 (tng_trajectory_t tng_data,
3342 tng_molecule_t *mol);
3345 // tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_get
3346 // (tng_trajectory_t tng_data,
3347 // const tng_molecule_t mol,
3348 // int64_t *n_particles,
3351 // char ***res_names,
3352 // int64_t **res_ids,
3353 // char ***chain_names,
3354 // int64_t **chain_ids);
3356 // tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_set
3357 // (tng_trajectory_t tng_data,
3358 // tng_molecule_t mol,
3359 // const int64_t n_particles,
3360 // const char **names,
3361 // const char **types,
3362 // const char **res_names,
3363 // const int64_t *res_ids,
3364 // const char **chain_names,
3365 // const int64_t *chain_ids);
3368 * @brief High-level function for reading the positions of all particles
3370 * @param tng_data is the trajectory to read from.
3371 * @param positions will be set to point at a 1-dimensional array of floats,
3372 * which will contain the positions. The data is stored sequentially in order
3373 * of frames. For each frame the positions (x, y and z coordinates) are stored.
3374 * The variable may point at already allocated memory or be a NULL pointer.
3375 * The memory must be freed afterwards.
3376 * @param stride_length will be set to the writing interval of the stored data.
3377 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3378 * must be initialised before using it.
3379 * @pre \code positions != 0 \endcode The pointer to the positions array
3380 * must not be a NULL pointer.
3381 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3382 * must not be a NULL pointer.
3383 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3384 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3387 tng_function_status DECLSPECDLLEXPORT tng_util_pos_read
3388 (tng_trajectory_t tng_data,
3390 int64_t *stride_length);
3393 * @brief High-level function for reading the velocities of all particles
3395 * @param tng_data is the trajectory to read from.
3396 * @param velocities will be set to point at a 1-dimensional array of floats,
3397 * which will contain the velocities. The data is stored sequentially in order
3398 * of frames. For each frame the velocities (in x, y and z) are stored. The
3399 * variable may point at already allocated memory or be a NULL pointer.
3400 * The memory must be freed afterwards.
3401 * @param stride_length will be set to the writing interval of the stored data.
3402 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3403 * must be initialised before using it.
3404 * @pre \code velocities != 0 \endcode The pointer to the velocities array
3405 * must not be a NULL pointer.
3406 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3407 * must not be a NULL pointer.
3408 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3409 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3412 tng_function_status DECLSPECDLLEXPORT tng_util_vel_read
3413 (tng_trajectory_t tng_data,
3415 int64_t *stride_length);
3418 * @brief High-level function for reading the forces of all particles
3420 * @param tng_data is the trajectory to read from.
3421 * @param forces will be set to point at a 1-dimensional array of floats,
3422 * which will contain the forces. The data is stored sequentially in order
3423 * of frames. For each frame the forces (in x, y and z) are stored. The
3424 * variable may point at already allocated memory or be a NULL pointer.
3425 * The memory must be freed afterwards.
3426 * @param stride_length will be set to the writing interval of the stored data.
3427 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3428 * must be initialised before using it.
3429 * @pre \code forces != 0 \endcode The pointer to the forces array
3430 * must not be a NULL pointer.
3431 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3432 * must not be a NULL pointer.
3433 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3434 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3437 tng_function_status DECLSPECDLLEXPORT tng_util_force_read
3438 (tng_trajectory_t tng_data,
3440 int64_t *stride_length);
3443 * @brief High-level function for reading the box shape from all frames.
3444 * @param tng_data is the trajectory to read from.
3445 * @param box_shape will be set to point at a 1-dimensional array of floats,
3446 * which will contain the box shape. The data is stored sequentially in order
3447 * of frames. The variable may point at already allocated memory or be a NULL pointer.
3448 * If the box shape is not modified during the trajectory, but as general data,
3449 * that will be returned instead.
3450 * @param stride_length will be set to the writing interval of the stored data.
3451 * @details This function should only be used if number of values used to specify
3452 * the box shape is known (by default TNG uses 9 values) since it does not
3453 * return the number of values in the array. It is recommended to use
3454 * tng_data_vector_interval_get() instead.
3455 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3456 * must be initialised before using it.
3457 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array
3458 * must not be a NULL pointer.
3459 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3460 * must not be a NULL pointer.
3461 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3462 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3465 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read
3466 (tng_trajectory_t tng_data,
3468 int64_t *stride_length);
3471 * @brief High-level function for reading the next frame of particle-dependent
3472 * data of a specific type.
3473 * @param tng_data is the trajectory to read from.
3474 * @param block_id is the ID number of the block containing the data of interest.
3475 * @param values will be set to point at a 1-dimensional array containing the
3476 * requested data. The variable may point at already allocated memory or be a
3477 * NULL pointer. The memory must be freed afterwards.
3478 * @param data_type will be pointing to a character indicating the size of the
3479 * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA.
3480 * @param retrieved_frame_number will be pointing at the frame number of the
3482 * @param retrieved_time will be pointing at the time stamp of the returned
3484 * @details If no frame has been read before the first frame of the trajectory
3486 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3487 * must be initialised before using it.
3488 * @pre \code values != 0 \endcode The pointer to the values array
3489 * must not be a NULL pointer.
3490 * @pre \code data_type != 0 \endcode The pointer to the data type of the
3491 * returned data must not be a NULL pointer.
3492 * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame
3493 * number of the returned data must not be a NULL pointer.
3494 * @pre \code retrieved_time != 0 \endcode The pointer to the time of the
3495 * returned data must not be a NULL pointer.
3496 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3497 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3500 tng_function_status DECLSPECDLLEXPORT tng_util_particle_data_next_frame_read
3501 (tng_trajectory_t tng_data,
3502 const int64_t block_id,
3505 int64_t *retrieved_frame_number,
3506 double *retrieved_time);
3509 * @brief High-level function for reading the next frame of non-particle-dependent
3510 * data of a specific type.
3511 * @param tng_data is the trajectory to read from.
3512 * @param block_id is the ID number of the block containing the data of interest.
3513 * @param values will be set to point at a 1-dimensional array containing the
3514 * requested data. The variable may point at already allocated memory or be a
3515 * NULL pointer. The memory must be freed afterwards.
3516 * @param data_type will be pointing to a character indicating the size of the
3517 * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA.
3518 * @param retrieved_frame_number will be pointing at the frame number of the
3520 * @param retrieved_time will be pointing at the time stamp of the returned
3522 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3523 * must be initialised before using it.
3524 * @pre \code values != 0 \endcode The pointer to the values array
3525 * must not be a NULL pointer.
3526 * @pre \code data_type != 0 \endcode The pointer to the data type of the
3527 * returned data must not be a NULL pointer.
3528 * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame
3529 * number of the returned data must not be a NULL pointer.
3530 * @pre \code retrieved_time != 0 \endcode The pointer to the time of the
3531 * returned data must not be a NULL pointer.
3532 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3533 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3536 tng_function_status DECLSPECDLLEXPORT tng_util_non_particle_data_next_frame_read
3537 (tng_trajectory_t tng_data,
3538 const int64_t block_id,
3541 int64_t *retrieved_frame_number,
3542 double *retrieved_time);
3545 * @brief High-level function for reading the positions of all particles
3546 * from a specific range of frames.
3547 * @param tng_data is the trajectory to read from.
3548 * @param first_frame is the first frame to return position data from.
3549 * @param last_frame is the last frame to return position data from.
3550 * @param positions will be set to point at a 1-dimensional array of floats,
3551 * which will contain the positions. The data is stored sequentially in order
3552 * of frames. For each frame the positions (x, y and z coordinates) are stored.
3553 * The variable may point at already allocated memory or be a NULL pointer.
3554 * The memory must be freed afterwards.
3555 * @param stride_length will be set to the writing interval of the stored data.
3556 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3557 * must be initialised before using it.
3558 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3560 * @pre \code positions != 0 \endcode The pointer to the positions array
3561 * must not be a NULL pointer.
3562 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3563 * must not be a NULL pointer.
3564 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3565 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3568 tng_function_status DECLSPECDLLEXPORT tng_util_pos_read_range
3569 (tng_trajectory_t tng_data,
3570 const int64_t first_frame,
3571 const int64_t last_frame,
3573 int64_t *stride_length);
3576 * @brief High-level function for reading the velocities of all particles
3577 * from a specific range of frames.
3578 * @param tng_data is the trajectory to read from.
3579 * @param first_frame is the first frame to return position data from.
3580 * @param last_frame is the last frame to return position data from.
3581 * @param velocities will be set to point at a 1-dimensional array of floats,
3582 * which will contain the velocities. The data is stored sequentially in order
3583 * of frames. For each frame the velocities (in x, y and z) are stored. The
3584 * variable may point at already allocated memory or be a NULL pointer.
3585 * The memory must be freed afterwards.
3586 * @param stride_length will be set to the writing interval of the stored data.
3587 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3588 * must be initialised before using it.
3589 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3591 * @pre \code velocities != 0 \endcode The pointer to the velocities array
3592 * must not be a NULL pointer.
3593 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3594 * must not be a NULL pointer.
3595 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3596 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3599 tng_function_status DECLSPECDLLEXPORT tng_util_vel_read_range
3600 (tng_trajectory_t tng_data,
3601 const int64_t first_frame,
3602 const int64_t last_frame,
3604 int64_t *stride_length);
3607 * @brief High-level function for reading the forces of all particles
3608 * from a specific range of frames.
3609 * @param tng_data is the trajectory to read from.
3610 * @param first_frame is the first frame to return position data from.
3611 * @param last_frame is the last frame to return position data from.
3612 * @param forces will be set to point at a 1-dimensional array of floats,
3613 * which will contain the forces. The data is stored sequentially in order
3614 * of frames. For each frame the forces (in x, y and z) are stored. The
3615 * variable may point at already allocated memory or be a NULL pointer.
3616 * The memory must be freed afterwards.
3617 * @param stride_length will be set to the writing interval of the stored data.
3618 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3619 * must be initialised before using it.
3620 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3622 * @pre \code forces != 0 \endcode The pointer to the forces array
3623 * must not be a NULL pointer.
3624 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3625 * must not be a NULL pointer.
3626 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3627 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3630 tng_function_status DECLSPECDLLEXPORT tng_util_force_read_range
3631 (tng_trajectory_t tng_data,
3632 const int64_t first_frame,
3633 const int64_t last_frame,
3635 int64_t *stride_length);
3638 * @brief High-level function for reading the box shape
3639 * from a specific range of frames.
3640 * @param tng_data is the trajectory to read from.
3641 * @param first_frame is the first frame to return position data from.
3642 * @param last_frame is the last frame to return position data from.
3643 * @param box_shape will be set to point at a 1-dimensional array of floats,
3644 * which will contain the box shape. The data is stored sequentially in order
3646 * If the box shape is not modified during the trajectory, but as general data,
3647 * that will be returned instead. The
3648 * variable may point at already allocated memory or be a NULL pointer.
3649 * The memory must be freed afterwards.
3650 * @param stride_length will be set to the writing interval of the stored data.
3651 * @details This function should only be used if number of values used to specify
3652 * the box shape is known (by default TNG uses 9 values) since it does not
3653 * return the number of values in the array. It is recommended to use
3654 * tng_data_vector_interval_get() instead.
3655 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3656 * must be initialised before using it.
3657 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3659 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array
3660 * must not be a NULL pointer.
3661 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3662 * must not be a NULL pointer.
3663 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3664 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3667 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read_range
3668 (tng_trajectory_t tng_data,
3669 const int64_t first_frame,
3670 const int64_t last_frame,
3672 int64_t *stride_length);
3675 * @brief High-level function for setting the writing interval of data blocks.
3676 * @param tng_data is the trajectory to use.
3677 * @param i is the output interval, i.e. i == 10 means data written every 10th
3679 * @param n_values_per_frame is the number of values to store per frame. If the
3680 * data is particle dependent there will be n_values_per_frame stored per
3681 * particle each frame.
3682 * @param block_id is the ID of the block, of which to set the output interval.
3683 * @param block_name is a string that will be used as name of the block. Only
3684 * required if the block did not exist, i.e. a new block is created.
3685 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
3686 * data is not related to specific particles (e.g. box shape) or
3687 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
3688 * positions). Only required if the block did not exist, i.e. a new block is
3690 * @param compression is the compression routine to use when writing the data.
3691 * Only required if the block did not exist, i.e. a new block is created.
3692 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3693 * must be initialised before using it.
3694 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3695 * @details n_values_per_frame, block_name, particle_dependency and
3696 * compression are only used if the data block did not exist before calling
3697 * this function, in which case it is created.
3698 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3699 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3702 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_set
3703 (tng_trajectory_t tng_data,
3705 const int64_t n_values_per_frame,
3706 const int64_t block_id,
3707 const char *block_name,
3708 const char particle_dependency,
3709 const char compression);
3712 * @brief High-level function for setting the writing interval of data blocks
3713 * containing double precision data.
3714 * @param tng_data is the trajectory to use.
3715 * @param i is the output interval, i.e. i == 10 means data written every 10th
3717 * @param n_values_per_frame is the number of values to store per frame. If the
3718 * data is particle dependent there will be n_values_per_frame stored per
3719 * particle each frame.
3720 * @param block_id is the ID of the block, of which to set the output interval.
3721 * @param block_name is a string that will be used as name of the block. Only
3722 * required if the block did not exist, i.e. a new block is created.
3723 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
3724 * data is not related to specific particles (e.g. box shape) or
3725 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
3726 * positions). Only required if the block did not exist, i.e. a new block is
3728 * @param compression is the compression routine to use when writing the data.
3729 * Only required if the block did not exist, i.e. a new block is created.
3730 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3731 * must be initialised before using it.
3732 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3733 * @details n_values_per_frame, block_name, particle_dependency and
3734 * compression are only used if the data block did not exist before calling
3735 * this function, in which case it is created.
3736 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3737 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3740 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_double_set
3741 (tng_trajectory_t tng_data,
3743 const int64_t n_values_per_frame,
3744 const int64_t block_id,
3745 const char *block_name,
3746 const char particle_dependency,
3747 const char compression);
3750 * @brief High-level function for setting the writing interval of data blocks.
3751 * Obsolete! Use tng_util_generic_write_interval_set()
3752 * @param tng_data is the trajectory to use.
3753 * @param i is the output interval, i.e. i == 10 means data written every 10th
3755 * @param n_values_per_frame is the number of values to store per frame. If the
3756 * data is particle dependent there will be n_values_per_frame stored per
3757 * particle each frame.
3758 * @param block_id is the ID of the block, of which to set the output interval.
3759 * @param block_name is a string that will be used as name of the block. Only
3760 * required if the block did not exist, i.e. a new block is created.
3761 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
3762 * data is not related to specific particles (e.g. box shape) or
3763 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
3764 * positions). Only required if the block did not exist, i.e. a new block is
3766 * @param compression is the compression routine to use when writing the data.
3767 * Only required if the block did not exist, i.e. a new block is created.
3768 * @details n_values_per_frame, block_name, particle_dependency and
3769 * compression are only used if the data block did not exist before calling
3770 * this function, in which case it is created.
3771 * This function is replaced by the more correcly named
3772 * tng_util_generic_write_interval_set(), but is kept for compatibility.
3773 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3774 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3777 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_frequency_set
3778 (tng_trajectory_t tng_data,
3780 const int64_t n_values_per_frame,
3781 const int64_t block_id,
3782 const char *block_name,
3783 const char particle_dependency,
3784 const char compression);
3787 * @brief High-level function for setting the writing interval of position
3789 * @param tng_data is the trajectory to use.
3790 * @param i is the output interval, i.e. i == 10 means data written every 10th
3792 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3793 * must be initialised before using it.
3794 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3795 * @details This function uses tng_util_generic_write_interval_set() and will
3796 * create a positions data block if none exists.
3797 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3798 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3801 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_set
3802 (tng_trajectory_t tng_data,
3806 * @brief High-level function for setting the writing interval of position
3807 * data blocks containing double precision data.
3808 * @param tng_data is the trajectory to use.
3809 * @param i is the output interval, i.e. i == 10 means data written every 10th
3811 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3812 * must be initialised before using it.
3813 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3814 * @details This function uses tng_util_generic_write_interval_set() and will
3815 * create a positions data block if none exists.
3816 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3817 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3820 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_double_set
3821 (tng_trajectory_t tng_data,
3825 * @brief High-level function for setting the writing interval of position
3826 * data blocks. Obsolete! Use tng_util_pos_write_interval_set()
3827 * @param tng_data is the trajectory to use.
3828 * @param i is the output interval, i.e. i == 10 means data written every 10th
3830 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3831 * must be initialised before using it.
3832 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3833 * @details This function uses tng_util_generic_write_interval_set() and will
3834 * create a positions data block if none exists.
3835 * This function is replaced by the more correcly named
3836 * tng_util_pos_write_interval_set(), but is kept for compatibility.
3837 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3838 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3841 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_frequency_set
3842 (tng_trajectory_t tng_data,
3846 * @brief High-level function for setting the writing interval of velocity
3848 * @param tng_data is the trajectory to use.
3849 * @param i is the output interval, i.e. i == 10 means data written every 10th
3851 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3852 * must be initialised before using it.
3853 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3854 * @details This function uses tng_util_generic_write_interval_set() and will
3855 * create a velocities data block if none exists.
3856 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3857 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3860 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_set
3861 (tng_trajectory_t tng_data,
3865 * @brief High-level function for setting the writing interval of velocity
3866 * data blocks containing double precision data.
3867 * @param tng_data is the trajectory to use.
3868 * @param i is the output interval, i.e. i == 10 means data written every 10th
3870 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3871 * must be initialised before using it.
3872 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3873 * @details This function uses tng_util_generic_write_interval_set() and will
3874 * create a velocities data block if none exists.
3875 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3876 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3879 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_double_set
3880 (tng_trajectory_t tng_data,
3884 * @brief High-level function for setting the writing interval of velocity
3885 * data blocks. Obsolete! Use tng_util_vel_write_interval_set()
3886 * @param tng_data is the trajectory to use.
3887 * @param i is the output interval, i.e. i == 10 means data written every 10th
3889 * @details This function uses tng_util_generic_write_interval_set() and will
3890 * create a velocities data block if none exists.
3891 * This function is replaced by the more correcly named
3892 * tng_util_vel_write_interval_set(), but is kept for compatibility.
3893 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3894 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3897 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_frequency_set
3898 (tng_trajectory_t tng_data,
3902 * @brief High-level function for setting the writing interval of force
3904 * @param tng_data is the trajectory to use.
3905 * @param i is the output interval, i.e. i == 10 means data written every 10th
3907 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3908 * must be initialised before using it.
3909 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3910 * @details This function uses tng_util_generic_write_interval_set() and will
3911 * create a forces data block if none exists.
3912 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3913 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3916 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_set
3917 (tng_trajectory_t tng_data,
3921 * @brief High-level function for setting the writing interval of force
3922 * data blocks containing double precision data.
3923 * @param tng_data is the trajectory to use.
3924 * @param i is the output interval, i.e. i == 10 means data written every 10th
3926 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3927 * must be initialised before using it.
3928 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3929 * @details This function uses tng_util_generic_write_interval_set() and will
3930 * create a forces data block if none exists.
3931 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3932 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3935 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_double_set
3936 (tng_trajectory_t tng_data,
3940 * @brief High-level function for setting the writing interval of force
3941 * data blocks. Obsolete! Use tng_util_force_write_interval_set()
3942 * @param tng_data is the trajectory to use.
3943 * @param i is the output interval, i.e. i == 10 means data written every 10th
3945 * @details This function uses tng_util_generic_write_interval_set() and will
3946 * create a forces data block if none exists.
3947 * This function is replaced by the more correcly named
3948 * tng_util_force_write_interval_set(), but is kept for compatibility.
3949 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3950 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3953 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_frequency_set
3954 (tng_trajectory_t tng_data,
3958 * @brief High-level function for setting the writing interval of box shape
3960 * @param tng_data is the trajectory to use.
3961 * @param i is the output interval, i.e. i == 10 means data written every 10th
3963 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3964 * must be initialised before using it.
3965 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3966 * @details This function uses tng_util_generic_write_interval_set() and will
3967 * create a box shape data block if none exists.
3968 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3969 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3972 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_set
3973 (tng_trajectory_t tng_data,
3977 * @brief High-level function for setting the writing interval of box shape
3978 * data blocks containing double precision data.
3979 * @param tng_data is the trajectory to use.
3980 * @param i is the output interval, i.e. i == 10 means data written every 10th
3982 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3983 * must be initialised before using it.
3984 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3985 * @details This function uses tng_util_generic_write_interval_set() and will
3986 * create a box shape data block if none exists.
3987 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3988 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3991 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_double_set
3992 (tng_trajectory_t tng_data,
3996 * @brief High-level function for setting the writing interval of velocity
3997 * data blocks. Obsolete! Use tng_util_box_shape_write_interval_set()
3998 * @param tng_data is the trajectory to use.
3999 * @param i is the output interval, i.e. i == 10 means data written every 10th
4001 * @details This function uses tng_util_generic_write_interval_set() and will
4002 * create a box shape data block if none exists.
4003 * This function is replaced by the more correcly named
4004 * tng_util_box_shape_write_interval_set(), but is kept for compatibility.
4005 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4006 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4009 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_frequency_set
4010 (tng_trajectory_t tng_data,
4014 * @brief High-level function for writing data of one frame to a data block.
4015 * @param tng_data is the trajectory to use.
4016 * @param frame_nr is the frame number of the data.
4017 * @param values is a 1D array of data to add. The array should be of length
4018 * n_particles * n_values_per_frame if writing particle related data, otherwise
4019 * it should be n_values_per_frame.
4020 * @param n_values_per_frame is the number of values to store per frame. If the
4021 * data is particle dependent there will be n_values_per_frame stored per
4022 * particle each frame.
4023 * @param block_id is the ID of the block, of which to set the output interval.
4024 * @param block_name is a string that will be used as name of the block. Only
4025 * required if the block did not exist, i.e. a new block is created.
4026 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4027 * data is not related to specific particles (e.g. box shape) or
4028 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4029 * positions). Only required if the block did not exist, i.e. a new block is
4031 * @param compression is the compression routine to use when writing the data.
4032 * Only required if the block did not exist, i.e. a new block is created.
4033 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4034 * must be initialised before using it.
4035 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4036 * @pre \code values != 0 \endcode The pointer to the values array must not
4037 * be a NULL pointer.
4038 * @details n_values_per_frame, block_name, particle_dependency and
4039 * compression are only used if the data block did not exist before calling
4040 * this function, in which case it is created.
4041 * N.b. Data is written a whole block at a time. The data is not
4042 * actually written to disk until the frame set is finished or the TNG
4043 * trajectory is closed.
4044 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4045 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4048 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write
4049 (tng_trajectory_t tng_data,
4050 const int64_t frame_nr,
4051 const float *values,
4052 const int64_t n_values_per_frame,
4053 const int64_t block_id,
4054 const char *block_name,
4055 const char particle_dependency,
4056 const char compression);
4059 * @brief High-level function for writing data of one frame to a double precision
4061 * @param tng_data is the trajectory to use.
4062 * @param frame_nr is the frame number of the data.
4063 * @param values is a 1D array of data to add. The array should be of length
4064 * n_particles * n_values_per_frame if writing particle related data, otherwise
4065 * it should be n_values_per_frame.
4066 * @param n_values_per_frame is the number of values to store per frame. If the
4067 * data is particle dependent there will be n_values_per_frame stored per
4068 * particle each frame.
4069 * @param block_id is the ID of the block, of which to set the output interval.
4070 * @param block_name is a string that will be used as name of the block. Only
4071 * required if the block did not exist, i.e. a new block is created.
4072 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4073 * data is not related to specific particles (e.g. box shape) or
4074 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4075 * positions). Only required if the block did not exist, i.e. a new block is
4077 * @param compression is the compression routine to use when writing the data.
4078 * Only required if the block did not exist, i.e. a new block is created.
4079 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4080 * must be initialised before using it.
4081 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4082 * @pre \code values != 0 \endcode The pointer to the values array must not
4083 * be a NULL pointer.
4084 * @details n_values_per_frame, block_name, particle_dependency and
4085 * compression are only used if the data block did not exist before calling
4086 * this function, in which case it is created.
4087 * N.b. Data is written a whole block at a time. The data is not
4088 * actually written to disk until the frame set is finished or the TNG
4089 * trajectory is closed.
4090 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4091 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4094 tng_function_status DECLSPECDLLEXPORT tng_util_generic_double_write
4095 (tng_trajectory_t tng_data,
4096 const int64_t frame_nr,
4097 const double *values,
4098 const int64_t n_values_per_frame,
4099 const int64_t block_id,
4100 const char *block_name,
4101 const char particle_dependency,
4102 const char compression);
4105 * @brief High-level function for adding data to positions data blocks.
4106 * @param tng_data is the trajectory to use.
4107 * @param frame_nr is the frame number of the data.
4108 * @param positions is a 1D array of data to add. The array should be of length
4110 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4111 * must be initialised before using it.
4112 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4113 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4114 * be a NULL pointer.
4115 * @details This function uses tng_util_generic_write() and will
4116 * create a positions data block if none exists. Positions are stored as three
4117 * values per frame and compressed using TNG compression.
4118 * N.b. Since compressed data is written a whole block at a time the data is not
4119 * actually written to disk until the frame set is finished or the TNG
4120 * trajectory is closed.
4121 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4122 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4125 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write
4126 (tng_trajectory_t tng_data,
4127 const int64_t frame_nr,
4128 const float *positions);
4131 * @brief High-level function for adding data to positions data blocks at double
4133 * @param tng_data is the trajectory to use.
4134 * @param frame_nr is the frame number of the data.
4135 * @param positions is a 1D array of data to add. The array should be of length
4137 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4138 * must be initialised before using it.
4139 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4140 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4141 * be a NULL pointer.
4142 * @details This function uses tng_util_generic_write() and will
4143 * create a positions data block if none exists. Positions are stored as three
4144 * values per frame and compressed using TNG compression.
4145 * N.b. Since compressed data is written a whole block at a time the data is not
4146 * actually written to disk until the frame set is finished or the TNG
4147 * trajectory is closed.
4148 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4149 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4152 tng_function_status DECLSPECDLLEXPORT tng_util_pos_double_write
4153 (tng_trajectory_t tng_data,
4154 const int64_t frame_nr,
4155 const double *positions);
4158 * @brief High-level function for adding data to velocities data blocks.
4159 * @param tng_data is the trajectory to use.
4160 * @param frame_nr is the frame number of the data.
4161 * @param velocities is a 1D array of data to add. The array should be of length
4163 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4164 * must be initialised before using it.
4165 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4166 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4167 * be a NULL pointer.
4168 * @details This function uses tng_util_generic_write() and will
4169 * create a velocities data block if none exists. Velocities are stored as three
4170 * values per frame and compressed using TNG compression.
4171 * N.b. Since compressed data is written a whole block at a time the data is not
4172 * actually written to disk until the frame set is finished or the TNG
4173 * trajectory is closed.
4174 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4175 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4178 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write
4179 (tng_trajectory_t tng_data,
4180 const int64_t frame_nr,
4181 const float *velocities);
4184 * @brief High-level function for adding data to velocities data blocks at double
4186 * @param tng_data is the trajectory to use.
4187 * @param frame_nr is the frame number of the data.
4188 * @param velocities is a 1D array of data to add. The array should be of length
4190 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4191 * must be initialised before using it.
4192 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4193 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4194 * be a NULL pointer.
4195 * @details This function uses tng_util_generic_write() and will
4196 * create a velocities data block if none exists. Velocities are stored as three
4197 * values per frame and compressed using TNG compression.
4198 * N.b. Since compressed data is written a whole block at a time the data is not
4199 * actually written to disk until the frame set is finished or the TNG
4200 * trajectory is closed.
4201 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4202 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4205 tng_function_status DECLSPECDLLEXPORT tng_util_vel_double_write
4206 (tng_trajectory_t tng_data,
4207 const int64_t frame_nr,
4208 const double *velocities);
4211 * @brief High-level function for adding data to forces data blocks.
4212 * @param tng_data is the trajectory to use.
4213 * @param frame_nr is the frame number of the data.
4214 * @param forces is a 1D array of data to add. The array should be of length
4216 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4217 * must be initialised before using it.
4218 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4219 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4220 * be a NULL pointer.
4221 * @details This function uses tng_util_generic_write() and will
4222 * create a forces data block if none exists. Forces are stored as three
4223 * values per frame and compressed using gzip compression.
4224 * N.b. Since compressed data is written a whole block at a time the data is not
4225 * actually written to disk until the frame set is finished or the TNG
4226 * trajectory is closed.
4227 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4228 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4231 tng_function_status DECLSPECDLLEXPORT tng_util_force_write
4232 (tng_trajectory_t tng_data,
4233 const int64_t frame_nr,
4234 const float *forces);
4237 * @brief High-level function for adding data to forces data blocks at double
4239 * @param tng_data is the trajectory to use.
4240 * @param frame_nr is the frame number of the data.
4241 * @param forces is a 1D array of data to add. The array should be of length
4243 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4244 * must be initialised before using it.
4245 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4246 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4247 * be a NULL pointer.
4248 * @details This function uses tng_util_generic_write() and will
4249 * create a forces data block if none exists. Forces are stored as three
4250 * values per frame and compressed using gzip compression.
4251 * N.b. Since compressed data is written a whole block at a time the data is not
4252 * actually written to disk until the frame set is finished or the TNG
4253 * trajectory is closed.
4254 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4255 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4258 tng_function_status DECLSPECDLLEXPORT tng_util_force_double_write
4259 (tng_trajectory_t tng_data,
4260 const int64_t frame_nr,
4261 const double *forces);
4264 * @brief High-level function for adding data to box shape data blocks.
4265 * @param tng_data is the trajectory to use.
4266 * @param frame_nr is the frame number of the data.
4267 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4268 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4269 * must be initialised before using it.
4270 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4271 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4272 * be a NULL pointer.
4273 * @details This function uses tng_util_generic_write() and will
4274 * create a box shape data block if none exists. Box shapes are stored as 9
4275 * values per frame and compressed using TNG compression.
4276 * N.b. Since compressed data is written a whole block at a time the data is not
4277 * actually written to disk until the frame set is finished or the TNG
4278 * trajectory is closed.
4279 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4280 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4283 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write
4284 (tng_trajectory_t tng_data,
4285 const int64_t frame_nr,
4286 const float *box_shape);
4289 * @brief High-level function for adding data to box shape data blocks at double
4291 * @param tng_data is the trajectory to use.
4292 * @param frame_nr is the frame number of the data.
4293 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4294 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4295 * must be initialised before using it.
4296 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4297 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4298 * be a NULL pointer.
4299 * @details This function uses tng_util_generic_write() and will
4300 * create a box shape data block if none exists. Box shapes are stored as 9
4301 * values per frame and compressed using TNG compression.
4302 * N.b. Since compressed data is written a whole block at a time the data is not
4303 * actually written to disk until the frame set is finished or the TNG
4304 * trajectory is closed.
4305 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4306 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4309 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_double_write
4310 (tng_trajectory_t tng_data,
4311 const int64_t frame_nr,
4312 const double *box_shape);
4315 * @brief High-level function for writing data of one frame to a data block.
4316 * If the frame is at the beginning of a frame set the time stamp of the frame
4318 * @param tng_data is the trajectory to use.
4319 * @param frame_nr is the frame number of the data.
4320 * @param time is the time stamp of the frame (in seconds).
4321 * @param values is a 1D array of data to add. The array should be of length
4322 * n_particles * n_values_per_frame if writing particle related data, otherwise
4323 * it should be n_values_per_frame.
4324 * @param n_values_per_frame is the number of values to store per frame. If the
4325 * data is particle dependent there will be n_values_per_frame stored per
4326 * particle each frame.
4327 * @param block_id is the ID of the block, of which to set the output interval.
4328 * @param block_name is a string that will be used as name of the block. Only
4329 * required if the block did not exist, i.e. a new block is created.
4330 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4331 * data is not related to specific particles (e.g. box shape) or
4332 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4333 * positions). Only required if the block did not exist, i.e. a new block is
4335 * @param compression is the compression routine to use when writing the data.
4336 * Only required if the block did not exist, i.e. a new block is created.
4337 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4338 * must be initialised before using it.
4339 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4340 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4341 * @pre \code values != 0 \endcode The pointer to the values array must not
4342 * be a NULL pointer.
4343 * @details n_values_per_frame, block_name, particle_dependency and
4344 * compression are only used if the data block did not exist before calling
4345 * this function, in which case it is created.
4346 * N.b. Data is written a whole block at a time. The data is not
4347 * actually written to disk until the frame set is finished or the TNG
4348 * trajectory is closed.
4349 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4350 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4353 tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_write
4354 (tng_trajectory_t tng_data,
4355 const int64_t frame_nr,
4357 const float *values,
4358 const int64_t n_values_per_frame,
4359 const int64_t block_id,
4360 const char *block_name,
4361 const char particle_dependency,
4362 const char compression);
4365 * @brief High-level function for writing data of one frame to a double precision
4366 * data block. If the frame is at the beginning of a frame set the time stamp of
4367 * the frame set is set.
4368 * @param tng_data is the trajectory to use.
4369 * @param frame_nr is the frame number of the data.
4370 * @param time is the time stamp of the frame (in seconds).
4371 * @param values is a 1D array of data to add. The array should be of length
4372 * n_particles * n_values_per_frame if writing particle related data, otherwise
4373 * it should be n_values_per_frame.
4374 * @param n_values_per_frame is the number of values to store per frame. If the
4375 * data is particle dependent there will be n_values_per_frame stored per
4376 * particle each frame.
4377 * @param block_id is the ID of the block, of which to set the output interval.
4378 * @param block_name is a string that will be used as name of the block. Only
4379 * required if the block did not exist, i.e. a new block is created.
4380 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4381 * data is not related to specific particles (e.g. box shape) or
4382 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4383 * positions). Only required if the block did not exist, i.e. a new block is
4385 * @param compression is the compression routine to use when writing the data.
4386 * Only required if the block did not exist, i.e. a new block is created.
4387 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4388 * must be initialised before using it.
4389 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4390 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4391 * @pre \code values != 0 \endcode The pointer to the values array must not
4392 * be a NULL pointer.
4393 * @details n_values_per_frame, block_name, particle_dependency and
4394 * compression are only used if the data block did not exist before calling
4395 * this function, in which case it is created.
4396 * N.b. Data is written a whole block at a time. The data is not
4397 * actually written to disk until the frame set is finished or the TNG
4398 * trajectory is closed.
4399 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4400 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4403 tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_double_write
4404 (tng_trajectory_t tng_data,
4405 const int64_t frame_nr,
4407 const double *values,
4408 const int64_t n_values_per_frame,
4409 const int64_t block_id,
4410 const char *block_name,
4411 const char particle_dependency,
4412 const char compression);
4415 * @brief High-level function for adding data to positions data blocks. If the
4416 * frame is at the beginning of a frame set the time stamp of the frame set
4418 * @param tng_data is the trajectory to use.
4419 * @param frame_nr is the frame number of the data.
4420 * @param time is the time stamp of the frame (in seconds).
4421 * @param positions is a 1D array of data to add. The array should be of length
4423 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4424 * must be initialised before using it.
4425 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4426 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4427 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4428 * be a NULL pointer.
4429 * @details This function uses tng_util_generic_with_time_write() and will
4430 * create a positions data block if none exists. Positions are stored as three
4431 * values per frame and compressed using TNG compression.
4432 * N.b. Since compressed data is written a whole block at a time the data is not
4433 * actually written to disk until the frame set is finished or the TNG
4434 * trajectory is closed.
4435 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4436 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4439 tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_write
4440 (tng_trajectory_t tng_data,
4441 const int64_t frame_nr,
4443 const float *positions);
4446 * @brief High-level function for adding data to positions data blocks at double
4447 * precision. If the frame is at the beginning of a frame set the time stamp of
4448 * the frame set is set.
4449 * @param tng_data is the trajectory to use.
4450 * @param frame_nr is the frame number of the data.
4451 * @param time is the time stamp of the frame (in seconds).
4452 * @param positions is a 1D array of data to add. The array should be of length
4454 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4455 * must be initialised before using it.
4456 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4457 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4458 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4459 * be a NULL pointer.
4460 * @details This function uses tng_util_generic_with_time_double_write() and will
4461 * create a positions data block if none exists. Positions are stored as three
4462 * values per frame and compressed using TNG compression.
4463 * N.b. Since compressed data is written a whole block at a time the data is not
4464 * actually written to disk until the frame set is finished or the TNG
4465 * trajectory is closed.
4466 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4467 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4470 tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_double_write
4471 (tng_trajectory_t tng_data,
4472 const int64_t frame_nr,
4474 const double *positions);
4477 * @brief High-level function for adding data to velocities data blocks. If the
4478 * frame is at the beginning of a frame set the time stamp of the frame set
4480 * @param tng_data is the trajectory to use.
4481 * @param frame_nr is the frame number of the data.
4482 * @param time is the time stamp of the frame (in seconds).
4483 * @param velocities is a 1D array of data to add. The array should be of length
4485 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4486 * must be initialised before using it.
4487 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4488 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4489 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4490 * be a NULL pointer.
4491 * @details This function uses tng_util_generic_with_time_write() and will
4492 * create a velocities data block if none exists. Velocities are stored as three
4493 * values per frame and compressed using TNG compression.
4494 * N.b. Since compressed data is written a whole block at a time the data is not
4495 * actually written to disk until the frame set is finished or the TNG
4496 * trajectory is closed.
4497 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4498 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4501 tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_write
4502 (tng_trajectory_t tng_data,
4503 const int64_t frame_nr,
4505 const float *velocities);
4508 * @brief High-level function for adding data to velocities data blocks at
4509 * double precision. If the frame is at the beginning of a frame set the
4510 * time stamp of the frame set is set.
4511 * @param tng_data is the trajectory to use.
4512 * @param frame_nr is the frame number of the data.
4513 * @param time is the time stamp of the frame (in seconds).
4514 * @param velocities is a 1D array of data to add. The array should be of length
4516 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4517 * must be initialised before using it.
4518 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4519 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4520 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4521 * be a NULL pointer.
4522 * @details This function uses tng_util_generic_with_time_double_write() and will
4523 * create a velocities data block if none exists. Velocities are stored as three
4524 * values per frame and compressed using TNG compression.
4525 * N.b. Since compressed data is written a whole block at a time the data is not
4526 * actually written to disk until the frame set is finished or the TNG
4527 * trajectory is closed.
4528 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4529 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4532 tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_double_write
4533 (tng_trajectory_t tng_data,
4534 const int64_t frame_nr,
4536 const double *velocities);
4539 * @brief High-level function for adding data to forces data blocks. If the
4540 * frame is at the beginning of a frame set the time stamp of the frame set
4542 * @param tng_data is the trajectory to use.
4543 * @param frame_nr is the frame number of the data.
4544 * @param time is the time stamp of the frame (in seconds).
4545 * @param forces is a 1D array of data to add. The array should be of length
4547 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4548 * must be initialised before using it.
4549 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4550 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4551 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4552 * be a NULL pointer.
4553 * @details This function uses tng_util_generic_with_time_write() and will
4554 * create a forces data block if none exists. Forces are stored as three
4555 * values per frame and compressed using gzip compression.
4556 * N.b. Since compressed data is written a whole block at a time the data is not
4557 * actually written to disk until the frame set is finished or the TNG
4558 * trajectory is closed.
4559 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4560 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4563 tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_write
4564 (tng_trajectory_t tng_data,
4565 const int64_t frame_nr,
4567 const float *forces);
4570 * @brief High-level function for adding data to forces data blocks at
4571 * double precision. If the frame is at the beginning of a frame set
4572 * the time stamp of the frame set is set.
4573 * @param tng_data is the trajectory to use.
4574 * @param frame_nr is the frame number of the data.
4575 * @param time is the time stamp of the frame (in seconds).
4576 * @param forces is a 1D array of data to add. The array should be of length
4578 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4579 * must be initialised before using it.
4580 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4581 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4582 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4583 * be a NULL pointer.
4584 * @details This function uses tng_util_generic_with_time_double_write() and will
4585 * create a forces data block if none exists. Forces are stored as three
4586 * values per frame and compressed using gzip compression.
4587 * N.b. Since compressed data is written a whole block at a time the data is not
4588 * actually written to disk until the frame set is finished or the TNG
4589 * trajectory is closed.
4590 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4591 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4594 tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_double_write
4595 (tng_trajectory_t tng_data,
4596 const int64_t frame_nr,
4598 const double *forces);
4601 * @brief High-level function for adding data to box shape data blocks. If the
4602 * frame is at the beginning of a frame set the time stamp of the frame set
4604 * @param tng_data is the trajectory to use.
4605 * @param frame_nr is the frame number of the data.
4606 * @param time is the time stamp of the frame (in seconds).
4607 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4608 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4609 * must be initialised before using it.
4610 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4611 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4612 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4613 * be a NULL pointer.
4614 * @details This function uses tng_util_generic_with_time_write() and will
4615 * create a box shape data block if none exists. Box shapes are stored as 9
4616 * values per frame and compressed using TNG compression.
4617 * N.b. Since compressed data is written a whole block at a time the data is not
4618 * actually written to disk until the frame set is finished or the TNG
4619 * trajectory is closed.
4620 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4621 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4624 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_write
4625 (tng_trajectory_t tng_data,
4626 const int64_t frame_nr,
4628 const float *box_shape);
4631 * @brief High-level function for adding data to box shape data blocks at
4632 * double precision. If the frame is at the beginning of a frame set the
4633 * time stamp of the frame set is set.
4634 * @param tng_data is the trajectory to use.
4635 * @param frame_nr is the frame number of the data.
4636 * @param time is the time stamp of the frame (in seconds).
4637 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4638 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4639 * must be initialised before using it.
4640 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4641 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4642 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4643 * be a NULL pointer.
4644 * @details This function uses tng_util_generic_with_time_double_write() and will
4645 * create a box shape data block if none exists. Box shapes are stored as 9
4646 * values per frame and compressed using TNG compression.
4647 * N.b. Since compressed data is written a whole block at a time the data is not
4648 * actually written to disk until the frame set is finished or the TNG
4649 * trajectory is closed.
4650 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4651 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4654 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_double_write
4655 (tng_trajectory_t tng_data,
4656 const int64_t frame_nr,
4658 const double *box_shape);
4661 * @brief High-level function for getting the compression method and
4662 * multiplication factor of the last read frame of a specific data block.
4663 * @param tng_data is the trajectory to use.
4664 * @param block_id is the ID number of the block containing the data of
4666 * @param codec_id will be set to the value of the codec_id of the
4667 * compression of the data block. See tng_compression for more details.
4668 * @param factor will be set to the multiplication factor applied to
4669 * the values before compression, in order to get integers from them.
4670 * factor is 1/precision.
4671 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4672 * must be initialised before using it.
4673 * @pre \code codec_id != 0 \endcode The pointer to the returned codec id
4674 * must not be a NULL pointer.
4675 * @pre \code factor != 0 \endcode The pointer to the returned multiplication
4676 * factor must not be a NULL pointer.
4677 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4678 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4681 tng_function_status DECLSPECDLLEXPORT tng_util_frame_current_compression_get
4682 (tng_trajectory_t tng_data,
4683 const int64_t block_id,
4687 /** @brief High-level function for determining the next frame with data and what
4688 * data blocks have data for that frame. The search can be limited to certain
4690 * @param tng_data is the trajectory to use.
4691 * @param current_frame is the frame that was last read, from where to start
4693 * @param n_requested_data_block_ids is the number of data blocks listed in
4694 * requested_data_block_ids. If this is 0 all data blocks will be taken into
4696 * @param requested_data_block_ids is an array of data blocks to look for.
4697 * @param next_frame will be set to the next frame with data.
4698 * @param n_data_blocks_in_next_frame is set to the number of data blocks with
4699 * data for next_frame.
4700 * @param data_block_ids_in_next_frame is set to an array (of length
4701 * n_data_blocks_in_next_frame) that lists the data block IDs with data for
4702 * next_frame. It must be pointing at NULL or previously allocated memory.
4703 * Memory for the array is allocated by this function.
4704 * The memory must be freed by the client afterwards or
4705 * there will be a memory leak.
4706 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4707 * must be initialised before using it.
4708 * @pre \code next_frame != 0 \endcode The pointer to the next frame must not
4710 * @pre \code n_data_blocks_in_next_frame != 0 \endcode The pointer to
4711 * n_data_blocks_in_next_frame must not be NULL.
4712 * @pre \code *data_block_ids_in_next_frame != 0 \endcode The pointer to the
4713 * list of data block IDs must not be NULL.
4714 * @pre \code n_requested_data_block_ids == 0 || requested_data_block_ids != 0 \endcode
4715 * If the number of requested data blocks != 0 then the array of data block IDs must not be NULL.
4716 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4717 * has occured or TNG_CRITICAL (2) if a major error
4720 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_next_frame_present_data_blocks_find
4721 (tng_trajectory_t tng_data,
4722 int64_t current_frame,
4723 const int64_t n_requested_data_block_ids,
4724 const int64_t *requested_data_block_ids,
4725 int64_t *next_frame,
4726 int64_t *n_data_blocks_in_next_frame,
4727 int64_t **data_block_ids_in_next_frame);
4729 /* @brief High-level function for getting all data block ids and their names
4730 * and stride lengths.
4731 * @param tng_data is the trajectory to use.
4732 * @param n_data_blocks is set to the number of data blocks in the trajectory.
4733 * @param data_block_ids is set to an array (of length
4734 * n_data_blocks) that lists the data block IDs in the trajectory.
4735 * It must be pointing at NULL or previously allocated memory.
4736 * Memory for the array is allocated by this function.
4737 * The memory must be freed by the client afterwards or
4738 * there will be a memory leak.
4739 * @param data_block_names is set to an array (of length
4740 * n_data_blocks) that contains the names of the data blocks.
4741 * It must be pointing at NULL or previously allocated memory.
4742 * Memory for the array is allocated by this function.
4743 * The memory must be freed by the client afterwards or
4744 * there will be a memory leak.
4745 * @param stride_lengths is set to an array (of length
4746 * n_data_blocks) that lists the stride lengths of the data blocks.
4747 * It must be pointing at NULL or previously allocated memory.
4748 * Memory for the array is allocated by this function.
4749 * The memory must be freed by the client afterwards or
4750 * there will be a memory leak.
4751 * @param n_values_per_frame is set to an array (of length
4752 * n_data_blocks) that lists the number of values per frame of the data blocks.
4753 * It must be pointing at NULL or previously allocated memory.
4754 * Memory for the array is allocated by this function.
4755 * The memory must be freed by the client afterwards or
4756 * there will be a memory leak.
4757 * @param block_types is set to an array (of length
4758 * n_data_blocks) that lists the block types of the data blocks.
4759 * It must be pointing at NULL or previously allocated memory.
4760 * Memory for the array is allocated by this function.
4761 * The memory must be freed by the client afterwards or
4762 * there will be a memory leak.
4763 * @param dependencies is set to an array (of length
4764 * n_data_blocks) that lists the dependencies of the data blocks.
4765 * It must be pointing at NULL or previously allocated memory.
4766 * Memory for the array is allocated by this function.
4767 * The memory must be freed by the client afterwards or
4768 * there will be a memory leak.
4769 * @param compressions is set to an array (of length
4770 * n_data_blocks) that lists the compressions of the data blocks.
4771 * It must be pointing at NULL or previously allocated memory.
4772 * Memory for the array is allocated by this function.
4773 * The memory must be freed by the client afterwards or
4774 * there will be a memory leak.
4775 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4776 * must be initialised before using it.
4777 * @pre \code n_data_blocks != 0 \endcode The pointer to
4778 * n_data_blocks must not be NULL.
4779 * @pre \code data_block_ids != 0 \endcode The pointer to the
4780 * list of data block IDs must not be NULL.
4781 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4782 * has occured or TNG_CRITICAL (2) if a major error
4786 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_all_data_block_types_get
4787 (tng_trajectory_t tng_data,
4788 int64_t *n_data_blocks,
4789 int64_t **data_block_ids,
4790 char ***data_block_names,
4791 int64_t **stride_lengths,
4792 int64_t **n_values_per_frame,
4794 char **dependencies,
4795 char **compressions);
4798 /** @brief Finds the frame set of the specified frame in order to prepare for writing
4800 * @param tng_data is the trajectory to use.
4801 * @param prev_frame is the frame after which to start appending.
4802 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4803 * must be initialised before using it.
4804 * @pre \code prev_frame >= 0 \endcode The previous frame must not be negative.
4805 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4806 * has occured (such as not finding the requested frame) or TNG_CRITICAL (2)
4807 * if a major error has occured.
4809 tng_function_status DECLSPECDLLEXPORT tng_util_prepare_append_after_frame
4810 (tng_trajectory_t tng_data,
4811 const int64_t prev_frame);
4813 /** @} */ /* end of group2 */
4817 } /* end extern "C" */
4820 #endif /* TNG_IO_H */