/* This code is part of the tng binary trajectory format. * * Written by Magnus Lundborg * Copyright (c) 2012-2013, The GROMACS development team. * Check out http://www.gromacs.org for more information. * * * This program is free software; you can redistribute it and/or * modify it under the terms of the Revised BSD License. */ /** @file tng_io.h * @brief API for input and output of tng trajectory files * @mainpage TNG: A flexible binary trajectory format * @section intro_sec Introduction * * The TNG format is developed as part of the ScalaLife EU project. * It is flexible by design to allow parallel writing, custom data blocks, * different output frequencies and different compression algorithms. * * Each block can contain MD5 hashes to verify data integrity and the file * can be signed by the user to ensure that the origin is correct. * * This is version 1.4 of the TNG API. The intention is that this version of * the API and ABI should be stable, but it is still possible that future * changes might make that impossible, in which case that will be clarified. * * The API and all examples are released without any warranties. Use them at * your own risk. * * @section authors_sec Authors * * The TNG trajectory format is developed by: * * Magnus Lundborg magnus.lundborg@scilifelab.se * * Daniel Spångberg daniels@mkem.uu.se * * Rossen Apostolov rossen@kth.se * * The API is implemented mainly by: * * Magnus Lundborg * * @section License * * Copyright (c) 2012, The GROMACS development team. * check out http://www.gromacs.org for more information. * * The TNG API is released under the Revised BSD License and is free to * redistribute according to that license. * * A license file (named COPYING) should be included with each copy of the API. * * @section install_sec Installation * * \code * mkdir build * * cd build * * cmake .. * * make * * make install * \endcode * Test by running: * \code * bin/tests/tng_testing * \endcode * * @section change_sec Change Log * * See git log for full revision history. * * Revisions * * v. 1.5 - Third stable release of the API. * * - Fortran wrapper split into separate file * - Added more block IDs. * - Some new functions and utility functions added. * - Improved compression precision settings. * - Improved tests. * - Make appending to file work better. * - Modified CMake settings * - Bugs fixed * * v. 1.4 - Changed from LGPL to the Revised BSD License. * * - More flexible support for digital signatures in header. * - Block ID numbers changed. * * v. 1.3 - Second stable release of the API. * * - Added multiplication factor for coordinate units to general info. * - Added time stamps and time per frame in frame sets. * - High-level API functions added (not for managing molecules yet) * - Added functions for reading data blocks into 1D arrays. * - TNG compression added. * - C++ interface added. * - Avoid memory allocation if no data is submitted when adding data * blocks. * - Added function tng_num_frames_per_frame_set_set * - Added data block IDs for charges, b-factors and occupancy. * - GZIP compression added. * - Fixed bug when updating MD5 hashes of data blocks. * - Fixed bug in chain_name_of_particle_get(...) * - Update frame set pointers properly. * - Moved fortran wrapper from header file to source file. * - Write sparse data in mdrun examples. * - Fixed bugs related to reading and writing sparse data. * - Fixed memory leak for non-trajectory particle data blocks. * - Fixed bug when writing data blocks. * - Fixed wrong values in dependency constants * - Write box shape, partial charges and annotation data in tng_testing * - Bug fixes in tng_testing (frame sets not written before) * * v. 1.0 - First stable release of the API. * * * @section examples_sec Examples * * There are some examples of how to use the library located in src/tests/ * * @subsection tng_subsec TNG files * * The build directory contains an example_files directory, which in turn * contains a very short example of a TNG file containing a few water molecules, * a box shape description and positions in 10 frames. * * It is also possible to run the bin/examples/md_openmp_util * (see src/tests/md_openmp_util.c) * testing program, which will save MD simulations output to a new file * (saved in the example_files directory). * * These files can be read using the bin/examples/tng_io_read_pos_util * program. * * @subsection c_subsec C * * Example writing data to a TNG file (just an excerpt): * \code * for ( step = 1; step < step_num; step++ ) * { * compute ( np, nd, pos, vel, mass, force, &potential, &kinetic ); * * if(step % step_save == 0) * { * // Write positions, velocities and forces * if(tng_util_pos_write(traj, step, pos) != TNG_SUCCESS) * { * printf("Error adding data. %s: %d\n", __FILE__, __LINE__); * break; * } * if(tng_util_vel_write(traj, step, vel) != TNG_SUCCESS) * { * printf("Error adding data. %s: %d\n", __FILE__, __LINE__); * break; * } * if(tng_util_force_write(traj, step, force) != TNG_SUCCESS) * { * printf("Error adding data. %s: %d\n", __FILE__, __LINE__); * break; * } * } * update ( np, nd, pos, vel, force, acc, mass, dt ); * } * \endcode * * Example reading positions from a TNG file: * \code * #include * #include * #include "tng_io.h" * * int main(int argc, char **argv) * { * tng_trajectory_t traj; * // Assume that the data is stored as floats. The data is placed in 1-D * // arrays * float *positions = 0, *box_shape = 0; * int64_t n_particles, n_frames, tot_n_frames, stride_length, i, j; * // Set a default frame range * int64_t first_frame = 0, last_frame = 5000; * int k; * * // A reference must be passed to allocate memory * tng_util_trajectory_open(argv[1], 'r', &traj); * * if(tng_num_frames_get(traj, &tot_n_frames) != TNG_SUCCESS) * { * printf("Cannot determine the number of frames in the file\n"); * tng_util_trajectory_close(&traj); * exit(1); * } * * if(tng_num_particles_get(traj, &n_particles) != TNG_SUCCESS) * { * printf("Cannot determine the number of particles in the file\n"); * tng_util_trajectory_close(&traj); * exit(1); * } * * printf("%"PRId64" frames in file\n", tot_n_frames); * * if(last_frame > tot_n_frames - 1) * { * last_frame = tot_n_frames - 1; * } * * if(tng_util_box_shape_read(traj, &box_shape, &stride_length) == * TNG_SUCCESS) * { * printf("Simulation box shape: "); * for(i=0; i < 9; i++) * { * printf("%f ", box_shape[i]); * } * printf("\n"); * } * else * { * printf("Simulation box shape not set in the file (or could not be read)\n"); * } * * n_frames = last_frame - first_frame + 1; * * * // Get the positions of all particles in the requested frame range. * // The positions are stored in the positions array. * // N.B. No proper error checks. * if(tng_util_pos_read_range(traj, 0, last_frame, &positions, &stride_length) * == TNG_SUCCESS) * { * // Print the positions of the wanted particle (zero based) * for(i=0; i < n_frames; i += stride_length) * { * printf("\nFrame %"PRId64":\n", first_frame + i); * for(j=0; j < n_particles; j++) * { * printf("Atom nr: %"PRId64"", j); * for(k=0; k < 3; k++) * { * printf("\t%f", positions[i/stride_length*n_particles* * 3+j*3+k]); * } * printf("\n"); * } * } * } * else * { * printf("Cannot read positions\n"); * } * * // Free memory * if(positions) * { * free(positions); * } * tng_util_trajectory_close(&traj); * * return(0); * } * * \endcode * * @subsection fortran_subsec Fortran * * The TNG library can be used from Fortran. It requires cray pointers, which * are not part of the Fortran 77 standard, but available in most compilers. * * To compile the fortran example -DTNG_BUILD_FORTRAN=ON needs to be specified when * running cmake. * */ #ifndef TNG_IO_H #define TNG_IO_H 1 #include #include #include #include #include "tng_io_fwd.h" #ifdef USE_STD_INTTYPES_H #include #else /* Visual Studio does not contain inttypes.h and stdint.h. Some defines and * typedefs are used from the GNU C Library */ #ifdef _MSC_VER typedef __int32 int32_t; typedef unsigned __int32 uint32_t; typedef __int64 int64_t; typedef unsigned __int64 uint64_t; #else #include #endif /* _MSC_VER */ /* This is from inttypes.h (GNU C Library) */ /* The ISO C99 standard specifies that these macros must only be defined if explicitly requested. */ #if !defined __cplusplus || defined __STDC_FORMAT_MACROS # if __WORDSIZE == 64 # define __PRI64_PREFIX "l" # define __PRIPTR_PREFIX "l" # else # define __PRI64_PREFIX "ll" # define __PRIPTR_PREFIX # endif /* From stdint.h (GNU C Library) */ /* Macros for printing format specifiers. */ /* Decimal notation. */ #ifndef PRId64 # define PRId64 __PRI64_PREFIX "d" #endif #endif #endif /* USE_STD_INTTYPES_H */ #ifndef USE_WINDOWS #if defined(WIN32) || defined(_WIN32) || defined(WIN64) || defined(_WIN64) #define USE_WINDOWS #endif /* win32... */ #endif /* not defined USE_WINDOWS */ #ifndef DECLSPECDLLEXPORT #ifdef USE_WINDOWS #define DECLSPECDLLEXPORT __declspec(dllexport) #else /* USE_WINDOWS */ #define DECLSPECDLLEXPORT #endif /* USE_WINDOWS */ #endif /* DECLSPECDLLEXPORT */ /** Flag to indicate frame dependent data. */ #define TNG_FRAME_DEPENDENT 1 /** Flag to indicate particle dependent data. */ #define TNG_PARTICLE_DEPENDENT 2 /** The maximum length of a date string */ #define TNG_MAX_DATE_STR_LEN 24 /** The length of an MD5 hash */ #define TNG_MD5_HASH_LEN 16 /** The maximum allowed length of a string */ #define TNG_MAX_STR_LEN 1024 #ifndef NDEBUG #define TNG_ASSERT(cnd, msg) if(!(cnd)) {printf("%s\n", msg); assert(cnd);} #else #define TNG_ASSERT(cnd, msg) (void)0; #endif /** Flag to specify the endianness of a TNG file */ typedef enum {TNG_BIG_ENDIAN, TNG_LITTLE_ENDIAN} tng_file_endianness; /** Flag to specify the endianness of 32 bit values of the current architecture. */ typedef enum {TNG_BIG_ENDIAN_32, TNG_LITTLE_ENDIAN_32, TNG_BYTE_PAIR_SWAP_32} tng_endianness_32; /** Flag to specify the endianness of 64 bit values of the current architecture. */ typedef enum {TNG_BIG_ENDIAN_64, TNG_LITTLE_ENDIAN_64, TNG_QUAD_SWAP_64, TNG_BYTE_PAIR_SWAP_64, TNG_BYTE_SWAP_64} tng_endianness_64; /** Compression mode is specified in each data block */ typedef enum {TNG_UNCOMPRESSED, TNG_XTC_COMPRESSION, TNG_TNG_COMPRESSION, TNG_GZIP_COMPRESSION} tng_compression; /** Hash types */ typedef enum {TNG_NO_HASH, TNG_MD5, TNG_SHA256} tng_hash_type; /** Non trajectory blocks come before the first frame set block */ typedef enum {TNG_NON_TRAJECTORY_BLOCK, TNG_TRAJECTORY_BLOCK} tng_block_type; /** @defgroup def1 Standard non-trajectory blocks * Block IDs of standard non-trajectory blocks. * @{ */ #define TNG_GENERAL_INFO 0x0000000000000000LL #define TNG_MOLECULES 0x0000000000000001LL #define TNG_TRAJECTORY_FRAME_SET 0x0000000000000002LL #define TNG_PARTICLE_MAPPING 0x0000000000000003LL /** @} */ /** @defgroup def2 Standard trajectory blocks * Block IDs of standard trajectory blocks. Box shape and partial charges can * be either trajectory blocks or non-trajectory blocks * @{ */ #define TNG_TRAJ_BOX_SHAPE 0x0000000010000000LL #define TNG_TRAJ_POSITIONS 0x0000000010000001LL #define TNG_TRAJ_VELOCITIES 0x0000000010000002LL #define TNG_TRAJ_FORCES 0x0000000010000003LL #define TNG_TRAJ_PARTIAL_CHARGES 0x0000000010000004LL #define TNG_TRAJ_FORMAL_CHARGES 0x0000000010000005LL #define TNG_TRAJ_B_FACTORS 0x0000000010000006LL #define TNG_TRAJ_ANISOTROPIC_B_FACTORS 0x0000000010000007LL #define TNG_TRAJ_OCCUPANCY 0x0000000010000008LL /** @} */ /** @defgroup def3 GROMACS data block IDs * Block IDs of data blocks specific to GROMACS. * @{ */ #define TNG_GMX_LAMBDA 0x1000000010000000LL #define TNG_GMX_ENERGY_ANGLE 0x1000000010000001LL #define TNG_GMX_ENERGY_RYCKAERT_BELL 0x1000000010000002LL #define TNG_GMX_ENERGY_LJ_14 0x1000000010000003LL #define TNG_GMX_ENERGY_COULOMB_14 0x1000000010000004LL #define TNG_GMX_ENERGY_LJ_(SR) 0x1000000010000005LL #define TNG_GMX_ENERGY_COULOMB_(SR) 0x1000000010000006LL #define TNG_GMX_ENERGY_COUL_RECIP 0x1000000010000007LL #define TNG_GMX_ENERGY_POTENTIAL 0x1000000010000008LL #define TNG_GMX_ENERGY_KINETIC_EN 0x1000000010000009LL #define TNG_GMX_ENERGY_TOTAL_ENERGY 0x1000000010000010LL #define TNG_GMX_ENERGY_TEMPERATURE 0x1000000010000011LL #define TNG_GMX_ENERGY_PRESSURE 0x1000000010000012LL #define TNG_GMX_ENERGY_CONSTR_RMSD 0x1000000010000013LL #define TNG_GMX_ENERGY_BOX_X 0x1000000010000014LL #define TNG_GMX_ENERGY_BOX_Y 0x1000000010000015LL #define TNG_GMX_ENERGY_BOX_Z 0x1000000010000016LL #define TNG_GMX_ENERGY_VOLUME 0x1000000010000017LL #define TNG_GMX_ENERGY_DENSITY 0x1000000010000018LL #define TNG_GMX_ENERGY_PV 0x1000000010000019LL #define TNG_GMX_ENERGY_ENTHALPY 0x1000000010000020LL #define TNG_GMX_ENERGY_VIR_XX 0x1000000010000021LL #define TNG_GMX_ENERGY_VIR_XY 0x1000000010000022LL #define TNG_GMX_ENERGY_VIR_XZ 0x1000000010000023LL #define TNG_GMX_ENERGY_VIR_YX 0x1000000010000024LL #define TNG_GMX_ENERGY_VIR_YY 0x1000000010000025LL #define TNG_GMX_ENERGY_VIR_YZ 0x1000000010000026LL #define TNG_GMX_ENERGY_VIR_ZX 0x1000000010000027LL #define TNG_GMX_ENERGY_VIR_ZY 0x1000000010000028LL #define TNG_GMX_ENERGY_VIR_ZZ 0x1000000010000029LL #define TNG_GMX_ENERGY_PRES_XX 0x1000000010000030LL #define TNG_GMX_ENERGY_PRES_XY 0x1000000010000031LL #define TNG_GMX_ENERGY_PRES_XZ 0x1000000010000032LL #define TNG_GMX_ENERGY_PRES_YX 0x1000000010000033LL #define TNG_GMX_ENERGY_PRES_YY 0x1000000010000034LL #define TNG_GMX_ENERGY_PRES_YZ 0x1000000010000035LL #define TNG_GMX_ENERGY_PRES_ZX 0x1000000010000036LL #define TNG_GMX_ENERGY_PRES_ZY 0x1000000010000037LL #define TNG_GMX_ENERGY_PRES_ZZ 0x1000000010000038LL #define TNG_GMX_ENERGY_SURFXSURFTEN 0x1000000010000039LL #define TNG_GMX_ENERGY_T_SYSTEM 0x1000000010000040LL #define TNG_GMX_ENERGY_LAMB_SYSTEM 0x1000000010000041LL #define TNG_GMX_SELECTION_GROUP_NAMES 0x1000000010000042LL #define TNG_GMX_ATOM_SELECTION_GROUP 0x1000000010000043LL /** @} */ /** Flag to specify if a data block contains data related to particles or not.*/ typedef enum {TNG_NON_PARTICLE_BLOCK_DATA, TNG_PARTICLE_BLOCK_DATA} tng_particle_dependency; typedef enum {TNG_FALSE, TNG_TRUE} tng_bool; /** Flag to specify if the number of atoms change throughout the trajectory or * if it is constant. */ typedef enum {TNG_CONSTANT_N_ATOMS, TNG_VARIABLE_N_ATOMS} tng_variable_n_atoms_flag; /** Return values of API functions. TNG_SUCCESS means that the operation * was successful. TNG_FAILURE means that the operation failed for some * reason, but it is possible to try to continue anyhow. TNG_CRITICAL * means that the error is irrecoverable. */ typedef enum {TNG_SUCCESS, TNG_FAILURE, TNG_CRITICAL} tng_function_status; /** If tng_hash_mode == TNG_USE_HASH md5 hashes will be written to output files * and when reading a file the md5 hashes of the contents will be compared to * those in the file (for each block) in order to ensure data integrity */ typedef enum {TNG_SKIP_HASH, TNG_USE_HASH} tng_hash_mode; /** Possible formats of data block contents */ typedef enum {TNG_CHAR_DATA, TNG_INT_DATA, TNG_FLOAT_DATA, TNG_DOUBLE_DATA} tng_data_type; struct tng_trajectory; struct tng_molecule; struct tng_chain; struct tng_residue; struct tng_atom; struct tng_bond; struct tng_gen_block; struct tng_particle_mapping; struct tng_trajectory_frame_set; struct tng_particle_data; struct tng_non_particle_data; /** Data can be either double, float, int or a string */ union data_values { double d; float f; int64_t i; char *c; }; #ifdef __cplusplus extern "C" { #endif /** @defgroup group1 Low-level API * These functions give detailed control of the TNG data management. Most * things can be done using the more convenient high-level API functions * instead. * @{ */ /** * @brief Setup a trajectory data container. * @param tng_data_p a pointer to memory to initialise as a trajectory. * @pre tng_data_p must not be pointing at a reserved memory block. * @details Memory is allocated during initialisation. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_trajectory_init (tng_trajectory_t *tng_data_p); /** * @brief Clean up a trajectory data container. * @param tng_data_p a pointer to the trajectory data to destroy. * @details All allocated memory in the data structure is freed, as well as * tng_data_p itself. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_trajectory_destroy (tng_trajectory_t *tng_data_p); /** * @brief Copy a trajectory data container (dest is setup as well). * @details This initialises dest and copies only what is absolute necessary for * parallel i/o. This can be used inside pragma omp for setting up a thread * local copy of src. It can be freed (using tng_trajectory_destroy) at the * end of the parallel block. * @param src the original trajectory. * @param dest_p a pointer to memory to initialise as a trajectory. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre tng_data_p must not be pointing at a reserved memory block. * @details Memory is allocated during initialisation. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_trajectory_init_from_src (tng_trajectory_t src, tng_trajectory_t *dest_p); /** * @brief Get the name of the input file. * @param tng_data the trajectory of which to get the input file name. * @param file_name the string to fill with the name of the input file, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for file_name. This includes \0 terminating character. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code file_name != 0 \endcode The pointer to the file name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_input_file_get (const tng_trajectory_t tng_data, char *file_name, const int max_len); /** * @brief Set the name of the input file. * @param tng_data the trajectory of which to set the input file name. * @param file_name the name of the input file. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code file_name != 0 \endcode The pointer to the file name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_input_file_set (tng_trajectory_t tng_data, const char *file_name); /** * @brief Get the name of the output file. * @param tng_data the trajectory of which to get the input file name. * @param file_name the string to fill with the name of the output file, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for file_name. This includes \0 terminating character. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code file_name != 0 \endcode The pointer to the file name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_output_file_get (const tng_trajectory_t tng_data, char *file_name, const int max_len); /** * @brief Set the name of the output file. * @param tng_data the trajectory of which to set the output file name. * @param file_name the name of the output file. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code file_name != 0 \endcode The pointer to the file name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_output_file_set (tng_trajectory_t tng_data, const char *file_name); /** * @brief Set the name of the output file for appending. The output file * will not be overwritten. * @param tng_data the trajectory of which to set the output file name. * @param file_name the name of the output file to append to. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code file_name != 0 \endcode The pointer to the file name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_output_append_file_set (tng_trajectory_t tng_data, const char *file_name); /** * @brief Get the endianness of the output file. * @param tng_data the trajectory of which to get the endianness of the current * output file. * @param endianness will contain the enumeration of the endianness. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code endianness != 0 \endcode The pointer to the endianness container * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness * could not be retrieved. */ tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_get (const tng_trajectory_t tng_data, tng_file_endianness *endianness); /** * @brief Set the endianness of the output file. * @param tng_data the trajectory of which to set the endianness of the current * output file. * @param endianness the enumeration of the endianness, can be either * TNG_BIG_ENDIAN (0) or TNG_LITTLE_ENDIAN (1). * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @details The endianness cannot be changed after file output has started. * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness * could not be set. */ tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_set (tng_trajectory_t tng_data, const tng_file_endianness endianness); /** * @brief Get the name of the program used when creating the trajectory. * @param tng_data the trajectory of which to get the program name. * @param name the string to fill with the name of the program, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for name. This includes \0 terminating character. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_first_program_name_get (const tng_trajectory_t tng_data, char *name, const int max_len); /** * @brief Set the name of the program used when creating the trajectory. * @param tng_data the trajectory of which to set the program name. * @param new_name is a string containing the wanted name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code new_name != 0 \endcode The pointer to the new_name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_first_program_name_set (tng_trajectory_t tng_data, const char *new_name); /** * @brief Get the name of the program used when last modifying the trajectory. * @param tng_data the trajectory of which to get the program name. * @param name the string to fill with the name of the program, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for name. This includes \0 terminating character. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_last_program_name_get (const tng_trajectory_t tng_data, char *name, const int max_len); /** * @brief Set the name of the program used when last modifying the trajectory. * @param tng_data the trajectory of which to set the program name. * @param new_name is a string containing the wanted name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code new_name != 0 \endcode The pointer to the new_name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_last_program_name_set (tng_trajectory_t tng_data, const char *new_name); /** * @brief Get the name of the user who created the trajectory. * @param tng_data the trajectory of which to get the user name. * @param name the string to fill with the name of the user, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for name. This includes \0 terminating character. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_first_user_name_get (const tng_trajectory_t tng_data, char *name, const int max_len); /** * @brief Set the name of the user who created the trajectory. * @param tng_data the trajectory of which to set the user name. * @param new_name is a string containing the wanted name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code new_name != 0 \endcode The pointer to the new_name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_first_user_name_set (tng_trajectory_t tng_data, const char *new_name); /** * @brief Get the name of the user who last modified the trajectory. * @param tng_data the trajectory of which to get the user name. * @param name the string to fill with the name of the user, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for name. This includes \0 terminating character. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_last_user_name_get (const tng_trajectory_t tng_data, char *name, const int max_len); /** * @brief Set the name of the user who last modified the trajectory. * @param tng_data the trajectory of which to set the user name. * @param new_name is a string containing the wanted name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code new_name != 0 \endcode The pointer to the new_name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_last_user_name_set (tng_trajectory_t tng_data, const char *new_name); /** * @brief Get the name of the computer used when creating the trajectory. * @param tng_data the trajectory of which to get the computer name. * @param name the string to fill with the name of the computer, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for name. This includes \0 terminating character. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_get (const tng_trajectory_t tng_data, char *name, const int max_len); /** * @brief Set the name of the computer used when creating the trajectory. * @param tng_data the trajectory of which to set the computer name. * @param new_name is a string containing the wanted name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code new_name != 0 \endcode The pointer to the new_name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_set (tng_trajectory_t tng_data, const char *new_name); /** * @brief Get the name of the computer used when last modifying the trajectory. * @param tng_data the trajectory of which to get the computer name. * @param name the string to fill with the name of the computer, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for name. This includes \0 terminating character. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_get (const tng_trajectory_t tng_data, char *name, const int max_len); /** * @brief Set the name of the computer used when last modifying the trajectory. * @param tng_data the trajectory of which to set the computer name. * @param new_name is a string containing the wanted name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code new_name != 0 \endcode The pointer to the new_name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_set (tng_trajectory_t tng_data, const char *new_name); /** * @brief Get the pgp_signature of the user creating the trajectory. * @param tng_data the trajectory of which to get the computer name. * @param signature the string to fill with the signature, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for name. This includes \0 terminating character. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code signature != 0 \endcode The pointer to the signature * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_first_signature_get (const tng_trajectory_t tng_data, char *signature, const int max_len); /** * @brief Set the pgp_signature of the user creating the trajectory. * @param tng_data the trajectory of which to set the computer name. * @param signature is a string containing the pgp_signature. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code signature != 0 \endcode The pointer to the signature * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_first_signature_set (tng_trajectory_t tng_data, const char *signature); /** * @brief Get the pgp_signature of the user last modifying the trajectory. * @param tng_data the trajectory of which to get the computer name. * @param signature the string to fill with the signature, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for name. This includes \0 terminating character. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code signature != 0 \endcode The pointer to the signature * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_last_signature_get (const tng_trajectory_t tng_data, char *signature, const int max_len); /** * @brief Set the pgp_signature of the user last modifying the trajectory. * @param tng_data the trajectory of which to set the computer name. * @param signature is a string containing the pgp_signature. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code signature != 0 \endcode The pointer to the signature * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_last_signature_set (tng_trajectory_t tng_data, const char *signature); /** * @brief Get the name of the forcefield used in the trajectory. * @param tng_data the trajectory of which to get the forcefield name. * @param name the string to fill with the name of the forcefield, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for name. This includes \0 terminating character. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_get (const tng_trajectory_t tng_data, char *name, const int max_len); /** * @brief Set the name of the forcefield used in the trajectory. * @param tng_data the trajectory of which to set the forcefield name. * @param new_name is a string containing the wanted name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code new_name != 0 \endcode The pointer to the new_name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_set (tng_trajectory_t tng_data, const char *new_name); /** * @brief Get the medium stride length of the trajectory. * @param tng_data is the trajectory from which to get the stride length. * @param len is pointing to a value set to the stride length. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_get (const tng_trajectory_t tng_data, int64_t *len); /** * @brief Set the medium stride length of the trajectory. * @param tng_data is the trajectory of which to set the stride length. * @param len is the wanted medium stride length. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred. */ tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_set (tng_trajectory_t tng_data, const int64_t len); /** * @brief Get the long stride length of the trajectory. * @param tng_data is the trajectory from which to get the stride length. * @param len is pointing to a value set to the stride length. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_get (const tng_trajectory_t tng_data, int64_t *len); /** * @brief Set the long stride length of the trajectory. * @param tng_data is the trajectory of which to set the stride length. * @param len is the wanted long stride length. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred. */ tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_set (tng_trajectory_t tng_data, const int64_t len); /** * @brief Get the current time per frame of the trajectory. * @param tng_data is the trajectory from which to get the time per frame. * @param time is pointing to a value set to the time per frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code time != 0 \endcode The pointer to time must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_get (const tng_trajectory_t tng_data, double *time); /** * @brief Set the time per frame of the trajectory. * @param tng_data is the trajectory of which to set the time per frame. * @param time is the new time per frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code time > 0 \endcode The time per frame must be >= 0. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred. */ tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_set (tng_trajectory_t tng_data, const double time); /** * @brief Get the length of the input file. * @param tng_data is the trajectory from which to get the input file length. * @param len is pointing to a value set to the file length. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_input_file_len_get (const tng_trajectory_t tng_data, int64_t *len); /** * @brief Get the number of frames in the trajectory * @param tng_data is the trajectory of which to get the number of frames. * @param n is pointing to a value set to the number of frames. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code tng_data->input_file != 0 \endcode An input file must be open * to find the next frame set. * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (could not find last frame set). */ tng_function_status DECLSPECDLLEXPORT tng_num_frames_get (const tng_trajectory_t tng_data, int64_t *n); /** * @brief Get the precision of lossy compression. * @param tng_data is the trajectory of which to get the compression precision. * @param precision will be pointing to the retrieved compression precision. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @details A compression precision of 0.001 (the default) means that the * compressed values are accurate to the third decimal. This function does * not check actual precision of compressed data, but just returns what has * previously been set using tng_compression_precision_set(). * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_compression_precision_get (const tng_trajectory_t tng_data, double *precision); /** * @brief Set the precision of lossy compression. * @param tng_data is the trajectory of which to set the compression precision. * @param precision is the new compression precision. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @details A compression precision of 0.001 (the default) means that the * compressed values are accurate to the third decimal. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_compression_precision_set (tng_trajectory_t tng_data, const double precision); /** * @brief Set the number of particles, in the case no molecular system is used. * @param tng_data is the trajectory of which to get the number of particles. * @param n is the number of particles to use. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @details When creating a molecular system the number of particles are set * automatically. This should only be used when there is no molecular system * specified or if the number of atoms needs to be overridden for some reason. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_implicit_num_particles_set (tng_trajectory_t tng_data, const int64_t n); /** * @brief Get the current number of particles. * @param tng_data is the trajectory from which to get the number of particles. * @param n is pointing to a value set to the number of particles. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. * @details If variable number of particles are used this function will return * the number of particles in the current frame set. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_num_particles_get (const tng_trajectory_t tng_data, int64_t *n); /** * @brief Get if the number of particle can be varied during the simulation. * @param tng_data is the trajectory from which to get the number of particles. * @param variable is pointing to a value set to TNG_CONSTANT_N_ATOMS if the * number of particles cannot change or TNG_VARIABLE_N_ATOMS if the number of * particles can change. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code variable != 0 \endcode The pointer to variable must not be * a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_num_particles_variable_get (const tng_trajectory_t tng_data, char *variable); /** * @brief Get the number of molecule types (length of tng_data->molecules). * @param tng_data is the trajectory from which to get the number of molecules. * @param n is pointing to a value set to the number of molecule types. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_num_molecule_types_get (const tng_trajectory_t tng_data, int64_t *n); /** * @brief Get the current total number of molecules. * @param tng_data is the trajectory from which to get the number of molecules. * @param n is pointing to a value set to the number of molecules. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. * @details If variable number of particles are used this function will return * the total number of molecules in the current frame set. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_num_molecules_get (const tng_trajectory_t tng_data, int64_t *n); /** @brief Get the list of the count of each molecule. * @param tng_data is the trajectory from which to get the molecule count list. * @param mol_cnt_list is a list of the count of each molecule in the * mol system. This is a pointer to the list in the TNG container, which * means that it should be handled carefully, e.g. not freed. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful or TNG_FAILURE(1) if the list of * molecule counts was not valid. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_list_get (const tng_trajectory_t tng_data, int64_t **mol_cnt_list); /** * @brief Get the exponent used for distances in the trajectory. * @param tng_data is the trajectory from which to get the information. * @param exp is pointing to a value set to the distance unit exponent. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code exp != 0 \endcode The pointer to exp must not be a NULL pointer. * @details Example: If the distances are specified in nm (default) exp is -9. * If the distances are specified in Å exp is -10. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_get (const tng_trajectory_t tng_data, int64_t *exp); /** * @brief Set the exponent used for distances in the trajectory. * @param tng_data is the trajectory of which to set the unit exponent. * @param exp is the distance unit exponent to use. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @details Example: If the distances are specified in nm (default) exp is -9. * If the distances are specified in Å exp is -10. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_set (const tng_trajectory_t tng_data, const int64_t exp); /** * @brief Get the number of frames per frame set. * @param tng_data is the trajectory from which to get the number of frames * per frame set. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. * @param n is pointing to a value set to the number of frames per frame set. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_get (const tng_trajectory_t tng_data, int64_t *n); /** * @brief Set the number of frames per frame set. * @param tng_data is the trajectory of which to set the number of frames * per frame set. * @param n is the number of frames per frame set. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @details This does not affect already existing frame sets. For * consistency the number of frames per frame set should be set * betfore creating any frame sets. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_set (const tng_trajectory_t tng_data, const int64_t n); /** * @brief Get the number of frame sets. * @details This updates tng_data->n_trajectory_frame_sets before returning it. * @param tng_data is the trajectory from which to get the number of frame sets. * @param n is pointing to a value set to the number of frame sets. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_num_frame_sets_get (const tng_trajectory_t tng_data, int64_t *n); /** * @brief Get the current trajectory frame set. * @param tng_data is the trajectory from which to get the frame set. * @param frame_set_p will be set to point at the memory position of * the found frame set. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_current_frame_set_get (const tng_trajectory_t tng_data, tng_trajectory_frame_set_t *frame_set_p); /** * @brief Find the requested frame set number. * @param tng_data is the trajectory from which to get the frame set. * @param nr is the frame set number to search for. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code nr >= 0 \endcode The frame set number (nr) must be >= 0. * @details tng_data->current_trajectory_frame_set will contain the * found trajectory if successful. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_nr_find (tng_trajectory_t tng_data, const int64_t nr); /** * @brief Find the frame set containing a specific frame. * @param tng_data is the trajectory from which to get the frame set. * @param frame is the frame number to search for. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame >= 0 \endcode The frame number must be >= 0. * @details tng_data->current_trajectory_frame_set will contain the * found trajectory if successful. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_of_frame_find (tng_trajectory_t tng_data, const int64_t frame); /** * @brief Get the file position of the next frame set in the input file. * @param tng_data is a trajectory data container. * @param frame_set is the frame set of which to get the position of the * following frame set. * @param pos is pointing to a value set to the file position. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_next_frame_set_file_pos_get (const tng_trajectory_t tng_data, const tng_trajectory_frame_set_t frame_set, int64_t *pos); /** * @brief Get the file position of the previous frame set in the input file. * @param tng_data is a trajectory data container. * @param frame_set is the frame set of which to get the position of the * previous frame set. * @param pos is pointing to a value set to the file position. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_prev_frame_set_file_pos_get (const tng_trajectory_t tng_data, const tng_trajectory_frame_set_t frame_set, int64_t *pos); /** * @brief Get the first and last frames of the frame set. * @param tng_data is a trajectory data container. * @param frame_set is the frame set of which to get the frame range. * @param first_frame is set to the first frame of the frame set. * @param last_frame is set to the last frame of the frame set. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code first_frame != 0 \endcode The pointer to first_frame must * not be a NULL pointer. * @pre \code last_frame != 0 \endcode The pointer to last_frame must * not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_frame_range_get (const tng_trajectory_t tng_data, const tng_trajectory_frame_set_t frame_set, int64_t *first_frame, int64_t *last_frame); /** * @brief Allocate memory for and setup a molecule container. * @param tng_data is a trajectory data container. * @param molecule_p is a pointer to molecule to allocate and initialise. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_alloc(const tng_trajectory_t tng_data, tng_molecule_t *molecule_p); /** * @brief Clean up a molecule container and free its allocated memory. * @param tng_data is a trajectory data container. * @param molecule_p is the molecule to destroy. * @details All allocated memory in the data structure is freed and also the memory * of the molecule itself. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_free(const tng_trajectory_t tng_data, tng_molecule_t *molecule_p); /** * @brief Setup a molecule container. * @param tng_data is a trajectory data container. * @param molecule is the molecule to initialise. Memory must be preallocated. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_init (const tng_trajectory_t tng_data, tng_molecule_t molecule); /** * @brief Clean up a molecule container. * @param tng_data is a trajectory data container. * @param molecule is the molecule to destroy. * @details All allocated memory in the data structure is freed, but not the * memory of molecule itself. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_destroy (const tng_trajectory_t tng_data, tng_molecule_t molecule); /** * @brief Add a molecule to the trajectory. * @param tng_data is the trajectory data container containing the block.. * @param name is a pointer to the string containing the name of the new molecule. * @param molecule is a pointer to the newly created molecule. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could * not be set properly or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_add (tng_trajectory_t tng_data, const char *name, tng_molecule_t *molecule); /** * @brief Add a molecule with a specific ID to the trajectory. * @param tng_data is the trajectory data container containing the block.. * @param name is a pointer to the string containing the name of the new molecule. * @param id is the ID of the created molecule. * @param molecule is a pointer to the newly created molecule. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could * not be set properly or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_w_id_add (tng_trajectory_t tng_data, const char *name, const int64_t id, tng_molecule_t *molecule); /** * @brief Add an existing molecule (from a molecule container) to the trajectory. * @param tng_data is the trajectory data container containing the block.. * @param molecule is a pointer to the molecule to add to the trajectory and will * afterwards point to the molecule in the trajectory. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_existing_add (tng_trajectory_t tng_data, tng_molecule_t *molecule); /** * @brief Get the name of a molecule. * @param tng_data the trajectory containing the molecule. * @param molecule the molecule of which to get the name. * @param name the string to fill with the name of the molecule, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for name. This includes \0 terminating character. * @pre \code molecule != 0 \endcode The molecule must not be NULL. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_molecule_name_get (const tng_trajectory_t tng_data, const tng_molecule_t molecule, char *name, const int max_len); /** * @brief Set the name of a molecule. * @param tng_data is the trajectory data container containing the molecule.. * @param molecule is the molecule to rename. * @param new_name is a string containing the wanted name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code new_name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_name_set (tng_trajectory_t tng_data, tng_molecule_t molecule, const char *new_name); /** * @brief Get the count of a molecule. * @param tng_data is the trajectory data container containing the molecule.. * @param molecule is the molecule of which to get the count. * @param cnt is a pointer to the variable to be populated with the count. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code cnt != 0 \endcode The pointer to the molecule count * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_get (const tng_trajectory_t tng_data, const tng_molecule_t molecule, int64_t *cnt); /** * @brief Set the count of a molecule. * @param tng_data is the trajectory data container containing the molecule.. * @param molecule is the molecule of which to set the count. * @param cnt is the number of instances of this molecule. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_set (tng_trajectory_t tng_data, tng_molecule_t molecule, const int64_t cnt); /** * @brief Find a molecule. * @param tng_data is the trajectory data container containing the molecule. * @param name is a string containing the name of the molecule. If name is empty * only id will be used for finding the molecule. * @param id is the id of the molecule to look for. If id is -1 only the name of * the molecule will be used for finding the molecule. * @param molecule is a pointer to the molecule if it was found - otherwise 0. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the * molecule is not found. * @details If name is an empty string and id == -1 the first residue will * be found. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_find (tng_trajectory_t tng_data, const char *name, int64_t id, tng_molecule_t *molecule); /** * @brief Retrieve the molecule with specified index in the list of molecules. * @param tng_data is the trajectory data container containing the molecule. * @param index is the index (in tng_data->molecules) of the molecule to return * @param molecule is a pointer to the molecule if it was found - otherwise 0. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the * molecule is not found. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_of_index_get (tng_trajectory_t tng_data, int64_t index, tng_molecule_t *molecule); /** * @brief Copy all molecules and the molecule counts from one TNG trajectory * to another. * @param tng_data_src is the source trajectory containing the molecular * system to copy. * @param tng_data_dest is the destination trajectory. * @pre \code tng_data_src != 0 \endcode The trajectory container (tng_data_src) * must be initialised before using it. * @pre \code tng_data_dest != 0 \endcode The trajectory container (tng_data_dest) * must be initialised before using it. * @details The molecular system in tng_data_dest will be overwritten. * @return TNG_SUCCESS(0) if the copying is successful, TNG_FAILURE if a minor * error has occured or TNG_CRITICAL(2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_system_copy(tng_trajectory_t tng_data_src, tng_trajectory_t tng_data_dest); /** * @brief Get the number of chains in a molecule. * @param tng_data is the trajectory containing the molecule. * @param molecule is the molecule of which to get the number of chains. * @param n is pointing to a value set to the number of chains. * @pre \code molecule != 0 \endcode The molecule must not be NULL. * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_num_chains_get (const tng_trajectory_t tng_data, const tng_molecule_t molecule, int64_t *n); /** * @brief Retrieve the chain of a molecule with specified index in the list * of chains. * @param tng_data is the trajectory data container containing the molecule. * @param index is the index (in molecule->chains) of the chain to return * @param molecule is the molecule from which to get the chain. * @param chain is a pointer to the chain if it was found - otherwise 0. * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. * @pre \code chain != 0 \endcode chain must not be a NULL pointer. * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the * chain is not found. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_of_index_get (tng_trajectory_t tng_data, tng_molecule_t molecule, int64_t index, tng_chain_t *chain); /** * @brief Get the number of residues in a molecule. * @param tng_data is the trajectory containing the molecule. * @param molecule is the molecule of which to get the number residues. * @param n is pointing to a value set to the number of residues. * @pre \code molecule != 0 \endcode The molecule must not be NULL. * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_num_residues_get (const tng_trajectory_t tng_data, const tng_molecule_t molecule, int64_t *n); /** * @brief Retrieve the residue of a molecule with specified index in the list * of chains. * @param tng_data is the trajectory data container containing the molecule. * @param index is the index (in molecule->residues) of the residue to return * @param molecule is the molecule from which to get the residue. * @param residue is a pointer to the residue if it was found - otherwise 0. * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. * @pre \code residue != 0 \endcode residue must not be a NULL pointer. * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the * residue is not found. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_residue_of_index_get (const tng_trajectory_t tng_data, const tng_molecule_t molecule, const int64_t index, tng_residue_t *residue); /** * @brief Get the number of atoms in a molecule. * @param tng_data is the trajectory containing the molecule. * @param molecule is the molecule of which to get the number of atoms. * @param n is pointing to a value set to the number of atoms. * @pre \code molecule != 0 \endcode The molecule must not be NULL. * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_num_atoms_get (const tng_trajectory_t tng_data, const tng_molecule_t molecule, int64_t *n); /** * @brief Retrieve the atom of a molecule with specified index in the list * of atoms. * @param tng_data is the trajectory data container containing the molecule. * @param index is the index (in molecule->atoms) of the atom to return * @param molecule is the molecule from which to get the atom. * @param atom is a pointer to the atom if it was found - otherwise 0. * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. * @pre \code atom != 0 \endcode atom must not be a NULL pointer. * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the * atom is not found. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_of_index_get (const tng_trajectory_t tng_data, const tng_molecule_t molecule, const int64_t index, tng_atom_t *atom); /** * @brief Find a chain in a molecule. * @param tng_data is the trajectory data container containing the molecule. * @param molecule is the molecule in which to search for the chain. * @param name is a string containing the name of the chain. If name is empty * only id will be used for finding the chain. * @param id is the id of the chain to look for. If id is -1 only the name of * the chain will be used for finding the chain. * @param chain is a pointer to the chain if it was found - otherwise 0. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the * chain is not found. * @details If name is an empty string and id == -1 the first residue will * be found. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_find (tng_trajectory_t tng_data, tng_molecule_t molecule, const char *name, int64_t id, tng_chain_t *chain); /** * @brief Add a chain to a molecule. * @param tng_data is the trajectory data container containing the molecule.. * @param molecule is the molecule to add a chain to. * @param name is a string containing the name of the chain. * @param chain is a pointer to the newly created chain. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could * not be set properly or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_add (tng_trajectory_t tng_data, tng_molecule_t molecule, const char *name, tng_chain_t *chain); /** * @brief Add a chain with a specific id to a molecule. * @param tng_data is the trajectory data container containing the molecule.. * @param molecule is the molecule to add a chain to. * @param name is a string containing the name of the chain. * @param id is the ID of the created chain. * @param chain is a pointer to the newly created chain. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could * not be set properly or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_w_id_add (tng_trajectory_t tng_data, tng_molecule_t molecule, const char *name, const int64_t id, tng_chain_t *chain); /** * @brief Add a bond between two atoms to a molecule. * @param tng_data is the trajectory data container containing the molecule. * @param molecule is the molecule containing the atoms to connect. * @param from_atom_id is the id of one of the two atoms in the bond. * @param to_atom_id is the id of the other atom in the bond. * @param bond is a pointer to the newly created bond. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (!) if a minor error * has occured or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_bond_add (const tng_trajectory_t tng_data, tng_molecule_t molecule, const int64_t from_atom_id, const int64_t to_atom_id, tng_bond_t *bond); /** * @brief Find an atom in a molecule. * @param tng_data is the trajectory data container containing the molecule. * @param molecule is the molecule in which to search for the atom. * @param name is a string containing the name of the atom. If name is an * empty string only id will be used for searching. * @param id is the id of the atom to find. If id == -1 the first atom * that matches the specified name will be found. * @param atom is a pointer to the atom if it was found - otherwise 0. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the * atom is not found. * @details If name is an empty string and id == -1 the first residue will * be found. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_find (tng_trajectory_t tng_data, tng_molecule_t molecule, const char *name, int64_t id, tng_atom_t *atom); /** * @brief Get the name of a chain. * @param tng_data the trajectory containing the chain. * @param chain the chain of which to get the name. * @param name the string to fill with the name of the chain, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for name. This includes \0 terminating character. * @pre \code chain != 0 \endcode The chain must not be NULL. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_chain_name_get (const tng_trajectory_t tng_data, const tng_chain_t chain, char *name, const int max_len); /** * @brief Set the name of a chain. * @param tng_data is the trajectory data container containing the atom.. * @param chain is the chain to rename. * @param new_name is a string containing the wanted name. * @pre \code new_name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_chain_name_set (tng_trajectory_t tng_data, tng_chain_t chain, const char *new_name); /** * @brief Get the number of residues in a molecule chain. * @param tng_data is the trajectory containing the chain. * @param chain is the chain of which to get the number of residues. * @param n is pointing to a value set to the number of residues. * @pre \code chain != 0 \endcode The chain must not be NULL. * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_chain_num_residues_get (const tng_trajectory_t tng_data, const tng_chain_t chain, int64_t *n); /** * @brief Retrieve the residue of a chain with specified index in the list * of residues. * @param tng_data is the trajectory data container containing the chain. * @param index is the index (in chain->residues) of the residue to return * @param chain is the chain from which to get the residue. * @param residue is a pointer to the residue if it was found - otherwise 0. * @pre \code chain != 0 \endcode chain must not be a NULL pointer. * @pre \code residue != 0 \endcode residue must not be a NULL pointer. * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the * residue is not found. */ tng_function_status DECLSPECDLLEXPORT tng_chain_residue_of_index_get (const tng_trajectory_t tng_data, const tng_chain_t chain, const int64_t index, tng_residue_t *residue); /** * @brief Find a residue in a chain. * @param tng_data is the trajectory data container containing the chain. * @param chain is the chain in which to search for the residue. * @param name is a string containing the name of the residue. If name is an * empty string only id will be used for searching. * @param id is the id of the residue to find. If id == -1 the first residue * that matches the specified name will be found. * @param residue is a pointer to the residue if it was found - otherwise 0. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the * residue is not found. * @details If name is an empty string and id == -1 the first residue will * be found. */ tng_function_status DECLSPECDLLEXPORT tng_chain_residue_find (tng_trajectory_t tng_data, tng_chain_t chain, const char *name, int64_t id, tng_residue_t *residue); /** * @brief Add a residue to a chain. * @param tng_data is the trajectory data container containing the chain.. * @param chain is the chain to add a residue to. * @param name is a string containing the name of the residue. * @param residue is a pointer to the newly created residue. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could * not be set properly or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_chain_residue_add (tng_trajectory_t tng_data, tng_chain_t chain, const char *name, tng_residue_t *residue); /** * @brief Add a residue with a specific ID to a chain. * @param tng_data is the trajectory data container containing the chain.. * @param chain is the chain to add a residue to. * @param name is a string containing the name of the residue. * @param id is the ID of the created residue. * @param residue is a pointer to the newly created residue. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could * not be set properly or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_chain_residue_w_id_add (tng_trajectory_t tng_data, tng_chain_t chain, const char *name, const int64_t id, tng_residue_t *residue); /** * @brief Get the name of a residue. * @param tng_data the trajectory containing the residue. * @param residue the residue of which to get the name. * @param name the string to fill with the name of the residue, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for name. This includes \0 terminating character. * @pre \code residue != 0 \endcode The residue must not be NULL. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_residue_name_get (const tng_trajectory_t tng_data, const tng_residue_t residue, char *name, const int max_len); /** * @brief Set the name of a residue. * @param tng_data is the trajectory data container containing the residue. * @param residue is the residue to rename. * @param new_name is a string containing the wanted name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code new_name != 0 \endcode The new name to set (new_name) must * not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_residue_name_set (tng_trajectory_t tng_data, tng_residue_t residue, const char *new_name); /** * @brief Get the number of atoms in a residue. * @param tng_data is the trajectory containing the residue. * @param residue is the residue of which to get the number atoms. * @param n is pointing to a value set to the number of atoms. * @pre \code residue != 0 \endcode The residue must not be NULL. * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_residue_num_atoms_get (const tng_trajectory_t tng_data, const tng_residue_t residue, int64_t *n); /** * @brief Retrieve the atom of a residue with specified index in the list * of atoms. * @param tng_data is the trajectory data container containing the residue. * @param index is the index (in residue->atoms) of the atom to return * @param residue is the residue from which to get the atom. * @param atom is a pointer to the atom if it was found - otherwise 0. * @pre \code residue != 0 \endcode residue must not be a NULL pointer. * @pre \code atom != 0 \endcode atom must not be a NULL pointer. * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the * atom is not found. */ tng_function_status DECLSPECDLLEXPORT tng_residue_atom_of_index_get (const tng_trajectory_t tng_data, const tng_residue_t residue, const int64_t index, tng_atom_t *atom); /** * @brief Add an atom to a residue. * @param tng_data is the trajectory containing the residue. * @param residue is the residue to add an atom to. * @param atom_name is a string containing the name of the atom. * @param atom_type is a string containing the atom type of the atom. * @param atom is a pointer to the newly created atom. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code atom_name != 0 \endcode The pointer to the atom name string * must not be a NULL pointer. * @pre \code atom_type != 0 \endcode The pointer to the atom_type string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could * not be set properly or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_residue_atom_add (tng_trajectory_t tng_data, tng_residue_t residue, const char *atom_name, const char *atom_type, tng_atom_t *atom); /** * @brief Add an atom with a specific ID to a residue. * @param tng_data is the trajectory containing the residue. * @param residue is the residue to add an atom to. * @param atom_name is a string containing the name of the atom. * @param atom_type is a string containing the atom type of the atom. * @param id is the ID of the created atom. * @param atom is a pointer to the newly created atom. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code atom_name != 0 \endcode The pointer to the atom name string * must not be a NULL pointer. * @pre \code atom_type != 0 \endcode The pointer to the atom_type string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could * not be set properly or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_residue_atom_w_id_add (tng_trajectory_t tng_data, tng_residue_t residue, const char *atom_name, const char *atom_type, const int64_t id, tng_atom_t *atom); /** * @brief Get the residue of an atom. * @param tng_data the trajectory containing the atom. * @param atom the atom of which to get the name. * @param residue is set to the residue of the atom. * @pre \code atom != 0 \endcode The atom must not be NULL. * @return TNG_SUCCESS (0) if successful. */ tng_function_status tng_atom_residue_get(const tng_trajectory_t tng_data, const tng_atom_t atom, tng_residue_t *residue); /** * @brief Get the name of an atom. * @param tng_data the trajectory containing the atom. * @param atom the atom of which to get the name. * @param name the string to fill with the name of the atom, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for name. This includes \0 terminating character. * @pre \code atom != 0 \endcode The atom must not be NULL. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_atom_name_get (const tng_trajectory_t tng_data, const tng_atom_t atom, char *name, const int max_len); /** * @brief Set the name of an atom. * @param tng_data is the trajectory data container containing the atom. * @param atom is the atom to rename. * @param new_name is a string containing the wanted name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code new_name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_atom_name_set (tng_trajectory_t tng_data, tng_atom_t atom, const char *new_name); /** * @brief Get the type of an atom. * @param tng_data the trajectory containing the atom. * @param atom the atom of which to get the type. * @param type the string to fill with the type of the atom, * memory must be allocated before. * @param max_len maximum char length of the string, i.e. how much memory has * been reserved for type. This includes \0 terminating character. * @pre \code atom != 0 \endcode The atom must not be NULL. * @pre \code type != 0 \endcode The pointer to the type string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred (source string longer than destination string). */ tng_function_status DECLSPECDLLEXPORT tng_atom_type_get (const tng_trajectory_t tng_data, const tng_atom_t atom, char *type, const int max_len); /** * @brief Set the atom type of an atom. * @param tng_data is the trajectory data container containing the atom. * @param atom is the atom to change. * @param new_type is a string containing the atom type. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code new_type != 0 \endcode The pointer to the atom type string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_atom_type_set (tng_trajectory_t tng_data, tng_atom_t atom, const char *new_type); /** * @brief Get the molecule name of real particle number (number in mol system). * @param tng_data is the trajectory data container containing the atom. * @param nr is the real number of the particle in the molecular system. * @param name is a string, which is set to the name of the molecule. Memory * must be reserved beforehand. * @param max_len is the maximum length of name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_name_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, char *name, int max_len); /** * @brief Get the molecule id of real particle number (number in mol system). * @param tng_data is the trajectory data container containing the atom. * @param nr is the real number of the particle in the molecular system. * @param id is will be set to the id of the molecule. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molecule_id_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, int64_t *id); /** * @brief Get the bonds of the current molecular system. * @param tng_data is the trajectory data container containing the molecular * system. * @param n_bonds is set to the number of bonds in the molecular system and * thereby also the lengths of the two lists: from_atoms and to_atoms. * @param from_atoms is a list (memory reserved by this function) of atoms * (number of atom in mol system) in bonds. * @param to_atoms is a list (memory reserved by this function) of atoms * (number of atom in mol system) in bonds. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n_bonds != 0 \endcode The pointer to n_bonds must not be a * NULL pointer. * @pre \code from_atoms != 0 \endcode The pointer to from_atoms must not * be a NULL pointer. * @pre \code to_atoms != 0 \endcode The pointer to to_atoms must not * be a NULL pointer. * @details The two lists of atoms use the same index, i.e. from_atoms[0] * and to_atoms[0] are linked with a bond. Since memory is reserved in * this function it must be freed afterwards. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_molsystem_bonds_get (const tng_trajectory_t tng_data, int64_t *n_bonds, int64_t **from_atoms, int64_t **to_atoms); /** * @brief Get the chain name of real particle number (number in mol system). * @param tng_data is the trajectory data container containing the atom. * @param nr is the real number of the particle in the molecular system. * @param name is a string, which is set to the name of the chain. Memory * must be reserved beforehand. * @param max_len is the maximum length of name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_chain_name_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, char *name, int max_len); /** * @brief Get the residue name of real particle number (number in mol system). * @param tng_data is the trajectory data container containing the atom. * @param nr is the real number of the particle in the molecular system. * @param name is a string, which is set to the name of the residue. Memory * must be reserved beforehand. * @param max_len is the maximum length of name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_residue_name_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, char *name, int max_len); /** * @brief Get the residue id (local to molecule) of real particle number * (number in mol system). * @param tng_data is the trajectory data container containing the atom. * @param nr is the real number of the particle in the molecular system. * @param id is a pointer to the variable, which will be set to the ID. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_residue_id_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, int64_t *id); /** * @brief Get the residue id (based on other molecules and molecule counts) * of real particle number (number in mol system). * @param tng_data is the trajectory data container containing the atom. * @param nr is the real number of the particle in the molecular system. * @param id is a pointer to the variable, which will be set to the ID. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_global_residue_id_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, int64_t *id); /** * @brief Get the atom name of real particle number (number in mol system). * @param tng_data is the trajectory data container containing the atom. * @param nr is the real number of the particle in the molecular system. * @param name is a string, which is set to the name of the atom. Memory * must be reserved beforehand. * @param max_len is the maximum length of name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_atom_name_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, char *name, int max_len); /** * @brief Get the atom type of real particle number (number in mol system). * @param tng_data is the trajectory data container containing the atom. * @param nr is the real number of the particle in the molecular system. * @param type is a string, which is set to the type of the atom. Memory * must be reserved beforehand. * @param max_len is the maximum length of type. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code type != 0 \endcode The pointer to the type string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_atom_type_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, char *type, int max_len); /** * @brief Add a particle mapping table. * @details Each particle mapping table will be written as a separate block, * followed by the data blocks for the corresponding particles. In most cases * there is one particle mapping block for each thread writing the trajectory. * @param tng_data is the trajectory, with the frame set to which to add * the mapping block. * @details The mapping information is added to the currently active frame set * of tng_data * @param num_first_particle is the first particle number of this mapping * block. * @param n_particles is the number of particles in this mapping block. * @param mapping_table is a list of the real particle numbers (i.e. the numbers * used in the molecular system). The list is n_particles long. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @details mapping_table[0] is the real particle number of the first particle * in the following data blocks. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_particle_mapping_add (tng_trajectory_t tng_data, const int64_t num_first_particle, const int64_t n_particles, const int64_t *mapping_table); /** * @brief Remove all particle mappings (in memory) from the current frame set. * @details Clears the currently setup particle mappings of the current frame * set. * @param tng_data is the trajectory, with the frame set of which to clear * all particle mappings. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_particle_mapping_free (tng_trajectory_t tng_data); /** * @brief Read the header blocks from the input_file of tng_data. * @details The trajectory blocks must be read separately and iteratively in chunks * to fit in memory. * @param tng_data is a trajectory data container. * @details tng_data->input_file_path specifies * which file to read from. If the file (input_file) is not open it will be * opened. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be * compared to the md5 hash of the read contents to ensure valid data. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_file_headers_read (tng_trajectory_t tng_data, const char hash_mode); /** * @brief Write the header blocks to the output_file of tng_data. * @details The trajectory blocks must be written separately and iteratively in chunks * to fit in memory. * @param tng_data is a trajectory data container. * @details tng_data->output_file_path * specifies which file to write to. If the file (output_file) is not open it * will be opened. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major * error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_file_headers_write (tng_trajectory_t tng_data, const char hash_mode); /** * @brief Read one (the next) block (of any kind) from the input_file of tng_data. * @param tng_data is a trajectory data container. * @details tng_data->input_file_path specifies * which file to read from. If the file (input_file) is not open it will be * opened. * @param block_data is a pointer to the struct which will be populated with the * data. * @details If block_data->input_file_pos > 0 it is the position from where the * reading starts otherwise it starts from the current position. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be * compared to the md5 hash of the read contents to ensure valid data. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code block != 0 \endcode The block container (block) must be * initialised before using it. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_block_read_next (tng_trajectory_t tng_data, tng_gen_block_t block_data, const char hash_mode); /** * @brief Read one frame set, including all particle mapping blocks and data * blocks, starting from the current file position. * @param tng_data is a trajectory data container. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be * compared to the md5 hash of the read contents to ensure valid data. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_read (tng_trajectory_t tng_data, const char hash_mode); /** * @brief Read data from the current frame set from the input_file. Only read * particle mapping and data blocks matching the specified block_id. * @param tng_data is a trajectory data container. * @details tng_data->input_file_path specifies * which file to read from. If the file (input_file) is not open it will be * opened. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be * compared to the md5 hash of the read contents to ensure valid data. * @param block_id is the ID of the data block to read from file. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_current_only_data_from_block_id (tng_trajectory_t tng_data, const char hash_mode, const int64_t block_id); /** * @brief Read one (the next) frame set, including particle mapping and related data blocks * from the input_file of tng_data. * @param tng_data is a trajectory data container. * @details tng_data->input_file_path specifies * which file to read from. If the file (input_file) is not open it will be * opened. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be * compared to the md5 hash of the read contents to ensure valid data. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next (tng_trajectory_t tng_data, const char hash_mode); /** * @brief Read one (the next) frame set, including particle mapping and data blocks with a * specific block id from the input_file of tng_data. * @param tng_data is a trajectory data container. * @details tng_data->input_file_path specifies * which file to read from. If the file (input_file) is not open it will be * opened. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be * compared to the md5 hash of the read contents to ensure valid data. * @param block_id is the ID number of the blocks that should be read from file. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next_only_data_from_block_id (tng_trajectory_t tng_data, const char hash_mode, const int64_t block_id); /** * @brief Write one frame set, including mapping and related data blocks * to the output_file of tng_data. * @param tng_data is a trajectory data container. * @details tng_data->output_file_path specifies * which file to write to. If the file (output_file) is not open it will be * opened. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_write (tng_trajectory_t tng_data, const char hash_mode); /** * @brief Write one frame set even if it does not have as many frames as * expected. The function also writes mapping and related data blocks * to the output_file of tng_data. * @param tng_data is a trajectory data container. * @details tng_data->output_file_path specifies * which file to write to. If the file (output_file) is not open it will be * opened. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @details The number of frames in the frame set is set to the number of * frames of the data blocks before writing it to disk. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_premature_write (tng_trajectory_t tng_data, const char hash_mode); /** * @brief Create and initialise a frame set. * @details Particle mappings are retained from previous frame set (if any). * To explicitly clear particle mappings use tng_frame_set_particle_mapping_free(). * @param tng_data is the trajectory data container in which to add the frame * set. * @param first_frame is the first frame of the frame set. * @param n_frames is the number of frames in the frame set. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code first_frame >= 0 \endcode The first frame must not be negative. * @pre \code n_frames >= 0 \endcode The number of frames must not be negative. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_new (tng_trajectory_t tng_data, const int64_t first_frame, const int64_t n_frames); /** * @brief Create and initialise a frame set with the time of the first frame * specified. * @param tng_data is the trajectory data container in which to add the frame * set. * @param first_frame is the first frame of the frame set. * @param n_frames is the number of frames in the frame set. * @param first_frame_time is the time stamp of the first frame (in seconds). * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code first_frame >= 0 \endcode The first frame must not be negative. * @pre \code n_frames >= 0 \endcode The number of frames must not be negative. * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame * must not be negative. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_with_time_new (tng_trajectory_t tng_data, const int64_t first_frame, const int64_t n_frames, const double first_frame_time); /** * @brief Set the time stamp of the first frame of the current frame set. * @param tng_data is the trajectory containing the frame set. * @param first_frame_time is the time stamp of the first frame in the * frame set. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame * must not be negative. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_frame_set_first_frame_time_set (tng_trajectory_t tng_data, const double first_frame_time); /** * @brief Read the number of the first frame of the next frame set. * @param tng_data is the trajectory containing the frame set. * @param frame is set to the frame number of the first frame in the * next frame set. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code tng_data->input_file != 0 \endcode An input file must be open * to find the next frame set. * @pre \code frame != 0 \endcode The pointer to the frame must not be a NULL * pointer. * @return TNG_SUCCESS(0) if successful, TNG_FAILURE(1) if there is no next * frame set or TNG_CRITICAL(2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_first_frame_nr_of_next_frame_set_get (const tng_trajectory_t tng_data, int64_t *frame); /** * @brief Add a non-particle dependent data block. * @param tng_data is the trajectory data container in which to add the data * block * @param id is the block ID of the block to add. * @param block_name is a descriptive name of the block to add * @param datatype is the datatype of the data in the block (e.g. int/float) * @param block_type_flag indicates if this is a non-trajectory block (added * directly to tng_data) or if it is a trajectory block (added to the * frame set) * @param n_frames is the number of frames of the data block (automatically * set to 1 if adding a non-trajectory data block) * @param n_values_per_frame is how many values a stored each frame (e.g. 9 * for a box shape block) * @param stride_length is how many frames are between each entry in the * data block * @param codec_id is the ID of the codec to compress the data. * @param new_data is an array of data values to add. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code block_name != 0 \endcode The pointer to the block name must * not be a NULL pointer. * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be * a positive integer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_data_block_add (tng_trajectory_t tng_data, const int64_t id, const char *block_name, const char datatype, const char block_type_flag, int64_t n_frames, const int64_t n_values_per_frame, int64_t stride_length, const int64_t codec_id, void *new_data); /** * @brief Add a particle dependent data block. * @param tng_data is the trajectory data container in which to add the data * block * @param id is the block ID of the block to add. * @param block_name is a descriptive name of the block to add * @param datatype is the datatype of the data in the block (e.g. int/float) * @param block_type_flag indicates if this is a non-trajectory block (added * directly to tng_data) or if it is a trajectory block (added to the * frame set) * @param n_frames is the number of frames of the data block (automatically * set to 1 if adding a non-trajectory data block) * @param n_values_per_frame is how many values a stored each frame (e.g. 9 * for a box shape block) * @param stride_length is how many frames are between each entry in the * data block * @param num_first_particle is the number of the first particle stored * in this data block * @param n_particles is the number of particles stored in this data block * @param codec_id is the ID of the codec to compress the data. * @param new_data is an array of data values to add. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code block_name != 0 \endcode The pointer to the block name must * not be a NULL pointer. * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be * a positive integer. * @pre \code num_first_particle >= 0 \endcode The number of the * first particle must be >= 0. * @pre \code n_particles >= 0 \endcode n_particles must be >= 0. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_particle_data_block_add (tng_trajectory_t tng_data, const int64_t id, const char *block_name, const char datatype, const char block_type_flag, int64_t n_frames, const int64_t n_values_per_frame, int64_t stride_length, const int64_t num_first_particle, const int64_t n_particles, const int64_t codec_id, void *new_data); /** @brief Get the name of a data block of a specific ID. * @param tng_data is the trajectory data container. * @param block_id is the ID of the data block of which to get the name. * @param name is a string, which is set to the name of the data block. * Memory must be reserved beforehand. * @param max_len is the maximum length of name. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code name != 0 \endcode The pointer to the name string * must not be a NULL pointer. * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1) * if a minor error has occured or the data block is not found or * TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_data_block_name_get (tng_trajectory_t tng_data, int64_t block_id, char *name, int max_len); /** @brief Get the dependency of a data block of a specific ID. * @param tng_data is the trajectory data container. * @param block_id is the ID of the data block of which to get the name. * @param block_dependency is a pointer to the dependency of the data block. * If the block is frame dependent it will be set to TNG_FRAME_DEPENDENT, * if it is particle dependent it will be set to TNG_PARTICLE_DEPENDENT and * if it is both it will be set to TNG_FRAME_DEPENDENT & TNG_PARTICLE_DEPENDENT. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code block_dependency != 0 \endcode The pointer to the block dependency * must not be a NULL pointer. * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1) * if a minor error has occured or the data block is not found or * TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_data_block_dependency_get (const tng_trajectory_t tng_data, int64_t block_id, int *block_dependency); /** @brief Get the number of values per frame of a data block of a specific ID. * @param tng_data is the trajectory data container. * @param block_id is the ID of the data block of which to get the name. * @param n_values_per_frame is a pointer set to the number of values per frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of values * per frame must not be a NULL pointer. * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1) * if a minor error has occured or the data block is not found or * TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_data_block_num_values_per_frame_get (const tng_trajectory_t tng_data, int64_t block_id, int64_t *n_values_per_frame); /** * @brief Write data of one trajectory frame to the output_file of tng_data. * @param tng_data is a trajectory data container. tng_data->output_file_path * specifies which file to write to. If the file (output_file) is not open it * will be opened. * @param frame_nr is the index number of the frame to write. * @param block_id is the ID of the data block to write the data to. * @param values is an array of data to write. The length of the array should * equal n_values_per_frame. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be * compared to the md5 hash of the read contents to ensure valid data. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code values != 0 \endcode The pointer to the values must not be a NULL * pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_frame_data_write (tng_trajectory_t tng_data, const int64_t frame_nr, const int64_t block_id, const void *values, const char hash_mode); /** * @brief Write particle data of one trajectory frame to the output_file of * tng_data. * @param tng_data is a trajectory data container. tng_data->output_file_path * specifies which file to write to. If the file (output_file) is not open it * will be opened. * @param frame_nr is the index number of the frame to write. * @param block_id is the ID of the data block to write the data to. * @param val_first_particle is the number of the first particle in the data * array. * @param val_n_particles is the number of particles in the data array. * @param values is a 1D-array of data to write. The length of the array should * equal n_particles * n_values_per_frame. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be * compared to the md5 hash of the read contents to ensure valid data. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code val_first_particle >= 0 \endcode The number of the * first particle must be >= 0. * @pre \code val_n_particles >= 0 \endcode The number of particles must be >= 0. * @pre \code values != 0 \endcode The pointer to the values must not be a NULL * pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_frame_particle_data_write (tng_trajectory_t tng_data, const int64_t frame_nr, const int64_t block_id, const int64_t val_first_particle, const int64_t val_n_particles, const void *values, const char hash_mode); /** * @brief Free data of an array of values (2D). * @param tng_data is a trajectory data container. * @param values is the 2D array to free and will be set to 0 afterwards. * @param n_frames is the number of frames in the data array. * @param n_values_per_frame is the number of values per frame in the data array. * @param type is the data type of the data in the array (e.g. int/float/char). * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_data_values_free (const tng_trajectory_t tng_data, union data_values **values, const int64_t n_frames, const int64_t n_values_per_frame, const char type); /** * @brief Free data of an array of values (3D). * @param tng_data is a trajectory data container. * @param values is the array to free and will be set to 0 afterwards. * @param n_frames is the number of frames in the data array. * @param n_particles is the number of particles in the data array. * @param n_values_per_frame is the number of values per frame in the data array. * @param type is the data type of the data in the array (e.g. int/float/char). * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_particle_data_values_free (const tng_trajectory_t tng_data, union data_values ***values, const int64_t n_frames, const int64_t n_particles, const int64_t n_values_per_frame, const char type); /** * @brief Retrieve non-particle data, from the last read frame set. Obsolete! * @param tng_data is a trajectory data container. tng_data->input_file_path specifies * which file to read from. If the file (input_file) is not open it will be * opened. * @param block_id is the id number of the particle data block to read. * @param values is a pointer to a 2-dimensional array (memory unallocated), which * will be filled with data. The array will be sized * (n_frames * n_values_per_frame). * Since ***values is allocated in this function it is the callers * responsibility to free the memory. * @param n_frames is set to the number of frames in the returned data. This is * needed to properly reach and/or free the data afterwards. * @param n_values_per_frame is set to the number of values per frame in the data. * This is needed to properly reach and/or free the data afterwards. * @param type is set to the data type of the data in the array. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n_frames != 0 \endcode The pointer to the number of frames * must not be a NULL pointer. * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of * values per frame must not be a NULL pointer. * @pre \code type != 0 \endcode The pointer to the data type must not * be a NULL pointer. * @details This function is obsolete and only retained for compatibility. Use * tng_data_vector_get() instead. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_data_get(tng_trajectory_t tng_data, const int64_t block_id, union data_values ***values, int64_t *n_frames, int64_t *n_values_per_frame, char *type); /** * @brief Retrieve a vector (1D array) of non-particle data, from the last read frame set. * @param tng_data is a trajectory data container. tng_data->input_file_path specifies * which file to read from. If the file (input_file) is not open it will be * opened. * @param block_id is the id number of the particle data block to read. * @param values is a pointer to a 1-dimensional array (memory unallocated), which * will be filled with data. The length of the array will be (n_frames * n_values_per_frame). * Since **values is allocated in this function it is the callers * responsibility to free the memory. * @param n_frames is set to the number of particles in the returned data. This is * needed to properly reach and/or free the data afterwards. * @param stride_length is set to the stride length of the returned data. * @param n_values_per_frame is set to the number of values per frame in the data. * This is needed to properly reach and/or free the data afterwards. * @param type is set to the data type of the data in the array. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n_frames != 0 \endcode The pointer to the number of frames * must not be a NULL pointer. * @pre \code stride_length != 0 \endcode The pointer to the stride length * must not be a NULL pointer. * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of * values per frame must not be a NULL pointer. * @pre \code type != 0 \endcode The pointer to the data type must not * be a NULL pointer. * @details This does only work for numerical (int, float, double) data. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_data_vector_get (tng_trajectory_t tng_data, const int64_t block_id, void **values, int64_t *n_frames, int64_t *stride_length, int64_t *n_values_per_frame, char *type); /** * @brief Read and retrieve non-particle data, in a specific interval. Obsolete! * @param tng_data is a trajectory data container. tng_data->input_file_path specifies * which file to read from. If the file (input_file) is not open it will be * opened. * @param block_id is the id number of the particle data block to read. * @param start_frame_nr is the index number of the first frame to read. * @param end_frame_nr is the index number of the last frame to read. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH the md5 hash in the file will be * compared to the md5 hash of the read contents to ensure valid data. * @param values is a pointer to a 2-dimensional array (memory unallocated), which * will be filled with data. The array will be sized * (n_frames * n_values_per_frame). * Since ***values is allocated in this function it is the callers * responsibility to free the memory. * @param n_values_per_frame is set to the number of values per frame in the data. * This is needed to properly reach and/or free the data afterwards. * @param type is set to the data type of the data in the array. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before * the last frame. * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of * values per frame must not be a NULL pointer. * @pre \code type != 0 \endcode The pointer to the data type must not * be a NULL pointer. * @details This function is obsolete and only retained for compatibility. Use * tng_data_vector_interval_get() instead. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_data_interval_get (tng_trajectory_t tng_data, const int64_t block_id, const int64_t start_frame_nr, const int64_t end_frame_nr, const char hash_mode, union data_values ***values, int64_t *n_values_per_frame, char *type); /** * @brief Read and retrieve a vector (1D array) of non-particle data, * in a specific interval. * @param tng_data is a trajectory data container. tng_data->input_file_path specifies * which file to read from. If the file (input_file) is not open it will be * opened. * @param block_id is the id number of the particle data block to read. * @param start_frame_nr is the index number of the first frame to read. * @param end_frame_nr is the index number of the last frame to read. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH the md5 hash in the file will be * compared to the md5 hash of the read contents to ensure valid data. * @param values is a pointer to a 1-dimensional array (memory unallocated), which * will be filled with data. The length of the array will be (n_frames * n_values_per_frame). * Since **values is allocated in this function it is the callers * responsibility to free the memory. * @param stride_length is set to the stride length (writing interval) of * the data. * @param n_values_per_frame is set to the number of values per frame in the data. * This is needed to properly reach and/or free the data afterwards. * @param type is set to the data type of the data in the array. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before * the last frame. * @pre \code stride_length != 0 \endcode The pointer to the stride length * must not be a NULL pointer. * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of * values per frame must not be a NULL pointer. * @pre \code type != 0 \endcode The pointer to the data type must not * be a NULL pointer. * @details This does only work for numerical (int, float, double) data. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_data_vector_interval_get (tng_trajectory_t tng_data, const int64_t block_id, const int64_t start_frame_nr, const int64_t end_frame_nr, const char hash_mode, void **values, int64_t *stride_length, int64_t *n_values_per_frame, char *type); /** * @brief Retrieve particle data, from the last read frame set. Obsolete! * @details The particle dimension of the returned values array is translated * to real particle numbering, i.e. the numbering of the actual molecular * system. * @param tng_data is a trajectory data container. tng_data->input_file_path * specifies which file to read from. If the file (input_file) is not open it * will be opened. * @param block_id is the id number of the particle data block to read. * @param values is a pointer to a 3-dimensional array (memory unallocated), which * will be filled with data. The array will be sized * (n_frames * n_particles * n_values_per_frame). * Since ****values is allocated in this function it is the callers * responsibility to free the memory. * @param n_frames is set to the number of frames in the returned data. This is * needed to properly reach and/or free the data afterwards. * @param n_particles is set to the number of particles in the returned data. This is * needed to properly reach and/or free the data afterwards. * @param n_values_per_frame is set to the number of values per frame in the data. * This is needed to properly reach and/or free the data afterwards. * @param type is set to the data type of the data in the array. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n_frames != 0 \endcode The pointer to the number of frames * must not be a NULL pointer. * @pre \code n_particles != 0 \endcode The pointer to the number of particles must * not be a NULL pointer. * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of * values per frame must not be a NULL pointer. * @pre \code type != 0 \endcode The pointer to the data type must not * be a NULL pointer. * @details This function is obsolete and only retained for compatibility. Use * tng_particle_data_vector_get() instead. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_particle_data_get (tng_trajectory_t tng_data, const int64_t block_id, union data_values ****values, int64_t *n_frames, int64_t *n_particles, int64_t *n_values_per_frame, char *type); /** * @brief Retrieve a vector (1D array) of particle data, from the last read frame set. * @details The particle dimension of the returned values array is translated * to real particle numbering, i.e. the numbering of the actual molecular * system. * @param tng_data is a trajectory data container. tng_data->input_file_path * specifies which file to read from. If the file (input_file) is not open it * will be opened. * @param block_id is the id number of the particle data block to read. * @param values is a pointer to a 1-dimensional array (memory unallocated), which * will be filled with data. The length of the array will be * (n_frames * n_particles * n_values_per_frame). * Since **values is allocated in this function it is the callers * responsibility to free the memory. * @param n_frames is set to the number of frames in the returned data. This is * needed to properly reach and/or free the data afterwards. * @param stride_length is set to the stride length of the returned data. * @param n_particles is set to the number of particles in the returned data. This is * needed to properly reach and/or free the data afterwards. * @param n_values_per_frame is set to the number of values per frame in the data. * This is needed to properly reach and/or free the data afterwards. * @param type is set to the data type of the data in the array. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n_particles != 0 \endcode The pointer to the number of particles must * not be a NULL pointer. * @pre \code stride_length != 0 \endcode The pointer to the stride length * must not be a NULL pointer. * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of * values per frame must not be a NULL pointer. * @pre \code type != 0 \endcode The pointer to the data type must not * be a NULL pointer. * @details This does only work for numerical (int, float, double) data. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_get (tng_trajectory_t tng_data, const int64_t block_id, void **values, int64_t *n_frames, int64_t *stride_length, int64_t *n_particles, int64_t *n_values_per_frame, char *type); /** * @brief Read and retrieve particle data, in a specific interval. Obsolete! * @details The particle dimension of the returned values array is translated * to real particle numbering, i.e. the numbering of the actual molecular * system. * @param tng_data is a trajectory data container. tng_data->input_file_path specifies * which file to read from. If the file (input_file) is not open it will be * opened. * @param block_id is the id number of the particle data block to read. * @param start_frame_nr is the index number of the first frame to read. * @param end_frame_nr is the index number of the last frame to read. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH the md5 hash in the file will be * compared to the md5 hash of the read contents to ensure valid data. * @param values is a pointer to a 3-dimensional array (memory unallocated), which * will be filled with data. The array will be sized * (n_frames * n_particles * n_values_per_frame). * Since ****values is allocated in this function it is the callers * responsibility to free the memory. * @param n_particles is set to the number of particles in the returned data. This is * needed to properly reach and/or free the data afterwards. * @param n_values_per_frame is set to the number of values per frame in the data. * This is needed to properly reach and/or free the data afterwards. * @param type is set to the data type of the data in the array. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n_frames != 0 \endcode The pointer to the number of frames * must not be a NULL pointer. * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before * the last frame. * @pre \code n_particles != 0 \endcode The pointer to the number of particles must * not be a NULL pointer. * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of * values per frame must not be a NULL pointer. * @pre \code type != 0 \endcode The pointer to the data type must not * be a NULL pointer. * @details This function is obsolete and only retained for compatibility. Use * tng_particle_data_vector_interval_get() instead. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_particle_data_interval_get (tng_trajectory_t tng_data, const int64_t block_id, const int64_t start_frame_nr, const int64_t end_frame_nr, const char hash_mode, union data_values ****values, int64_t *n_particles, int64_t *n_values_per_frame, char *type); /** * @brief Read and retrieve a vector (1D array) particle data, in a * specific interval. * @details The particle dimension of the returned values array is translated * to real particle numbering, i.e. the numbering of the actual molecular * system. * @param tng_data is a trajectory data container. tng_data->input_file_path specifies * which file to read from. If the file (input_file) is not open it will be * opened. * @param block_id is the id number of the particle data block to read. * @param start_frame_nr is the index number of the first frame to read. * @param end_frame_nr is the index number of the last frame to read. * @param hash_mode is an option to decide whether to use the md5 hash or not. * If hash_mode == TNG_USE_HASH the md5 hash in the file will be * compared to the md5 hash of the read contents to ensure valid data. * @param values is a pointer to a 1-dimensional array (memory unallocated), which * will be filled with data. The length of the array will be * (n_frames * n_particles * n_values_per_frame). * Since **values is allocated in this function it is the callers * responsibility to free the memory. * @param stride_length is set to the stride length (writing interval) of * the data. * @param n_particles is set to the number of particles in the returned data. This is * needed to properly reach and/or free the data afterwards. * @param n_values_per_frame is set to the number of values per frame in the data. * This is needed to properly reach and/or free the data afterwards. * @param type is set to the data type of the data in the array. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before * the last frame. * @pre \code n_particles != 0 \endcode The pointer to the number of particles must * not be a NULL pointer. * @pre \code stride_length != 0 \endcode The pointer to the stride length * must not be a NULL pointer. * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of * values per frame must not be a NULL pointer. * @pre \code type != 0 \endcode The pointer to the data type must not * be a NULL pointer. * @details This does only work for numerical (int, float, double) data. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_interval_get (tng_trajectory_t tng_data, const int64_t block_id, const int64_t start_frame_nr, const int64_t end_frame_nr, const char hash_mode, void **values, int64_t *n_particles, int64_t *stride_length, int64_t *n_values_per_frame, char *type); /** * @brief Get the stride length of a specific data (particle dependency does not matter) * block, either in the current frame set or of a specific frame. * @param tng_data is the trajectory data container. * @param block_id is the block ID of the data block, of which to retrieve the * stride length of the data. * @param frame is the frame from which to get the stride length. If frame is set to -1 * no specific frame will be used, but instead the first frame, starting from the last read * frame set, containing the data block will be used. * @param stride_length is set to the value of the stride length of the data block. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occurred or TNG_CRITICAL (2) if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_data_get_stride_length (const tng_trajectory_t tng_data, const int64_t block_id, int64_t frame, int64_t *stride_length); /** * @brief Get the date and time of initial file creation in ISO format (string). * @param tng_data is a trajectory data container. * @param time is a pointer to the string in which the date will be stored. Memory * must be reserved beforehand. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code time != 0 \endcode The pointer to the time must not be a NULL * pointer. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_time_get_str (const tng_trajectory_t tng_data, char *time); /** @} */ /* end of group1 */ /** @defgroup group2 High-level API * These functions make it easier to access and output TNG data. They * are recommended unless there is a special reason to use the more * detailed functions available in the low-level API. * @{ */ /** * @brief High-level function for opening and initializing a TNG trajectory. * @param filename is a string containing the name of the trajectory to open. * @param mode specifies the file mode of the trajectory. Can be set to 'r', * 'w' or 'a' for reading, writing or appending respectively. * @param tng_data_p is a pointer to the opened trajectory. This will be * allocated by the TNG library. The trajectory must be * closed by the user, whereby memory is freed. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code filename != 0 \endcode The pointer to the filename must not be a * NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_open (const char *filename, const char mode, tng_trajectory_t *tng_data_p); /** * @brief High-level function for closing a TNG trajectory. * @param tng_data_p is a pointer to the trajectory to close. The memory * will be freed after finalising the writing. * @return TNG_SUCCESS (0) if successful. */ tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_close (tng_trajectory_t *tng_data_p); /** * @brief High-level function for getting the time (in seconds) of a frame. * @param tng_data is the trajectory containing the frame. * @param frame_nr is the frame number of which to get the time. * @param time is set to the time (in seconds) of the specified frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code time != 0 \endcode The pointer to the time must not be a * NULL pointer. * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if a * minor error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_time_of_frame_get (tng_trajectory_t tng_data, const int64_t frame_nr, double *time); /* * @brief High-level function for getting the molecules in the mol system. * @param tng_data is the trajectory containing the mol system. * @param n_mols is set to the number of molecules in the system. * @param molecule_cnt_list will be pointing to the list of counts of each molecule * in the mol system. * @param mols pointing to the list of molecules in the mol system. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n_mols != 0 \endcode The pointer to the number of molecules must * not be a NULL pointer. * @return TNG_SUCCESS (0) if successful. */ /*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecules_get (tng_trajectory_t tng_data, int64_t *n_mols, int64_t **molecule_cnt_list, tng_molecule_t *mols); */ /* * @brief High-level function for adding a molecule to the mol system. * @param tng_data is the trajectory containing the mol system. * @param name is the name of the molecule to add. * @param cnt is the count of the molecule. * @param mol is set to point to the newly created molecule. * @pre \code name != 0 \endcode The pointer to the name must not be a * NULL pointer. * @pre \code cnt >= 0 \endcode The requested count must be >= 0. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured or TNG_CRITICAL (2) if a major error has occured. */ /*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecule_add (tng_trajectory_t tng_data, const char *name, const int64_t cnt, tng_molecule_t *mol); */ /* // tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_get // (tng_trajectory_t tng_data, // const tng_molecule_t mol, // int64_t *n_particles, // char ***names, // char ***types, // char ***res_names, // int64_t **res_ids, // char ***chain_names, // int64_t **chain_ids); // // tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_set // (tng_trajectory_t tng_data, // tng_molecule_t mol, // const int64_t n_particles, // const char **names, // const char **types, // const char **res_names, // const int64_t *res_ids, // const char **chain_names, // const int64_t *chain_ids); */ /** * @brief High-level function for reading the positions of all particles * from all frames. * @param tng_data is the trajectory to read from. * @param positions will be set to point at a 1-dimensional array of floats, * which will contain the positions. The data is stored sequentially in order * of frames. For each frame the positions (x, y and z coordinates) are stored. * The variable may point at already allocated memory or be a NULL pointer. * The memory must be freed afterwards. * @param stride_length will be set to the writing interval of the stored data. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code positions != 0 \endcode The pointer to the positions array * must not be a NULL pointer. * @pre \code stride_length != 0 \endcode The pointer to the stride length * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_pos_read (tng_trajectory_t tng_data, float **positions, int64_t *stride_length); /** * @brief High-level function for reading the velocities of all particles * from all frames. * @param tng_data is the trajectory to read from. * @param velocities will be set to point at a 1-dimensional array of floats, * which will contain the velocities. The data is stored sequentially in order * of frames. For each frame the velocities (in x, y and z) are stored. The * variable may point at already allocated memory or be a NULL pointer. * The memory must be freed afterwards. * @param stride_length will be set to the writing interval of the stored data. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code velocities != 0 \endcode The pointer to the velocities array * must not be a NULL pointer. * @pre \code stride_length != 0 \endcode The pointer to the stride length * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_vel_read (tng_trajectory_t tng_data, float **velocities, int64_t *stride_length); /** * @brief High-level function for reading the forces of all particles * from all frames. * @param tng_data is the trajectory to read from. * @param forces will be set to point at a 1-dimensional array of floats, * which will contain the forces. The data is stored sequentially in order * of frames. For each frame the forces (in x, y and z) are stored. The * variable may point at already allocated memory or be a NULL pointer. * The memory must be freed afterwards. * @param stride_length will be set to the writing interval of the stored data. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code forces != 0 \endcode The pointer to the forces array * must not be a NULL pointer. * @pre \code stride_length != 0 \endcode The pointer to the stride length * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_force_read (tng_trajectory_t tng_data, float **forces, int64_t *stride_length); /** * @brief High-level function for reading the box shape from all frames. * @param tng_data is the trajectory to read from. * @param box_shape will be set to point at a 1-dimensional array of floats, * which will contain the box shape. The data is stored sequentially in order * of frames. The variable may point at already allocated memory or be a NULL pointer. * If the box shape is not modified during the trajectory, but as general data, * that will be returned instead. * @param stride_length will be set to the writing interval of the stored data. * @details This function should only be used if number of values used to specify * the box shape is known (by default TNG uses 9 values) since it does not * return the number of values in the array. It is recommended to use * tng_data_vector_interval_get() instead. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code box_shape != 0 \endcode The pointer to the box_shape array * must not be a NULL pointer. * @pre \code stride_length != 0 \endcode The pointer to the stride length * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read (tng_trajectory_t tng_data, float **box_shape, int64_t *stride_length); /** * @brief High-level function for reading the next frame of particle-dependent * data of a specific type. * @param tng_data is the trajectory to read from. * @param block_id is the ID number of the block containing the data of interest. * @param values will be set to point at a 1-dimensional array containing the * requested data. The variable may point at already allocated memory or be a * NULL pointer. The memory must be freed afterwards. * @param data_type will be pointing to a character indicating the size of the * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA. * @param retrieved_frame_number will be pointing at the frame number of the * returned frame. * @param retrieved_time will be pointing at the time stamp of the returned * frame. * @details If no frame has been read before the first frame of the trajectory * is read. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code values != 0 \endcode The pointer to the values array * must not be a NULL pointer. * @pre \code data_type != 0 \endcode The pointer to the data type of the * returned data must not be a NULL pointer. * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame * number of the returned data must not be a NULL pointer. * @pre \code retrieved_time != 0 \endcode The pointer to the time of the * returned data must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_particle_data_next_frame_read (tng_trajectory_t tng_data, const int64_t block_id, void **values, char *data_type, int64_t *retrieved_frame_number, double *retrieved_time); /** * @brief High-level function for reading the next frame of non-particle-dependent * data of a specific type. * @param tng_data is the trajectory to read from. * @param block_id is the ID number of the block containing the data of interest. * @param values will be set to point at a 1-dimensional array containing the * requested data. The variable may point at already allocated memory or be a * NULL pointer. The memory must be freed afterwards. * @param data_type will be pointing to a character indicating the size of the * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA. * @param retrieved_frame_number will be pointing at the frame number of the * returned frame. * @param retrieved_time will be pointing at the time stamp of the returned * frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code values != 0 \endcode The pointer to the values array * must not be a NULL pointer. * @pre \code data_type != 0 \endcode The pointer to the data type of the * returned data must not be a NULL pointer. * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame * number of the returned data must not be a NULL pointer. * @pre \code retrieved_time != 0 \endcode The pointer to the time of the * returned data must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_non_particle_data_next_frame_read (tng_trajectory_t tng_data, const int64_t block_id, void **values, char *data_type, int64_t *retrieved_frame_number, double *retrieved_time); /** * @brief High-level function for reading the positions of all particles * from a specific range of frames. * @param tng_data is the trajectory to read from. * @param first_frame is the first frame to return position data from. * @param last_frame is the last frame to return position data from. * @param positions will be set to point at a 1-dimensional array of floats, * which will contain the positions. The data is stored sequentially in order * of frames. For each frame the positions (x, y and z coordinates) are stored. * The variable may point at already allocated memory or be a NULL pointer. * The memory must be freed afterwards. * @param stride_length will be set to the writing interval of the stored data. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before * the last frame. * @pre \code positions != 0 \endcode The pointer to the positions array * must not be a NULL pointer. * @pre \code stride_length != 0 \endcode The pointer to the stride length * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_pos_read_range (tng_trajectory_t tng_data, const int64_t first_frame, const int64_t last_frame, float **positions, int64_t *stride_length); /** * @brief High-level function for reading the velocities of all particles * from a specific range of frames. * @param tng_data is the trajectory to read from. * @param first_frame is the first frame to return position data from. * @param last_frame is the last frame to return position data from. * @param velocities will be set to point at a 1-dimensional array of floats, * which will contain the velocities. The data is stored sequentially in order * of frames. For each frame the velocities (in x, y and z) are stored. The * variable may point at already allocated memory or be a NULL pointer. * The memory must be freed afterwards. * @param stride_length will be set to the writing interval of the stored data. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before * the last frame. * @pre \code velocities != 0 \endcode The pointer to the velocities array * must not be a NULL pointer. * @pre \code stride_length != 0 \endcode The pointer to the stride length * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_vel_read_range (tng_trajectory_t tng_data, const int64_t first_frame, const int64_t last_frame, float **velocities, int64_t *stride_length); /** * @brief High-level function for reading the forces of all particles * from a specific range of frames. * @param tng_data is the trajectory to read from. * @param first_frame is the first frame to return position data from. * @param last_frame is the last frame to return position data from. * @param forces will be set to point at a 1-dimensional array of floats, * which will contain the forces. The data is stored sequentially in order * of frames. For each frame the forces (in x, y and z) are stored. The * variable may point at already allocated memory or be a NULL pointer. * The memory must be freed afterwards. * @param stride_length will be set to the writing interval of the stored data. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before * the last frame. * @pre \code forces != 0 \endcode The pointer to the forces array * must not be a NULL pointer. * @pre \code stride_length != 0 \endcode The pointer to the stride length * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_force_read_range (tng_trajectory_t tng_data, const int64_t first_frame, const int64_t last_frame, float **forces, int64_t *stride_length); /** * @brief High-level function for reading the box shape * from a specific range of frames. * @param tng_data is the trajectory to read from. * @param first_frame is the first frame to return position data from. * @param last_frame is the last frame to return position data from. * @param box_shape will be set to point at a 1-dimensional array of floats, * which will contain the box shape. The data is stored sequentially in order * of frames. * If the box shape is not modified during the trajectory, but as general data, * that will be returned instead. The * variable may point at already allocated memory or be a NULL pointer. * The memory must be freed afterwards. * @param stride_length will be set to the writing interval of the stored data. * @details This function should only be used if number of values used to specify * the box shape is known (by default TNG uses 9 values) since it does not * return the number of values in the array. It is recommended to use * tng_data_vector_interval_get() instead. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before * the last frame. * @pre \code box_shape != 0 \endcode The pointer to the box_shape array * must not be a NULL pointer. * @pre \code stride_length != 0 \endcode The pointer to the stride length * must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read_range (tng_trajectory_t tng_data, const int64_t first_frame, const int64_t last_frame, float **box_shape, int64_t *stride_length); /** * @brief High-level function for setting the writing interval of data blocks. * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @param n_values_per_frame is the number of values to store per frame. If the * data is particle dependent there will be n_values_per_frame stored per * particle each frame. * @param block_id is the ID of the block, of which to set the output interval. * @param block_name is a string that will be used as name of the block. Only * required if the block did not exist, i.e. a new block is created. * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the * data is not related to specific particles (e.g. box shape) or * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. * positions). Only required if the block did not exist, i.e. a new block is * created. * @param compression is the compression routine to use when writing the data. * Only required if the block did not exist, i.e. a new block is created. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code i >= 0 \endcode The writing interval must be >= 0. * @details n_values_per_frame, block_name, particle_dependency and * compression are only used if the data block did not exist before calling * this function, in which case it is created. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_set (tng_trajectory_t tng_data, const int64_t i, const int64_t n_values_per_frame, const int64_t block_id, const char *block_name, const char particle_dependency, const char compression); /** * @brief High-level function for setting the writing interval of data blocks * containing double precision data. * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @param n_values_per_frame is the number of values to store per frame. If the * data is particle dependent there will be n_values_per_frame stored per * particle each frame. * @param block_id is the ID of the block, of which to set the output interval. * @param block_name is a string that will be used as name of the block. Only * required if the block did not exist, i.e. a new block is created. * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the * data is not related to specific particles (e.g. box shape) or * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. * positions). Only required if the block did not exist, i.e. a new block is * created. * @param compression is the compression routine to use when writing the data. * Only required if the block did not exist, i.e. a new block is created. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code i >= 0 \endcode The writing interval must be >= 0. * @details n_values_per_frame, block_name, particle_dependency and * compression are only used if the data block did not exist before calling * this function, in which case it is created. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_double_set (tng_trajectory_t tng_data, const int64_t i, const int64_t n_values_per_frame, const int64_t block_id, const char *block_name, const char particle_dependency, const char compression); /** * @brief High-level function for setting the writing interval of data blocks. * Obsolete! Use tng_util_generic_write_interval_set() * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @param n_values_per_frame is the number of values to store per frame. If the * data is particle dependent there will be n_values_per_frame stored per * particle each frame. * @param block_id is the ID of the block, of which to set the output interval. * @param block_name is a string that will be used as name of the block. Only * required if the block did not exist, i.e. a new block is created. * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the * data is not related to specific particles (e.g. box shape) or * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. * positions). Only required if the block did not exist, i.e. a new block is * created. * @param compression is the compression routine to use when writing the data. * Only required if the block did not exist, i.e. a new block is created. * @details n_values_per_frame, block_name, particle_dependency and * compression are only used if the data block did not exist before calling * this function, in which case it is created. * This function is replaced by the more correcly named * tng_util_generic_write_interval_set(), but is kept for compatibility. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_frequency_set (tng_trajectory_t tng_data, const int64_t i, const int64_t n_values_per_frame, const int64_t block_id, const char *block_name, const char particle_dependency, const char compression); /** * @brief High-level function for setting the writing interval of position * data blocks. * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code i >= 0 \endcode The writing interval must be >= 0. * @details This function uses tng_util_generic_write_interval_set() and will * create a positions data block if none exists. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_set (tng_trajectory_t tng_data, const int64_t i); /** * @brief High-level function for setting the writing interval of position * data blocks containing double precision data. * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code i >= 0 \endcode The writing interval must be >= 0. * @details This function uses tng_util_generic_write_interval_set() and will * create a positions data block if none exists. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_double_set (tng_trajectory_t tng_data, const int64_t i); /** * @brief High-level function for setting the writing interval of position * data blocks. Obsolete! Use tng_util_pos_write_interval_set() * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code i >= 0 \endcode The writing interval must be >= 0. * @details This function uses tng_util_generic_write_interval_set() and will * create a positions data block if none exists. * This function is replaced by the more correcly named * tng_util_pos_write_interval_set(), but is kept for compatibility. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_frequency_set (tng_trajectory_t tng_data, const int64_t i); /** * @brief High-level function for setting the writing interval of velocity * data blocks. * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code i >= 0 \endcode The writing interval must be >= 0. * @details This function uses tng_util_generic_write_interval_set() and will * create a velocities data block if none exists. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_set (tng_trajectory_t tng_data, const int64_t i); /** * @brief High-level function for setting the writing interval of velocity * data blocks containing double precision data. * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code i >= 0 \endcode The writing interval must be >= 0. * @details This function uses tng_util_generic_write_interval_set() and will * create a velocities data block if none exists. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_double_set (tng_trajectory_t tng_data, const int64_t i); /** * @brief High-level function for setting the writing interval of velocity * data blocks. Obsolete! Use tng_util_vel_write_interval_set() * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @details This function uses tng_util_generic_write_interval_set() and will * create a velocities data block if none exists. * This function is replaced by the more correcly named * tng_util_vel_write_interval_set(), but is kept for compatibility. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_frequency_set (tng_trajectory_t tng_data, const int64_t i); /** * @brief High-level function for setting the writing interval of force * data blocks. * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code i >= 0 \endcode The writing interval must be >= 0. * @details This function uses tng_util_generic_write_interval_set() and will * create a forces data block if none exists. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_set (tng_trajectory_t tng_data, const int64_t i); /** * @brief High-level function for setting the writing interval of force * data blocks containing double precision data. * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code i >= 0 \endcode The writing interval must be >= 0. * @details This function uses tng_util_generic_write_interval_set() and will * create a forces data block if none exists. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_double_set (tng_trajectory_t tng_data, const int64_t i); /** * @brief High-level function for setting the writing interval of force * data blocks. Obsolete! Use tng_util_force_write_interval_set() * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @details This function uses tng_util_generic_write_interval_set() and will * create a forces data block if none exists. * This function is replaced by the more correcly named * tng_util_force_write_interval_set(), but is kept for compatibility. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_force_write_frequency_set (tng_trajectory_t tng_data, const int64_t i); /** * @brief High-level function for setting the writing interval of box shape * data blocks. * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code i >= 0 \endcode The writing interval must be >= 0. * @details This function uses tng_util_generic_write_interval_set() and will * create a box shape data block if none exists. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_set (tng_trajectory_t tng_data, const int64_t i); /** * @brief High-level function for setting the writing interval of box shape * data blocks containing double precision data. * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code i >= 0 \endcode The writing interval must be >= 0. * @details This function uses tng_util_generic_write_interval_set() and will * create a box shape data block if none exists. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_double_set (tng_trajectory_t tng_data, const int64_t i); /** * @brief High-level function for setting the writing interval of velocity * data blocks. Obsolete! Use tng_util_box_shape_write_interval_set() * @param tng_data is the trajectory to use. * @param i is the output interval, i.e. i == 10 means data written every 10th * frame. * @details This function uses tng_util_generic_write_interval_set() and will * create a box shape data block if none exists. * This function is replaced by the more correcly named * tng_util_box_shape_write_interval_set(), but is kept for compatibility. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_frequency_set (tng_trajectory_t tng_data, const int64_t i); /** * @brief High-level function for writing data of one frame to a data block. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param values is a 1D array of data to add. The array should be of length * n_particles * n_values_per_frame if writing particle related data, otherwise * it should be n_values_per_frame. * @param n_values_per_frame is the number of values to store per frame. If the * data is particle dependent there will be n_values_per_frame stored per * particle each frame. * @param block_id is the ID of the block, of which to set the output interval. * @param block_name is a string that will be used as name of the block. Only * required if the block did not exist, i.e. a new block is created. * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the * data is not related to specific particles (e.g. box shape) or * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. * positions). Only required if the block did not exist, i.e. a new block is * created. * @param compression is the compression routine to use when writing the data. * Only required if the block did not exist, i.e. a new block is created. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code values != 0 \endcode The pointer to the values array must not * be a NULL pointer. * @details n_values_per_frame, block_name, particle_dependency and * compression are only used if the data block did not exist before calling * this function, in which case it is created. * N.b. Data is written a whole block at a time. The data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_generic_write (tng_trajectory_t tng_data, const int64_t frame_nr, const float *values, const int64_t n_values_per_frame, const int64_t block_id, const char *block_name, const char particle_dependency, const char compression); /** * @brief High-level function for writing data of one frame to a double precision * data block. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param values is a 1D array of data to add. The array should be of length * n_particles * n_values_per_frame if writing particle related data, otherwise * it should be n_values_per_frame. * @param n_values_per_frame is the number of values to store per frame. If the * data is particle dependent there will be n_values_per_frame stored per * particle each frame. * @param block_id is the ID of the block, of which to set the output interval. * @param block_name is a string that will be used as name of the block. Only * required if the block did not exist, i.e. a new block is created. * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the * data is not related to specific particles (e.g. box shape) or * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. * positions). Only required if the block did not exist, i.e. a new block is * created. * @param compression is the compression routine to use when writing the data. * Only required if the block did not exist, i.e. a new block is created. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code values != 0 \endcode The pointer to the values array must not * be a NULL pointer. * @details n_values_per_frame, block_name, particle_dependency and * compression are only used if the data block did not exist before calling * this function, in which case it is created. * N.b. Data is written a whole block at a time. The data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_generic_double_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double *values, const int64_t n_values_per_frame, const int64_t block_id, const char *block_name, const char particle_dependency, const char compression); /** * @brief High-level function for adding data to positions data blocks. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param positions is a 1D array of data to add. The array should be of length * n_particles * 3. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code positions != 0 \endcode The pointer to the positions array must not * be a NULL pointer. * @details This function uses tng_util_generic_write() and will * create a positions data block if none exists. Positions are stored as three * values per frame and compressed using TNG compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_pos_write (tng_trajectory_t tng_data, const int64_t frame_nr, const float *positions); /** * @brief High-level function for adding data to positions data blocks at double * precision. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param positions is a 1D array of data to add. The array should be of length * n_particles * 3. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code positions != 0 \endcode The pointer to the positions array must not * be a NULL pointer. * @details This function uses tng_util_generic_write() and will * create a positions data block if none exists. Positions are stored as three * values per frame and compressed using TNG compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_pos_double_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double *positions); /** * @brief High-level function for adding data to velocities data blocks. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param velocities is a 1D array of data to add. The array should be of length * n_particles * 3. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code velocities != 0 \endcode The pointer to the velocities array must not * be a NULL pointer. * @details This function uses tng_util_generic_write() and will * create a velocities data block if none exists. Velocities are stored as three * values per frame and compressed using TNG compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_vel_write (tng_trajectory_t tng_data, const int64_t frame_nr, const float *velocities); /** * @brief High-level function for adding data to velocities data blocks at double * precision. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param velocities is a 1D array of data to add. The array should be of length * n_particles * 3. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code velocities != 0 \endcode The pointer to the velocities array must not * be a NULL pointer. * @details This function uses tng_util_generic_write() and will * create a velocities data block if none exists. Velocities are stored as three * values per frame and compressed using TNG compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_vel_double_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double *velocities); /** * @brief High-level function for adding data to forces data blocks. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param forces is a 1D array of data to add. The array should be of length * n_particles * 3. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code forces != 0 \endcode The pointer to the forces array must not * be a NULL pointer. * @details This function uses tng_util_generic_write() and will * create a forces data block if none exists. Forces are stored as three * values per frame and compressed using gzip compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_force_write (tng_trajectory_t tng_data, const int64_t frame_nr, const float *forces); /** * @brief High-level function for adding data to forces data blocks at double * precision. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param forces is a 1D array of data to add. The array should be of length * n_particles * 3. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code forces != 0 \endcode The pointer to the forces array must not * be a NULL pointer. * @details This function uses tng_util_generic_write() and will * create a forces data block if none exists. Forces are stored as three * values per frame and compressed using gzip compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_force_double_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double *forces); /** * @brief High-level function for adding data to box shape data blocks. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param box_shape is a 1D array of data to add. The array should be of length 9. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not * be a NULL pointer. * @details This function uses tng_util_generic_write() and will * create a box shape data block if none exists. Box shapes are stored as 9 * values per frame and compressed using TNG compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write (tng_trajectory_t tng_data, const int64_t frame_nr, const float *box_shape); /** * @brief High-level function for adding data to box shape data blocks at double * precision. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param box_shape is a 1D array of data to add. The array should be of length 9. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not * be a NULL pointer. * @details This function uses tng_util_generic_write() and will * create a box shape data block if none exists. Box shapes are stored as 9 * values per frame and compressed using TNG compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_double_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double *box_shape); /** * @brief High-level function for writing data of one frame to a data block. * If the frame is at the beginning of a frame set the time stamp of the frame * set is set. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param time is the time stamp of the frame (in seconds). * @param values is a 1D array of data to add. The array should be of length * n_particles * n_values_per_frame if writing particle related data, otherwise * it should be n_values_per_frame. * @param n_values_per_frame is the number of values to store per frame. If the * data is particle dependent there will be n_values_per_frame stored per * particle each frame. * @param block_id is the ID of the block, of which to set the output interval. * @param block_name is a string that will be used as name of the block. Only * required if the block did not exist, i.e. a new block is created. * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the * data is not related to specific particles (e.g. box shape) or * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. * positions). Only required if the block did not exist, i.e. a new block is * created. * @param compression is the compression routine to use when writing the data. * Only required if the block did not exist, i.e. a new block is created. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code time >= 0 \endcode The time stamp must be >= 0. * @pre \code values != 0 \endcode The pointer to the values array must not * be a NULL pointer. * @details n_values_per_frame, block_name, particle_dependency and * compression are only used if the data block did not exist before calling * this function, in which case it is created. * N.b. Data is written a whole block at a time. The data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const float *values, const int64_t n_values_per_frame, const int64_t block_id, const char *block_name, const char particle_dependency, const char compression); /** * @brief High-level function for writing data of one frame to a double precision * data block. If the frame is at the beginning of a frame set the time stamp of * the frame set is set. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param time is the time stamp of the frame (in seconds). * @param values is a 1D array of data to add. The array should be of length * n_particles * n_values_per_frame if writing particle related data, otherwise * it should be n_values_per_frame. * @param n_values_per_frame is the number of values to store per frame. If the * data is particle dependent there will be n_values_per_frame stored per * particle each frame. * @param block_id is the ID of the block, of which to set the output interval. * @param block_name is a string that will be used as name of the block. Only * required if the block did not exist, i.e. a new block is created. * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the * data is not related to specific particles (e.g. box shape) or * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. * positions). Only required if the block did not exist, i.e. a new block is * created. * @param compression is the compression routine to use when writing the data. * Only required if the block did not exist, i.e. a new block is created. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code time >= 0 \endcode The time stamp must be >= 0. * @pre \code values != 0 \endcode The pointer to the values array must not * be a NULL pointer. * @details n_values_per_frame, block_name, particle_dependency and * compression are only used if the data block did not exist before calling * this function, in which case it is created. * N.b. Data is written a whole block at a time. The data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_double_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const double *values, const int64_t n_values_per_frame, const int64_t block_id, const char *block_name, const char particle_dependency, const char compression); /** * @brief High-level function for adding data to positions data blocks. If the * frame is at the beginning of a frame set the time stamp of the frame set * is set. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param time is the time stamp of the frame (in seconds). * @param positions is a 1D array of data to add. The array should be of length * n_particles * 3. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code time >= 0 \endcode The time stamp must be >= 0. * @pre \code positions != 0 \endcode The pointer to the positions array must not * be a NULL pointer. * @details This function uses tng_util_generic_with_time_write() and will * create a positions data block if none exists. Positions are stored as three * values per frame and compressed using TNG compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const float *positions); /** * @brief High-level function for adding data to positions data blocks at double * precision. If the frame is at the beginning of a frame set the time stamp of * the frame set is set. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param time is the time stamp of the frame (in seconds). * @param positions is a 1D array of data to add. The array should be of length * n_particles * 3. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code time >= 0 \endcode The time stamp must be >= 0. * @pre \code positions != 0 \endcode The pointer to the positions array must not * be a NULL pointer. * @details This function uses tng_util_generic_with_time_double_write() and will * create a positions data block if none exists. Positions are stored as three * values per frame and compressed using TNG compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_double_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const double *positions); /** * @brief High-level function for adding data to velocities data blocks. If the * frame is at the beginning of a frame set the time stamp of the frame set * is set. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param time is the time stamp of the frame (in seconds). * @param velocities is a 1D array of data to add. The array should be of length * n_particles * 3. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code time >= 0 \endcode The time stamp must be >= 0. * @pre \code velocities != 0 \endcode The pointer to the velocities array must not * be a NULL pointer. * @details This function uses tng_util_generic_with_time_write() and will * create a velocities data block if none exists. Velocities are stored as three * values per frame and compressed using TNG compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const float *velocities); /** * @brief High-level function for adding data to velocities data blocks at * double precision. If the frame is at the beginning of a frame set the * time stamp of the frame set is set. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param time is the time stamp of the frame (in seconds). * @param velocities is a 1D array of data to add. The array should be of length * n_particles * 3. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code time >= 0 \endcode The time stamp must be >= 0. * @pre \code velocities != 0 \endcode The pointer to the velocities array must not * be a NULL pointer. * @details This function uses tng_util_generic_with_time_double_write() and will * create a velocities data block if none exists. Velocities are stored as three * values per frame and compressed using TNG compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_double_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const double *velocities); /** * @brief High-level function for adding data to forces data blocks. If the * frame is at the beginning of a frame set the time stamp of the frame set * is set. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param time is the time stamp of the frame (in seconds). * @param forces is a 1D array of data to add. The array should be of length * n_particles * 3. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code time >= 0 \endcode The time stamp must be >= 0. * @pre \code forces != 0 \endcode The pointer to the forces array must not * be a NULL pointer. * @details This function uses tng_util_generic_with_time_write() and will * create a forces data block if none exists. Forces are stored as three * values per frame and compressed using gzip compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const float *forces); /** * @brief High-level function for adding data to forces data blocks at * double precision. If the frame is at the beginning of a frame set * the time stamp of the frame set is set. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param time is the time stamp of the frame (in seconds). * @param forces is a 1D array of data to add. The array should be of length * n_particles * 3. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code time >= 0 \endcode The time stamp must be >= 0. * @pre \code forces != 0 \endcode The pointer to the forces array must not * be a NULL pointer. * @details This function uses tng_util_generic_with_time_double_write() and will * create a forces data block if none exists. Forces are stored as three * values per frame and compressed using gzip compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_double_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const double *forces); /** * @brief High-level function for adding data to box shape data blocks. If the * frame is at the beginning of a frame set the time stamp of the frame set * is set. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param time is the time stamp of the frame (in seconds). * @param box_shape is a 1D array of data to add. The array should be of length 9. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code time >= 0 \endcode The time stamp must be >= 0. * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not * be a NULL pointer. * @details This function uses tng_util_generic_with_time_write() and will * create a box shape data block if none exists. Box shapes are stored as 9 * values per frame and compressed using TNG compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const float *box_shape); /** * @brief High-level function for adding data to box shape data blocks at * double precision. If the frame is at the beginning of a frame set the * time stamp of the frame set is set. * @param tng_data is the trajectory to use. * @param frame_nr is the frame number of the data. * @param time is the time stamp of the frame (in seconds). * @param box_shape is a 1D array of data to add. The array should be of length 9. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. * @pre \code time >= 0 \endcode The time stamp must be >= 0. * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not * be a NULL pointer. * @details This function uses tng_util_generic_with_time_double_write() and will * create a box shape data block if none exists. Box shapes are stored as 9 * values per frame and compressed using TNG compression. * N.b. Since compressed data is written a whole block at a time the data is not * actually written to disk until the frame set is finished or the TNG * trajectory is closed. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_double_write (tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const double *box_shape); /** * @brief High-level function for getting the compression method and * multiplication factor of the last read frame of a specific data block. * @param tng_data is the trajectory to use. * @param block_id is the ID number of the block containing the data of * interest. * @param codec_id will be set to the value of the codec_id of the * compression of the data block. See tng_compression for more details. * @param factor will be set to the multiplication factor applied to * the values before compression, in order to get integers from them. * factor is 1/precision. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code codec_id != 0 \endcode The pointer to the returned codec id * must not be a NULL pointer. * @pre \code factor != 0 \endcode The pointer to the returned multiplication * factor must not be a NULL pointer. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_frame_current_compression_get (tng_trajectory_t tng_data, const int64_t block_id, int64_t *codec_id, float *factor); /** @brief High-level function for determining the next frame with data and what * data blocks have data for that frame. The search can be limited to certain * data blocks. * @param tng_data is the trajectory to use. * @param current_frame is the frame that was last read, from where to start * looking for data. * @param n_requested_data_block_ids is the number of data blocks listed in * requested_data_block_ids. If this is 0 all data blocks will be taken into * account. * @param requested_data_block_ids is an array of data blocks to look for. * @param next_frame will be set to the next frame with data. * @param n_data_blocks_in_next_frame is set to the number of data blocks with * data for next_frame. * @param data_block_ids_in_next_frame is set to an array (of length * n_data_blocks_in_next_frame) that lists the data block IDs with data for * next_frame. It must be pointing at NULL or previously allocated memory. * Memory for the array is allocated by this function. * The memory must be freed by the client afterwards or * there will be a memory leak. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code next_frame != 0 \endcode The pointer to the next frame must not * be NULL. * @pre \code n_data_blocks_in_next_frame != 0 \endcode The pointer to * n_data_blocks_in_next_frame must not be NULL. * @pre \code *data_block_ids_in_next_frame != 0 \endcode The pointer to the * list of data block IDs must not be NULL. * @pre \code n_requested_data_block_ids == 0 || requested_data_block_ids != 0 \endcode * If the number of requested data blocks != 0 then the array of data block IDs must not be NULL. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured or TNG_CRITICAL (2) if a major error * has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_next_frame_present_data_blocks_find (tng_trajectory_t tng_data, int64_t current_frame, const int64_t n_requested_data_block_ids, const int64_t *requested_data_block_ids, int64_t *next_frame, int64_t *n_data_blocks_in_next_frame, int64_t **data_block_ids_in_next_frame); /* @brief High-level function for getting all data block ids and their names * and stride lengths. * @param tng_data is the trajectory to use. * @param n_data_blocks is set to the number of data blocks in the trajectory. * @param data_block_ids is set to an array (of length * n_data_blocks) that lists the data block IDs in the trajectory. * It must be pointing at NULL or previously allocated memory. * Memory for the array is allocated by this function. * The memory must be freed by the client afterwards or * there will be a memory leak. * @param data_block_names is set to an array (of length * n_data_blocks) that contains the names of the data blocks. * It must be pointing at NULL or previously allocated memory. * Memory for the array is allocated by this function. * The memory must be freed by the client afterwards or * there will be a memory leak. * @param stride_lengths is set to an array (of length * n_data_blocks) that lists the stride lengths of the data blocks. * It must be pointing at NULL or previously allocated memory. * Memory for the array is allocated by this function. * The memory must be freed by the client afterwards or * there will be a memory leak. * @param n_values_per_frame is set to an array (of length * n_data_blocks) that lists the number of values per frame of the data blocks. * It must be pointing at NULL or previously allocated memory. * Memory for the array is allocated by this function. * The memory must be freed by the client afterwards or * there will be a memory leak. * @param block_types is set to an array (of length * n_data_blocks) that lists the block types of the data blocks. * It must be pointing at NULL or previously allocated memory. * Memory for the array is allocated by this function. * The memory must be freed by the client afterwards or * there will be a memory leak. * @param dependencies is set to an array (of length * n_data_blocks) that lists the dependencies of the data blocks. * It must be pointing at NULL or previously allocated memory. * Memory for the array is allocated by this function. * The memory must be freed by the client afterwards or * there will be a memory leak. * @param compressions is set to an array (of length * n_data_blocks) that lists the compressions of the data blocks. * It must be pointing at NULL or previously allocated memory. * Memory for the array is allocated by this function. * The memory must be freed by the client afterwards or * there will be a memory leak. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code n_data_blocks != 0 \endcode The pointer to * n_data_blocks must not be NULL. * @pre \code data_block_ids != 0 \endcode The pointer to the * list of data block IDs must not be NULL. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured or TNG_CRITICAL (2) if a major error * has occured. */ /* tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_all_data_block_types_get (tng_trajectory_t tng_data, int64_t *n_data_blocks, int64_t **data_block_ids, char ***data_block_names, int64_t **stride_lengths, int64_t **n_values_per_frame, char **block_types, char **dependencies, char **compressions); */ /** @brief Finds the frame set of the specified frame in order to prepare for writing * after it. * @param tng_data is the trajectory to use. * @param prev_frame is the frame after which to start appending. * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) * must be initialised before using it. * @pre \code prev_frame >= 0 \endcode The previous frame must not be negative. * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error * has occured (such as not finding the requested frame) or TNG_CRITICAL (2) * if a major error has occured. */ tng_function_status DECLSPECDLLEXPORT tng_util_prepare_append_after_frame (tng_trajectory_t tng_data, const int64_t prev_frame); /** @} */ /* end of group2 */ #ifdef __cplusplus } /* end extern "C" */ #endif #endif /* TNG_IO_H */