1 /* This code is part of the tng binary trajectory format.
3 * Written by Magnus Lundborg
4 * Copyright (c) 2012-2014, The GROMACS development team.
5 * Check out http://www.gromacs.org for more information.
8 * This program is free software; you can redistribute it and/or
9 * modify it under the terms of the Revised BSD License.
13 * @brief API for input and output of tng trajectory files
14 * @mainpage TNG: A flexible binary trajectory format
15 * @section intro_sec Introduction
17 * The TNG format is developed as part of the ScalaLife EU project.
18 * It is flexible by design to allow parallel writing, custom data blocks,
19 * different output frequencies and different compression algorithms.
21 * Each block can contain MD5 hashes to verify data integrity and the file
22 * can be signed by the user to ensure that the origin is correct.
24 * The intention is that the API and ABI should be stable, but it is
25 * still possible that future changes might make that impossible, in which
26 * case that will be clarified.
28 * The API and all examples are released without any warranties. Use them at
31 * @section authors_sec Authors
33 * The TNG trajectory format is developed by:
35 * Magnus Lundborg magnus.lundborg@scilifelab.se
37 * Daniel SpÄngberg daniels@mkem.uu.se
39 * Rossen Apostolov rossen@kth.se
41 * The API is implemented mainly by:
47 * Copyright (c) 2012, The GROMACS development team.
48 * check out http://www.gromacs.org for more information.
50 * The TNG API is released under the Revised BSD License and is free to
51 * redistribute according to that license.
53 * A license file (named COPYING) should be included with each copy of the API.
55 * @section install_sec Installation
70 * bin/tests/tng_testing
73 * @section change_sec Change Log
75 * See git log for full revision history.
79 * v. 1.6 - Fourth stable release of the API.
81 * - Removed OpenMP option when building.
82 * - Functionality for migrating data blocks.
83 * - Improved handling of molecules.
84 * - Improved installation of TNG documentation.
85 * - Enhancements to CMake usage.
86 * - Required CMake version raised to 2.8.8.
89 * v. 1.5 - Third stable release of the API.
91 * - Fortran wrapper split into separate file
92 * - Added more block IDs.
93 * - Some new functions and utility functions added.
94 * - Improved compression precision settings.
96 * - Make appending to file work better.
97 * - Modified CMake settings
100 * v. 1.4 - Changed from LGPL to the Revised BSD License.
102 * - More flexible support for digital signatures in header.
103 * - Block ID numbers changed.
105 * v. 1.3 - Second stable release of the API.
107 * - Added multiplication factor for coordinate units to general info.
108 * - Added time stamps and time per frame in frame sets.
109 * - High-level API functions added (not for managing molecules yet)
110 * - Added functions for reading data blocks into 1D arrays.
111 * - TNG compression added.
112 * - C++ interface added.
113 * - Avoid memory allocation if no data is submitted when adding data
115 * - Added function tng_num_frames_per_frame_set_set
116 * - Added data block IDs for charges, b-factors and occupancy.
117 * - GZIP compression added.
118 * - Fixed bug when updating MD5 hashes of data blocks.
119 * - Fixed bug in chain_name_of_particle_get(...)
120 * - Update frame set pointers properly.
121 * - Moved fortran wrapper from header file to source file.
122 * - Write sparse data in mdrun examples.
123 * - Fixed bugs related to reading and writing sparse data.
124 * - Fixed memory leak for non-trajectory particle data blocks.
125 * - Fixed bug when writing data blocks.
126 * - Fixed wrong values in dependency constants
127 * - Write box shape, partial charges and annotation data in tng_testing
128 * - Bug fixes in tng_testing (frame sets not written before)
130 * v. 1.0 - First stable release of the API.
133 * @section examples_sec Examples
135 * There are some examples of how to use the library located in src/tests/
137 * @subsection tng_subsec TNG files
139 * The build directory contains an example_files directory, which in turn
140 * contains a very short example of a TNG file containing a few water molecules,
141 * a box shape description and positions in 10 frames.
143 * It is also possible to run the bin/examples/md_openmp_util
144 * (see src/tests/md_openmp_util.c)
145 * testing program, which will save MD simulations output to a new file
146 * (saved in the example_files directory).
148 * These files can be read using the bin/examples/tng_io_read_pos_util
151 * @subsection c_subsec C
153 * Example writing data to a TNG file (just an excerpt):
155 * for ( step = 1; step < step_num; step++ )
157 * compute ( np, nd, pos, vel, mass, force, &potential, &kinetic );
159 * if(step % step_save == 0)
161 * // Write positions, velocities and forces
162 * if(tng_util_pos_write(traj, step, pos) != TNG_SUCCESS)
164 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
167 * if(tng_util_vel_write(traj, step, vel) != TNG_SUCCESS)
169 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
172 * if(tng_util_force_write(traj, step, force) != TNG_SUCCESS)
174 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__);
178 * update ( np, nd, pos, vel, force, acc, mass, dt );
182 * Example reading positions from a TNG file:
184 * #include <stdlib.h>
186 * #include "tng/tng_io.h"
188 * int main(int argc, char **argv)
190 * tng_trajectory_t traj;
191 * // Assume that the data is stored as floats. The data is placed in 1-D
193 * float *positions = 0, *box_shape = 0;
194 * int64_t n_particles, n_frames, tot_n_frames, stride_length, i, j;
195 * // Set a default frame range
196 * int64_t first_frame = 0, last_frame = 5000;
199 * // A reference must be passed to allocate memory
200 * tng_util_trajectory_open(argv[1], 'r', &traj);
202 * if(tng_num_frames_get(traj, &tot_n_frames) != TNG_SUCCESS)
204 * printf("Cannot determine the number of frames in the file\n");
205 * tng_util_trajectory_close(&traj);
209 * if(tng_num_particles_get(traj, &n_particles) != TNG_SUCCESS)
211 * printf("Cannot determine the number of particles in the file\n");
212 * tng_util_trajectory_close(&traj);
216 * printf("%"PRId64" frames in file\n", tot_n_frames);
218 * if(last_frame > tot_n_frames - 1)
220 * last_frame = tot_n_frames - 1;
223 * if(tng_util_box_shape_read(traj, &box_shape, &stride_length) ==
226 * printf("Simulation box shape: ");
227 * for(i=0; i < 9; i++)
229 * printf("%f ", box_shape[i]);
235 * printf("Simulation box shape not set in the file (or could not be read)\n");
238 * n_frames = last_frame - first_frame + 1;
241 * // Get the positions of all particles in the requested frame range.
242 * // The positions are stored in the positions array.
243 * // N.B. No proper error checks.
244 * if(tng_util_pos_read_range(traj, 0, last_frame, &positions, &stride_length)
247 * // Print the positions of the wanted particle (zero based)
248 * for(i=0; i < n_frames; i += stride_length)
250 * printf("\nFrame %"PRId64":\n", first_frame + i);
251 * for(j=0; j < n_particles; j++)
253 * printf("Atom nr: %"PRId64"", j);
254 * for(k=0; k < 3; k++)
256 * printf("\t%f", positions[i/stride_length*n_particles*
265 * printf("Cannot read positions\n");
273 * tng_util_trajectory_close(&traj);
280 * @subsection fortran_subsec Fortran
282 * The TNG library can be used from Fortran. It requires cray pointers, which
283 * are not part of the Fortran 77 standard, but available in most compilers.
285 * To compile the fortran example -DTNG_BUILD_FORTRAN=ON needs to be specified when
297 #include "tng_io_fwd.h"
299 #ifdef USE_STD_INTTYPES_H
300 #include <inttypes.h>
302 /* Visual Studio does not contain inttypes.h and stdint.h. Some defines and
303 * typedefs are used from the GNU C Library */
306 typedef __int32 int32_t;
307 typedef unsigned __int32 uint32_t;
308 typedef __int64 int64_t;
309 typedef unsigned __int64 uint64_t;
313 #endif /* _MSC_VER */
315 /* This is from inttypes.h (GNU C Library) */
316 /* The ISO C99 standard specifies that these macros must only be
317 defined if explicitly requested. */
318 #if !defined __cplusplus || defined __STDC_FORMAT_MACROS
320 # if __WORDSIZE == 64
321 # define __PRI64_PREFIX "l"
322 # define __PRIPTR_PREFIX "l"
324 # define __PRI64_PREFIX "ll"
325 # define __PRIPTR_PREFIX
328 /* From stdint.h (GNU C Library) */
329 /* Macros for printing format specifiers. */
330 /* Decimal notation. */
332 # define PRId64 __PRI64_PREFIX "d"
337 #endif /* USE_STD_INTTYPES_H */
340 #if defined(WIN32) || defined(_WIN32) || defined(WIN64) || defined(_WIN64)
342 #endif /* win32... */
343 #endif /* not defined USE_WINDOWS */
346 #define TNG_PRIsize "Iu"
348 #define TNG_PRIsize "zu"
351 #ifndef DECLSPECDLLEXPORT
353 #define DECLSPECDLLEXPORT __declspec(dllexport)
354 #else /* USE_WINDOWS */
355 #define DECLSPECDLLEXPORT
356 #endif /* USE_WINDOWS */
357 #endif /* DECLSPECDLLEXPORT */
359 /** Flag to indicate frame dependent data. */
360 #define TNG_FRAME_DEPENDENT 1
361 /** Flag to indicate particle dependent data. */
362 #define TNG_PARTICLE_DEPENDENT 2
364 /** The maximum length of a date string */
365 #define TNG_MAX_DATE_STR_LEN 24
366 /** The length of an MD5 hash */
367 #define TNG_MD5_HASH_LEN 16
368 /** The maximum allowed length of a string */
369 #define TNG_MAX_STR_LEN 1024
372 #define TNG_ASSERT(cnd, msg) if(!(cnd)) {printf("%s\n", msg); assert(cnd);}
374 #define TNG_ASSERT(cnd, msg) (void)0;
377 /** Flag to specify the endianness of a TNG file */
378 typedef enum {TNG_BIG_ENDIAN,
379 TNG_LITTLE_ENDIAN} tng_file_endianness;
381 /** Flag to specify the endianness of 32 bit values of the current architecture. */
382 typedef enum {TNG_BIG_ENDIAN_32,
383 TNG_LITTLE_ENDIAN_32,
384 TNG_BYTE_PAIR_SWAP_32} tng_endianness_32;
386 /** Flag to specify the endianness of 64 bit values of the current architecture. */
387 typedef enum {TNG_BIG_ENDIAN_64,
388 TNG_LITTLE_ENDIAN_64,
390 TNG_BYTE_PAIR_SWAP_64,
391 TNG_BYTE_SWAP_64} tng_endianness_64;
393 /** Compression mode is specified in each data block */
394 typedef enum {TNG_UNCOMPRESSED,
397 TNG_GZIP_COMPRESSION} tng_compression;
400 typedef enum {TNG_NO_HASH,
402 TNG_SHA256} tng_hash_type;
404 /** Non trajectory blocks come before the first frame set block */
405 typedef enum {TNG_NON_TRAJECTORY_BLOCK, TNG_TRAJECTORY_BLOCK} tng_block_type;
407 /** @defgroup def1 Standard non-trajectory blocks
408 * Block IDs of standard non-trajectory blocks.
411 #define TNG_GENERAL_INFO 0x0000000000000000LL
412 #define TNG_MOLECULES 0x0000000000000001LL
413 #define TNG_TRAJECTORY_FRAME_SET 0x0000000000000002LL
414 #define TNG_PARTICLE_MAPPING 0x0000000000000003LL
417 /** @defgroup def2 Standard trajectory blocks
418 * Block IDs of standard trajectory blocks. Box shape and partial charges can
419 * be either trajectory blocks or non-trajectory blocks
422 #define TNG_TRAJ_BOX_SHAPE 0x0000000010000000LL
423 #define TNG_TRAJ_POSITIONS 0x0000000010000001LL
424 #define TNG_TRAJ_VELOCITIES 0x0000000010000002LL
425 #define TNG_TRAJ_FORCES 0x0000000010000003LL
426 #define TNG_TRAJ_PARTIAL_CHARGES 0x0000000010000004LL
427 #define TNG_TRAJ_FORMAL_CHARGES 0x0000000010000005LL
428 #define TNG_TRAJ_B_FACTORS 0x0000000010000006LL
429 #define TNG_TRAJ_ANISOTROPIC_B_FACTORS 0x0000000010000007LL
430 #define TNG_TRAJ_OCCUPANCY 0x0000000010000008LL
431 #define TNG_TRAJ_GENERAL_COMMENTS 0x0000000010000009LL
435 /** @defgroup def3 GROMACS data block IDs
436 * Block IDs of data blocks specific to GROMACS.
439 #define TNG_GMX_LAMBDA 0x1000000010000000LL
440 #define TNG_GMX_ENERGY_ANGLE 0x1000000010000001LL
441 #define TNG_GMX_ENERGY_RYCKAERT_BELL 0x1000000010000002LL
442 #define TNG_GMX_ENERGY_LJ_14 0x1000000010000003LL
443 #define TNG_GMX_ENERGY_COULOMB_14 0x1000000010000004LL
444 #define TNG_GMX_ENERGY_LJ_(SR) 0x1000000010000005LL
445 #define TNG_GMX_ENERGY_COULOMB_(SR) 0x1000000010000006LL
446 #define TNG_GMX_ENERGY_COUL_RECIP 0x1000000010000007LL
447 #define TNG_GMX_ENERGY_POTENTIAL 0x1000000010000008LL
448 #define TNG_GMX_ENERGY_KINETIC_EN 0x1000000010000009LL
449 #define TNG_GMX_ENERGY_TOTAL_ENERGY 0x1000000010000010LL
450 #define TNG_GMX_ENERGY_TEMPERATURE 0x1000000010000011LL
451 #define TNG_GMX_ENERGY_PRESSURE 0x1000000010000012LL
452 #define TNG_GMX_ENERGY_CONSTR_RMSD 0x1000000010000013LL
453 #define TNG_GMX_ENERGY_BOX_X 0x1000000010000014LL
454 #define TNG_GMX_ENERGY_BOX_Y 0x1000000010000015LL
455 #define TNG_GMX_ENERGY_BOX_Z 0x1000000010000016LL
456 #define TNG_GMX_ENERGY_VOLUME 0x1000000010000017LL
457 #define TNG_GMX_ENERGY_DENSITY 0x1000000010000018LL
458 #define TNG_GMX_ENERGY_PV 0x1000000010000019LL
459 #define TNG_GMX_ENERGY_ENTHALPY 0x1000000010000020LL
460 #define TNG_GMX_ENERGY_VIR_XX 0x1000000010000021LL
461 #define TNG_GMX_ENERGY_VIR_XY 0x1000000010000022LL
462 #define TNG_GMX_ENERGY_VIR_XZ 0x1000000010000023LL
463 #define TNG_GMX_ENERGY_VIR_YX 0x1000000010000024LL
464 #define TNG_GMX_ENERGY_VIR_YY 0x1000000010000025LL
465 #define TNG_GMX_ENERGY_VIR_YZ 0x1000000010000026LL
466 #define TNG_GMX_ENERGY_VIR_ZX 0x1000000010000027LL
467 #define TNG_GMX_ENERGY_VIR_ZY 0x1000000010000028LL
468 #define TNG_GMX_ENERGY_VIR_ZZ 0x1000000010000029LL
469 #define TNG_GMX_ENERGY_PRES_XX 0x1000000010000030LL
470 #define TNG_GMX_ENERGY_PRES_XY 0x1000000010000031LL
471 #define TNG_GMX_ENERGY_PRES_XZ 0x1000000010000032LL
472 #define TNG_GMX_ENERGY_PRES_YX 0x1000000010000033LL
473 #define TNG_GMX_ENERGY_PRES_YY 0x1000000010000034LL
474 #define TNG_GMX_ENERGY_PRES_YZ 0x1000000010000035LL
475 #define TNG_GMX_ENERGY_PRES_ZX 0x1000000010000036LL
476 #define TNG_GMX_ENERGY_PRES_ZY 0x1000000010000037LL
477 #define TNG_GMX_ENERGY_PRES_ZZ 0x1000000010000038LL
478 #define TNG_GMX_ENERGY_SURFXSURFTEN 0x1000000010000039LL
479 #define TNG_GMX_ENERGY_T_SYSTEM 0x1000000010000040LL
480 #define TNG_GMX_ENERGY_LAMB_SYSTEM 0x1000000010000041LL
481 #define TNG_GMX_SELECTION_GROUP_NAMES 0x1000000010000042LL
482 #define TNG_GMX_ATOM_SELECTION_GROUP 0x1000000010000043LL
485 /** Flag to specify if a data block contains data related to particles or not.*/
486 typedef enum {TNG_NON_PARTICLE_BLOCK_DATA,
487 TNG_PARTICLE_BLOCK_DATA} tng_particle_dependency;
490 typedef enum {TNG_FALSE, TNG_TRUE} tng_bool;
492 /** Flag to specify if the number of atoms change throughout the trajectory or
493 * if it is constant. */
494 typedef enum {TNG_CONSTANT_N_ATOMS, TNG_VARIABLE_N_ATOMS}
495 tng_variable_n_atoms_flag;
497 /** Return values of API functions. TNG_SUCCESS means that the operation
498 * was successful. TNG_FAILURE means that the operation failed for some
499 * reason, but it is possible to try to continue anyhow. TNG_CRITICAL
500 * means that the error is irrecoverable. */
501 typedef enum {TNG_SUCCESS, TNG_FAILURE, TNG_CRITICAL} tng_function_status;
503 /** If tng_hash_mode == TNG_USE_HASH md5 hashes will be written to output files
504 * and when reading a file the md5 hashes of the contents will be compared to
505 * those in the file (for each block) in order to ensure data integrity */
506 typedef enum {TNG_SKIP_HASH, TNG_USE_HASH} tng_hash_mode;
508 /** Possible formats of data block contents */
509 typedef enum {TNG_CHAR_DATA,
512 TNG_DOUBLE_DATA} tng_data_type;
515 struct tng_trajectory;
521 struct tng_gen_block;
522 struct tng_particle_mapping;
523 struct tng_trajectory_frame_set;
524 struct tng_particle_data;
525 struct tng_non_particle_data;
527 /** Data can be either double, float, int or a string */
541 /** @defgroup group1 Low-level API
542 * These functions give detailed control of the TNG data management. Most
543 * things can be done using the more convenient high-level API functions
549 * @brief Get the major version of the TNG library.
550 * @param tng_data is a trajectory data container, it does not have
551 * to be initialized beforehand.
552 * @param version is pointing to a value set to the major version of
554 * @return TNG_SUCCESS (0) if successful.
556 tng_function_status DECLSPECDLLEXPORT tng_version_major
557 (const tng_trajectory_t tng_data,
561 * @brief Get the minor version of the TNG library.
562 * @param tng_data is a trajectory data container, it does not have
563 * to be initialized beforehand.
564 * @param version is pointing to a value set to the minor version of
566 * @return TNG_SUCCESS (0) if successful.
568 tng_function_status DECLSPECDLLEXPORT tng_version_minor
569 (const tng_trajectory_t tng_data,
573 * @brief Get the patch level of the TNG library.
574 * @param tng_data is a trajectory data container, it does not have
575 * to be initialized beforehand.
576 * @param patch_level is the string to fill with the full version,
577 * memory must be allocated before.
578 * @return TNG_SUCCESS (0) if successful.
580 tng_function_status DECLSPECDLLEXPORT tng_version_patchlevel
581 (const tng_trajectory_t tng_data,
585 * @brief Get the full version string of the TNG library.
586 * @param tng_data is a trajectory data container, it does not have
587 * to be initialized beforehand.
588 * @param version is pointing to a value set to the major version of
590 * @param max_len maximum char length of the string, i.e. how much memory has
591 * been reserved for version. This includes \0 terminating character.
592 * @pre \code version != 0 \endcode The pointer to the name string
593 * must not be a NULL pointer.
594 * @return TNG_SUCCESS (0) if successful.
596 tng_function_status DECLSPECDLLEXPORT tng_version
597 (const tng_trajectory_t tng_data,
602 * @brief Setup a trajectory data container.
603 * @param tng_data_p a pointer to memory to initialise as a trajectory.
604 * @pre tng_data_p must not be pointing at a reserved memory block.
605 * @details Memory is allocated during initialisation.
606 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
609 tng_function_status DECLSPECDLLEXPORT tng_trajectory_init
610 (tng_trajectory_t *tng_data_p);
613 * @brief Clean up a trajectory data container.
614 * @param tng_data_p a pointer to the trajectory data to destroy.
615 * @details All allocated memory in the data structure is freed, as well as
617 * @return TNG_SUCCESS (0) if successful.
619 tng_function_status DECLSPECDLLEXPORT tng_trajectory_destroy
620 (tng_trajectory_t *tng_data_p);
623 * @brief Copy a trajectory data container (dest is setup as well).
624 * @details This initialises dest and copies only what is absolute necessary for
625 * parallel i/o. This can be used inside pragma omp for setting up a thread
626 * local copy of src. It can be freed (using tng_trajectory_destroy) at the
627 * end of the parallel block.
628 * @param src the original trajectory.
629 * @param dest_p a pointer to memory to initialise as a trajectory.
630 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
631 * must be initialised before using it.
632 * @pre tng_data_p must not be pointing at a reserved memory block.
633 * @details Memory is allocated during initialisation.
634 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
637 tng_function_status DECLSPECDLLEXPORT tng_trajectory_init_from_src
638 (tng_trajectory_t src, tng_trajectory_t *dest_p);
641 * @brief Get the name of the input file.
642 * @param tng_data the trajectory of which to get the input file name.
643 * @param file_name the string to fill with the name of the input file,
644 * memory must be allocated before.
645 * @param max_len maximum char length of the string, i.e. how much memory has
646 * been reserved for file_name. This includes \0 terminating character.
647 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
648 * must be initialised before using it.
649 * @pre \code file_name != 0 \endcode The pointer to the file name string
650 * must not be a NULL pointer.
651 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
652 * has occurred (source string longer than destination string).
654 tng_function_status DECLSPECDLLEXPORT tng_input_file_get
655 (const tng_trajectory_t tng_data,
656 char *file_name, const int max_len);
659 * @brief Set the name of the input file.
660 * @param tng_data the trajectory of which to set the input file name.
661 * @param file_name the name of the input file.
662 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
663 * must be initialised before using it.
664 * @pre \code file_name != 0 \endcode The pointer to the file name string
665 * must not be a NULL pointer.
666 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
669 tng_function_status DECLSPECDLLEXPORT tng_input_file_set
670 (tng_trajectory_t tng_data,
671 const char *file_name);
674 * @brief Get the name of the output file.
675 * @param tng_data the trajectory of which to get the input file name.
676 * @param file_name the string to fill with the name of the output file,
677 * memory must be allocated before.
678 * @param max_len maximum char length of the string, i.e. how much memory has
679 * been reserved for file_name. This includes \0 terminating character.
680 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
681 * must be initialised before using it.
682 * @pre \code file_name != 0 \endcode The pointer to the file name string
683 * must not be a NULL pointer.
684 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
685 * has occurred (source string longer than destination string).
687 tng_function_status DECLSPECDLLEXPORT tng_output_file_get
688 (const tng_trajectory_t tng_data,
689 char *file_name, const int max_len);
692 * @brief Set the name of the output file.
693 * @param tng_data the trajectory of which to set the output file name.
694 * @param file_name the name of the output file.
695 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
696 * must be initialised before using it.
697 * @pre \code file_name != 0 \endcode The pointer to the file name string
698 * must not be a NULL pointer.
699 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
702 tng_function_status DECLSPECDLLEXPORT tng_output_file_set
703 (tng_trajectory_t tng_data,
704 const char *file_name);
707 * @brief Set the name of the output file for appending. The output file
708 * will not be overwritten.
709 * @param tng_data the trajectory of which to set the output file name.
710 * @param file_name the name of the output file to append to.
711 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
712 * must be initialised before using it.
713 * @pre \code file_name != 0 \endcode The pointer to the file name string
714 * must not be a NULL pointer.
715 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
718 tng_function_status DECLSPECDLLEXPORT tng_output_append_file_set
719 (tng_trajectory_t tng_data,
720 const char *file_name);
723 * @brief Get the endianness of the output file.
724 * @param tng_data the trajectory of which to get the endianness of the current
726 * @param endianness will contain the enumeration of the endianness.
727 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
728 * must be initialised before using it.
729 * @pre \code endianness != 0 \endcode The pointer to the endianness container
730 * must not be a NULL pointer.
731 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness
732 * could not be retrieved.
734 tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_get
735 (const tng_trajectory_t tng_data, tng_file_endianness *endianness);
738 * @brief Set the endianness of the output file.
739 * @param tng_data the trajectory of which to set the endianness of the current
741 * @param endianness the enumeration of the endianness, can be either
742 * TNG_BIG_ENDIAN (0) or TNG_LITTLE_ENDIAN (1).
743 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
744 * must be initialised before using it.
745 * @details The endianness cannot be changed after file output has started.
746 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness
749 tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_set
750 (tng_trajectory_t tng_data,
751 const tng_file_endianness endianness);
754 * @brief Get the name of the program used when creating the trajectory.
755 * @param tng_data the trajectory of which to get the program name.
756 * @param name the string to fill with the name of the program,
757 * memory must be allocated before.
758 * @param max_len maximum char length of the string, i.e. how much memory has
759 * been reserved for name. This includes \0 terminating character.
760 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
761 * must be initialised before using it.
762 * @pre \code name != 0 \endcode The pointer to the name string
763 * must not be a NULL pointer.
764 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
765 * has occurred (source string longer than destination string).
767 tng_function_status DECLSPECDLLEXPORT tng_first_program_name_get
768 (const tng_trajectory_t tng_data,
769 char *name, const int max_len);
772 * @brief Set the name of the program used when creating the trajectory.
773 * @param tng_data the trajectory of which to set the program name.
774 * @param new_name is a string containing the wanted name.
775 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
776 * must be initialised before using it.
777 * @pre \code new_name != 0 \endcode The pointer to the new_name string
778 * must not be a NULL pointer.
779 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
782 tng_function_status DECLSPECDLLEXPORT tng_first_program_name_set
783 (tng_trajectory_t tng_data,
784 const char *new_name);
787 * @brief Get the name of the program used when last modifying the trajectory.
788 * @param tng_data the trajectory of which to get the program name.
789 * @param name the string to fill with the name of the program,
790 * memory must be allocated before.
791 * @param max_len maximum char length of the string, i.e. how much memory has
792 * been reserved for name. This includes \0 terminating character.
793 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
794 * must be initialised before using it.
795 * @pre \code name != 0 \endcode The pointer to the name string
796 * must not be a NULL pointer.
797 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
798 * has occurred (source string longer than destination string).
800 tng_function_status DECLSPECDLLEXPORT tng_last_program_name_get
801 (const tng_trajectory_t tng_data,
802 char *name, const int max_len);
805 * @brief Set the name of the program used when last modifying the trajectory.
806 * @param tng_data the trajectory of which to set the program name.
807 * @param new_name is a string containing the wanted name.
808 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
809 * must be initialised before using it.
810 * @pre \code new_name != 0 \endcode The pointer to the new_name string
811 * must not be a NULL pointer.
812 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
815 tng_function_status DECLSPECDLLEXPORT tng_last_program_name_set
816 (tng_trajectory_t tng_data,
817 const char *new_name);
820 * @brief Get the name of the user who created the trajectory.
821 * @param tng_data the trajectory of which to get the user name.
822 * @param name the string to fill with the name of the user,
823 * memory must be allocated before.
824 * @param max_len maximum char length of the string, i.e. how much memory has
825 * been reserved for name. This includes \0 terminating character.
826 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
827 * must be initialised before using it.
828 * @pre \code name != 0 \endcode The pointer to the name string
829 * must not be a NULL pointer.
830 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
831 * has occurred (source string longer than destination string).
833 tng_function_status DECLSPECDLLEXPORT tng_first_user_name_get
834 (const tng_trajectory_t tng_data,
835 char *name, const int max_len);
838 * @brief Set the name of the user who created the trajectory.
839 * @param tng_data the trajectory of which to set the user name.
840 * @param new_name is a string containing the wanted name.
841 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
842 * must be initialised before using it.
843 * @pre \code new_name != 0 \endcode The pointer to the new_name string
844 * must not be a NULL pointer.
845 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
848 tng_function_status DECLSPECDLLEXPORT tng_first_user_name_set
849 (tng_trajectory_t tng_data,
850 const char *new_name);
853 * @brief Get the name of the user who last modified the trajectory.
854 * @param tng_data the trajectory of which to get the user name.
855 * @param name the string to fill with the name of the user,
856 * memory must be allocated before.
857 * @param max_len maximum char length of the string, i.e. how much memory has
858 * been reserved for name. This includes \0 terminating character.
859 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
860 * must be initialised before using it.
861 * @pre \code name != 0 \endcode The pointer to the name string
862 * must not be a NULL pointer.
863 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
864 * has occurred (source string longer than destination string).
866 tng_function_status DECLSPECDLLEXPORT tng_last_user_name_get
867 (const tng_trajectory_t tng_data,
868 char *name, const int max_len);
871 * @brief Set the name of the user who last modified the trajectory.
872 * @param tng_data the trajectory of which to set the user name.
873 * @param new_name is a string containing the wanted name.
874 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
875 * must be initialised before using it.
876 * @pre \code new_name != 0 \endcode The pointer to the new_name string
877 * must not be a NULL pointer.
878 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
881 tng_function_status DECLSPECDLLEXPORT tng_last_user_name_set
882 (tng_trajectory_t tng_data,
883 const char *new_name);
886 * @brief Get the name of the computer used when creating the trajectory.
887 * @param tng_data the trajectory of which to get the computer name.
888 * @param name the string to fill with the name of the computer,
889 * memory must be allocated before.
890 * @param max_len maximum char length of the string, i.e. how much memory has
891 * been reserved for name. This includes \0 terminating character.
892 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
893 * must be initialised before using it.
894 * @pre \code name != 0 \endcode The pointer to the name string
895 * must not be a NULL pointer.
896 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
897 * has occurred (source string longer than destination string).
899 tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_get
900 (const tng_trajectory_t tng_data,
901 char *name, const int max_len);
904 * @brief Set the name of the computer used when creating the trajectory.
905 * @param tng_data the trajectory of which to set the computer name.
906 * @param new_name is a string containing the wanted name.
907 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
908 * must be initialised before using it.
909 * @pre \code new_name != 0 \endcode The pointer to the new_name string
910 * must not be a NULL pointer.
911 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
914 tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_set
915 (tng_trajectory_t tng_data,
916 const char *new_name);
919 * @brief Get the name of the computer used when last modifying the trajectory.
920 * @param tng_data the trajectory of which to get the computer name.
921 * @param name the string to fill with the name of the computer,
922 * memory must be allocated before.
923 * @param max_len maximum char length of the string, i.e. how much memory has
924 * been reserved for name. This includes \0 terminating character.
925 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
926 * must be initialised before using it.
927 * @pre \code name != 0 \endcode The pointer to the name string
928 * must not be a NULL pointer.
929 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
930 * has occurred (source string longer than destination string).
932 tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_get
933 (const tng_trajectory_t tng_data,
934 char *name, const int max_len);
937 * @brief Set the name of the computer used when last modifying the trajectory.
938 * @param tng_data the trajectory of which to set the computer name.
939 * @param new_name is a string containing the wanted name.
940 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
941 * must be initialised before using it.
942 * @pre \code new_name != 0 \endcode The pointer to the new_name string
943 * must not be a NULL pointer.
944 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
947 tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_set
948 (tng_trajectory_t tng_data,
949 const char *new_name);
952 * @brief Get the pgp_signature of the user creating the trajectory.
953 * @param tng_data the trajectory of which to get the computer name.
954 * @param signature the string to fill with the signature,
955 * memory must be allocated before.
956 * @param max_len maximum char length of the string, i.e. how much memory has
957 * been reserved for name. This includes \0 terminating character.
958 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
959 * must be initialised before using it.
960 * @pre \code signature != 0 \endcode The pointer to the signature
961 * must not be a NULL pointer.
962 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
963 * has occurred (source string longer than destination string).
965 tng_function_status DECLSPECDLLEXPORT tng_first_signature_get
966 (const tng_trajectory_t tng_data,
967 char *signature, const int max_len);
970 * @brief Set the pgp_signature of the user creating the trajectory.
971 * @param tng_data the trajectory of which to set the computer name.
972 * @param signature is a string containing the pgp_signature.
973 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
974 * must be initialised before using it.
975 * @pre \code signature != 0 \endcode The pointer to the signature
976 * must not be a NULL pointer.
977 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
980 tng_function_status DECLSPECDLLEXPORT tng_first_signature_set
981 (tng_trajectory_t tng_data,
982 const char *signature);
985 * @brief Get the pgp_signature of the user last modifying the trajectory.
986 * @param tng_data the trajectory of which to get the computer name.
987 * @param signature the string to fill with the signature,
988 * memory must be allocated before.
989 * @param max_len maximum char length of the string, i.e. how much memory has
990 * been reserved for name. This includes \0 terminating character.
991 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
992 * must be initialised before using it.
993 * @pre \code signature != 0 \endcode The pointer to the signature
994 * must not be a NULL pointer.
995 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
996 * has occurred (source string longer than destination string).
998 tng_function_status DECLSPECDLLEXPORT tng_last_signature_get
999 (const tng_trajectory_t tng_data,
1000 char *signature, const int max_len);
1003 * @brief Set the pgp_signature of the user last modifying the trajectory.
1004 * @param tng_data the trajectory of which to set the computer name.
1005 * @param signature is a string containing the pgp_signature.
1006 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1007 * must be initialised before using it.
1008 * @pre \code signature != 0 \endcode The pointer to the signature
1009 * must not be a NULL pointer.
1010 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1011 * error has occured.
1013 tng_function_status DECLSPECDLLEXPORT tng_last_signature_set
1014 (tng_trajectory_t tng_data,
1015 const char *signature);
1018 * @brief Get the name of the forcefield used in the trajectory.
1019 * @param tng_data the trajectory of which to get the forcefield name.
1020 * @param name the string to fill with the name of the forcefield,
1021 * memory must be allocated before.
1022 * @param max_len maximum char length of the string, i.e. how much memory has
1023 * been reserved for name. This includes \0 terminating character.
1024 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1025 * must be initialised before using it.
1026 * @pre \code name != 0 \endcode The pointer to the name string
1027 * must not be a NULL pointer.
1028 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1029 * has occurred (source string longer than destination string).
1031 tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_get
1032 (const tng_trajectory_t tng_data,
1033 char *name, const int max_len);
1036 * @brief Set the name of the forcefield used in the trajectory.
1037 * @param tng_data the trajectory of which to set the forcefield name.
1038 * @param new_name is a string containing the wanted name.
1039 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1040 * must be initialised before using it.
1041 * @pre \code new_name != 0 \endcode The pointer to the new_name string
1042 * must not be a NULL pointer.
1043 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1044 * error has occured.
1046 tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_set
1047 (tng_trajectory_t tng_data,
1048 const char *new_name);
1051 * @brief Get the medium stride length of the trajectory.
1052 * @param tng_data is the trajectory from which to get the stride length.
1053 * @param len is pointing to a value set to the stride length.
1054 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1055 * must be initialised before using it.
1056 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer.
1057 * @return TNG_SUCCESS (0) if successful.
1059 tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_get
1060 (const tng_trajectory_t tng_data,
1064 * @brief Set the medium stride length of the trajectory.
1065 * @param tng_data is the trajectory of which to set the stride length.
1066 * @param len is the wanted medium stride length.
1067 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1068 * must be initialised before using it.
1069 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1072 tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_set
1073 (tng_trajectory_t tng_data,
1077 * @brief Get the long stride length of the trajectory.
1078 * @param tng_data is the trajectory from which to get the stride length.
1079 * @param len is pointing to a value set to the stride length.
1080 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1081 * must be initialised before using it.
1082 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer.
1083 * @return TNG_SUCCESS (0) if successful.
1085 tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_get
1086 (const tng_trajectory_t tng_data,
1090 * @brief Set the long stride length of the trajectory.
1091 * @param tng_data is the trajectory of which to set the stride length.
1092 * @param len is the wanted long stride length.
1093 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1094 * must be initialised before using it.
1095 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1098 tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_set
1099 (tng_trajectory_t tng_data,
1103 * @brief Get the current time per frame of the trajectory.
1104 * @param tng_data is the trajectory from which to get the time per frame.
1105 * @param time is pointing to a value set to the time per frame.
1106 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1107 * must be initialised before using it.
1108 * @pre \code time != 0 \endcode The pointer to time must not be a NULL pointer.
1109 * @return TNG_SUCCESS (0) if successful.
1111 tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_get
1112 (const tng_trajectory_t tng_data,
1116 * @brief Set the time per frame of the trajectory.
1117 * @param tng_data is the trajectory of which to set the time per frame.
1118 * @param time is the new time per frame.
1119 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1120 * must be initialised before using it.
1121 * @pre \code time > 0 \endcode The time per frame must be >= 0.
1122 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1125 tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_set
1126 (tng_trajectory_t tng_data,
1130 * @brief Get the length of the input file.
1131 * @param tng_data is the trajectory from which to get the input file length.
1132 * @param len is pointing to a value set to the file length.
1133 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1134 * must be initialised before using it.
1135 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer.
1136 * @return TNG_SUCCESS (0) if successful.
1138 tng_function_status DECLSPECDLLEXPORT tng_input_file_len_get
1139 (const tng_trajectory_t tng_data,
1143 * @brief Get the number of frames in the trajectory
1144 * @param tng_data is the trajectory of which to get the number of frames.
1145 * @param n is pointing to a value set to the number of frames.
1146 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1147 * must be initialised before using it.
1148 * @pre \code tng_data->input_file != 0 \endcode An input file must be open
1149 * to find the next frame set.
1150 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1151 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1152 * has occurred (could not find last frame set).
1154 tng_function_status DECLSPECDLLEXPORT tng_num_frames_get
1155 (const tng_trajectory_t tng_data,
1159 * @brief Get the precision of lossy compression.
1160 * @param tng_data is the trajectory of which to get the compression precision.
1161 * @param precision will be pointing to the retrieved compression precision.
1162 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1163 * must be initialised before using it.
1164 * @details A compression precision of 0.001 (the default) means that the
1165 * compressed values are accurate to the third decimal. This function does
1166 * not check actual precision of compressed data, but just returns what has
1167 * previously been set using tng_compression_precision_set().
1168 * @return TNG_SUCCESS (0) if successful.
1170 tng_function_status DECLSPECDLLEXPORT tng_compression_precision_get
1171 (const tng_trajectory_t tng_data,
1175 * @brief Set the precision of lossy compression.
1176 * @param tng_data is the trajectory of which to set the compression precision.
1177 * @param precision is the new compression precision.
1178 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1179 * must be initialised before using it.
1180 * @details A compression precision of 0.001 (the default) means that the
1181 * compressed values are accurate to the third decimal.
1182 * @return TNG_SUCCESS (0) if successful.
1184 tng_function_status DECLSPECDLLEXPORT tng_compression_precision_set
1185 (tng_trajectory_t tng_data,
1186 const double precision);
1189 * @brief Set the number of particles, in the case no molecular system is used.
1190 * @param tng_data is the trajectory of which to get the number of particles.
1191 * @param n is the number of particles to use.
1192 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1193 * must be initialised before using it.
1194 * @details When creating a molecular system the number of particles are set
1195 * automatically. This should only be used when there is no molecular system
1196 * specified or if the number of atoms needs to be overridden for some reason.
1197 * @return TNG_SUCCESS (0) if successful.
1199 tng_function_status DECLSPECDLLEXPORT tng_implicit_num_particles_set
1200 (tng_trajectory_t tng_data,
1204 * @brief Get the current number of particles.
1205 * @param tng_data is the trajectory from which to get the number of particles.
1206 * @param n is pointing to a value set to the number of particles.
1207 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1208 * must be initialised before using it.
1209 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1210 * @details If variable number of particles are used this function will return
1211 * the number of particles in the current frame set.
1212 * @return TNG_SUCCESS (0) if successful.
1214 tng_function_status DECLSPECDLLEXPORT tng_num_particles_get
1215 (const tng_trajectory_t tng_data,
1219 * @brief Get if the number of particle can be varied during the simulation.
1220 * @param tng_data is the trajectory from which to get the number of particles.
1221 * @param variable is pointing to a value set to TNG_CONSTANT_N_ATOMS if the
1222 * number of particles cannot change or TNG_VARIABLE_N_ATOMS if the number of
1223 * particles can change.
1224 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1225 * must be initialised before using it.
1226 * @pre \code variable != 0 \endcode The pointer to variable must not be
1228 * @return TNG_SUCCESS (0) if successful.
1230 tng_function_status DECLSPECDLLEXPORT tng_num_particles_variable_get
1231 (const tng_trajectory_t tng_data,
1235 * @brief Get the number of molecule types (length of tng_data->molecules).
1236 * @param tng_data is the trajectory from which to get the number of molecules.
1237 * @param n is pointing to a value set to the number of molecule types.
1238 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1239 * must be initialised before using it.
1240 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1241 * @return TNG_SUCCESS (0) if successful.
1243 tng_function_status DECLSPECDLLEXPORT tng_num_molecule_types_get
1244 (const tng_trajectory_t tng_data,
1248 * @brief Get the current total number of molecules.
1249 * @param tng_data is the trajectory from which to get the number of molecules.
1250 * @param n is pointing to a value set to the number of molecules.
1251 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1252 * must be initialised before using it.
1253 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1254 * @details If variable number of particles are used this function will return
1255 * the total number of molecules in the current frame set.
1256 * @return TNG_SUCCESS (0) if successful.
1258 tng_function_status DECLSPECDLLEXPORT tng_num_molecules_get
1259 (const tng_trajectory_t tng_data,
1262 /** @brief Get the list of the count of each molecule.
1263 * @param tng_data is the trajectory from which to get the molecule count list.
1264 * @param mol_cnt_list is a list of the count of each molecule in the
1265 * mol system. This is a pointer to the list in the TNG container, which
1266 * means that it should be handled carefully, e.g. not freed.
1267 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1268 * must be initialised before using it.
1269 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE(1) if the list of
1270 * molecule counts was not valid.
1272 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_list_get
1273 (const tng_trajectory_t tng_data,
1274 int64_t **mol_cnt_list);
1277 * @brief Get the exponent used for distances in the trajectory.
1278 * @param tng_data is the trajectory from which to get the information.
1279 * @param exp is pointing to a value set to the distance unit exponent.
1280 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1281 * must be initialised before using it.
1282 * @pre \code exp != 0 \endcode The pointer to exp must not be a NULL pointer.
1283 * @details Example: If the distances are specified in nm (default) exp is -9.
1284 * If the distances are specified in Ă
exp is -10.
1285 * @return TNG_SUCCESS (0) if successful.
1287 tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_get
1288 (const tng_trajectory_t tng_data,
1292 * @brief Set the exponent used for distances in the trajectory.
1293 * @param tng_data is the trajectory of which to set the unit exponent.
1294 * @param exp is the distance unit exponent to use.
1295 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1296 * must be initialised before using it.
1297 * @details Example: If the distances are specified in nm (default) exp is -9.
1298 * If the distances are specified in Ă
exp is -10.
1299 * @return TNG_SUCCESS (0) if successful.
1301 tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_set
1302 (const tng_trajectory_t tng_data,
1306 * @brief Get the number of frames per frame set.
1307 * @param tng_data is the trajectory from which to get the number of frames
1309 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1310 * must be initialised before using it.
1311 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1312 * @param n is pointing to a value set to the number of frames per frame set.
1313 * @return TNG_SUCCESS (0) if successful.
1315 tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_get
1316 (const tng_trajectory_t tng_data,
1320 * @brief Set the number of frames per frame set.
1321 * @param tng_data is the trajectory of which to set the number of frames
1323 * @param n is the number of frames per frame set.
1324 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1325 * must be initialised before using it.
1326 * @details This does not affect already existing frame sets. For
1327 * consistency the number of frames per frame set should be set
1328 * betfore creating any frame sets.
1329 * @return TNG_SUCCESS (0) if successful.
1331 tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_set
1332 (const tng_trajectory_t tng_data,
1336 * @brief Get the number of frame sets.
1337 * @details This updates tng_data->n_trajectory_frame_sets before returning it.
1338 * @param tng_data is the trajectory from which to get the number of frame sets.
1339 * @param n is pointing to a value set to the number of frame sets.
1340 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1341 * must be initialised before using it.
1342 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1343 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1344 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1346 tng_function_status DECLSPECDLLEXPORT tng_num_frame_sets_get
1347 (const tng_trajectory_t tng_data,
1351 * @brief Get the current trajectory frame set.
1352 * @param tng_data is the trajectory from which to get the frame set.
1353 * @param frame_set_p will be set to point at the memory position of
1354 * the found frame set.
1355 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1356 * must be initialised before using it.
1357 * @return TNG_SUCCESS (0) if successful.
1359 tng_function_status DECLSPECDLLEXPORT tng_current_frame_set_get
1360 (const tng_trajectory_t tng_data,
1361 tng_trajectory_frame_set_t *frame_set_p);
1364 * @brief Find the requested frame set number.
1365 * @param tng_data is the trajectory from which to get the frame set.
1366 * @param nr is the frame set number to search for.
1367 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1368 * must be initialised before using it.
1369 * @pre \code nr >= 0 \endcode The frame set number (nr) must be >= 0.
1370 * @details tng_data->current_trajectory_frame_set will contain the
1371 * found trajectory if successful.
1372 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1373 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1375 tng_function_status DECLSPECDLLEXPORT tng_frame_set_nr_find
1376 (tng_trajectory_t tng_data,
1380 * @brief Find the frame set containing a specific frame.
1381 * @param tng_data is the trajectory from which to get the frame set.
1382 * @param frame is the frame number to search for.
1383 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1384 * must be initialised before using it.
1385 * @pre \code frame >= 0 \endcode The frame number must be >= 0.
1386 * @details tng_data->current_trajectory_frame_set will contain the
1387 * found trajectory if successful.
1388 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1389 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1391 tng_function_status DECLSPECDLLEXPORT tng_frame_set_of_frame_find
1392 (tng_trajectory_t tng_data,
1393 const int64_t frame);
1396 * @brief Get the file position of the next frame set in the input file.
1397 * @param tng_data is a trajectory data container.
1398 * @param frame_set is the frame set of which to get the position of the
1399 * following frame set.
1400 * @param pos is pointing to a value set to the file position.
1401 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1402 * must be initialised before using it.
1403 * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer.
1404 * @return TNG_SUCCESS (0) if successful.
1406 tng_function_status DECLSPECDLLEXPORT tng_frame_set_next_frame_set_file_pos_get
1407 (const tng_trajectory_t tng_data,
1408 const tng_trajectory_frame_set_t frame_set,
1412 * @brief Get the file position of the previous frame set in the input file.
1413 * @param tng_data is a trajectory data container.
1414 * @param frame_set is the frame set of which to get the position of the
1415 * previous frame set.
1416 * @param pos is pointing to a value set to the file position.
1417 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1418 * must be initialised before using it.
1419 * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer.
1420 * @return TNG_SUCCESS (0) if successful.
1422 tng_function_status DECLSPECDLLEXPORT tng_frame_set_prev_frame_set_file_pos_get
1423 (const tng_trajectory_t tng_data,
1424 const tng_trajectory_frame_set_t frame_set,
1428 * @brief Get the first and last frames of the frame set.
1429 * @param tng_data is a trajectory data container.
1430 * @param frame_set is the frame set of which to get the frame range.
1431 * @param first_frame is set to the first frame of the frame set.
1432 * @param last_frame is set to the last frame of the frame set.
1433 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1434 * must be initialised before using it.
1435 * @pre \code first_frame != 0 \endcode The pointer to first_frame must
1436 * not be a NULL pointer.
1437 * @pre \code last_frame != 0 \endcode The pointer to last_frame must
1438 * not be a NULL pointer.
1439 * @return TNG_SUCCESS (0) if successful.
1441 tng_function_status DECLSPECDLLEXPORT tng_frame_set_frame_range_get
1442 (const tng_trajectory_t tng_data,
1443 const tng_trajectory_frame_set_t frame_set,
1444 int64_t *first_frame,
1445 int64_t *last_frame);
1448 * @brief Allocate memory for and setup a molecule container.
1449 * @param tng_data is a trajectory data container.
1450 * @param molecule_p is a pointer to molecule to allocate and initialise.
1451 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1452 * error has occured.
1454 tng_function_status DECLSPECDLLEXPORT tng_molecule_alloc(const tng_trajectory_t tng_data,
1455 tng_molecule_t *molecule_p);
1458 * @brief Clean up a molecule container and free its allocated memory.
1459 * @param tng_data is a trajectory data container.
1460 * @param molecule_p is the molecule to destroy.
1461 * @details All allocated memory in the data structure is freed and also the memory
1462 * of the molecule itself.
1463 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1464 * error has occured.
1466 tng_function_status DECLSPECDLLEXPORT tng_molecule_free(const tng_trajectory_t tng_data,
1467 tng_molecule_t *molecule_p);
1470 * @brief Setup a molecule container.
1471 * @param tng_data is a trajectory data container.
1472 * @param molecule is the molecule to initialise. Memory must be preallocated.
1473 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1474 * error has occured.
1476 tng_function_status DECLSPECDLLEXPORT tng_molecule_init
1477 (const tng_trajectory_t tng_data,
1478 tng_molecule_t molecule);
1481 * @brief Clean up a molecule container.
1482 * @param tng_data is a trajectory data container.
1483 * @param molecule is the molecule to destroy.
1484 * @details All allocated memory in the data structure is freed, but not the
1485 * memory of molecule itself.
1486 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1487 * error has occured.
1489 tng_function_status DECLSPECDLLEXPORT tng_molecule_destroy
1490 (const tng_trajectory_t tng_data,
1491 tng_molecule_t molecule);
1494 * @brief Add a molecule to the trajectory.
1495 * @param tng_data is the trajectory data container containing the block..
1496 * @param name is a pointer to the string containing the name of the new molecule.
1497 * @param molecule is a pointer to the newly created molecule.
1498 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1499 * must be initialised before using it.
1500 * @pre \code name != 0 \endcode The pointer to the name string
1501 * must not be a NULL pointer.
1502 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1503 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1505 tng_function_status DECLSPECDLLEXPORT tng_molecule_add
1506 (tng_trajectory_t tng_data,
1508 tng_molecule_t *molecule);
1511 * @brief Add a molecule with a specific ID to the trajectory.
1512 * @param tng_data is the trajectory data container containing the block..
1513 * @param name is a pointer to the string containing the name of the new molecule.
1514 * @param id is the ID of the created molecule.
1515 * @param molecule is a pointer to the newly created molecule.
1516 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1517 * must be initialised before using it.
1518 * @pre \code name != 0 \endcode The pointer to the name string
1519 * must not be a NULL pointer.
1520 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1521 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1523 tng_function_status DECLSPECDLLEXPORT tng_molecule_w_id_add
1524 (tng_trajectory_t tng_data,
1527 tng_molecule_t *molecule);
1530 * @brief Add an existing molecule (from a molecule container) to the trajectory.
1531 * @param tng_data is the trajectory data container containing the block..
1532 * @param molecule is a pointer to the molecule to add to the trajectory and will
1533 * afterwards point to the molecule in the trajectory.
1534 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1535 * must be initialised before using it.
1536 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error
1539 tng_function_status DECLSPECDLLEXPORT tng_molecule_existing_add
1540 (tng_trajectory_t tng_data,
1541 tng_molecule_t *molecule);
1544 * @brief Get the name of a molecule.
1545 * @param tng_data the trajectory containing the molecule.
1546 * @param molecule the molecule of which to get the name.
1547 * @param name the string to fill with the name of the molecule,
1548 * memory must be allocated before.
1549 * @param max_len maximum char length of the string, i.e. how much memory has
1550 * been reserved for name. This includes \0 terminating character.
1551 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1552 * @pre \code name != 0 \endcode The pointer to the name string
1553 * must not be a NULL pointer.
1554 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1555 * has occurred (source string longer than destination string).
1557 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_get
1558 (const tng_trajectory_t tng_data,
1559 const tng_molecule_t molecule,
1564 * @brief Set the name of a molecule.
1565 * @param tng_data is the trajectory data container containing the molecule..
1566 * @param molecule is the molecule to rename.
1567 * @param new_name is a string containing the wanted name.
1568 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1569 * must be initialised before using it.
1570 * @pre \code new_name != 0 \endcode The pointer to the name string
1571 * must not be a NULL pointer.
1572 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1573 * error has occured.
1575 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_set
1576 (tng_trajectory_t tng_data,
1577 tng_molecule_t molecule,
1578 const char *new_name);
1581 * @brief Get the count of a molecule.
1582 * @param tng_data is the trajectory data container containing the molecule..
1583 * @param molecule is the molecule of which to get the count.
1584 * @param cnt is a pointer to the variable to be populated with the count.
1585 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1586 * must be initialised before using it.
1587 * @pre \code cnt != 0 \endcode The pointer to the molecule count
1588 * must not be a NULL pointer.
1589 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1590 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1592 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_get
1593 (const tng_trajectory_t tng_data,
1594 const tng_molecule_t molecule,
1598 * @brief Set the count of a molecule.
1599 * @param tng_data is the trajectory data container containing the molecule..
1600 * @param molecule is the molecule of which to set the count.
1601 * @param cnt is the number of instances of this molecule.
1602 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1603 * must be initialised before using it.
1604 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1605 * has occurred or TNG_CRITICAL (2) if a major error has occured.
1607 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_set
1608 (tng_trajectory_t tng_data,
1609 tng_molecule_t molecule,
1613 * @brief Find a molecule.
1614 * @param tng_data is the trajectory data container containing the molecule.
1615 * @param name is a string containing the name of the molecule. If name is empty
1616 * only id will be used for finding the molecule.
1617 * @param id is the id of the molecule to look for. If id is -1 only the name of
1618 * the molecule will be used for finding the molecule.
1619 * @param molecule is a pointer to the molecule if it was found - otherwise 0.
1620 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1621 * must be initialised before using it.
1622 * @pre \code name != 0 \endcode The pointer to the name string
1623 * must not be a NULL pointer.
1624 * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the
1625 * molecule is not found.
1626 * @details If name is an empty string and id == -1 the first residue will
1629 tng_function_status DECLSPECDLLEXPORT tng_molecule_find
1630 (tng_trajectory_t tng_data,
1633 tng_molecule_t *molecule);
1636 * @brief Retrieve the molecule with specified index in the list of molecules.
1637 * @param tng_data is the trajectory data container containing the molecule.
1638 * @param index is the index (in tng_data->molecules) of the molecule to return
1639 * @param molecule is a pointer to the molecule if it was found - otherwise 0.
1640 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1641 * must be initialised before using it.
1642 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1643 * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the
1644 * molecule is not found.
1646 tng_function_status DECLSPECDLLEXPORT tng_molecule_of_index_get
1647 (tng_trajectory_t tng_data,
1649 tng_molecule_t *molecule);
1652 * @brief Copy all molecules and the molecule counts from one TNG trajectory
1654 * @param tng_data_src is the source trajectory containing the molecular
1656 * @param tng_data_dest is the destination trajectory.
1657 * @pre \code tng_data_src != 0 \endcode The trajectory container (tng_data_src)
1658 * must be initialised before using it.
1659 * @pre \code tng_data_dest != 0 \endcode The trajectory container (tng_data_dest)
1660 * must be initialised before using it.
1661 * @details The molecular system in tng_data_dest will be overwritten.
1662 * @return TNG_SUCCESS(0) if the copying is successful, TNG_FAILURE if a minor
1663 * error has occured or TNG_CRITICAL(2) if a major error has occured.
1665 tng_function_status DECLSPECDLLEXPORT tng_molecule_system_copy(tng_trajectory_t tng_data_src,
1666 tng_trajectory_t tng_data_dest);
1669 * @brief Get the number of chains in a molecule.
1670 * @param tng_data is the trajectory containing the molecule.
1671 * @param molecule is the molecule of which to get the number of chains.
1672 * @param n is pointing to a value set to the number of chains.
1673 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1674 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1675 * @return TNG_SUCCESS (0) if successful.
1677 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_chains_get
1678 (const tng_trajectory_t tng_data,
1679 const tng_molecule_t molecule,
1683 * @brief Retrieve the chain of a molecule with specified index in the list
1685 * @param tng_data is the trajectory data container containing the molecule.
1686 * @param index is the index (in molecule->chains) of the chain to return
1687 * @param molecule is the molecule from which to get the chain.
1688 * @param chain is a pointer to the chain if it was found - otherwise 0.
1689 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1690 * @pre \code chain != 0 \endcode chain must not be a NULL pointer.
1691 * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the
1692 * chain is not found.
1694 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_of_index_get
1695 (tng_trajectory_t tng_data,
1696 tng_molecule_t molecule,
1698 tng_chain_t *chain);
1701 * @brief Get the number of residues in a molecule.
1702 * @param tng_data is the trajectory containing the molecule.
1703 * @param molecule is the molecule of which to get the number residues.
1704 * @param n is pointing to a value set to the number of residues.
1705 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1706 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1707 * @return TNG_SUCCESS (0) if successful.
1709 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_residues_get
1710 (const tng_trajectory_t tng_data,
1711 const tng_molecule_t molecule,
1715 * @brief Retrieve the residue of a molecule with specified index in the list
1717 * @param tng_data is the trajectory data container containing the molecule.
1718 * @param index is the index (in molecule->residues) of the residue to return
1719 * @param molecule is the molecule from which to get the residue.
1720 * @param residue is a pointer to the residue if it was found - otherwise 0.
1721 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1722 * @pre \code residue != 0 \endcode residue must not be a NULL pointer.
1723 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the
1724 * residue is not found.
1726 tng_function_status DECLSPECDLLEXPORT tng_molecule_residue_of_index_get
1727 (const tng_trajectory_t tng_data,
1728 const tng_molecule_t molecule,
1729 const int64_t index,
1730 tng_residue_t *residue);
1733 * @brief Get the number of atoms in a molecule.
1734 * @param tng_data is the trajectory containing the molecule.
1735 * @param molecule is the molecule of which to get the number of atoms.
1736 * @param n is pointing to a value set to the number of atoms.
1737 * @pre \code molecule != 0 \endcode The molecule must not be NULL.
1738 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1739 * @return TNG_SUCCESS (0) if successful.
1741 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_atoms_get
1742 (const tng_trajectory_t tng_data,
1743 const tng_molecule_t molecule,
1747 * @brief Retrieve the atom of a molecule with specified index in the list
1749 * @param tng_data is the trajectory data container containing the molecule.
1750 * @param index is the index (in molecule->atoms) of the atom to return
1751 * @param molecule is the molecule from which to get the atom.
1752 * @param atom is a pointer to the atom if it was found - otherwise 0.
1753 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer.
1754 * @pre \code atom != 0 \endcode atom must not be a NULL pointer.
1755 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the
1756 * atom is not found.
1758 tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_of_index_get
1759 (const tng_trajectory_t tng_data,
1760 const tng_molecule_t molecule,
1761 const int64_t index,
1765 * @brief Find a chain in a molecule.
1766 * @param tng_data is the trajectory data container containing the molecule.
1767 * @param molecule is the molecule in which to search for the chain.
1768 * @param name is a string containing the name of the chain. If name is empty
1769 * only id will be used for finding the chain.
1770 * @param id is the id of the chain to look for. If id is -1 only the name of
1771 * the chain will be used for finding the chain.
1772 * @param chain is a pointer to the chain if it was found - otherwise 0.
1773 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1774 * must be initialised before using it.
1775 * @pre \code name != 0 \endcode The pointer to the name string
1776 * must not be a NULL pointer.
1777 * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the
1778 * chain is not found.
1779 * @details If name is an empty string and id == -1 the first residue will
1782 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_find
1783 (tng_trajectory_t tng_data,
1784 tng_molecule_t molecule,
1787 tng_chain_t *chain);
1790 * @brief Add a chain to a molecule.
1791 * @param tng_data is the trajectory data container containing the molecule..
1792 * @param molecule is the molecule to add a chain to.
1793 * @param name is a string containing the name of the chain.
1794 * @param chain is a pointer to the newly created chain.
1795 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1796 * must be initialised before using it.
1797 * @pre \code name != 0 \endcode The pointer to the name string
1798 * must not be a NULL pointer.
1799 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1800 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1802 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_add
1803 (tng_trajectory_t tng_data,
1804 tng_molecule_t molecule,
1806 tng_chain_t *chain);
1809 * @brief Add a chain with a specific id to a molecule.
1810 * @param tng_data is the trajectory data container containing the molecule..
1811 * @param molecule is the molecule to add a chain to.
1812 * @param name is a string containing the name of the chain.
1813 * @param id is the ID of the created chain.
1814 * @param chain is a pointer to the newly created chain.
1815 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1816 * must be initialised before using it.
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 the ID could
1820 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1822 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_w_id_add
1823 (tng_trajectory_t tng_data,
1824 tng_molecule_t molecule,
1827 tng_chain_t *chain);
1830 * @brief Add a bond between two atoms to a molecule.
1831 * @param tng_data is the trajectory data container containing the molecule.
1832 * @param molecule is the molecule containing the atoms to connect.
1833 * @param from_atom_id is the id of one of the two atoms in the bond.
1834 * @param to_atom_id is the id of the other atom in the bond.
1835 * @param bond is a pointer to the newly created bond.
1836 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1837 * must be initialised before using it.
1838 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (!) if a minor error
1839 * has occured or TNG_CRITICAL (2) if a major error has occured.
1841 tng_function_status DECLSPECDLLEXPORT tng_molecule_bond_add
1842 (const tng_trajectory_t tng_data,
1843 tng_molecule_t molecule,
1844 const int64_t from_atom_id,
1845 const int64_t to_atom_id,
1849 * @brief Find an atom in a molecule.
1850 * @param tng_data is the trajectory data container containing the molecule.
1851 * @param molecule is the molecule in which to search for the atom.
1852 * @param name is a string containing the name of the atom. If name is an
1853 * empty string only id will be used for searching.
1854 * @param id is the id of the atom to find. If id == -1 the first atom
1855 * that matches the specified name will be found.
1856 * @param atom is a pointer to the atom if it was found - otherwise 0.
1857 * @pre \code name != 0 \endcode The pointer to the name string
1858 * must not be a NULL pointer.
1859 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the
1860 * atom is not found.
1861 * @details If name is an empty string and id == -1 the first residue will
1864 tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_find
1865 (tng_trajectory_t tng_data,
1866 tng_molecule_t molecule,
1872 * @brief Get the name of a chain.
1873 * @param tng_data the trajectory containing the chain.
1874 * @param chain the chain of which to get the name.
1875 * @param name the string to fill with the name of the chain,
1876 * memory must be allocated before.
1877 * @param max_len maximum char length of the string, i.e. how much memory has
1878 * been reserved for name. This includes \0 terminating character.
1879 * @pre \code chain != 0 \endcode The chain must not be NULL.
1880 * @pre \code name != 0 \endcode The pointer to the name string
1881 * must not be a NULL pointer.
1882 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1883 * has occurred (source string longer than destination string).
1885 tng_function_status DECLSPECDLLEXPORT tng_chain_name_get
1886 (const tng_trajectory_t tng_data,
1887 const tng_chain_t chain,
1892 * @brief Set the name of a chain.
1893 * @param tng_data is the trajectory data container containing the atom..
1894 * @param chain is the chain to rename.
1895 * @param new_name is a string containing the wanted name.
1896 * @pre \code new_name != 0 \endcode The pointer to the name string
1897 * must not be a NULL pointer.
1898 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1899 * error has occured.
1901 tng_function_status DECLSPECDLLEXPORT tng_chain_name_set
1902 (tng_trajectory_t tng_data,
1904 const char *new_name);
1907 * @brief Get the number of residues in a molecule chain.
1908 * @param tng_data is the trajectory containing the chain.
1909 * @param chain is the chain of which to get the number of residues.
1910 * @param n is pointing to a value set to the number of residues.
1911 * @pre \code chain != 0 \endcode The chain must not be NULL.
1912 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
1913 * @return TNG_SUCCESS (0) if successful.
1915 tng_function_status DECLSPECDLLEXPORT tng_chain_num_residues_get
1916 (const tng_trajectory_t tng_data,
1917 const tng_chain_t chain,
1921 * @brief Retrieve the residue of a chain with specified index in the list
1923 * @param tng_data is the trajectory data container containing the chain.
1924 * @param index is the index (in chain->residues) of the residue to return
1925 * @param chain is the chain from which to get the residue.
1926 * @param residue is a pointer to the residue if it was found - otherwise 0.
1927 * @pre \code chain != 0 \endcode chain must not be a NULL pointer.
1928 * @pre \code residue != 0 \endcode residue must not be a NULL pointer.
1929 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the
1930 * residue is not found.
1932 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_of_index_get
1933 (const tng_trajectory_t tng_data,
1934 const tng_chain_t chain,
1935 const int64_t index,
1936 tng_residue_t *residue);
1939 * @brief Find a residue in a chain.
1940 * @param tng_data is the trajectory data container containing the chain.
1941 * @param chain is the chain in which to search for the residue.
1942 * @param name is a string containing the name of the residue. If name is an
1943 * empty string only id will be used for searching.
1944 * @param id is the id of the residue to find. If id == -1 the first residue
1945 * that matches the specified name will be found.
1946 * @param residue is a pointer to the residue if it was found - otherwise 0.
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 the residue is found or TNG_FAILURE (1) if the
1950 * residue is not found.
1951 * @details If name is an empty string and id == -1 the first residue will
1954 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_find
1955 (tng_trajectory_t tng_data,
1959 tng_residue_t *residue);
1962 * @brief Add a residue to a chain.
1963 * @param tng_data is the trajectory data container containing the chain..
1964 * @param chain is the chain to add a residue to.
1965 * @param name is a string containing the name of the residue.
1966 * @param residue is a pointer to the newly created residue.
1967 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1968 * must be initialised before using it.
1969 * @pre \code name != 0 \endcode The pointer to the name string
1970 * must not be a NULL pointer.
1971 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1972 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1974 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_add
1975 (tng_trajectory_t tng_data,
1978 tng_residue_t *residue);
1981 * @brief Add a residue with a specific ID to a chain.
1982 * @param tng_data is the trajectory data container containing the chain..
1983 * @param chain is the chain to add a residue to.
1984 * @param name is a string containing the name of the residue.
1985 * @param id is the ID of the created residue.
1986 * @param residue is a pointer to the newly created residue.
1987 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
1988 * must be initialised before using it.
1989 * @pre \code name != 0 \endcode The pointer to the name string
1990 * must not be a NULL pointer.
1991 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1992 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1994 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_w_id_add
1995 (tng_trajectory_t tng_data,
1999 tng_residue_t *residue);
2002 * @brief Get the name of a residue.
2003 * @param tng_data the trajectory containing the residue.
2004 * @param residue the residue of which to get the name.
2005 * @param name the string to fill with the name of the residue,
2006 * memory must be allocated before.
2007 * @param max_len maximum char length of the string, i.e. how much memory has
2008 * been reserved for name. This includes \0 terminating character.
2009 * @pre \code residue != 0 \endcode The residue must not be NULL.
2010 * @pre \code name != 0 \endcode The pointer to the name string
2011 * must not be a NULL pointer.
2012 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2013 * has occurred (source string longer than destination string).
2015 tng_function_status DECLSPECDLLEXPORT tng_residue_name_get
2016 (const tng_trajectory_t tng_data,
2017 const tng_residue_t residue,
2022 * @brief Set the name of a residue.
2023 * @param tng_data is the trajectory data container containing the residue.
2024 * @param residue is the residue to rename.
2025 * @param new_name is a string containing the wanted name.
2026 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2027 * must be initialised before using it.
2028 * @pre \code new_name != 0 \endcode The new name to set (new_name) must
2029 * not be a NULL pointer.
2030 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2031 * error has occured.
2033 tng_function_status DECLSPECDLLEXPORT tng_residue_name_set
2034 (tng_trajectory_t tng_data,
2035 tng_residue_t residue,
2036 const char *new_name);
2039 * @brief Get the number of atoms in a residue.
2040 * @param tng_data is the trajectory containing the residue.
2041 * @param residue is the residue of which to get the number atoms.
2042 * @param n is pointing to a value set to the number of atoms.
2043 * @pre \code residue != 0 \endcode The residue must not be NULL.
2044 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer.
2045 * @return TNG_SUCCESS (0) if successful.
2047 tng_function_status DECLSPECDLLEXPORT tng_residue_num_atoms_get
2048 (const tng_trajectory_t tng_data,
2049 const tng_residue_t residue,
2053 * @brief Retrieve the atom of a residue with specified index in the list
2055 * @param tng_data is the trajectory data container containing the residue.
2056 * @param index is the index (in residue->atoms) of the atom to return
2057 * @param residue is the residue from which to get the atom.
2058 * @param atom is a pointer to the atom if it was found - otherwise 0.
2059 * @pre \code residue != 0 \endcode residue must not be a NULL pointer.
2060 * @pre \code atom != 0 \endcode atom must not be a NULL pointer.
2061 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the
2062 * atom is not found.
2064 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_of_index_get
2065 (const tng_trajectory_t tng_data,
2066 const tng_residue_t residue,
2067 const int64_t index,
2071 * @brief Add an atom to a residue.
2072 * @param tng_data is the trajectory containing the residue.
2073 * @param residue is the residue to add an atom to.
2074 * @param atom_name is a string containing the name of the atom.
2075 * @param atom_type is a string containing the atom type of the atom.
2076 * @param atom is a pointer to the newly created atom.
2077 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2078 * must be initialised before using it.
2079 * @pre \code atom_name != 0 \endcode The pointer to the atom name string
2080 * must not be a NULL pointer.
2081 * @pre \code atom_type != 0 \endcode The pointer to the atom_type string
2082 * must not be a NULL pointer.
2083 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
2084 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
2086 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_add
2087 (tng_trajectory_t tng_data,
2088 tng_residue_t residue,
2089 const char *atom_name,
2090 const char *atom_type,
2094 * @brief Add an atom with a specific ID to a residue.
2095 * @param tng_data is the trajectory containing the residue.
2096 * @param residue is the residue to add an atom to.
2097 * @param atom_name is a string containing the name of the atom.
2098 * @param atom_type is a string containing the atom type of the atom.
2099 * @param id is the ID of the created atom.
2100 * @param atom is a pointer to the newly created atom.
2101 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2102 * must be initialised before using it.
2103 * @pre \code atom_name != 0 \endcode The pointer to the atom name string
2104 * must not be a NULL pointer.
2105 * @pre \code atom_type != 0 \endcode The pointer to the atom_type string
2106 * must not be a NULL pointer.
2107 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
2108 * not be set properly or TNG_CRITICAL (2) if a major error has occured.
2110 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_w_id_add
2111 (tng_trajectory_t tng_data,
2112 tng_residue_t residue,
2113 const char *atom_name,
2114 const char *atom_type,
2119 * @brief Get the residue of an atom.
2120 * @param tng_data the trajectory containing the atom.
2121 * @param atom the atom of which to get the name.
2122 * @param residue is set to the residue of the atom.
2123 * @pre \code atom != 0 \endcode The atom must not be NULL.
2124 * @return TNG_SUCCESS (0) if successful.
2126 tng_function_status tng_atom_residue_get(const tng_trajectory_t tng_data,
2127 const tng_atom_t atom,
2128 tng_residue_t *residue);
2131 * @brief Get the name of an atom.
2132 * @param tng_data the trajectory containing the atom.
2133 * @param atom the atom of which to get the name.
2134 * @param name the string to fill with the name of the atom,
2135 * memory must be allocated before.
2136 * @param max_len maximum char length of the string, i.e. how much memory has
2137 * been reserved for name. This includes \0 terminating character.
2138 * @pre \code atom != 0 \endcode The atom must not be NULL.
2139 * @pre \code name != 0 \endcode The pointer to the name string
2140 * must not be a NULL pointer.
2141 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2142 * has occurred (source string longer than destination string).
2144 tng_function_status DECLSPECDLLEXPORT tng_atom_name_get
2145 (const tng_trajectory_t tng_data,
2146 const tng_atom_t atom,
2151 * @brief Set the name of an atom.
2152 * @param tng_data is the trajectory data container containing the atom.
2153 * @param atom is the atom to rename.
2154 * @param new_name is a string containing the wanted name.
2155 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2156 * must be initialised before using it.
2157 * @pre \code new_name != 0 \endcode The pointer to the name string
2158 * must not be a NULL pointer.
2159 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2160 * error has occured.
2162 tng_function_status DECLSPECDLLEXPORT tng_atom_name_set
2163 (tng_trajectory_t tng_data,
2165 const char *new_name);
2168 * @brief Get the type of an atom.
2169 * @param tng_data the trajectory containing the atom.
2170 * @param atom the atom of which to get the type.
2171 * @param type the string to fill with the type of the atom,
2172 * memory must be allocated before.
2173 * @param max_len maximum char length of the string, i.e. how much memory has
2174 * been reserved for type. This includes \0 terminating character.
2175 * @pre \code atom != 0 \endcode The atom must not be NULL.
2176 * @pre \code type != 0 \endcode The pointer to the type string
2177 * must not be a NULL pointer.
2178 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2179 * has occurred (source string longer than destination string).
2181 tng_function_status DECLSPECDLLEXPORT tng_atom_type_get
2182 (const tng_trajectory_t tng_data,
2183 const tng_atom_t atom,
2188 * @brief Set the atom type of an atom.
2189 * @param tng_data is the trajectory data container containing the atom.
2190 * @param atom is the atom to change.
2191 * @param new_type is a string containing the atom type.
2192 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2193 * must be initialised before using it.
2194 * @pre \code new_type != 0 \endcode The pointer to the atom type string
2195 * must not be a NULL pointer.
2196 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2197 * error has occured.
2199 tng_function_status DECLSPECDLLEXPORT tng_atom_type_set
2200 (tng_trajectory_t tng_data,
2202 const char *new_type);
2205 * @brief Get the molecule name of real particle number (number in mol system).
2206 * @param tng_data is the trajectory data container containing the atom.
2207 * @param nr is the real number of the particle in the molecular system.
2208 * @param name is a string, which is set to the name of the molecule. Memory
2209 * must be reserved beforehand.
2210 * @param max_len is the maximum length of name.
2211 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2212 * must be initialised before using it.
2213 * @pre \code name != 0 \endcode The pointer to the name string
2214 * must not be a NULL pointer.
2215 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2218 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_of_particle_nr_get
2219 (const tng_trajectory_t tng_data,
2225 * @brief Get the molecule id of real particle number (number in mol system).
2226 * @param tng_data is the trajectory data container containing the atom.
2227 * @param nr is the real number of the particle in the molecular system.
2228 * @param id is will be set to the id of the molecule.
2229 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2230 * must be initialised before using it.
2231 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer.
2232 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2235 tng_function_status DECLSPECDLLEXPORT tng_molecule_id_of_particle_nr_get
2236 (const tng_trajectory_t tng_data,
2241 * @brief Get the bonds of the current molecular system.
2242 * @param tng_data is the trajectory data container containing the molecular
2244 * @param n_bonds is set to the number of bonds in the molecular system and
2245 * thereby also the lengths of the two lists: from_atoms and to_atoms.
2246 * @param from_atoms is a list (memory reserved by this function) of atoms
2247 * (number of atom in mol system) in bonds.
2248 * @param to_atoms is a list (memory reserved by this function) of atoms
2249 * (number of atom in mol system) in bonds.
2250 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2251 * must be initialised before using it.
2252 * @pre \code n_bonds != 0 \endcode The pointer to n_bonds must not be a
2254 * @pre \code from_atoms != 0 \endcode The pointer to from_atoms must not
2255 * be a NULL pointer.
2256 * @pre \code to_atoms != 0 \endcode The pointer to to_atoms must not
2257 * be a NULL pointer.
2258 * @details The two lists of atoms use the same index, i.e. from_atoms[0]
2259 * and to_atoms[0] are linked with a bond. Since memory is reserved in
2260 * this function it must be freed afterwards.
2261 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2262 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2264 tng_function_status DECLSPECDLLEXPORT tng_molsystem_bonds_get
2265 (const tng_trajectory_t tng_data,
2267 int64_t **from_atoms,
2268 int64_t **to_atoms);
2271 * @brief Get the chain name of real particle number (number in mol system).
2272 * @param tng_data is the trajectory data container containing the atom.
2273 * @param nr is the real number of the particle in the molecular system.
2274 * @param name is a string, which is set to the name of the chain. Memory
2275 * must be reserved beforehand.
2276 * @param max_len is the maximum length of name.
2277 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2278 * must be initialised before using it.
2279 * @pre \code name != 0 \endcode The pointer to the name string
2280 * must not be a NULL pointer.
2281 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2284 tng_function_status DECLSPECDLLEXPORT tng_chain_name_of_particle_nr_get
2285 (const tng_trajectory_t tng_data,
2291 * @brief Get the residue name of real particle number (number in mol system).
2292 * @param tng_data is the trajectory data container containing the atom.
2293 * @param nr is the real number of the particle in the molecular system.
2294 * @param name is a string, which is set to the name of the residue. Memory
2295 * must be reserved beforehand.
2296 * @param max_len is the maximum length of name.
2297 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2298 * must be initialised before using it.
2299 * @pre \code name != 0 \endcode The pointer to the name string
2300 * must not be a NULL pointer.
2301 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2304 tng_function_status DECLSPECDLLEXPORT tng_residue_name_of_particle_nr_get
2305 (const tng_trajectory_t tng_data,
2311 * @brief Get the residue id (local to molecule) of real particle number
2312 * (number in mol system).
2313 * @param tng_data is the trajectory data container containing the atom.
2314 * @param nr is the real number of the particle in the molecular system.
2315 * @param id is a pointer to the variable, which will be set to the ID.
2316 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2317 * must be initialised before using it.
2318 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer.
2319 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2322 tng_function_status DECLSPECDLLEXPORT tng_residue_id_of_particle_nr_get
2323 (const tng_trajectory_t tng_data,
2328 * @brief Get the residue id (based on other molecules and molecule counts)
2329 * of real particle number (number in mol system).
2330 * @param tng_data is the trajectory data container containing the atom.
2331 * @param nr is the real number of the particle in the molecular system.
2332 * @param id is a pointer to the variable, which will be set to the ID.
2333 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2334 * must be initialised before using it.
2335 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer.
2336 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2339 tng_function_status DECLSPECDLLEXPORT tng_global_residue_id_of_particle_nr_get
2340 (const tng_trajectory_t tng_data,
2345 * @brief Get the atom name of real particle number (number in mol system).
2346 * @param tng_data is the trajectory data container containing the atom.
2347 * @param nr is the real number of the particle in the molecular system.
2348 * @param name is a string, which is set to the name of the atom. Memory
2349 * must be reserved beforehand.
2350 * @param max_len is the maximum length of name.
2351 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2352 * must be initialised before using it.
2353 * @pre \code name != 0 \endcode The pointer to the name string
2354 * must not be a NULL pointer.
2355 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2358 tng_function_status DECLSPECDLLEXPORT tng_atom_name_of_particle_nr_get
2359 (const tng_trajectory_t tng_data,
2365 * @brief Get the atom type of real particle number (number in mol system).
2366 * @param tng_data is the trajectory data container containing the atom.
2367 * @param nr is the real number of the particle in the molecular system.
2368 * @param type is a string, which is set to the type of the atom. Memory
2369 * must be reserved beforehand.
2370 * @param max_len is the maximum length of type.
2371 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2372 * must be initialised before using it.
2373 * @pre \code type != 0 \endcode The pointer to the type string
2374 * must not be a NULL pointer.
2375 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
2378 tng_function_status DECLSPECDLLEXPORT tng_atom_type_of_particle_nr_get
2379 (const tng_trajectory_t tng_data,
2385 * @brief Add a particle mapping table.
2386 * @details Each particle mapping table will be written as a separate block,
2387 * followed by the data blocks for the corresponding particles. In most cases
2388 * there is one particle mapping block for each thread writing the trajectory.
2389 * @param tng_data is the trajectory, with the frame set to which to add
2390 * the mapping block.
2391 * @details The mapping information is added to the currently active frame set
2393 * @param num_first_particle is the first particle number of this mapping
2395 * @param n_particles is the number of particles in this mapping block.
2396 * @param mapping_table is a list of the real particle numbers (i.e. the numbers
2397 * used in the molecular system). The list is n_particles long.
2398 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2399 * must be initialised before using it.
2400 * @details mapping_table[0] is the real particle number of the first particle
2401 * in the following data blocks.
2402 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2403 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2405 tng_function_status DECLSPECDLLEXPORT tng_particle_mapping_add
2406 (tng_trajectory_t tng_data,
2407 const int64_t num_first_particle,
2408 const int64_t n_particles,
2409 const int64_t *mapping_table);
2412 * @brief Remove all particle mappings (in memory) from the current frame set.
2413 * @details Clears the currently setup particle mappings of the current frame
2415 * @param tng_data is the trajectory, with the frame set of which to clear
2416 * all particle mappings.
2417 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2418 * must be initialised before using it.
2419 * @return TNG_SUCCESS (0) if successful.
2421 tng_function_status DECLSPECDLLEXPORT tng_frame_set_particle_mapping_free
2422 (tng_trajectory_t tng_data);
2425 * @brief Read the header blocks from the input_file of tng_data.
2426 * @details The trajectory blocks must be read separately and iteratively in chunks
2428 * @param tng_data is a trajectory data container.
2429 * @details tng_data->input_file_path specifies
2430 * which file to read from. If the file (input_file) is not open it will be
2432 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2433 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2434 * compared to the md5 hash of the read contents to ensure valid data.
2435 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2436 * must be initialised before using it.
2437 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2438 * error has occured.
2440 tng_function_status DECLSPECDLLEXPORT tng_file_headers_read
2441 (tng_trajectory_t tng_data,
2442 const char hash_mode);
2445 * @brief Write the header blocks to the output_file of tng_data.
2446 * @details The trajectory blocks must be written separately and iteratively in chunks
2448 * @param tng_data is a trajectory data container.
2449 * @details tng_data->output_file_path
2450 * specifies which file to write to. If the file (output_file) is not open it
2452 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2453 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
2454 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2455 * must be initialised before using it.
2456 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
2457 * error has occured.
2459 tng_function_status DECLSPECDLLEXPORT tng_file_headers_write
2460 (tng_trajectory_t tng_data,
2461 const char hash_mode);
2464 * @brief Read one (the next) block (of any kind) 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 block_data is a pointer to the struct which will be populated with the
2471 * @details If block_data->input_file_pos > 0 it is the position from where the
2472 * reading starts otherwise it starts from the current position.
2473 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2474 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2475 * compared to the md5 hash of the read contents to ensure valid data.
2476 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2477 * must be initialised before using it.
2478 * @pre \code block != 0 \endcode The block container (block) must be
2479 * initialised before using it.
2480 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2481 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2483 tng_function_status DECLSPECDLLEXPORT tng_block_read_next
2484 (tng_trajectory_t tng_data,
2485 tng_gen_block_t block_data,
2486 const char hash_mode);
2489 * @brief Read one frame set, including all particle mapping blocks and data
2490 * blocks, starting from the current file position.
2491 * @param tng_data is a trajectory data container.
2492 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2493 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2494 * compared to the md5 hash of the read contents to ensure valid data.
2495 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2496 * must be initialised before using it.
2497 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2498 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2500 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read
2501 (tng_trajectory_t tng_data,
2502 const char hash_mode);
2505 * @brief Read data from the current frame set from the input_file. Only read
2506 * particle mapping and data blocks matching the specified block_id.
2507 * @param tng_data is a trajectory data container.
2508 * @details tng_data->input_file_path specifies
2509 * which file to read from. If the file (input_file) is not open it will be
2511 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2512 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2513 * compared to the md5 hash of the read contents to ensure valid data.
2514 * @param block_id is the ID of the data block to read from file.
2515 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2516 * must be initialised before using it.
2517 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2518 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2520 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_current_only_data_from_block_id
2521 (tng_trajectory_t tng_data,
2522 const char hash_mode,
2523 const int64_t block_id);
2526 * @brief Read one (the next) frame set, including particle mapping and related data blocks
2527 * from the input_file of tng_data.
2528 * @param tng_data is a trajectory data container.
2529 * @details tng_data->input_file_path specifies
2530 * which file to read from. If the file (input_file) is not open it will be
2532 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2533 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2534 * compared to the md5 hash of the read contents to ensure valid data.
2535 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2536 * must be initialised before using it.
2537 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2538 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2540 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next
2541 (tng_trajectory_t tng_data,
2542 const char hash_mode);
2545 * @brief Read one (the next) frame set, including particle mapping and data blocks with a
2546 * specific block id from the input_file of tng_data.
2547 * @param tng_data is a trajectory data container.
2548 * @details tng_data->input_file_path specifies
2549 * which file to read from. If the file (input_file) is not open it will be
2551 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2552 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2553 * compared to the md5 hash of the read contents to ensure valid data.
2554 * @param block_id is the ID number of the blocks that should be read from file.
2555 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2556 * must be initialised before using it.
2557 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2558 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2560 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next_only_data_from_block_id
2561 (tng_trajectory_t tng_data,
2562 const char hash_mode,
2563 const int64_t block_id);
2566 * @brief Write one frame set, including mapping and related data blocks
2567 * to the output_file of tng_data.
2568 * @param tng_data is a trajectory data container.
2569 * @details tng_data->output_file_path specifies
2570 * which file to write to. If the file (output_file) is not open it will be
2572 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2573 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
2574 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2575 * must be initialised before using it.
2576 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2577 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2579 tng_function_status DECLSPECDLLEXPORT tng_frame_set_write
2580 (tng_trajectory_t tng_data,
2581 const char hash_mode);
2584 * @brief Write one frame set even if it does not have as many frames as
2585 * expected. The function also writes mapping and related data blocks
2586 * to the output_file of tng_data.
2587 * @param tng_data is a trajectory data container.
2588 * @details tng_data->output_file_path specifies
2589 * which file to write to. If the file (output_file) is not open it will be
2591 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2592 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
2593 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2594 * must be initialised before using it.
2595 * @details The number of frames in the frame set is set to the number of
2596 * frames of the data blocks before writing it to disk.
2597 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2598 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2600 tng_function_status DECLSPECDLLEXPORT tng_frame_set_premature_write
2601 (tng_trajectory_t tng_data,
2602 const char hash_mode);
2605 * @brief Create and initialise a frame set.
2606 * @details Particle mappings are retained from previous frame set (if any).
2607 * To explicitly clear particle mappings use tng_frame_set_particle_mapping_free().
2608 * @param tng_data is the trajectory data container in which to add the frame
2610 * @param first_frame is the first frame of the frame set.
2611 * @param n_frames is the number of frames in the frame set.
2612 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2613 * must be initialised before using it.
2614 * @pre \code first_frame >= 0 \endcode The first frame must not be negative.
2615 * @pre \code n_frames >= 0 \endcode The number of frames must not be negative.
2616 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2617 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2619 tng_function_status DECLSPECDLLEXPORT tng_frame_set_new
2620 (tng_trajectory_t tng_data,
2621 const int64_t first_frame,
2622 const int64_t n_frames);
2625 * @brief Create and initialise a frame set with the time of the first frame
2627 * @param tng_data is the trajectory data container in which to add the frame
2629 * @param first_frame is the first frame of the frame set.
2630 * @param n_frames is the number of frames in the frame set.
2631 * @param first_frame_time is the time stamp of the first frame (in seconds).
2632 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2633 * must be initialised before using it.
2634 * @pre \code first_frame >= 0 \endcode The first frame must not be negative.
2635 * @pre \code n_frames >= 0 \endcode The number of frames must not be negative.
2636 * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame
2637 * must not be negative.
2638 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2639 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2641 tng_function_status DECLSPECDLLEXPORT tng_frame_set_with_time_new
2642 (tng_trajectory_t tng_data,
2643 const int64_t first_frame,
2644 const int64_t n_frames,
2645 const double first_frame_time);
2648 * @brief Set the time stamp of the first frame of the current frame set.
2649 * @param tng_data is the trajectory containing the frame set.
2650 * @param first_frame_time is the time stamp of the first frame in the
2652 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2653 * must be initialised before using it.
2654 * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame
2655 * must not be negative.
2656 * @return TNG_SUCCESS (0) if successful.
2658 tng_function_status DECLSPECDLLEXPORT tng_frame_set_first_frame_time_set
2659 (tng_trajectory_t tng_data,
2660 const double first_frame_time);
2663 * @brief Read the number of the first frame of the next frame set.
2664 * @param tng_data is the trajectory containing the frame set.
2665 * @param frame is set to the frame number of the first frame in the
2667 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2668 * must be initialised before using it.
2669 * @pre \code tng_data->input_file != 0 \endcode An input file must be open
2670 * to find the next frame set.
2671 * @pre \code frame != 0 \endcode The pointer to the frame must not be a NULL
2673 * @return TNG_SUCCESS(0) if successful, TNG_FAILURE(1) if there is no next
2674 * frame set or TNG_CRITICAL(2) if a major error has occured.
2676 tng_function_status DECLSPECDLLEXPORT tng_first_frame_nr_of_next_frame_set_get
2677 (const tng_trajectory_t tng_data,
2681 * @brief Add a non-particle dependent data block.
2682 * @param tng_data is the trajectory data container in which to add the data
2684 * @param id is the block ID of the block to add.
2685 * @param block_name is a descriptive name of the block to add
2686 * @param datatype is the datatype of the data in the block (e.g. int/float)
2687 * @param block_type_flag indicates if this is a non-trajectory block (added
2688 * directly to tng_data) or if it is a trajectory block (added to the
2690 * @param n_frames is the number of frames of the data block (automatically
2691 * set to 1 if adding a non-trajectory data block)
2692 * @param n_values_per_frame is how many values a stored each frame (e.g. 9
2693 * for a box shape block)
2694 * @param stride_length is how many frames are between each entry in the
2696 * @param codec_id is the ID of the codec to compress the data.
2697 * @param new_data is an array of data values to add.
2698 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2699 * must be initialised before using it.
2700 * @pre \code block_name != 0 \endcode The pointer to the block name must
2701 * not be a NULL pointer.
2702 * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be
2703 * a positive integer.
2704 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2705 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2707 tng_function_status DECLSPECDLLEXPORT tng_data_block_add
2708 (tng_trajectory_t tng_data,
2710 const char *block_name,
2711 const char datatype,
2712 const char block_type_flag,
2714 const int64_t n_values_per_frame,
2715 int64_t stride_length,
2716 const int64_t codec_id,
2720 * @brief Add a particle dependent data block.
2721 * @param tng_data is the trajectory data container in which to add the data
2723 * @param id is the block ID of the block to add.
2724 * @param block_name is a descriptive name of the block to add
2725 * @param datatype is the datatype of the data in the block (e.g. int/float)
2726 * @param block_type_flag indicates if this is a non-trajectory block (added
2727 * directly to tng_data) or if it is a trajectory block (added to the
2729 * @param n_frames is the number of frames of the data block (automatically
2730 * set to 1 if adding a non-trajectory data block)
2731 * @param n_values_per_frame is how many values a stored each frame (e.g. 9
2732 * for a box shape block)
2733 * @param stride_length is how many frames are between each entry in the
2735 * @param num_first_particle is the number of the first particle stored
2736 * in this data block
2737 * @param n_particles is the number of particles stored in this data block
2738 * @param codec_id is the ID of the codec to compress the data.
2739 * @param new_data is an array of data values to add.
2740 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2741 * must be initialised before using it.
2742 * @pre \code block_name != 0 \endcode The pointer to the block name must
2743 * not be a NULL pointer.
2744 * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be
2745 * a positive integer.
2746 * @pre \code num_first_particle >= 0 \endcode The number of the
2747 * first particle must be >= 0.
2748 * @pre \code n_particles >= 0 \endcode n_particles must be >= 0.
2749 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2750 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2752 tng_function_status DECLSPECDLLEXPORT tng_particle_data_block_add
2753 (tng_trajectory_t tng_data,
2755 const char *block_name,
2756 const char datatype,
2757 const char block_type_flag,
2759 const int64_t n_values_per_frame,
2760 int64_t stride_length,
2761 const int64_t num_first_particle,
2762 const int64_t n_particles,
2763 const int64_t codec_id,
2766 /** @brief Get the name of a data block of a specific ID.
2767 * @param tng_data is the trajectory data container.
2768 * @param block_id is the ID of the data block of which to get the name.
2769 * @param name is a string, which is set to the name of the data block.
2770 * Memory must be reserved beforehand.
2771 * @param max_len is the maximum length of name.
2772 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2773 * must be initialised before using it.
2774 * @pre \code name != 0 \endcode The pointer to the name string
2775 * must not be a NULL pointer.
2776 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1)
2777 * if a minor error has occured or the data block is not found or
2778 * TNG_CRITICAL (2) if a major error has occured.
2780 tng_function_status DECLSPECDLLEXPORT tng_data_block_name_get
2781 (tng_trajectory_t tng_data,
2786 /** @brief Get the dependency of a data block of a specific ID.
2787 * @param tng_data is the trajectory data container.
2788 * @param block_id is the ID of the data block of which to get the name.
2789 * @param block_dependency is a pointer to the dependency of the data block.
2790 * If the block is frame dependent it will be set to TNG_FRAME_DEPENDENT,
2791 * if it is particle dependent it will be set to TNG_PARTICLE_DEPENDENT and
2792 * if it is both it will be set to TNG_FRAME_DEPENDENT & TNG_PARTICLE_DEPENDENT.
2793 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2794 * must be initialised before using it.
2795 * @pre \code block_dependency != 0 \endcode The pointer to the block dependency
2796 * must not be a NULL pointer.
2797 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1)
2798 * if a minor error has occured or the data block is not found or
2799 * TNG_CRITICAL (2) if a major error has occured.
2801 tng_function_status DECLSPECDLLEXPORT tng_data_block_dependency_get
2802 (const tng_trajectory_t tng_data,
2804 int *block_dependency);
2806 /** @brief Get the number of values per frame of a data block of a specific ID.
2807 * @param tng_data is the trajectory data container.
2808 * @param block_id is the ID of the data block of which to get the name.
2809 * @param n_values_per_frame is a pointer set to the number of values per frame.
2810 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2811 * must be initialised before using it.
2812 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of values
2813 * per frame must not be a NULL pointer.
2814 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1)
2815 * if a minor error has occured or the data block is not found or
2816 * TNG_CRITICAL (2) if a major error has occured.
2818 tng_function_status DECLSPECDLLEXPORT tng_data_block_num_values_per_frame_get
2819 (const tng_trajectory_t tng_data,
2821 int64_t *n_values_per_frame);
2824 * @brief Write data of one trajectory frame to the output_file of tng_data.
2825 * @param tng_data is a trajectory data container. tng_data->output_file_path
2826 * specifies which file to write to. If the file (output_file) is not open it
2828 * @param frame_nr is the index number of the frame to write.
2829 * @param block_id is the ID of the data block to write the data to.
2830 * @param values is an array of data to write. The length of the array should
2831 * equal n_values_per_frame.
2832 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2833 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2834 * compared to the md5 hash of the read contents to ensure valid data.
2835 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2836 * must be initialised before using it.
2837 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
2838 * @pre \code values != 0 \endcode The pointer to the values must not be a NULL
2840 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2841 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2843 tng_function_status DECLSPECDLLEXPORT tng_frame_data_write
2844 (tng_trajectory_t tng_data,
2845 const int64_t frame_nr,
2846 const int64_t block_id,
2848 const char hash_mode);
2851 * @brief Write particle data of one trajectory frame to the output_file of
2853 * @param tng_data is a trajectory data container. tng_data->output_file_path
2854 * specifies which file to write to. If the file (output_file) is not open it
2856 * @param frame_nr is the index number of the frame to write.
2857 * @param block_id is the ID of the data block to write the data to.
2858 * @param val_first_particle is the number of the first particle in the data
2860 * @param val_n_particles is the number of particles in the data array.
2861 * @param values is a 1D-array of data to write. The length of the array should
2862 * equal n_particles * n_values_per_frame.
2863 * @param hash_mode is an option to decide whether to use the md5 hash or not.
2864 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
2865 * compared to the md5 hash of the read contents to ensure valid data.
2866 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2867 * must be initialised before using it.
2868 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
2869 * @pre \code val_first_particle >= 0 \endcode The number of the
2870 * first particle must be >= 0.
2871 * @pre \code val_n_particles >= 0 \endcode The number of particles must be >= 0.
2872 * @pre \code values != 0 \endcode The pointer to the values must not be a NULL
2874 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2875 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2877 tng_function_status DECLSPECDLLEXPORT tng_frame_particle_data_write
2878 (tng_trajectory_t tng_data,
2879 const int64_t frame_nr,
2880 const int64_t block_id,
2881 const int64_t val_first_particle,
2882 const int64_t val_n_particles,
2884 const char hash_mode);
2887 * @brief Free data of an array of values (2D).
2888 * @param tng_data is a trajectory data container.
2889 * @param values is the 2D array to free and will be set to 0 afterwards.
2890 * @param n_frames is the number of frames in the data array.
2891 * @param n_values_per_frame is the number of values per frame in the data array.
2892 * @param type is the data type of the data in the array (e.g. int/float/char).
2893 * @return TNG_SUCCESS (0) if successful.
2895 tng_function_status DECLSPECDLLEXPORT tng_data_values_free
2896 (const tng_trajectory_t tng_data,
2897 union data_values **values,
2898 const int64_t n_frames,
2899 const int64_t n_values_per_frame,
2903 * @brief Free data of an array of values (3D).
2904 * @param tng_data is a trajectory data container.
2905 * @param values is the array to free and will be set to 0 afterwards.
2906 * @param n_frames is the number of frames in the data array.
2907 * @param n_particles is the number of particles in the data array.
2908 * @param n_values_per_frame is the number of values per frame in the data array.
2909 * @param type is the data type of the data in the array (e.g. int/float/char).
2910 * @return TNG_SUCCESS (0) if successful.
2912 tng_function_status DECLSPECDLLEXPORT tng_particle_data_values_free
2913 (const tng_trajectory_t tng_data,
2914 union data_values ***values,
2915 const int64_t n_frames,
2916 const int64_t n_particles,
2917 const int64_t n_values_per_frame,
2921 * @brief Retrieve non-particle data, from the last read frame set. Obsolete!
2922 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
2923 * which file to read from. If the file (input_file) is not open it will be
2925 * @param block_id is the id number of the particle data block to read.
2926 * @param values is a pointer to a 2-dimensional array (memory unallocated), which
2927 * will be filled with data. The array will be sized
2928 * (n_frames * n_values_per_frame).
2929 * Since ***values is allocated in this function it is the callers
2930 * responsibility to free the memory.
2931 * @param n_frames is set to the number of frames in the returned data. This is
2932 * needed to properly reach and/or free the data afterwards.
2933 * @param n_values_per_frame is set to the number of values per frame in the data.
2934 * This is needed to properly reach and/or free the data afterwards.
2935 * @param type is set to the data type of the data in the array.
2936 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2937 * must be initialised before using it.
2938 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
2939 * must not be a NULL pointer.
2940 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
2941 * values per frame must not be a NULL pointer.
2942 * @pre \code type != 0 \endcode The pointer to the data type must not
2943 * be a NULL pointer.
2944 * @details This function is obsolete and only retained for compatibility. Use
2945 * tng_data_vector_get() instead.
2946 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2947 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2949 tng_function_status DECLSPECDLLEXPORT tng_data_get(tng_trajectory_t tng_data,
2950 const int64_t block_id,
2951 union data_values ***values,
2953 int64_t *n_values_per_frame,
2957 * @brief Retrieve a vector (1D array) of non-particle data, from the last read frame set.
2958 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
2959 * which file to read from. If the file (input_file) is not open it will be
2961 * @param block_id is the id number of the particle data block to read.
2962 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
2963 * will be filled with data. The length of the array will be (n_frames * n_values_per_frame).
2964 * Since **values is allocated in this function it is the callers
2965 * responsibility to free the memory.
2966 * @param n_frames is set to the number of particles in the returned data. This is
2967 * needed to properly reach and/or free the data afterwards.
2968 * @param stride_length is set to the stride length of the returned data.
2969 * @param n_values_per_frame is set to the number of values per frame in the data.
2970 * This is needed to properly reach and/or free the data afterwards.
2971 * @param type is set to the data type of the data in the array.
2972 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
2973 * must be initialised before using it.
2974 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
2975 * must not be a NULL pointer.
2976 * @pre \code stride_length != 0 \endcode The pointer to the stride length
2977 * must not be a NULL pointer.
2978 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
2979 * values per frame must not be a NULL pointer.
2980 * @pre \code type != 0 \endcode The pointer to the data type must not
2981 * be a NULL pointer.
2982 * @details This does only work for numerical (int, float, double) data.
2983 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
2984 * has occurred or TNG_CRITICAL (2) if a major error has occured.
2986 tng_function_status DECLSPECDLLEXPORT tng_data_vector_get
2987 (tng_trajectory_t tng_data,
2988 const int64_t block_id,
2991 int64_t *stride_length,
2992 int64_t *n_values_per_frame,
2996 * @brief Read and retrieve non-particle data, in a specific interval. Obsolete!
2997 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
2998 * which file to read from. If the file (input_file) is not open it will be
3000 * @param block_id is the id number of the particle data block to read.
3001 * @param start_frame_nr is the index number of the first frame to read.
3002 * @param end_frame_nr is the index number of the last frame to read.
3003 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3004 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3005 * compared to the md5 hash of the read contents to ensure valid data.
3006 * @param values is a pointer to a 2-dimensional array (memory unallocated), which
3007 * will be filled with data. The array will be sized
3008 * (n_frames * n_values_per_frame).
3009 * Since ***values is allocated in this function it is the callers
3010 * responsibility to free the memory.
3011 * @param n_values_per_frame is set to the number of values per frame in the data.
3012 * This is needed to properly reach and/or free the data afterwards.
3013 * @param type is set to the data type of the data in the array.
3014 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3015 * must be initialised before using it.
3016 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3018 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3019 * values per frame must not be a NULL pointer.
3020 * @pre \code type != 0 \endcode The pointer to the data type must not
3021 * be a NULL pointer.
3022 * @details This function is obsolete and only retained for compatibility. Use
3023 * tng_data_vector_interval_get() instead.
3024 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3025 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3027 tng_function_status DECLSPECDLLEXPORT tng_data_interval_get
3028 (tng_trajectory_t tng_data,
3029 const int64_t block_id,
3030 const int64_t start_frame_nr,
3031 const int64_t end_frame_nr,
3032 const char hash_mode,
3033 union data_values ***values,
3034 int64_t *n_values_per_frame,
3038 * @brief Read and retrieve a vector (1D array) of non-particle data,
3039 * in a specific interval.
3040 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
3041 * which file to read from. If the file (input_file) is not open it will be
3043 * @param block_id is the id number of the particle data block to read.
3044 * @param start_frame_nr is the index number of the first frame to read.
3045 * @param end_frame_nr is the index number of the last frame to read.
3046 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3047 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3048 * compared to the md5 hash of the read contents to ensure valid data.
3049 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
3050 * will be filled with data. The length of the array will be (n_frames * n_values_per_frame).
3051 * Since **values is allocated in this function it is the callers
3052 * responsibility to free the memory.
3053 * @param stride_length is set to the stride length (writing interval) of
3055 * @param n_values_per_frame is set to the number of values per frame in the data.
3056 * This is needed to properly reach and/or free the data afterwards.
3057 * @param type is set to the data type of the data in the array.
3058 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3059 * must be initialised before using it.
3060 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3062 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3063 * must not be a NULL pointer.
3064 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3065 * values per frame must not be a NULL pointer.
3066 * @pre \code type != 0 \endcode The pointer to the data type must not
3067 * be a NULL pointer.
3068 * @details This does only work for numerical (int, float, double) data.
3069 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3070 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3072 tng_function_status DECLSPECDLLEXPORT tng_data_vector_interval_get
3073 (tng_trajectory_t tng_data,
3074 const int64_t block_id,
3075 const int64_t start_frame_nr,
3076 const int64_t end_frame_nr,
3077 const char hash_mode,
3079 int64_t *stride_length,
3080 int64_t *n_values_per_frame,
3084 * @brief Retrieve particle data, from the last read frame set. Obsolete!
3085 * @details The particle dimension of the returned values array is translated
3086 * to real particle numbering, i.e. the numbering of the actual molecular
3088 * @param tng_data is a trajectory data container. tng_data->input_file_path
3089 * specifies which file to read from. If the file (input_file) is not open it
3091 * @param block_id is the id number of the particle data block to read.
3092 * @param values is a pointer to a 3-dimensional array (memory unallocated), which
3093 * will be filled with data. The array will be sized
3094 * (n_frames * n_particles * n_values_per_frame).
3095 * Since ****values is allocated in this function it is the callers
3096 * responsibility to free the memory.
3097 * @param n_frames is set to the number of frames in the returned data. This is
3098 * needed to properly reach and/or free the data afterwards.
3099 * @param n_particles is set to the number of particles in the returned data. This is
3100 * needed to properly reach and/or free the data afterwards.
3101 * @param n_values_per_frame is set to the number of values per frame in the data.
3102 * This is needed to properly reach and/or free the data afterwards.
3103 * @param type is set to the data type of the data in the array.
3104 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3105 * must be initialised before using it.
3106 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
3107 * must not be a NULL pointer.
3108 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3109 * not be a NULL pointer.
3110 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3111 * values per frame must not be a NULL pointer.
3112 * @pre \code type != 0 \endcode The pointer to the data type must not
3113 * be a NULL pointer.
3114 * @details This function is obsolete and only retained for compatibility. Use
3115 * tng_particle_data_vector_get() instead.
3116 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3117 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3119 tng_function_status DECLSPECDLLEXPORT tng_particle_data_get
3120 (tng_trajectory_t tng_data,
3121 const int64_t block_id,
3122 union data_values ****values,
3124 int64_t *n_particles,
3125 int64_t *n_values_per_frame,
3129 * @brief Retrieve a vector (1D array) of particle data, from the last read frame set.
3130 * @details The particle dimension of the returned values array is translated
3131 * to real particle numbering, i.e. the numbering of the actual molecular
3133 * @param tng_data is a trajectory data container. tng_data->input_file_path
3134 * specifies which file to read from. If the file (input_file) is not open it
3136 * @param block_id is the id number of the particle data block to read.
3137 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
3138 * will be filled with data. The length of the array will be
3139 * (n_frames * n_particles * n_values_per_frame).
3140 * Since **values is allocated in this function it is the callers
3141 * responsibility to free the memory.
3142 * @param n_frames is set to the number of frames in the returned data. This is
3143 * needed to properly reach and/or free the data afterwards.
3144 * @param stride_length is set to the stride length of the returned data.
3145 * @param n_particles is set to the number of particles in the returned data. This is
3146 * needed to properly reach and/or free the data afterwards.
3147 * @param n_values_per_frame is set to the number of values per frame in the data.
3148 * This is needed to properly reach and/or free the data afterwards.
3149 * @param type is set to the data type of the data in the array.
3150 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3151 * must be initialised before using it.
3152 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3153 * not be a NULL pointer.
3154 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3155 * must not be a NULL pointer.
3156 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3157 * values per frame must not be a NULL pointer.
3158 * @pre \code type != 0 \endcode The pointer to the data type must not
3159 * be a NULL pointer.
3160 * @details This does only work for numerical (int, float, double) data.
3161 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3162 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3164 tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_get
3165 (tng_trajectory_t tng_data,
3166 const int64_t block_id,
3169 int64_t *stride_length,
3170 int64_t *n_particles,
3171 int64_t *n_values_per_frame,
3175 * @brief Read and retrieve particle data, in a specific interval. Obsolete!
3176 * @details The particle dimension of the returned values array is translated
3177 * to real particle numbering, i.e. the numbering of the actual molecular
3179 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
3180 * which file to read from. If the file (input_file) is not open it will be
3182 * @param block_id is the id number of the particle data block to read.
3183 * @param start_frame_nr is the index number of the first frame to read.
3184 * @param end_frame_nr is the index number of the last frame to read.
3185 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3186 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3187 * compared to the md5 hash of the read contents to ensure valid data.
3188 * @param values is a pointer to a 3-dimensional array (memory unallocated), which
3189 * will be filled with data. The array will be sized
3190 * (n_frames * n_particles * n_values_per_frame).
3191 * Since ****values is allocated in this function it is the callers
3192 * responsibility to free the memory.
3193 * @param n_particles is set to the number of particles in the returned data. This is
3194 * needed to properly reach and/or free the data afterwards.
3195 * @param n_values_per_frame is set to the number of values per frame in the data.
3196 * This is needed to properly reach and/or free the data afterwards.
3197 * @param type is set to the data type of the data in the array.
3198 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3199 * must be initialised before using it.
3200 * @pre \code n_frames != 0 \endcode The pointer to the number of frames
3201 * must not be a NULL pointer.
3202 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3204 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3205 * not be a NULL pointer.
3206 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3207 * values per frame must not be a NULL pointer.
3208 * @pre \code type != 0 \endcode The pointer to the data type must not
3209 * be a NULL pointer.
3210 * @details This function is obsolete and only retained for compatibility. Use
3211 * tng_particle_data_vector_interval_get() instead.
3212 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3213 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3215 tng_function_status DECLSPECDLLEXPORT tng_particle_data_interval_get
3216 (tng_trajectory_t tng_data,
3217 const int64_t block_id,
3218 const int64_t start_frame_nr,
3219 const int64_t end_frame_nr,
3220 const char hash_mode,
3221 union data_values ****values,
3222 int64_t *n_particles,
3223 int64_t *n_values_per_frame,
3227 * @brief Read and retrieve a vector (1D array) particle data, in a
3228 * specific interval.
3229 * @details The particle dimension of the returned values array is translated
3230 * to real particle numbering, i.e. the numbering of the actual molecular
3232 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies
3233 * which file to read from. If the file (input_file) is not open it will be
3235 * @param block_id is the id number of the particle data block to read.
3236 * @param start_frame_nr is the index number of the first frame to read.
3237 * @param end_frame_nr is the index number of the last frame to read.
3238 * @param hash_mode is an option to decide whether to use the md5 hash or not.
3239 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
3240 * compared to the md5 hash of the read contents to ensure valid data.
3241 * @param values is a pointer to a 1-dimensional array (memory unallocated), which
3242 * will be filled with data. The length of the array will be
3243 * (n_frames * n_particles * n_values_per_frame).
3244 * Since **values is allocated in this function it is the callers
3245 * responsibility to free the memory.
3246 * @param stride_length is set to the stride length (writing interval) of
3248 * @param n_particles is set to the number of particles in the returned data. This is
3249 * needed to properly reach and/or free the data afterwards.
3250 * @param n_values_per_frame is set to the number of values per frame in the data.
3251 * This is needed to properly reach and/or free the data afterwards.
3252 * @param type is set to the data type of the data in the array.
3253 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3254 * must be initialised before using it.
3255 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3257 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must
3258 * not be a NULL pointer.
3259 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3260 * must not be a NULL pointer.
3261 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of
3262 * values per frame must not be a NULL pointer.
3263 * @pre \code type != 0 \endcode The pointer to the data type must not
3264 * be a NULL pointer.
3265 * @details This does only work for numerical (int, float, double) data.
3266 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3267 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3269 tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_interval_get
3270 (tng_trajectory_t tng_data,
3271 const int64_t block_id,
3272 const int64_t start_frame_nr,
3273 const int64_t end_frame_nr,
3274 const char hash_mode,
3276 int64_t *n_particles,
3277 int64_t *stride_length,
3278 int64_t *n_values_per_frame,
3282 * @brief Get the stride length of a specific data (particle dependency does not matter)
3283 * block, either in the current frame set or of a specific frame.
3284 * @param tng_data is the trajectory data container.
3285 * @param block_id is the block ID of the data block, of which to retrieve the
3286 * stride length of the data.
3287 * @param frame is the frame from which to get the stride length. If frame is set to -1
3288 * no specific frame will be used, but instead the first frame, starting from the last read
3289 * frame set, containing the data block will be used.
3290 * @param stride_length is set to the value of the stride length of the data block.
3291 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3292 * has occurred or TNG_CRITICAL (2) if a major error has occured.
3294 tng_function_status DECLSPECDLLEXPORT tng_data_get_stride_length
3295 (const tng_trajectory_t tng_data,
3296 const int64_t block_id,
3298 int64_t *stride_length);
3301 * @brief Get the date and time of initial file creation in ISO format (string).
3302 * @param tng_data is a trajectory data container.
3303 * @param time is a pointer to the string in which the date will be stored. Memory
3304 * must be reserved beforehand.
3305 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3306 * must be initialised before using it.
3307 * @pre \code time != 0 \endcode The pointer to the time must not be a NULL
3309 * @return TNG_SUCCESS (0) if successful.
3311 tng_function_status DECLSPECDLLEXPORT tng_time_get_str
3312 (const tng_trajectory_t tng_data,
3314 /** @} */ /* end of group1 */
3316 /** @defgroup group2 High-level API
3317 * These functions make it easier to access and output TNG data. They
3318 * are recommended unless there is a special reason to use the more
3319 * detailed functions available in the low-level API.
3324 * @brief High-level function for opening and initializing a TNG trajectory.
3325 * @param filename is a string containing the name of the trajectory to open.
3326 * @param mode specifies the file mode of the trajectory. Can be set to 'r',
3327 * 'w' or 'a' for reading, writing or appending respectively.
3328 * @param tng_data_p is a pointer to the opened trajectory. This will be
3329 * allocated by the TNG library. The trajectory must be
3330 * closed by the user, whereby memory is freed.
3331 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3332 * must be initialised before using it.
3333 * @pre \code filename != 0 \endcode The pointer to the filename must not be a
3335 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3336 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3339 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_open
3340 (const char *filename,
3342 tng_trajectory_t *tng_data_p);
3345 * @brief High-level function for closing a TNG trajectory.
3346 * @param tng_data_p is a pointer to the trajectory to close. The memory
3347 * will be freed after finalising the writing.
3348 * @return TNG_SUCCESS (0) if successful.
3350 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_close
3351 (tng_trajectory_t *tng_data_p);
3354 * @brief High-level function for getting the time (in seconds) of a frame.
3355 * @param tng_data is the trajectory containing the frame.
3356 * @param frame_nr is the frame number of which to get the time.
3357 * @param time is set to the time (in seconds) of the specified frame.
3358 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3359 * must be initialised before using it.
3360 * @pre \code time != 0 \endcode The pointer to the time must not be a
3362 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if a
3363 * minor error has occured.
3365 tng_function_status DECLSPECDLLEXPORT tng_util_time_of_frame_get
3366 (tng_trajectory_t tng_data,
3367 const int64_t frame_nr,
3371 * @brief High-level function for getting the molecules in the mol system.
3372 * @param tng_data is the trajectory containing the mol system.
3373 * @param n_mols is set to the number of molecules in the system.
3374 * @param molecule_cnt_list will be pointing to the list of counts of each molecule
3375 * in the mol system.
3376 * @param mols pointing to the list of molecules in the mol system.
3377 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3378 * must be initialised before using it.
3379 * @pre \code n_mols != 0 \endcode The pointer to the number of molecules must
3380 * not be a NULL pointer.
3381 * @return TNG_SUCCESS (0) if successful.
3383 /*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecules_get
3384 (tng_trajectory_t tng_data,
3386 int64_t **molecule_cnt_list,
3387 tng_molecule_t *mols);
3390 * @brief High-level function for adding a molecule to the mol system.
3391 * @param tng_data is the trajectory containing the mol system.
3392 * @param name is the name of the molecule to add.
3393 * @param cnt is the count of the molecule.
3394 * @param mol is set to point to the newly created molecule.
3395 * @pre \code name != 0 \endcode The pointer to the name must not be a
3397 * @pre \code cnt >= 0 \endcode The requested count must be >= 0.
3398 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3399 * has occured or TNG_CRITICAL (2) if a major error has occured.
3401 /*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecule_add
3402 (tng_trajectory_t tng_data,
3405 tng_molecule_t *mol);
3408 // tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_get
3409 // (tng_trajectory_t tng_data,
3410 // const tng_molecule_t mol,
3411 // int64_t *n_particles,
3414 // char ***res_names,
3415 // int64_t **res_ids,
3416 // char ***chain_names,
3417 // int64_t **chain_ids);
3419 // tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_set
3420 // (tng_trajectory_t tng_data,
3421 // tng_molecule_t mol,
3422 // const int64_t n_particles,
3423 // const char **names,
3424 // const char **types,
3425 // const char **res_names,
3426 // const int64_t *res_ids,
3427 // const char **chain_names,
3428 // const int64_t *chain_ids);
3431 * @brief High-level function for reading the positions of all particles
3433 * @param tng_data is the trajectory to read from.
3434 * @param positions will be set to point at a 1-dimensional array of floats,
3435 * which will contain the positions. The data is stored sequentially in order
3436 * of frames. For each frame the positions (x, y and z coordinates) are stored.
3437 * The variable may point at already allocated memory or be a NULL pointer.
3438 * The memory must be freed afterwards.
3439 * @param stride_length will be set to the writing interval of the stored data.
3440 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3441 * must be initialised before using it.
3442 * @pre \code positions != 0 \endcode The pointer to the positions array
3443 * must not be a NULL pointer.
3444 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3445 * must not be a NULL pointer.
3446 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3447 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3450 tng_function_status DECLSPECDLLEXPORT tng_util_pos_read
3451 (tng_trajectory_t tng_data,
3453 int64_t *stride_length);
3456 * @brief High-level function for reading the velocities of all particles
3458 * @param tng_data is the trajectory to read from.
3459 * @param velocities will be set to point at a 1-dimensional array of floats,
3460 * which will contain the velocities. The data is stored sequentially in order
3461 * of frames. For each frame the velocities (in x, y and z) are stored. The
3462 * variable may point at already allocated memory or be a NULL pointer.
3463 * The memory must be freed afterwards.
3464 * @param stride_length will be set to the writing interval of the stored data.
3465 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3466 * must be initialised before using it.
3467 * @pre \code velocities != 0 \endcode The pointer to the velocities array
3468 * must not be a NULL pointer.
3469 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3470 * must not be a NULL pointer.
3471 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3472 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3475 tng_function_status DECLSPECDLLEXPORT tng_util_vel_read
3476 (tng_trajectory_t tng_data,
3478 int64_t *stride_length);
3481 * @brief High-level function for reading the forces of all particles
3483 * @param tng_data is the trajectory to read from.
3484 * @param forces will be set to point at a 1-dimensional array of floats,
3485 * which will contain the forces. The data is stored sequentially in order
3486 * of frames. For each frame the forces (in x, y and z) are stored. The
3487 * variable may point at already allocated memory or be a NULL pointer.
3488 * The memory must be freed afterwards.
3489 * @param stride_length will be set to the writing interval of the stored data.
3490 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3491 * must be initialised before using it.
3492 * @pre \code forces != 0 \endcode The pointer to the forces array
3493 * must not be a NULL pointer.
3494 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3495 * 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_force_read
3501 (tng_trajectory_t tng_data,
3503 int64_t *stride_length);
3506 * @brief High-level function for reading the box shape from all frames.
3507 * @param tng_data is the trajectory to read from.
3508 * @param box_shape will be set to point at a 1-dimensional array of floats,
3509 * which will contain the box shape. The data is stored sequentially in order
3510 * of frames. The variable may point at already allocated memory or be a NULL pointer.
3511 * If the box shape is not modified during the trajectory, but as general data,
3512 * that will be returned instead.
3513 * @param stride_length will be set to the writing interval of the stored data.
3514 * @details This function should only be used if number of values used to specify
3515 * the box shape is known (by default TNG uses 9 values) since it does not
3516 * return the number of values in the array. It is recommended to use
3517 * tng_data_vector_interval_get() instead.
3518 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3519 * must be initialised before using it.
3520 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array
3521 * must not be a NULL pointer.
3522 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3523 * must not be a NULL pointer.
3524 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3525 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3528 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read
3529 (tng_trajectory_t tng_data,
3531 int64_t *stride_length);
3534 * @brief High-level function for reading the next frame of particle-dependent
3535 * data of a specific type.
3536 * @param tng_data is the trajectory to read from.
3537 * @param block_id is the ID number of the block containing the data of interest.
3538 * @param values will be set to point at a 1-dimensional array containing the
3539 * requested data. The variable may point at already allocated memory or be a
3540 * NULL pointer. The memory must be freed afterwards.
3541 * @param data_type will be pointing to a character indicating the size of the
3542 * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA.
3543 * @param retrieved_frame_number will be pointing at the frame number of the
3545 * @param retrieved_time will be pointing at the time stamp of the returned
3547 * @details If no frame has been read before the first frame of the trajectory
3549 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3550 * must be initialised before using it.
3551 * @pre \code values != 0 \endcode The pointer to the values array
3552 * must not be a NULL pointer.
3553 * @pre \code data_type != 0 \endcode The pointer to the data type of the
3554 * returned data must not be a NULL pointer.
3555 * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame
3556 * number of the returned data must not be a NULL pointer.
3557 * @pre \code retrieved_time != 0 \endcode The pointer to the time of the
3558 * returned data must not be a NULL pointer.
3559 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3560 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3563 tng_function_status DECLSPECDLLEXPORT tng_util_particle_data_next_frame_read
3564 (tng_trajectory_t tng_data,
3565 const int64_t block_id,
3568 int64_t *retrieved_frame_number,
3569 double *retrieved_time);
3572 * @brief High-level function for reading the next frame of non-particle-dependent
3573 * data of a specific type.
3574 * @param tng_data is the trajectory to read from.
3575 * @param block_id is the ID number of the block containing the data of interest.
3576 * @param values will be set to point at a 1-dimensional array containing the
3577 * requested data. The variable may point at already allocated memory or be a
3578 * NULL pointer. The memory must be freed afterwards.
3579 * @param data_type will be pointing to a character indicating the size of the
3580 * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA.
3581 * @param retrieved_frame_number will be pointing at the frame number of the
3583 * @param retrieved_time will be pointing at the time stamp of the returned
3585 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3586 * must be initialised before using it.
3587 * @pre \code values != 0 \endcode The pointer to the values array
3588 * must not be a NULL pointer.
3589 * @pre \code data_type != 0 \endcode The pointer to the data type of the
3590 * returned data must not be a NULL pointer.
3591 * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame
3592 * number of the returned data must not be a NULL pointer.
3593 * @pre \code retrieved_time != 0 \endcode The pointer to the time of the
3594 * returned data 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_non_particle_data_next_frame_read
3600 (tng_trajectory_t tng_data,
3601 const int64_t block_id,
3604 int64_t *retrieved_frame_number,
3605 double *retrieved_time);
3608 * @brief High-level function for reading the positions of all particles
3609 * from a specific range of frames.
3610 * @param tng_data is the trajectory to read from.
3611 * @param first_frame is the first frame to return position data from.
3612 * @param last_frame is the last frame to return position data from.
3613 * @param positions will be set to point at a 1-dimensional array of floats,
3614 * which will contain the positions. The data is stored sequentially in order
3615 * of frames. For each frame the positions (x, y and z coordinates) are stored.
3616 * The variable may point at already allocated memory or be a NULL pointer.
3617 * The memory must be freed afterwards.
3618 * @param stride_length will be set to the writing interval of the stored data.
3619 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3620 * must be initialised before using it.
3621 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3623 * @pre \code positions != 0 \endcode The pointer to the positions array
3624 * must not be a NULL pointer.
3625 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3626 * must not be a NULL pointer.
3627 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3628 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3631 tng_function_status DECLSPECDLLEXPORT tng_util_pos_read_range
3632 (tng_trajectory_t tng_data,
3633 const int64_t first_frame,
3634 const int64_t last_frame,
3636 int64_t *stride_length);
3639 * @brief High-level function for reading the velocities of all particles
3640 * from a specific range of frames.
3641 * @param tng_data is the trajectory to read from.
3642 * @param first_frame is the first frame to return position data from.
3643 * @param last_frame is the last frame to return position data from.
3644 * @param velocities will be set to point at a 1-dimensional array of floats,
3645 * which will contain the velocities. The data is stored sequentially in order
3646 * of frames. For each frame the velocities (in x, y and z) are stored. The
3647 * variable may point at already allocated memory or be a NULL pointer.
3648 * The memory must be freed afterwards.
3649 * @param stride_length will be set to the writing interval of the stored data.
3650 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3651 * must be initialised before using it.
3652 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3654 * @pre \code velocities != 0 \endcode The pointer to the velocities array
3655 * must not be a NULL pointer.
3656 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3657 * must not be a NULL pointer.
3658 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3659 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3662 tng_function_status DECLSPECDLLEXPORT tng_util_vel_read_range
3663 (tng_trajectory_t tng_data,
3664 const int64_t first_frame,
3665 const int64_t last_frame,
3667 int64_t *stride_length);
3670 * @brief High-level function for reading the forces of all particles
3671 * from a specific range of frames.
3672 * @param tng_data is the trajectory to read from.
3673 * @param first_frame is the first frame to return position data from.
3674 * @param last_frame is the last frame to return position data from.
3675 * @param forces will be set to point at a 1-dimensional array of floats,
3676 * which will contain the forces. The data is stored sequentially in order
3677 * of frames. For each frame the forces (in x, y and z) are stored. The
3678 * variable may point at already allocated memory or be a NULL pointer.
3679 * The memory must be freed afterwards.
3680 * @param stride_length will be set to the writing interval of the stored data.
3681 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3682 * must be initialised before using it.
3683 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3685 * @pre \code forces != 0 \endcode The pointer to the forces array
3686 * must not be a NULL pointer.
3687 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3688 * must not be a NULL pointer.
3689 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3690 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3693 tng_function_status DECLSPECDLLEXPORT tng_util_force_read_range
3694 (tng_trajectory_t tng_data,
3695 const int64_t first_frame,
3696 const int64_t last_frame,
3698 int64_t *stride_length);
3701 * @brief High-level function for reading the box shape
3702 * from a specific range of frames.
3703 * @param tng_data is the trajectory to read from.
3704 * @param first_frame is the first frame to return position data from.
3705 * @param last_frame is the last frame to return position data from.
3706 * @param box_shape will be set to point at a 1-dimensional array of floats,
3707 * which will contain the box shape. The data is stored sequentially in order
3709 * If the box shape is not modified during the trajectory, but as general data,
3710 * that will be returned instead. The
3711 * variable may point at already allocated memory or be a NULL pointer.
3712 * The memory must be freed afterwards.
3713 * @param stride_length will be set to the writing interval of the stored data.
3714 * @details This function should only be used if number of values used to specify
3715 * the box shape is known (by default TNG uses 9 values) since it does not
3716 * return the number of values in the array. It is recommended to use
3717 * tng_data_vector_interval_get() instead.
3718 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3719 * must be initialised before using it.
3720 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before
3722 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array
3723 * must not be a NULL pointer.
3724 * @pre \code stride_length != 0 \endcode The pointer to the stride length
3725 * must not be a NULL pointer.
3726 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3727 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3730 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read_range
3731 (tng_trajectory_t tng_data,
3732 const int64_t first_frame,
3733 const int64_t last_frame,
3735 int64_t *stride_length);
3738 * @brief High-level function for setting the writing interval of data blocks.
3739 * @param tng_data is the trajectory to use.
3740 * @param i is the output interval, i.e. i == 10 means data written every 10th
3742 * @param n_values_per_frame is the number of values to store per frame. If the
3743 * data is particle dependent there will be n_values_per_frame stored per
3744 * particle each frame.
3745 * @param block_id is the ID of the block, of which to set the output interval.
3746 * @param block_name is a string that will be used as name of the block. Only
3747 * required if the block did not exist, i.e. a new block is created.
3748 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
3749 * data is not related to specific particles (e.g. box shape) or
3750 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
3751 * positions). Only required if the block did not exist, i.e. a new block is
3753 * @param compression is the compression routine to use when writing the data.
3754 * Only required if the block did not exist, i.e. a new block is created.
3755 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3756 * must be initialised before using it.
3757 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3758 * @details n_values_per_frame, block_name, particle_dependency and
3759 * compression are only used if the data block did not exist before calling
3760 * this function, in which case it is created.
3761 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3762 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3765 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_set
3766 (tng_trajectory_t tng_data,
3768 const int64_t n_values_per_frame,
3769 const int64_t block_id,
3770 const char *block_name,
3771 const char particle_dependency,
3772 const char compression);
3775 * @brief High-level function for setting the writing interval of data blocks
3776 * containing double precision data.
3777 * @param tng_data is the trajectory to use.
3778 * @param i is the output interval, i.e. i == 10 means data written every 10th
3780 * @param n_values_per_frame is the number of values to store per frame. If the
3781 * data is particle dependent there will be n_values_per_frame stored per
3782 * particle each frame.
3783 * @param block_id is the ID of the block, of which to set the output interval.
3784 * @param block_name is a string that will be used as name of the block. Only
3785 * required if the block did not exist, i.e. a new block is created.
3786 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
3787 * data is not related to specific particles (e.g. box shape) or
3788 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
3789 * positions). Only required if the block did not exist, i.e. a new block is
3791 * @param compression is the compression routine to use when writing the data.
3792 * Only required if the block did not exist, i.e. a new block is created.
3793 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3794 * must be initialised before using it.
3795 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3796 * @details n_values_per_frame, block_name, particle_dependency and
3797 * compression are only used if the data block did not exist before calling
3798 * this function, in which case it is created.
3799 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3800 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3803 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_double_set
3804 (tng_trajectory_t tng_data,
3806 const int64_t n_values_per_frame,
3807 const int64_t block_id,
3808 const char *block_name,
3809 const char particle_dependency,
3810 const char compression);
3813 * @brief High-level function for setting the writing interval of data blocks.
3814 * Obsolete! Use tng_util_generic_write_interval_set()
3815 * @param tng_data is the trajectory to use.
3816 * @param i is the output interval, i.e. i == 10 means data written every 10th
3818 * @param n_values_per_frame is the number of values to store per frame. If the
3819 * data is particle dependent there will be n_values_per_frame stored per
3820 * particle each frame.
3821 * @param block_id is the ID of the block, of which to set the output interval.
3822 * @param block_name is a string that will be used as name of the block. Only
3823 * required if the block did not exist, i.e. a new block is created.
3824 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
3825 * data is not related to specific particles (e.g. box shape) or
3826 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
3827 * positions). Only required if the block did not exist, i.e. a new block is
3829 * @param compression is the compression routine to use when writing the data.
3830 * Only required if the block did not exist, i.e. a new block is created.
3831 * @details n_values_per_frame, block_name, particle_dependency and
3832 * compression are only used if the data block did not exist before calling
3833 * this function, in which case it is created.
3834 * This function is replaced by the more correcly named
3835 * tng_util_generic_write_interval_set(), but is kept for compatibility.
3836 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3837 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3840 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_frequency_set
3841 (tng_trajectory_t tng_data,
3843 const int64_t n_values_per_frame,
3844 const int64_t block_id,
3845 const char *block_name,
3846 const char particle_dependency,
3847 const char compression);
3850 * @brief High-level function for setting the writing interval of position
3852 * @param tng_data is the trajectory to use.
3853 * @param i is the output interval, i.e. i == 10 means data written every 10th
3855 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3856 * must be initialised before using it.
3857 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3858 * @details This function uses tng_util_generic_write_interval_set() and will
3859 * create a positions data block if none exists.
3860 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3861 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3864 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_set
3865 (tng_trajectory_t tng_data,
3869 * @brief High-level function for setting the writing interval of position
3870 * data blocks containing double precision data.
3871 * @param tng_data is the trajectory to use.
3872 * @param i is the output interval, i.e. i == 10 means data written every 10th
3874 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3875 * must be initialised before using it.
3876 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3877 * @details This function uses tng_util_generic_write_interval_set() and will
3878 * create a positions data block if none exists.
3879 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3880 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3883 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_double_set
3884 (tng_trajectory_t tng_data,
3888 * @brief High-level function for setting the writing interval of position
3889 * data blocks. Obsolete! Use tng_util_pos_write_interval_set()
3890 * @param tng_data is the trajectory to use.
3891 * @param i is the output interval, i.e. i == 10 means data written every 10th
3893 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3894 * must be initialised before using it.
3895 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3896 * @details This function uses tng_util_generic_write_interval_set() and will
3897 * create a positions data block if none exists.
3898 * This function is replaced by the more correcly named
3899 * tng_util_pos_write_interval_set(), but is kept for compatibility.
3900 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3901 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3904 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_frequency_set
3905 (tng_trajectory_t tng_data,
3909 * @brief High-level function for setting the writing interval of velocity
3911 * @param tng_data is the trajectory to use.
3912 * @param i is the output interval, i.e. i == 10 means data written every 10th
3914 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3915 * must be initialised before using it.
3916 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3917 * @details This function uses tng_util_generic_write_interval_set() and will
3918 * create a velocities data block if none exists.
3919 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3920 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3923 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_set
3924 (tng_trajectory_t tng_data,
3928 * @brief High-level function for setting the writing interval of velocity
3929 * data blocks containing double precision data.
3930 * @param tng_data is the trajectory to use.
3931 * @param i is the output interval, i.e. i == 10 means data written every 10th
3933 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3934 * must be initialised before using it.
3935 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3936 * @details This function uses tng_util_generic_write_interval_set() and will
3937 * create a velocities data block if none exists.
3938 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3939 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3942 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_double_set
3943 (tng_trajectory_t tng_data,
3947 * @brief High-level function for setting the writing interval of velocity
3948 * data blocks. Obsolete! Use tng_util_vel_write_interval_set()
3949 * @param tng_data is the trajectory to use.
3950 * @param i is the output interval, i.e. i == 10 means data written every 10th
3952 * @details This function uses tng_util_generic_write_interval_set() and will
3953 * create a velocities data block if none exists.
3954 * This function is replaced by the more correcly named
3955 * tng_util_vel_write_interval_set(), but is kept for compatibility.
3956 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3957 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3960 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_frequency_set
3961 (tng_trajectory_t tng_data,
3965 * @brief High-level function for setting the writing interval of force
3967 * @param tng_data is the trajectory to use.
3968 * @param i is the output interval, i.e. i == 10 means data written every 10th
3970 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3971 * must be initialised before using it.
3972 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3973 * @details This function uses tng_util_generic_write_interval_set() and will
3974 * create a forces data block if none exists.
3975 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3976 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3979 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_set
3980 (tng_trajectory_t tng_data,
3984 * @brief High-level function for setting the writing interval of force
3985 * data blocks containing double precision data.
3986 * @param tng_data is the trajectory to use.
3987 * @param i is the output interval, i.e. i == 10 means data written every 10th
3989 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
3990 * must be initialised before using it.
3991 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
3992 * @details This function uses tng_util_generic_write_interval_set() and will
3993 * create a forces data block if none exists.
3994 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
3995 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
3998 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_double_set
3999 (tng_trajectory_t tng_data,
4003 * @brief High-level function for setting the writing interval of force
4004 * data blocks. Obsolete! Use tng_util_force_write_interval_set()
4005 * @param tng_data is the trajectory to use.
4006 * @param i is the output interval, i.e. i == 10 means data written every 10th
4008 * @details This function uses tng_util_generic_write_interval_set() and will
4009 * create a forces data block if none exists.
4010 * This function is replaced by the more correcly named
4011 * tng_util_force_write_interval_set(), but is kept for compatibility.
4012 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4013 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4016 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_frequency_set
4017 (tng_trajectory_t tng_data,
4021 * @brief High-level function for setting the writing interval of box shape
4023 * @param tng_data is the trajectory to use.
4024 * @param i is the output interval, i.e. i == 10 means data written every 10th
4026 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4027 * must be initialised before using it.
4028 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
4029 * @details This function uses tng_util_generic_write_interval_set() and will
4030 * create a box shape data block if none exists.
4031 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4032 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4035 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_set
4036 (tng_trajectory_t tng_data,
4040 * @brief High-level function for setting the writing interval of box shape
4041 * data blocks containing double precision data.
4042 * @param tng_data is the trajectory to use.
4043 * @param i is the output interval, i.e. i == 10 means data written every 10th
4045 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4046 * must be initialised before using it.
4047 * @pre \code i >= 0 \endcode The writing interval must be >= 0.
4048 * @details This function uses tng_util_generic_write_interval_set() and will
4049 * create a box shape data block if none exists.
4050 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4051 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4054 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_double_set
4055 (tng_trajectory_t tng_data,
4059 * @brief High-level function for setting the writing interval of velocity
4060 * data blocks. Obsolete! Use tng_util_box_shape_write_interval_set()
4061 * @param tng_data is the trajectory to use.
4062 * @param i is the output interval, i.e. i == 10 means data written every 10th
4064 * @details This function uses tng_util_generic_write_interval_set() and will
4065 * create a box shape data block if none exists.
4066 * This function is replaced by the more correcly named
4067 * tng_util_box_shape_write_interval_set(), but is kept for compatibility.
4068 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4069 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4072 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_frequency_set
4073 (tng_trajectory_t tng_data,
4077 * @brief High-level function for writing data of one frame to a data block.
4078 * @param tng_data is the trajectory to use.
4079 * @param frame_nr is the frame number of the data.
4080 * @param values is a 1D array of data to add. The array should be of length
4081 * n_particles * n_values_per_frame if writing particle related data, otherwise
4082 * it should be n_values_per_frame.
4083 * @param n_values_per_frame is the number of values to store per frame. If the
4084 * data is particle dependent there will be n_values_per_frame stored per
4085 * particle each frame.
4086 * @param block_id is the ID of the block, of which to set the output interval.
4087 * @param block_name is a string that will be used as name of the block. Only
4088 * required if the block did not exist, i.e. a new block is created.
4089 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4090 * data is not related to specific particles (e.g. box shape) or
4091 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4092 * positions). Only required if the block did not exist, i.e. a new block is
4094 * @param compression is the compression routine to use when writing the data.
4095 * Only required if the block did not exist, i.e. a new block is created.
4096 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4097 * must be initialised before using it.
4098 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4099 * @pre \code values != 0 \endcode The pointer to the values array must not
4100 * be a NULL pointer.
4101 * @details n_values_per_frame, block_name, particle_dependency and
4102 * compression are only used if the data block did not exist before calling
4103 * this function, in which case it is created.
4104 * N.b. Data is written a whole block at a time. The data is not
4105 * actually written to disk until the frame set is finished or the TNG
4106 * trajectory is closed.
4107 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4108 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4111 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write
4112 (tng_trajectory_t tng_data,
4113 const int64_t frame_nr,
4114 const float *values,
4115 const int64_t n_values_per_frame,
4116 const int64_t block_id,
4117 const char *block_name,
4118 const char particle_dependency,
4119 const char compression);
4122 * @brief High-level function for writing data of one frame to a double precision
4124 * @param tng_data is the trajectory to use.
4125 * @param frame_nr is the frame number of the data.
4126 * @param values is a 1D array of data to add. The array should be of length
4127 * n_particles * n_values_per_frame if writing particle related data, otherwise
4128 * it should be n_values_per_frame.
4129 * @param n_values_per_frame is the number of values to store per frame. If the
4130 * data is particle dependent there will be n_values_per_frame stored per
4131 * particle each frame.
4132 * @param block_id is the ID of the block, of which to set the output interval.
4133 * @param block_name is a string that will be used as name of the block. Only
4134 * required if the block did not exist, i.e. a new block is created.
4135 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4136 * data is not related to specific particles (e.g. box shape) or
4137 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4138 * positions). Only required if the block did not exist, i.e. a new block is
4140 * @param compression is the compression routine to use when writing the data.
4141 * Only required if the block did not exist, i.e. a new block is created.
4142 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4143 * must be initialised before using it.
4144 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4145 * @pre \code values != 0 \endcode The pointer to the values array must not
4146 * be a NULL pointer.
4147 * @details n_values_per_frame, block_name, particle_dependency and
4148 * compression are only used if the data block did not exist before calling
4149 * this function, in which case it is created.
4150 * N.b. Data is written a whole block at a time. The data is not
4151 * actually written to disk until the frame set is finished or the TNG
4152 * trajectory is closed.
4153 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4154 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4157 tng_function_status DECLSPECDLLEXPORT tng_util_generic_double_write
4158 (tng_trajectory_t tng_data,
4159 const int64_t frame_nr,
4160 const double *values,
4161 const int64_t n_values_per_frame,
4162 const int64_t block_id,
4163 const char *block_name,
4164 const char particle_dependency,
4165 const char compression);
4168 * @brief High-level function for adding data to positions data blocks.
4169 * @param tng_data is the trajectory to use.
4170 * @param frame_nr is the frame number of the data.
4171 * @param positions is a 1D array of data to add. The array should be of length
4173 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4174 * must be initialised before using it.
4175 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4176 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4177 * be a NULL pointer.
4178 * @details This function uses tng_util_generic_write() and will
4179 * create a positions data block if none exists. Positions are stored as three
4180 * values per frame and compressed using TNG compression.
4181 * N.b. Since compressed data is written a whole block at a time the data is not
4182 * actually written to disk until the frame set is finished or the TNG
4183 * trajectory is closed.
4184 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4185 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4188 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write
4189 (tng_trajectory_t tng_data,
4190 const int64_t frame_nr,
4191 const float *positions);
4194 * @brief High-level function for adding data to positions data blocks at double
4196 * @param tng_data is the trajectory to use.
4197 * @param frame_nr is the frame number of the data.
4198 * @param positions is a 1D array of data to add. The array should be of length
4200 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4201 * must be initialised before using it.
4202 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4203 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4204 * be a NULL pointer.
4205 * @details This function uses tng_util_generic_write() and will
4206 * create a positions data block if none exists. Positions are stored as three
4207 * values per frame and compressed using TNG compression.
4208 * N.b. Since compressed data is written a whole block at a time the data is not
4209 * actually written to disk until the frame set is finished or the TNG
4210 * trajectory is closed.
4211 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4212 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4215 tng_function_status DECLSPECDLLEXPORT tng_util_pos_double_write
4216 (tng_trajectory_t tng_data,
4217 const int64_t frame_nr,
4218 const double *positions);
4221 * @brief High-level function for adding data to velocities data blocks.
4222 * @param tng_data is the trajectory to use.
4223 * @param frame_nr is the frame number of the data.
4224 * @param velocities is a 1D array of data to add. The array should be of length
4226 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4227 * must be initialised before using it.
4228 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4229 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4230 * be a NULL pointer.
4231 * @details This function uses tng_util_generic_write() and will
4232 * create a velocities data block if none exists. Velocities are stored as three
4233 * values per frame and compressed using TNG compression.
4234 * N.b. Since compressed data is written a whole block at a time the data is not
4235 * actually written to disk until the frame set is finished or the TNG
4236 * trajectory is closed.
4237 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4238 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4241 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write
4242 (tng_trajectory_t tng_data,
4243 const int64_t frame_nr,
4244 const float *velocities);
4247 * @brief High-level function for adding data to velocities data blocks at double
4249 * @param tng_data is the trajectory to use.
4250 * @param frame_nr is the frame number of the data.
4251 * @param velocities is a 1D array of data to add. The array should be of length
4253 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4254 * must be initialised before using it.
4255 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4256 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4257 * be a NULL pointer.
4258 * @details This function uses tng_util_generic_write() and will
4259 * create a velocities data block if none exists. Velocities are stored as three
4260 * values per frame and compressed using TNG compression.
4261 * N.b. Since compressed data is written a whole block at a time the data is not
4262 * actually written to disk until the frame set is finished or the TNG
4263 * trajectory is closed.
4264 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4265 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4268 tng_function_status DECLSPECDLLEXPORT tng_util_vel_double_write
4269 (tng_trajectory_t tng_data,
4270 const int64_t frame_nr,
4271 const double *velocities);
4274 * @brief High-level function for adding data to forces data blocks.
4275 * @param tng_data is the trajectory to use.
4276 * @param frame_nr is the frame number of the data.
4277 * @param forces is a 1D array of data to add. The array should be of length
4279 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4280 * must be initialised before using it.
4281 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4282 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4283 * be a NULL pointer.
4284 * @details This function uses tng_util_generic_write() and will
4285 * create a forces data block if none exists. Forces are stored as three
4286 * values per frame and compressed using gzip compression.
4287 * N.b. Since compressed data is written a whole block at a time the data is not
4288 * actually written to disk until the frame set is finished or the TNG
4289 * trajectory is closed.
4290 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4291 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4294 tng_function_status DECLSPECDLLEXPORT tng_util_force_write
4295 (tng_trajectory_t tng_data,
4296 const int64_t frame_nr,
4297 const float *forces);
4300 * @brief High-level function for adding data to forces data blocks at double
4302 * @param tng_data is the trajectory to use.
4303 * @param frame_nr is the frame number of the data.
4304 * @param forces is a 1D array of data to add. The array should be of length
4306 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4307 * must be initialised before using it.
4308 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4309 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4310 * be a NULL pointer.
4311 * @details This function uses tng_util_generic_write() and will
4312 * create a forces data block if none exists. Forces are stored as three
4313 * values per frame and compressed using gzip compression.
4314 * N.b. Since compressed data is written a whole block at a time the data is not
4315 * actually written to disk until the frame set is finished or the TNG
4316 * trajectory is closed.
4317 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4318 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4321 tng_function_status DECLSPECDLLEXPORT tng_util_force_double_write
4322 (tng_trajectory_t tng_data,
4323 const int64_t frame_nr,
4324 const double *forces);
4327 * @brief High-level function for adding data to box shape data blocks.
4328 * @param tng_data is the trajectory to use.
4329 * @param frame_nr is the frame number of the data.
4330 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4331 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4332 * must be initialised before using it.
4333 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4334 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4335 * be a NULL pointer.
4336 * @details This function uses tng_util_generic_write() and will
4337 * create a box shape data block if none exists. Box shapes are stored as 9
4338 * values per frame and compressed using TNG compression.
4339 * N.b. Since compressed data is written a whole block at a time the data is not
4340 * actually written to disk until the frame set is finished or the TNG
4341 * trajectory is closed.
4342 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4343 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4346 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write
4347 (tng_trajectory_t tng_data,
4348 const int64_t frame_nr,
4349 const float *box_shape);
4352 * @brief High-level function for adding data to box shape data blocks at double
4354 * @param tng_data is the trajectory to use.
4355 * @param frame_nr is the frame number of the data.
4356 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4357 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4358 * must be initialised before using it.
4359 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4360 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4361 * be a NULL pointer.
4362 * @details This function uses tng_util_generic_write() and will
4363 * create a box shape data block if none exists. Box shapes are stored as 9
4364 * values per frame and compressed using TNG compression.
4365 * N.b. Since compressed data is written a whole block at a time the data is not
4366 * actually written to disk until the frame set is finished or the TNG
4367 * trajectory is closed.
4368 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4369 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4372 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_double_write
4373 (tng_trajectory_t tng_data,
4374 const int64_t frame_nr,
4375 const double *box_shape);
4378 * @brief High-level function for writing data of one frame to a data block.
4379 * If the frame is at the beginning of a frame set the time stamp of the frame
4381 * @param tng_data is the trajectory to use.
4382 * @param frame_nr is the frame number of the data.
4383 * @param time is the time stamp of the frame (in seconds).
4384 * @param values is a 1D array of data to add. The array should be of length
4385 * n_particles * n_values_per_frame if writing particle related data, otherwise
4386 * it should be n_values_per_frame.
4387 * @param n_values_per_frame is the number of values to store per frame. If the
4388 * data is particle dependent there will be n_values_per_frame stored per
4389 * particle each frame.
4390 * @param block_id is the ID of the block, of which to set the output interval.
4391 * @param block_name is a string that will be used as name of the block. Only
4392 * required if the block did not exist, i.e. a new block is created.
4393 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4394 * data is not related to specific particles (e.g. box shape) or
4395 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4396 * positions). Only required if the block did not exist, i.e. a new block is
4398 * @param compression is the compression routine to use when writing the data.
4399 * Only required if the block did not exist, i.e. a new block is created.
4400 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4401 * must be initialised before using it.
4402 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4403 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4404 * @pre \code values != 0 \endcode The pointer to the values array must not
4405 * be a NULL pointer.
4406 * @details n_values_per_frame, block_name, particle_dependency and
4407 * compression are only used if the data block did not exist before calling
4408 * this function, in which case it is created.
4409 * N.b. Data is written a whole block at a time. The data is not
4410 * actually written to disk until the frame set is finished or the TNG
4411 * trajectory is closed.
4412 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4413 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4416 tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_write
4417 (tng_trajectory_t tng_data,
4418 const int64_t frame_nr,
4420 const float *values,
4421 const int64_t n_values_per_frame,
4422 const int64_t block_id,
4423 const char *block_name,
4424 const char particle_dependency,
4425 const char compression);
4428 * @brief High-level function for writing data of one frame to a double precision
4429 * data block. If the frame is at the beginning of a frame set the time stamp of
4430 * the frame set is set.
4431 * @param tng_data is the trajectory to use.
4432 * @param frame_nr is the frame number of the data.
4433 * @param time is the time stamp of the frame (in seconds).
4434 * @param values is a 1D array of data to add. The array should be of length
4435 * n_particles * n_values_per_frame if writing particle related data, otherwise
4436 * it should be n_values_per_frame.
4437 * @param n_values_per_frame is the number of values to store per frame. If the
4438 * data is particle dependent there will be n_values_per_frame stored per
4439 * particle each frame.
4440 * @param block_id is the ID of the block, of which to set the output interval.
4441 * @param block_name is a string that will be used as name of the block. Only
4442 * required if the block did not exist, i.e. a new block is created.
4443 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the
4444 * data is not related to specific particles (e.g. box shape) or
4445 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g.
4446 * positions). Only required if the block did not exist, i.e. a new block is
4448 * @param compression is the compression routine to use when writing the data.
4449 * Only required if the block did not exist, i.e. a new block is created.
4450 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4451 * must be initialised before using it.
4452 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4453 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4454 * @pre \code values != 0 \endcode The pointer to the values array must not
4455 * be a NULL pointer.
4456 * @details n_values_per_frame, block_name, particle_dependency and
4457 * compression are only used if the data block did not exist before calling
4458 * this function, in which case it is created.
4459 * N.b. Data is written a whole block at a time. The data is not
4460 * actually written to disk until the frame set is finished or the TNG
4461 * trajectory is closed.
4462 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4463 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4466 tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_double_write
4467 (tng_trajectory_t tng_data,
4468 const int64_t frame_nr,
4470 const double *values,
4471 const int64_t n_values_per_frame,
4472 const int64_t block_id,
4473 const char *block_name,
4474 const char particle_dependency,
4475 const char compression);
4478 * @brief High-level function for adding data to positions data blocks. If the
4479 * frame is at the beginning of a frame set the time stamp of the frame set
4481 * @param tng_data is the trajectory to use.
4482 * @param frame_nr is the frame number of the data.
4483 * @param time is the time stamp of the frame (in seconds).
4484 * @param positions is a 1D array of data to add. The array should be of length
4486 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4487 * must be initialised before using it.
4488 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4489 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4490 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4491 * be a NULL pointer.
4492 * @details This function uses tng_util_generic_with_time_write() and will
4493 * create a positions data block if none exists. Positions are stored as three
4494 * values per frame and compressed using TNG compression.
4495 * N.b. Since compressed data is written a whole block at a time the data is not
4496 * actually written to disk until the frame set is finished or the TNG
4497 * trajectory is closed.
4498 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4499 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4502 tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_write
4503 (tng_trajectory_t tng_data,
4504 const int64_t frame_nr,
4506 const float *positions);
4509 * @brief High-level function for adding data to positions data blocks at double
4510 * precision. If the frame is at the beginning of a frame set the time stamp of
4511 * the frame set is set.
4512 * @param tng_data is the trajectory to use.
4513 * @param frame_nr is the frame number of the data.
4514 * @param time is the time stamp of the frame (in seconds).
4515 * @param positions is a 1D array of data to add. The array should be of length
4517 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4518 * must be initialised before using it.
4519 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4520 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4521 * @pre \code positions != 0 \endcode The pointer to the positions array must not
4522 * be a NULL pointer.
4523 * @details This function uses tng_util_generic_with_time_double_write() and will
4524 * create a positions data block if none exists. Positions are stored as three
4525 * values per frame and compressed using TNG compression.
4526 * N.b. Since compressed data is written a whole block at a time the data is not
4527 * actually written to disk until the frame set is finished or the TNG
4528 * trajectory is closed.
4529 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4530 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4533 tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_double_write
4534 (tng_trajectory_t tng_data,
4535 const int64_t frame_nr,
4537 const double *positions);
4540 * @brief High-level function for adding data to velocities data blocks. If the
4541 * frame is at the beginning of a frame set the time stamp of the frame set
4543 * @param tng_data is the trajectory to use.
4544 * @param frame_nr is the frame number of the data.
4545 * @param time is the time stamp of the frame (in seconds).
4546 * @param velocities is a 1D array of data to add. The array should be of length
4548 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4549 * must be initialised before using it.
4550 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4551 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4552 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4553 * be a NULL pointer.
4554 * @details This function uses tng_util_generic_with_time_write() and will
4555 * create a velocities data block if none exists. Velocities are stored as three
4556 * values per frame and compressed using TNG compression.
4557 * N.b. Since compressed data is written a whole block at a time the data is not
4558 * actually written to disk until the frame set is finished or the TNG
4559 * trajectory is closed.
4560 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4561 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4564 tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_write
4565 (tng_trajectory_t tng_data,
4566 const int64_t frame_nr,
4568 const float *velocities);
4571 * @brief High-level function for adding data to velocities data blocks at
4572 * double precision. If the frame is at the beginning of a frame set the
4573 * time stamp of the frame set is set.
4574 * @param tng_data is the trajectory to use.
4575 * @param frame_nr is the frame number of the data.
4576 * @param time is the time stamp of the frame (in seconds).
4577 * @param velocities is a 1D array of data to add. The array should be of length
4579 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4580 * must be initialised before using it.
4581 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4582 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4583 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not
4584 * be a NULL pointer.
4585 * @details This function uses tng_util_generic_with_time_double_write() and will
4586 * create a velocities data block if none exists. Velocities are stored as three
4587 * values per frame and compressed using TNG compression.
4588 * N.b. Since compressed data is written a whole block at a time the data is not
4589 * actually written to disk until the frame set is finished or the TNG
4590 * trajectory is closed.
4591 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4592 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4595 tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_double_write
4596 (tng_trajectory_t tng_data,
4597 const int64_t frame_nr,
4599 const double *velocities);
4602 * @brief High-level function for adding data to forces data blocks. If the
4603 * frame is at the beginning of a frame set the time stamp of the frame set
4605 * @param tng_data is the trajectory to use.
4606 * @param frame_nr is the frame number of the data.
4607 * @param time is the time stamp of the frame (in seconds).
4608 * @param forces is a 1D array of data to add. The array should be of length
4610 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4611 * must be initialised before using it.
4612 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4613 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4614 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4615 * be a NULL pointer.
4616 * @details This function uses tng_util_generic_with_time_write() and will
4617 * create a forces data block if none exists. Forces are stored as three
4618 * values per frame and compressed using gzip compression.
4619 * N.b. Since compressed data is written a whole block at a time the data is not
4620 * actually written to disk until the frame set is finished or the TNG
4621 * trajectory is closed.
4622 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4623 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4626 tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_write
4627 (tng_trajectory_t tng_data,
4628 const int64_t frame_nr,
4630 const float *forces);
4633 * @brief High-level function for adding data to forces data blocks at
4634 * double precision. If the frame is at the beginning of a frame set
4635 * the time stamp of the frame set is set.
4636 * @param tng_data is the trajectory to use.
4637 * @param frame_nr is the frame number of the data.
4638 * @param time is the time stamp of the frame (in seconds).
4639 * @param forces is a 1D array of data to add. The array should be of length
4641 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4642 * must be initialised before using it.
4643 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4644 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4645 * @pre \code forces != 0 \endcode The pointer to the forces array must not
4646 * be a NULL pointer.
4647 * @details This function uses tng_util_generic_with_time_double_write() and will
4648 * create a forces data block if none exists. Forces are stored as three
4649 * values per frame and compressed using gzip compression.
4650 * N.b. Since compressed data is written a whole block at a time the data is not
4651 * actually written to disk until the frame set is finished or the TNG
4652 * trajectory is closed.
4653 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4654 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4657 tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_double_write
4658 (tng_trajectory_t tng_data,
4659 const int64_t frame_nr,
4661 const double *forces);
4664 * @brief High-level function for adding data to box shape data blocks. If the
4665 * frame is at the beginning of a frame set the time stamp of the frame set
4667 * @param tng_data is the trajectory to use.
4668 * @param frame_nr is the frame number of the data.
4669 * @param time is the time stamp of the frame (in seconds).
4670 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4671 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4672 * must be initialised before using it.
4673 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4674 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4675 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4676 * be a NULL pointer.
4677 * @details This function uses tng_util_generic_with_time_write() and will
4678 * create a box shape data block if none exists. Box shapes are stored as 9
4679 * values per frame and compressed using TNG compression.
4680 * N.b. Since compressed data is written a whole block at a time the data is not
4681 * actually written to disk until the frame set is finished or the TNG
4682 * trajectory is closed.
4683 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4684 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4687 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_write
4688 (tng_trajectory_t tng_data,
4689 const int64_t frame_nr,
4691 const float *box_shape);
4694 * @brief High-level function for adding data to box shape data blocks at
4695 * double precision. If the frame is at the beginning of a frame set the
4696 * time stamp of the frame set is set.
4697 * @param tng_data is the trajectory to use.
4698 * @param frame_nr is the frame number of the data.
4699 * @param time is the time stamp of the frame (in seconds).
4700 * @param box_shape is a 1D array of data to add. The array should be of length 9.
4701 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4702 * must be initialised before using it.
4703 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0.
4704 * @pre \code time >= 0 \endcode The time stamp must be >= 0.
4705 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not
4706 * be a NULL pointer.
4707 * @details This function uses tng_util_generic_with_time_double_write() and will
4708 * create a box shape data block if none exists. Box shapes are stored as 9
4709 * values per frame and compressed using TNG compression.
4710 * N.b. Since compressed data is written a whole block at a time the data is not
4711 * actually written to disk until the frame set is finished or the TNG
4712 * trajectory is closed.
4713 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4714 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4717 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_double_write
4718 (tng_trajectory_t tng_data,
4719 const int64_t frame_nr,
4721 const double *box_shape);
4724 * @brief High-level function for getting the compression method and
4725 * multiplication factor of the last read frame of a specific data block.
4726 * @param tng_data is the trajectory to use.
4727 * @param block_id is the ID number of the block containing the data of
4729 * @param codec_id will be set to the value of the codec_id of the
4730 * compression of the data block. See tng_compression for more details.
4731 * @param factor will be set to the multiplication factor applied to
4732 * the values before compression, in order to get integers from them.
4733 * factor is 1/precision.
4734 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4735 * must be initialised before using it.
4736 * @pre \code codec_id != 0 \endcode The pointer to the returned codec id
4737 * must not be a NULL pointer.
4738 * @pre \code factor != 0 \endcode The pointer to the returned multiplication
4739 * factor must not be a NULL pointer.
4740 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4741 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error
4744 tng_function_status DECLSPECDLLEXPORT tng_util_frame_current_compression_get
4745 (tng_trajectory_t tng_data,
4746 const int64_t block_id,
4750 /** @brief High-level function for determining the next frame with data and what
4751 * data blocks have data for that frame. The search can be limited to certain
4753 * @param tng_data is the trajectory to use.
4754 * @param current_frame is the frame that was last read, from where to start
4756 * @param n_requested_data_block_ids is the number of data blocks listed in
4757 * requested_data_block_ids. If this is 0 all data blocks will be taken into
4759 * @param requested_data_block_ids is an array of data blocks to look for.
4760 * @param next_frame will be set to the next frame with data.
4761 * @param n_data_blocks_in_next_frame is set to the number of data blocks with
4762 * data for next_frame.
4763 * @param data_block_ids_in_next_frame is set to an array (of length
4764 * n_data_blocks_in_next_frame) that lists the data block IDs with data for
4765 * next_frame. 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 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4770 * must be initialised before using it.
4771 * @pre \code next_frame != 0 \endcode The pointer to the next frame must not
4773 * @pre \code n_data_blocks_in_next_frame != 0 \endcode The pointer to
4774 * n_data_blocks_in_next_frame must not be NULL.
4775 * @pre \code *data_block_ids_in_next_frame != 0 \endcode The pointer to the
4776 * list of data block IDs must not be NULL.
4777 * @pre \code n_requested_data_block_ids == 0 || requested_data_block_ids != 0 \endcode
4778 * If the number of requested data blocks != 0 then the array of data block IDs must not be NULL.
4779 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4780 * has occured or TNG_CRITICAL (2) if a major error
4783 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_next_frame_present_data_blocks_find
4784 (tng_trajectory_t tng_data,
4785 int64_t current_frame,
4786 const int64_t n_requested_data_block_ids,
4787 const int64_t *requested_data_block_ids,
4788 int64_t *next_frame,
4789 int64_t *n_data_blocks_in_next_frame,
4790 int64_t **data_block_ids_in_next_frame);
4792 /* @brief High-level function for getting all data block ids and their names
4793 * and stride lengths.
4794 * @param tng_data is the trajectory to use.
4795 * @param n_data_blocks is set to the number of data blocks in the trajectory.
4796 * @param data_block_ids is set to an array (of length
4797 * n_data_blocks) that lists the data block IDs in the trajectory.
4798 * It must be pointing at NULL or previously allocated memory.
4799 * Memory for the array is allocated by this function.
4800 * The memory must be freed by the client afterwards or
4801 * there will be a memory leak.
4802 * @param data_block_names is set to an array (of length
4803 * n_data_blocks) that contains the names of the data blocks.
4804 * It must be pointing at NULL or previously allocated memory.
4805 * Memory for the array is allocated by this function.
4806 * The memory must be freed by the client afterwards or
4807 * there will be a memory leak.
4808 * @param stride_lengths is set to an array (of length
4809 * n_data_blocks) that lists the stride lengths of the data blocks.
4810 * It must be pointing at NULL or previously allocated memory.
4811 * Memory for the array is allocated by this function.
4812 * The memory must be freed by the client afterwards or
4813 * there will be a memory leak.
4814 * @param n_values_per_frame is set to an array (of length
4815 * n_data_blocks) that lists the number of values per frame of the data blocks.
4816 * It must be pointing at NULL or previously allocated memory.
4817 * Memory for the array is allocated by this function.
4818 * The memory must be freed by the client afterwards or
4819 * there will be a memory leak.
4820 * @param block_types is set to an array (of length
4821 * n_data_blocks) that lists the block types of the data blocks.
4822 * It must be pointing at NULL or previously allocated memory.
4823 * Memory for the array is allocated by this function.
4824 * The memory must be freed by the client afterwards or
4825 * there will be a memory leak.
4826 * @param dependencies is set to an array (of length
4827 * n_data_blocks) that lists the dependencies of the data blocks.
4828 * It must be pointing at NULL or previously allocated memory.
4829 * Memory for the array is allocated by this function.
4830 * The memory must be freed by the client afterwards or
4831 * there will be a memory leak.
4832 * @param compressions is set to an array (of length
4833 * n_data_blocks) that lists the compressions of the data blocks.
4834 * It must be pointing at NULL or previously allocated memory.
4835 * Memory for the array is allocated by this function.
4836 * The memory must be freed by the client afterwards or
4837 * there will be a memory leak.
4838 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4839 * must be initialised before using it.
4840 * @pre \code n_data_blocks != 0 \endcode The pointer to
4841 * n_data_blocks must not be NULL.
4842 * @pre \code data_block_ids != 0 \endcode The pointer to the
4843 * list of data block IDs must not be NULL.
4844 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4845 * has occured or TNG_CRITICAL (2) if a major error
4849 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_all_data_block_types_get
4850 (tng_trajectory_t tng_data,
4851 int64_t *n_data_blocks,
4852 int64_t **data_block_ids,
4853 char ***data_block_names,
4854 int64_t **stride_lengths,
4855 int64_t **n_values_per_frame,
4857 char **dependencies,
4858 char **compressions);
4861 /** @brief Finds the frame set of the specified frame in order to prepare for writing
4863 * @param tng_data is the trajectory to use.
4864 * @param prev_frame is the frame after which to start appending.
4865 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data)
4866 * must be initialised before using it.
4867 * @pre \code prev_frame >= 0 \endcode The previous frame must not be negative.
4868 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
4869 * has occured (such as not finding the requested frame) or TNG_CRITICAL (2)
4870 * if a major error has occured.
4872 tng_function_status DECLSPECDLLEXPORT tng_util_prepare_append_after_frame
4873 (tng_trajectory_t tng_data,
4874 const int64_t prev_frame);
4876 /** @} */ /* end of group2 */
4880 } /* end extern "C" */
4883 #endif /* TNG_IO_H */