1 /* This code is part of the tng binary trajectory format. 2 * 3 * Written by Magnus Lundborg 4 * Copyright (c) 2012-2017, The GROMACS development team. 5 * Check out http://www.gromacs.org for more information. 6 * 7 * 8 * This program is free software; you can redistribute it and/or 9 * modify it under the terms of the Revised BSD License. 10 */ 11 12 /** @file tng_io.h 13 * @brief API for input and output of tng trajectory files 14 * @mainpage TNG: A flexible binary trajectory format 15 * @section intro_sec Introduction 16 * 17 * The TNG format is developed as part of the ScalaLife EU project. 18 * It is flexible by design to allow parallel writing, custom data blocks, 19 * different output frequencies and different compression algorithms. 20 * 21 * Each block can contain MD5 hashes to verify data integrity and the file 22 * can be signed by the user to ensure that the origin is correct. 23 * 24 * The intention is that the API and ABI should be stable, but it is 25 * still possible that future changes might make that impossible, in which 26 * case that will be clarified. 27 * 28 * The API and all examples are released without any warranties. Use them at 29 * your own risk. 30 * 31 * @section authors_sec Authors 32 * 33 * The TNG trajectory format is developed by: 34 * 35 * Magnus Lundborg magnus.lundborg@scilifelab.se 36 * 37 * Daniel Spångberg daniels@mkem.uu.se 38 * 39 * Rossen Apostolov rossen@kth.se 40 * 41 * The API is implemented mainly by: 42 * 43 * Magnus Lundborg 44 * 45 * @section License 46 * 47 * Copyright (c) 2012, The GROMACS development team. 48 * check out http://www.gromacs.org for more information. 49 * 50 * The TNG API is released under the Revised BSD License and is free to 51 * redistribute according to that license. 52 * 53 * A license file (named COPYING) should be included with each copy of the API. 54 * 55 * @section install_sec Installation 56 * 57 * \code 58 * mkdir build 59 * 60 * cd build 61 * 62 * cmake .. 63 * 64 * make 65 * 66 * make install 67 * \endcode 68 * Test by running: 69 * \code 70 * bin/tests/tng_testing 71 * \endcode 72 * 73 * @section change_sec Change Log 74 * 75 * See git log for full revision history. 76 * 77 * Revisions 78 * 79 * v. 1.8 - Added GROMACS energy block IDs. 80 * - Rewritten build system for the main library. 81 * - Added block ID for atom (or generic particle) mass. 82 * - Fixed bugs, such as: 83 * - Do not switch endianness when reading and writing TNG compressed data. 84 * - Update pointers to residues in the chain when writing multiple chains in one molecule. 85 * - Update frame set pointers when appending to file. 86 * 87 * v. 1.7 - Fifth stable release of the API 88 * 89 * - Added function tng_util_num_frames_with_data_of_block_id_get(). 90 * - Merged some functions and data structures 91 * to make less difference between data blocks. 92 * - Bugs fixed 93 * 94 * v. 1.6 - Fourth stable release of the API. 95 * 96 * - Removed OpenMP option when building. 97 * - Functionality for migrating data blocks. 98 * - Improved handling of molecules. 99 * - Improved installation of TNG documentation. 100 * - Enhancements to CMake usage. 101 * - Required CMake version raised to 2.8.8. 102 * - Bugs fixed. 103 * 104 * v. 1.5 - Third stable release of the API. 105 * 106 * - Fortran wrapper split into separate file 107 * - Added more block IDs. 108 * - Some new functions and utility functions added. 109 * - Improved compression precision settings. 110 * - Improved tests. 111 * - Make appending to file work better. 112 * - Modified CMake settings 113 * - Bugs fixed 114 * 115 * v. 1.4 - Changed from LGPL to the Revised BSD License. 116 * 117 * - More flexible support for digital signatures in header. 118 * - Block ID numbers changed. 119 * 120 * v. 1.3 - Second stable release of the API. 121 * 122 * - Added multiplication factor for coordinate units to general info. 123 * - Added time stamps and time per frame in frame sets. 124 * - High-level API functions added (not for managing molecules yet) 125 * - Added functions for reading data blocks into 1D arrays. 126 * - TNG compression added. 127 * - C++ interface added. 128 * - Avoid memory allocation if no data is submitted when adding data 129 * blocks. 130 * - Added function tng_num_frames_per_frame_set_set 131 * - Added data block IDs for charges, b-factors and occupancy. 132 * - GZIP compression added. 133 * - Fixed bug when updating MD5 hashes of data blocks. 134 * - Fixed bug in chain_name_of_particle_get(...) 135 * - Update frame set pointers properly. 136 * - Moved fortran wrapper from header file to source file. 137 * - Write sparse data in mdrun examples. 138 * - Fixed bugs related to reading and writing sparse data. 139 * - Fixed memory leak for non-trajectory particle data blocks. 140 * - Fixed bug when writing data blocks. 141 * - Fixed wrong values in dependency constants 142 * - Write box shape, partial charges and annotation data in tng_testing 143 * - Bug fixes in tng_testing (frame sets not written before) 144 * 145 * v. 1.0 - First stable release of the API. 146 * 147 * 148 * @section examples_sec Examples 149 * 150 * There are some examples of how to use the library located in src/tests/ 151 * 152 * @subsection tng_subsec TNG files 153 * 154 * The build directory contains an example_files directory, which in turn 155 * contains a very short example of a TNG file containing a few water molecules, 156 * a box shape description and positions in 10 frames. 157 * 158 * It is also possible to run the bin/examples/md_openmp_util 159 * (see src/tests/md_openmp_util.c) 160 * testing program, which will save MD simulations output to a new file 161 * (saved in the example_files directory). 162 * 163 * These files can be read using the bin/examples/tng_io_read_pos_util 164 * program. 165 * 166 * @subsection c_subsec C 167 * 168 * Example writing data to a TNG file (just an excerpt): 169 * \code 170 * for ( step = 1; step < step_num; step++ ) 171 * { 172 * compute ( np, nd, pos, vel, mass, force, &potential, &kinetic ); 173 * 174 * if(step % step_save == 0) 175 * { 176 * // Write positions, velocities and forces 177 * if(tng_util_pos_write(traj, step, pos) != TNG_SUCCESS) 178 * { 179 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__); 180 * break; 181 * } 182 * if(tng_util_vel_write(traj, step, vel) != TNG_SUCCESS) 183 * { 184 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__); 185 * break; 186 * } 187 * if(tng_util_force_write(traj, step, force) != TNG_SUCCESS) 188 * { 189 * printf("Error adding data. %s: %d\n", __FILE__, __LINE__); 190 * break; 191 * } 192 * } 193 * update ( np, nd, pos, vel, force, acc, mass, dt ); 194 * } 195 * \endcode 196 * 197 * Example reading positions from a TNG file: 198 * \code 199 * #include <stdlib.h> 200 * #include <stdio.h> 201 * #include "tng/tng_io.h" 202 * 203 * int main(int argc, char **argv) 204 * { 205 * tng_trajectory_t traj; 206 * // Assume that the data is stored as floats. The data is placed in 1-D 207 * // arrays 208 * float *positions = 0, *box_shape = 0; 209 * int64_t n_particles, n_frames, tot_n_frames, stride_length, i, j; 210 * // Set a default frame range 211 * int64_t first_frame = 0, last_frame = 5000; 212 * int k; 213 * 214 * // A reference must be passed to allocate memory 215 * tng_util_trajectory_open(argv[1], 'r', &traj); 216 * 217 * if(tng_num_frames_get(traj, &tot_n_frames) != TNG_SUCCESS) 218 * { 219 * printf("Cannot determine the number of frames in the file\n"); 220 * tng_util_trajectory_close(&traj); 221 * exit(1); 222 * } 223 * 224 * if(tng_num_particles_get(traj, &n_particles) != TNG_SUCCESS) 225 * { 226 * printf("Cannot determine the number of particles in the file\n"); 227 * tng_util_trajectory_close(&traj); 228 * exit(1); 229 * } 230 * 231 * printf("%"PRId64" frames in file\n", tot_n_frames); 232 * 233 * if(last_frame > tot_n_frames - 1) 234 * { 235 * last_frame = tot_n_frames - 1; 236 * } 237 * 238 * if(tng_util_box_shape_read(traj, &box_shape, &stride_length) == 239 * TNG_SUCCESS) 240 * { 241 * printf("Simulation box shape: "); 242 * for(i=0; i < 9; i++) 243 * { 244 * printf("%f ", box_shape[i]); 245 * } 246 * printf("\n"); 247 * } 248 * else 249 * { 250 * printf("Simulation box shape not set in the file (or could not be read)\n"); 251 * } 252 * 253 * n_frames = last_frame - first_frame + 1; 254 * 255 * 256 * // Get the positions of all particles in the requested frame range. 257 * // The positions are stored in the positions array. 258 * // N.B. No proper error checks. 259 * if(tng_util_pos_read_range(traj, 0, last_frame, &positions, &stride_length) 260 * == TNG_SUCCESS) 261 * { 262 * // Print the positions of the wanted particle (zero based) 263 * for(i=0; i < n_frames; i += stride_length) 264 * { 265 * printf("\nFrame %"PRId64":\n", first_frame + i); 266 * for(j=0; j < n_particles; j++) 267 * { 268 * printf("Atom nr: %"PRId64"", j); 269 * for(k=0; k < 3; k++) 270 * { 271 * printf("\t%f", positions[i/stride_length*n_particles* 272 * 3+j*3+k]); 273 * } 274 * printf("\n"); 275 * } 276 * } 277 * } 278 * else 279 * { 280 * printf("Cannot read positions\n"); 281 * } 282 * 283 * // Free memory 284 * if(positions) 285 * { 286 * free(positions); 287 * } 288 * tng_util_trajectory_close(&traj); 289 * 290 * return(0); 291 * } 292 * 293 * \endcode 294 * 295 * @subsection fortran_subsec Fortran 296 * 297 * The TNG library can be used from Fortran. It requires cray pointers, which 298 * are not part of the Fortran 77 standard, but available in most compilers. 299 * 300 * To compile the fortran example -DTNG_BUILD_FORTRAN=ON needs to be specified when 301 * running cmake. 302 * 303 */ 304 305 #ifndef TNG_IO_H 306 #define TNG_IO_H 1 307 308 #include <stdio.h> 309 #include <stdlib.h> 310 #include <string.h> 311 #include <assert.h> 312 #include "tng_io_fwd.h" 313 314 #ifdef USE_STD_INTTYPES_H 315 #include <inttypes.h> 316 #else 317 /* Visual Studio does not contain inttypes.h and stdint.h. Some defines and 318 * typedefs are used from the GNU C Library */ 319 #ifdef _MSC_VER 320 321 typedef __int32 int32_t; 322 typedef unsigned __int32 uint32_t; 323 typedef __int64 int64_t; 324 typedef unsigned __int64 uint64_t; 325 326 #else 327 #include <stdint.h> 328 #endif /* _MSC_VER */ 329 330 /* This is from inttypes.h (GNU C Library) */ 331 /* The ISO C99 standard specifies that these macros must only be 332 defined if explicitly requested. */ 333 #if !defined __cplusplus || defined __STDC_FORMAT_MACROS 334 335 # if __WORDSIZE == 64 336 # define __PRI64_PREFIX "l" 337 # define __PRIPTR_PREFIX "l" 338 # else 339 # define __PRI64_PREFIX "ll" 340 # define __PRIPTR_PREFIX 341 # endif 342 343 /* From stdint.h (GNU C Library) */ 344 /* Macros for printing format specifiers. */ 345 /* Decimal notation. */ 346 #ifndef PRId64 347 # define PRId64 __PRI64_PREFIX "d" 348 #endif 349 350 #ifndef PRIu64 351 # define PRIu64 __PRI64_PREFIX "u" 352 #endif 353 354 #ifndef PRIuPTR 355 # define PRIuPTR __PRIPTR_PREFIX "u" 356 #endif 357 358 #endif 359 360 #endif /* USE_STD_INTTYPES_H */ 361 362 #ifndef USE_WINDOWS 363 #if defined(WIN32) || defined(_WIN32) || defined(WIN64) || defined(_WIN64) 364 #define USE_WINDOWS 365 #endif /* win32... */ 366 #endif /* not defined USE_WINDOWS */ 367 368 #ifndef DECLSPECDLLEXPORT 369 #ifdef USE_WINDOWS 370 #define DECLSPECDLLEXPORT __declspec(dllexport) 371 #else /* USE_WINDOWS */ 372 #define DECLSPECDLLEXPORT 373 #endif /* USE_WINDOWS */ 374 #endif /* DECLSPECDLLEXPORT */ 375 376 /** Flag to indicate frame dependent data. */ 377 #define TNG_FRAME_DEPENDENT 1 378 /** Flag to indicate particle dependent data. */ 379 #define TNG_PARTICLE_DEPENDENT 2 380 381 /** The maximum length of a date string */ 382 #define TNG_MAX_DATE_STR_LEN 24 383 /** The length of an MD5 hash */ 384 #define TNG_MD5_HASH_LEN 16 385 /** The maximum allowed length of a string */ 386 #define TNG_MAX_STR_LEN 1024 387 388 #ifndef NDEBUG 389 #define TNG_ASSERT(cnd, msg) if(!(cnd)) {printf("%s\n", msg); assert(cnd);} 390 #else 391 #define TNG_ASSERT(cnd, msg) (void)0; 392 #endif 393 394 /** Flag to specify the endianness of a TNG file */ 395 typedef enum {TNG_BIG_ENDIAN, 396 TNG_LITTLE_ENDIAN} tng_file_endianness; 397 398 /** Flag to specify the endianness of 32 bit values of the current architecture. */ 399 typedef enum {TNG_BIG_ENDIAN_32, 400 TNG_LITTLE_ENDIAN_32, 401 TNG_BYTE_PAIR_SWAP_32} tng_endianness_32; 402 403 /** Flag to specify the endianness of 64 bit values of the current architecture. */ 404 typedef enum {TNG_BIG_ENDIAN_64, 405 TNG_LITTLE_ENDIAN_64, 406 TNG_QUAD_SWAP_64, 407 TNG_BYTE_PAIR_SWAP_64, 408 TNG_BYTE_SWAP_64} tng_endianness_64; 409 410 /** Compression mode is specified in each data block */ 411 typedef enum {TNG_UNCOMPRESSED, 412 TNG_XTC_COMPRESSION, 413 TNG_TNG_COMPRESSION, 414 TNG_GZIP_COMPRESSION} tng_compression; 415 416 /** Hash types */ 417 typedef enum {TNG_NO_HASH, 418 TNG_MD5, 419 TNG_SHA256} tng_hash_type; 420 421 /** Non trajectory blocks come before the first frame set block */ 422 typedef enum {TNG_NON_TRAJECTORY_BLOCK, TNG_TRAJECTORY_BLOCK} tng_block_type; 423 424 /** @defgroup def1 Standard non-trajectory blocks 425 * Block IDs of standard non-trajectory blocks. 426 * @{ 427 */ 428 #define TNG_GENERAL_INFO 0x0000000000000000LL 429 #define TNG_MOLECULES 0x0000000000000001LL 430 #define TNG_TRAJECTORY_FRAME_SET 0x0000000000000002LL 431 #define TNG_PARTICLE_MAPPING 0x0000000000000003LL 432 /** @} */ 433 434 /** @defgroup def2 Standard trajectory blocks 435 * Block IDs of standard trajectory blocks. Box shape and partial charges can 436 * be either trajectory blocks or non-trajectory blocks 437 * @{ 438 */ 439 #define TNG_TRAJ_BOX_SHAPE 0x0000000010000000LL 440 #define TNG_TRAJ_POSITIONS 0x0000000010000001LL 441 #define TNG_TRAJ_VELOCITIES 0x0000000010000002LL 442 #define TNG_TRAJ_FORCES 0x0000000010000003LL 443 #define TNG_TRAJ_PARTIAL_CHARGES 0x0000000010000004LL 444 #define TNG_TRAJ_FORMAL_CHARGES 0x0000000010000005LL 445 #define TNG_TRAJ_B_FACTORS 0x0000000010000006LL 446 #define TNG_TRAJ_ANISOTROPIC_B_FACTORS 0x0000000010000007LL 447 #define TNG_TRAJ_OCCUPANCY 0x0000000010000008LL 448 #define TNG_TRAJ_GENERAL_COMMENTS 0x0000000010000009LL 449 #define TNG_TRAJ_MASSES 0x0000000010000010LL 450 /** @} */ 451 452 453 /** @defgroup def3 GROMACS data block IDs 454 * Block IDs of data blocks specific to GROMACS. 455 * @{ 456 */ 457 #define TNG_GMX_LAMBDA 0x1000000010000000LL 458 #define TNG_GMX_ENERGY_ANGLE 0x1000000010000001LL 459 #define TNG_GMX_ENERGY_RYCKAERT_BELL 0x1000000010000002LL 460 #define TNG_GMX_ENERGY_LJ_14 0x1000000010000003LL 461 #define TNG_GMX_ENERGY_COULOMB_14 0x1000000010000004LL 462 #define TNG_GMX_ENERGY_LJ_(SR) 0x1000000010000005LL 463 #define TNG_GMX_ENERGY_COULOMB_(SR) 0x1000000010000006LL 464 #define TNG_GMX_ENERGY_COUL_RECIP 0x1000000010000007LL 465 #define TNG_GMX_ENERGY_POTENTIAL 0x1000000010000008LL 466 #define TNG_GMX_ENERGY_KINETIC_EN 0x1000000010000009LL 467 #define TNG_GMX_ENERGY_TOTAL_ENERGY 0x1000000010000010LL 468 #define TNG_GMX_ENERGY_TEMPERATURE 0x1000000010000011LL 469 #define TNG_GMX_ENERGY_PRESSURE 0x1000000010000012LL 470 #define TNG_GMX_ENERGY_CONSTR_RMSD 0x1000000010000013LL 471 #define TNG_GMX_ENERGY_CONSTR2_RMSD 0x1000000010000014LL 472 #define TNG_GMX_ENERGY_BOX_X 0x1000000010000015LL 473 #define TNG_GMX_ENERGY_BOX_Y 0x1000000010000016LL 474 #define TNG_GMX_ENERGY_BOX_Z 0x1000000010000017LL 475 #define TNG_GMX_ENERGY_BOXXX 0x1000000010000018LL 476 #define TNG_GMX_ENERGY_BOXYY 0x1000000010000019LL 477 #define TNG_GMX_ENERGY_BOXZZ 0x1000000010000020LL 478 #define TNG_GMX_ENERGY_BOXYX 0x1000000010000021LL 479 #define TNG_GMX_ENERGY_BOXZX 0x1000000010000022LL 480 #define TNG_GMX_ENERGY_BOXZY 0x1000000010000023LL 481 #define TNG_GMX_ENERGY_BOXVELXX 0x1000000010000024LL 482 #define TNG_GMX_ENERGY_BOXVELYY 0x1000000010000025LL 483 #define TNG_GMX_ENERGY_BOXVELZZ 0x1000000010000026LL 484 #define TNG_GMX_ENERGY_BOXVELYX 0x1000000010000027LL 485 #define TNG_GMX_ENERGY_BOXVELZX 0x1000000010000028LL 486 #define TNG_GMX_ENERGY_BOXVELZY 0x1000000010000029LL 487 #define TNG_GMX_ENERGY_VOLUME 0x1000000010000030LL 488 #define TNG_GMX_ENERGY_DENSITY 0x1000000010000031LL 489 #define TNG_GMX_ENERGY_PV 0x1000000010000032LL 490 #define TNG_GMX_ENERGY_ENTHALPY 0x1000000010000033LL 491 #define TNG_GMX_ENERGY_VIR_XX 0x1000000010000034LL 492 #define TNG_GMX_ENERGY_VIR_XY 0x1000000010000035LL 493 #define TNG_GMX_ENERGY_VIR_XZ 0x1000000010000036LL 494 #define TNG_GMX_ENERGY_VIR_YX 0x1000000010000037LL 495 #define TNG_GMX_ENERGY_VIR_YY 0x1000000010000038LL 496 #define TNG_GMX_ENERGY_VIR_YZ 0x1000000010000039LL 497 #define TNG_GMX_ENERGY_VIR_ZX 0x1000000010000040LL 498 #define TNG_GMX_ENERGY_VIR_ZY 0x1000000010000041LL 499 #define TNG_GMX_ENERGY_VIR_ZZ 0x1000000010000042LL 500 #define TNG_GMX_ENERGY_SHAKEVIR_XX 0x1000000010000043LL 501 #define TNG_GMX_ENERGY_SHAKEVIR_XY 0x1000000010000044LL 502 #define TNG_GMX_ENERGY_SHAKEVIR_XZ 0x1000000010000045LL 503 #define TNG_GMX_ENERGY_SHAKEVIR_YX 0x1000000010000046LL 504 #define TNG_GMX_ENERGY_SHAKEVIR_YY 0x1000000010000047LL 505 #define TNG_GMX_ENERGY_SHAKEVIR_YZ 0x1000000010000048LL 506 #define TNG_GMX_ENERGY_SHAKEVIR_ZX 0x1000000010000049LL 507 #define TNG_GMX_ENERGY_SHAKEVIR_ZY 0x1000000010000050LL 508 #define TNG_GMX_ENERGY_SHAKEVIR_ZZ 0x1000000010000051LL 509 #define TNG_GMX_ENERGY_FORCEVIR_XX 0x1000000010000052LL 510 #define TNG_GMX_ENERGY_FORCEVIR_XY 0x1000000010000053LL 511 #define TNG_GMX_ENERGY_FORCEVIR_XZ 0x1000000010000054LL 512 #define TNG_GMX_ENERGY_FORCEVIR_YX 0x1000000010000055LL 513 #define TNG_GMX_ENERGY_FORCEVIR_YY 0x1000000010000056LL 514 #define TNG_GMX_ENERGY_FORCEVIR_YZ 0x1000000010000057LL 515 #define TNG_GMX_ENERGY_FORCEVIR_ZX 0x1000000010000058LL 516 #define TNG_GMX_ENERGY_FORCEVIR_ZY 0x1000000010000059LL 517 #define TNG_GMX_ENERGY_FORCEVIR_ZZ 0x1000000010000060LL 518 #define TNG_GMX_ENERGY_PRES_XX 0x1000000010000061LL 519 #define TNG_GMX_ENERGY_PRES_XY 0x1000000010000062LL 520 #define TNG_GMX_ENERGY_PRES_XZ 0x1000000010000063LL 521 #define TNG_GMX_ENERGY_PRES_YX 0x1000000010000064LL 522 #define TNG_GMX_ENERGY_PRES_YY 0x1000000010000065LL 523 #define TNG_GMX_ENERGY_PRES_YZ 0x1000000010000066LL 524 #define TNG_GMX_ENERGY_PRES_ZX 0x1000000010000067LL 525 #define TNG_GMX_ENERGY_PRES_ZY 0x1000000010000068LL 526 #define TNG_GMX_ENERGY_PRES_ZZ 0x1000000010000069LL 527 #define TNG_GMX_ENERGY_SURFXSURFTEN 0x1000000010000070LL 528 #define TNG_GMX_ENERGY_MUX 0x1000000010000071LL 529 #define TNG_GMX_ENERGY_MUY 0x1000000010000072LL 530 #define TNG_GMX_ENERGY_MUZ 0x1000000010000073LL 531 #define TNG_GMX_ENERGY_VCOS 0x1000000010000074LL 532 #define TNG_GMX_ENERGY_VISC 0x1000000010000075LL 533 #define TNG_GMX_ENERGY_BAROSTAT 0x1000000010000076LL 534 #define TNG_GMX_ENERGY_T_SYSTEM 0x1000000010000077LL 535 #define TNG_GMX_ENERGY_LAMB_SYSTEM 0x1000000010000078LL 536 #define TNG_GMX_SELECTION_GROUP_NAMES 0x1000000010000079LL 537 #define TNG_GMX_ATOM_SELECTION_GROUP 0x1000000010000080LL 538 /** @} */ 539 540 /** Flag to specify if a data block contains data related to particles or not.*/ 541 typedef enum {TNG_NON_PARTICLE_BLOCK_DATA, 542 TNG_PARTICLE_BLOCK_DATA} tng_particle_dependency; 543 544 545 typedef enum {TNG_FALSE, TNG_TRUE} tng_bool; 546 547 /** Flag to specify if the number of atoms change throughout the trajectory or 548 * if it is constant. */ 549 typedef enum {TNG_CONSTANT_N_ATOMS, TNG_VARIABLE_N_ATOMS} 550 tng_variable_n_atoms_flag; 551 552 /** Return values of API functions. TNG_SUCCESS means that the operation 553 * was successful. TNG_FAILURE means that the operation failed for some 554 * reason, but it is possible to try to continue anyhow. TNG_CRITICAL 555 * means that the error is irrecoverable. */ 556 typedef enum {TNG_SUCCESS, TNG_FAILURE, TNG_CRITICAL} tng_function_status; 557 558 /** If tng_hash_mode == TNG_USE_HASH md5 hashes will be written to output files 559 * and when reading a file the md5 hashes of the contents will be compared to 560 * those in the file (for each block) in order to ensure data integrity */ 561 typedef enum {TNG_SKIP_HASH, TNG_USE_HASH} tng_hash_mode; 562 563 /** Possible formats of data block contents */ 564 typedef enum {TNG_CHAR_DATA, 565 TNG_INT_DATA, 566 TNG_FLOAT_DATA, 567 TNG_DOUBLE_DATA} tng_data_type; 568 569 570 struct tng_trajectory; 571 struct tng_molecule; 572 struct tng_chain; 573 struct tng_residue; 574 struct tng_atom; 575 struct tng_bond; 576 struct tng_gen_block; 577 struct tng_particle_mapping; 578 struct tng_trajectory_frame_set; 579 struct tng_particle_data; 580 struct tng_non_particle_data; 581 582 /** Data can be either double, float, int or a string */ 583 union data_values { 584 double d; 585 float f; 586 int64_t i; 587 char *c; 588 }; 589 590 591 #ifdef __cplusplus 592 extern "C" 593 { 594 #endif 595 596 /** @defgroup group1 Low-level API 597 * These functions give detailed control of the TNG data management. Most 598 * things can be done using the more convenient high-level API functions 599 * instead. 600 * @{ 601 */ 602 603 /** 604 * @brief Get the major version of the TNG library. 605 * @param tng_data is a trajectory data container, it does not have 606 * to be initialized beforehand. 607 * @param version is pointing to a value set to the major version of 608 * the library. 609 * @return TNG_SUCCESS (0) if successful. 610 */ 611 tng_function_status DECLSPECDLLEXPORT tng_version_major 612 (const tng_trajectory_t tng_data, 613 int *version); 614 615 /** 616 * @brief Get the minor version of the TNG library. 617 * @param tng_data is a trajectory data container, it does not have 618 * to be initialized beforehand. 619 * @param version is pointing to a value set to the minor version of 620 * the library. 621 * @return TNG_SUCCESS (0) if successful. 622 */ 623 tng_function_status DECLSPECDLLEXPORT tng_version_minor 624 (const tng_trajectory_t tng_data, 625 int *version); 626 627 /** 628 * @brief Get the patch level of the TNG library. 629 * @param tng_data is a trajectory data container, it does not have 630 * to be initialized beforehand. 631 * @param patch_level is the string to fill with the full version, 632 * memory must be allocated before. 633 * @return TNG_SUCCESS (0) if successful. 634 */ 635 tng_function_status DECLSPECDLLEXPORT tng_version_patchlevel 636 (const tng_trajectory_t tng_data, 637 int *patch_level); 638 639 /** 640 * @brief Get the full version string of the TNG library. 641 * @param tng_data is a trajectory data container, it does not have 642 * to be initialized beforehand. 643 * @param version is pointing to a value set to the major version of 644 * the library. 645 * @param max_len maximum char length of the string, i.e. how much memory has 646 * been reserved for version. This includes \0 terminating character. 647 * @pre \code version != 0 \endcode The pointer to the name string 648 * must not be a NULL pointer. 649 * @return TNG_SUCCESS (0) if successful. 650 */ 651 tng_function_status DECLSPECDLLEXPORT tng_version 652 (const tng_trajectory_t tng_data, 653 char *version, 654 const int max_len); 655 656 /** 657 * @brief Setup a trajectory data container. 658 * @param tng_data_p a pointer to memory to initialise as a trajectory. 659 * @pre tng_data_p must not be pointing at a reserved memory block. 660 * @details Memory is allocated during initialisation. 661 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 662 * error has occured. 663 */ 664 tng_function_status DECLSPECDLLEXPORT tng_trajectory_init 665 (tng_trajectory_t *tng_data_p); 666 667 /** 668 * @brief Clean up a trajectory data container. 669 * @param tng_data_p a pointer to the trajectory data to destroy. 670 * @details All allocated memory in the data structure is freed, as well as 671 * tng_data_p itself. 672 * @return TNG_SUCCESS (0) if successful. 673 */ 674 tng_function_status DECLSPECDLLEXPORT tng_trajectory_destroy 675 (tng_trajectory_t *tng_data_p); 676 677 /** 678 * @brief Copy a trajectory data container (dest is setup as well). 679 * @details This initialises dest and copies only what is absolute necessary for 680 * parallel i/o. This can be used inside pragma omp for setting up a thread 681 * local copy of src. It can be freed (using tng_trajectory_destroy) at the 682 * end of the parallel block. 683 * @param src the original trajectory. 684 * @param dest_p a pointer to memory to initialise as a trajectory. 685 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 686 * must be initialised before using it. 687 * @pre tng_data_p must not be pointing at a reserved memory block. 688 * @details Memory is allocated during initialisation. 689 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 690 * error has occured. 691 */ 692 tng_function_status DECLSPECDLLEXPORT tng_trajectory_init_from_src 693 (const tng_trajectory_t src, tng_trajectory_t *dest_p); 694 695 /** 696 * @brief Get the name of the input file. 697 * @param tng_data the trajectory of which to get the input file name. 698 * @param file_name the string to fill with the name of the input file, 699 * memory must be allocated before. 700 * @param max_len maximum char length of the string, i.e. how much memory has 701 * been reserved for file_name. This includes \0 terminating character. 702 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 703 * must be initialised before using it. 704 * @pre \code file_name != 0 \endcode The pointer to the file name string 705 * must not be a NULL pointer. 706 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 707 * has occurred (source string longer than destination string). 708 */ 709 tng_function_status DECLSPECDLLEXPORT tng_input_file_get 710 (const tng_trajectory_t tng_data, 711 char *file_name, const int max_len); 712 713 /** 714 * @brief Set the name of the input file. 715 * @param tng_data the trajectory of which to set the input file name. 716 * @param file_name the name of the input file. 717 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 718 * must be initialised before using it. 719 * @pre \code file_name != 0 \endcode The pointer to the file name string 720 * must not be a NULL pointer. 721 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 722 * error has occured. 723 */ 724 tng_function_status DECLSPECDLLEXPORT tng_input_file_set 725 (const tng_trajectory_t tng_data, 726 const char *file_name); 727 728 /** 729 * @brief Get the name of the output file. 730 * @param tng_data the trajectory of which to get the input file name. 731 * @param file_name the string to fill with the name of the output file, 732 * memory must be allocated before. 733 * @param max_len maximum char length of the string, i.e. how much memory has 734 * been reserved for file_name. This includes \0 terminating character. 735 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 736 * must be initialised before using it. 737 * @pre \code file_name != 0 \endcode The pointer to the file name string 738 * must not be a NULL pointer. 739 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 740 * has occurred (source string longer than destination string). 741 */ 742 tng_function_status DECLSPECDLLEXPORT tng_output_file_get 743 (const tng_trajectory_t tng_data, 744 char *file_name, const int max_len); 745 746 /** 747 * @brief Set the name of the output file. 748 * @param tng_data the trajectory of which to set the output file name. 749 * @param file_name the name of the output file. 750 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 751 * must be initialised before using it. 752 * @pre \code file_name != 0 \endcode The pointer to the file name string 753 * must not be a NULL pointer. 754 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 755 * error has occured. 756 */ 757 tng_function_status DECLSPECDLLEXPORT tng_output_file_set 758 (const tng_trajectory_t tng_data, 759 const char *file_name); 760 761 /** 762 * @brief Set the name of the output file for appending. The output file 763 * will not be overwritten. 764 * @param tng_data the trajectory of which to set the output file name. 765 * @param file_name the name of the output file to append to. 766 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 767 * must be initialised before using it. 768 * @pre \code file_name != 0 \endcode The pointer to the file name string 769 * must not be a NULL pointer. 770 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 771 * error has occured. 772 */ 773 tng_function_status DECLSPECDLLEXPORT tng_output_append_file_set 774 (const tng_trajectory_t tng_data, 775 const char *file_name); 776 777 /** 778 * @brief Get the endianness of the output file. 779 * @param tng_data the trajectory of which to get the endianness of the current 780 * output file. 781 * @param endianness will contain the enumeration of the endianness. 782 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 783 * must be initialised before using it. 784 * @pre \code endianness != 0 \endcode The pointer to the endianness container 785 * must not be a NULL pointer. 786 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness 787 * could not be retrieved. 788 */ 789 tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_get 790 (const tng_trajectory_t tng_data, tng_file_endianness *endianness); 791 792 /** 793 * @brief Set the endianness of the output file. 794 * @param tng_data the trajectory of which to set the endianness of the current 795 * output file. 796 * @param endianness the enumeration of the endianness, can be either 797 * TNG_BIG_ENDIAN (0) or TNG_LITTLE_ENDIAN (1). 798 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 799 * must be initialised before using it. 800 * @details The endianness cannot be changed after file output has started. 801 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness 802 * could not be set. 803 */ 804 tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_set 805 (const tng_trajectory_t tng_data, 806 const tng_file_endianness endianness); 807 808 /** 809 * @brief Get the name of the program used when creating the trajectory. 810 * @param tng_data the trajectory of which to get the program name. 811 * @param name the string to fill with the name of the program, 812 * memory must be allocated before. 813 * @param max_len maximum char length of the string, i.e. how much memory has 814 * been reserved for name. This includes \0 terminating character. 815 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 816 * must be initialised before using it. 817 * @pre \code name != 0 \endcode The pointer to the name string 818 * must not be a NULL pointer. 819 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 820 * has occurred (source string longer than destination string). 821 */ 822 tng_function_status DECLSPECDLLEXPORT tng_first_program_name_get 823 (const tng_trajectory_t tng_data, 824 char *name, const int max_len); 825 826 /** 827 * @brief Set the name of the program used when creating the trajectory. 828 * @param tng_data the trajectory of which to set the program name. 829 * @param new_name is a string containing the wanted name. 830 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 831 * must be initialised before using it. 832 * @pre \code new_name != 0 \endcode The pointer to the new_name string 833 * must not be a NULL pointer. 834 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 835 * error has occured. 836 */ 837 tng_function_status DECLSPECDLLEXPORT tng_first_program_name_set 838 (const tng_trajectory_t tng_data, 839 const char *new_name); 840 841 /** 842 * @brief Get the name of the program used when last modifying the trajectory. 843 * @param tng_data the trajectory of which to get the program name. 844 * @param name the string to fill with the name of the program, 845 * memory must be allocated before. 846 * @param max_len maximum char length of the string, i.e. how much memory has 847 * been reserved for name. This includes \0 terminating character. 848 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 849 * must be initialised before using it. 850 * @pre \code name != 0 \endcode The pointer to the name string 851 * must not be a NULL pointer. 852 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 853 * has occurred (source string longer than destination string). 854 */ 855 tng_function_status DECLSPECDLLEXPORT tng_last_program_name_get 856 (const tng_trajectory_t tng_data, 857 char *name, const int max_len); 858 859 /** 860 * @brief Set the name of the program used when last modifying the trajectory. 861 * @param tng_data the trajectory of which to set the program name. 862 * @param new_name is a string containing the wanted name. 863 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 864 * must be initialised before using it. 865 * @pre \code new_name != 0 \endcode The pointer to the new_name string 866 * must not be a NULL pointer. 867 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 868 * error has occured. 869 */ 870 tng_function_status DECLSPECDLLEXPORT tng_last_program_name_set 871 (const tng_trajectory_t tng_data, 872 const char *new_name); 873 874 /** 875 * @brief Get the name of the user who created the trajectory. 876 * @param tng_data the trajectory of which to get the user name. 877 * @param name the string to fill with the name of the user, 878 * memory must be allocated before. 879 * @param max_len maximum char length of the string, i.e. how much memory has 880 * been reserved for name. This includes \0 terminating character. 881 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 882 * must be initialised before using it. 883 * @pre \code name != 0 \endcode The pointer to the name string 884 * must not be a NULL pointer. 885 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 886 * has occurred (source string longer than destination string). 887 */ 888 tng_function_status DECLSPECDLLEXPORT tng_first_user_name_get 889 (const tng_trajectory_t tng_data, 890 char *name, const int max_len); 891 892 /** 893 * @brief Set the name of the user who created the trajectory. 894 * @param tng_data the trajectory of which to set the user name. 895 * @param new_name is a string containing the wanted name. 896 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 897 * must be initialised before using it. 898 * @pre \code new_name != 0 \endcode The pointer to the new_name string 899 * must not be a NULL pointer. 900 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 901 * error has occured. 902 */ 903 tng_function_status DECLSPECDLLEXPORT tng_first_user_name_set 904 (const tng_trajectory_t tng_data, 905 const char *new_name); 906 907 /** 908 * @brief Get the name of the user who last modified the trajectory. 909 * @param tng_data the trajectory of which to get the user name. 910 * @param name the string to fill with the name of the user, 911 * memory must be allocated before. 912 * @param max_len maximum char length of the string, i.e. how much memory has 913 * been reserved for name. This includes \0 terminating character. 914 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 915 * must be initialised before using it. 916 * @pre \code name != 0 \endcode The pointer to the name string 917 * must not be a NULL pointer. 918 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 919 * has occurred (source string longer than destination string). 920 */ 921 tng_function_status DECLSPECDLLEXPORT tng_last_user_name_get 922 (const tng_trajectory_t tng_data, 923 char *name, const int max_len); 924 925 /** 926 * @brief Set the name of the user who last modified the trajectory. 927 * @param tng_data the trajectory of which to set the user name. 928 * @param new_name is a string containing the wanted name. 929 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 930 * must be initialised before using it. 931 * @pre \code new_name != 0 \endcode The pointer to the new_name string 932 * must not be a NULL pointer. 933 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 934 * error has occured. 935 */ 936 tng_function_status DECLSPECDLLEXPORT tng_last_user_name_set 937 (const tng_trajectory_t tng_data, 938 const char *new_name); 939 940 /** 941 * @brief Get the name of the computer used when creating the trajectory. 942 * @param tng_data the trajectory of which to get the computer name. 943 * @param name the string to fill with the name of the computer, 944 * memory must be allocated before. 945 * @param max_len maximum char length of the string, i.e. how much memory has 946 * been reserved for name. This includes \0 terminating character. 947 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 948 * must be initialised before using it. 949 * @pre \code name != 0 \endcode The pointer to the name string 950 * must not be a NULL pointer. 951 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 952 * has occurred (source string longer than destination string). 953 */ 954 tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_get 955 (const tng_trajectory_t tng_data, 956 char *name, const int max_len); 957 958 /** 959 * @brief Set the name of the computer used when creating the trajectory. 960 * @param tng_data the trajectory of which to set the computer name. 961 * @param new_name is a string containing the wanted name. 962 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 963 * must be initialised before using it. 964 * @pre \code new_name != 0 \endcode The pointer to the new_name string 965 * must not be a NULL pointer. 966 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 967 * error has occured. 968 */ 969 tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_set 970 (const tng_trajectory_t tng_data, 971 const char *new_name); 972 973 /** 974 * @brief Get the name of the computer used when last modifying the trajectory. 975 * @param tng_data the trajectory of which to get the computer name. 976 * @param name the string to fill with the name of the computer, 977 * memory must be allocated before. 978 * @param max_len maximum char length of the string, i.e. how much memory has 979 * been reserved for name. This includes \0 terminating character. 980 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 981 * must be initialised before using it. 982 * @pre \code name != 0 \endcode The pointer to the name string 983 * must not be a NULL pointer. 984 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 985 * has occurred (source string longer than destination string). 986 */ 987 tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_get 988 (const tng_trajectory_t tng_data, 989 char *name, const int max_len); 990 991 /** 992 * @brief Set the name of the computer used when last modifying the trajectory. 993 * @param tng_data the trajectory of which to set the computer name. 994 * @param new_name is a string containing the wanted name. 995 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 996 * must be initialised before using it. 997 * @pre \code new_name != 0 \endcode The pointer to the new_name string 998 * must not be a NULL pointer. 999 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 1000 * error has occured. 1001 */ 1002 tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_set 1003 (const tng_trajectory_t tng_data, 1004 const char *new_name); 1005 1006 /** 1007 * @brief Get the pgp_signature of the user creating the trajectory. 1008 * @param tng_data the trajectory of which to get the computer name. 1009 * @param signature the string to fill with the signature, 1010 * memory must be allocated before. 1011 * @param max_len maximum char length of the string, i.e. how much memory has 1012 * been reserved for name. This includes \0 terminating character. 1013 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1014 * must be initialised before using it. 1015 * @pre \code signature != 0 \endcode The pointer to the signature 1016 * must not be a NULL pointer. 1017 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1018 * has occurred (source string longer than destination string). 1019 */ 1020 tng_function_status DECLSPECDLLEXPORT tng_first_signature_get 1021 (const tng_trajectory_t tng_data, 1022 char *signature, const int max_len); 1023 1024 /** 1025 * @brief Set the pgp_signature of the user creating the trajectory. 1026 * @param tng_data the trajectory of which to set the computer name. 1027 * @param signature is a string containing the pgp_signature. 1028 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1029 * must be initialised before using it. 1030 * @pre \code signature != 0 \endcode The pointer to the signature 1031 * must not be a NULL pointer. 1032 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 1033 * error has occured. 1034 */ 1035 tng_function_status DECLSPECDLLEXPORT tng_first_signature_set 1036 (const tng_trajectory_t tng_data, 1037 const char *signature); 1038 1039 /** 1040 * @brief Get the pgp_signature of the user last modifying the trajectory. 1041 * @param tng_data the trajectory of which to get the computer name. 1042 * @param signature the string to fill with the signature, 1043 * memory must be allocated before. 1044 * @param max_len maximum char length of the string, i.e. how much memory has 1045 * been reserved for name. This includes \0 terminating character. 1046 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1047 * must be initialised before using it. 1048 * @pre \code signature != 0 \endcode The pointer to the signature 1049 * must not be a NULL pointer. 1050 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1051 * has occurred (source string longer than destination string). 1052 */ 1053 tng_function_status DECLSPECDLLEXPORT tng_last_signature_get 1054 (const tng_trajectory_t tng_data, 1055 char *signature, const int max_len); 1056 1057 /** 1058 * @brief Set the pgp_signature of the user last modifying the trajectory. 1059 * @param tng_data the trajectory of which to set the computer name. 1060 * @param signature is a string containing the pgp_signature. 1061 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1062 * must be initialised before using it. 1063 * @pre \code signature != 0 \endcode The pointer to the signature 1064 * must not be a NULL pointer. 1065 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 1066 * error has occured. 1067 */ 1068 tng_function_status DECLSPECDLLEXPORT tng_last_signature_set 1069 (const tng_trajectory_t tng_data, 1070 const char *signature); 1071 1072 /** 1073 * @brief Get the name of the forcefield used in the trajectory. 1074 * @param tng_data the trajectory of which to get the forcefield name. 1075 * @param name the string to fill with the name of the forcefield, 1076 * memory must be allocated before. 1077 * @param max_len maximum char length of the string, i.e. how much memory has 1078 * been reserved for name. This includes \0 terminating character. 1079 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1080 * must be initialised before using it. 1081 * @pre \code name != 0 \endcode The pointer to the name string 1082 * must not be a NULL pointer. 1083 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1084 * has occurred (source string longer than destination string). 1085 */ 1086 tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_get 1087 (const tng_trajectory_t tng_data, 1088 char *name, const int max_len); 1089 1090 /** 1091 * @brief Set the name of the forcefield used in the trajectory. 1092 * @param tng_data the trajectory of which to set the forcefield name. 1093 * @param new_name is a string containing the wanted name. 1094 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1095 * must be initialised before using it. 1096 * @pre \code new_name != 0 \endcode The pointer to the new_name string 1097 * must not be a NULL pointer. 1098 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 1099 * error has occured. 1100 */ 1101 tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_set 1102 (const tng_trajectory_t tng_data, 1103 const char *new_name); 1104 1105 /** 1106 * @brief Get the medium stride length of the trajectory. 1107 * @param tng_data is the trajectory from which to get the stride length. 1108 * @param len is pointing to a value set to the stride length. 1109 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1110 * must be initialised before using it. 1111 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer. 1112 * @return TNG_SUCCESS (0) if successful. 1113 */ 1114 tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_get 1115 (const tng_trajectory_t tng_data, 1116 int64_t *len); 1117 1118 /** 1119 * @brief Set the medium stride length of the trajectory. 1120 * @param tng_data is the trajectory of which to set the stride length. 1121 * @param len is the wanted medium stride length. 1122 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1123 * must be initialised before using it. 1124 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1125 * has occurred. 1126 */ 1127 tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_set 1128 (const tng_trajectory_t tng_data, 1129 const int64_t len); 1130 1131 /** 1132 * @brief Get the long stride length of the trajectory. 1133 * @param tng_data is the trajectory from which to get the stride length. 1134 * @param len is pointing to a value set to the stride length. 1135 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1136 * must be initialised before using it. 1137 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer. 1138 * @return TNG_SUCCESS (0) if successful. 1139 */ 1140 tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_get 1141 (const tng_trajectory_t tng_data, 1142 int64_t *len); 1143 1144 /** 1145 * @brief Set the long stride length of the trajectory. 1146 * @param tng_data is the trajectory of which to set the stride length. 1147 * @param len is the wanted long stride length. 1148 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1149 * must be initialised before using it. 1150 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1151 * has occurred. 1152 */ 1153 tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_set 1154 (const tng_trajectory_t tng_data, 1155 const int64_t len); 1156 1157 /** 1158 * @brief Get the current time per frame of the trajectory. 1159 * @param tng_data is the trajectory from which to get the time per frame. 1160 * @param time is pointing to a value set to the time per frame. 1161 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1162 * must be initialised before using it. 1163 * @pre \code time != 0 \endcode The pointer to time must not be a NULL pointer. 1164 * @return TNG_SUCCESS (0) if successful. 1165 */ 1166 tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_get 1167 (const tng_trajectory_t tng_data, 1168 double *time); 1169 1170 /** 1171 * @brief Set the time per frame of the trajectory. 1172 * @param tng_data is the trajectory of which to set the time per frame. 1173 * @param time is the new time per frame. 1174 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1175 * must be initialised before using it. 1176 * @pre \code time > 0 \endcode The time per frame must be >= 0. 1177 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1178 * has occurred. 1179 */ 1180 tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_set 1181 (const tng_trajectory_t tng_data, 1182 const double time); 1183 1184 /** 1185 * @brief Get the length of the input file. 1186 * @param tng_data is the trajectory from which to get the input file length. 1187 * @param len is pointing to a value set to the file length. 1188 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1189 * must be initialised before using it. 1190 * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer. 1191 * @return TNG_SUCCESS (0) if successful. 1192 */ 1193 tng_function_status DECLSPECDLLEXPORT tng_input_file_len_get 1194 (const tng_trajectory_t tng_data, 1195 int64_t *len); 1196 1197 /** 1198 * @brief Get the number of frames in the trajectory 1199 * @param tng_data is the trajectory of which to get the number of frames. 1200 * @param n is pointing to a value set to the number of frames. 1201 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1202 * must be initialised before using it. 1203 * @pre \code tng_data->input_file != 0 \endcode An input file must be open 1204 * to find the next frame set. 1205 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. 1206 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1207 * has occurred (could not find last frame set). 1208 */ 1209 tng_function_status DECLSPECDLLEXPORT tng_num_frames_get 1210 (const tng_trajectory_t tng_data, 1211 int64_t *n); 1212 1213 /** 1214 * @brief Get the precision of lossy compression. 1215 * @param tng_data is the trajectory of which to get the compression precision. 1216 * @param precision will be pointing to the retrieved compression precision. 1217 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1218 * must be initialised before using it. 1219 * @details A compression precision of 0.001 (the default) means that the 1220 * compressed values are accurate to the third decimal. This function does 1221 * not check actual precision of compressed data, but just returns what has 1222 * previously been set using tng_compression_precision_set(). 1223 * @return TNG_SUCCESS (0) if successful. 1224 */ 1225 tng_function_status DECLSPECDLLEXPORT tng_compression_precision_get 1226 (const tng_trajectory_t tng_data, 1227 double *precision); 1228 1229 /** 1230 * @brief Set the precision of lossy compression. 1231 * @param tng_data is the trajectory of which to set the compression precision. 1232 * @param precision is the new compression precision. 1233 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1234 * must be initialised before using it. 1235 * @details A compression precision of 0.001 (the default) means that the 1236 * compressed values are accurate to the third decimal. 1237 * @return TNG_SUCCESS (0) if successful. 1238 */ 1239 tng_function_status DECLSPECDLLEXPORT tng_compression_precision_set 1240 (const tng_trajectory_t tng_data, 1241 const double precision); 1242 1243 /** 1244 * @brief Set the number of particles, in the case no molecular system is used. 1245 * @param tng_data is the trajectory of which to get the number of particles. 1246 * @param n is the number of particles to use. 1247 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1248 * must be initialised before using it. 1249 * @details When creating a molecular system the number of particles are set 1250 * automatically. This should only be used when there is no molecular system 1251 * specified or if the number of atoms needs to be overridden for some reason. 1252 * @return TNG_SUCCESS (0) if successful. 1253 */ 1254 tng_function_status DECLSPECDLLEXPORT tng_implicit_num_particles_set 1255 (const tng_trajectory_t tng_data, 1256 const int64_t n); 1257 1258 /** 1259 * @brief Get the current number of particles. 1260 * @param tng_data is the trajectory from which to get the number of particles. 1261 * @param n is pointing to a value set to the number of particles. 1262 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1263 * must be initialised before using it. 1264 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. 1265 * @details If variable number of particles are used this function will return 1266 * the number of particles in the current frame set. 1267 * @return TNG_SUCCESS (0) if successful. 1268 */ 1269 tng_function_status DECLSPECDLLEXPORT tng_num_particles_get 1270 (const tng_trajectory_t tng_data, 1271 int64_t *n); 1272 1273 /** 1274 * @brief Get if the number of particle can be varied during the simulation. 1275 * @param tng_data is the trajectory from which to get the number of particles. 1276 * @param variable is pointing to a value set to TNG_CONSTANT_N_ATOMS if the 1277 * number of particles cannot change or TNG_VARIABLE_N_ATOMS if the number of 1278 * particles can change. 1279 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1280 * must be initialised before using it. 1281 * @pre \code variable != 0 \endcode The pointer to variable must not be 1282 * a NULL pointer. 1283 * @return TNG_SUCCESS (0) if successful. 1284 */ 1285 tng_function_status DECLSPECDLLEXPORT tng_num_particles_variable_get 1286 (const tng_trajectory_t tng_data, 1287 char *variable); 1288 1289 /** 1290 * @brief Get the number of molecule types (length of tng_data->molecules). 1291 * @param tng_data is the trajectory from which to get the number of molecules. 1292 * @param n is pointing to a value set to the number of molecule types. 1293 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1294 * must be initialised before using it. 1295 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. 1296 * @return TNG_SUCCESS (0) if successful. 1297 */ 1298 tng_function_status DECLSPECDLLEXPORT tng_num_molecule_types_get 1299 (const tng_trajectory_t tng_data, 1300 int64_t *n); 1301 1302 /** 1303 * @brief Get the current total number of molecules. 1304 * @param tng_data is the trajectory from which to get the number of molecules. 1305 * @param n is pointing to a value set to the number of molecules. 1306 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1307 * must be initialised before using it. 1308 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. 1309 * @details If variable number of particles are used this function will return 1310 * the total number of molecules in the current frame set. 1311 * @return TNG_SUCCESS (0) if successful. 1312 */ 1313 tng_function_status DECLSPECDLLEXPORT tng_num_molecules_get 1314 (const tng_trajectory_t tng_data, 1315 int64_t *n); 1316 1317 /** @brief Get the list of the count of each molecule. 1318 * @param tng_data is the trajectory from which to get the molecule count list. 1319 * @param mol_cnt_list is a list of the count of each molecule in the 1320 * mol system. This is a pointer to the list in the TNG container, which 1321 * means that it should be handled carefully, e.g. not freed. 1322 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1323 * must be initialised before using it. 1324 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE(1) if the list of 1325 * molecule counts was not valid. 1326 */ 1327 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_list_get 1328 (const tng_trajectory_t tng_data, 1329 int64_t **mol_cnt_list); 1330 1331 /** 1332 * @brief Get the exponent used for distances in the trajectory. 1333 * @param tng_data is the trajectory from which to get the information. 1334 * @param exp is pointing to a value set to the distance unit exponent. 1335 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1336 * must be initialised before using it. 1337 * @pre \code exp != 0 \endcode The pointer to exp must not be a NULL pointer. 1338 * @details Example: If the distances are specified in nm (default) exp is -9. 1339 * If the distances are specified in Å exp is -10. 1340 * @return TNG_SUCCESS (0) if successful. 1341 */ 1342 tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_get 1343 (const tng_trajectory_t tng_data, 1344 int64_t *exp); 1345 1346 /** 1347 * @brief Set the exponent used for distances in the trajectory. 1348 * @param tng_data is the trajectory of which to set the unit exponent. 1349 * @param exp is the distance unit exponent to use. 1350 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1351 * must be initialised before using it. 1352 * @details Example: If the distances are specified in nm (default) exp is -9. 1353 * If the distances are specified in Å exp is -10. 1354 * @return TNG_SUCCESS (0) if successful. 1355 */ 1356 tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_set 1357 (const tng_trajectory_t tng_data, 1358 const int64_t exp); 1359 1360 /** 1361 * @brief Get the number of frames per frame set. 1362 * @param tng_data is the trajectory from which to get the number of frames 1363 * per frame set. 1364 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1365 * must be initialised before using it. 1366 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. 1367 * @param n is pointing to a value set to the number of frames per frame set. 1368 * @return TNG_SUCCESS (0) if successful. 1369 */ 1370 tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_get 1371 (const tng_trajectory_t tng_data, 1372 int64_t *n); 1373 1374 /** 1375 * @brief Set the number of frames per frame set. 1376 * @param tng_data is the trajectory of which to set the number of frames 1377 * per frame set. 1378 * @param n is the number of frames per frame set. 1379 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1380 * must be initialised before using it. 1381 * @details This does not affect already existing frame sets. For 1382 * consistency the number of frames per frame set should be set 1383 * betfore creating any frame sets. 1384 * @return TNG_SUCCESS (0) if successful. 1385 */ 1386 tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_set 1387 (const tng_trajectory_t tng_data, 1388 const int64_t n); 1389 1390 /** 1391 * @brief Get the number of frame sets. 1392 * @details This updates tng_data->n_trajectory_frame_sets before returning it. 1393 * @param tng_data is the trajectory from which to get the number of frame sets. 1394 * @param n is pointing to a value set to the number of frame sets. 1395 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1396 * must be initialised before using it. 1397 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. 1398 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1399 * has occurred or TNG_CRITICAL (2) if a major error has occured. 1400 */ 1401 tng_function_status DECLSPECDLLEXPORT tng_num_frame_sets_get 1402 (const tng_trajectory_t tng_data, 1403 int64_t *n); 1404 1405 /** 1406 * @brief Get the current trajectory frame set. 1407 * @param tng_data is the trajectory from which to get the frame set. 1408 * @param frame_set_p will be set to point at the memory position of 1409 * the found frame set. 1410 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1411 * must be initialised before using it. 1412 * @return TNG_SUCCESS (0) if successful. 1413 */ 1414 tng_function_status DECLSPECDLLEXPORT tng_current_frame_set_get 1415 (const tng_trajectory_t tng_data, 1416 tng_trajectory_frame_set_t *frame_set_p); 1417 1418 /** 1419 * @brief Find the requested frame set number. 1420 * @param tng_data is the trajectory from which to get the frame set. 1421 * @param nr is the frame set number to search for. 1422 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1423 * must be initialised before using it. 1424 * @pre \code nr >= 0 \endcode The frame set number (nr) must be >= 0. 1425 * @details tng_data->current_trajectory_frame_set will contain the 1426 * found trajectory if successful. 1427 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1428 * has occurred or TNG_CRITICAL (2) if a major error has occured. 1429 */ 1430 tng_function_status DECLSPECDLLEXPORT tng_frame_set_nr_find 1431 (const tng_trajectory_t tng_data, 1432 const int64_t nr); 1433 1434 /** 1435 * @brief Find the frame set containing a specific frame. 1436 * @param tng_data is the trajectory from which to get the frame set. 1437 * @param frame is the frame number to search for. 1438 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1439 * must be initialised before using it. 1440 * @pre \code frame >= 0 \endcode The frame number must be >= 0. 1441 * @details tng_data->current_trajectory_frame_set will contain the 1442 * found trajectory if successful. 1443 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1444 * has occurred or TNG_CRITICAL (2) if a major error has occured. 1445 */ 1446 tng_function_status DECLSPECDLLEXPORT tng_frame_set_of_frame_find 1447 (const tng_trajectory_t tng_data, 1448 const int64_t frame); 1449 1450 /** 1451 * @brief Get the file position of the next frame set in the input file. 1452 * @param tng_data is a trajectory data container. 1453 * @param frame_set is the frame set of which to get the position of the 1454 * following frame set. 1455 * @param pos is pointing to a value set to the file position. 1456 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1457 * must be initialised before using it. 1458 * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer. 1459 * @return TNG_SUCCESS (0) if successful. 1460 */ 1461 tng_function_status DECLSPECDLLEXPORT tng_frame_set_next_frame_set_file_pos_get 1462 (const tng_trajectory_t tng_data, 1463 const tng_trajectory_frame_set_t frame_set, 1464 int64_t *pos); 1465 1466 /** 1467 * @brief Get the file position of the previous frame set in the input file. 1468 * @param tng_data is a trajectory data container. 1469 * @param frame_set is the frame set of which to get the position of the 1470 * previous frame set. 1471 * @param pos is pointing to a value set to the file position. 1472 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1473 * must be initialised before using it. 1474 * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer. 1475 * @return TNG_SUCCESS (0) if successful. 1476 */ 1477 tng_function_status DECLSPECDLLEXPORT tng_frame_set_prev_frame_set_file_pos_get 1478 (const tng_trajectory_t tng_data, 1479 const tng_trajectory_frame_set_t frame_set, 1480 int64_t *pos); 1481 1482 /** 1483 * @brief Get the first and last frames of the frame set. 1484 * @param tng_data is a trajectory data container. 1485 * @param frame_set is the frame set of which to get the frame range. 1486 * @param first_frame is set to the first frame of the frame set. 1487 * @param last_frame is set to the last frame of the frame set. 1488 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1489 * must be initialised before using it. 1490 * @pre \code first_frame != 0 \endcode The pointer to first_frame must 1491 * not be a NULL pointer. 1492 * @pre \code last_frame != 0 \endcode The pointer to last_frame must 1493 * not be a NULL pointer. 1494 * @return TNG_SUCCESS (0) if successful. 1495 */ 1496 tng_function_status DECLSPECDLLEXPORT tng_frame_set_frame_range_get 1497 (const tng_trajectory_t tng_data, 1498 const tng_trajectory_frame_set_t frame_set, 1499 int64_t *first_frame, 1500 int64_t *last_frame); 1501 1502 /** 1503 * @brief Allocate memory for and setup a molecule container. 1504 * @param tng_data is a trajectory data container. 1505 * @param molecule_p is a pointer to molecule to allocate and initialise. 1506 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 1507 * error has occured. 1508 */ 1509 tng_function_status DECLSPECDLLEXPORT tng_molecule_alloc(const tng_trajectory_t tng_data, 1510 tng_molecule_t *molecule_p); 1511 1512 /** 1513 * @brief Clean up a molecule container and free its allocated memory. 1514 * @param tng_data is a trajectory data container. 1515 * @param molecule_p is the molecule to destroy. 1516 * @details All allocated memory in the data structure is freed and also the memory 1517 * of the molecule itself. 1518 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 1519 * error has occured. 1520 */ 1521 tng_function_status DECLSPECDLLEXPORT tng_molecule_free(const tng_trajectory_t tng_data, 1522 tng_molecule_t *molecule_p); 1523 1524 /** 1525 * @brief Setup a molecule container. 1526 * @param tng_data is a trajectory data container. 1527 * @param molecule is the molecule to initialise. Memory must be preallocated. 1528 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 1529 * error has occured. 1530 */ 1531 tng_function_status DECLSPECDLLEXPORT tng_molecule_init 1532 (const tng_trajectory_t tng_data, 1533 const tng_molecule_t molecule); 1534 1535 /** 1536 * @brief Clean up a molecule container. 1537 * @param tng_data is a trajectory data container. 1538 * @param molecule is the molecule to destroy. 1539 * @details All allocated memory in the data structure is freed, but not the 1540 * memory of molecule itself. 1541 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 1542 * error has occured. 1543 */ 1544 tng_function_status DECLSPECDLLEXPORT tng_molecule_destroy 1545 (const tng_trajectory_t tng_data, 1546 const tng_molecule_t molecule); 1547 1548 /** 1549 * @brief Add a molecule to the trajectory. 1550 * @param tng_data is the trajectory data container containing the block.. 1551 * @param name is a pointer to the string containing the name of the new molecule. 1552 * @param molecule is a pointer to the newly created molecule. 1553 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1554 * must be initialised before using it. 1555 * @pre \code name != 0 \endcode The pointer to the name string 1556 * must not be a NULL pointer. 1557 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could 1558 * not be set properly or TNG_CRITICAL (2) if a major error has occured. 1559 */ 1560 tng_function_status DECLSPECDLLEXPORT tng_molecule_add 1561 (const tng_trajectory_t tng_data, 1562 const char *name, 1563 tng_molecule_t *molecule); 1564 1565 /** 1566 * @brief Add a molecule with a specific ID to the trajectory. 1567 * @param tng_data is the trajectory data container containing the block.. 1568 * @param name is a pointer to the string containing the name of the new molecule. 1569 * @param id is the ID of the created molecule. 1570 * @param molecule is a pointer to the newly created molecule. 1571 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1572 * must be initialised before using it. 1573 * @pre \code name != 0 \endcode The pointer to the name string 1574 * must not be a NULL pointer. 1575 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could 1576 * not be set properly or TNG_CRITICAL (2) if a major error has occured. 1577 */ 1578 tng_function_status DECLSPECDLLEXPORT tng_molecule_w_id_add 1579 (const tng_trajectory_t tng_data, 1580 const char *name, 1581 const int64_t id, 1582 tng_molecule_t *molecule); 1583 1584 /** 1585 * @brief Add an existing molecule (from a molecule container) to the trajectory. 1586 * @param tng_data is the trajectory data container containing the block.. 1587 * @param molecule is a pointer to the molecule to add to the trajectory and will 1588 * afterwards point to the molecule in the trajectory. 1589 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1590 * must be initialised before using it. 1591 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error 1592 * has occured. 1593 */ 1594 tng_function_status DECLSPECDLLEXPORT tng_molecule_existing_add 1595 (const tng_trajectory_t tng_data, 1596 tng_molecule_t *molecule); 1597 1598 /** 1599 * @brief Get the name of a molecule. 1600 * @param tng_data the trajectory containing the molecule. 1601 * @param molecule the molecule of which to get the name. 1602 * @param name the string to fill with the name of the molecule, 1603 * memory must be allocated before. 1604 * @param max_len maximum char length of the string, i.e. how much memory has 1605 * been reserved for name. This includes \0 terminating character. 1606 * @pre \code molecule != 0 \endcode The molecule must not be NULL. 1607 * @pre \code name != 0 \endcode The pointer to the name string 1608 * must not be a NULL pointer. 1609 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1610 * has occurred (source string longer than destination string). 1611 */ 1612 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_get 1613 (const tng_trajectory_t tng_data, 1614 const tng_molecule_t molecule, 1615 char *name, 1616 const int max_len); 1617 1618 /** 1619 * @brief Set the name of a molecule. 1620 * @param tng_data is the trajectory data container containing the molecule.. 1621 * @param molecule is the molecule to rename. 1622 * @param new_name is a string containing the wanted name. 1623 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1624 * must be initialised before using it. 1625 * @pre \code new_name != 0 \endcode The pointer to the name string 1626 * must not be a NULL pointer. 1627 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 1628 * error has occured. 1629 */ 1630 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_set 1631 (const tng_trajectory_t tng_data, 1632 const tng_molecule_t molecule, 1633 const char *new_name); 1634 1635 /** 1636 * @brief Get the count of a molecule. 1637 * @param tng_data is the trajectory data container containing the molecule.. 1638 * @param molecule is the molecule of which to get the count. 1639 * @param cnt is a pointer to the variable to be populated with the count. 1640 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1641 * must be initialised before using it. 1642 * @pre \code cnt != 0 \endcode The pointer to the molecule count 1643 * must not be a NULL pointer. 1644 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1645 * has occurred or TNG_CRITICAL (2) if a major error has occured. 1646 */ 1647 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_get 1648 (const tng_trajectory_t tng_data, 1649 const tng_molecule_t molecule, 1650 int64_t *cnt); 1651 1652 /** 1653 * @brief Set the count of a molecule. 1654 * @param tng_data is the trajectory data container containing the molecule.. 1655 * @param molecule is the molecule of which to set the count. 1656 * @param cnt is the number of instances of this molecule. 1657 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1658 * must be initialised before using it. 1659 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1660 * has occurred or TNG_CRITICAL (2) if a major error has occured. 1661 */ 1662 tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_set 1663 (const tng_trajectory_t tng_data, 1664 const tng_molecule_t molecule, 1665 const int64_t cnt); 1666 1667 /** 1668 * @brief Find a molecule. 1669 * @param tng_data is the trajectory data container containing the molecule. 1670 * @param name is a string containing the name of the molecule. If name is empty 1671 * only id will be used for finding the molecule. 1672 * @param id is the id of the molecule to look for. If id is -1 only the name of 1673 * the molecule will be used for finding the molecule. 1674 * @param molecule is a pointer to the molecule if it was found - otherwise 0. 1675 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1676 * must be initialised before using it. 1677 * @pre \code name != 0 \endcode The pointer to the name string 1678 * must not be a NULL pointer. 1679 * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the 1680 * molecule is not found. 1681 * @details If name is an empty string and id == -1 the first residue will 1682 * be found. 1683 */ 1684 tng_function_status DECLSPECDLLEXPORT tng_molecule_find 1685 (const tng_trajectory_t tng_data, 1686 const char *name, 1687 const int64_t id, 1688 tng_molecule_t *molecule); 1689 1690 /** 1691 * @brief Retrieve the molecule with specified index in the list of molecules. 1692 * @param tng_data is the trajectory data container containing the molecule. 1693 * @param index is the index (in tng_data->molecules) of the molecule to return 1694 * @param molecule is a pointer to the molecule if it was found - otherwise 0. 1695 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1696 * must be initialised before using it. 1697 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. 1698 * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the 1699 * molecule is not found. 1700 */ 1701 tng_function_status DECLSPECDLLEXPORT tng_molecule_of_index_get 1702 (const tng_trajectory_t tng_data, 1703 const int64_t index, 1704 tng_molecule_t *molecule); 1705 1706 /** 1707 * @brief Copy all molecules and the molecule counts from one TNG trajectory 1708 * to another. 1709 * @param tng_data_src is the source trajectory containing the molecular 1710 * system to copy. 1711 * @param tng_data_dest is the destination trajectory. 1712 * @pre \code tng_data_src != 0 \endcode The trajectory container (tng_data_src) 1713 * must be initialised before using it. 1714 * @pre \code tng_data_dest != 0 \endcode The trajectory container (tng_data_dest) 1715 * must be initialised before using it. 1716 * @details The molecular system in tng_data_dest will be overwritten. 1717 * @return TNG_SUCCESS(0) if the copying is successful, TNG_FAILURE if a minor 1718 * error has occured or TNG_CRITICAL(2) if a major error has occured. 1719 */ 1720 tng_function_status DECLSPECDLLEXPORT tng_molecule_system_copy(const tng_trajectory_t tng_data_src, 1721 const tng_trajectory_t tng_data_dest); 1722 1723 /** 1724 * @brief Get the number of chains in a molecule. 1725 * @param tng_data is the trajectory containing the molecule. 1726 * @param molecule is the molecule of which to get the number of chains. 1727 * @param n is pointing to a value set to the number of chains. 1728 * @pre \code molecule != 0 \endcode The molecule must not be NULL. 1729 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. 1730 * @return TNG_SUCCESS (0) if successful. 1731 */ 1732 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_chains_get 1733 (const tng_trajectory_t tng_data, 1734 const tng_molecule_t molecule, 1735 int64_t *n); 1736 1737 /** 1738 * @brief Retrieve the chain of a molecule with specified index in the list 1739 * of chains. 1740 * @param tng_data is the trajectory data container containing the molecule. 1741 * @param index is the index (in molecule->chains) of the chain to return 1742 * @param molecule is the molecule from which to get the chain. 1743 * @param chain is a pointer to the chain if it was found - otherwise 0. 1744 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. 1745 * @pre \code chain != 0 \endcode chain must not be a NULL pointer. 1746 * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the 1747 * chain is not found. 1748 */ 1749 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_of_index_get 1750 (const tng_trajectory_t tng_data, 1751 const tng_molecule_t molecule, 1752 const int64_t index, 1753 tng_chain_t *chain); 1754 1755 /** 1756 * @brief Get the number of residues in a molecule. 1757 * @param tng_data is the trajectory containing the molecule. 1758 * @param molecule is the molecule of which to get the number residues. 1759 * @param n is pointing to a value set to the number of residues. 1760 * @pre \code molecule != 0 \endcode The molecule must not be NULL. 1761 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. 1762 * @return TNG_SUCCESS (0) if successful. 1763 */ 1764 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_residues_get 1765 (const tng_trajectory_t tng_data, 1766 const tng_molecule_t molecule, 1767 int64_t *n); 1768 1769 /** 1770 * @brief Retrieve the residue of a molecule with specified index in the list 1771 * of chains. 1772 * @param tng_data is the trajectory data container containing the molecule. 1773 * @param index is the index (in molecule->residues) of the residue to return 1774 * @param molecule is the molecule from which to get the residue. 1775 * @param residue is a pointer to the residue if it was found - otherwise 0. 1776 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. 1777 * @pre \code residue != 0 \endcode residue must not be a NULL pointer. 1778 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the 1779 * residue is not found. 1780 */ 1781 tng_function_status DECLSPECDLLEXPORT tng_molecule_residue_of_index_get 1782 (const tng_trajectory_t tng_data, 1783 const tng_molecule_t molecule, 1784 const int64_t index, 1785 tng_residue_t *residue); 1786 1787 /** 1788 * @brief Get the number of atoms in a molecule. 1789 * @param tng_data is the trajectory containing the molecule. 1790 * @param molecule is the molecule of which to get the number of atoms. 1791 * @param n is pointing to a value set to the number of atoms. 1792 * @pre \code molecule != 0 \endcode The molecule must not be NULL. 1793 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. 1794 * @return TNG_SUCCESS (0) if successful. 1795 */ 1796 tng_function_status DECLSPECDLLEXPORT tng_molecule_num_atoms_get 1797 (const tng_trajectory_t tng_data, 1798 const tng_molecule_t molecule, 1799 int64_t *n); 1800 1801 /** 1802 * @brief Retrieve the atom of a molecule with specified index in the list 1803 * of atoms. 1804 * @param tng_data is the trajectory data container containing the molecule. 1805 * @param index is the index (in molecule->atoms) of the atom to return 1806 * @param molecule is the molecule from which to get the atom. 1807 * @param atom is a pointer to the atom if it was found - otherwise 0. 1808 * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. 1809 * @pre \code atom != 0 \endcode atom must not be a NULL pointer. 1810 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the 1811 * atom is not found. 1812 */ 1813 tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_of_index_get 1814 (const tng_trajectory_t tng_data, 1815 const tng_molecule_t molecule, 1816 const int64_t index, 1817 tng_atom_t *atom); 1818 1819 /** 1820 * @brief Find a chain in a molecule. 1821 * @param tng_data is the trajectory data container containing the molecule. 1822 * @param molecule is the molecule in which to search for the chain. 1823 * @param name is a string containing the name of the chain. If name is empty 1824 * only id will be used for finding the chain. 1825 * @param id is the id of the chain to look for. If id is -1 only the name of 1826 * the chain will be used for finding the chain. 1827 * @param chain is a pointer to the chain if it was found - otherwise 0. 1828 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1829 * must be initialised before using it. 1830 * @pre \code name != 0 \endcode The pointer to the name string 1831 * must not be a NULL pointer. 1832 * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the 1833 * chain is not found. 1834 * @details If name is an empty string and id == -1 the first residue will 1835 * be found. 1836 */ 1837 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_find 1838 (const tng_trajectory_t tng_data, 1839 const tng_molecule_t molecule, 1840 const char *name, 1841 const int64_t id, 1842 tng_chain_t *chain); 1843 1844 /** 1845 * @brief Add a chain to a molecule. 1846 * @param tng_data is the trajectory data container containing the molecule.. 1847 * @param molecule is the molecule to add a chain to. 1848 * @param name is a string containing the name of the chain. 1849 * @param chain is a pointer to the newly created chain. 1850 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1851 * must be initialised before using it. 1852 * @pre \code name != 0 \endcode The pointer to the name string 1853 * must not be a NULL pointer. 1854 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could 1855 * not be set properly or TNG_CRITICAL (2) if a major error has occured. 1856 */ 1857 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_add 1858 (const tng_trajectory_t tng_data, 1859 const tng_molecule_t molecule, 1860 const char *name, 1861 tng_chain_t *chain); 1862 1863 /** 1864 * @brief Add a chain with a specific id to a molecule. 1865 * @param tng_data is the trajectory data container containing the molecule.. 1866 * @param molecule is the molecule to add a chain to. 1867 * @param name is a string containing the name of the chain. 1868 * @param id is the ID of the created chain. 1869 * @param chain is a pointer to the newly created chain. 1870 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1871 * must be initialised before using it. 1872 * @pre \code name != 0 \endcode The pointer to the name string 1873 * must not be a NULL pointer. 1874 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could 1875 * not be set properly or TNG_CRITICAL (2) if a major error has occured. 1876 */ 1877 tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_w_id_add 1878 (const tng_trajectory_t tng_data, 1879 const tng_molecule_t molecule, 1880 const char *name, 1881 const int64_t id, 1882 tng_chain_t *chain); 1883 1884 /** 1885 * @brief Add a bond between two atoms to a molecule. 1886 * @param tng_data is the trajectory data container containing the molecule. 1887 * @param molecule is the molecule containing the atoms to connect. 1888 * @param from_atom_id is the id of one of the two atoms in the bond. 1889 * @param to_atom_id is the id of the other atom in the bond. 1890 * @param bond is a pointer to the newly created bond. 1891 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 1892 * must be initialised before using it. 1893 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (!) if a minor error 1894 * has occured or TNG_CRITICAL (2) if a major error has occured. 1895 */ 1896 tng_function_status DECLSPECDLLEXPORT tng_molecule_bond_add 1897 (const tng_trajectory_t tng_data, 1898 const tng_molecule_t molecule, 1899 const int64_t from_atom_id, 1900 const int64_t to_atom_id, 1901 tng_bond_t *bond); 1902 1903 /** 1904 * @brief Find an atom in a molecule. 1905 * @param tng_data is the trajectory data container containing the molecule. 1906 * @param molecule is the molecule in which to search for the atom. 1907 * @param name is a string containing the name of the atom. If name is an 1908 * empty string only id will be used for searching. 1909 * @param id is the id of the atom to find. If id == -1 the first atom 1910 * that matches the specified name will be found. 1911 * @param atom is a pointer to the atom if it was found - otherwise 0. 1912 * @pre \code name != 0 \endcode The pointer to the name string 1913 * must not be a NULL pointer. 1914 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the 1915 * atom is not found. 1916 * @details If name is an empty string and id == -1 the first residue will 1917 * be found. 1918 */ 1919 tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_find 1920 (const tng_trajectory_t tng_data, 1921 const tng_molecule_t molecule, 1922 const char *name, 1923 const int64_t id, 1924 tng_atom_t *atom); 1925 1926 /** 1927 * @brief Get the name of a chain. 1928 * @param tng_data the trajectory containing the chain. 1929 * @param chain the chain of which to get the name. 1930 * @param name the string to fill with the name of the chain, 1931 * memory must be allocated before. 1932 * @param max_len maximum char length of the string, i.e. how much memory has 1933 * been reserved for name. This includes \0 terminating character. 1934 * @pre \code chain != 0 \endcode The chain must not be NULL. 1935 * @pre \code name != 0 \endcode The pointer to the name string 1936 * must not be a NULL pointer. 1937 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 1938 * has occurred (source string longer than destination string). 1939 */ 1940 tng_function_status DECLSPECDLLEXPORT tng_chain_name_get 1941 (const tng_trajectory_t tng_data, 1942 const tng_chain_t chain, 1943 char *name, 1944 const int max_len); 1945 1946 /** 1947 * @brief Set the name of a chain. 1948 * @param tng_data is the trajectory data container containing the atom.. 1949 * @param chain is the chain to rename. 1950 * @param new_name is a string containing the wanted name. 1951 * @pre \code new_name != 0 \endcode The pointer to the name string 1952 * must not be a NULL pointer. 1953 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 1954 * error has occured. 1955 */ 1956 tng_function_status DECLSPECDLLEXPORT tng_chain_name_set 1957 (const tng_trajectory_t tng_data, 1958 const tng_chain_t chain, 1959 const char *new_name); 1960 1961 /** 1962 * @brief Get the number of residues in a molecule chain. 1963 * @param tng_data is the trajectory containing the chain. 1964 * @param chain is the chain of which to get the number of residues. 1965 * @param n is pointing to a value set to the number of residues. 1966 * @pre \code chain != 0 \endcode The chain must not be NULL. 1967 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. 1968 * @return TNG_SUCCESS (0) if successful. 1969 */ 1970 tng_function_status DECLSPECDLLEXPORT tng_chain_num_residues_get 1971 (const tng_trajectory_t tng_data, 1972 const tng_chain_t chain, 1973 int64_t *n); 1974 1975 /** 1976 * @brief Retrieve the residue of a chain with specified index in the list 1977 * of residues. 1978 * @param tng_data is the trajectory data container containing the chain. 1979 * @param index is the index (in chain->residues) of the residue to return 1980 * @param chain is the chain from which to get the residue. 1981 * @param residue is a pointer to the residue if it was found - otherwise 0. 1982 * @pre \code chain != 0 \endcode chain must not be a NULL pointer. 1983 * @pre \code residue != 0 \endcode residue must not be a NULL pointer. 1984 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the 1985 * residue is not found. 1986 */ 1987 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_of_index_get 1988 (const tng_trajectory_t tng_data, 1989 const tng_chain_t chain, 1990 const int64_t index, 1991 tng_residue_t *residue); 1992 1993 /** 1994 * @brief Find a residue in a chain. 1995 * @param tng_data is the trajectory data container containing the chain. 1996 * @param chain is the chain in which to search for the residue. 1997 * @param name is a string containing the name of the residue. If name is an 1998 * empty string only id will be used for searching. 1999 * @param id is the id of the residue to find. If id == -1 the first residue 2000 * that matches the specified name will be found. 2001 * @param residue is a pointer to the residue if it was found - otherwise 0. 2002 * @pre \code name != 0 \endcode The pointer to the name string 2003 * must not be a NULL pointer. 2004 * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the 2005 * residue is not found. 2006 * @details If name is an empty string and id == -1 the first residue will 2007 * be found. 2008 */ 2009 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_find 2010 (const tng_trajectory_t tng_data, 2011 const tng_chain_t chain, 2012 const char *name, 2013 const int64_t id, 2014 tng_residue_t *residue); 2015 2016 /** 2017 * @brief Add a residue to a chain. 2018 * @param tng_data is the trajectory data container containing the chain.. 2019 * @param chain is the chain to add a residue to. 2020 * @param name is a string containing the name of the residue. 2021 * @param residue is a pointer to the newly created residue. 2022 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2023 * must be initialised before using it. 2024 * @pre \code name != 0 \endcode The pointer to the name string 2025 * must not be a NULL pointer. 2026 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could 2027 * not be set properly or TNG_CRITICAL (2) if a major error has occured. 2028 */ 2029 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_add 2030 (const tng_trajectory_t tng_data, 2031 const tng_chain_t chain, 2032 const char *name, 2033 tng_residue_t *residue); 2034 2035 /** 2036 * @brief Add a residue with a specific ID to a chain. 2037 * @param tng_data is the trajectory data container containing the chain.. 2038 * @param chain is the chain to add a residue to. 2039 * @param name is a string containing the name of the residue. 2040 * @param id is the ID of the created residue. 2041 * @param residue is a pointer to the newly created residue. 2042 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2043 * must be initialised before using it. 2044 * @pre \code name != 0 \endcode The pointer to the name string 2045 * must not be a NULL pointer. 2046 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could 2047 * not be set properly or TNG_CRITICAL (2) if a major error has occured. 2048 */ 2049 tng_function_status DECLSPECDLLEXPORT tng_chain_residue_w_id_add 2050 (const tng_trajectory_t tng_data, 2051 const tng_chain_t chain, 2052 const char *name, 2053 const int64_t id, 2054 tng_residue_t *residue); 2055 2056 /** 2057 * @brief Get the name of a residue. 2058 * @param tng_data the trajectory containing the residue. 2059 * @param residue the residue of which to get the name. 2060 * @param name the string to fill with the name of the residue, 2061 * memory must be allocated before. 2062 * @param max_len maximum char length of the string, i.e. how much memory has 2063 * been reserved for name. This includes \0 terminating character. 2064 * @pre \code residue != 0 \endcode The residue must not be NULL. 2065 * @pre \code name != 0 \endcode The pointer to the name string 2066 * must not be a NULL pointer. 2067 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2068 * has occurred (source string longer than destination string). 2069 */ 2070 tng_function_status DECLSPECDLLEXPORT tng_residue_name_get 2071 (const tng_trajectory_t tng_data, 2072 const tng_residue_t residue, 2073 char *name, 2074 const int max_len); 2075 2076 /** 2077 * @brief Set the name of a residue. 2078 * @param tng_data is the trajectory data container containing the residue. 2079 * @param residue is the residue to rename. 2080 * @param new_name is a string containing the wanted name. 2081 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2082 * must be initialised before using it. 2083 * @pre \code new_name != 0 \endcode The new name to set (new_name) must 2084 * not be a NULL pointer. 2085 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 2086 * error has occured. 2087 */ 2088 tng_function_status DECLSPECDLLEXPORT tng_residue_name_set 2089 (const tng_trajectory_t tng_data, 2090 const tng_residue_t residue, 2091 const char *new_name); 2092 2093 /** 2094 * @brief Get the number of atoms in a residue. 2095 * @param tng_data is the trajectory containing the residue. 2096 * @param residue is the residue of which to get the number atoms. 2097 * @param n is pointing to a value set to the number of atoms. 2098 * @pre \code residue != 0 \endcode The residue must not be NULL. 2099 * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. 2100 * @return TNG_SUCCESS (0) if successful. 2101 */ 2102 tng_function_status DECLSPECDLLEXPORT tng_residue_num_atoms_get 2103 (const tng_trajectory_t tng_data, 2104 const tng_residue_t residue, 2105 int64_t *n); 2106 2107 /** 2108 * @brief Retrieve the atom of a residue with specified index in the list 2109 * of atoms. 2110 * @param tng_data is the trajectory data container containing the residue. 2111 * @param index is the index (in residue->atoms) of the atom to return 2112 * @param residue is the residue from which to get the atom. 2113 * @param atom is a pointer to the atom if it was found - otherwise 0. 2114 * @pre \code residue != 0 \endcode residue must not be a NULL pointer. 2115 * @pre \code atom != 0 \endcode atom must not be a NULL pointer. 2116 * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the 2117 * atom is not found. 2118 */ 2119 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_of_index_get 2120 (const tng_trajectory_t tng_data, 2121 const tng_residue_t residue, 2122 const int64_t index, 2123 tng_atom_t *atom); 2124 2125 /** 2126 * @brief Add an atom to a residue. 2127 * @param tng_data is the trajectory containing the residue. 2128 * @param residue is the residue to add an atom to. 2129 * @param atom_name is a string containing the name of the atom. 2130 * @param atom_type is a string containing the atom type of the atom. 2131 * @param atom is a pointer to the newly created atom. 2132 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2133 * must be initialised before using it. 2134 * @pre \code atom_name != 0 \endcode The pointer to the atom name string 2135 * must not be a NULL pointer. 2136 * @pre \code atom_type != 0 \endcode The pointer to the atom_type string 2137 * must not be a NULL pointer. 2138 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could 2139 * not be set properly or TNG_CRITICAL (2) if a major error has occured. 2140 */ 2141 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_add 2142 (const tng_trajectory_t tng_data, 2143 const tng_residue_t residue, 2144 const char *atom_name, 2145 const char *atom_type, 2146 tng_atom_t *atom); 2147 2148 /** 2149 * @brief Add an atom with a specific ID to a residue. 2150 * @param tng_data is the trajectory containing the residue. 2151 * @param residue is the residue to add an atom to. 2152 * @param atom_name is a string containing the name of the atom. 2153 * @param atom_type is a string containing the atom type of the atom. 2154 * @param id is the ID of the created atom. 2155 * @param atom is a pointer to the newly created atom. 2156 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2157 * must be initialised before using it. 2158 * @pre \code atom_name != 0 \endcode The pointer to the atom name string 2159 * must not be a NULL pointer. 2160 * @pre \code atom_type != 0 \endcode The pointer to the atom_type string 2161 * must not be a NULL pointer. 2162 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could 2163 * not be set properly or TNG_CRITICAL (2) if a major error has occured. 2164 */ 2165 tng_function_status DECLSPECDLLEXPORT tng_residue_atom_w_id_add 2166 (const tng_trajectory_t tng_data, 2167 const tng_residue_t residue, 2168 const char *atom_name, 2169 const char *atom_type, 2170 const int64_t id, 2171 tng_atom_t *atom); 2172 2173 /** 2174 * @brief Get the residue of an atom. 2175 * @param tng_data the trajectory containing the atom. 2176 * @param atom the atom of which to get the name. 2177 * @param residue is set to the residue of the atom. 2178 * @pre \code atom != 0 \endcode The atom must not be NULL. 2179 * @return TNG_SUCCESS (0) if successful. 2180 */ 2181 tng_function_status DECLSPECDLLEXPORT tng_atom_residue_get 2182 (const tng_trajectory_t tng_data, 2183 const tng_atom_t atom, 2184 tng_residue_t *residue); 2185 2186 /** 2187 * @brief Get the name of an atom. 2188 * @param tng_data the trajectory containing the atom. 2189 * @param atom the atom of which to get the name. 2190 * @param name the string to fill with the name of the atom, 2191 * memory must be allocated before. 2192 * @param max_len maximum char length of the string, i.e. how much memory has 2193 * been reserved for name. This includes \0 terminating character. 2194 * @pre \code atom != 0 \endcode The atom must not be NULL. 2195 * @pre \code name != 0 \endcode The pointer to the name string 2196 * must not be a NULL pointer. 2197 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2198 * has occurred (source string longer than destination string). 2199 */ 2200 tng_function_status DECLSPECDLLEXPORT tng_atom_name_get 2201 (const tng_trajectory_t tng_data, 2202 const tng_atom_t atom, 2203 char *name, 2204 const int max_len); 2205 2206 /** 2207 * @brief Set the name of an atom. 2208 * @param tng_data is the trajectory data container containing the atom. 2209 * @param atom is the atom to rename. 2210 * @param new_name is a string containing the wanted name. 2211 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2212 * must be initialised before using it. 2213 * @pre \code new_name != 0 \endcode The pointer to the name string 2214 * must not be a NULL pointer. 2215 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 2216 * error has occured. 2217 */ 2218 tng_function_status DECLSPECDLLEXPORT tng_atom_name_set 2219 (const tng_trajectory_t tng_data, 2220 const tng_atom_t atom, 2221 const char *new_name); 2222 2223 /** 2224 * @brief Get the type of an atom. 2225 * @param tng_data the trajectory containing the atom. 2226 * @param atom the atom of which to get the type. 2227 * @param type the string to fill with the type of the atom, 2228 * memory must be allocated before. 2229 * @param max_len maximum char length of the string, i.e. how much memory has 2230 * been reserved for type. This includes \0 terminating character. 2231 * @pre \code atom != 0 \endcode The atom must not be NULL. 2232 * @pre \code type != 0 \endcode The pointer to the type string 2233 * must not be a NULL pointer. 2234 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2235 * has occurred (source string longer than destination string). 2236 */ 2237 tng_function_status DECLSPECDLLEXPORT tng_atom_type_get 2238 (const tng_trajectory_t tng_data, 2239 const tng_atom_t atom, 2240 char *type, 2241 const int max_len); 2242 2243 /** 2244 * @brief Set the atom type of an atom. 2245 * @param tng_data is the trajectory data container containing the atom. 2246 * @param atom is the atom to change. 2247 * @param new_type is a string containing the atom type. 2248 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2249 * must be initialised before using it. 2250 * @pre \code new_type != 0 \endcode The pointer to the atom type string 2251 * must not be a NULL pointer. 2252 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 2253 * error has occured. 2254 */ 2255 tng_function_status DECLSPECDLLEXPORT tng_atom_type_set 2256 (const tng_trajectory_t tng_data, 2257 const tng_atom_t atom, 2258 const char *new_type); 2259 2260 /** 2261 * @brief Get the molecule name of real particle number (number in mol system). 2262 * @param tng_data is the trajectory data container containing the atom. 2263 * @param nr is the real number of the particle in the molecular system. 2264 * @param name is a string, which is set to the name of the molecule. Memory 2265 * must be reserved beforehand. 2266 * @param max_len is the maximum length of name. 2267 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2268 * must be initialised before using it. 2269 * @pre \code name != 0 \endcode The pointer to the name string 2270 * must not be a NULL pointer. 2271 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error 2272 * has occured. 2273 */ 2274 tng_function_status DECLSPECDLLEXPORT tng_molecule_name_of_particle_nr_get 2275 (const tng_trajectory_t tng_data, 2276 const int64_t nr, 2277 char *name, 2278 const int max_len); 2279 2280 /** 2281 * @brief Get the molecule id of real particle number (number in mol system). 2282 * @param tng_data is the trajectory data container containing the atom. 2283 * @param nr is the real number of the particle in the molecular system. 2284 * @param id is will be set to the id of the molecule. 2285 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2286 * must be initialised before using it. 2287 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer. 2288 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error 2289 * has occured. 2290 */ 2291 tng_function_status DECLSPECDLLEXPORT tng_molecule_id_of_particle_nr_get 2292 (const tng_trajectory_t tng_data, 2293 const int64_t nr, 2294 int64_t *id); 2295 2296 /** 2297 * @brief Get the bonds of the current molecular system. 2298 * @param tng_data is the trajectory data container containing the molecular 2299 * system. 2300 * @param n_bonds is set to the number of bonds in the molecular system and 2301 * thereby also the lengths of the two lists: from_atoms and to_atoms. 2302 * @param from_atoms is a list (memory reserved by this function) of atoms 2303 * (number of atom in mol system) in bonds. 2304 * @param to_atoms is a list (memory reserved by this function) of atoms 2305 * (number of atom in mol system) in bonds. 2306 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2307 * must be initialised before using it. 2308 * @pre \code n_bonds != 0 \endcode The pointer to n_bonds must not be a 2309 * NULL pointer. 2310 * @pre \code from_atoms != 0 \endcode The pointer to from_atoms must not 2311 * be a NULL pointer. 2312 * @pre \code to_atoms != 0 \endcode The pointer to to_atoms must not 2313 * be a NULL pointer. 2314 * @details The two lists of atoms use the same index, i.e. from_atoms[0] 2315 * and to_atoms[0] are linked with a bond. Since memory is reserved in 2316 * this function it must be freed afterwards. 2317 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2318 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2319 */ 2320 tng_function_status DECLSPECDLLEXPORT tng_molsystem_bonds_get 2321 (const tng_trajectory_t tng_data, 2322 int64_t *n_bonds, 2323 int64_t **from_atoms, 2324 int64_t **to_atoms); 2325 2326 /** 2327 * @brief Get the chain name of real particle number (number in mol system). 2328 * @param tng_data is the trajectory data container containing the atom. 2329 * @param nr is the real number of the particle in the molecular system. 2330 * @param name is a string, which is set to the name of the chain. Memory 2331 * must be reserved beforehand. 2332 * @param max_len is the maximum length of name. 2333 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2334 * must be initialised before using it. 2335 * @pre \code name != 0 \endcode The pointer to the name string 2336 * must not be a NULL pointer. 2337 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error 2338 * has occured. 2339 */ 2340 tng_function_status DECLSPECDLLEXPORT tng_chain_name_of_particle_nr_get 2341 (const tng_trajectory_t tng_data, 2342 const int64_t nr, 2343 char *name, 2344 const int max_len); 2345 2346 /** 2347 * @brief Get the residue name of real particle number (number in mol system). 2348 * @param tng_data is the trajectory data container containing the atom. 2349 * @param nr is the real number of the particle in the molecular system. 2350 * @param name is a string, which is set to the name of the residue. Memory 2351 * must be reserved beforehand. 2352 * @param max_len is the maximum length of name. 2353 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2354 * must be initialised before using it. 2355 * @pre \code name != 0 \endcode The pointer to the name string 2356 * must not be a NULL pointer. 2357 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error 2358 * has occured. 2359 */ 2360 tng_function_status DECLSPECDLLEXPORT tng_residue_name_of_particle_nr_get 2361 (const tng_trajectory_t tng_data, 2362 const int64_t nr, 2363 char *name, 2364 const int max_len); 2365 2366 /** 2367 * @brief Get the residue id (local to molecule) of real particle number 2368 * (number in mol system). 2369 * @param tng_data is the trajectory data container containing the atom. 2370 * @param nr is the real number of the particle in the molecular system. 2371 * @param id is a pointer to the variable, which will be set to the ID. 2372 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2373 * must be initialised before using it. 2374 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer. 2375 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error 2376 * has occured. 2377 */ 2378 tng_function_status DECLSPECDLLEXPORT tng_residue_id_of_particle_nr_get 2379 (const tng_trajectory_t tng_data, 2380 const int64_t nr, 2381 int64_t *id); 2382 2383 /** 2384 * @brief Get the residue id (based on other molecules and molecule counts) 2385 * of real particle number (number in mol system). 2386 * @param tng_data is the trajectory data container containing the atom. 2387 * @param nr is the real number of the particle in the molecular system. 2388 * @param id is a pointer to the variable, which will be set to the ID. 2389 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2390 * must be initialised before using it. 2391 * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer. 2392 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error 2393 * has occured. 2394 */ 2395 tng_function_status DECLSPECDLLEXPORT tng_global_residue_id_of_particle_nr_get 2396 (const tng_trajectory_t tng_data, 2397 const int64_t nr, 2398 int64_t *id); 2399 2400 /** 2401 * @brief Get the atom name of real particle number (number in mol system). 2402 * @param tng_data is the trajectory data container containing the atom. 2403 * @param nr is the real number of the particle in the molecular system. 2404 * @param name is a string, which is set to the name of the atom. Memory 2405 * must be reserved beforehand. 2406 * @param max_len is the maximum length of name. 2407 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2408 * must be initialised before using it. 2409 * @pre \code name != 0 \endcode The pointer to the name string 2410 * must not be a NULL pointer. 2411 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error 2412 * has occured. 2413 */ 2414 tng_function_status DECLSPECDLLEXPORT tng_atom_name_of_particle_nr_get 2415 (const tng_trajectory_t tng_data, 2416 const int64_t nr, 2417 char *name, 2418 const int max_len); 2419 2420 /** 2421 * @brief Get the atom type of real particle number (number in mol system). 2422 * @param tng_data is the trajectory data container containing the atom. 2423 * @param nr is the real number of the particle in the molecular system. 2424 * @param type is a string, which is set to the type of the atom. Memory 2425 * must be reserved beforehand. 2426 * @param max_len is the maximum length of type. 2427 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2428 * must be initialised before using it. 2429 * @pre \code type != 0 \endcode The pointer to the type string 2430 * must not be a NULL pointer. 2431 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error 2432 * has occured. 2433 */ 2434 tng_function_status DECLSPECDLLEXPORT tng_atom_type_of_particle_nr_get 2435 (const tng_trajectory_t tng_data, 2436 const int64_t nr, 2437 char *type, 2438 const int max_len); 2439 2440 /** 2441 * @brief Add a particle mapping table. 2442 * @details Each particle mapping table will be written as a separate block, 2443 * followed by the data blocks for the corresponding particles. In most cases 2444 * there is one particle mapping block for each thread writing the trajectory. 2445 * @param tng_data is the trajectory, with the frame set to which to add 2446 * the mapping block. 2447 * @details The mapping information is added to the currently active frame set 2448 * of tng_data 2449 * @param num_first_particle is the first particle number of this mapping 2450 * block. 2451 * @param n_particles is the number of particles in this mapping block. 2452 * @param mapping_table is a list of the real particle numbers (i.e. the numbers 2453 * used in the molecular system). The list is n_particles long. 2454 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2455 * must be initialised before using it. 2456 * @details mapping_table[0] is the real particle number of the first particle 2457 * in the following data blocks. 2458 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2459 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2460 */ 2461 tng_function_status DECLSPECDLLEXPORT tng_particle_mapping_add 2462 (const tng_trajectory_t tng_data, 2463 const int64_t num_first_particle, 2464 const int64_t n_particles, 2465 const int64_t *mapping_table); 2466 2467 /** 2468 * @brief Remove all particle mappings (in memory) from the current frame set. 2469 * @details Clears the currently setup particle mappings of the current frame 2470 * set. 2471 * @param tng_data is the trajectory, with the frame set of which to clear 2472 * all particle mappings. 2473 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2474 * must be initialised before using it. 2475 * @return TNG_SUCCESS (0) if successful. 2476 */ 2477 tng_function_status DECLSPECDLLEXPORT tng_frame_set_particle_mapping_free 2478 (const tng_trajectory_t tng_data); 2479 2480 /** 2481 * @brief Read the header blocks from the input_file of tng_data. 2482 * @details The trajectory blocks must be read separately and iteratively in chunks 2483 * to fit in memory. 2484 * @param tng_data is a trajectory data container. 2485 * @details tng_data->input_file_path specifies 2486 * which file to read from. If the file (input_file) is not open it will be 2487 * opened. 2488 * @param hash_mode is an option to decide whether to use the md5 hash or not. 2489 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be 2490 * compared to the md5 hash of the read contents to ensure valid data. 2491 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2492 * must be initialised before using it. 2493 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 2494 * error has occured. 2495 */ 2496 tng_function_status DECLSPECDLLEXPORT tng_file_headers_read 2497 (const tng_trajectory_t tng_data, 2498 const char hash_mode); 2499 2500 /** 2501 * @brief Write the header blocks to the output_file of tng_data. 2502 * @details The trajectory blocks must be written separately and iteratively in chunks 2503 * to fit in memory. 2504 * @param tng_data is a trajectory data container. 2505 * @details tng_data->output_file_path 2506 * specifies which file to write to. If the file (output_file) is not open it 2507 * will be opened. 2508 * @param hash_mode is an option to decide whether to use the md5 hash or not. 2509 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. 2510 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2511 * must be initialised before using it. 2512 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 2513 * error has occured. 2514 */ 2515 tng_function_status DECLSPECDLLEXPORT tng_file_headers_write 2516 (const tng_trajectory_t tng_data, 2517 const char hash_mode); 2518 2519 /** 2520 * @brief Read one (the next) block (of any kind) from the input_file of tng_data. 2521 * @param tng_data is a trajectory data container. 2522 * @details tng_data->input_file_path specifies 2523 * which file to read from. If the file (input_file) is not open it will be 2524 * opened. 2525 * @param block_data is a pointer to the struct which will be populated with the 2526 * data. 2527 * @details If block_data->input_file_pos > 0 it is the position from where the 2528 * reading starts otherwise it starts from the current position. 2529 * @param hash_mode is an option to decide whether to use the md5 hash or not. 2530 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be 2531 * compared to the md5 hash of the read contents to ensure valid data. 2532 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2533 * must be initialised before using it. 2534 * @pre \code block != 0 \endcode The block container (block) must be 2535 * initialised before using it. 2536 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2537 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2538 */ 2539 tng_function_status DECLSPECDLLEXPORT tng_block_read_next 2540 (const tng_trajectory_t tng_data, 2541 const tng_gen_block_t block_data, 2542 const char hash_mode); 2543 2544 /** 2545 * @brief Read one frame set, including all particle mapping blocks and data 2546 * blocks, starting from the current file position. 2547 * @param tng_data is a trajectory data container. 2548 * @param hash_mode is an option to decide whether to use the md5 hash or not. 2549 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be 2550 * compared to the md5 hash of the read contents to ensure valid data. 2551 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2552 * must be initialised before using it. 2553 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2554 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2555 */ 2556 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read 2557 (const tng_trajectory_t tng_data, 2558 const char hash_mode); 2559 2560 /** 2561 * @brief Read data from the current frame set from the input_file. Only read 2562 * particle mapping and data blocks matching the specified block_id. 2563 * @param tng_data is a trajectory data container. 2564 * @details tng_data->input_file_path specifies 2565 * which file to read from. If the file (input_file) is not open it will be 2566 * opened. 2567 * @param hash_mode is an option to decide whether to use the md5 hash or not. 2568 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be 2569 * compared to the md5 hash of the read contents to ensure valid data. 2570 * @param block_id is the ID of the data block to read from file. 2571 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2572 * must be initialised before using it. 2573 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2574 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2575 */ 2576 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_current_only_data_from_block_id 2577 (const tng_trajectory_t tng_data, 2578 const char hash_mode, 2579 const int64_t block_id); 2580 2581 /** 2582 * @brief Read one (the next) frame set, including particle mapping and related data blocks 2583 * from the input_file of tng_data. 2584 * @param tng_data is a trajectory data container. 2585 * @details tng_data->input_file_path specifies 2586 * which file to read from. If the file (input_file) is not open it will be 2587 * opened. 2588 * @param hash_mode is an option to decide whether to use the md5 hash or not. 2589 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be 2590 * compared to the md5 hash of the read contents to ensure valid data. 2591 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2592 * must be initialised before using it. 2593 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2594 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2595 */ 2596 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next 2597 (const tng_trajectory_t tng_data, 2598 const char hash_mode); 2599 2600 /** 2601 * @brief Read one (the next) frame set, including particle mapping and data blocks with a 2602 * specific block id from the input_file of tng_data. 2603 * @param tng_data is a trajectory data container. 2604 * @details tng_data->input_file_path specifies 2605 * which file to read from. If the file (input_file) is not open it will be 2606 * opened. 2607 * @param hash_mode is an option to decide whether to use the md5 hash or not. 2608 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be 2609 * compared to the md5 hash of the read contents to ensure valid data. 2610 * @param block_id is the ID number of the blocks that should be read from file. 2611 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2612 * must be initialised before using it. 2613 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2614 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2615 */ 2616 tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next_only_data_from_block_id 2617 (const tng_trajectory_t tng_data, 2618 const char hash_mode, 2619 const int64_t block_id); 2620 2621 /** 2622 * @brief Write one frame set, including mapping and related data blocks 2623 * to the output_file of tng_data. 2624 * @param tng_data is a trajectory data container. 2625 * @details tng_data->output_file_path specifies 2626 * which file to write to. If the file (output_file) is not open it will be 2627 * opened. 2628 * @param hash_mode is an option to decide whether to use the md5 hash or not. 2629 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. 2630 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2631 * must be initialised before using it. 2632 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2633 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2634 */ 2635 tng_function_status DECLSPECDLLEXPORT tng_frame_set_write 2636 (const tng_trajectory_t tng_data, 2637 const char hash_mode); 2638 2639 /** 2640 * @brief Write one frame set even if it does not have as many frames as 2641 * expected. The function also writes mapping and related data blocks 2642 * to the output_file of tng_data. 2643 * @param tng_data is a trajectory data container. 2644 * @details tng_data->output_file_path specifies 2645 * which file to write to. If the file (output_file) is not open it will be 2646 * opened. 2647 * @param hash_mode is an option to decide whether to use the md5 hash or not. 2648 * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. 2649 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2650 * must be initialised before using it. 2651 * @details The number of frames in the frame set is set to the number of 2652 * frames of the data blocks before writing it to disk. 2653 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2654 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2655 */ 2656 tng_function_status DECLSPECDLLEXPORT tng_frame_set_premature_write 2657 (const tng_trajectory_t tng_data, 2658 const char hash_mode); 2659 2660 /** 2661 * @brief Create and initialise a frame set. 2662 * @details Particle mappings are retained from previous frame set (if any). 2663 * To explicitly clear particle mappings use tng_frame_set_particle_mapping_free(). 2664 * @param tng_data is the trajectory data container in which to add the frame 2665 * set. 2666 * @param first_frame is the first frame of the frame set. 2667 * @param n_frames is the number of frames in the frame set. 2668 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2669 * must be initialised before using it. 2670 * @pre \code first_frame >= 0 \endcode The first frame must not be negative. 2671 * @pre \code n_frames >= 0 \endcode The number of frames must not be negative. 2672 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2673 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2674 */ 2675 tng_function_status DECLSPECDLLEXPORT tng_frame_set_new 2676 (const tng_trajectory_t tng_data, 2677 const int64_t first_frame, 2678 const int64_t n_frames); 2679 2680 /** 2681 * @brief Create and initialise a frame set with the time of the first frame 2682 * specified. 2683 * @param tng_data is the trajectory data container in which to add the frame 2684 * set. 2685 * @param first_frame is the first frame of the frame set. 2686 * @param n_frames is the number of frames in the frame set. 2687 * @param first_frame_time is the time stamp of the first frame (in seconds). 2688 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2689 * must be initialised before using it. 2690 * @pre \code first_frame >= 0 \endcode The first frame must not be negative. 2691 * @pre \code n_frames >= 0 \endcode The number of frames must not be negative. 2692 * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame 2693 * must not be negative. 2694 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2695 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2696 */ 2697 tng_function_status DECLSPECDLLEXPORT tng_frame_set_with_time_new 2698 (const tng_trajectory_t tng_data, 2699 const int64_t first_frame, 2700 const int64_t n_frames, 2701 const double first_frame_time); 2702 2703 /** 2704 * @brief Set the time stamp of the first frame of the current frame set. 2705 * @param tng_data is the trajectory containing the frame set. 2706 * @param first_frame_time is the time stamp of the first frame in the 2707 * frame set. 2708 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2709 * must be initialised before using it. 2710 * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame 2711 * must not be negative. 2712 * @return TNG_SUCCESS (0) if successful. 2713 */ 2714 tng_function_status DECLSPECDLLEXPORT tng_frame_set_first_frame_time_set 2715 (const tng_trajectory_t tng_data, 2716 const double first_frame_time); 2717 2718 /** 2719 * @brief Read the number of the first frame of the next frame set. 2720 * @param tng_data is the trajectory containing the frame set. 2721 * @param frame is set to the frame number of the first frame in the 2722 * next frame set. 2723 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2724 * must be initialised before using it. 2725 * @pre \code tng_data->input_file != 0 \endcode An input file must be open 2726 * to find the next frame set. 2727 * @pre \code frame != 0 \endcode The pointer to the frame must not be a NULL 2728 * pointer. 2729 * @return TNG_SUCCESS(0) if successful, TNG_FAILURE(1) if there is no next 2730 * frame set or TNG_CRITICAL(2) if a major error has occured. 2731 */ 2732 tng_function_status DECLSPECDLLEXPORT tng_first_frame_nr_of_next_frame_set_get 2733 (const tng_trajectory_t tng_data, 2734 int64_t *frame); 2735 2736 /** 2737 * @brief Add a non-particle dependent data block. 2738 * @param tng_data is the trajectory data container in which to add the data 2739 * block 2740 * @param id is the block ID of the block to add. 2741 * @param block_name is a descriptive name of the block to add 2742 * @param datatype is the datatype of the data in the block (e.g. int/float) 2743 * @param block_type_flag indicates if this is a non-trajectory block (added 2744 * directly to tng_data) or if it is a trajectory block (added to the 2745 * frame set) 2746 * @param n_frames is the number of frames of the data block (automatically 2747 * set to 1 if adding a non-trajectory data block) 2748 * @param n_values_per_frame is how many values a stored each frame (e.g. 9 2749 * for a box shape block) 2750 * @param stride_length is how many frames are between each entry in the 2751 * data block 2752 * @param codec_id is the ID of the codec to compress the data. 2753 * @param new_data is an array of data values to add. 2754 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2755 * must be initialised before using it. 2756 * @pre \code block_name != 0 \endcode The pointer to the block name must 2757 * not be a NULL pointer. 2758 * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be 2759 * a positive integer. 2760 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2761 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2762 */ 2763 tng_function_status DECLSPECDLLEXPORT tng_data_block_add 2764 (const tng_trajectory_t tng_data, 2765 const int64_t id, 2766 const char *block_name, 2767 const char datatype, 2768 const char block_type_flag, 2769 int64_t n_frames, 2770 const int64_t n_values_per_frame, 2771 int64_t stride_length, 2772 const int64_t codec_id, 2773 void *new_data); 2774 2775 /** 2776 * @brief Add a particle dependent data block. 2777 * @param tng_data is the trajectory data container in which to add the data 2778 * block 2779 * @param id is the block ID of the block to add. 2780 * @param block_name is a descriptive name of the block to add 2781 * @param datatype is the datatype of the data in the block (e.g. int/float) 2782 * @param block_type_flag indicates if this is a non-trajectory block (added 2783 * directly to tng_data) or if it is a trajectory block (added to the 2784 * frame set) 2785 * @param n_frames is the number of frames of the data block (automatically 2786 * set to 1 if adding a non-trajectory data block) 2787 * @param n_values_per_frame is how many values a stored each frame (e.g. 9 2788 * for a box shape block) 2789 * @param stride_length is how many frames are between each entry in the 2790 * data block 2791 * @param num_first_particle is the number of the first particle stored 2792 * in this data block 2793 * @param n_particles is the number of particles stored in this data block 2794 * @param codec_id is the ID of the codec to compress the data. 2795 * @param new_data is an array of data values to add. 2796 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2797 * must be initialised before using it. 2798 * @pre \code block_name != 0 \endcode The pointer to the block name must 2799 * not be a NULL pointer. 2800 * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be 2801 * a positive integer. 2802 * @pre \code num_first_particle >= 0 \endcode The number of the 2803 * first particle must be >= 0. 2804 * @pre \code n_particles >= 0 \endcode n_particles must be >= 0. 2805 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2806 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2807 */ 2808 tng_function_status DECLSPECDLLEXPORT tng_particle_data_block_add 2809 (const tng_trajectory_t tng_data, 2810 const int64_t id, 2811 const char *block_name, 2812 const char datatype, 2813 const char block_type_flag, 2814 int64_t n_frames, 2815 const int64_t n_values_per_frame, 2816 int64_t stride_length, 2817 const int64_t num_first_particle, 2818 const int64_t n_particles, 2819 const int64_t codec_id, 2820 void *new_data); 2821 2822 /** @brief Get the name of a data block of a specific ID. 2823 * @param tng_data is the trajectory data container. 2824 * @param block_id is the ID of the data block of which to get the name. 2825 * @param name is a string, which is set to the name of the data block. 2826 * Memory must be reserved beforehand. 2827 * @param max_len is the maximum length of name. 2828 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2829 * must be initialised before using it. 2830 * @pre \code name != 0 \endcode The pointer to the name string 2831 * must not be a NULL pointer. 2832 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1) 2833 * if a minor error has occured or the data block is not found or 2834 * TNG_CRITICAL (2) if a major error has occured. 2835 */ 2836 tng_function_status DECLSPECDLLEXPORT tng_data_block_name_get 2837 (const tng_trajectory_t tng_data, 2838 const int64_t block_id, 2839 char *name, 2840 const int max_len); 2841 2842 /** @brief Get the dependency of a data block of a specific ID. 2843 * @param tng_data is the trajectory data container. 2844 * @param block_id is the ID of the data block of which to get the name. 2845 * @param block_dependency is a pointer to the dependency of the data block. 2846 * If the block is frame dependent it will be set to TNG_FRAME_DEPENDENT, 2847 * if it is particle dependent it will be set to TNG_PARTICLE_DEPENDENT and 2848 * if it is both it will be set to TNG_FRAME_DEPENDENT & TNG_PARTICLE_DEPENDENT. 2849 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2850 * must be initialised before using it. 2851 * @pre \code block_dependency != 0 \endcode The pointer to the block dependency 2852 * must not be a NULL pointer. 2853 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1) 2854 * if a minor error has occured or the data block is not found or 2855 * TNG_CRITICAL (2) if a major error has occured. 2856 */ 2857 tng_function_status DECLSPECDLLEXPORT tng_data_block_dependency_get 2858 (const tng_trajectory_t tng_data, 2859 const int64_t block_id, 2860 int *block_dependency); 2861 2862 /** @brief Get the number of values per frame of a data block of a specific ID. 2863 * @param tng_data is the trajectory data container. 2864 * @param block_id is the ID of the data block of which to get the name. 2865 * @param n_values_per_frame is a pointer set to the number of values per frame. 2866 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2867 * must be initialised before using it. 2868 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of values 2869 * per frame must not be a NULL pointer. 2870 * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1) 2871 * if a minor error has occured or the data block is not found or 2872 * TNG_CRITICAL (2) if a major error has occured. 2873 */ 2874 tng_function_status DECLSPECDLLEXPORT tng_data_block_num_values_per_frame_get 2875 (const tng_trajectory_t tng_data, 2876 const int64_t block_id, 2877 int64_t *n_values_per_frame); 2878 2879 /** 2880 * @brief Write data of one trajectory frame to the output_file of tng_data. 2881 * @param tng_data is a trajectory data container. tng_data->output_file_path 2882 * specifies which file to write to. If the file (output_file) is not open it 2883 * will be opened. 2884 * @param frame_nr is the index number of the frame to write. 2885 * @param block_id is the ID of the data block to write the data to. 2886 * @param values is an array of data to write. The length of the array should 2887 * equal n_values_per_frame. 2888 * @param hash_mode is an option to decide whether to use the md5 hash or not. 2889 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be 2890 * compared to the md5 hash of the read contents to ensure valid data. 2891 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2892 * must be initialised before using it. 2893 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. 2894 * @pre \code values != 0 \endcode The pointer to the values must not be a NULL 2895 * pointer. 2896 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2897 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2898 */ 2899 tng_function_status DECLSPECDLLEXPORT tng_frame_data_write 2900 (const tng_trajectory_t tng_data, 2901 const int64_t frame_nr, 2902 const int64_t block_id, 2903 const void *values, 2904 const char hash_mode); 2905 2906 /** 2907 * @brief Write particle data of one trajectory frame to the output_file of 2908 * tng_data. 2909 * @param tng_data is a trajectory data container. tng_data->output_file_path 2910 * specifies which file to write to. If the file (output_file) is not open it 2911 * will be opened. 2912 * @param frame_nr is the index number of the frame to write. 2913 * @param block_id is the ID of the data block to write the data to. 2914 * @param val_first_particle is the number of the first particle in the data 2915 * array. 2916 * @param val_n_particles is the number of particles in the data array. 2917 * @param values is a 1D-array of data to write. The length of the array should 2918 * equal n_particles * n_values_per_frame. 2919 * @param hash_mode is an option to decide whether to use the md5 hash or not. 2920 * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be 2921 * compared to the md5 hash of the read contents to ensure valid data. 2922 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2923 * must be initialised before using it. 2924 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. 2925 * @pre \code val_first_particle >= 0 \endcode The number of the 2926 * first particle must be >= 0. 2927 * @pre \code val_n_particles >= 0 \endcode The number of particles must be >= 0. 2928 * @pre \code values != 0 \endcode The pointer to the values must not be a NULL 2929 * pointer. 2930 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 2931 * has occurred or TNG_CRITICAL (2) if a major error has occured. 2932 */ 2933 tng_function_status DECLSPECDLLEXPORT tng_frame_particle_data_write 2934 (const tng_trajectory_t tng_data, 2935 const int64_t frame_nr, 2936 const int64_t block_id, 2937 const int64_t val_first_particle, 2938 const int64_t val_n_particles, 2939 const void *values, 2940 const char hash_mode); 2941 2942 /** 2943 * @brief Free data of an array of values (2D). 2944 * @param tng_data is a trajectory data container. 2945 * @param values is the 2D array to free and will be set to 0 afterwards. 2946 * @param n_frames is the number of frames in the data array. 2947 * @param n_values_per_frame is the number of values per frame in the data array. 2948 * @param type is the data type of the data in the array (e.g. int/float/char). 2949 * @details This function should not be used. The data_values union is obsolete. 2950 * This function also causes memory leaks, but its signature cannot be changed 2951 * without disturbing the API. 2952 * @return TNG_SUCCESS (0) if successful. 2953 */ 2954 tng_function_status DECLSPECDLLEXPORT tng_data_values_free 2955 (const tng_trajectory_t tng_data, 2956 union data_values **values, 2957 const int64_t n_frames, 2958 const int64_t n_values_per_frame, 2959 const char type); 2960 2961 /** 2962 * @brief Free data of an array of values (3D). 2963 * @param tng_data is a trajectory data container. 2964 * @param values is the array to free and will be set to 0 afterwards. 2965 * @param n_frames is the number of frames in the data array. 2966 * @param n_particles is the number of particles in the data array. 2967 * @param n_values_per_frame is the number of values per frame in the data array. 2968 * @param type is the data type of the data in the array (e.g. int/float/char). 2969 * @details This function should not be used. The data_values union is obsolete. 2970 * This function also causes memory leaks, but its signature cannot be changed 2971 * without disturbing the API. 2972 * @return TNG_SUCCESS (0) if successful. 2973 */ 2974 tng_function_status DECLSPECDLLEXPORT tng_particle_data_values_free 2975 (const tng_trajectory_t tng_data, 2976 union data_values ***values, 2977 const int64_t n_frames, 2978 const int64_t n_particles, 2979 const int64_t n_values_per_frame, 2980 const char type); 2981 2982 /** 2983 * @brief Retrieve non-particle data, from the last read frame set. Obsolete! 2984 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies 2985 * which file to read from. If the file (input_file) is not open it will be 2986 * opened. 2987 * @param block_id is the id number of the particle data block to read. 2988 * @param values is a pointer to a 2-dimensional array (memory unallocated), which 2989 * will be filled with data. The array will be sized 2990 * (n_frames * n_values_per_frame). 2991 * Since ***values is allocated in this function it is the callers 2992 * responsibility to free the memory. 2993 * @param n_frames is set to the number of frames in the returned data. This is 2994 * needed to properly reach and/or free the data afterwards. 2995 * @param n_values_per_frame is set to the number of values per frame in the data. 2996 * This is needed to properly reach and/or free the data afterwards. 2997 * @param type is set to the data type of the data in the array. 2998 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 2999 * must be initialised before using it. 3000 * @pre \code n_frames != 0 \endcode The pointer to the number of frames 3001 * must not be a NULL pointer. 3002 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of 3003 * values per frame must not be a NULL pointer. 3004 * @pre \code type != 0 \endcode The pointer to the data type must not 3005 * be a NULL pointer. 3006 * @details This function is obsolete and only retained for compatibility. Use 3007 * tng_data_vector_get() instead. 3008 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3009 * has occurred or TNG_CRITICAL (2) if a major error has occured. 3010 */ 3011 tng_function_status DECLSPECDLLEXPORT tng_data_get(const tng_trajectory_t tng_data, 3012 const int64_t block_id, 3013 union data_values ***values, 3014 int64_t *n_frames, 3015 int64_t *n_values_per_frame, 3016 char *type); 3017 3018 /** 3019 * @brief Retrieve a vector (1D array) of non-particle data, from the last read frame set. 3020 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies 3021 * which file to read from. If the file (input_file) is not open it will be 3022 * opened. 3023 * @param block_id is the id number of the particle data block to read. 3024 * @param values is a pointer to a 1-dimensional array (memory unallocated), which 3025 * will be filled with data. The length of the array will be 3026 * (n_frames_with_data (see stride_length) * n_values_per_frame). 3027 * Since **values is allocated in this function it is the callers 3028 * responsibility to free the memory. 3029 * @param n_frames is set to the number of particles in the returned data. This is 3030 * needed to properly reach and/or free the data afterwards. 3031 * @param stride_length is set to the stride length of the returned data. 3032 * @param n_values_per_frame is set to the number of values per frame in the data. 3033 * This is needed to properly reach and/or free the data afterwards. 3034 * @param type is set to the data type of the data in the array. 3035 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3036 * must be initialised before using it. 3037 * @pre \code n_frames != 0 \endcode The pointer to the number of frames 3038 * must not be a NULL pointer. 3039 * @pre \code stride_length != 0 \endcode The pointer to the stride length 3040 * must not be a NULL pointer. 3041 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of 3042 * values per frame must not be a NULL pointer. 3043 * @pre \code type != 0 \endcode The pointer to the data type must not 3044 * be a NULL pointer. 3045 * @details This does only work for numerical (int, float, double) data. 3046 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3047 * has occurred or TNG_CRITICAL (2) if a major error has occured. 3048 */ 3049 tng_function_status DECLSPECDLLEXPORT tng_data_vector_get 3050 (const tng_trajectory_t tng_data, 3051 const int64_t block_id, 3052 void **values, 3053 int64_t *n_frames, 3054 int64_t *stride_length, 3055 int64_t *n_values_per_frame, 3056 char *type); 3057 3058 /** 3059 * @brief Read and retrieve non-particle data, in a specific interval. Obsolete! 3060 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies 3061 * which file to read from. If the file (input_file) is not open it will be 3062 * opened. 3063 * @param block_id is the id number of the particle data block to read. 3064 * @param start_frame_nr is the index number of the first frame to read. 3065 * @param end_frame_nr is the index number of the last frame to read. 3066 * @param hash_mode is an option to decide whether to use the md5 hash or not. 3067 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be 3068 * compared to the md5 hash of the read contents to ensure valid data. 3069 * @param values is a pointer to a 2-dimensional array (memory unallocated), which 3070 * will be filled with data. The array will be sized 3071 * (n_frames * n_values_per_frame). 3072 * Since ***values is allocated in this function it is the callers 3073 * responsibility to free the memory. 3074 * @param n_values_per_frame is set to the number of values per frame in the data. 3075 * This is needed to properly reach and/or free the data afterwards. 3076 * @param type is set to the data type of the data in the array. 3077 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3078 * must be initialised before using it. 3079 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before 3080 * the last frame. 3081 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of 3082 * values per frame must not be a NULL pointer. 3083 * @pre \code type != 0 \endcode The pointer to the data type must not 3084 * be a NULL pointer. 3085 * @details This function is obsolete and only retained for compatibility. Use 3086 * tng_data_vector_interval_get() instead. 3087 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3088 * has occurred or TNG_CRITICAL (2) if a major error has occured. 3089 */ 3090 tng_function_status DECLSPECDLLEXPORT tng_data_interval_get 3091 (const tng_trajectory_t tng_data, 3092 const int64_t block_id, 3093 const int64_t start_frame_nr, 3094 const int64_t end_frame_nr, 3095 const char hash_mode, 3096 union data_values ***values, 3097 int64_t *n_values_per_frame, 3098 char *type); 3099 3100 /** 3101 * @brief Read and retrieve a vector (1D array) of non-particle data, 3102 * in a specific interval. 3103 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies 3104 * which file to read from. If the file (input_file) is not open it will be 3105 * opened. 3106 * @param block_id is the id number of the particle data block to read. 3107 * @param start_frame_nr is the index number of the first frame to read. 3108 * @param end_frame_nr is the index number of the last frame to read. 3109 * @param hash_mode is an option to decide whether to use the md5 hash or not. 3110 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be 3111 * compared to the md5 hash of the read contents to ensure valid data. 3112 * @param values is a pointer to a 1-dimensional array (memory unallocated), which 3113 * will be filled with data. The length of the array will be 3114 * (n_frames_with_data (see stride_length) * n_values_per_frame). 3115 * Since **values is allocated in this function it is the callers 3116 * responsibility to free the memory. 3117 * @param stride_length is set to the stride length (writing interval) of 3118 * the data. 3119 * @param n_values_per_frame is set to the number of values per frame in the data. 3120 * This is needed to properly reach and/or free the data afterwards. 3121 * @param type is set to the data type of the data in the array. 3122 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3123 * must be initialised before using it. 3124 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before 3125 * the last frame. 3126 * @pre \code stride_length != 0 \endcode The pointer to the stride length 3127 * must not be a NULL pointer. 3128 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of 3129 * values per frame must not be a NULL pointer. 3130 * @pre \code type != 0 \endcode The pointer to the data type must not 3131 * be a NULL pointer. 3132 * @details This does only work for numerical (int, float, double) data. 3133 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3134 * has occurred or TNG_CRITICAL (2) if a major error has occured. 3135 */ 3136 tng_function_status DECLSPECDLLEXPORT tng_data_vector_interval_get 3137 (const tng_trajectory_t tng_data, 3138 const int64_t block_id, 3139 const int64_t start_frame_nr, 3140 const int64_t end_frame_nr, 3141 const char hash_mode, 3142 void **values, 3143 int64_t *stride_length, 3144 int64_t *n_values_per_frame, 3145 char *type); 3146 3147 /** 3148 * @brief Retrieve particle data, from the last read frame set. Obsolete! 3149 * @details The particle dimension of the returned values array is translated 3150 * to real particle numbering, i.e. the numbering of the actual molecular 3151 * system. 3152 * @param tng_data is a trajectory data container. tng_data->input_file_path 3153 * specifies which file to read from. If the file (input_file) is not open it 3154 * will be opened. 3155 * @param block_id is the id number of the particle data block to read. 3156 * @param values is a pointer to a 3-dimensional array (memory unallocated), which 3157 * will be filled with data. The array will be sized 3158 * (n_frames * n_particles * n_values_per_frame). 3159 * Since ****values is allocated in this function it is the callers 3160 * responsibility to free the memory. 3161 * @param n_frames is set to the number of frames in the returned data. This is 3162 * needed to properly reach and/or free the data afterwards. 3163 * @param n_particles is set to the number of particles in the returned data. This is 3164 * needed to properly reach and/or free the data afterwards. 3165 * @param n_values_per_frame is set to the number of values per frame in the data. 3166 * This is needed to properly reach and/or free the data afterwards. 3167 * @param type is set to the data type of the data in the array. 3168 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3169 * must be initialised before using it. 3170 * @pre \code n_frames != 0 \endcode The pointer to the number of frames 3171 * must not be a NULL pointer. 3172 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must 3173 * not be a NULL pointer. 3174 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of 3175 * values per frame must not be a NULL pointer. 3176 * @pre \code type != 0 \endcode The pointer to the data type must not 3177 * be a NULL pointer. 3178 * @details This function is obsolete and only retained for compatibility. Use 3179 * tng_particle_data_vector_get() instead. 3180 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3181 * has occurred or TNG_CRITICAL (2) if a major error has occured. 3182 */ 3183 tng_function_status DECLSPECDLLEXPORT tng_particle_data_get 3184 (const tng_trajectory_t tng_data, 3185 const int64_t block_id, 3186 union data_values ****values, 3187 int64_t *n_frames, 3188 int64_t *n_particles, 3189 int64_t *n_values_per_frame, 3190 char *type); 3191 3192 /** 3193 * @brief Retrieve a vector (1D array) of particle data, from the last read frame set. 3194 * @details The particle dimension of the returned values array is translated 3195 * to real particle numbering, i.e. the numbering of the actual molecular 3196 * system. 3197 * @param tng_data is a trajectory data container. tng_data->input_file_path 3198 * specifies which file to read from. If the file (input_file) is not open it 3199 * will be opened. 3200 * @param block_id is the id number of the particle data block to read. 3201 * @param values is a pointer to a 1-dimensional array (memory unallocated), which 3202 * will be filled with data. The length of the array will be 3203 * (n_frames_with_data (see stride_length) * n_particles * n_values_per_frame). 3204 * Since **values is allocated in this function it is the callers 3205 * responsibility to free the memory. 3206 * @param n_frames is set to the number of frames in the returned data. This is 3207 * needed to properly reach and/or free the data afterwards. 3208 * @param stride_length is set to the stride length of the returned data. 3209 * @param n_particles is set to the number of particles in the returned data. This is 3210 * needed to properly reach and/or free the data afterwards. 3211 * @param n_values_per_frame is set to the number of values per frame in the data. 3212 * This is needed to properly reach and/or free the data afterwards. 3213 * @param type is set to the data type of the data in the array. 3214 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3215 * must be initialised before using it. 3216 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must 3217 * not be a NULL pointer. 3218 * @pre \code stride_length != 0 \endcode The pointer to the stride length 3219 * must not be a NULL pointer. 3220 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of 3221 * values per frame must not be a NULL pointer. 3222 * @pre \code type != 0 \endcode The pointer to the data type must not 3223 * be a NULL pointer. 3224 * @details This does only work for numerical (int, float, double) data. 3225 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3226 * has occurred or TNG_CRITICAL (2) if a major error has occured. 3227 */ 3228 tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_get 3229 (const tng_trajectory_t tng_data, 3230 const int64_t block_id, 3231 void **values, 3232 int64_t *n_frames, 3233 int64_t *stride_length, 3234 int64_t *n_particles, 3235 int64_t *n_values_per_frame, 3236 char *type); 3237 3238 /** 3239 * @brief Read and retrieve particle data, in a specific interval. Obsolete! 3240 * @details The particle dimension of the returned values array is translated 3241 * to real particle numbering, i.e. the numbering of the actual molecular 3242 * system. 3243 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies 3244 * which file to read from. If the file (input_file) is not open it will be 3245 * opened. 3246 * @param block_id is the id number of the particle data block to read. 3247 * @param start_frame_nr is the index number of the first frame to read. 3248 * @param end_frame_nr is the index number of the last frame to read. 3249 * @param hash_mode is an option to decide whether to use the md5 hash or not. 3250 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be 3251 * compared to the md5 hash of the read contents to ensure valid data. 3252 * @param values is a pointer to a 3-dimensional array (memory unallocated), which 3253 * will be filled with data. The array will be sized 3254 * (n_frames * n_particles * n_values_per_frame). 3255 * Since ****values is allocated in this function it is the callers 3256 * responsibility to free the memory. 3257 * @param n_particles is set to the number of particles in the returned data. This is 3258 * needed to properly reach and/or free the data afterwards. 3259 * @param n_values_per_frame is set to the number of values per frame in the data. 3260 * This is needed to properly reach and/or free the data afterwards. 3261 * @param type is set to the data type of the data in the array. 3262 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3263 * must be initialised before using it. 3264 * @pre \code n_frames != 0 \endcode The pointer to the number of frames 3265 * must not be a NULL pointer. 3266 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before 3267 * the last frame. 3268 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must 3269 * not be a NULL pointer. 3270 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of 3271 * values per frame must not be a NULL pointer. 3272 * @pre \code type != 0 \endcode The pointer to the data type must not 3273 * be a NULL pointer. 3274 * @details This function is obsolete and only retained for compatibility. Use 3275 * tng_particle_data_vector_interval_get() instead. 3276 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3277 * has occurred or TNG_CRITICAL (2) if a major error has occured. 3278 */ 3279 tng_function_status DECLSPECDLLEXPORT tng_particle_data_interval_get 3280 (const tng_trajectory_t tng_data, 3281 const int64_t block_id, 3282 const int64_t start_frame_nr, 3283 const int64_t end_frame_nr, 3284 const char hash_mode, 3285 union data_values ****values, 3286 int64_t *n_particles, 3287 int64_t *n_values_per_frame, 3288 char *type); 3289 3290 /** 3291 * @brief Read and retrieve a vector (1D array) particle data, in a 3292 * specific interval. 3293 * @details The particle dimension of the returned values array is translated 3294 * to real particle numbering, i.e. the numbering of the actual molecular 3295 * system. 3296 * @param tng_data is a trajectory data container. tng_data->input_file_path specifies 3297 * which file to read from. If the file (input_file) is not open it will be 3298 * opened. 3299 * @param block_id is the id number of the particle data block to read. 3300 * @param start_frame_nr is the index number of the first frame to read. 3301 * @param end_frame_nr is the index number of the last frame to read. 3302 * @param hash_mode is an option to decide whether to use the md5 hash or not. 3303 * If hash_mode == TNG_USE_HASH the md5 hash in the file will be 3304 * compared to the md5 hash of the read contents to ensure valid data. 3305 * @param values is a pointer to a 1-dimensional array (memory unallocated), which 3306 * will be filled with data. The length of the array will be 3307 * (n_frames_with_data (see stride_length) * n_particles * n_values_per_frame). 3308 * Since **values is allocated in this function it is the callers 3309 * responsibility to free the memory. 3310 * @param stride_length is set to the stride length (writing interval) of 3311 * the data. 3312 * @param n_particles is set to the number of particles in the returned data. This is 3313 * needed to properly reach and/or free the data afterwards. 3314 * @param n_values_per_frame is set to the number of values per frame in the data. 3315 * This is needed to properly reach and/or free the data afterwards. 3316 * @param type is set to the data type of the data in the array. 3317 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3318 * must be initialised before using it. 3319 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before 3320 * the last frame. 3321 * @pre \code n_particles != 0 \endcode The pointer to the number of particles must 3322 * not be a NULL pointer. 3323 * @pre \code stride_length != 0 \endcode The pointer to the stride length 3324 * must not be a NULL pointer. 3325 * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of 3326 * values per frame must not be a NULL pointer. 3327 * @pre \code type != 0 \endcode The pointer to the data type must not 3328 * be a NULL pointer. 3329 * @details This does only work for numerical (int, float, double) data. 3330 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3331 * has occurred or TNG_CRITICAL (2) if a major error has occured. 3332 */ 3333 tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_interval_get 3334 (const tng_trajectory_t tng_data, 3335 const int64_t block_id, 3336 const int64_t start_frame_nr, 3337 const int64_t end_frame_nr, 3338 const char hash_mode, 3339 void **values, 3340 int64_t *n_particles, 3341 int64_t *stride_length, 3342 int64_t *n_values_per_frame, 3343 char *type); 3344 3345 /** 3346 * @brief Get the stride length of a specific data (particle dependency does not matter) 3347 * block, either in the current frame set or of a specific frame. 3348 * @param tng_data is the trajectory data container. 3349 * @param block_id is the block ID of the data block, of which to retrieve the 3350 * stride length of the data. 3351 * @param frame is the frame from which to get the stride length. If frame is set to -1 3352 * no specific frame will be used, but instead the first frame, starting from the last read 3353 * frame set, containing the data block will be used. 3354 * @param stride_length is set to the value of the stride length of the data block. 3355 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3356 * has occurred or TNG_CRITICAL (2) if a major error has occured. 3357 */ 3358 tng_function_status DECLSPECDLLEXPORT tng_data_get_stride_length 3359 (const tng_trajectory_t tng_data, 3360 const int64_t block_id, 3361 int64_t frame, 3362 int64_t *stride_length); 3363 3364 /** 3365 * @brief Get the date and time of initial file creation in ISO format (string). 3366 * @param tng_data is a trajectory data container. 3367 * @param time is a pointer to the string in which the date will be stored. Memory 3368 * must be reserved beforehand. 3369 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3370 * must be initialised before using it. 3371 * @pre \code time != 0 \endcode The pointer to the time must not be a NULL 3372 * pointer. 3373 * @return TNG_SUCCESS (0) if successful. 3374 */ 3375 tng_function_status DECLSPECDLLEXPORT tng_time_get_str 3376 (const tng_trajectory_t tng_data, 3377 char *time); 3378 /** @} */ /* end of group1 */ 3379 3380 /** @defgroup group2 High-level API 3381 * These functions make it easier to access and output TNG data. They 3382 * are recommended unless there is a special reason to use the more 3383 * detailed functions available in the low-level API. 3384 * @{ 3385 */ 3386 3387 /** 3388 * @brief High-level function for opening and initializing a TNG trajectory. 3389 * @param filename is a string containing the name of the trajectory to open. 3390 * @param mode specifies the file mode of the trajectory. Can be set to 'r', 3391 * 'w' or 'a' for reading, writing or appending respectively. 3392 * @param tng_data_p is a pointer to the opened trajectory. This will be 3393 * allocated by the TNG library. The trajectory must be 3394 * closed by the user, whereby memory is freed. 3395 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3396 * must be initialised before using it. 3397 * @pre \code filename != 0 \endcode The pointer to the filename must not be a 3398 * NULL pointer. 3399 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3400 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3401 * has occured. 3402 */ 3403 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_open 3404 (const char *filename, 3405 const char mode, 3406 tng_trajectory_t *tng_data_p); 3407 3408 /** 3409 * @brief High-level function for closing a TNG trajectory. 3410 * @param tng_data_p is a pointer to the trajectory to close. The memory 3411 * will be freed after finalising the writing. 3412 * @return TNG_SUCCESS (0) if successful. 3413 */ 3414 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_close 3415 (tng_trajectory_t *tng_data_p); 3416 3417 /** 3418 * @brief High-level function for getting the time (in seconds) of a frame. 3419 * @param tng_data is the trajectory containing the frame. 3420 * @param frame_nr is the frame number of which to get the time. 3421 * @param time is set to the time (in seconds) of the specified frame. 3422 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3423 * must be initialised before using it. 3424 * @pre \code time != 0 \endcode The pointer to the time must not be a 3425 * NULL pointer. 3426 * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if a 3427 * minor error has occured. 3428 */ 3429 tng_function_status DECLSPECDLLEXPORT tng_util_time_of_frame_get 3430 (const tng_trajectory_t tng_data, 3431 const int64_t frame_nr, 3432 double *time); 3433 3434 /* 3435 * @brief High-level function for getting the molecules in the mol system. 3436 * @param tng_data is the trajectory containing the mol system. 3437 * @param n_mols is set to the number of molecules in the system. 3438 * @param molecule_cnt_list will be pointing to the list of counts of each molecule 3439 * in the mol system. 3440 * @param mols pointing to the list of molecules in the mol system. 3441 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3442 * must be initialised before using it. 3443 * @pre \code n_mols != 0 \endcode The pointer to the number of molecules must 3444 * not be a NULL pointer. 3445 * @return TNG_SUCCESS (0) if successful. 3446 */ 3447 /*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecules_get 3448 (const tng_trajectory_t tng_data, 3449 int64_t *n_mols, 3450 int64_t **molecule_cnt_list, 3451 tng_molecule_t *mols); 3452 */ 3453 /* 3454 * @brief High-level function for adding a molecule to the mol system. 3455 * @param tng_data is the trajectory containing the mol system. 3456 * @param name is the name of the molecule to add. 3457 * @param cnt is the count of the molecule. 3458 * @param mol is set to point to the newly created molecule. 3459 * @pre \code name != 0 \endcode The pointer to the name must not be a 3460 * NULL pointer. 3461 * @pre \code cnt >= 0 \endcode The requested count must be >= 0. 3462 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3463 * has occured or TNG_CRITICAL (2) if a major error has occured. 3464 */ 3465 /*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecule_add 3466 (const tng_trajectory_t tng_data, 3467 const char *name, 3468 const int64_t cnt, 3469 tng_molecule_t *mol); 3470 */ 3471 /* 3472 // tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_get 3473 // (const tng_trajectory_t tng_data, 3474 // const tng_molecule_t mol, 3475 // int64_t *n_particles, 3476 // char ***names, 3477 // char ***types, 3478 // char ***res_names, 3479 // int64_t **res_ids, 3480 // char ***chain_names, 3481 // int64_t **chain_ids); 3482 // 3483 // tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_set 3484 // (const tng_trajectory_t tng_data, 3485 // tng_molecule_t mol, 3486 // const int64_t n_particles, 3487 // const char **names, 3488 // const char **types, 3489 // const char **res_names, 3490 // const int64_t *res_ids, 3491 // const char **chain_names, 3492 // const int64_t *chain_ids); 3493 */ 3494 /** 3495 * @brief High-level function for reading the positions of all particles 3496 * from all frames. 3497 * @param tng_data is the trajectory to read from. 3498 * @param positions will be set to point at a 1-dimensional array of floats, 3499 * which will contain the positions. The data is stored sequentially in order 3500 * of frames. For each frame the positions (x, y and z coordinates) are stored. 3501 * The variable may point at already allocated memory or be a NULL pointer. 3502 * The memory must be freed afterwards. 3503 * @param stride_length will be set to the writing interval of the stored data. 3504 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3505 * must be initialised before using it. 3506 * @pre \code positions != 0 \endcode The pointer to the positions array 3507 * must not be a NULL pointer. 3508 * @pre \code stride_length != 0 \endcode The pointer to the stride length 3509 * must not be a NULL pointer. 3510 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3511 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3512 * has occured. 3513 */ 3514 tng_function_status DECLSPECDLLEXPORT tng_util_pos_read 3515 (const tng_trajectory_t tng_data, 3516 float **positions, 3517 int64_t *stride_length); 3518 3519 /** 3520 * @brief High-level function for reading the velocities of all particles 3521 * from all frames. 3522 * @param tng_data is the trajectory to read from. 3523 * @param velocities will be set to point at a 1-dimensional array of floats, 3524 * which will contain the velocities. The data is stored sequentially in order 3525 * of frames. For each frame the velocities (in x, y and z) are stored. The 3526 * variable may point at already allocated memory or be a NULL pointer. 3527 * The memory must be freed afterwards. 3528 * @param stride_length will be set to the writing interval of the stored data. 3529 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3530 * must be initialised before using it. 3531 * @pre \code velocities != 0 \endcode The pointer to the velocities array 3532 * must not be a NULL pointer. 3533 * @pre \code stride_length != 0 \endcode The pointer to the stride length 3534 * must not be a NULL pointer. 3535 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3536 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3537 * has occured. 3538 */ 3539 tng_function_status DECLSPECDLLEXPORT tng_util_vel_read 3540 (const tng_trajectory_t tng_data, 3541 float **velocities, 3542 int64_t *stride_length); 3543 3544 /** 3545 * @brief High-level function for reading the forces of all particles 3546 * from all frames. 3547 * @param tng_data is the trajectory to read from. 3548 * @param forces will be set to point at a 1-dimensional array of floats, 3549 * which will contain the forces. The data is stored sequentially in order 3550 * of frames. For each frame the forces (in x, y and z) are stored. The 3551 * variable may point at already allocated memory or be a NULL pointer. 3552 * The memory must be freed afterwards. 3553 * @param stride_length will be set to the writing interval of the stored data. 3554 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3555 * must be initialised before using it. 3556 * @pre \code forces != 0 \endcode The pointer to the forces array 3557 * must not be a NULL pointer. 3558 * @pre \code stride_length != 0 \endcode The pointer to the stride length 3559 * must not be a NULL pointer. 3560 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3561 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3562 * has occured. 3563 */ 3564 tng_function_status DECLSPECDLLEXPORT tng_util_force_read 3565 (const tng_trajectory_t tng_data, 3566 float **forces, 3567 int64_t *stride_length); 3568 3569 /** 3570 * @brief High-level function for reading the box shape from all frames. 3571 * @param tng_data is the trajectory to read from. 3572 * @param box_shape will be set to point at a 1-dimensional array of floats, 3573 * which will contain the box shape. The data is stored sequentially in order 3574 * of frames. The variable may point at already allocated memory or be a NULL pointer. 3575 * If the box shape is not modified during the trajectory, but as general data, 3576 * that will be returned instead. 3577 * @param stride_length will be set to the writing interval of the stored data. 3578 * @details This function should only be used if number of values used to specify 3579 * the box shape is known (by default TNG uses 9 values) since it does not 3580 * return the number of values in the array. It is recommended to use 3581 * tng_data_vector_interval_get() instead. 3582 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3583 * must be initialised before using it. 3584 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array 3585 * must not be a NULL pointer. 3586 * @pre \code stride_length != 0 \endcode The pointer to the stride length 3587 * must not be a NULL pointer. 3588 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3589 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3590 * has occured. 3591 */ 3592 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read 3593 (const tng_trajectory_t tng_data, 3594 float **box_shape, 3595 int64_t *stride_length); 3596 3597 /** 3598 * @brief High-level function for reading the next frame of particle-dependent 3599 * data of a specific type. 3600 * @param tng_data is the trajectory to read from. 3601 * @param block_id is the ID number of the block containing the data of interest. 3602 * @param values will be set to point at a 1-dimensional array containing the 3603 * requested data. The variable may point at already allocated memory (which will 3604 * be reallocated with realloc()), or be a 3605 * NULL pointer. The calling code must free the memory afterwards. 3606 * @param data_type will be pointing to a character indicating the size of the 3607 * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA. 3608 * @param retrieved_frame_number will be pointing at the frame number of the 3609 * returned frame. 3610 * @param retrieved_time will be pointing at the time stamp of the returned 3611 * frame. 3612 * @details If no frame has been read before the first frame of the trajectory 3613 * is read. 3614 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3615 * must be initialised before using it. 3616 * @pre \code values != 0 \endcode The pointer to the values array 3617 * must not be a NULL pointer. 3618 * @pre \code data_type != 0 \endcode The pointer to the data type of the 3619 * returned data must not be a NULL pointer. 3620 * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame 3621 * number of the returned data must not be a NULL pointer. 3622 * @pre \code retrieved_time != 0 \endcode The pointer to the time of the 3623 * returned data must not be a NULL pointer. 3624 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3625 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3626 * has occured. 3627 */ 3628 tng_function_status DECLSPECDLLEXPORT tng_util_particle_data_next_frame_read 3629 (const tng_trajectory_t tng_data, 3630 const int64_t block_id, 3631 void **values, 3632 char *data_type, 3633 int64_t *retrieved_frame_number, 3634 double *retrieved_time); 3635 3636 /** 3637 * @brief High-level function for reading the next frame of non-particle-dependent 3638 * data of a specific type. 3639 * @param tng_data is the trajectory to read from. 3640 * @param block_id is the ID number of the block containing the data of interest. 3641 * @param values will be set to point at a 1-dimensional array containing the 3642 * requested data. The variable may point at already allocated memory or be a 3643 * NULL pointer. The memory must be freed afterwards. 3644 * @param data_type will be pointing to a character indicating the size of the 3645 * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA. 3646 * @param retrieved_frame_number will be pointing at the frame number of the 3647 * returned frame. 3648 * @param retrieved_time will be pointing at the time stamp of the returned 3649 * frame. 3650 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3651 * must be initialised before using it. 3652 * @pre \code values != 0 \endcode The pointer to the values array 3653 * must not be a NULL pointer. 3654 * @pre \code data_type != 0 \endcode The pointer to the data type of the 3655 * returned data must not be a NULL pointer. 3656 * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame 3657 * number of the returned data must not be a NULL pointer. 3658 * @pre \code retrieved_time != 0 \endcode The pointer to the time of the 3659 * returned data must not be a NULL pointer. 3660 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3661 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3662 * has occured. 3663 */ 3664 tng_function_status DECLSPECDLLEXPORT tng_util_non_particle_data_next_frame_read 3665 (const tng_trajectory_t tng_data, 3666 const int64_t block_id, 3667 void **values, 3668 char *data_type, 3669 int64_t *retrieved_frame_number, 3670 double *retrieved_time); 3671 3672 /** 3673 * @brief High-level function for reading the positions of all particles 3674 * from a specific range of frames. 3675 * @param tng_data is the trajectory to read from. 3676 * @param first_frame is the first frame to return position data from. 3677 * @param last_frame is the last frame to return position data from. 3678 * @param positions will be set to point at a 1-dimensional array of floats, 3679 * which will contain the positions. The data is stored sequentially in order 3680 * of frames. For each frame the positions (x, y and z coordinates) are stored. 3681 * The variable may point at already allocated memory or be a NULL pointer. 3682 * The memory must be freed afterwards. 3683 * @param stride_length will be set to the writing interval of the stored data. 3684 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3685 * must be initialised before using it. 3686 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before 3687 * the last frame. 3688 * @pre \code positions != 0 \endcode The pointer to the positions array 3689 * must not be a NULL pointer. 3690 * @pre \code stride_length != 0 \endcode The pointer to the stride length 3691 * must not be a NULL pointer. 3692 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3693 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3694 * has occured. 3695 */ 3696 tng_function_status DECLSPECDLLEXPORT tng_util_pos_read_range 3697 (const tng_trajectory_t tng_data, 3698 const int64_t first_frame, 3699 const int64_t last_frame, 3700 float **positions, 3701 int64_t *stride_length); 3702 3703 /** 3704 * @brief High-level function for reading the velocities of all particles 3705 * from a specific range of frames. 3706 * @param tng_data is the trajectory to read from. 3707 * @param first_frame is the first frame to return position data from. 3708 * @param last_frame is the last frame to return position data from. 3709 * @param velocities will be set to point at a 1-dimensional array of floats, 3710 * which will contain the velocities. The data is stored sequentially in order 3711 * of frames. For each frame the velocities (in x, y and z) are stored. The 3712 * variable may point at already allocated memory or be a NULL pointer. 3713 * The memory must be freed afterwards. 3714 * @param stride_length will be set to the writing interval of the stored data. 3715 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3716 * must be initialised before using it. 3717 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before 3718 * the last frame. 3719 * @pre \code velocities != 0 \endcode The pointer to the velocities array 3720 * must not be a NULL pointer. 3721 * @pre \code stride_length != 0 \endcode The pointer to the stride length 3722 * must not be a NULL pointer. 3723 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3724 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3725 * has occured. 3726 */ 3727 tng_function_status DECLSPECDLLEXPORT tng_util_vel_read_range 3728 (const tng_trajectory_t tng_data, 3729 const int64_t first_frame, 3730 const int64_t last_frame, 3731 float **velocities, 3732 int64_t *stride_length); 3733 3734 /** 3735 * @brief High-level function for reading the forces of all particles 3736 * from a specific range of frames. 3737 * @param tng_data is the trajectory to read from. 3738 * @param first_frame is the first frame to return position data from. 3739 * @param last_frame is the last frame to return position data from. 3740 * @param forces will be set to point at a 1-dimensional array of floats, 3741 * which will contain the forces. The data is stored sequentially in order 3742 * of frames. For each frame the forces (in x, y and z) are stored. The 3743 * variable may point at already allocated memory or be a NULL pointer. 3744 * The memory must be freed afterwards. 3745 * @param stride_length will be set to the writing interval of the stored data. 3746 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3747 * must be initialised before using it. 3748 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before 3749 * the last frame. 3750 * @pre \code forces != 0 \endcode The pointer to the forces array 3751 * must not be a NULL pointer. 3752 * @pre \code stride_length != 0 \endcode The pointer to the stride length 3753 * must not be a NULL pointer. 3754 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3755 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3756 * has occured. 3757 */ 3758 tng_function_status DECLSPECDLLEXPORT tng_util_force_read_range 3759 (const tng_trajectory_t tng_data, 3760 const int64_t first_frame, 3761 const int64_t last_frame, 3762 float **forces, 3763 int64_t *stride_length); 3764 3765 /** 3766 * @brief High-level function for reading the box shape 3767 * from a specific range of frames. 3768 * @param tng_data is the trajectory to read from. 3769 * @param first_frame is the first frame to return position data from. 3770 * @param last_frame is the last frame to return position data from. 3771 * @param box_shape will be set to point at a 1-dimensional array of floats, 3772 * which will contain the box shape. The data is stored sequentially in order 3773 * of frames. 3774 * If the box shape is not modified during the trajectory, but as general data, 3775 * that will be returned instead. The 3776 * variable may point at already allocated memory or be a NULL pointer. 3777 * The memory must be freed afterwards. 3778 * @param stride_length will be set to the writing interval of the stored data. 3779 * @details This function should only be used if number of values used to specify 3780 * the box shape is known (by default TNG uses 9 values) since it does not 3781 * return the number of values in the array. It is recommended to use 3782 * tng_data_vector_interval_get() instead. 3783 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3784 * must be initialised before using it. 3785 * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before 3786 * the last frame. 3787 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array 3788 * must not be a NULL pointer. 3789 * @pre \code stride_length != 0 \endcode The pointer to the stride length 3790 * must not be a NULL pointer. 3791 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3792 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3793 * has occured. 3794 */ 3795 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read_range 3796 (const tng_trajectory_t tng_data, 3797 const int64_t first_frame, 3798 const int64_t last_frame, 3799 float **box_shape, 3800 int64_t *stride_length); 3801 3802 /** 3803 * @brief High-level function for setting the writing interval of data blocks. 3804 * @param tng_data is the trajectory to use. 3805 * @param i is the output interval, i.e. i == 10 means data written every 10th 3806 * frame. 3807 * @param n_values_per_frame is the number of values to store per frame. If the 3808 * data is particle dependent there will be n_values_per_frame stored per 3809 * particle each frame. 3810 * @param block_id is the ID of the block, of which to set the output interval. 3811 * @param block_name is a string that will be used as name of the block. Only 3812 * required if the block did not exist, i.e. a new block is created. 3813 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the 3814 * data is not related to specific particles (e.g. box shape) or 3815 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. 3816 * positions). Only required if the block did not exist, i.e. a new block is 3817 * created. 3818 * @param compression is the compression routine to use when writing the data. 3819 * Only required if the block did not exist, i.e. a new block is created. 3820 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3821 * must be initialised before using it. 3822 * @pre \code i >= 0 \endcode The writing interval must be >= 0. 3823 * @details n_values_per_frame, block_name, particle_dependency and 3824 * compression are only used if the data block did not exist before calling 3825 * this function, in which case it is created. 3826 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3827 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3828 * has occured. 3829 */ 3830 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_set 3831 (const tng_trajectory_t tng_data, 3832 const int64_t i, 3833 const int64_t n_values_per_frame, 3834 const int64_t block_id, 3835 const char *block_name, 3836 const char particle_dependency, 3837 const char compression); 3838 3839 /** 3840 * @brief High-level function for setting the writing interval of data blocks 3841 * containing double precision data. 3842 * @param tng_data is the trajectory to use. 3843 * @param i is the output interval, i.e. i == 10 means data written every 10th 3844 * frame. 3845 * @param n_values_per_frame is the number of values to store per frame. If the 3846 * data is particle dependent there will be n_values_per_frame stored per 3847 * particle each frame. 3848 * @param block_id is the ID of the block, of which to set the output interval. 3849 * @param block_name is a string that will be used as name of the block. Only 3850 * required if the block did not exist, i.e. a new block is created. 3851 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the 3852 * data is not related to specific particles (e.g. box shape) or 3853 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. 3854 * positions). Only required if the block did not exist, i.e. a new block is 3855 * created. 3856 * @param compression is the compression routine to use when writing the data. 3857 * Only required if the block did not exist, i.e. a new block is created. 3858 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3859 * must be initialised before using it. 3860 * @pre \code i >= 0 \endcode The writing interval must be >= 0. 3861 * @details n_values_per_frame, block_name, particle_dependency and 3862 * compression are only used if the data block did not exist before calling 3863 * this function, in which case it is created. 3864 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3865 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3866 * has occured. 3867 */ 3868 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_double_set 3869 (const tng_trajectory_t tng_data, 3870 const int64_t i, 3871 const int64_t n_values_per_frame, 3872 const int64_t block_id, 3873 const char *block_name, 3874 const char particle_dependency, 3875 const char compression); 3876 3877 /** 3878 * @brief High-level function for setting the writing interval of data blocks. 3879 * Obsolete! Use tng_util_generic_write_interval_set() 3880 * @param tng_data is the trajectory to use. 3881 * @param i is the output interval, i.e. i == 10 means data written every 10th 3882 * frame. 3883 * @param n_values_per_frame is the number of values to store per frame. If the 3884 * data is particle dependent there will be n_values_per_frame stored per 3885 * particle each frame. 3886 * @param block_id is the ID of the block, of which to set the output interval. 3887 * @param block_name is a string that will be used as name of the block. Only 3888 * required if the block did not exist, i.e. a new block is created. 3889 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the 3890 * data is not related to specific particles (e.g. box shape) or 3891 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. 3892 * positions). Only required if the block did not exist, i.e. a new block is 3893 * created. 3894 * @param compression is the compression routine to use when writing the data. 3895 * Only required if the block did not exist, i.e. a new block is created. 3896 * @details n_values_per_frame, block_name, particle_dependency and 3897 * compression are only used if the data block did not exist before calling 3898 * this function, in which case it is created. 3899 * This function is replaced by the more correcly named 3900 * tng_util_generic_write_interval_set(), but is kept for compatibility. 3901 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3902 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3903 * has occured. 3904 */ 3905 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_frequency_set 3906 (const tng_trajectory_t tng_data, 3907 const int64_t i, 3908 const int64_t n_values_per_frame, 3909 const int64_t block_id, 3910 const char *block_name, 3911 const char particle_dependency, 3912 const char compression); 3913 3914 /** 3915 * @brief High-level function for setting the writing interval of position 3916 * data blocks. 3917 * @param tng_data is the trajectory to use. 3918 * @param i is the output interval, i.e. i == 10 means data written every 10th 3919 * frame. 3920 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3921 * must be initialised before using it. 3922 * @pre \code i >= 0 \endcode The writing interval must be >= 0. 3923 * @details This function uses tng_util_generic_write_interval_set() and will 3924 * create a positions data block if none exists. 3925 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3926 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3927 * has occured. 3928 */ 3929 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_set 3930 (const tng_trajectory_t tng_data, 3931 const int64_t i); 3932 3933 /** 3934 * @brief High-level function for setting the writing interval of position 3935 * data blocks containing double precision data. 3936 * @param tng_data is the trajectory to use. 3937 * @param i is the output interval, i.e. i == 10 means data written every 10th 3938 * frame. 3939 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3940 * must be initialised before using it. 3941 * @pre \code i >= 0 \endcode The writing interval must be >= 0. 3942 * @details This function uses tng_util_generic_write_interval_set() and will 3943 * create a positions data block if none exists. 3944 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3945 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3946 * has occured. 3947 */ 3948 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_double_set 3949 (const tng_trajectory_t tng_data, 3950 const int64_t i); 3951 3952 /** 3953 * @brief High-level function for setting the writing interval of position 3954 * data blocks. Obsolete! Use tng_util_pos_write_interval_set() 3955 * @param tng_data is the trajectory to use. 3956 * @param i is the output interval, i.e. i == 10 means data written every 10th 3957 * frame. 3958 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3959 * must be initialised before using it. 3960 * @pre \code i >= 0 \endcode The writing interval must be >= 0. 3961 * @details This function uses tng_util_generic_write_interval_set() and will 3962 * create a positions data block if none exists. 3963 * This function is replaced by the more correcly named 3964 * tng_util_pos_write_interval_set(), but is kept for compatibility. 3965 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3966 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3967 * has occured. 3968 */ 3969 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_frequency_set 3970 (const tng_trajectory_t tng_data, 3971 const int64_t i); 3972 3973 /** 3974 * @brief High-level function for setting the writing interval of velocity 3975 * data blocks. 3976 * @param tng_data is the trajectory to use. 3977 * @param i is the output interval, i.e. i == 10 means data written every 10th 3978 * frame. 3979 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3980 * must be initialised before using it. 3981 * @pre \code i >= 0 \endcode The writing interval must be >= 0. 3982 * @details This function uses tng_util_generic_write_interval_set() and will 3983 * create a velocities data block if none exists. 3984 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 3985 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 3986 * has occured. 3987 */ 3988 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_set 3989 (const tng_trajectory_t tng_data, 3990 const int64_t i); 3991 3992 /** 3993 * @brief High-level function for setting the writing interval of velocity 3994 * data blocks containing double precision data. 3995 * @param tng_data is the trajectory to use. 3996 * @param i is the output interval, i.e. i == 10 means data written every 10th 3997 * frame. 3998 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 3999 * must be initialised before using it. 4000 * @pre \code i >= 0 \endcode The writing interval must be >= 0. 4001 * @details This function uses tng_util_generic_write_interval_set() and will 4002 * create a velocities data block if none exists. 4003 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4004 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4005 * has occured. 4006 */ 4007 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_double_set 4008 (const tng_trajectory_t tng_data, 4009 const int64_t i); 4010 4011 /** 4012 * @brief High-level function for setting the writing interval of velocity 4013 * data blocks. Obsolete! Use tng_util_vel_write_interval_set() 4014 * @param tng_data is the trajectory to use. 4015 * @param i is the output interval, i.e. i == 10 means data written every 10th 4016 * frame. 4017 * @details This function uses tng_util_generic_write_interval_set() and will 4018 * create a velocities data block if none exists. 4019 * This function is replaced by the more correcly named 4020 * tng_util_vel_write_interval_set(), but is kept for compatibility. 4021 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4022 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4023 * has occured. 4024 */ 4025 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_frequency_set 4026 (const tng_trajectory_t tng_data, 4027 const int64_t i); 4028 4029 /** 4030 * @brief High-level function for setting the writing interval of force 4031 * data blocks. 4032 * @param tng_data is the trajectory to use. 4033 * @param i is the output interval, i.e. i == 10 means data written every 10th 4034 * frame. 4035 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4036 * must be initialised before using it. 4037 * @pre \code i >= 0 \endcode The writing interval must be >= 0. 4038 * @details This function uses tng_util_generic_write_interval_set() and will 4039 * create a forces data block if none exists. 4040 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4041 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4042 * has occured. 4043 */ 4044 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_set 4045 (const tng_trajectory_t tng_data, 4046 const int64_t i); 4047 4048 /** 4049 * @brief High-level function for setting the writing interval of force 4050 * data blocks containing double precision data. 4051 * @param tng_data is the trajectory to use. 4052 * @param i is the output interval, i.e. i == 10 means data written every 10th 4053 * frame. 4054 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4055 * must be initialised before using it. 4056 * @pre \code i >= 0 \endcode The writing interval must be >= 0. 4057 * @details This function uses tng_util_generic_write_interval_set() and will 4058 * create a forces data block if none exists. 4059 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4060 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4061 * has occured. 4062 */ 4063 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_double_set 4064 (const tng_trajectory_t tng_data, 4065 const int64_t i); 4066 4067 /** 4068 * @brief High-level function for setting the writing interval of force 4069 * data blocks. Obsolete! Use tng_util_force_write_interval_set() 4070 * @param tng_data is the trajectory to use. 4071 * @param i is the output interval, i.e. i == 10 means data written every 10th 4072 * frame. 4073 * @details This function uses tng_util_generic_write_interval_set() and will 4074 * create a forces data block if none exists. 4075 * This function is replaced by the more correcly named 4076 * tng_util_force_write_interval_set(), but is kept for compatibility. 4077 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4078 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4079 * has occured. 4080 */ 4081 tng_function_status DECLSPECDLLEXPORT tng_util_force_write_frequency_set 4082 (const tng_trajectory_t tng_data, 4083 const int64_t i); 4084 4085 /** 4086 * @brief High-level function for setting the writing interval of box shape 4087 * data blocks. 4088 * @param tng_data is the trajectory to use. 4089 * @param i is the output interval, i.e. i == 10 means data written every 10th 4090 * frame. 4091 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4092 * must be initialised before using it. 4093 * @pre \code i >= 0 \endcode The writing interval must be >= 0. 4094 * @details This function uses tng_util_generic_write_interval_set() and will 4095 * create a box shape data block if none exists. 4096 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4097 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4098 * has occured. 4099 */ 4100 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_set 4101 (const tng_trajectory_t tng_data, 4102 const int64_t i); 4103 4104 /** 4105 * @brief High-level function for setting the writing interval of box shape 4106 * data blocks containing double precision data. 4107 * @param tng_data is the trajectory to use. 4108 * @param i is the output interval, i.e. i == 10 means data written every 10th 4109 * frame. 4110 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4111 * must be initialised before using it. 4112 * @pre \code i >= 0 \endcode The writing interval must be >= 0. 4113 * @details This function uses tng_util_generic_write_interval_set() and will 4114 * create a box shape data block if none exists. 4115 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4116 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4117 * has occured. 4118 */ 4119 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_double_set 4120 (const tng_trajectory_t tng_data, 4121 const int64_t i); 4122 4123 /** 4124 * @brief High-level function for setting the writing interval of velocity 4125 * data blocks. Obsolete! Use tng_util_box_shape_write_interval_set() 4126 * @param tng_data is the trajectory to use. 4127 * @param i is the output interval, i.e. i == 10 means data written every 10th 4128 * frame. 4129 * @details This function uses tng_util_generic_write_interval_set() and will 4130 * create a box shape data block if none exists. 4131 * This function is replaced by the more correcly named 4132 * tng_util_box_shape_write_interval_set(), but is kept for compatibility. 4133 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4134 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4135 * has occured. 4136 */ 4137 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_frequency_set 4138 (const tng_trajectory_t tng_data, 4139 const int64_t i); 4140 4141 /** 4142 * @brief High-level function for writing data of one frame to a data block. 4143 * @param tng_data is the trajectory to use. 4144 * @param frame_nr is the frame number of the data. If frame_nr < 0 the 4145 * data is written as non-trajectory data. 4146 * @param values is a 1D array of data to add. The array should be of length 4147 * n_particles * n_values_per_frame if writing particle related data, otherwise 4148 * it should be n_values_per_frame. 4149 * @param n_values_per_frame is the number of values to store per frame. If the 4150 * data is particle dependent there will be n_values_per_frame stored per 4151 * particle each frame. 4152 * @param block_id is the ID of the block, of which to set the output interval. 4153 * @param block_name is a string that will be used as name of the block. Only 4154 * required if the block did not exist, i.e. a new block is created. 4155 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the 4156 * data is not related to specific particles (e.g. box shape) or 4157 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. 4158 * positions). Only required if the block did not exist, i.e. a new block is 4159 * created. 4160 * @param compression is the compression routine to use when writing the data. 4161 * Only required if the block did not exist, i.e. a new block is created. 4162 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4163 * must be initialised before using it. 4164 * @pre \code values != 0 \endcode The pointer to the values array must not 4165 * be a NULL pointer. 4166 * @details n_values_per_frame, block_name, particle_dependency and 4167 * compression are only used if the data block did not exist before calling 4168 * this function, in which case it is created. 4169 * N.b. Data is written a whole block at a time. The data is not 4170 * actually written to disk until the frame set is finished or the TNG 4171 * trajectory is closed. 4172 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4173 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4174 * has occured. 4175 */ 4176 tng_function_status DECLSPECDLLEXPORT tng_util_generic_write 4177 (const tng_trajectory_t tng_data, 4178 const int64_t frame_nr, 4179 const float *values, 4180 const int64_t n_values_per_frame, 4181 const int64_t block_id, 4182 const char *block_name, 4183 const char particle_dependency, 4184 const char compression); 4185 4186 /** 4187 * @brief High-level function for writing data of one frame to a double precision 4188 * data block. 4189 * @param tng_data is the trajectory to use. 4190 * @param frame_nr is the frame number of the data. If frame_nr < 0 the 4191 * data is written as non-trajectory data. 4192 * @param values is a 1D array of data to add. The array should be of length 4193 * n_particles * n_values_per_frame if writing particle related data, otherwise 4194 * it should be n_values_per_frame. 4195 * @param n_values_per_frame is the number of values to store per frame. If the 4196 * data is particle dependent there will be n_values_per_frame stored per 4197 * particle each frame. 4198 * @param block_id is the ID of the block, of which to set the output interval. 4199 * @param block_name is a string that will be used as name of the block. Only 4200 * required if the block did not exist, i.e. a new block is created. 4201 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the 4202 * data is not related to specific particles (e.g. box shape) or 4203 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. 4204 * positions). Only required if the block did not exist, i.e. a new block is 4205 * created. 4206 * @param compression is the compression routine to use when writing the data. 4207 * Only required if the block did not exist, i.e. a new block is created. 4208 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4209 * must be initialised before using it. 4210 * @pre \code values != 0 \endcode The pointer to the values array must not 4211 * be a NULL pointer. 4212 * @details n_values_per_frame, block_name, particle_dependency and 4213 * compression are only used if the data block did not exist before calling 4214 * this function, in which case it is created. 4215 * N.b. Data is written a whole block at a time. The data is not 4216 * actually written to disk until the frame set is finished or the TNG 4217 * trajectory is closed. 4218 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4219 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4220 * has occured. 4221 */ 4222 tng_function_status DECLSPECDLLEXPORT tng_util_generic_double_write 4223 (const tng_trajectory_t tng_data, 4224 const int64_t frame_nr, 4225 const double *values, 4226 const int64_t n_values_per_frame, 4227 const int64_t block_id, 4228 const char *block_name, 4229 const char particle_dependency, 4230 const char compression); 4231 4232 /** 4233 * @brief High-level function for adding data to positions data blocks. 4234 * @param tng_data is the trajectory to use. 4235 * @param frame_nr is the frame number of the data. If frame_nr < 0 the 4236 * data is written as non-trajectory data. 4237 * @param positions is a 1D array of data to add. The array should be of length 4238 * n_particles * 3. 4239 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4240 * must be initialised before using it. 4241 * @pre \code positions != 0 \endcode The pointer to the positions array must not 4242 * be a NULL pointer. 4243 * @details This function uses tng_util_generic_write() and will 4244 * create a positions data block if none exists. Positions are stored as three 4245 * values per frame and compressed using TNG compression. 4246 * N.b. Since compressed data is written a whole block at a time the data is not 4247 * actually written to disk until the frame set is finished or the TNG 4248 * trajectory is closed. 4249 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4250 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4251 * has occured. 4252 */ 4253 tng_function_status DECLSPECDLLEXPORT tng_util_pos_write 4254 (const tng_trajectory_t tng_data, 4255 const int64_t frame_nr, 4256 const float *positions); 4257 4258 /** 4259 * @brief High-level function for adding data to positions data blocks at double 4260 * precision. 4261 * @param tng_data is the trajectory to use. 4262 * @param frame_nr is the frame number of the data. If frame_nr < 0 the 4263 * data is written as non-trajectory data. 4264 * @param positions is a 1D array of data to add. The array should be of length 4265 * n_particles * 3. 4266 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4267 * must be initialised before using it. 4268 * @pre \code positions != 0 \endcode The pointer to the positions array must not 4269 * be a NULL pointer. 4270 * @details This function uses tng_util_generic_write() and will 4271 * create a positions data block if none exists. Positions are stored as three 4272 * values per frame and compressed using TNG compression. 4273 * N.b. Since compressed data is written a whole block at a time the data is not 4274 * actually written to disk until the frame set is finished or the TNG 4275 * trajectory is closed. 4276 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4277 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4278 * has occured. 4279 */ 4280 tng_function_status DECLSPECDLLEXPORT tng_util_pos_double_write 4281 (const tng_trajectory_t tng_data, 4282 const int64_t frame_nr, 4283 const double *positions); 4284 4285 /** 4286 * @brief High-level function for adding data to velocities data blocks. 4287 * @param tng_data is the trajectory to use. 4288 * @param frame_nr is the frame number of the data. If frame_nr < 0 the 4289 * data is written as non-trajectory data. 4290 * @param velocities is a 1D array of data to add. The array should be of length 4291 * n_particles * 3. 4292 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4293 * must be initialised before using it. 4294 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not 4295 * be a NULL pointer. 4296 * @details This function uses tng_util_generic_write() and will 4297 * create a velocities data block if none exists. Velocities are stored as three 4298 * values per frame and compressed using TNG compression. 4299 * N.b. Since compressed data is written a whole block at a time the data is not 4300 * actually written to disk until the frame set is finished or the TNG 4301 * trajectory is closed. 4302 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4303 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4304 * has occured. 4305 */ 4306 tng_function_status DECLSPECDLLEXPORT tng_util_vel_write 4307 (const tng_trajectory_t tng_data, 4308 const int64_t frame_nr, 4309 const float *velocities); 4310 4311 /** 4312 * @brief High-level function for adding data to velocities data blocks at double 4313 * precision. 4314 * @param tng_data is the trajectory to use. 4315 * @param frame_nr is the frame number of the data. If frame_nr < 0 the 4316 * data is written as non-trajectory data. 4317 * @param velocities is a 1D array of data to add. The array should be of length 4318 * n_particles * 3. 4319 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4320 * must be initialised before using it. 4321 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not 4322 * be a NULL pointer. 4323 * @details This function uses tng_util_generic_write() and will 4324 * create a velocities data block if none exists. Velocities are stored as three 4325 * values per frame and compressed using TNG compression. 4326 * N.b. Since compressed data is written a whole block at a time the data is not 4327 * actually written to disk until the frame set is finished or the TNG 4328 * trajectory is closed. 4329 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4330 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4331 * has occured. 4332 */ 4333 tng_function_status DECLSPECDLLEXPORT tng_util_vel_double_write 4334 (const tng_trajectory_t tng_data, 4335 const int64_t frame_nr, 4336 const double *velocities); 4337 4338 /** 4339 * @brief High-level function for adding data to forces data blocks. 4340 * @param tng_data is the trajectory to use. 4341 * @param frame_nr is the frame number of the data. If frame_nr < 0 the 4342 * data is written as non-trajectory data. 4343 * @param forces is a 1D array of data to add. The array should be of length 4344 * n_particles * 3. 4345 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4346 * must be initialised before using it. 4347 * @pre \code forces != 0 \endcode The pointer to the forces array must not 4348 * be a NULL pointer. 4349 * @details This function uses tng_util_generic_write() and will 4350 * create a forces data block if none exists. Forces are stored as three 4351 * values per frame and compressed using gzip compression. 4352 * N.b. Since compressed data is written a whole block at a time the data is not 4353 * actually written to disk until the frame set is finished or the TNG 4354 * trajectory is closed. 4355 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4356 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4357 * has occured. 4358 */ 4359 tng_function_status DECLSPECDLLEXPORT tng_util_force_write 4360 (const tng_trajectory_t tng_data, 4361 const int64_t frame_nr, 4362 const float *forces); 4363 4364 /** 4365 * @brief High-level function for adding data to forces data blocks at double 4366 * precision. 4367 * @param tng_data is the trajectory to use. 4368 * @param frame_nr is the frame number of the data. If frame_nr < 0 the 4369 * data is written as non-trajectory data. 4370 * @param forces is a 1D array of data to add. The array should be of length 4371 * n_particles * 3. 4372 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4373 * must be initialised before using it. 4374 * @pre \code forces != 0 \endcode The pointer to the forces array must not 4375 * be a NULL pointer. 4376 * @details This function uses tng_util_generic_write() and will 4377 * create a forces data block if none exists. Forces are stored as three 4378 * values per frame and compressed using gzip compression. 4379 * N.b. Since compressed data is written a whole block at a time the data is not 4380 * actually written to disk until the frame set is finished or the TNG 4381 * trajectory is closed. 4382 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4383 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4384 * has occured. 4385 */ 4386 tng_function_status DECLSPECDLLEXPORT tng_util_force_double_write 4387 (const tng_trajectory_t tng_data, 4388 const int64_t frame_nr, 4389 const double *forces); 4390 4391 /** 4392 * @brief High-level function for adding data to box shape data blocks. 4393 * @param tng_data is the trajectory to use. 4394 * @param frame_nr is the frame number of the data. If frame_nr < 0 the 4395 * data is written as non-trajectory data. 4396 * @param box_shape is a 1D array of data to add. The array should be of length 9. 4397 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4398 * must be initialised before using it. 4399 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not 4400 * be a NULL pointer. 4401 * @details This function uses tng_util_generic_write() and will 4402 * create a box shape data block if none exists. Box shapes are stored as 9 4403 * values per frame and compressed using TNG compression. 4404 * N.b. Since compressed data is written a whole block at a time the data is not 4405 * actually written to disk until the frame set is finished or the TNG 4406 * trajectory is closed. 4407 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4408 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4409 * has occured. 4410 */ 4411 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write 4412 (const tng_trajectory_t tng_data, 4413 const int64_t frame_nr, 4414 const float *box_shape); 4415 4416 /** 4417 * @brief High-level function for adding data to box shape data blocks at double 4418 * precision. 4419 * @param tng_data is the trajectory to use. 4420 * @param frame_nr is the frame number of the data. If frame_nr < 0 the 4421 * data is written as non-trajectory data. 4422 * @param box_shape is a 1D array of data to add. The array should be of length 9. 4423 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4424 * must be initialised before using it. 4425 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not 4426 * be a NULL pointer. 4427 * @details This function uses tng_util_generic_write() and will 4428 * create a box shape data block if none exists. Box shapes are stored as 9 4429 * values per frame and compressed using TNG compression. 4430 * N.b. Since compressed data is written a whole block at a time the data is not 4431 * actually written to disk until the frame set is finished or the TNG 4432 * trajectory is closed. 4433 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4434 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4435 * has occured. 4436 */ 4437 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_double_write 4438 (const tng_trajectory_t tng_data, 4439 const int64_t frame_nr, 4440 const double *box_shape); 4441 4442 /** 4443 * @brief High-level function for writing data of one frame to a data block. 4444 * If the frame is at the beginning of a frame set the time stamp of the frame 4445 * set is set. 4446 * @param tng_data is the trajectory to use. 4447 * @param frame_nr is the frame number of the data. 4448 * @param time is the time stamp of the frame (in seconds). 4449 * @param values is a 1D array of data to add. The array should be of length 4450 * n_particles * n_values_per_frame if writing particle related data, otherwise 4451 * it should be n_values_per_frame. 4452 * @param n_values_per_frame is the number of values to store per frame. If the 4453 * data is particle dependent there will be n_values_per_frame stored per 4454 * particle each frame. 4455 * @param block_id is the ID of the block, of which to set the output interval. 4456 * @param block_name is a string that will be used as name of the block. Only 4457 * required if the block did not exist, i.e. a new block is created. 4458 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the 4459 * data is not related to specific particles (e.g. box shape) or 4460 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. 4461 * positions). Only required if the block did not exist, i.e. a new block is 4462 * created. 4463 * @param compression is the compression routine to use when writing the data. 4464 * Only required if the block did not exist, i.e. a new block is created. 4465 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4466 * must be initialised before using it. 4467 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. 4468 * @pre \code time >= 0 \endcode The time stamp must be >= 0. 4469 * @pre \code values != 0 \endcode The pointer to the values array must not 4470 * be a NULL pointer. 4471 * @details n_values_per_frame, block_name, particle_dependency and 4472 * compression are only used if the data block did not exist before calling 4473 * this function, in which case it is created. 4474 * N.b. Data is written a whole block at a time. The data is not 4475 * actually written to disk until the frame set is finished or the TNG 4476 * trajectory is closed. 4477 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4478 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4479 * has occured. 4480 */ 4481 tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_write 4482 (const tng_trajectory_t tng_data, 4483 const int64_t frame_nr, 4484 const double time, 4485 const float *values, 4486 const int64_t n_values_per_frame, 4487 const int64_t block_id, 4488 const char *block_name, 4489 const char particle_dependency, 4490 const char compression); 4491 4492 /** 4493 * @brief High-level function for writing data of one frame to a double precision 4494 * data block. If the frame is at the beginning of a frame set the time stamp of 4495 * the frame set is set. 4496 * @param tng_data is the trajectory to use. 4497 * @param frame_nr is the frame number of the data. 4498 * @param time is the time stamp of the frame (in seconds). 4499 * @param values is a 1D array of data to add. The array should be of length 4500 * n_particles * n_values_per_frame if writing particle related data, otherwise 4501 * it should be n_values_per_frame. 4502 * @param n_values_per_frame is the number of values to store per frame. If the 4503 * data is particle dependent there will be n_values_per_frame stored per 4504 * particle each frame. 4505 * @param block_id is the ID of the block, of which to set the output interval. 4506 * @param block_name is a string that will be used as name of the block. Only 4507 * required if the block did not exist, i.e. a new block is created. 4508 * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the 4509 * data is not related to specific particles (e.g. box shape) or 4510 * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. 4511 * positions). Only required if the block did not exist, i.e. a new block is 4512 * created. 4513 * @param compression is the compression routine to use when writing the data. 4514 * Only required if the block did not exist, i.e. a new block is created. 4515 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4516 * must be initialised before using it. 4517 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. 4518 * @pre \code time >= 0 \endcode The time stamp must be >= 0. 4519 * @pre \code values != 0 \endcode The pointer to the values array must not 4520 * be a NULL pointer. 4521 * @details n_values_per_frame, block_name, particle_dependency and 4522 * compression are only used if the data block did not exist before calling 4523 * this function, in which case it is created. 4524 * N.b. Data is written a whole block at a time. The data is not 4525 * actually written to disk until the frame set is finished or the TNG 4526 * trajectory is closed. 4527 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4528 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4529 * has occured. 4530 */ 4531 tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_double_write 4532 (const tng_trajectory_t tng_data, 4533 const int64_t frame_nr, 4534 const double time, 4535 const double *values, 4536 const int64_t n_values_per_frame, 4537 const int64_t block_id, 4538 const char *block_name, 4539 const char particle_dependency, 4540 const char compression); 4541 4542 /** 4543 * @brief High-level function for adding data to positions data blocks. If the 4544 * frame is at the beginning of a frame set the time stamp of the frame set 4545 * is set. 4546 * @param tng_data is the trajectory to use. 4547 * @param frame_nr is the frame number of the data. 4548 * @param time is the time stamp of the frame (in seconds). 4549 * @param positions is a 1D array of data to add. The array should be of length 4550 * n_particles * 3. 4551 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4552 * must be initialised before using it. 4553 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. 4554 * @pre \code time >= 0 \endcode The time stamp must be >= 0. 4555 * @pre \code positions != 0 \endcode The pointer to the positions array must not 4556 * be a NULL pointer. 4557 * @details This function uses tng_util_generic_with_time_write() and will 4558 * create a positions data block if none exists. Positions are stored as three 4559 * values per frame and compressed using TNG compression. 4560 * N.b. Since compressed data is written a whole block at a time the data is not 4561 * actually written to disk until the frame set is finished or the TNG 4562 * trajectory is closed. 4563 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4564 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4565 * has occured. 4566 */ 4567 tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_write 4568 (const tng_trajectory_t tng_data, 4569 const int64_t frame_nr, 4570 const double time, 4571 const float *positions); 4572 4573 /** 4574 * @brief High-level function for adding data to positions data blocks at double 4575 * precision. If the frame is at the beginning of a frame set the time stamp of 4576 * the frame set is set. 4577 * @param tng_data is the trajectory to use. 4578 * @param frame_nr is the frame number of the data. 4579 * @param time is the time stamp of the frame (in seconds). 4580 * @param positions is a 1D array of data to add. The array should be of length 4581 * n_particles * 3. 4582 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4583 * must be initialised before using it. 4584 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. 4585 * @pre \code time >= 0 \endcode The time stamp must be >= 0. 4586 * @pre \code positions != 0 \endcode The pointer to the positions array must not 4587 * be a NULL pointer. 4588 * @details This function uses tng_util_generic_with_time_double_write() and will 4589 * create a positions data block if none exists. Positions are stored as three 4590 * values per frame and compressed using TNG compression. 4591 * N.b. Since compressed data is written a whole block at a time the data is not 4592 * actually written to disk until the frame set is finished or the TNG 4593 * trajectory is closed. 4594 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4595 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4596 * has occured. 4597 */ 4598 tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_double_write 4599 (const tng_trajectory_t tng_data, 4600 const int64_t frame_nr, 4601 const double time, 4602 const double *positions); 4603 4604 /** 4605 * @brief High-level function for adding data to velocities data blocks. If the 4606 * frame is at the beginning of a frame set the time stamp of the frame set 4607 * is set. 4608 * @param tng_data is the trajectory to use. 4609 * @param frame_nr is the frame number of the data. 4610 * @param time is the time stamp of the frame (in seconds). 4611 * @param velocities is a 1D array of data to add. The array should be of length 4612 * n_particles * 3. 4613 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4614 * must be initialised before using it. 4615 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. 4616 * @pre \code time >= 0 \endcode The time stamp must be >= 0. 4617 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not 4618 * be a NULL pointer. 4619 * @details This function uses tng_util_generic_with_time_write() and will 4620 * create a velocities data block if none exists. Velocities are stored as three 4621 * values per frame and compressed using TNG compression. 4622 * N.b. Since compressed data is written a whole block at a time the data is not 4623 * actually written to disk until the frame set is finished or the TNG 4624 * trajectory is closed. 4625 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4626 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4627 * has occured. 4628 */ 4629 tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_write 4630 (const tng_trajectory_t tng_data, 4631 const int64_t frame_nr, 4632 const double time, 4633 const float *velocities); 4634 4635 /** 4636 * @brief High-level function for adding data to velocities data blocks at 4637 * double precision. If the frame is at the beginning of a frame set the 4638 * time stamp of the frame set is set. 4639 * @param tng_data is the trajectory to use. 4640 * @param frame_nr is the frame number of the data. 4641 * @param time is the time stamp of the frame (in seconds). 4642 * @param velocities is a 1D array of data to add. The array should be of length 4643 * n_particles * 3. 4644 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4645 * must be initialised before using it. 4646 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. 4647 * @pre \code time >= 0 \endcode The time stamp must be >= 0. 4648 * @pre \code velocities != 0 \endcode The pointer to the velocities array must not 4649 * be a NULL pointer. 4650 * @details This function uses tng_util_generic_with_time_double_write() and will 4651 * create a velocities data block if none exists. Velocities are stored as three 4652 * values per frame and compressed using TNG compression. 4653 * N.b. Since compressed data is written a whole block at a time the data is not 4654 * actually written to disk until the frame set is finished or the TNG 4655 * trajectory is closed. 4656 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4657 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4658 * has occured. 4659 */ 4660 tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_double_write 4661 (const tng_trajectory_t tng_data, 4662 const int64_t frame_nr, 4663 const double time, 4664 const double *velocities); 4665 4666 /** 4667 * @brief High-level function for adding data to forces data blocks. If the 4668 * frame is at the beginning of a frame set the time stamp of the frame set 4669 * is set. 4670 * @param tng_data is the trajectory to use. 4671 * @param frame_nr is the frame number of the data. 4672 * @param time is the time stamp of the frame (in seconds). 4673 * @param forces is a 1D array of data to add. The array should be of length 4674 * n_particles * 3. 4675 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4676 * must be initialised before using it. 4677 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. 4678 * @pre \code time >= 0 \endcode The time stamp must be >= 0. 4679 * @pre \code forces != 0 \endcode The pointer to the forces array must not 4680 * be a NULL pointer. 4681 * @details This function uses tng_util_generic_with_time_write() and will 4682 * create a forces data block if none exists. Forces are stored as three 4683 * values per frame and compressed using gzip compression. 4684 * N.b. Since compressed data is written a whole block at a time the data is not 4685 * actually written to disk until the frame set is finished or the TNG 4686 * trajectory is closed. 4687 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4688 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4689 * has occured. 4690 */ 4691 tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_write 4692 (const tng_trajectory_t tng_data, 4693 const int64_t frame_nr, 4694 const double time, 4695 const float *forces); 4696 4697 /** 4698 * @brief High-level function for adding data to forces data blocks at 4699 * double precision. If the frame is at the beginning of a frame set 4700 * the time stamp of the frame set is set. 4701 * @param tng_data is the trajectory to use. 4702 * @param frame_nr is the frame number of the data. 4703 * @param time is the time stamp of the frame (in seconds). 4704 * @param forces is a 1D array of data to add. The array should be of length 4705 * n_particles * 3. 4706 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4707 * must be initialised before using it. 4708 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. 4709 * @pre \code time >= 0 \endcode The time stamp must be >= 0. 4710 * @pre \code forces != 0 \endcode The pointer to the forces array must not 4711 * be a NULL pointer. 4712 * @details This function uses tng_util_generic_with_time_double_write() and will 4713 * create a forces data block if none exists. Forces are stored as three 4714 * values per frame and compressed using gzip compression. 4715 * N.b. Since compressed data is written a whole block at a time the data is not 4716 * actually written to disk until the frame set is finished or the TNG 4717 * trajectory is closed. 4718 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4719 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4720 * has occured. 4721 */ 4722 tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_double_write 4723 (const tng_trajectory_t tng_data, 4724 const int64_t frame_nr, 4725 const double time, 4726 const double *forces); 4727 4728 /** 4729 * @brief High-level function for adding data to box shape data blocks. If the 4730 * frame is at the beginning of a frame set the time stamp of the frame set 4731 * is set. 4732 * @param tng_data is the trajectory to use. 4733 * @param frame_nr is the frame number of the data. 4734 * @param time is the time stamp of the frame (in seconds). 4735 * @param box_shape is a 1D array of data to add. The array should be of length 9. 4736 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4737 * must be initialised before using it. 4738 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. 4739 * @pre \code time >= 0 \endcode The time stamp must be >= 0. 4740 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not 4741 * be a NULL pointer. 4742 * @details This function uses tng_util_generic_with_time_write() and will 4743 * create a box shape data block if none exists. Box shapes are stored as 9 4744 * values per frame and compressed using TNG compression. 4745 * N.b. Since compressed data is written a whole block at a time the data is not 4746 * actually written to disk until the frame set is finished or the TNG 4747 * trajectory is closed. 4748 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4749 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4750 * has occured. 4751 */ 4752 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_write 4753 (const tng_trajectory_t tng_data, 4754 const int64_t frame_nr, 4755 const double time, 4756 const float *box_shape); 4757 4758 /** 4759 * @brief High-level function for adding data to box shape data blocks at 4760 * double precision. If the frame is at the beginning of a frame set the 4761 * time stamp of the frame set is set. 4762 * @param tng_data is the trajectory to use. 4763 * @param frame_nr is the frame number of the data. 4764 * @param time is the time stamp of the frame (in seconds). 4765 * @param box_shape is a 1D array of data to add. The array should be of length 9. 4766 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4767 * must be initialised before using it. 4768 * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. 4769 * @pre \code time >= 0 \endcode The time stamp must be >= 0. 4770 * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not 4771 * be a NULL pointer. 4772 * @details This function uses tng_util_generic_with_time_double_write() and will 4773 * create a box shape data block if none exists. Box shapes are stored as 9 4774 * values per frame and compressed using TNG compression. 4775 * N.b. Since compressed data is written a whole block at a time the data is not 4776 * actually written to disk until the frame set is finished or the TNG 4777 * trajectory is closed. 4778 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4779 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4780 * has occured. 4781 */ 4782 tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_double_write 4783 (const tng_trajectory_t tng_data, 4784 const int64_t frame_nr, 4785 const double time, 4786 const double *box_shape); 4787 4788 /** 4789 * @brief High-level function for getting the compression method and 4790 * multiplication factor of the last read frame of a specific data block. 4791 * @param tng_data is the trajectory to use. 4792 * @param block_id is the ID number of the block containing the data of 4793 * interest. 4794 * @param codec_id will be set to the value of the codec_id of the 4795 * compression of the data block. See tng_compression for more details. 4796 * @param factor will be set to the multiplication factor applied to 4797 * the values before compression, in order to get integers from them. 4798 * factor is 1/precision. 4799 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4800 * must be initialised before using it. 4801 * @pre \code codec_id != 0 \endcode The pointer to the returned codec id 4802 * must not be a NULL pointer. 4803 * @pre \code factor != 0 \endcode The pointer to the returned multiplication 4804 * factor must not be a NULL pointer. 4805 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4806 * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error 4807 * has occured. 4808 */ 4809 tng_function_status DECLSPECDLLEXPORT tng_util_frame_current_compression_get 4810 (const tng_trajectory_t tng_data, 4811 const int64_t block_id, 4812 int64_t *codec_id, 4813 double *factor); 4814 4815 /** @brief High-level function for determining the next frame with data and what 4816 * data blocks have data for that frame. The search can be limited to certain 4817 * data blocks. 4818 * @param tng_data is the trajectory to use. 4819 * @param current_frame is the frame that was last read, from where to start 4820 * looking for data. 4821 * @param n_requested_data_block_ids is the number of data blocks listed in 4822 * requested_data_block_ids. If this is 0 all data blocks will be taken into 4823 * account. 4824 * @param requested_data_block_ids is an array of data blocks to look for. 4825 * @param next_frame will be set to the next frame with data. 4826 * @param n_data_blocks_in_next_frame is set to the number of data blocks with 4827 * data for next_frame. 4828 * @param data_block_ids_in_next_frame is set to an array (of length 4829 * n_data_blocks_in_next_frame) that lists the data block IDs with data for 4830 * next_frame. It must be pointing at NULL or previously allocated memory. 4831 * Memory for the array is reallocated by this function using realloc(). 4832 * The memory must be freed by the client afterwards or 4833 * there will be a memory leak. 4834 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4835 * must be initialised before using it. 4836 * @pre \code next_frame != 0 \endcode The pointer to the next frame must not 4837 * be NULL. 4838 * @pre \code n_data_blocks_in_next_frame != 0 \endcode The pointer to 4839 * n_data_blocks_in_next_frame must not be NULL. 4840 * @pre \code *data_block_ids_in_next_frame != 0 \endcode The pointer to the 4841 * list of data block IDs must not be NULL. 4842 * @pre \code n_requested_data_block_ids == 0 || requested_data_block_ids != 0 \endcode 4843 * If the number of requested data blocks != 0 then the array of data block IDs must not be NULL. 4844 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4845 * has occured or TNG_CRITICAL (2) if a major error 4846 * has occured. 4847 */ 4848 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_next_frame_present_data_blocks_find 4849 (const tng_trajectory_t tng_data, 4850 int64_t current_frame, 4851 const int64_t n_requested_data_block_ids, 4852 const int64_t *requested_data_block_ids, 4853 int64_t *next_frame, 4854 int64_t *n_data_blocks_in_next_frame, 4855 int64_t **data_block_ids_in_next_frame); 4856 4857 /* @brief High-level function for getting all data block ids and their names 4858 * and stride lengths. 4859 * @param tng_data is the trajectory to use. 4860 * @param n_data_blocks is set to the number of data blocks in the trajectory. 4861 * @param data_block_ids is set to an array (of length 4862 * n_data_blocks) that lists the data block IDs in the trajectory. 4863 * It must be pointing at NULL or previously allocated memory. 4864 * Memory for the array is allocated by this function. 4865 * The memory must be freed by the client afterwards or 4866 * there will be a memory leak. 4867 * @param data_block_names is set to an array (of length 4868 * n_data_blocks) that contains the names of the data blocks. 4869 * It must be pointing at NULL or previously allocated memory. 4870 * Memory for the array is allocated by this function. 4871 * The memory must be freed by the client afterwards or 4872 * there will be a memory leak. 4873 * @param stride_lengths is set to an array (of length 4874 * n_data_blocks) that lists the stride lengths of the data blocks. 4875 * It must be pointing at NULL or previously allocated memory. 4876 * Memory for the array is allocated by this function. 4877 * The memory must be freed by the client afterwards or 4878 * there will be a memory leak. 4879 * @param n_values_per_frame is set to an array (of length 4880 * n_data_blocks) that lists the number of values per frame of the data blocks. 4881 * It must be pointing at NULL or previously allocated memory. 4882 * Memory for the array is allocated by this function. 4883 * The memory must be freed by the client afterwards or 4884 * there will be a memory leak. 4885 * @param block_types is set to an array (of length 4886 * n_data_blocks) that lists the block types of the data blocks. 4887 * It must be pointing at NULL or previously allocated memory. 4888 * Memory for the array is allocated by this function. 4889 * The memory must be freed by the client afterwards or 4890 * there will be a memory leak. 4891 * @param dependencies is set to an array (of length 4892 * n_data_blocks) that lists the dependencies of the data blocks. 4893 * It must be pointing at NULL or previously allocated memory. 4894 * Memory for the array is allocated by this function. 4895 * The memory must be freed by the client afterwards or 4896 * there will be a memory leak. 4897 * @param compressions is set to an array (of length 4898 * n_data_blocks) that lists the compressions of the data blocks. 4899 * It must be pointing at NULL or previously allocated memory. 4900 * Memory for the array is allocated by this function. 4901 * The memory must be freed by the client afterwards or 4902 * there will be a memory leak. 4903 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4904 * must be initialised before using it. 4905 * @pre \code n_data_blocks != 0 \endcode The pointer to 4906 * n_data_blocks must not be NULL. 4907 * @pre \code data_block_ids != 0 \endcode The pointer to the 4908 * list of data block IDs must not be NULL. 4909 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4910 * has occured or TNG_CRITICAL (2) if a major error 4911 * has occured. 4912 */ 4913 /* 4914 tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_all_data_block_types_get 4915 (const tng_trajectory_t tng_data, 4916 int64_t *n_data_blocks, 4917 int64_t **data_block_ids, 4918 char ***data_block_names, 4919 int64_t **stride_lengths, 4920 int64_t **n_values_per_frame, 4921 char **block_types, 4922 char **dependencies, 4923 char **compressions); 4924 */ 4925 4926 /** @brief Finds the frame set of the specified frame in order to prepare for writing 4927 * after it. 4928 * @param tng_data is the trajectory to use. 4929 * @param prev_frame is the frame after which to start appending. 4930 * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) 4931 * must be initialised before using it. 4932 * @pre \code prev_frame >= 0 \endcode The previous frame must not be negative. 4933 * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error 4934 * has occured (such as not finding the requested frame) or TNG_CRITICAL (2) 4935 * if a major error has occured. 4936 */ 4937 tng_function_status DECLSPECDLLEXPORT tng_util_prepare_append_after_frame 4938 (const tng_trajectory_t tng_data, 4939 const int64_t prev_frame); 4940 4941 4942 /** @brief Get the number of frames containing data of a specific type. 4943 * @param tng_data is the trajectory to use. 4944 * @param block_id is the id of the block of the data type. 4945 * @param n_frames is set to the number of frames containing data of 4946 * the requested data type. 4947 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major 4948 * error has occured. 4949 */ 4950 tng_function_status DECLSPECDLLEXPORT tng_util_num_frames_with_data_of_block_id_get 4951 (const tng_trajectory_t tng_data, 4952 const int64_t block_id, 4953 int64_t *n_frames); 4954 /** @} */ /* end of group2 */ 4955 4956 4957 #ifdef __cplusplus 4958 } /* end extern "C" */ 4959 #endif 4960 4961 #endif /* TNG_IO_H */ 4962