src/external/tng_io/include/tng/tng_io.hpp

   1 /* This code is part of the tng binary trajectory format.
   2  *
   3  * Written by Anders Gärdenäs
   4  * Copyright (c) 2012-2013, 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 #ifndef TNG_IO_HPP
  13 #define TNG_IO_HPP
  14
  15 #include "tng_io.h"
  16
  17 namespace Tng
  18 {
  19 class Trajectory;
  20 class Atom;
  21 class Residue;
  22 class Chain;
  23 class Molecule;
  24 typedef class Molecule * Molecule_t;
  25
  26
  27 class Trajectory {
  28 private:
  29     tng_trajectory_t traj;
  30     tng_function_status status;
  31 public:
  32     /**
  33     * @brief Add a molecule to the trajectory.
  34     * @param name is a pointer to the string containing the name of the new molecule.
  35     * @param molecule is a pointer to the newly created molecule.
  36     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
  37     * error has occured.
  38     */
  39
  40     tng_function_status addMolecule(const char *, Molecule_t);
  41     tng_function_status addMoleculeWithId(const char *, int64_t id, Molecule_t);
  42     tng_function_status findMolecule(const char *name, int64_t id, Molecule_t molecule);
  43     friend class Atom;
  44     friend class Residue;
  45     friend class Chain;
  46     friend class Molecule;
  47
  48     //! Normal constructor
  49     Trajectory()
  50     { status = tng_trajectory_init(&traj); }
  51
  52     //! Copy constructor
  53     Trajectory(Trajectory * src)
  54     { status = tng_trajectory_init_from_src(traj,&src->traj); }
  55
  56     //! Detructor
  57     ~Trajectory()
  58     { status = tng_trajectory_destroy(&traj); }
  59
  60     //! Status
  61     tng_function_status getStatus()
  62     { return status; }
  63
  64
  65     /**
  66     * @brief Get the name of the input file.
  67     * @param file_name the string to fill with the name of the input file,
  68     * memory must be allocated before.
  69     * @param max_len maximum char length of the string, i.e. how much memory has
  70     * been reserved for file_name. This includes \0 terminating character.
  71     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
  72     * has occurred (source string longer than destination string).
  73     */
  74     tng_function_status getInputFile (char *file_name, const int max_len)
  75     {
  76         return status = tng_input_file_get(traj, file_name,   max_len);
  77     }
  78
  79     /**
  80     * @brief Set the name of the input file.
  81     * @param file_name the name of the input file.
  82     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
  83     * error has occured.
  84     */
  85     tng_function_status setInputFile(const char *file_name)
  86     {
  87         return status = tng_input_file_set(traj, file_name);
  88     }
  89
  90
  91     /**
  92     * @brief Get the name of the output file.
  93     * @param file_name the string to fill with the name of the output file,
  94     * memory must be allocated before.
  95     * @param max_len maximum char length of the string, i.e. how much memory has
  96     * been reserved for file_name. This includes \0 terminating character.
  97     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
  98     * has occurred (source string longer than destination string).
  99     */
 100     tng_function_status getOutputFile(char *file_name, const int max_len)
 101     {
 102         return status = tng_output_file_get(traj, file_name, max_len);
 103     }
 104
 105
 106     /**
 107     * @brief Set the name of the output file.
 108     * @param file_name the name of the output file.
 109     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
 110     * error has occured.
 111     */
 112     tng_function_status setOutputFile(const char *file_name)
 113     {
 114         return status = tng_output_file_set(traj, file_name);
 115     }
 116
 117     /**
 118     * @brief Get the endianness of the output file.
 119     * current output file.
 120     * @param endianness will contain the enumeration of the endianness.
 121     * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness
 122     * could not be retrieved.
 123     */
 124     tng_function_status getOutputFileEndianness
 125                     (tng_file_endianness *endianness)
 126     {
 127         return status = tng_output_file_endianness_get(traj, endianness);
 128     }
 129
 130     /**
 131     * @brief Set the endianness of the output file.
 132     * @param endianness the enumeration of the endianness, can be either
 133     * TNG_BIG_ENDIAN (0) or TNG_LITTLE_ENDIAN (1).
 134     * @details The endianness cannot be changed after file output has started.
 135     * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness
 136     * could not be set.
 137     */
 138     tng_function_status setOutputFileEndianness
 139                     (const tng_file_endianness endianness)
 140     {
 141         return status = tng_output_file_endianness_set(traj, endianness);
 142     }
 143
 144     /**
 145     * @brief Get the name of the program used when creating the trajectory.
 146     * @param name the string to fill with the name of the program,
 147     * memory must be allocated before.
 148     * @param max_len maximum char length of the string, i.e. how much memory has
 149     * been reserved for name. This includes \0 terminating character.
 150     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 151     * has occurred (source string longer than destination string).
 152     */
 153     tng_function_status getFirstProgramName(char *name, const int max_len)
 154     {
 155         return status = tng_first_program_name_get(traj,name,max_len);
 156     }
 157
 158
 159     /**
 160     * @brief Set the name of the program used when creating the trajectory..
 161     * @param new_name is a string containing the wanted name.
 162     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
 163     * error has occured.
 164     */
 165     tng_function_status setFirstProgramName(const char *new_name)
 166     {
 167         return status = tng_first_program_name_set(traj, new_name);
 168     }
 169
 170
 171     /**
 172     * @brief Get the name of the program used when last modifying the trajectory.
 173     * @param name the string to fill with the name of the program,
 174     * memory must be allocated before.
 175     * @param max_len maximum char length of the string, i.e. how much memory has
 176     * been reserved for name. This includes \0 terminating character.
 177     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 178     * has occurred (source string longer than destination string).
 179     */
 180     tng_function_status getLastProgramName(char *name, const int max_len)
 181     {
 182         return status = tng_last_program_name_get(traj, name, max_len);
 183     }
 184
 185
 186     /**
 187     * @brief Set the name of the program used when last modifying the trajectory.
 188     * @param new_name is a string containing the wanted name.
 189     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
 190     * error has occured.
 191     */
 192     tng_function_status setLastProgramName(const char *new_name)
 193     {
 194         return status = tng_last_program_name_set(traj, new_name);
 195     }
 196
 197
 198     /**
 199     * @brief Get the name of the user who created the trajectory.
 200     * @param name the string to fill with the name of the user,
 201     * memory must be allocated before.
 202     * @param max_len maximum char length of the string, i.e. how much memory has
 203     * been reserved for name. This includes \0 terminating character.
 204     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 205     * has occurred (source string longer than destination string).
 206     */
 207     tng_function_status getFirstUserName(char *name, const int max_len)
 208     {
 209         return status = tng_first_user_name_get(traj,name, max_len);
 210     }
 211
 212
 213     /**
 214     * @brief Set the name of the user who created the trajectory.
 215     * @param new_name is a string containing the wanted name.
 216     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
 217     * error has occured.
 218     */
 219     tng_function_status setFirstUserName(const char *new_name)
 220     {
 221         return status = tng_first_user_name_set(traj, new_name);
 222     }
 223
 224
 225     /**
 226     * @brief Get the name of the user who last modified the trajectory.
 227     * @param name the string to fill with the name of the user,
 228     * memory must be allocated before.
 229     * @param max_len maximum char length of the string, i.e. how much memory has
 230     * been reserved for name. This includes \0 terminating character.
 231     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 232     * has occurred (source string longer than destination string).
 233     */
 234     tng_function_status getLastUserName(char *name, const int max_len)
 235     {
 236         return status = tng_last_user_name_get(traj,name,max_len);
 237     }
 238
 239
 240     /**
 241     * @brief Set the name of the user who last modified the trajectory.
 242     * @param new_name is a string containing the wanted name.
 243     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
 244     * error has occured.
 245     */
 246     tng_function_status setLastUserName(const char *new_name)
 247     {
 248         return status = tng_last_user_name_set(traj,new_name);
 249     }
 250
 251
 252
 253     /**
 254     * @brief Get the name of the computer used when creating the trajectory.
 255     * @param name the string to fill with the name of the computer,
 256     * memory must be allocated before.
 257     * @param max_len maximum char length of the string, i.e. how much memory has
 258     * been reserved for name. This includes \0 terminating character.
 259     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 260     * has occurred (source string longer than destination string).
 261     */
 262     tng_function_status getFirstComputerName(char *name, const int max_len)
 263     {
 264         return status = tng_first_computer_name_get(traj, name, max_len);
 265     }
 266
 267
 268     /**
 269     * @brief Set the name of the computer used when creating the trajectory.
 270     * @param new_name is a string containing the wanted name.
 271     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
 272     * error has occured.
 273     */
 274     tng_function_status setFirstComputerName(const char *new_name)
 275     {
 276         return status = tng_first_computer_name_set(traj, new_name);
 277     }
 278
 279
 280     /**
 281     * @brief Get the name of the computer used when last modifying the trajectory.
 282     * @param name the string to fill with the name of the computer,
 283     * memory must be allocated before.
 284     * @param max_len maximum char length of the string, i.e. how much memory has
 285     * been reserved for name. This includes \0 terminating character.
 286     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 287     * has occurred (source string longer than destination string).
 288     */
 289     tng_function_status getLastComputerName(char *name, const int max_len)
 290     {
 291         return status = tng_last_computer_name_get(traj,name,max_len);
 292     }
 293
 294
 295     /**
 296     * @brief Set the name of the computer used when last modifying the trajectory.
 297     * @param new_name is a string containing the wanted name.
 298     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
 299     * error has occured.
 300     */
 301     tng_function_status setLastComputerName(const char *new_name)
 302     {
 303         return status = tng_last_computer_name_set(traj,new_name);
 304     }
 305
 306
 307     /**
 308     * @brief Get the pgp_signature of the user creating the trajectory.
 309     * @param signature the string to fill with the signature,
 310     * memory must be allocated before.
 311     * @param max_len maximum char length of the string, i.e. how much memory has
 312     * been reserved for name. This includes \0 terminating character.
 313     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 314     * has occurred (source string longer than destination string).
 315     */
 316     tng_function_status getFirstSignature(char *signature, const int max_len)
 317     {
 318         return status = tng_last_computer_name_get(traj, signature,max_len);
 319     }
 320
 321
 322     /**
 323     * @brief Set the pgp_signature of the user creating the trajectory.
 324     * @param signature is a string containing the pgp_signature.
 325     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
 326     * error has occured.
 327     */
 328     tng_function_status setFirstSignature(const char *signature)
 329     {
 330         return status = tng_first_signature_set(traj, signature);
 331     }
 332
 333
 334     /**
 335     * @brief Get the pgp_signature of the user last modifying the trajectory.
 336     * @param signature the string to fill with the signature,
 337     * memory must be allocated before.
 338     * @param max_len maximum char length of the string, i.e. how much memory has
 339     * been reserved for name. This includes \0 terminating character.
 340     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 341     * has occurred (source string longer than destination string).
 342     */
 343     tng_function_status getLastSignature(char *signature, const int max_len)
 344     {
 345         return status = tng_first_signature_get(traj, signature, max_len);
 346     }
 347
 348
 349     /**
 350     * @brief Set the pgp_signature of the user last modifying the trajectory.
 351     * @param signature is a string containing the pgp_signature.
 352     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
 353     * error has occured.
 354     */
 355     tng_function_status setLastSignature(const char *signature)
 356     {
 357         return status = tng_last_signature_set(traj, signature);
 358     }
 359
 360
 361     /**
 362     * @brief Get the name of the forcefield used in the trajectory.
 363     * @param name the string to fill with the name of the forcefield,
 364     * memory must be allocated before.
 365     * @param max_len maximum char length of the string, i.e. how much memory has
 366     * been reserved for name. This includes \0 terminating character.
 367     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 368     * has occurred (source string longer than destination string).
 369     */
 370     tng_function_status getForcefieldName(char *name, const int max_len)
 371     {
 372         return status = tng_last_signature_get(traj,name,max_len);
 373     }
 374
 375
 376     /**
 377     * @brief Set the name of the forcefield used in the trajectory.
 378     * @param new_name is a string containing the wanted name.
 379     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
 380     * error has occured.
 381     */
 382     tng_function_status setForcefieldName(const char *new_name)
 383     {
 384         return status = tng_forcefield_name_set(traj, new_name);
 385     }
 386
 387
 388     /**
 389     * @brief Get the medium stride length of the trajectory.
 390     * @param len is pointing to a value set to the stride length.
 391     * @return TNG_SUCCESS (0) if successful.
 392     */
 393     tng_function_status getMediumStrideLength(int64_t *len)
 394     {
 395         return status = tng_medium_stride_length_get(traj,len);
 396     }
 397
 398
 399     /**
 400     * @brief Set the medium stride length of the trajectory.
 401     * @param len is the wanted medium stride length.
 402     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 403     * has occurred.
 404     */
 405     tng_function_status setMediumStrideLength(const int64_t len)
 406     {
 407         return status = tng_medium_stride_length_set(traj,len);
 408     }
 409
 410
 411     /**
 412     * @brief Get the long stride length of the trajectory.
 413     * @param len is pointing to a value set to the stride length.
 414     * @return TNG_SUCCESS (0) if successful.
 415     */
 416     tng_function_status getLongStrideLength(int64_t *len)
 417     {
 418         return status = tng_long_stride_length_get(traj, len);
 419     }
 420
 421
 422     /**
 423     * @brief Set the long stride length of the trajectory.
 424     * @param len is the wanted long stride length.
 425     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 426     * has occurred.
 427     */
 428     tng_function_status setLongStrideLength(const int64_t len)
 429     {
 430         return status = tng_long_stride_length_set(traj,len);
 431     }
 432
 433
 434     /**
 435     * @brief Get the current time per frame of the trajectory.
 436     * @param len is pointing to a value set to the time per frame.
 437     * @return TNG_SUCCESS (0) if successful.
 438     */
 439     tng_function_status getTimePerFrame(double *time)
 440     {
 441         return status = tng_time_per_frame_get(traj, time);
 442     }
 443
 444
 445     /**
 446     * @brief Set the time per frame of the trajectory.
 447     * @param len is the new time per frame.
 448     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 449     * has occurred.
 450     */
 451     tng_function_status setTimePerFrame(const double time)
 452     {
 453         return status = tng_time_per_frame_set(traj, time);
 454     }
 455
 456
 457     /**
 458     * @brief Get the length of the input file.
 459     * @param len is pointing to a value set to the file length.
 460     * @return TNG_SUCCESS (0) if successful.
 461     */
 462     tng_function_status getInputFileLen(int64_t *len)
 463     {
 464         return status = tng_input_file_len_get(traj, len);
 465     }
 466
 467
 468     /**
 469     * @brief Get the number of frames in the trajectory
 470     * @param n is pointing to a value set to the number of frames.
 471     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 472     * has occurred (could not find last frame set).
 473     */
 474     tng_function_status getNumFrames(int64_t *n)
 475     {
 476         return status = tng_num_frames_get(traj, n);
 477     }
 478
 479     /**
 480     * @brief Get the current number of particles.
 481     * @param n is pointing to a value set to the number of particles.
 482     * @details If variable number of particles are used this function will return
 483     * the number of particles in the current frame set.
 484     * @return TNG_SUCCESS (0) if successful.
 485     */
 486     tng_function_status getNumParticles(int64_t *n)
 487     {
 488         return status = tng_num_particles_get(traj, n);
 489     }
 490
 491
 492
 493
 494     /**
 495     * @brief Get the current total number of molecules.
 496     * @param n is pointing to a value set to the number of molecules.
 497     * @details If variable number of particles are used this function will return
 498     * the total number of molecules in the current frame set.
 499     * @return TNG_SUCCESS (0) if successful.
 500     */
 501     tng_function_status getNumMolecules(int64_t *n)
 502     {
 503         return status = tng_num_molecules_get(traj,n);
 504     }
 505
 506     /**
 507     * @brief Get the exponential used for distances in the trajectory.
 508     * @param exp is pointing to a value set to the distance unit exponential.
 509     * @details Example: If the distances are specified in nm (default) exp is -9.
 510     * If the distances are specified in Å exp is -10.
 511     * @return TNG_SUCCESS (0) if successful.
 512     */
 513     tng_function_status getDistanceUnitExponential
 514                     (int64_t *exp)
 515     {
 516         return status = tng_distance_unit_exponential_get(traj, exp);
 517     }
 518
 519     /**
 520     * @brief Set the exponential used for distances in the trajectory.
 521     * @param exp is the distance unit exponential to use.
 522     * @details Example: If the distances are specified in nm (default) exp is -9.
 523     * If the distances are specified in Å exp is -10.
 524     * @return TNG_SUCCESS (0) if successful.
 525     */
 526     tng_function_status setDistanceUnitExponential
 527                     (int64_t exp)
 528     {
 529         return status = tng_distance_unit_exponential_set(traj, exp);
 530     }
 531
 532
 533     /**
 534     * @brief Get the number of frames per frame set.
 535     * per frame set.
 536     * @param n is pointing to a value set to the number of frames per frame set.
 537     * @return TNG_SUCCESS (0) if successful.
 538     */
 539     tng_function_status getNumFramesPerFrameSet(int64_t *n)
 540     {
 541         return status = tng_num_frames_per_frame_set_get(traj,n);
 542     }
 543
 544     /**
 545     * @brief Set the number of frames per frame set.
 546     * @param n is the number of frames per frame set.
 547     * @details This does not affect already existing frame sets. For
 548     * consistency the number of frames per frame set should be set
 549     * betfore creating any frame sets.
 550     * @return TNG_SUCCESS (0) if successful.
 551     */
 552     tng_function_status setNumFramesPerFrameSet(const int64_t n)
 553     {
 554         return status = tng_num_frames_per_frame_set_set(traj,n);
 555     }
 556
 557     /**
 558     * @brief Get the number of frame sets.
 559     * @param n is pointing to a value set to the number of frame sets.
 560     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 561     * has occurred or TNG_CRITICAL (2) if a major error has occured.
 562     */
 563     tng_function_status getNumFrameSets(int64_t *n)
 564     {
 565         return status = tng_num_frame_sets_get(traj, n);
 566     }
 567
 568
 569     /**
 570     * @brief Get the current trajectory frame set.
 571     * @param frame_set_p will be set to point at the memory position of
 572     * the found frame set.
 573     * @return TNG_SUCCESS (0) if successful.
 574     */
 575     tng_function_status getCurrentFrameSet(tng_trajectory_frame_set_t *frame_set_p)
 576     {
 577         return status = tng_current_frame_set_get(traj, frame_set_p);
 578     }
 579
 580
 581     /**
 582     * @brief Find the requested frame set number.
 583     * @param nr is the frame set number to search for.
 584     * @details tng_data->current_trajectory_frame_set will contain the
 585     * found trajectory if successful.
 586     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 587     * has occurred or TNG_CRITICAL (2) if a major error has occured.
 588     */
 589     tng_function_status findFrameSetNr(const int64_t nr)
 590     {
 591         return status = tng_frame_set_nr_find(traj,nr);
 592     }
 593
 594
 595     /**
 596     * @brief Find the frame set containing a specific frame.
 597     * @param frame is the frame number to search for.
 598     * @details tng_data->current_trajectory_frame_set will contain the
 599     * found trajectory if successful.
 600     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 601     * has occurred or TNG_CRITICAL (2) if a major error has occured.
 602     */
 603     tng_function_status findFrameSetOfFrame(const int64_t frame)
 604     {
 605         return status = tng_frame_set_of_frame_find(traj, frame);
 606     }
 607
 608
 609     /**
 610     * @brief Get the file position of the next frame set in the input file.
 611     * @param frame_set is the frame set of which to get the position of the
 612     * following frame set.
 613     * @param pos is pointing to a value set to the file position.
 614     * @return TNG_SUCCESS (0) if successful.
 615     */
 616     tng_function_status getNextFrameSetFilePos
 617         (const tng_trajectory_frame_set_t frame_set,int64_t *pos)
 618     {
 619         return status = tng_frame_set_next_frame_set_file_pos_get(traj,frame_set,pos );
 620     }
 621
 622     /**
 623     * @brief Get the file position of the previous frame set in the input file.
 624     * @param frame_set is the frame set of which to get the position of the
 625     * previous frame set.
 626     * @param pos is pointing to a value set to the file position.
 627     * @return TNG_SUCCESS (0) if successful.
 628     */
 629     tng_function_status getPrevFrameSetFilePos
 630         (const tng_trajectory_frame_set_t frame_set,int64_t *pos)
 631     {
 632         return status = tng_frame_set_prev_frame_set_file_pos_get(traj, frame_set, pos);
 633     }
 634
 635
 636     /**
 637     * @brief Get the first and last frames of the frame set.
 638     * @param frame_set is the frame set of which to get the frame range.
 639     * @param first_frame is set to the first frame of the frame set.
 640     * @param last_frame is set to the last frame of the frame set.
 641     * @return TNG_SUCCESS (0) if successful.
 642     */
 643     tng_function_status getFrameSetFrameRange
 644         (const tng_trajectory_frame_set_t frame_set,
 645         int64_t *first_frame,
 646         int64_t *last_frame)
 647     {
 648         return status = tng_frame_set_frame_range_get(traj,frame_set, first_frame, last_frame);
 649     }
 650
 651
 652     /**
 653     * @brief Get the molecume name of real particle number (number in mol system).
 654     * @param nr is the real number of the particle in the molecular system.
 655     * @param name is a string, which is set to the name of the molecule. Memory
 656     * must be reserved beforehand.
 657     * @param max_len is the maximum length of name.
 658     * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
 659     * has occured.
 660     */
 661     tng_function_status getMoleculeNameOfParticleNr
 662         (const int64_t nr,char *name,int max_len)
 663     {
 664         return status = tng_molecule_name_of_particle_nr_get(traj,nr,name,max_len);
 665     }
 666
 667
 668     /**
 669     * @brief Get the chain name of real particle number (number in mol system).
 670     * @param nr is the real number of the particle in the molecular system.
 671     * @param name is a string, which is set to the name of the chain. Memory
 672     * must be reserved beforehand.
 673     * @param max_len is the maximum length of name.
 674     * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
 675     * has occured.
 676     */
 677     tng_function_status getChainNameOfParticleNr
 678         (const int64_t nr,char *name,int max_len)
 679     {
 680         return status = tng_chain_name_of_particle_nr_get(traj, nr, name, max_len);
 681     }
 682
 683
 684     /**
 685     * @brief Get the residue name of real particle number (number in mol system).
 686     * @param nr is the real number of the particle in the molecular system.
 687     * @param name is a string, which is set to the name of the residue. Memory
 688     * must be reserved beforehand.
 689     * @param max_len is the maximum length of name.
 690     * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
 691     * has occured.
 692     */
 693     tng_function_status getResidueNameOfParticleNr
 694         (const int64_t nr,char *name,int max_len)
 695     {
 696         return status = tng_residue_name_of_particle_nr_get(traj,nr,name,max_len);
 697     }
 698
 699
 700     /**
 701     * @brief Get the atom name of real particle number (number in mol system).
 702     * @param nr is the real number of the particle in the molecular system.
 703     * @param name is a string, which is set to the name of the atom. Memory
 704     * must be reserved beforehand.
 705     * @param max_len is the maximum length of name.
 706     * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error
 707     * has occured.
 708     */
 709     tng_function_status getAtomNameOfParticleNr
 710         (const int64_t nr,char *name,int max_len)
 711     {
 712         return status = tng_atom_name_of_particle_nr_get(traj, nr,name,max_len);
 713     }
 714
 715
 716     /**
 717     * @brief Add a particle mapping table.
 718     * @details Each particle mapping table will be written as a separate block,
 719     * followed by the data blocks for the corresponding particles. In most cases
 720     * there is one particle mapping block for each thread writing the trajectory.
 721     * @details The mapping information is added to the currently active frame set
 722     * of tng_data
 723     * @param first_particle_number is the first particle number of this mapping
 724     * block.
 725     * @param n_particles is the number of particles in this mapping block.
 726     * @param mapping_table is a list of the real particle numbers (i.e. the numbers
 727     * used in the molecular system). The list is n_particles long.
 728     * @details mapping_table[0] is the real particle number of the first particle
 729     * in the following data blocks.
 730     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 731     * has occurred or TNG_CRITICAL (2) if a major error has occured.
 732     */
 733     tng_function_status addParticleMapping
 734         (const int64_t first_particle_number,
 735         const int64_t n_particles,
 736         const int64_t *mapping_table)
 737     {
 738         return status = tng_particle_mapping_add(traj,first_particle_number,n_particles,mapping_table );
 739     }
 740
 741
 742     /**
 743     * @brief Read the header blocks from the input_file of tng_data.
 744     * @details The trajectory blocks must be read separately and iteratively in chunks
 745     * to fit in memory.
 746     * @details tng_data->input_file_path specifies
 747     * which file to read from. If the file (input_file) is not open it will be
 748     * opened.
 749     * @param hash_mode is an option to decide whether to use the md5 hash or not.
 750     * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
 751     * compared to the md5 hash of the read contents to ensure valid data.
 752     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
 753     * error has occured.
 754     */
 755     tng_function_status readFileHeaders(const tng_hash_mode hash_mode)
 756     {
 757         return status = tng_file_headers_read(traj, hash_mode);
 758     }
 759
 760
 761     /**
 762     * @brief Write the header blocks to the output_file of tng_data.
 763     * @details The trajectory blocks must be written separately and iteratively in chunks
 764     * to fit in memory.
 765     * @details tng_data->output_file_path
 766     * specifies which file to write to. If the file (output_file) is not open it
 767     * will be opened.
 768     * @param hash_mode is an option to decide whether to use the md5 hash or not.
 769     * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
 770     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
 771     * error has occured.
 772     */
 773     tng_function_status writeFileHeaders(const tng_hash_mode hash_mode)
 774     {
 775         return status = tng_file_headers_write(traj, hash_mode);
 776     }
 777
 778
 779
 780     /**
 781     * @brief Read one (the next) block (of any kind) from the input_file of tng_data.
 782     * which file to read from. If the file (input_file) is not open it will be
 783     * opened.
 784     * @param block_data is a pointer to the struct which will be populated with the
 785     * data.
 786     * @details If block_data->input_file_pos > 0 it is the position from where the
 787     * reading starts otherwise it starts from the current position.
 788     * @param hash_mode is an option to decide whether to use the md5 hash or not.
 789     * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
 790     * compared to the md5 hash of the read contents to ensure valid data.
 791     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 792     * has occurred or TNG_CRITICAL (2) if a major error has occured.
 793     */
 794     tng_function_status readNextBlock(const tng_hash_mode hash_mode, tng_gen_block_t block_data)
 795     {
 796         return status = tng_block_read_next(traj,block_data, hash_mode);
 797     }
 798
 799
 800
 801     /**
 802     * @brief Read one (the next) frame set, including mapping and related data blocks
 803     * from the input_file of tng_data.
 804     * which file to read from. If the file (input_file) is not open it will be
 805     * opened.
 806     * @param hash_mode is an option to decide whether to use the md5 hash or not.
 807     * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
 808     * compared to the md5 hash of the read contents to ensure valid data.
 809     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 810     * has occurred or TNG_CRITICAL (2) if a major error has occured.
 811     */
 812     tng_function_status readNextFrameSet(const tng_hash_mode hash_mode)
 813     {
 814         return status = tng_frame_set_read_next(traj, hash_mode);
 815     }
 816
 817
 818     /**
 819     * @brief Write one frame set, including mapping and related data blocks
 820     * to the output_file of tng_data.
 821     * @details  tng_data->output_file_path specifies
 822     * which file to write to. If the file (output_file) is not open it will be
 823     * opened.
 824     * @param hash_mode is an option to decide whether to use the md5 hash or not.
 825     * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated.
 826     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 827     * has occurred or TNG_CRITICAL (2) if a major error has occured.
 828     */
 829     tng_function_status writeFrameSet(const tng_hash_mode hash_mode)
 830     {
 831         return status = tng_frame_set_write(traj, hash_mode);
 832     }
 833
 834
 835     /**
 836     * @brief Create and initialise a frame set.
 837     * @param first_frame is the first frame of the frame set.
 838     * @param n_frames is the number of frames in the frame set.
 839     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 840     * has occurred or TNG_CRITICAL (2) if a major error has occured.
 841     */
 842     tng_function_status newFrameSet(const int64_t first_frame,
 843         const int64_t n_frames)
 844     {
 845         return status =  tng_frame_set_new(traj, first_frame, n_frames);
 846     }
 847
 848
 849     /**
 850     * @brief Create and initialise a frame set with the time of the first frame
 851     * specified.
 852     * @param first_frame is the first frame of the frame set.
 853     * @param n_frames is the number of frames in the frame set.
 854     * @param first_frame_time is the time stamp of the first frame (in seconds).
 855     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 856     * has occurred or TNG_CRITICAL (2) if a major error has occured.
 857     */
 858     tng_function_status newFrameSetWithTime
 859                 (const int64_t first_frame,
 860                  const int64_t n_frames,
 861                  const double first_frame_time)
 862     {
 863         return status =  tng_frame_set_with_time_new(traj,
 864                                                      first_frame, n_frames,
 865                                                      first_frame_time);
 866     }
 867
 868
 869     /**
 870     * @brief Set the time stamp of the first frame of the current frame set.
 871     * @param first_frame_time is the time stamp of the first frame in the
 872     * frame set.
 873     * @return TNG_SUCCESS (0) if successful.
 874     */
 875     tng_function_status setTimeOfFirstFrameOfFrameSet
 876                     (const double first_frame_time)
 877     {
 878         return status = tng_frame_set_first_frame_time_set(traj,
 879                                                            first_frame_time);
 880     }
 881
 882     /**
 883     * @brief Add a non-particle dependent data block.
 884     * @param id is the block ID of the block to add.
 885     * @param block_name is a descriptive name of the block to add
 886     * @param datatype is the datatype of the data in the block (e.g. int/float)
 887     * @param block_type_flag indicates if this is a non-trajectory block (added
 888     * directly to tng_data) or if it is a trajectory block (added to the
 889     * frame set)
 890     * @param n_frames is the number of frames of the data block (automatically
 891     * set to 1 if adding a non-trajectory data block)
 892     * @param n_values_per_frame is how many values a stored each frame (e.g. 9
 893     * for a box shape block)
 894     * @param stride_length is how many frames are between each entry in the
 895     * data block
 896     * @param codec_id is the ID of the codec to compress the data.
 897     * @param new_data is an array of data values to add.
 898     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 899     * has occurred or TNG_CRITICAL (2) if a major error has occured.
 900     */
 901     tng_function_status addDataBlock(const int64_t id,
 902         const char *block_name,
 903         const tng_data_type datatype,
 904         const tng_block_type block_type_flag,
 905         int64_t n_frames,
 906         const int64_t n_values_per_frame,
 907         const int64_t stride_length,
 908         const int64_t codec_id,
 909         void *new_data)
 910     {
 911         return status = tng_data_block_add(traj, id,block_name,
 912             datatype,block_type_flag, n_frames,
 913             n_values_per_frame, stride_length,
 914             codec_id, new_data);
 915     }
 916
 917
 918     /**
 919     * @brief Add a particle dependent data block.
 920     * @param id is the block ID of the block to add.
 921     * @param block_name is a descriptive name of the block to add
 922     * @param datatype is the datatype of the data in the block (e.g. int/float)
 923     * @param block_type_flag indicates if this is a non-trajectory block (added
 924     * directly to tng_data) or if it is a trajectory block (added to the
 925     * frame set)
 926     * @param n_frames is the number of frames of the data block (automatically
 927     * set to 1 if adding a non-trajectory data block)
 928     * @param n_values_per_frame is how many values a stored each frame (e.g. 9
 929     * for a box shape block)
 930     * @param stride_length is how many frames are between each entry in the
 931     * data block
 932     * @param first_particle_number is the number of the first particle stored
 933     * in this data block
 934     * @param n_particles is the number of particles stored in this data block
 935     * @param codec_id is the ID of the codec to compress the data.
 936     * @param new_data is an array of data values to add.
 937     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 938     * has occurred or TNG_CRITICAL (2) if a major error has occured.
 939     */
 940     tng_function_status addParticleDataBlock(const int64_t id,
 941         const char *block_name,
 942         const tng_data_type datatype,
 943         const tng_block_type block_type_flag,
 944         int64_t n_frames,
 945         const int64_t n_values_per_frame,
 946         const int64_t stride_length,
 947         const int64_t first_particle_number,
 948         const int64_t n_particles,
 949         const int64_t codec_id,
 950         void *new_data)
 951     {
 952         return status = tng_particle_data_block_add(traj,id,    block_name,
 953             datatype, block_type_flag, n_frames,n_values_per_frame,
 954             stride_length,first_particle_number,n_particles,
 955             codec_id, new_data);
 956     }
 957
 958
 959     /**
 960     * @brief Write data of one trajectory frame to the output_file of tng_data.
 961     * @param frame_nr is the index number of the frame to write.
 962     * @param block_id is the ID of the data block to write the data to.
 963     * @param data is an array of data to write. The length of the array should
 964     * equal n_values_per_frame.
 965     * @param hash_mode is an option to decide whether to use the md5 hash or not.
 966     * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
 967     * compared to the md5 hash of the read contents to ensure valid data.
 968     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 969     * has occurred or TNG_CRITICAL (2) if a major error has occured.
 970     */
 971     tng_function_status writeFrameData(const int64_t frame_nr,
 972         const int64_t block_id,
 973         const void *data,
 974         const tng_hash_mode hash_mode)
 975     {
 976         return status = tng_frame_data_write(traj,frame_nr,block_id,data,hash_mode);
 977     }
 978
 979
 980     /**
 981     * @brief Write particle data of one trajectory frame to the output_file of
 982     * tng_data.
 983     * @param frame_nr is the index number of the frame to write.
 984     * @param block_id is the ID of the data block to write the data to.
 985     * @param val_first_particle is the number of the first particle in the data
 986     * array.
 987     * @param val_n_particles is the number of particles in the data array.
 988     * @param data is a 1D-array of data to write. The length of the array should
 989     * equal n_particles * n_values_per_frame.
 990     * @param hash_mode is an option to decide whether to use the md5 hash or not.
 991     * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be
 992     * compared to the md5 hash of the read contents to ensure valid data.
 993     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
 994     * has occurred or TNG_CRITICAL (2) if a major error has occured.
 995     */
 996     tng_function_status writeFrameParticleData(const int64_t frame_nr,
 997         const int64_t block_id,
 998         const int64_t val_first_particle,
 999         const int64_t val_n_particles,
1000         const void *data,
1001         const tng_hash_mode hash_mode)
1002     {
1003         return status = tng_frame_particle_data_write(traj,frame_nr,block_id,val_first_particle,val_n_particles,data,hash_mode);
1004     }
1005
1006
1007     /**
1008     * @brief Free data is an array of values (2D).
1009     * @param values is the 2D array to free and will be set to 0 afterwards.
1010     * @param n_frames is the number of frames in the data array.
1011     * @param n_values_per_frame is the number of values per frame in the data array.
1012     * @param type is the data type of the data in the array (e.g. int/float/char).
1013     * @return TNG_SUCCESS (0) if successful.
1014     */
1015     tng_function_status freeDataValues(union data_values **values,
1016         const int64_t n_frames,
1017         const int64_t n_values_per_frame,
1018         const tng_data_type type)
1019     {
1020         return status = tng_data_values_free(traj, values, n_frames,n_values_per_frame,type);
1021     }
1022
1023
1024     /**
1025     * @brief Free data is an array of values (3D).
1026     * @param values is the array to free and will be set to 0 afterwards.
1027     * @param n_frames is the number of frames in the data array.
1028     * @param n_particles is the number of particles in the data array.
1029     * @param n_values_per_frame is the number of values per frame in the data array.
1030     * @param type is the data type of the data in the array (e.g. int/float/char).
1031     * @return TNG_SUCCESS (0) if successful.
1032     */
1033     tng_function_status freeParticleDataValues(union data_values ***values,
1034         const int64_t n_frames,
1035         const int64_t n_particles,
1036         const int64_t n_values_per_frame,
1037         const tng_data_type type)
1038     {
1039         return status = tng_particle_data_values_free(traj, values,n_frames,n_particles,n_values_per_frame,type);
1040     }
1041
1042
1043     /**
1044     * @brief Retrieve non-particle data, from the last read frame set. Obsolete!
1045     * which file to read from. If the file (input_file) is not open it will be
1046     * opened.
1047     * @param block_id is the id number of the particle data block to read.
1048     * @param values is a pointer to a 2-dimensional array (memory unallocated), which
1049     * will be filled with data. The array will be sized
1050     * (n_frames * n_values_per_frame).
1051     * Since ***values is allocated in this function it is the callers
1052     * responsibility to free the memory.
1053     * @param n_frames is set to the number of particles in the returned data. This is
1054     * needed to properly reach and/or free the data afterwards.
1055     * @param n_values_per_frame is set to the number of values per frame in the data.
1056     * This is needed to properly reach and/or free the data afterwards.
1057     * @param type is set to the data type of the data in the array.
1058     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1059     * has occurred or TNG_CRITICAL (2) if a major error has occured.
1060     */
1061     tng_function_status getData(const int64_t block_id,
1062         union data_values ***values,
1063         int64_t *n_frames,
1064         int64_t *n_values_per_frame,
1065         char *type)
1066     {
1067         return status = tng_data_get(traj, block_id, values, n_frames,
1068                                      n_values_per_frame, type);
1069     }
1070
1071     /**
1072     * @brief Retrieve a vector (1D array) of non-particle data, from the last read frame set.
1073     * @param block_id is the id number of the particle data block to read.
1074     * @param values is a pointer to a 1-dimensional array (memory unallocated), which
1075     * will be filled with data. The length of the array will be (n_frames * n_values_per_frame).
1076     * Since **values is allocated in this function it is the callers
1077     * responsibility to free the memory.
1078     * @param n_frames is set to the number of particles in the returned data. This is
1079     * needed to properly reach and/or free the data afterwards.
1080     * @param stride_length is set to the stride length of the returned data.
1081     * @param n_values_per_frame is set to the number of values per frame in the data.
1082     * This is needed to properly reach and/or free the data afterwards.
1083     * @param type is set to the data type of the data in the array.
1084     * @details This does only work for numerical (int, float, double) data.
1085     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1086     * has occurred or TNG_CRITICAL (2) if a major error has occured.
1087     */
1088     tng_function_status getDataVector
1089                 (const int64_t block_id,
1090                  void **values,
1091                  int64_t *n_frames,
1092                  int64_t *stride_length,
1093                  int64_t *n_values_per_frame,
1094                  char *type)
1095     {
1096         return status = tng_data_vector_get(traj, block_id, values, n_frames,
1097                                             stride_length, n_values_per_frame,
1098                                             type);
1099     }
1100
1101     /**
1102     * @brief Read and retrieve non-particle data, in a specific interval. Obsolete!
1103     * which file to read from. If the file (input_file) is not open it will be
1104     * opened.
1105     * @param block_id is the id number of the particle data block to read.
1106     * @param start_frame_nr is the index number of the first frame to read.
1107     * @param end_frame_nr is the index number of the last frame to read.
1108     * @param hash_mode is an option to decide whether to use the md5 hash or not.
1109     * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
1110     * compared to the md5 hash of the read contents to ensure valid data.
1111     * @param values is a pointer to a 2-dimensional array (memory unallocated), which
1112     * will be filled with data. The array will be sized
1113     * (n_frames * n_values_per_frame).
1114     * Since ***values is allocated in this function it is the callers
1115     * responsibility to free the memory.
1116     * @param n_values_per_frame is set to the number of values per frame in the data.
1117     * This is needed to properly reach and/or free the data afterwards.
1118     * @param type is set to the data type of the data in the array.
1119     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1120     * has occurred or TNG_CRITICAL (2) if a major error has occured.
1121     */
1122     tng_function_status getDataInterval(const int64_t block_id,
1123         const int64_t start_frame_nr,
1124         const int64_t end_frame_nr,
1125         const tng_hash_mode hash_mode,
1126         union data_values ***values,
1127         int64_t *n_values_per_frame,
1128         char *type)
1129     {
1130         return status = tng_data_interval_get(traj, block_id, start_frame_nr,
1131                                               end_frame_nr, hash_mode, values,
1132                                               n_values_per_frame, type);
1133     }
1134
1135
1136     /**
1137     * @brief Read and retrieve a vector (1D array) of non-particle data,
1138     * in a specific interval.
1139     * @param block_id is the id number of the particle data block to read.
1140     * @param start_frame_nr is the index number of the first frame to read.
1141     * @param end_frame_nr is the index number of the last frame to read.
1142     * @param hash_mode is an option to decide whether to use the md5 hash or not.
1143     * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
1144     * compared to the md5 hash of the read contents to ensure valid data.
1145     * @param values is a pointer to a 1-dimensional array (memory unallocated), which
1146     * will be filled with data. The length of the array will be (n_frames * n_values_per_frame).
1147     * Since **values is allocated in this function it is the callers
1148     * responsibility to free the memory.
1149     * @param stride_length is set to the stride length (writing frequency) of
1150     * the data.
1151     * @param n_values_per_frame is set to the number of values per frame in the data.
1152     * This is needed to properly reach and/or free the data afterwards.
1153     * @param type is set to the data type of the data in the array.
1154     * @details This does only work for numerical (int, float, double) data.
1155     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1156     * has occurred or TNG_CRITICAL (2) if a major error has occured.
1157     */
1158     tng_function_status getDataVectorInterval
1159                 (const int64_t block_id,
1160                  const int64_t start_frame_nr,
1161                  const int64_t end_frame_nr,
1162                  const char hash_mode,
1163                  void **values,
1164                  int64_t *stride_length,
1165                  int64_t *n_values_per_frame,
1166                  char *type)
1167     {
1168         return status = tng_data_vector_interval_get(traj, block_id,
1169                                                      start_frame_nr,
1170                                                      end_frame_nr,
1171                                                      hash_mode, values,
1172                                                      stride_length,
1173                                                      n_values_per_frame,
1174                                                      type);
1175     }
1176
1177     /**
1178     * @brief Retrieve particle data, from the last read frame set. Obsolete!
1179     * @details The particle dimension of the returned values array is translated
1180     * to real particle numbering, i.e. the numbering of the actual molecular
1181     * system.
1182     * specifies which file to read from. If the file (input_file) is not open it
1183     * will be opened.
1184     * @param block_id is the id number of the particle data block to read.
1185     * @param values is a pointer to a 3-dimensional array (memory unallocated), which
1186     * will be filled with data. The array will be sized
1187     * (n_frames * n_particles * n_values_per_frame).
1188     * Since ****values is allocated in this function it is the callers
1189     * responsibility to free the memory.
1190     * @param n_frames is set to the number of particles in the returned data. This is
1191     * needed to properly reach and/or free the data afterwards.
1192     * @param n_particles is set to the number of particles in the returned data. This is
1193     * needed to properly reach and/or free the data afterwards.
1194     * @param n_values_per_frame is set to the number of values per frame in the data.
1195     * This is needed to properly reach and/or free the data afterwards.
1196     * @param type is set to the data type of the data in the array.
1197     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1198     * has occurred or TNG_CRITICAL (2) if a major error has occured.
1199     */
1200     tng_function_status getParticleData(const int64_t block_id,
1201         union data_values ****values,
1202         int64_t *n_frames,
1203         int64_t *n_particles,
1204         int64_t *n_values_per_frame,
1205         char *type)
1206     {
1207         return status = (tng_particle_data_get(traj, block_id, values, n_frames,
1208             n_particles, n_values_per_frame, type));
1209     }
1210
1211
1212     /**
1213     * @brief Retrieve a vector (1D array) of particle data, from the last read frame set.
1214     * @details The particle dimension of the returned values array is translated
1215     * to real particle numbering, i.e. the numbering of the actual molecular
1216     * system.
1217     * @param block_id is the id number of the particle data block to read.
1218     * @param values is a pointer to a 1-dimensional array (memory unallocated), which
1219     * will be filled with data. The length of the array will be
1220     * (n_frames * n_particles * n_values_per_frame).
1221     * Since **values is allocated in this function it is the callers
1222     * responsibility to free the memory.
1223     * @param n_frames is set to the number of frames in the returned data. This is
1224     * needed to properly reach and/or free the data afterwards.
1225     * @param stride_length is set to the stride length of the returned data.
1226     * @param n_particles is set to the number of particles in the returned data. This is
1227     * needed to properly reach and/or free the data afterwards.
1228     * @param n_values_per_frame is set to the number of values per frame in the data.
1229     * This is needed to properly reach and/or free the data afterwards.
1230     * @param type is set to the data type of the data in the array.
1231     * @details This does only work for numerical (int, float, double) data.
1232     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1233     * has occurred or TNG_CRITICAL (2) if a major error has occured.
1234     */
1235     tng_function_status getParticleDataVector
1236                 (const int64_t block_id,
1237                  void **values,
1238                  int64_t *n_frames,
1239                  int64_t *stride_length,
1240                  int64_t *n_particles,
1241                  int64_t *n_values_per_frame,
1242                  char *type)
1243     {
1244         return status = tng_particle_data_vector_get(traj, block_id,
1245                                                      values, n_frames,
1246                                                      stride_length,
1247                                                      n_particles,
1248                                                      n_values_per_frame, type);
1249     }
1250
1251
1252     /**
1253     * @brief Read and retrieve particle data, in a specific interval. Obsolete!
1254     * @details The particle dimension of the returned values array is translated
1255     * to real particle numbering, i.e. the numbering of the actual molecular
1256     * system.
1257     * @param block_id is the id number of the particle data block to read.
1258     * @param start_frame_nr is the index number of the first frame to read.
1259     * @param end_frame_nr is the index number of the last frame to read.
1260     * @param hash_mode is an option to decide whether to use the md5 hash or not.
1261     * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
1262     * compared to the md5 hash of the read contents to ensure valid data.
1263     * @param values is a pointer to a 3-dimensional array (memory unallocated), which
1264     * will be filled with data. The array will be sized
1265     * (n_frames * n_particles * n_values_per_frame).
1266     * Since ****values is allocated in this function it is the callers
1267     * responsibility to free the memory.
1268     * @param n_particles is set to the number of particles in the returned data. This is
1269     * needed to properly reach and/or free the data afterwards.
1270     * @param n_values_per_frame is set to the number of values per frame in the data.
1271     * This is needed to properly reach and/or free the data afterwards.
1272     * @param type is set to the data type of the data in the array.
1273     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1274     * has occurred or TNG_CRITICAL (2) if a major error has occured.
1275     */
1276     tng_function_status getParticleDataInterval(const int64_t block_id,
1277         const int64_t start_frame_nr,
1278         const int64_t end_frame_nr,
1279         const tng_hash_mode hash_mode,
1280         union data_values ****values,
1281         int64_t *n_particles,
1282         int64_t *n_values_per_frame,
1283         char *type)
1284     {
1285         return status = (tng_particle_data_interval_get(traj, block_id, start_frame_nr,
1286             end_frame_nr, hash_mode, values,
1287             n_particles, n_values_per_frame,
1288             type));
1289     }
1290
1291
1292     /**
1293     * @brief Read and retrieve a vector (1D array) particle data, in a
1294     * specific interval.
1295     * @details The particle dimension of the returned values array is translated
1296     * to real particle numbering, i.e. the numbering of the actual molecular
1297     * system.
1298     * @param block_id is the id number of the particle data block to read.
1299     * @param start_frame_nr is the index number of the first frame to read.
1300     * @param end_frame_nr is the index number of the last frame to read.
1301     * @param hash_mode is an option to decide whether to use the md5 hash or not.
1302     * If hash_mode == TNG_USE_HASH the md5 hash in the file will be
1303     * compared to the md5 hash of the read contents to ensure valid data.
1304     * @param values is a pointer to a 1-dimensional array (memory unallocated), which
1305     * will be filled with data. The length of the array will be
1306     * (n_frames * n_particles * n_values_per_frame).
1307     * Since **values is allocated in this function it is the callers
1308     * responsibility to free the memory.
1309     * @param stride_length is set to the stride length (writing frequency) of
1310     * the data.
1311     * @param n_particles is set to the number of particles in the returned data. This is
1312     * needed to properly reach and/or free the data afterwards.
1313     * @param n_values_per_frame is set to the number of values per frame in the data.
1314     * This is needed to properly reach and/or free the data afterwards.
1315     * @param type is set to the data type of the data in the array.
1316     * @details This does only work for numerical (int, float, double) data.
1317     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1318     * has occurred or TNG_CRITICAL (2) if a major error has occured.
1319     */
1320     tng_function_status getParticleDataVectorInterval
1321                 (const int64_t block_id,
1322                  const int64_t start_frame_nr,
1323                  const int64_t end_frame_nr,
1324                  const tng_hash_mode hash_mode,
1325                  void **values,
1326                  int64_t *n_particles,
1327                  int64_t *stride_length,
1328                  int64_t *n_values_per_frame,
1329                  char *type)
1330     {
1331         return status = tng_particle_data_vector_interval_get(traj, block_id,
1332                                                               start_frame_nr,
1333                                                               end_frame_nr,
1334                                                               hash_mode,
1335                                                               values,
1336                                                               n_particles,
1337                                                               stride_length,
1338                                                               n_values_per_frame,
1339                                                               type);
1340     }
1341
1342
1343     /** @brief Get the date and time of initial file creation in ISO format (string).
1344     *  @param time is a pointer to the string in which the date will be stored. Memory
1345     must be reserved beforehand.
1346     * @return TNG_SUCCESS (0) if successful.
1347     */
1348     tng_function_status getTimeStr(char *time)
1349     {
1350         return status = tng_time_get_str(traj, time);
1351     }
1352
1353
1354 };
1355
1356
1357
1358
1359
1360 class Molecule
1361 {
1362 private:
1363
1364     tng_molecule_t mol;
1365     Trajectory * traj;
1366     tng_function_status status;
1367 public:
1368     tng_function_status addChain(const char *name, Chain *chain);
1369     tng_function_status findChain(const char *name, int64_t id, Chain *chain);
1370     friend class Trajectory;
1371     //Constructor
1372     Molecule(Trajectory * trajectory)
1373     {
1374         traj = trajectory;
1375
1376         //status = tng_molecule_init(traj->traj,mol);
1377     }
1378     /**
1379      *@Dose nothing, use ~TngMolecule()
1380     */
1381     ~Molecule()
1382     {
1383         status = tng_molecule_destroy(traj->traj,mol);
1384     }
1385         //! Status
1386     tng_function_status getStatus()
1387     { return status; }
1388
1389
1390     /**
1391     * @brief Set the name of a molecule.
1392     * @param new_name is a string containing the wanted name.
1393     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1394     * error has occured.
1395     */
1396     tng_function_status setName(const char *new_name)
1397     {
1398         return status = tng_molecule_name_set(traj->traj,mol,new_name);
1399     }
1400
1401     /**
1402     * @brief Get the count of a molecule.
1403     * @param cnt is a pointer to the variable to be populated with the count.
1404     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1405     * has occurred or TNG_CRITICAL (2) if a major error has occured.
1406     */
1407     tng_function_status getCnt(int64_t *cnt)
1408     {
1409         return status = tng_molecule_cnt_get(traj->traj,mol,cnt);
1410     }
1411
1412     /**
1413     * @brief Set the count of a molecule.
1414     * @param cnt is the number of instances of this molecule.
1415     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error
1416     * has occurred or TNG_CRITICAL (2) if a major error has occured.
1417     */
1418     tng_function_status setCnt(int64_t cnt)
1419     {
1420         return status = tng_molecule_cnt_set(traj->traj,mol,cnt);
1421     }
1422
1423 };
1424
1425     tng_function_status Trajectory::addMolecule(const char *name, Molecule_t molecule)
1426 {
1427     return status = tng_molecule_add(traj,name, &molecule->mol);
1428 }
1429
1430     tng_function_status Trajectory::addMoleculeWithId
1431                 (const char *name,
1432                  const int64_t id,
1433                  Molecule_t molecule)
1434 {
1435     return status = tng_molecule_w_id_add(traj, name, id, &molecule->mol);
1436 }
1437
1438 /**
1439 * @brief Find a molecule.
1440 * @param tng_data is the trajectory data container containing the molecule.
1441 * @param name is a string containing the name of the molecule. If name is empty
1442 * only id will be used for finding the molecule.
1443 * @param id is the id of the molecule to look for. If id is -1 only the name of
1444 * the molecule will be used for finding the molecule.
1445 * @param molecule is a pointer to the molecule if it was found - otherwise 0.
1446 * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the
1447 * molecule is not found.
1448 * @details If name is an empty string and id is -1 the first molecule will be
1449 * found.
1450 */
1451 tng_function_status Trajectory::findMolecule
1452                 (const char *name,
1453                 int64_t id,
1454                 Molecule_t molecule)
1455 {
1456     return status = tng_molecule_find(traj, name, id,
1457                             &molecule->mol);
1458 }
1459
1460
1461 class Atom
1462 {
1463 private:
1464     tng_atom_t atom;
1465     Trajectory * traj;
1466     tng_function_status status;
1467 public:
1468     friend class Residue;
1469     //constructor
1470     Atom(Trajectory * trajectory)
1471     {
1472         traj = trajectory;
1473     }
1474     //deonstructor
1475     /**
1476      *@Dose nothing, use ~TngMolecule()
1477     */
1478         ~Atom()
1479     {
1480         //delete atom;
1481     }
1482             //! Status
1483     tng_function_status getStatus()
1484     { return status; }
1485     /**
1486     * @brief Set the name of an atom.
1487     * @param new_name is a string containing the wanted name.
1488     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1489     * error has occured.
1490     */
1491     tng_function_status setName(const char *new_name)
1492     {
1493         return status = tng_atom_name_set(traj->traj, atom , new_name);
1494     }
1495
1496     /**
1497     * @param new_type is a string containing the atom type.
1498     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1499     * error has occured.
1500     */
1501     tng_function_status setType(const char *new_type)
1502     {
1503         return status = tng_atom_type_set(traj->traj, atom, new_type);
1504     }
1505 };
1506
1507 class Residue
1508 {
1509     private:
1510     tng_residue_t residue;
1511     Trajectory * traj;
1512     tng_function_status status;
1513 public:
1514     friend class Chain;
1515     //constructor
1516     Residue(Trajectory  * trajectory)
1517     {
1518         traj = trajectory;
1519     }
1520     //deonstructor
1521     /**
1522      *@Dose nothing, use ~TngMolecule()
1523     */
1524         ~Residue()
1525     {
1526         //delete residue;
1527     }
1528     //! Status
1529     tng_function_status getStatus()
1530     { return status; }
1531     /**
1532     * @brief Set the name of a residue.
1533     * @param residue is the residue to rename.
1534     * @param new_name is a string containing the wanted name.
1535     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1536     * error has occured.
1537     */
1538     tng_function_status setName(const char *new_name)
1539     {
1540         return status = tng_residue_name_set(traj->traj, residue,new_name);
1541     }
1542
1543     /**
1544     * @brief Add an atom to a residue.
1545     * @param atom_name is a string containing the name of the atom.
1546     * @param atom_type is a string containing the atom type of the atom.
1547     * @param atom is a pointer to the newly created atom.
1548     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1549     * error has occured.
1550     */
1551     tng_function_status addAtom(const char *atom_name,
1552         const char *atom_type,
1553         Atom * atom)
1554     {
1555         return status = tng_residue_atom_add(traj->traj, residue, atom_name,
1556                                              atom_type, &atom->atom);
1557     }
1558
1559
1560     /**
1561     * @brief Add an atom with a specific ID to a residue.
1562     * @param atom_name is a string containing the name of the atom.
1563     * @param atom_type is a string containing the atom type of the atom.
1564     * @param id is the ID of the created atom.
1565     * @param atom is a pointer to the newly created atom.
1566     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1567     * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1568     */
1569     tng_function_status addAtomWithId
1570                 (const char *atom_name,
1571                  const char *atom_type,
1572                  const int64_t id,
1573                  Atom * atom)
1574     {
1575         return status = tng_residue_atom_w_id_add(traj->traj, residue,
1576                                                   atom_name, atom_type,
1577                                                   id, &atom->atom);
1578     }
1579
1580 };
1581
1582 class Chain
1583 {
1584     private:
1585     tng_chain_t chain;
1586     Trajectory * traj;
1587     tng_function_status status;
1588 public:
1589     friend class Molecule;
1590     //constructor
1591     Chain(Trajectory * trajectory)
1592     {
1593         traj = trajectory;
1594     }
1595     //deonstructor
1596     /**
1597      *@Dose nothing, use ~TngMolecule()
1598     */
1599         ~Chain()
1600     {
1601         //delete chain;
1602     }
1603     //! Status
1604     tng_function_status getStatus()
1605     { return status; }
1606     /**
1607     * @brief Set the name of a chain.
1608     * @param new_name is a string containing the wanted name.
1609     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1610     * error has occured.
1611     */
1612     tng_function_status setName(const char *new_name)
1613     {
1614         return status  = tng_chain_name_set(traj->traj, chain, new_name);
1615     }
1616
1617
1618     /**
1619     * @brief Find a residue in a chain.
1620     * @param name is a string containing the name of the residue.
1621     * @param id is the id of the residue to find. If id == -1 the first residue
1622     * that matches the specified name will be found.
1623     * @param residue is a pointer to the residue if it was found - otherwise 0.
1624     * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the
1625     * residue is not found.
1626     * @details If name is an empty string the first residue will be found.
1627     */
1628     tng_function_status findResidue
1629                 (const char *name,
1630                  int64_t id,
1631                  Residue *residue)
1632     {
1633         return status = tng_chain_residue_find(traj->traj, chain, name,
1634                                                id, &residue->residue);
1635     }
1636
1637     /**
1638     * @brief Add a residue to a chain.
1639     * @param name is a string containing the name of the residue.
1640     * @param residue is a pointer to the newly created residue.
1641     * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1642     * error has occured.
1643     */
1644     tng_function_status addResidue(const char *name,
1645         Residue * residue)
1646     {
1647         return status = tng_chain_residue_add(traj->traj, chain,
1648                                               name, &residue->residue);
1649     }
1650
1651     /**
1652     * @brief Add a residue with a specific ID to a chain.
1653     * @param name is a string containing the name of the residue.
1654     * @param id is the ID of the created residue.
1655     * @param residue is a pointer to the newly created residue.
1656     * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could
1657     * not be set properly or TNG_CRITICAL (2) if a major error has occured.
1658     */
1659     tng_function_status addResidueWithId
1660                 (const char *name,
1661                  const int64_t id,
1662                  Residue * residue)
1663     {
1664         return status = tng_chain_residue_w_id_add(traj->traj, chain,
1665                                                    name, id, &residue->residue);
1666     }
1667 };
1668
1669 /**
1670 * @brief Add a chain to a molecule.
1671 * @param name is a string containing the name of the chain.
1672 * @param chain s a pointer to the newly created chain.
1673 * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major
1674 * error has occured.
1675 */
1676 tng_function_status Molecule::addChain(const char *name, Chain *chain)
1677 {
1678     return status = tng_molecule_chain_add(traj->traj,mol,name,&chain->chain);
1679 }
1680
1681 /**
1682 * @brief Find a chain in a molecule.
1683 * @param name is a string containing the name of the chain. If name is empty
1684 * only id will be used for finding the chain.
1685 * @param id is the id of the chain to look for. If id is -1 only the name of
1686 * the chain will be used for finding the chain.
1687 * @param chain is a pointer to the chain if it was found - otherwise 0.
1688 * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the
1689 * chain is not found.
1690 * @details If name is an empty string and id is -1 the first chain will be
1691 * found.
1692 */
1693 tng_function_status Molecule::findChain
1694                 (const char *name,
1695                 int64_t id,
1696                 Chain *chain)
1697 {
1698     return status = tng_molecule_chain_find(traj->traj, mol, name, id,
1699                                             &chain->chain);
1700 }
1701
1702 }
1703 #endif