From ba9aea42b01c0563e0ff0a886999daeaf6b570a7 Mon Sep 17 00:00:00 2001 From: Magnus Lundborg Date: Sun, 22 Jun 2014 16:24:43 +0200 Subject: Version 1.6 of the TNG library. Added functions to get the version of the header and the library. Improved version control of the library using CMake config and version files. Changed tng_util_frame_current_compression_get() return type to double before the API is widely circulated (no release has been made since that function was added). Compiling compression functions into the tng_io library. Uses BuildTNG.cmake instead of including add_subdirectories. Change-Id: I5e4818736fb2632c06ca7df8e84ce9544bf2acaf diff --git a/BuildTNG.cmake b/BuildTNG.cmake new file mode 100644 index 0000000..f4f2caf --- /dev/null +++ b/BuildTNG.cmake @@ -0,0 +1,71 @@ +set(TNG_ROOT_SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR}) +file(RELATIVE_PATH TNG_ROOT_BINARY_DIR ${CMAKE_SOURCE_DIR} ${TNG_ROOT_SOURCE_DIR}) +set(TNG_ROOT_BINARY_DIR ${CMAKE_BINARY_DIR}/${TNG_ROOT_BINARY_DIR}) + +function (TNG_GENERATE_VERSION_H) + set(TNG_MAJOR_VERSION "1") + set(TNG_MINOR_VERSION "6") + set(TNG_VERSION_PATCH_LEVEL "0") + set(TNG_IO_VERSION "${TNG_MAJOR_VERSION}.${TNG_MINOR_VERSION}.${TNG_VERSION_PATCH_LEVEL}") + set(TNG_API_VERSION "6") + configure_file(${TNG_ROOT_SOURCE_DIR}/include/tng/version.h.in + ${TNG_ROOT_BINARY_DIR}/include/tng/version.h) + + set(TNG_MAJOR_VERSION ${TNG_MAJOR_VERSION} PARENT_SCOPE) + set(TNG_IO_VERSION ${TNG_IO_VERSION} PARENT_SCOPE) +endfunction() + +tng_generate_version_h() + +include(TestBigEndian) +test_big_endian(TNG_INTEGER_BIG_ENDIAN) +include(CheckIncludeFile) +check_include_file(inttypes.h TNG_HAVE_INTTYPES_H) + +macro(TNG_GET_SOURCE_LIST TNG_SOURCELIST TNG_COMPILEDEFS) + include_directories(${TNG_ROOT_SOURCE_DIR}/include) + include_directories(${TNG_ROOT_BINARY_DIR}/include) + set(_tng_compression_sources bwlzh.c bwt.c coder.c dict.c fixpoint.c huffman.c huffmem.c lz77.c merge_sort.c mtf.c rle.c tng_compress.c vals16.c warnmalloc.c widemuldiv.c xtc2.c xtc3.c) + set(_tng_io_sources tng_io.c md5.c) + set(${TNG_SOURCELIST}) + set(${TNG_COMPILEDEFS}) + foreach(_file ${_tng_compression_sources}) + list(APPEND ${TNG_SOURCELIST} ${TNG_ROOT_SOURCE_DIR}/src/compression/${_file}) + endforeach() + foreach(_file ${_tng_io_sources}) + list(APPEND ${TNG_SOURCELIST} ${TNG_ROOT_SOURCE_DIR}/src/lib/${_file}) + endforeach() + if(TNG_BUILD_FORTRAN) + list(APPEND ${TNG_SOURCELIST} ${TNG_ROOT_SOURCE_DIR}/src/lib/tng_io_fortran.c) + endif() + if (TNG_HAVE_INTTYPES_H) + list(APPEND ${TNG_COMPILEDEFS} USE_STD_INTTYPES_H) + endif() +endmacro() + +macro(TNG_SET_SOURCE_PROPERTIES) + set(_tng_with_zlib OFF) + set(_curr_var) + foreach (_arg ${ARGN}) + if (_arg STREQUAL "WITH_ZLIB") + set(_curr_var with_zlib) + elseif (_curr_var) + set(_tng_${_curr_var} ${_arg}) + set(_curr_var "") + else() + message(FATAL_ERROR "Invalid argument ${_arg} to TNG_SET_SOURCE_PROPERTIES") + endif() + endforeach() + if (_tng_with_zlib) + set_property(SOURCE ${TNG_ROOT_SOURCE_DIR}/src/lib/tng_io.c + APPEND PROPERTY COMPILE_DEFINITIONS USE_ZLIB) + endif() + if (TNG_HAVE_INTTYPES_H) + set_property(SOURCE ${TNG_ROOT_SOURCE_DIR}/src/lib/tng_io.c + APPEND PROPERTY COMPILE_DEFINITIONS USE_STD_INTTYPES_H) + endif() + if (TNG_INTEGER_BIG_ENDIAN) + set_property(SOURCE ${TNG_ROOT_SOURCE_DIR}/src/lib/md5.c + APPEND PROPERTY COMPILE_DEFINITIONS TNG_INTEGER_BIG_ENDIAN) + endif() +endmacro() diff --git a/CMakeLists.txt b/CMakeLists.txt index 871d17e..7fc6ad6 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,12 +1,7 @@ cmake_minimum_required(VERSION 2.8.8) project(TNG_IO) -set(PROJECT_VERSION "1.5") -set(API_VERSION "5") -configure_file(${CMAKE_CURRENT_SOURCE_DIR}/include/version.h.in - ${CMAKE_BINARY_DIR}/include/version.h ) -include_directories(${CMAKE_BINARY_DIR}/include) if("${CMAKE_C_COMPILER_ID}" STREQUAL "GNU") set(CMAKE_C_FLAGS_DEBUG "${CMAKE_C_FLAGS_DEBUG} -Wall") @@ -31,9 +26,47 @@ option(TNG_BUILD_WITH_ZLIB "Build TNG with zlib compression" ${ZLIB_FOUND}) include(CheckIncludeFile) check_include_file(inttypes.h HAVE_INTTYPES_H) -add_subdirectory(src) +include(BuildTNG.cmake) +tng_get_source_list(TNG_SOURCES TNG_COMPILE_DEFS) + +tng_set_source_properties(WITH_ZLIB ${ZLIB_FOUND}) + +if (ZLIB_FOUND) + list(APPEND EXTRA_LIBRARIES ${ZLIB_LIBRARIES}) +endif() + +if (UNIX) + list(APPEND EXTRA_LIBRARIES m) +endif() + +add_library(tng_io ${TNG_SOURCES}) + +target_link_libraries(tng_io ${EXTRA_LIBRARIES}) -install(FILES include/tng_io.h include/tng_io_fwd.h DESTINATION include/) +set_target_properties(tng_io PROPERTIES VERSION ${TNG_IO_VERSION} SOVERSION ${TNG_MAJOR_VERSION}) + +# Create the tng_ioConfig.cmake and tng_ioConfigVersion.cmake files for the install tree +set(CONF_INCLUDE_DIRS "${CMAKE_INSTALL_PREFIX}/include") +configure_file( src/lib/tng_io-config.cmake.in + "${CMAKE_CURRENT_BINARY_DIR}/cmake/tng_io-config.cmake" @ONLY) +configure_file( src/lib/tng_io-configVersion.cmake.in + "${CMAKE_CURRENT_BINARY_DIR}/cmake/tng_io-configVersion.cmake" @ONLY) + +# Use GNUInstallDirst to set paths on multiarch systems +include(GNUInstallDirs) + +# Install the tng_ioConfig.cmake and tng_ioConfigVersion.cmake +install(FILES + "${CMAKE_CURRENT_BINARY_DIR}/cmake/tng_io-config.cmake" + "${CMAKE_CURRENT_BINARY_DIR}/cmake/tng_io-configVersion.cmake" + DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/tng_io") + +install(TARGETS tng_io + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}) + +install(FILES include/tng/tng_io.h include/tng/tng_io_fwd.h ${CMAKE_CURRENT_BINARY_DIR}/include/tng/version.h + DESTINATION include/tng) #-- Add an Option to toggle the generation of the API documentation option(TNG_BUILD_DOCUMENTATION "Use Doxygen to create the HTML based API documentation" OFF) @@ -57,3 +90,5 @@ if(TNG_BUILD_DOCUMENTATION) DESTINATION share/tng/doc) endif() +add_subdirectory(src) + diff --git a/Doxyfile.in b/Doxyfile.in index 3d6f0f7..03ba553 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -658,7 +658,7 @@ RECURSIVE = NO # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = @PROJECT_SOURCE_DIR@/src/lib/md5.c @PROJECT_SOURCE_DIR@/include/md5.h @PROJECT_SOURCE_DIR@/include/tng_io.hpp @PROJECT_SOURCE_DIR@/src/lib/tng_io.c +EXCLUDE = @PROJECT_SOURCE_DIR@/src/lib/md5.c @PROJECT_SOURCE_DIR@/include/tng/md5.h @PROJECT_SOURCE_DIR@/include/tng/tng_io.hpp @PROJECT_SOURCE_DIR@/src/lib/tng_io.c # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded diff --git a/include/md5.h b/include/md5.h deleted file mode 100644 index 80fbf6c..0000000 --- a/include/md5.h +++ /dev/null @@ -1,113 +0,0 @@ - -/* This file has been modified in the TNG library distribution. Modifications - * are marked below. */ - -/* - Copyright (C) 1999, 2002 Aladdin Enterprises. All rights reserved. - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. - - L. Peter Deutsch - ghost@aladdin.com - - */ -/* - Independent implementation of MD5 (RFC 1321). - - This code implements the MD5 Algorithm defined in RFC 1321, whose - text is available at - http://www.ietf.org/rfc/rfc1321.txt - The code is derived from the text of the RFC, including the test suite - (section A.5) but excluding the rest of Appendix A. It does not include - any code or documentation that is identified in the RFC as being - copyrighted. - - The original and principal author of md5.h is L. Peter Deutsch - . Other authors are noted in the change history - that follows (in reverse chronological order): - - 2002-04-13 lpd Removed support for non-ANSI compilers; removed - references to Ghostscript; clarified derivation from RFC 1321; - now handles byte order either statically or dynamically. - 1999-11-04 lpd Edited comments slightly for automatic TOC extraction. - 1999-10-18 lpd Fixed typo in header comment (ansi2knr rather than md5); - added conditionalization for C++ compilation from Martin - Purschke . - 1999-05-03 lpd Original version. - */ - -#ifndef md5_INCLUDED -# define md5_INCLUDED - - -/* - * This package supports both compile-time and run-time determination of CPU - * byte order. If ARCH_IS_BIG_ENDIAN is defined as 0, the code will be - * compiled to run only on little-endian CPUs; if ARCH_IS_BIG_ENDIAN is - * defined as non-zero, the code will be compiled to run only on big-endian - * CPUs; if ARCH_IS_BIG_ENDIAN is not defined, the code will be compiled to - * run on either big- or little-endian CPUs, but will run slightly less - * efficiently on either one than if ARCH_IS_BIG_ENDIAN is defined. - */ - -typedef unsigned char md5_byte_t; /* 8-bit byte */ -typedef unsigned int md5_word_t; /* 32-bit word */ - -/* Define the state of the MD5 Algorithm. */ -typedef struct md5_state_s { - md5_word_t count[2]; /* message length in bits, lsw first */ - md5_word_t abcd[4]; /* digest buffer */ - md5_byte_t buf[64]; /* accumulate block */ -} md5_state_t; - -#ifdef __cplusplus -extern "C" -{ -#endif - -/* The USE_WINDOWS define below was added in TNG library distribution of this - * file in order to compile properly in MSVC */ -#ifndef USE_WINDOWS -#if defined(WIN32) || defined(_WIN32) || defined(WIN64) || defined(_WIN64) -#define USE_WINDOWS -#endif /* win32... */ -#endif /* not defined USE_WINDOWS */ - -/* The DECLSPECDLLEXPORT define below was added in the TNG library distribution - * of this file. It is also used in the function declarations. */ -#ifndef DECLSPECDLLEXPORT -#ifdef USE_WINDOWS -#define DECLSPECDLLEXPORT __declspec(dllexport) -#else /* USE_WINDOWS */ -#define DECLSPECDLLEXPORT -#endif /* USE_WINDOWS */ -#endif /* DECLSPECDLLEXPORT */ - -/* Initialize the algorithm. */ -void DECLSPECDLLEXPORT md5_init(md5_state_t *pms); - -/* Append a string to the message. */ -void DECLSPECDLLEXPORT md5_append(md5_state_t *pms, const md5_byte_t *data, int nbytes); - -/* Finish the message and return the digest. */ -void DECLSPECDLLEXPORT md5_finish(md5_state_t *pms, md5_byte_t digest[16]); - -#ifdef __cplusplus -} /* end extern "C" */ -#endif - -#endif /* md5_INCLUDED */ diff --git a/include/tng/md5.h b/include/tng/md5.h new file mode 100644 index 0000000..80fbf6c --- /dev/null +++ b/include/tng/md5.h @@ -0,0 +1,113 @@ + +/* This file has been modified in the TNG library distribution. Modifications + * are marked below. */ + +/* + Copyright (C) 1999, 2002 Aladdin Enterprises. All rights reserved. + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. + + L. Peter Deutsch + ghost@aladdin.com + + */ +/* + Independent implementation of MD5 (RFC 1321). + + This code implements the MD5 Algorithm defined in RFC 1321, whose + text is available at + http://www.ietf.org/rfc/rfc1321.txt + The code is derived from the text of the RFC, including the test suite + (section A.5) but excluding the rest of Appendix A. It does not include + any code or documentation that is identified in the RFC as being + copyrighted. + + The original and principal author of md5.h is L. Peter Deutsch + . Other authors are noted in the change history + that follows (in reverse chronological order): + + 2002-04-13 lpd Removed support for non-ANSI compilers; removed + references to Ghostscript; clarified derivation from RFC 1321; + now handles byte order either statically or dynamically. + 1999-11-04 lpd Edited comments slightly for automatic TOC extraction. + 1999-10-18 lpd Fixed typo in header comment (ansi2knr rather than md5); + added conditionalization for C++ compilation from Martin + Purschke . + 1999-05-03 lpd Original version. + */ + +#ifndef md5_INCLUDED +# define md5_INCLUDED + + +/* + * This package supports both compile-time and run-time determination of CPU + * byte order. If ARCH_IS_BIG_ENDIAN is defined as 0, the code will be + * compiled to run only on little-endian CPUs; if ARCH_IS_BIG_ENDIAN is + * defined as non-zero, the code will be compiled to run only on big-endian + * CPUs; if ARCH_IS_BIG_ENDIAN is not defined, the code will be compiled to + * run on either big- or little-endian CPUs, but will run slightly less + * efficiently on either one than if ARCH_IS_BIG_ENDIAN is defined. + */ + +typedef unsigned char md5_byte_t; /* 8-bit byte */ +typedef unsigned int md5_word_t; /* 32-bit word */ + +/* Define the state of the MD5 Algorithm. */ +typedef struct md5_state_s { + md5_word_t count[2]; /* message length in bits, lsw first */ + md5_word_t abcd[4]; /* digest buffer */ + md5_byte_t buf[64]; /* accumulate block */ +} md5_state_t; + +#ifdef __cplusplus +extern "C" +{ +#endif + +/* The USE_WINDOWS define below was added in TNG library distribution of this + * file in order to compile properly in MSVC */ +#ifndef USE_WINDOWS +#if defined(WIN32) || defined(_WIN32) || defined(WIN64) || defined(_WIN64) +#define USE_WINDOWS +#endif /* win32... */ +#endif /* not defined USE_WINDOWS */ + +/* The DECLSPECDLLEXPORT define below was added in the TNG library distribution + * of this file. It is also used in the function declarations. */ +#ifndef DECLSPECDLLEXPORT +#ifdef USE_WINDOWS +#define DECLSPECDLLEXPORT __declspec(dllexport) +#else /* USE_WINDOWS */ +#define DECLSPECDLLEXPORT +#endif /* USE_WINDOWS */ +#endif /* DECLSPECDLLEXPORT */ + +/* Initialize the algorithm. */ +void DECLSPECDLLEXPORT md5_init(md5_state_t *pms); + +/* Append a string to the message. */ +void DECLSPECDLLEXPORT md5_append(md5_state_t *pms, const md5_byte_t *data, int nbytes); + +/* Finish the message and return the digest. */ +void DECLSPECDLLEXPORT md5_finish(md5_state_t *pms, md5_byte_t digest[16]); + +#ifdef __cplusplus +} /* end extern "C" */ +#endif + +#endif /* md5_INCLUDED */ diff --git a/include/tng/tng_io.h b/include/tng/tng_io.h new file mode 100644 index 0000000..42119a5 --- /dev/null +++ b/include/tng/tng_io.h @@ -0,0 +1,4878 @@ +/* This code is part of the tng binary trajectory format. + * + * Written by Magnus Lundborg + * Copyright (c) 2012-2014, The GROMACS development team. + * Check out http://www.gromacs.org for more information. + * + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the Revised BSD License. + */ + +/** @file tng_io.h + * @brief API for input and output of tng trajectory files + * @mainpage TNG: A flexible binary trajectory format + * @section intro_sec Introduction + * + * The TNG format is developed as part of the ScalaLife EU project. + * It is flexible by design to allow parallel writing, custom data blocks, + * different output frequencies and different compression algorithms. + * + * Each block can contain MD5 hashes to verify data integrity and the file + * can be signed by the user to ensure that the origin is correct. + * + * The intention is that the API and ABI should be stable, but it is + * still possible that future changes might make that impossible, in which + * case that will be clarified. + * + * The API and all examples are released without any warranties. Use them at + * your own risk. + * + * @section authors_sec Authors + * + * The TNG trajectory format is developed by: + * + * Magnus Lundborg magnus.lundborg@scilifelab.se + * + * Daniel Spångberg daniels@mkem.uu.se + * + * Rossen Apostolov rossen@kth.se + * + * The API is implemented mainly by: + * + * Magnus Lundborg + * + * @section License + * + * Copyright (c) 2012, The GROMACS development team. + * check out http://www.gromacs.org for more information. + * + * The TNG API is released under the Revised BSD License and is free to + * redistribute according to that license. + * + * A license file (named COPYING) should be included with each copy of the API. + * + * @section install_sec Installation + * + * \code + * mkdir build + * + * cd build + * + * cmake .. + * + * make + * + * make install + * \endcode + * Test by running: + * \code + * bin/tests/tng_testing + * \endcode + * + * @section change_sec Change Log + * + * See git log for full revision history. + * + * Revisions + * + * v. 1.6 - Fourth stable release of the API. + * + * - Removed OpenMP option when building. + * - Functionality for migrating data blocks. + * - Improved handling of molecules. + * - Improved installation of TNG documentation. + * - Enhancements to CMake usage. + * - Required CMake version raised to 2.8.8. + * - Bugs fixed. + * + * v. 1.5 - Third stable release of the API. + * + * - Fortran wrapper split into separate file + * - Added more block IDs. + * - Some new functions and utility functions added. + * - Improved compression precision settings. + * - Improved tests. + * - Make appending to file work better. + * - Modified CMake settings + * - Bugs fixed + * + * v. 1.4 - Changed from LGPL to the Revised BSD License. + * + * - More flexible support for digital signatures in header. + * - Block ID numbers changed. + * + * v. 1.3 - Second stable release of the API. + * + * - Added multiplication factor for coordinate units to general info. + * - Added time stamps and time per frame in frame sets. + * - High-level API functions added (not for managing molecules yet) + * - Added functions for reading data blocks into 1D arrays. + * - TNG compression added. + * - C++ interface added. + * - Avoid memory allocation if no data is submitted when adding data + * blocks. + * - Added function tng_num_frames_per_frame_set_set + * - Added data block IDs for charges, b-factors and occupancy. + * - GZIP compression added. + * - Fixed bug when updating MD5 hashes of data blocks. + * - Fixed bug in chain_name_of_particle_get(...) + * - Update frame set pointers properly. + * - Moved fortran wrapper from header file to source file. + * - Write sparse data in mdrun examples. + * - Fixed bugs related to reading and writing sparse data. + * - Fixed memory leak for non-trajectory particle data blocks. + * - Fixed bug when writing data blocks. + * - Fixed wrong values in dependency constants + * - Write box shape, partial charges and annotation data in tng_testing + * - Bug fixes in tng_testing (frame sets not written before) + * + * v. 1.0 - First stable release of the API. + * + * + * @section examples_sec Examples + * + * There are some examples of how to use the library located in src/tests/ + * + * @subsection tng_subsec TNG files + * + * The build directory contains an example_files directory, which in turn + * contains a very short example of a TNG file containing a few water molecules, + * a box shape description and positions in 10 frames. + * + * It is also possible to run the bin/examples/md_openmp_util + * (see src/tests/md_openmp_util.c) + * testing program, which will save MD simulations output to a new file + * (saved in the example_files directory). + * + * These files can be read using the bin/examples/tng_io_read_pos_util + * program. + * + * @subsection c_subsec C + * + * Example writing data to a TNG file (just an excerpt): + * \code + * for ( step = 1; step < step_num; step++ ) + * { + * compute ( np, nd, pos, vel, mass, force, &potential, &kinetic ); + * + * if(step % step_save == 0) + * { + * // Write positions, velocities and forces + * if(tng_util_pos_write(traj, step, pos) != TNG_SUCCESS) + * { + * printf("Error adding data. %s: %d\n", __FILE__, __LINE__); + * break; + * } + * if(tng_util_vel_write(traj, step, vel) != TNG_SUCCESS) + * { + * printf("Error adding data. %s: %d\n", __FILE__, __LINE__); + * break; + * } + * if(tng_util_force_write(traj, step, force) != TNG_SUCCESS) + * { + * printf("Error adding data. %s: %d\n", __FILE__, __LINE__); + * break; + * } + * } + * update ( np, nd, pos, vel, force, acc, mass, dt ); + * } + * \endcode + * + * Example reading positions from a TNG file: + * \code + * #include + * #include + * #include "tng/tng_io.h" + * + * int main(int argc, char **argv) + * { + * tng_trajectory_t traj; + * // Assume that the data is stored as floats. The data is placed in 1-D + * // arrays + * float *positions = 0, *box_shape = 0; + * int64_t n_particles, n_frames, tot_n_frames, stride_length, i, j; + * // Set a default frame range + * int64_t first_frame = 0, last_frame = 5000; + * int k; + * + * // A reference must be passed to allocate memory + * tng_util_trajectory_open(argv[1], 'r', &traj); + * + * if(tng_num_frames_get(traj, &tot_n_frames) != TNG_SUCCESS) + * { + * printf("Cannot determine the number of frames in the file\n"); + * tng_util_trajectory_close(&traj); + * exit(1); + * } + * + * if(tng_num_particles_get(traj, &n_particles) != TNG_SUCCESS) + * { + * printf("Cannot determine the number of particles in the file\n"); + * tng_util_trajectory_close(&traj); + * exit(1); + * } + * + * printf("%"PRId64" frames in file\n", tot_n_frames); + * + * if(last_frame > tot_n_frames - 1) + * { + * last_frame = tot_n_frames - 1; + * } + * + * if(tng_util_box_shape_read(traj, &box_shape, &stride_length) == + * TNG_SUCCESS) + * { + * printf("Simulation box shape: "); + * for(i=0; i < 9; i++) + * { + * printf("%f ", box_shape[i]); + * } + * printf("\n"); + * } + * else + * { + * printf("Simulation box shape not set in the file (or could not be read)\n"); + * } + * + * n_frames = last_frame - first_frame + 1; + * + * + * // Get the positions of all particles in the requested frame range. + * // The positions are stored in the positions array. + * // N.B. No proper error checks. + * if(tng_util_pos_read_range(traj, 0, last_frame, &positions, &stride_length) + * == TNG_SUCCESS) + * { + * // Print the positions of the wanted particle (zero based) + * for(i=0; i < n_frames; i += stride_length) + * { + * printf("\nFrame %"PRId64":\n", first_frame + i); + * for(j=0; j < n_particles; j++) + * { + * printf("Atom nr: %"PRId64"", j); + * for(k=0; k < 3; k++) + * { + * printf("\t%f", positions[i/stride_length*n_particles* + * 3+j*3+k]); + * } + * printf("\n"); + * } + * } + * } + * else + * { + * printf("Cannot read positions\n"); + * } + * + * // Free memory + * if(positions) + * { + * free(positions); + * } + * tng_util_trajectory_close(&traj); + * + * return(0); + * } + * + * \endcode + * + * @subsection fortran_subsec Fortran + * + * The TNG library can be used from Fortran. It requires cray pointers, which + * are not part of the Fortran 77 standard, but available in most compilers. + * + * To compile the fortran example -DTNG_BUILD_FORTRAN=ON needs to be specified when + * running cmake. + * + */ + +#ifndef TNG_IO_H +#define TNG_IO_H 1 + +#include +#include +#include +#include +#include "tng_io_fwd.h" + +#ifdef USE_STD_INTTYPES_H +#include +#else +/* Visual Studio does not contain inttypes.h and stdint.h. Some defines and + * typedefs are used from the GNU C Library */ +#ifdef _MSC_VER + +typedef __int32 int32_t; +typedef unsigned __int32 uint32_t; +typedef __int64 int64_t; +typedef unsigned __int64 uint64_t; + +#else +#include +#endif /* _MSC_VER */ + +/* This is from inttypes.h (GNU C Library) */ +/* The ISO C99 standard specifies that these macros must only be + defined if explicitly requested. */ +#if !defined __cplusplus || defined __STDC_FORMAT_MACROS + +# if __WORDSIZE == 64 +# define __PRI64_PREFIX "l" +# define __PRIPTR_PREFIX "l" +# else +# define __PRI64_PREFIX "ll" +# define __PRIPTR_PREFIX +# endif + +/* From stdint.h (GNU C Library) */ +/* Macros for printing format specifiers. */ +/* Decimal notation. */ +#ifndef PRId64 +# define PRId64 __PRI64_PREFIX "d" +#endif + +#endif + +#endif /* USE_STD_INTTYPES_H */ + + +#ifndef USE_WINDOWS +#if defined(WIN32) || defined(_WIN32) || defined(WIN64) || defined(_WIN64) +#define USE_WINDOWS +#endif /* win32... */ +#endif /* not defined USE_WINDOWS */ + +#ifndef DECLSPECDLLEXPORT +#ifdef USE_WINDOWS +#define DECLSPECDLLEXPORT __declspec(dllexport) +#else /* USE_WINDOWS */ +#define DECLSPECDLLEXPORT +#endif /* USE_WINDOWS */ +#endif /* DECLSPECDLLEXPORT */ + +/** Flag to indicate frame dependent data. */ +#define TNG_FRAME_DEPENDENT 1 +/** Flag to indicate particle dependent data. */ +#define TNG_PARTICLE_DEPENDENT 2 + +/** The maximum length of a date string */ +#define TNG_MAX_DATE_STR_LEN 24 +/** The length of an MD5 hash */ +#define TNG_MD5_HASH_LEN 16 +/** The maximum allowed length of a string */ +#define TNG_MAX_STR_LEN 1024 + +#ifndef NDEBUG +#define TNG_ASSERT(cnd, msg) if(!(cnd)) {printf("%s\n", msg); assert(cnd);} +#else +#define TNG_ASSERT(cnd, msg) (void)0; +#endif + +/** Flag to specify the endianness of a TNG file */ +typedef enum {TNG_BIG_ENDIAN, + TNG_LITTLE_ENDIAN} tng_file_endianness; + +/** Flag to specify the endianness of 32 bit values of the current architecture. */ +typedef enum {TNG_BIG_ENDIAN_32, + TNG_LITTLE_ENDIAN_32, + TNG_BYTE_PAIR_SWAP_32} tng_endianness_32; + +/** Flag to specify the endianness of 64 bit values of the current architecture. */ +typedef enum {TNG_BIG_ENDIAN_64, + TNG_LITTLE_ENDIAN_64, + TNG_QUAD_SWAP_64, + TNG_BYTE_PAIR_SWAP_64, + TNG_BYTE_SWAP_64} tng_endianness_64; + +/** Compression mode is specified in each data block */ +typedef enum {TNG_UNCOMPRESSED, + TNG_XTC_COMPRESSION, + TNG_TNG_COMPRESSION, + TNG_GZIP_COMPRESSION} tng_compression; + +/** Hash types */ +typedef enum {TNG_NO_HASH, + TNG_MD5, + TNG_SHA256} tng_hash_type; + +/** Non trajectory blocks come before the first frame set block */ +typedef enum {TNG_NON_TRAJECTORY_BLOCK, TNG_TRAJECTORY_BLOCK} tng_block_type; + +/** @defgroup def1 Standard non-trajectory blocks + * Block IDs of standard non-trajectory blocks. + * @{ + */ +#define TNG_GENERAL_INFO 0x0000000000000000LL +#define TNG_MOLECULES 0x0000000000000001LL +#define TNG_TRAJECTORY_FRAME_SET 0x0000000000000002LL +#define TNG_PARTICLE_MAPPING 0x0000000000000003LL +/** @} */ + +/** @defgroup def2 Standard trajectory blocks + * Block IDs of standard trajectory blocks. Box shape and partial charges can + * be either trajectory blocks or non-trajectory blocks + * @{ + */ +#define TNG_TRAJ_BOX_SHAPE 0x0000000010000000LL +#define TNG_TRAJ_POSITIONS 0x0000000010000001LL +#define TNG_TRAJ_VELOCITIES 0x0000000010000002LL +#define TNG_TRAJ_FORCES 0x0000000010000003LL +#define TNG_TRAJ_PARTIAL_CHARGES 0x0000000010000004LL +#define TNG_TRAJ_FORMAL_CHARGES 0x0000000010000005LL +#define TNG_TRAJ_B_FACTORS 0x0000000010000006LL +#define TNG_TRAJ_ANISOTROPIC_B_FACTORS 0x0000000010000007LL +#define TNG_TRAJ_OCCUPANCY 0x0000000010000008LL +#define TNG_TRAJ_GENERAL_COMMENTS 0x0000000010000009LL +/** @} */ + + +/** @defgroup def3 GROMACS data block IDs + * Block IDs of data blocks specific to GROMACS. + * @{ + */ +#define TNG_GMX_LAMBDA 0x1000000010000000LL +#define TNG_GMX_ENERGY_ANGLE 0x1000000010000001LL +#define TNG_GMX_ENERGY_RYCKAERT_BELL 0x1000000010000002LL +#define TNG_GMX_ENERGY_LJ_14 0x1000000010000003LL +#define TNG_GMX_ENERGY_COULOMB_14 0x1000000010000004LL +#define TNG_GMX_ENERGY_LJ_(SR) 0x1000000010000005LL +#define TNG_GMX_ENERGY_COULOMB_(SR) 0x1000000010000006LL +#define TNG_GMX_ENERGY_COUL_RECIP 0x1000000010000007LL +#define TNG_GMX_ENERGY_POTENTIAL 0x1000000010000008LL +#define TNG_GMX_ENERGY_KINETIC_EN 0x1000000010000009LL +#define TNG_GMX_ENERGY_TOTAL_ENERGY 0x1000000010000010LL +#define TNG_GMX_ENERGY_TEMPERATURE 0x1000000010000011LL +#define TNG_GMX_ENERGY_PRESSURE 0x1000000010000012LL +#define TNG_GMX_ENERGY_CONSTR_RMSD 0x1000000010000013LL +#define TNG_GMX_ENERGY_BOX_X 0x1000000010000014LL +#define TNG_GMX_ENERGY_BOX_Y 0x1000000010000015LL +#define TNG_GMX_ENERGY_BOX_Z 0x1000000010000016LL +#define TNG_GMX_ENERGY_VOLUME 0x1000000010000017LL +#define TNG_GMX_ENERGY_DENSITY 0x1000000010000018LL +#define TNG_GMX_ENERGY_PV 0x1000000010000019LL +#define TNG_GMX_ENERGY_ENTHALPY 0x1000000010000020LL +#define TNG_GMX_ENERGY_VIR_XX 0x1000000010000021LL +#define TNG_GMX_ENERGY_VIR_XY 0x1000000010000022LL +#define TNG_GMX_ENERGY_VIR_XZ 0x1000000010000023LL +#define TNG_GMX_ENERGY_VIR_YX 0x1000000010000024LL +#define TNG_GMX_ENERGY_VIR_YY 0x1000000010000025LL +#define TNG_GMX_ENERGY_VIR_YZ 0x1000000010000026LL +#define TNG_GMX_ENERGY_VIR_ZX 0x1000000010000027LL +#define TNG_GMX_ENERGY_VIR_ZY 0x1000000010000028LL +#define TNG_GMX_ENERGY_VIR_ZZ 0x1000000010000029LL +#define TNG_GMX_ENERGY_PRES_XX 0x1000000010000030LL +#define TNG_GMX_ENERGY_PRES_XY 0x1000000010000031LL +#define TNG_GMX_ENERGY_PRES_XZ 0x1000000010000032LL +#define TNG_GMX_ENERGY_PRES_YX 0x1000000010000033LL +#define TNG_GMX_ENERGY_PRES_YY 0x1000000010000034LL +#define TNG_GMX_ENERGY_PRES_YZ 0x1000000010000035LL +#define TNG_GMX_ENERGY_PRES_ZX 0x1000000010000036LL +#define TNG_GMX_ENERGY_PRES_ZY 0x1000000010000037LL +#define TNG_GMX_ENERGY_PRES_ZZ 0x1000000010000038LL +#define TNG_GMX_ENERGY_SURFXSURFTEN 0x1000000010000039LL +#define TNG_GMX_ENERGY_T_SYSTEM 0x1000000010000040LL +#define TNG_GMX_ENERGY_LAMB_SYSTEM 0x1000000010000041LL +#define TNG_GMX_SELECTION_GROUP_NAMES 0x1000000010000042LL +#define TNG_GMX_ATOM_SELECTION_GROUP 0x1000000010000043LL +/** @} */ + +/** Flag to specify if a data block contains data related to particles or not.*/ +typedef enum {TNG_NON_PARTICLE_BLOCK_DATA, + TNG_PARTICLE_BLOCK_DATA} tng_particle_dependency; + + +typedef enum {TNG_FALSE, TNG_TRUE} tng_bool; + +/** Flag to specify if the number of atoms change throughout the trajectory or + * if it is constant. */ +typedef enum {TNG_CONSTANT_N_ATOMS, TNG_VARIABLE_N_ATOMS} + tng_variable_n_atoms_flag; + +/** Return values of API functions. TNG_SUCCESS means that the operation + * was successful. TNG_FAILURE means that the operation failed for some + * reason, but it is possible to try to continue anyhow. TNG_CRITICAL + * means that the error is irrecoverable. */ +typedef enum {TNG_SUCCESS, TNG_FAILURE, TNG_CRITICAL} tng_function_status; + +/** If tng_hash_mode == TNG_USE_HASH md5 hashes will be written to output files + * and when reading a file the md5 hashes of the contents will be compared to + * those in the file (for each block) in order to ensure data integrity */ +typedef enum {TNG_SKIP_HASH, TNG_USE_HASH} tng_hash_mode; + +/** Possible formats of data block contents */ +typedef enum {TNG_CHAR_DATA, + TNG_INT_DATA, + TNG_FLOAT_DATA, + TNG_DOUBLE_DATA} tng_data_type; + + +struct tng_trajectory; +struct tng_molecule; +struct tng_chain; +struct tng_residue; +struct tng_atom; +struct tng_bond; +struct tng_gen_block; +struct tng_particle_mapping; +struct tng_trajectory_frame_set; +struct tng_particle_data; +struct tng_non_particle_data; + +/** Data can be either double, float, int or a string */ +union data_values { + double d; + float f; + int64_t i; + char *c; +}; + + +#ifdef __cplusplus +extern "C" +{ +#endif + +/** @defgroup group1 Low-level API + * These functions give detailed control of the TNG data management. Most + * things can be done using the more convenient high-level API functions + * instead. + * @{ + */ + +/** + * @brief Get the major version of the TNG library. + * @param tng_data is a trajectory data container, it does not have + * to be initialized beforehand. + * @param version is pointing to a value set to the major version of + * the library. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_version_major + (const tng_trajectory_t tng_data, + int *version); + +/** + * @brief Get the minor version of the TNG library. + * @param tng_data is a trajectory data container, it does not have + * to be initialized beforehand. + * @param version is pointing to a value set to the minor version of + * the library. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_version_minor + (const tng_trajectory_t tng_data, + int *version); + +/** + * @brief Get the patch level of the TNG library. + * @param tng_data is a trajectory data container, it does not have + * to be initialized beforehand. + * @param patch_level is the string to fill with the full version, + * memory must be allocated before. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_version_patchlevel + (const tng_trajectory_t tng_data, + int *patch_level); + +/** + * @brief Get the full version string of the TNG library. + * @param tng_data is a trajectory data container, it does not have + * to be initialized beforehand. + * @param version is pointing to a value set to the major version of + * the library. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for version. This includes \0 terminating character. + * @pre \code version != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_version + (const tng_trajectory_t tng_data, + char *version, + const int max_len); + +/** + * @brief Setup a trajectory data container. + * @param tng_data_p a pointer to memory to initialise as a trajectory. + * @pre tng_data_p must not be pointing at a reserved memory block. + * @details Memory is allocated during initialisation. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_trajectory_init + (tng_trajectory_t *tng_data_p); + +/** + * @brief Clean up a trajectory data container. + * @param tng_data_p a pointer to the trajectory data to destroy. + * @details All allocated memory in the data structure is freed, as well as + * tng_data_p itself. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_trajectory_destroy + (tng_trajectory_t *tng_data_p); + +/** + * @brief Copy a trajectory data container (dest is setup as well). + * @details This initialises dest and copies only what is absolute necessary for + * parallel i/o. This can be used inside pragma omp for setting up a thread + * local copy of src. It can be freed (using tng_trajectory_destroy) at the + * end of the parallel block. + * @param src the original trajectory. + * @param dest_p a pointer to memory to initialise as a trajectory. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre tng_data_p must not be pointing at a reserved memory block. + * @details Memory is allocated during initialisation. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_trajectory_init_from_src + (tng_trajectory_t src, tng_trajectory_t *dest_p); + +/** + * @brief Get the name of the input file. + * @param tng_data the trajectory of which to get the input file name. + * @param file_name the string to fill with the name of the input file, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for file_name. This includes \0 terminating character. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code file_name != 0 \endcode The pointer to the file name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_input_file_get + (const tng_trajectory_t tng_data, + char *file_name, const int max_len); + +/** + * @brief Set the name of the input file. + * @param tng_data the trajectory of which to set the input file name. + * @param file_name the name of the input file. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code file_name != 0 \endcode The pointer to the file name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_input_file_set + (tng_trajectory_t tng_data, + const char *file_name); + +/** + * @brief Get the name of the output file. + * @param tng_data the trajectory of which to get the input file name. + * @param file_name the string to fill with the name of the output file, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for file_name. This includes \0 terminating character. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code file_name != 0 \endcode The pointer to the file name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_output_file_get + (const tng_trajectory_t tng_data, + char *file_name, const int max_len); + +/** + * @brief Set the name of the output file. + * @param tng_data the trajectory of which to set the output file name. + * @param file_name the name of the output file. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code file_name != 0 \endcode The pointer to the file name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_output_file_set + (tng_trajectory_t tng_data, + const char *file_name); + +/** + * @brief Set the name of the output file for appending. The output file + * will not be overwritten. + * @param tng_data the trajectory of which to set the output file name. + * @param file_name the name of the output file to append to. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code file_name != 0 \endcode The pointer to the file name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_output_append_file_set + (tng_trajectory_t tng_data, + const char *file_name); + +/** + * @brief Get the endianness of the output file. + * @param tng_data the trajectory of which to get the endianness of the current + * output file. + * @param endianness will contain the enumeration of the endianness. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code endianness != 0 \endcode The pointer to the endianness container + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness + * could not be retrieved. + */ +tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_get + (const tng_trajectory_t tng_data, tng_file_endianness *endianness); + +/** + * @brief Set the endianness of the output file. + * @param tng_data the trajectory of which to set the endianness of the current + * output file. + * @param endianness the enumeration of the endianness, can be either + * TNG_BIG_ENDIAN (0) or TNG_LITTLE_ENDIAN (1). + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @details The endianness cannot be changed after file output has started. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness + * could not be set. + */ +tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_set + (tng_trajectory_t tng_data, + const tng_file_endianness endianness); + +/** + * @brief Get the name of the program used when creating the trajectory. + * @param tng_data the trajectory of which to get the program name. + * @param name the string to fill with the name of the program, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_first_program_name_get + (const tng_trajectory_t tng_data, + char *name, const int max_len); + +/** + * @brief Set the name of the program used when creating the trajectory. + * @param tng_data the trajectory of which to set the program name. + * @param new_name is a string containing the wanted name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code new_name != 0 \endcode The pointer to the new_name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_first_program_name_set + (tng_trajectory_t tng_data, + const char *new_name); + +/** + * @brief Get the name of the program used when last modifying the trajectory. + * @param tng_data the trajectory of which to get the program name. + * @param name the string to fill with the name of the program, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_last_program_name_get + (const tng_trajectory_t tng_data, + char *name, const int max_len); + +/** + * @brief Set the name of the program used when last modifying the trajectory. + * @param tng_data the trajectory of which to set the program name. + * @param new_name is a string containing the wanted name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code new_name != 0 \endcode The pointer to the new_name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_last_program_name_set + (tng_trajectory_t tng_data, + const char *new_name); + +/** + * @brief Get the name of the user who created the trajectory. + * @param tng_data the trajectory of which to get the user name. + * @param name the string to fill with the name of the user, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_first_user_name_get + (const tng_trajectory_t tng_data, + char *name, const int max_len); + +/** + * @brief Set the name of the user who created the trajectory. + * @param tng_data the trajectory of which to set the user name. + * @param new_name is a string containing the wanted name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code new_name != 0 \endcode The pointer to the new_name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_first_user_name_set + (tng_trajectory_t tng_data, + const char *new_name); + +/** + * @brief Get the name of the user who last modified the trajectory. + * @param tng_data the trajectory of which to get the user name. + * @param name the string to fill with the name of the user, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_last_user_name_get + (const tng_trajectory_t tng_data, + char *name, const int max_len); + +/** + * @brief Set the name of the user who last modified the trajectory. + * @param tng_data the trajectory of which to set the user name. + * @param new_name is a string containing the wanted name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code new_name != 0 \endcode The pointer to the new_name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_last_user_name_set + (tng_trajectory_t tng_data, + const char *new_name); + +/** + * @brief Get the name of the computer used when creating the trajectory. + * @param tng_data the trajectory of which to get the computer name. + * @param name the string to fill with the name of the computer, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_get + (const tng_trajectory_t tng_data, + char *name, const int max_len); + +/** + * @brief Set the name of the computer used when creating the trajectory. + * @param tng_data the trajectory of which to set the computer name. + * @param new_name is a string containing the wanted name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code new_name != 0 \endcode The pointer to the new_name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_set + (tng_trajectory_t tng_data, + const char *new_name); + +/** + * @brief Get the name of the computer used when last modifying the trajectory. + * @param tng_data the trajectory of which to get the computer name. + * @param name the string to fill with the name of the computer, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_get + (const tng_trajectory_t tng_data, + char *name, const int max_len); + +/** + * @brief Set the name of the computer used when last modifying the trajectory. + * @param tng_data the trajectory of which to set the computer name. + * @param new_name is a string containing the wanted name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code new_name != 0 \endcode The pointer to the new_name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_set + (tng_trajectory_t tng_data, + const char *new_name); + +/** + * @brief Get the pgp_signature of the user creating the trajectory. + * @param tng_data the trajectory of which to get the computer name. + * @param signature the string to fill with the signature, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code signature != 0 \endcode The pointer to the signature + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_first_signature_get + (const tng_trajectory_t tng_data, + char *signature, const int max_len); + +/** + * @brief Set the pgp_signature of the user creating the trajectory. + * @param tng_data the trajectory of which to set the computer name. + * @param signature is a string containing the pgp_signature. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code signature != 0 \endcode The pointer to the signature + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_first_signature_set + (tng_trajectory_t tng_data, + const char *signature); + +/** + * @brief Get the pgp_signature of the user last modifying the trajectory. + * @param tng_data the trajectory of which to get the computer name. + * @param signature the string to fill with the signature, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code signature != 0 \endcode The pointer to the signature + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_last_signature_get + (const tng_trajectory_t tng_data, + char *signature, const int max_len); + +/** + * @brief Set the pgp_signature of the user last modifying the trajectory. + * @param tng_data the trajectory of which to set the computer name. + * @param signature is a string containing the pgp_signature. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code signature != 0 \endcode The pointer to the signature + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_last_signature_set + (tng_trajectory_t tng_data, + const char *signature); + +/** + * @brief Get the name of the forcefield used in the trajectory. + * @param tng_data the trajectory of which to get the forcefield name. + * @param name the string to fill with the name of the forcefield, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_get + (const tng_trajectory_t tng_data, + char *name, const int max_len); + +/** + * @brief Set the name of the forcefield used in the trajectory. + * @param tng_data the trajectory of which to set the forcefield name. + * @param new_name is a string containing the wanted name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code new_name != 0 \endcode The pointer to the new_name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_set + (tng_trajectory_t tng_data, + const char *new_name); + +/** + * @brief Get the medium stride length of the trajectory. + * @param tng_data is the trajectory from which to get the stride length. + * @param len is pointing to a value set to the stride length. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_get + (const tng_trajectory_t tng_data, + int64_t *len); + +/** + * @brief Set the medium stride length of the trajectory. + * @param tng_data is the trajectory of which to set the stride length. + * @param len is the wanted medium stride length. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred. + */ +tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_set + (tng_trajectory_t tng_data, + const int64_t len); + +/** + * @brief Get the long stride length of the trajectory. + * @param tng_data is the trajectory from which to get the stride length. + * @param len is pointing to a value set to the stride length. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_get + (const tng_trajectory_t tng_data, + int64_t *len); + +/** + * @brief Set the long stride length of the trajectory. + * @param tng_data is the trajectory of which to set the stride length. + * @param len is the wanted long stride length. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred. + */ +tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_set + (tng_trajectory_t tng_data, + const int64_t len); + +/** + * @brief Get the current time per frame of the trajectory. + * @param tng_data is the trajectory from which to get the time per frame. + * @param time is pointing to a value set to the time per frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code time != 0 \endcode The pointer to time must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_get + (const tng_trajectory_t tng_data, + double *time); + +/** + * @brief Set the time per frame of the trajectory. + * @param tng_data is the trajectory of which to set the time per frame. + * @param time is the new time per frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code time > 0 \endcode The time per frame must be >= 0. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred. + */ +tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_set + (tng_trajectory_t tng_data, + const double time); + +/** + * @brief Get the length of the input file. + * @param tng_data is the trajectory from which to get the input file length. + * @param len is pointing to a value set to the file length. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_input_file_len_get + (const tng_trajectory_t tng_data, + int64_t *len); + +/** + * @brief Get the number of frames in the trajectory + * @param tng_data is the trajectory of which to get the number of frames. + * @param n is pointing to a value set to the number of frames. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code tng_data->input_file != 0 \endcode An input file must be open + * to find the next frame set. + * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (could not find last frame set). + */ +tng_function_status DECLSPECDLLEXPORT tng_num_frames_get + (const tng_trajectory_t tng_data, + int64_t *n); + +/** + * @brief Get the precision of lossy compression. + * @param tng_data is the trajectory of which to get the compression precision. + * @param precision will be pointing to the retrieved compression precision. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @details A compression precision of 0.001 (the default) means that the + * compressed values are accurate to the third decimal. This function does + * not check actual precision of compressed data, but just returns what has + * previously been set using tng_compression_precision_set(). + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_compression_precision_get + (const tng_trajectory_t tng_data, + double *precision); + +/** + * @brief Set the precision of lossy compression. + * @param tng_data is the trajectory of which to set the compression precision. + * @param precision is the new compression precision. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @details A compression precision of 0.001 (the default) means that the + * compressed values are accurate to the third decimal. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_compression_precision_set + (tng_trajectory_t tng_data, + const double precision); + +/** + * @brief Set the number of particles, in the case no molecular system is used. + * @param tng_data is the trajectory of which to get the number of particles. + * @param n is the number of particles to use. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @details When creating a molecular system the number of particles are set + * automatically. This should only be used when there is no molecular system + * specified or if the number of atoms needs to be overridden for some reason. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_implicit_num_particles_set + (tng_trajectory_t tng_data, + const int64_t n); + +/** + * @brief Get the current number of particles. + * @param tng_data is the trajectory from which to get the number of particles. + * @param n is pointing to a value set to the number of particles. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. + * @details If variable number of particles are used this function will return + * the number of particles in the current frame set. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_num_particles_get + (const tng_trajectory_t tng_data, + int64_t *n); + +/** + * @brief Get if the number of particle can be varied during the simulation. + * @param tng_data is the trajectory from which to get the number of particles. + * @param variable is pointing to a value set to TNG_CONSTANT_N_ATOMS if the + * number of particles cannot change or TNG_VARIABLE_N_ATOMS if the number of + * particles can change. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code variable != 0 \endcode The pointer to variable must not be + * a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_num_particles_variable_get + (const tng_trajectory_t tng_data, + char *variable); + +/** + * @brief Get the number of molecule types (length of tng_data->molecules). + * @param tng_data is the trajectory from which to get the number of molecules. + * @param n is pointing to a value set to the number of molecule types. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_num_molecule_types_get + (const tng_trajectory_t tng_data, + int64_t *n); + +/** + * @brief Get the current total number of molecules. + * @param tng_data is the trajectory from which to get the number of molecules. + * @param n is pointing to a value set to the number of molecules. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. + * @details If variable number of particles are used this function will return + * the total number of molecules in the current frame set. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_num_molecules_get + (const tng_trajectory_t tng_data, + int64_t *n); + +/** @brief Get the list of the count of each molecule. + * @param tng_data is the trajectory from which to get the molecule count list. + * @param mol_cnt_list is a list of the count of each molecule in the + * mol system. This is a pointer to the list in the TNG container, which + * means that it should be handled carefully, e.g. not freed. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE(1) if the list of + * molecule counts was not valid. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_list_get + (const tng_trajectory_t tng_data, + int64_t **mol_cnt_list); + +/** + * @brief Get the exponent used for distances in the trajectory. + * @param tng_data is the trajectory from which to get the information. + * @param exp is pointing to a value set to the distance unit exponent. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code exp != 0 \endcode The pointer to exp must not be a NULL pointer. + * @details Example: If the distances are specified in nm (default) exp is -9. + * If the distances are specified in Å exp is -10. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_get + (const tng_trajectory_t tng_data, + int64_t *exp); + +/** + * @brief Set the exponent used for distances in the trajectory. + * @param tng_data is the trajectory of which to set the unit exponent. + * @param exp is the distance unit exponent to use. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @details Example: If the distances are specified in nm (default) exp is -9. + * If the distances are specified in Å exp is -10. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_set + (const tng_trajectory_t tng_data, + const int64_t exp); + +/** + * @brief Get the number of frames per frame set. + * @param tng_data is the trajectory from which to get the number of frames + * per frame set. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. + * @param n is pointing to a value set to the number of frames per frame set. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_get + (const tng_trajectory_t tng_data, + int64_t *n); + +/** + * @brief Set the number of frames per frame set. + * @param tng_data is the trajectory of which to set the number of frames + * per frame set. + * @param n is the number of frames per frame set. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @details This does not affect already existing frame sets. For + * consistency the number of frames per frame set should be set + * betfore creating any frame sets. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_set + (const tng_trajectory_t tng_data, + const int64_t n); + +/** + * @brief Get the number of frame sets. + * @details This updates tng_data->n_trajectory_frame_sets before returning it. + * @param tng_data is the trajectory from which to get the number of frame sets. + * @param n is pointing to a value set to the number of frame sets. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_num_frame_sets_get + (const tng_trajectory_t tng_data, + int64_t *n); + +/** + * @brief Get the current trajectory frame set. + * @param tng_data is the trajectory from which to get the frame set. + * @param frame_set_p will be set to point at the memory position of + * the found frame set. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_current_frame_set_get + (const tng_trajectory_t tng_data, + tng_trajectory_frame_set_t *frame_set_p); + +/** + * @brief Find the requested frame set number. + * @param tng_data is the trajectory from which to get the frame set. + * @param nr is the frame set number to search for. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code nr >= 0 \endcode The frame set number (nr) must be >= 0. + * @details tng_data->current_trajectory_frame_set will contain the + * found trajectory if successful. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_nr_find + (tng_trajectory_t tng_data, + const int64_t nr); + +/** + * @brief Find the frame set containing a specific frame. + * @param tng_data is the trajectory from which to get the frame set. + * @param frame is the frame number to search for. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame >= 0 \endcode The frame number must be >= 0. + * @details tng_data->current_trajectory_frame_set will contain the + * found trajectory if successful. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_of_frame_find + (tng_trajectory_t tng_data, + const int64_t frame); + +/** + * @brief Get the file position of the next frame set in the input file. + * @param tng_data is a trajectory data container. + * @param frame_set is the frame set of which to get the position of the + * following frame set. + * @param pos is pointing to a value set to the file position. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_next_frame_set_file_pos_get + (const tng_trajectory_t tng_data, + const tng_trajectory_frame_set_t frame_set, + int64_t *pos); + +/** + * @brief Get the file position of the previous frame set in the input file. + * @param tng_data is a trajectory data container. + * @param frame_set is the frame set of which to get the position of the + * previous frame set. + * @param pos is pointing to a value set to the file position. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_prev_frame_set_file_pos_get + (const tng_trajectory_t tng_data, + const tng_trajectory_frame_set_t frame_set, + int64_t *pos); + +/** + * @brief Get the first and last frames of the frame set. + * @param tng_data is a trajectory data container. + * @param frame_set is the frame set of which to get the frame range. + * @param first_frame is set to the first frame of the frame set. + * @param last_frame is set to the last frame of the frame set. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code first_frame != 0 \endcode The pointer to first_frame must + * not be a NULL pointer. + * @pre \code last_frame != 0 \endcode The pointer to last_frame must + * not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_frame_range_get + (const tng_trajectory_t tng_data, + const tng_trajectory_frame_set_t frame_set, + int64_t *first_frame, + int64_t *last_frame); + +/** + * @brief Allocate memory for and setup a molecule container. + * @param tng_data is a trajectory data container. + * @param molecule_p is a pointer to molecule to allocate and initialise. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_alloc(const tng_trajectory_t tng_data, + tng_molecule_t *molecule_p); + +/** + * @brief Clean up a molecule container and free its allocated memory. + * @param tng_data is a trajectory data container. + * @param molecule_p is the molecule to destroy. + * @details All allocated memory in the data structure is freed and also the memory + * of the molecule itself. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_free(const tng_trajectory_t tng_data, + tng_molecule_t *molecule_p); + +/** + * @brief Setup a molecule container. + * @param tng_data is a trajectory data container. + * @param molecule is the molecule to initialise. Memory must be preallocated. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_init + (const tng_trajectory_t tng_data, + tng_molecule_t molecule); + +/** + * @brief Clean up a molecule container. + * @param tng_data is a trajectory data container. + * @param molecule is the molecule to destroy. + * @details All allocated memory in the data structure is freed, but not the + * memory of molecule itself. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_destroy + (const tng_trajectory_t tng_data, + tng_molecule_t molecule); + +/** + * @brief Add a molecule to the trajectory. + * @param tng_data is the trajectory data container containing the block.. + * @param name is a pointer to the string containing the name of the new molecule. + * @param molecule is a pointer to the newly created molecule. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could + * not be set properly or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_add + (tng_trajectory_t tng_data, + const char *name, + tng_molecule_t *molecule); + +/** + * @brief Add a molecule with a specific ID to the trajectory. + * @param tng_data is the trajectory data container containing the block.. + * @param name is a pointer to the string containing the name of the new molecule. + * @param id is the ID of the created molecule. + * @param molecule is a pointer to the newly created molecule. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could + * not be set properly or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_w_id_add + (tng_trajectory_t tng_data, + const char *name, + const int64_t id, + tng_molecule_t *molecule); + +/** + * @brief Add an existing molecule (from a molecule container) to the trajectory. + * @param tng_data is the trajectory data container containing the block.. + * @param molecule is a pointer to the molecule to add to the trajectory and will + * afterwards point to the molecule in the trajectory. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_existing_add + (tng_trajectory_t tng_data, + tng_molecule_t *molecule); + +/** + * @brief Get the name of a molecule. + * @param tng_data the trajectory containing the molecule. + * @param molecule the molecule of which to get the name. + * @param name the string to fill with the name of the molecule, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @pre \code molecule != 0 \endcode The molecule must not be NULL. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_name_get + (const tng_trajectory_t tng_data, + const tng_molecule_t molecule, + char *name, + const int max_len); + +/** + * @brief Set the name of a molecule. + * @param tng_data is the trajectory data container containing the molecule.. + * @param molecule is the molecule to rename. + * @param new_name is a string containing the wanted name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code new_name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_name_set + (tng_trajectory_t tng_data, + tng_molecule_t molecule, + const char *new_name); + +/** + * @brief Get the count of a molecule. + * @param tng_data is the trajectory data container containing the molecule.. + * @param molecule is the molecule of which to get the count. + * @param cnt is a pointer to the variable to be populated with the count. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code cnt != 0 \endcode The pointer to the molecule count + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_get + (const tng_trajectory_t tng_data, + const tng_molecule_t molecule, + int64_t *cnt); + +/** + * @brief Set the count of a molecule. + * @param tng_data is the trajectory data container containing the molecule.. + * @param molecule is the molecule of which to set the count. + * @param cnt is the number of instances of this molecule. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_set + (tng_trajectory_t tng_data, + tng_molecule_t molecule, + const int64_t cnt); + +/** + * @brief Find a molecule. + * @param tng_data is the trajectory data container containing the molecule. + * @param name is a string containing the name of the molecule. If name is empty + * only id will be used for finding the molecule. + * @param id is the id of the molecule to look for. If id is -1 only the name of + * the molecule will be used for finding the molecule. + * @param molecule is a pointer to the molecule if it was found - otherwise 0. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the + * molecule is not found. + * @details If name is an empty string and id == -1 the first residue will + * be found. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_find + (tng_trajectory_t tng_data, + const char *name, + int64_t id, + tng_molecule_t *molecule); + +/** + * @brief Retrieve the molecule with specified index in the list of molecules. + * @param tng_data is the trajectory data container containing the molecule. + * @param index is the index (in tng_data->molecules) of the molecule to return + * @param molecule is a pointer to the molecule if it was found - otherwise 0. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. + * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the + * molecule is not found. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_of_index_get + (tng_trajectory_t tng_data, + int64_t index, + tng_molecule_t *molecule); + +/** + * @brief Copy all molecules and the molecule counts from one TNG trajectory + * to another. + * @param tng_data_src is the source trajectory containing the molecular + * system to copy. + * @param tng_data_dest is the destination trajectory. + * @pre \code tng_data_src != 0 \endcode The trajectory container (tng_data_src) + * must be initialised before using it. + * @pre \code tng_data_dest != 0 \endcode The trajectory container (tng_data_dest) + * must be initialised before using it. + * @details The molecular system in tng_data_dest will be overwritten. + * @return TNG_SUCCESS(0) if the copying is successful, TNG_FAILURE if a minor + * error has occured or TNG_CRITICAL(2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_system_copy(tng_trajectory_t tng_data_src, + tng_trajectory_t tng_data_dest); + +/** + * @brief Get the number of chains in a molecule. + * @param tng_data is the trajectory containing the molecule. + * @param molecule is the molecule of which to get the number of chains. + * @param n is pointing to a value set to the number of chains. + * @pre \code molecule != 0 \endcode The molecule must not be NULL. + * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_num_chains_get + (const tng_trajectory_t tng_data, + const tng_molecule_t molecule, + int64_t *n); + +/** + * @brief Retrieve the chain of a molecule with specified index in the list + * of chains. + * @param tng_data is the trajectory data container containing the molecule. + * @param index is the index (in molecule->chains) of the chain to return + * @param molecule is the molecule from which to get the chain. + * @param chain is a pointer to the chain if it was found - otherwise 0. + * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. + * @pre \code chain != 0 \endcode chain must not be a NULL pointer. + * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the + * chain is not found. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_of_index_get + (tng_trajectory_t tng_data, + tng_molecule_t molecule, + int64_t index, + tng_chain_t *chain); + +/** + * @brief Get the number of residues in a molecule. + * @param tng_data is the trajectory containing the molecule. + * @param molecule is the molecule of which to get the number residues. + * @param n is pointing to a value set to the number of residues. + * @pre \code molecule != 0 \endcode The molecule must not be NULL. + * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_num_residues_get + (const tng_trajectory_t tng_data, + const tng_molecule_t molecule, + int64_t *n); + +/** + * @brief Retrieve the residue of a molecule with specified index in the list + * of chains. + * @param tng_data is the trajectory data container containing the molecule. + * @param index is the index (in molecule->residues) of the residue to return + * @param molecule is the molecule from which to get the residue. + * @param residue is a pointer to the residue if it was found - otherwise 0. + * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. + * @pre \code residue != 0 \endcode residue must not be a NULL pointer. + * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the + * residue is not found. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_residue_of_index_get + (const tng_trajectory_t tng_data, + const tng_molecule_t molecule, + const int64_t index, + tng_residue_t *residue); + +/** + * @brief Get the number of atoms in a molecule. + * @param tng_data is the trajectory containing the molecule. + * @param molecule is the molecule of which to get the number of atoms. + * @param n is pointing to a value set to the number of atoms. + * @pre \code molecule != 0 \endcode The molecule must not be NULL. + * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_num_atoms_get + (const tng_trajectory_t tng_data, + const tng_molecule_t molecule, + int64_t *n); + +/** + * @brief Retrieve the atom of a molecule with specified index in the list + * of atoms. + * @param tng_data is the trajectory data container containing the molecule. + * @param index is the index (in molecule->atoms) of the atom to return + * @param molecule is the molecule from which to get the atom. + * @param atom is a pointer to the atom if it was found - otherwise 0. + * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. + * @pre \code atom != 0 \endcode atom must not be a NULL pointer. + * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the + * atom is not found. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_of_index_get + (const tng_trajectory_t tng_data, + const tng_molecule_t molecule, + const int64_t index, + tng_atom_t *atom); + +/** + * @brief Find a chain in a molecule. + * @param tng_data is the trajectory data container containing the molecule. + * @param molecule is the molecule in which to search for the chain. + * @param name is a string containing the name of the chain. If name is empty + * only id will be used for finding the chain. + * @param id is the id of the chain to look for. If id is -1 only the name of + * the chain will be used for finding the chain. + * @param chain is a pointer to the chain if it was found - otherwise 0. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the + * chain is not found. + * @details If name is an empty string and id == -1 the first residue will + * be found. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_find + (tng_trajectory_t tng_data, + tng_molecule_t molecule, + const char *name, + int64_t id, + tng_chain_t *chain); + +/** + * @brief Add a chain to a molecule. + * @param tng_data is the trajectory data container containing the molecule.. + * @param molecule is the molecule to add a chain to. + * @param name is a string containing the name of the chain. + * @param chain is a pointer to the newly created chain. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could + * not be set properly or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_add + (tng_trajectory_t tng_data, + tng_molecule_t molecule, + const char *name, + tng_chain_t *chain); + +/** + * @brief Add a chain with a specific id to a molecule. + * @param tng_data is the trajectory data container containing the molecule.. + * @param molecule is the molecule to add a chain to. + * @param name is a string containing the name of the chain. + * @param id is the ID of the created chain. + * @param chain is a pointer to the newly created chain. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could + * not be set properly or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_w_id_add + (tng_trajectory_t tng_data, + tng_molecule_t molecule, + const char *name, + const int64_t id, + tng_chain_t *chain); + +/** + * @brief Add a bond between two atoms to a molecule. + * @param tng_data is the trajectory data container containing the molecule. + * @param molecule is the molecule containing the atoms to connect. + * @param from_atom_id is the id of one of the two atoms in the bond. + * @param to_atom_id is the id of the other atom in the bond. + * @param bond is a pointer to the newly created bond. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (!) if a minor error + * has occured or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_bond_add + (const tng_trajectory_t tng_data, + tng_molecule_t molecule, + const int64_t from_atom_id, + const int64_t to_atom_id, + tng_bond_t *bond); + +/** + * @brief Find an atom in a molecule. + * @param tng_data is the trajectory data container containing the molecule. + * @param molecule is the molecule in which to search for the atom. + * @param name is a string containing the name of the atom. If name is an + * empty string only id will be used for searching. + * @param id is the id of the atom to find. If id == -1 the first atom + * that matches the specified name will be found. + * @param atom is a pointer to the atom if it was found - otherwise 0. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the + * atom is not found. + * @details If name is an empty string and id == -1 the first residue will + * be found. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_find + (tng_trajectory_t tng_data, + tng_molecule_t molecule, + const char *name, + int64_t id, + tng_atom_t *atom); + +/** + * @brief Get the name of a chain. + * @param tng_data the trajectory containing the chain. + * @param chain the chain of which to get the name. + * @param name the string to fill with the name of the chain, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @pre \code chain != 0 \endcode The chain must not be NULL. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_chain_name_get + (const tng_trajectory_t tng_data, + const tng_chain_t chain, + char *name, + const int max_len); + +/** + * @brief Set the name of a chain. + * @param tng_data is the trajectory data container containing the atom.. + * @param chain is the chain to rename. + * @param new_name is a string containing the wanted name. + * @pre \code new_name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_chain_name_set + (tng_trajectory_t tng_data, + tng_chain_t chain, + const char *new_name); + +/** + * @brief Get the number of residues in a molecule chain. + * @param tng_data is the trajectory containing the chain. + * @param chain is the chain of which to get the number of residues. + * @param n is pointing to a value set to the number of residues. + * @pre \code chain != 0 \endcode The chain must not be NULL. + * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_chain_num_residues_get + (const tng_trajectory_t tng_data, + const tng_chain_t chain, + int64_t *n); + +/** + * @brief Retrieve the residue of a chain with specified index in the list + * of residues. + * @param tng_data is the trajectory data container containing the chain. + * @param index is the index (in chain->residues) of the residue to return + * @param chain is the chain from which to get the residue. + * @param residue is a pointer to the residue if it was found - otherwise 0. + * @pre \code chain != 0 \endcode chain must not be a NULL pointer. + * @pre \code residue != 0 \endcode residue must not be a NULL pointer. + * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the + * residue is not found. + */ +tng_function_status DECLSPECDLLEXPORT tng_chain_residue_of_index_get + (const tng_trajectory_t tng_data, + const tng_chain_t chain, + const int64_t index, + tng_residue_t *residue); + +/** + * @brief Find a residue in a chain. + * @param tng_data is the trajectory data container containing the chain. + * @param chain is the chain in which to search for the residue. + * @param name is a string containing the name of the residue. If name is an + * empty string only id will be used for searching. + * @param id is the id of the residue to find. If id == -1 the first residue + * that matches the specified name will be found. + * @param residue is a pointer to the residue if it was found - otherwise 0. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the + * residue is not found. + * @details If name is an empty string and id == -1 the first residue will + * be found. + */ +tng_function_status DECLSPECDLLEXPORT tng_chain_residue_find + (tng_trajectory_t tng_data, + tng_chain_t chain, + const char *name, + int64_t id, + tng_residue_t *residue); + +/** + * @brief Add a residue to a chain. + * @param tng_data is the trajectory data container containing the chain.. + * @param chain is the chain to add a residue to. + * @param name is a string containing the name of the residue. + * @param residue is a pointer to the newly created residue. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could + * not be set properly or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_chain_residue_add + (tng_trajectory_t tng_data, + tng_chain_t chain, + const char *name, + tng_residue_t *residue); + +/** + * @brief Add a residue with a specific ID to a chain. + * @param tng_data is the trajectory data container containing the chain.. + * @param chain is the chain to add a residue to. + * @param name is a string containing the name of the residue. + * @param id is the ID of the created residue. + * @param residue is a pointer to the newly created residue. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could + * not be set properly or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_chain_residue_w_id_add + (tng_trajectory_t tng_data, + tng_chain_t chain, + const char *name, + const int64_t id, + tng_residue_t *residue); + +/** + * @brief Get the name of a residue. + * @param tng_data the trajectory containing the residue. + * @param residue the residue of which to get the name. + * @param name the string to fill with the name of the residue, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @pre \code residue != 0 \endcode The residue must not be NULL. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_residue_name_get + (const tng_trajectory_t tng_data, + const tng_residue_t residue, + char *name, + const int max_len); + +/** + * @brief Set the name of a residue. + * @param tng_data is the trajectory data container containing the residue. + * @param residue is the residue to rename. + * @param new_name is a string containing the wanted name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code new_name != 0 \endcode The new name to set (new_name) must + * not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_residue_name_set + (tng_trajectory_t tng_data, + tng_residue_t residue, + const char *new_name); + +/** + * @brief Get the number of atoms in a residue. + * @param tng_data is the trajectory containing the residue. + * @param residue is the residue of which to get the number atoms. + * @param n is pointing to a value set to the number of atoms. + * @pre \code residue != 0 \endcode The residue must not be NULL. + * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_residue_num_atoms_get + (const tng_trajectory_t tng_data, + const tng_residue_t residue, + int64_t *n); + +/** + * @brief Retrieve the atom of a residue with specified index in the list + * of atoms. + * @param tng_data is the trajectory data container containing the residue. + * @param index is the index (in residue->atoms) of the atom to return + * @param residue is the residue from which to get the atom. + * @param atom is a pointer to the atom if it was found - otherwise 0. + * @pre \code residue != 0 \endcode residue must not be a NULL pointer. + * @pre \code atom != 0 \endcode atom must not be a NULL pointer. + * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the + * atom is not found. + */ +tng_function_status DECLSPECDLLEXPORT tng_residue_atom_of_index_get + (const tng_trajectory_t tng_data, + const tng_residue_t residue, + const int64_t index, + tng_atom_t *atom); + +/** + * @brief Add an atom to a residue. + * @param tng_data is the trajectory containing the residue. + * @param residue is the residue to add an atom to. + * @param atom_name is a string containing the name of the atom. + * @param atom_type is a string containing the atom type of the atom. + * @param atom is a pointer to the newly created atom. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code atom_name != 0 \endcode The pointer to the atom name string + * must not be a NULL pointer. + * @pre \code atom_type != 0 \endcode The pointer to the atom_type string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could + * not be set properly or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_residue_atom_add + (tng_trajectory_t tng_data, + tng_residue_t residue, + const char *atom_name, + const char *atom_type, + tng_atom_t *atom); + +/** + * @brief Add an atom with a specific ID to a residue. + * @param tng_data is the trajectory containing the residue. + * @param residue is the residue to add an atom to. + * @param atom_name is a string containing the name of the atom. + * @param atom_type is a string containing the atom type of the atom. + * @param id is the ID of the created atom. + * @param atom is a pointer to the newly created atom. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code atom_name != 0 \endcode The pointer to the atom name string + * must not be a NULL pointer. + * @pre \code atom_type != 0 \endcode The pointer to the atom_type string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could + * not be set properly or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_residue_atom_w_id_add + (tng_trajectory_t tng_data, + tng_residue_t residue, + const char *atom_name, + const char *atom_type, + const int64_t id, + tng_atom_t *atom); + +/** + * @brief Get the residue of an atom. + * @param tng_data the trajectory containing the atom. + * @param atom the atom of which to get the name. + * @param residue is set to the residue of the atom. + * @pre \code atom != 0 \endcode The atom must not be NULL. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status tng_atom_residue_get(const tng_trajectory_t tng_data, + const tng_atom_t atom, + tng_residue_t *residue); + +/** + * @brief Get the name of an atom. + * @param tng_data the trajectory containing the atom. + * @param atom the atom of which to get the name. + * @param name the string to fill with the name of the atom, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @pre \code atom != 0 \endcode The atom must not be NULL. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_atom_name_get + (const tng_trajectory_t tng_data, + const tng_atom_t atom, + char *name, + const int max_len); + +/** + * @brief Set the name of an atom. + * @param tng_data is the trajectory data container containing the atom. + * @param atom is the atom to rename. + * @param new_name is a string containing the wanted name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code new_name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_atom_name_set + (tng_trajectory_t tng_data, + tng_atom_t atom, + const char *new_name); + +/** + * @brief Get the type of an atom. + * @param tng_data the trajectory containing the atom. + * @param atom the atom of which to get the type. + * @param type the string to fill with the type of the atom, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for type. This includes \0 terminating character. + * @pre \code atom != 0 \endcode The atom must not be NULL. + * @pre \code type != 0 \endcode The pointer to the type string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ +tng_function_status DECLSPECDLLEXPORT tng_atom_type_get + (const tng_trajectory_t tng_data, + const tng_atom_t atom, + char *type, + const int max_len); + +/** + * @brief Set the atom type of an atom. + * @param tng_data is the trajectory data container containing the atom. + * @param atom is the atom to change. + * @param new_type is a string containing the atom type. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code new_type != 0 \endcode The pointer to the atom type string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_atom_type_set + (tng_trajectory_t tng_data, + tng_atom_t atom, + const char *new_type); + +/** + * @brief Get the molecule name of real particle number (number in mol system). + * @param tng_data is the trajectory data container containing the atom. + * @param nr is the real number of the particle in the molecular system. + * @param name is a string, which is set to the name of the molecule. Memory + * must be reserved beforehand. + * @param max_len is the maximum length of name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_name_of_particle_nr_get + (const tng_trajectory_t tng_data, + const int64_t nr, + char *name, + int max_len); + +/** + * @brief Get the molecule id of real particle number (number in mol system). + * @param tng_data is the trajectory data container containing the atom. + * @param nr is the real number of the particle in the molecular system. + * @param id is will be set to the id of the molecule. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molecule_id_of_particle_nr_get + (const tng_trajectory_t tng_data, + const int64_t nr, + int64_t *id); + +/** + * @brief Get the bonds of the current molecular system. + * @param tng_data is the trajectory data container containing the molecular + * system. + * @param n_bonds is set to the number of bonds in the molecular system and + * thereby also the lengths of the two lists: from_atoms and to_atoms. + * @param from_atoms is a list (memory reserved by this function) of atoms + * (number of atom in mol system) in bonds. + * @param to_atoms is a list (memory reserved by this function) of atoms + * (number of atom in mol system) in bonds. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n_bonds != 0 \endcode The pointer to n_bonds must not be a + * NULL pointer. + * @pre \code from_atoms != 0 \endcode The pointer to from_atoms must not + * be a NULL pointer. + * @pre \code to_atoms != 0 \endcode The pointer to to_atoms must not + * be a NULL pointer. + * @details The two lists of atoms use the same index, i.e. from_atoms[0] + * and to_atoms[0] are linked with a bond. Since memory is reserved in + * this function it must be freed afterwards. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_molsystem_bonds_get + (const tng_trajectory_t tng_data, + int64_t *n_bonds, + int64_t **from_atoms, + int64_t **to_atoms); + +/** + * @brief Get the chain name of real particle number (number in mol system). + * @param tng_data is the trajectory data container containing the atom. + * @param nr is the real number of the particle in the molecular system. + * @param name is a string, which is set to the name of the chain. Memory + * must be reserved beforehand. + * @param max_len is the maximum length of name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_chain_name_of_particle_nr_get + (const tng_trajectory_t tng_data, + const int64_t nr, + char *name, + int max_len); + +/** + * @brief Get the residue name of real particle number (number in mol system). + * @param tng_data is the trajectory data container containing the atom. + * @param nr is the real number of the particle in the molecular system. + * @param name is a string, which is set to the name of the residue. Memory + * must be reserved beforehand. + * @param max_len is the maximum length of name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_residue_name_of_particle_nr_get + (const tng_trajectory_t tng_data, + const int64_t nr, + char *name, + int max_len); + +/** + * @brief Get the residue id (local to molecule) of real particle number + * (number in mol system). + * @param tng_data is the trajectory data container containing the atom. + * @param nr is the real number of the particle in the molecular system. + * @param id is a pointer to the variable, which will be set to the ID. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_residue_id_of_particle_nr_get + (const tng_trajectory_t tng_data, + const int64_t nr, + int64_t *id); + +/** + * @brief Get the residue id (based on other molecules and molecule counts) + * of real particle number (number in mol system). + * @param tng_data is the trajectory data container containing the atom. + * @param nr is the real number of the particle in the molecular system. + * @param id is a pointer to the variable, which will be set to the ID. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_global_residue_id_of_particle_nr_get + (const tng_trajectory_t tng_data, + const int64_t nr, + int64_t *id); + +/** + * @brief Get the atom name of real particle number (number in mol system). + * @param tng_data is the trajectory data container containing the atom. + * @param nr is the real number of the particle in the molecular system. + * @param name is a string, which is set to the name of the atom. Memory + * must be reserved beforehand. + * @param max_len is the maximum length of name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_atom_name_of_particle_nr_get + (const tng_trajectory_t tng_data, + const int64_t nr, + char *name, + int max_len); + +/** + * @brief Get the atom type of real particle number (number in mol system). + * @param tng_data is the trajectory data container containing the atom. + * @param nr is the real number of the particle in the molecular system. + * @param type is a string, which is set to the type of the atom. Memory + * must be reserved beforehand. + * @param max_len is the maximum length of type. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code type != 0 \endcode The pointer to the type string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_atom_type_of_particle_nr_get + (const tng_trajectory_t tng_data, + const int64_t nr, + char *type, + int max_len); + +/** + * @brief Add a particle mapping table. + * @details Each particle mapping table will be written as a separate block, + * followed by the data blocks for the corresponding particles. In most cases + * there is one particle mapping block for each thread writing the trajectory. + * @param tng_data is the trajectory, with the frame set to which to add + * the mapping block. + * @details The mapping information is added to the currently active frame set + * of tng_data + * @param num_first_particle is the first particle number of this mapping + * block. + * @param n_particles is the number of particles in this mapping block. + * @param mapping_table is a list of the real particle numbers (i.e. the numbers + * used in the molecular system). The list is n_particles long. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @details mapping_table[0] is the real particle number of the first particle + * in the following data blocks. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_particle_mapping_add + (tng_trajectory_t tng_data, + const int64_t num_first_particle, + const int64_t n_particles, + const int64_t *mapping_table); + +/** + * @brief Remove all particle mappings (in memory) from the current frame set. + * @details Clears the currently setup particle mappings of the current frame + * set. + * @param tng_data is the trajectory, with the frame set of which to clear + * all particle mappings. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_particle_mapping_free + (tng_trajectory_t tng_data); + +/** + * @brief Read the header blocks from the input_file of tng_data. + * @details The trajectory blocks must be read separately and iteratively in chunks + * to fit in memory. + * @param tng_data is a trajectory data container. + * @details tng_data->input_file_path specifies + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_file_headers_read + (tng_trajectory_t tng_data, + const char hash_mode); + +/** + * @brief Write the header blocks to the output_file of tng_data. + * @details The trajectory blocks must be written separately and iteratively in chunks + * to fit in memory. + * @param tng_data is a trajectory data container. + * @details tng_data->output_file_path + * specifies which file to write to. If the file (output_file) is not open it + * will be opened. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_file_headers_write + (tng_trajectory_t tng_data, + const char hash_mode); + +/** + * @brief Read one (the next) block (of any kind) from the input_file of tng_data. + * @param tng_data is a trajectory data container. + * @details tng_data->input_file_path specifies + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param block_data is a pointer to the struct which will be populated with the + * data. + * @details If block_data->input_file_pos > 0 it is the position from where the + * reading starts otherwise it starts from the current position. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code block != 0 \endcode The block container (block) must be + * initialised before using it. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_block_read_next + (tng_trajectory_t tng_data, + tng_gen_block_t block_data, + const char hash_mode); + +/** + * @brief Read one frame set, including all particle mapping blocks and data + * blocks, starting from the current file position. + * @param tng_data is a trajectory data container. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_read + (tng_trajectory_t tng_data, + const char hash_mode); + +/** + * @brief Read data from the current frame set from the input_file. Only read + * particle mapping and data blocks matching the specified block_id. + * @param tng_data is a trajectory data container. + * @details tng_data->input_file_path specifies + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @param block_id is the ID of the data block to read from file. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_current_only_data_from_block_id + (tng_trajectory_t tng_data, + const char hash_mode, + const int64_t block_id); + +/** + * @brief Read one (the next) frame set, including particle mapping and related data blocks + * from the input_file of tng_data. + * @param tng_data is a trajectory data container. + * @details tng_data->input_file_path specifies + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next + (tng_trajectory_t tng_data, + const char hash_mode); + +/** + * @brief Read one (the next) frame set, including particle mapping and data blocks with a + * specific block id from the input_file of tng_data. + * @param tng_data is a trajectory data container. + * @details tng_data->input_file_path specifies + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @param block_id is the ID number of the blocks that should be read from file. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next_only_data_from_block_id + (tng_trajectory_t tng_data, + const char hash_mode, + const int64_t block_id); + +/** + * @brief Write one frame set, including mapping and related data blocks + * to the output_file of tng_data. + * @param tng_data is a trajectory data container. + * @details tng_data->output_file_path specifies + * which file to write to. If the file (output_file) is not open it will be + * opened. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_write + (tng_trajectory_t tng_data, + const char hash_mode); + +/** + * @brief Write one frame set even if it does not have as many frames as + * expected. The function also writes mapping and related data blocks + * to the output_file of tng_data. + * @param tng_data is a trajectory data container. + * @details tng_data->output_file_path specifies + * which file to write to. If the file (output_file) is not open it will be + * opened. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @details The number of frames in the frame set is set to the number of + * frames of the data blocks before writing it to disk. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_premature_write + (tng_trajectory_t tng_data, + const char hash_mode); + +/** + * @brief Create and initialise a frame set. + * @details Particle mappings are retained from previous frame set (if any). + * To explicitly clear particle mappings use tng_frame_set_particle_mapping_free(). + * @param tng_data is the trajectory data container in which to add the frame + * set. + * @param first_frame is the first frame of the frame set. + * @param n_frames is the number of frames in the frame set. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code first_frame >= 0 \endcode The first frame must not be negative. + * @pre \code n_frames >= 0 \endcode The number of frames must not be negative. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_new + (tng_trajectory_t tng_data, + const int64_t first_frame, + const int64_t n_frames); + +/** + * @brief Create and initialise a frame set with the time of the first frame + * specified. + * @param tng_data is the trajectory data container in which to add the frame + * set. + * @param first_frame is the first frame of the frame set. + * @param n_frames is the number of frames in the frame set. + * @param first_frame_time is the time stamp of the first frame (in seconds). + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code first_frame >= 0 \endcode The first frame must not be negative. + * @pre \code n_frames >= 0 \endcode The number of frames must not be negative. + * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame + * must not be negative. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_with_time_new + (tng_trajectory_t tng_data, + const int64_t first_frame, + const int64_t n_frames, + const double first_frame_time); + +/** + * @brief Set the time stamp of the first frame of the current frame set. + * @param tng_data is the trajectory containing the frame set. + * @param first_frame_time is the time stamp of the first frame in the + * frame set. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame + * must not be negative. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_set_first_frame_time_set + (tng_trajectory_t tng_data, + const double first_frame_time); + +/** + * @brief Read the number of the first frame of the next frame set. + * @param tng_data is the trajectory containing the frame set. + * @param frame is set to the frame number of the first frame in the + * next frame set. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code tng_data->input_file != 0 \endcode An input file must be open + * to find the next frame set. + * @pre \code frame != 0 \endcode The pointer to the frame must not be a NULL + * pointer. + * @return TNG_SUCCESS(0) if successful, TNG_FAILURE(1) if there is no next + * frame set or TNG_CRITICAL(2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_first_frame_nr_of_next_frame_set_get + (const tng_trajectory_t tng_data, + int64_t *frame); + +/** + * @brief Add a non-particle dependent data block. + * @param tng_data is the trajectory data container in which to add the data + * block + * @param id is the block ID of the block to add. + * @param block_name is a descriptive name of the block to add + * @param datatype is the datatype of the data in the block (e.g. int/float) + * @param block_type_flag indicates if this is a non-trajectory block (added + * directly to tng_data) or if it is a trajectory block (added to the + * frame set) + * @param n_frames is the number of frames of the data block (automatically + * set to 1 if adding a non-trajectory data block) + * @param n_values_per_frame is how many values a stored each frame (e.g. 9 + * for a box shape block) + * @param stride_length is how many frames are between each entry in the + * data block + * @param codec_id is the ID of the codec to compress the data. + * @param new_data is an array of data values to add. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code block_name != 0 \endcode The pointer to the block name must + * not be a NULL pointer. + * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be + * a positive integer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_data_block_add + (tng_trajectory_t tng_data, + const int64_t id, + const char *block_name, + const char datatype, + const char block_type_flag, + int64_t n_frames, + const int64_t n_values_per_frame, + int64_t stride_length, + const int64_t codec_id, + void *new_data); + +/** + * @brief Add a particle dependent data block. + * @param tng_data is the trajectory data container in which to add the data + * block + * @param id is the block ID of the block to add. + * @param block_name is a descriptive name of the block to add + * @param datatype is the datatype of the data in the block (e.g. int/float) + * @param block_type_flag indicates if this is a non-trajectory block (added + * directly to tng_data) or if it is a trajectory block (added to the + * frame set) + * @param n_frames is the number of frames of the data block (automatically + * set to 1 if adding a non-trajectory data block) + * @param n_values_per_frame is how many values a stored each frame (e.g. 9 + * for a box shape block) + * @param stride_length is how many frames are between each entry in the + * data block + * @param num_first_particle is the number of the first particle stored + * in this data block + * @param n_particles is the number of particles stored in this data block + * @param codec_id is the ID of the codec to compress the data. + * @param new_data is an array of data values to add. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code block_name != 0 \endcode The pointer to the block name must + * not be a NULL pointer. + * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be + * a positive integer. + * @pre \code num_first_particle >= 0 \endcode The number of the + * first particle must be >= 0. + * @pre \code n_particles >= 0 \endcode n_particles must be >= 0. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_particle_data_block_add + (tng_trajectory_t tng_data, + const int64_t id, + const char *block_name, + const char datatype, + const char block_type_flag, + int64_t n_frames, + const int64_t n_values_per_frame, + int64_t stride_length, + const int64_t num_first_particle, + const int64_t n_particles, + const int64_t codec_id, + void *new_data); + +/** @brief Get the name of a data block of a specific ID. + * @param tng_data is the trajectory data container. + * @param block_id is the ID of the data block of which to get the name. + * @param name is a string, which is set to the name of the data block. + * Memory must be reserved beforehand. + * @param max_len is the maximum length of name. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code name != 0 \endcode The pointer to the name string + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1) + * if a minor error has occured or the data block is not found or + * TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_data_block_name_get + (tng_trajectory_t tng_data, + int64_t block_id, + char *name, + int max_len); + +/** @brief Get the dependency of a data block of a specific ID. + * @param tng_data is the trajectory data container. + * @param block_id is the ID of the data block of which to get the name. + * @param block_dependency is a pointer to the dependency of the data block. + * If the block is frame dependent it will be set to TNG_FRAME_DEPENDENT, + * if it is particle dependent it will be set to TNG_PARTICLE_DEPENDENT and + * if it is both it will be set to TNG_FRAME_DEPENDENT & TNG_PARTICLE_DEPENDENT. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code block_dependency != 0 \endcode The pointer to the block dependency + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1) + * if a minor error has occured or the data block is not found or + * TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_data_block_dependency_get + (const tng_trajectory_t tng_data, + int64_t block_id, + int *block_dependency); + +/** @brief Get the number of values per frame of a data block of a specific ID. + * @param tng_data is the trajectory data container. + * @param block_id is the ID of the data block of which to get the name. + * @param n_values_per_frame is a pointer set to the number of values per frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of values + * per frame must not be a NULL pointer. + * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1) + * if a minor error has occured or the data block is not found or + * TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_data_block_num_values_per_frame_get + (const tng_trajectory_t tng_data, + int64_t block_id, + int64_t *n_values_per_frame); + +/** + * @brief Write data of one trajectory frame to the output_file of tng_data. + * @param tng_data is a trajectory data container. tng_data->output_file_path + * specifies which file to write to. If the file (output_file) is not open it + * will be opened. + * @param frame_nr is the index number of the frame to write. + * @param block_id is the ID of the data block to write the data to. + * @param values is an array of data to write. The length of the array should + * equal n_values_per_frame. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code values != 0 \endcode The pointer to the values must not be a NULL + * pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_data_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const int64_t block_id, + const void *values, + const char hash_mode); + +/** + * @brief Write particle data of one trajectory frame to the output_file of + * tng_data. + * @param tng_data is a trajectory data container. tng_data->output_file_path + * specifies which file to write to. If the file (output_file) is not open it + * will be opened. + * @param frame_nr is the index number of the frame to write. + * @param block_id is the ID of the data block to write the data to. + * @param val_first_particle is the number of the first particle in the data + * array. + * @param val_n_particles is the number of particles in the data array. + * @param values is a 1D-array of data to write. The length of the array should + * equal n_particles * n_values_per_frame. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code val_first_particle >= 0 \endcode The number of the + * first particle must be >= 0. + * @pre \code val_n_particles >= 0 \endcode The number of particles must be >= 0. + * @pre \code values != 0 \endcode The pointer to the values must not be a NULL + * pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_frame_particle_data_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const int64_t block_id, + const int64_t val_first_particle, + const int64_t val_n_particles, + const void *values, + const char hash_mode); + +/** + * @brief Free data of an array of values (2D). + * @param tng_data is a trajectory data container. + * @param values is the 2D array to free and will be set to 0 afterwards. + * @param n_frames is the number of frames in the data array. + * @param n_values_per_frame is the number of values per frame in the data array. + * @param type is the data type of the data in the array (e.g. int/float/char). + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_data_values_free + (const tng_trajectory_t tng_data, + union data_values **values, + const int64_t n_frames, + const int64_t n_values_per_frame, + const char type); + +/** + * @brief Free data of an array of values (3D). + * @param tng_data is a trajectory data container. + * @param values is the array to free and will be set to 0 afterwards. + * @param n_frames is the number of frames in the data array. + * @param n_particles is the number of particles in the data array. + * @param n_values_per_frame is the number of values per frame in the data array. + * @param type is the data type of the data in the array (e.g. int/float/char). + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_particle_data_values_free + (const tng_trajectory_t tng_data, + union data_values ***values, + const int64_t n_frames, + const int64_t n_particles, + const int64_t n_values_per_frame, + const char type); + +/** + * @brief Retrieve non-particle data, from the last read frame set. Obsolete! + * @param tng_data is a trajectory data container. tng_data->input_file_path specifies + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param block_id is the id number of the particle data block to read. + * @param values is a pointer to a 2-dimensional array (memory unallocated), which + * will be filled with data. The array will be sized + * (n_frames * n_values_per_frame). + * Since ***values is allocated in this function it is the callers + * responsibility to free the memory. + * @param n_frames is set to the number of frames in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n_frames != 0 \endcode The pointer to the number of frames + * must not be a NULL pointer. + * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of + * values per frame must not be a NULL pointer. + * @pre \code type != 0 \endcode The pointer to the data type must not + * be a NULL pointer. + * @details This function is obsolete and only retained for compatibility. Use + * tng_data_vector_get() instead. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_data_get(tng_trajectory_t tng_data, + const int64_t block_id, + union data_values ***values, + int64_t *n_frames, + int64_t *n_values_per_frame, + char *type); + +/** + * @brief Retrieve a vector (1D array) of non-particle data, from the last read frame set. + * @param tng_data is a trajectory data container. tng_data->input_file_path specifies + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param block_id is the id number of the particle data block to read. + * @param values is a pointer to a 1-dimensional array (memory unallocated), which + * will be filled with data. The length of the array will be (n_frames * n_values_per_frame). + * Since **values is allocated in this function it is the callers + * responsibility to free the memory. + * @param n_frames is set to the number of particles in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param stride_length is set to the stride length of the returned data. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n_frames != 0 \endcode The pointer to the number of frames + * must not be a NULL pointer. + * @pre \code stride_length != 0 \endcode The pointer to the stride length + * must not be a NULL pointer. + * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of + * values per frame must not be a NULL pointer. + * @pre \code type != 0 \endcode The pointer to the data type must not + * be a NULL pointer. + * @details This does only work for numerical (int, float, double) data. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_data_vector_get + (tng_trajectory_t tng_data, + const int64_t block_id, + void **values, + int64_t *n_frames, + int64_t *stride_length, + int64_t *n_values_per_frame, + char *type); + +/** + * @brief Read and retrieve non-particle data, in a specific interval. Obsolete! + * @param tng_data is a trajectory data container. tng_data->input_file_path specifies + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param block_id is the id number of the particle data block to read. + * @param start_frame_nr is the index number of the first frame to read. + * @param end_frame_nr is the index number of the last frame to read. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @param values is a pointer to a 2-dimensional array (memory unallocated), which + * will be filled with data. The array will be sized + * (n_frames * n_values_per_frame). + * Since ***values is allocated in this function it is the callers + * responsibility to free the memory. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before + * the last frame. + * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of + * values per frame must not be a NULL pointer. + * @pre \code type != 0 \endcode The pointer to the data type must not + * be a NULL pointer. + * @details This function is obsolete and only retained for compatibility. Use + * tng_data_vector_interval_get() instead. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_data_interval_get + (tng_trajectory_t tng_data, + const int64_t block_id, + const int64_t start_frame_nr, + const int64_t end_frame_nr, + const char hash_mode, + union data_values ***values, + int64_t *n_values_per_frame, + char *type); + +/** + * @brief Read and retrieve a vector (1D array) of non-particle data, + * in a specific interval. + * @param tng_data is a trajectory data container. tng_data->input_file_path specifies + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param block_id is the id number of the particle data block to read. + * @param start_frame_nr is the index number of the first frame to read. + * @param end_frame_nr is the index number of the last frame to read. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @param values is a pointer to a 1-dimensional array (memory unallocated), which + * will be filled with data. The length of the array will be (n_frames * n_values_per_frame). + * Since **values is allocated in this function it is the callers + * responsibility to free the memory. + * @param stride_length is set to the stride length (writing interval) of + * the data. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before + * the last frame. + * @pre \code stride_length != 0 \endcode The pointer to the stride length + * must not be a NULL pointer. + * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of + * values per frame must not be a NULL pointer. + * @pre \code type != 0 \endcode The pointer to the data type must not + * be a NULL pointer. + * @details This does only work for numerical (int, float, double) data. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_data_vector_interval_get + (tng_trajectory_t tng_data, + const int64_t block_id, + const int64_t start_frame_nr, + const int64_t end_frame_nr, + const char hash_mode, + void **values, + int64_t *stride_length, + int64_t *n_values_per_frame, + char *type); + +/** + * @brief Retrieve particle data, from the last read frame set. Obsolete! + * @details The particle dimension of the returned values array is translated + * to real particle numbering, i.e. the numbering of the actual molecular + * system. + * @param tng_data is a trajectory data container. tng_data->input_file_path + * specifies which file to read from. If the file (input_file) is not open it + * will be opened. + * @param block_id is the id number of the particle data block to read. + * @param values is a pointer to a 3-dimensional array (memory unallocated), which + * will be filled with data. The array will be sized + * (n_frames * n_particles * n_values_per_frame). + * Since ****values is allocated in this function it is the callers + * responsibility to free the memory. + * @param n_frames is set to the number of frames in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param n_particles is set to the number of particles in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n_frames != 0 \endcode The pointer to the number of frames + * must not be a NULL pointer. + * @pre \code n_particles != 0 \endcode The pointer to the number of particles must + * not be a NULL pointer. + * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of + * values per frame must not be a NULL pointer. + * @pre \code type != 0 \endcode The pointer to the data type must not + * be a NULL pointer. + * @details This function is obsolete and only retained for compatibility. Use + * tng_particle_data_vector_get() instead. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_particle_data_get + (tng_trajectory_t tng_data, + const int64_t block_id, + union data_values ****values, + int64_t *n_frames, + int64_t *n_particles, + int64_t *n_values_per_frame, + char *type); + +/** + * @brief Retrieve a vector (1D array) of particle data, from the last read frame set. + * @details The particle dimension of the returned values array is translated + * to real particle numbering, i.e. the numbering of the actual molecular + * system. + * @param tng_data is a trajectory data container. tng_data->input_file_path + * specifies which file to read from. If the file (input_file) is not open it + * will be opened. + * @param block_id is the id number of the particle data block to read. + * @param values is a pointer to a 1-dimensional array (memory unallocated), which + * will be filled with data. The length of the array will be + * (n_frames * n_particles * n_values_per_frame). + * Since **values is allocated in this function it is the callers + * responsibility to free the memory. + * @param n_frames is set to the number of frames in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param stride_length is set to the stride length of the returned data. + * @param n_particles is set to the number of particles in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n_particles != 0 \endcode The pointer to the number of particles must + * not be a NULL pointer. + * @pre \code stride_length != 0 \endcode The pointer to the stride length + * must not be a NULL pointer. + * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of + * values per frame must not be a NULL pointer. + * @pre \code type != 0 \endcode The pointer to the data type must not + * be a NULL pointer. + * @details This does only work for numerical (int, float, double) data. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_get + (tng_trajectory_t tng_data, + const int64_t block_id, + void **values, + int64_t *n_frames, + int64_t *stride_length, + int64_t *n_particles, + int64_t *n_values_per_frame, + char *type); + +/** + * @brief Read and retrieve particle data, in a specific interval. Obsolete! + * @details The particle dimension of the returned values array is translated + * to real particle numbering, i.e. the numbering of the actual molecular + * system. + * @param tng_data is a trajectory data container. tng_data->input_file_path specifies + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param block_id is the id number of the particle data block to read. + * @param start_frame_nr is the index number of the first frame to read. + * @param end_frame_nr is the index number of the last frame to read. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @param values is a pointer to a 3-dimensional array (memory unallocated), which + * will be filled with data. The array will be sized + * (n_frames * n_particles * n_values_per_frame). + * Since ****values is allocated in this function it is the callers + * responsibility to free the memory. + * @param n_particles is set to the number of particles in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n_frames != 0 \endcode The pointer to the number of frames + * must not be a NULL pointer. + * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before + * the last frame. + * @pre \code n_particles != 0 \endcode The pointer to the number of particles must + * not be a NULL pointer. + * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of + * values per frame must not be a NULL pointer. + * @pre \code type != 0 \endcode The pointer to the data type must not + * be a NULL pointer. + * @details This function is obsolete and only retained for compatibility. Use + * tng_particle_data_vector_interval_get() instead. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_particle_data_interval_get + (tng_trajectory_t tng_data, + const int64_t block_id, + const int64_t start_frame_nr, + const int64_t end_frame_nr, + const char hash_mode, + union data_values ****values, + int64_t *n_particles, + int64_t *n_values_per_frame, + char *type); + +/** + * @brief Read and retrieve a vector (1D array) particle data, in a + * specific interval. + * @details The particle dimension of the returned values array is translated + * to real particle numbering, i.e. the numbering of the actual molecular + * system. + * @param tng_data is a trajectory data container. tng_data->input_file_path specifies + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param block_id is the id number of the particle data block to read. + * @param start_frame_nr is the index number of the first frame to read. + * @param end_frame_nr is the index number of the last frame to read. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @param values is a pointer to a 1-dimensional array (memory unallocated), which + * will be filled with data. The length of the array will be + * (n_frames * n_particles * n_values_per_frame). + * Since **values is allocated in this function it is the callers + * responsibility to free the memory. + * @param stride_length is set to the stride length (writing interval) of + * the data. + * @param n_particles is set to the number of particles in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before + * the last frame. + * @pre \code n_particles != 0 \endcode The pointer to the number of particles must + * not be a NULL pointer. + * @pre \code stride_length != 0 \endcode The pointer to the stride length + * must not be a NULL pointer. + * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of + * values per frame must not be a NULL pointer. + * @pre \code type != 0 \endcode The pointer to the data type must not + * be a NULL pointer. + * @details This does only work for numerical (int, float, double) data. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_interval_get + (tng_trajectory_t tng_data, + const int64_t block_id, + const int64_t start_frame_nr, + const int64_t end_frame_nr, + const char hash_mode, + void **values, + int64_t *n_particles, + int64_t *stride_length, + int64_t *n_values_per_frame, + char *type); + +/** + * @brief Get the stride length of a specific data (particle dependency does not matter) + * block, either in the current frame set or of a specific frame. + * @param tng_data is the trajectory data container. + * @param block_id is the block ID of the data block, of which to retrieve the + * stride length of the data. + * @param frame is the frame from which to get the stride length. If frame is set to -1 + * no specific frame will be used, but instead the first frame, starting from the last read + * frame set, containing the data block will be used. + * @param stride_length is set to the value of the stride length of the data block. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_data_get_stride_length + (const tng_trajectory_t tng_data, + const int64_t block_id, + int64_t frame, + int64_t *stride_length); + +/** + * @brief Get the date and time of initial file creation in ISO format (string). + * @param tng_data is a trajectory data container. + * @param time is a pointer to the string in which the date will be stored. Memory + * must be reserved beforehand. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code time != 0 \endcode The pointer to the time must not be a NULL + * pointer. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_time_get_str + (const tng_trajectory_t tng_data, + char *time); +/** @} */ /* end of group1 */ + +/** @defgroup group2 High-level API + * These functions make it easier to access and output TNG data. They + * are recommended unless there is a special reason to use the more + * detailed functions available in the low-level API. + * @{ + */ + +/** + * @brief High-level function for opening and initializing a TNG trajectory. + * @param filename is a string containing the name of the trajectory to open. + * @param mode specifies the file mode of the trajectory. Can be set to 'r', + * 'w' or 'a' for reading, writing or appending respectively. + * @param tng_data_p is a pointer to the opened trajectory. This will be + * allocated by the TNG library. The trajectory must be + * closed by the user, whereby memory is freed. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code filename != 0 \endcode The pointer to the filename must not be a + * NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_open + (const char *filename, + const char mode, + tng_trajectory_t *tng_data_p); + +/** + * @brief High-level function for closing a TNG trajectory. + * @param tng_data_p is a pointer to the trajectory to close. The memory + * will be freed after finalising the writing. + * @return TNG_SUCCESS (0) if successful. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_close + (tng_trajectory_t *tng_data_p); + +/** + * @brief High-level function for getting the time (in seconds) of a frame. + * @param tng_data is the trajectory containing the frame. + * @param frame_nr is the frame number of which to get the time. + * @param time is set to the time (in seconds) of the specified frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code time != 0 \endcode The pointer to the time must not be a + * NULL pointer. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if a + * minor error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_time_of_frame_get + (tng_trajectory_t tng_data, + const int64_t frame_nr, + double *time); + +/* + * @brief High-level function for getting the molecules in the mol system. + * @param tng_data is the trajectory containing the mol system. + * @param n_mols is set to the number of molecules in the system. + * @param molecule_cnt_list will be pointing to the list of counts of each molecule + * in the mol system. + * @param mols pointing to the list of molecules in the mol system. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n_mols != 0 \endcode The pointer to the number of molecules must + * not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful. + */ +/*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecules_get + (tng_trajectory_t tng_data, + int64_t *n_mols, + int64_t **molecule_cnt_list, + tng_molecule_t *mols); +*/ +/* + * @brief High-level function for adding a molecule to the mol system. + * @param tng_data is the trajectory containing the mol system. + * @param name is the name of the molecule to add. + * @param cnt is the count of the molecule. + * @param mol is set to point to the newly created molecule. + * @pre \code name != 0 \endcode The pointer to the name must not be a + * NULL pointer. + * @pre \code cnt >= 0 \endcode The requested count must be >= 0. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured or TNG_CRITICAL (2) if a major error has occured. + */ +/*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecule_add + (tng_trajectory_t tng_data, + const char *name, + const int64_t cnt, + tng_molecule_t *mol); +*/ +/* +// tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_get +// (tng_trajectory_t tng_data, +// const tng_molecule_t mol, +// int64_t *n_particles, +// char ***names, +// char ***types, +// char ***res_names, +// int64_t **res_ids, +// char ***chain_names, +// int64_t **chain_ids); +// +// tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_set +// (tng_trajectory_t tng_data, +// tng_molecule_t mol, +// const int64_t n_particles, +// const char **names, +// const char **types, +// const char **res_names, +// const int64_t *res_ids, +// const char **chain_names, +// const int64_t *chain_ids); +*/ +/** + * @brief High-level function for reading the positions of all particles + * from all frames. + * @param tng_data is the trajectory to read from. + * @param positions will be set to point at a 1-dimensional array of floats, + * which will contain the positions. The data is stored sequentially in order + * of frames. For each frame the positions (x, y and z coordinates) are stored. + * The variable may point at already allocated memory or be a NULL pointer. + * The memory must be freed afterwards. + * @param stride_length will be set to the writing interval of the stored data. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code positions != 0 \endcode The pointer to the positions array + * must not be a NULL pointer. + * @pre \code stride_length != 0 \endcode The pointer to the stride length + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_pos_read + (tng_trajectory_t tng_data, + float **positions, + int64_t *stride_length); + +/** + * @brief High-level function for reading the velocities of all particles + * from all frames. + * @param tng_data is the trajectory to read from. + * @param velocities will be set to point at a 1-dimensional array of floats, + * which will contain the velocities. The data is stored sequentially in order + * of frames. For each frame the velocities (in x, y and z) are stored. The + * variable may point at already allocated memory or be a NULL pointer. + * The memory must be freed afterwards. + * @param stride_length will be set to the writing interval of the stored data. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code velocities != 0 \endcode The pointer to the velocities array + * must not be a NULL pointer. + * @pre \code stride_length != 0 \endcode The pointer to the stride length + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_vel_read + (tng_trajectory_t tng_data, + float **velocities, + int64_t *stride_length); + +/** + * @brief High-level function for reading the forces of all particles + * from all frames. + * @param tng_data is the trajectory to read from. + * @param forces will be set to point at a 1-dimensional array of floats, + * which will contain the forces. The data is stored sequentially in order + * of frames. For each frame the forces (in x, y and z) are stored. The + * variable may point at already allocated memory or be a NULL pointer. + * The memory must be freed afterwards. + * @param stride_length will be set to the writing interval of the stored data. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code forces != 0 \endcode The pointer to the forces array + * must not be a NULL pointer. + * @pre \code stride_length != 0 \endcode The pointer to the stride length + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_force_read + (tng_trajectory_t tng_data, + float **forces, + int64_t *stride_length); + +/** + * @brief High-level function for reading the box shape from all frames. + * @param tng_data is the trajectory to read from. + * @param box_shape will be set to point at a 1-dimensional array of floats, + * which will contain the box shape. The data is stored sequentially in order + * of frames. The variable may point at already allocated memory or be a NULL pointer. + * If the box shape is not modified during the trajectory, but as general data, + * that will be returned instead. + * @param stride_length will be set to the writing interval of the stored data. + * @details This function should only be used if number of values used to specify + * the box shape is known (by default TNG uses 9 values) since it does not + * return the number of values in the array. It is recommended to use + * tng_data_vector_interval_get() instead. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code box_shape != 0 \endcode The pointer to the box_shape array + * must not be a NULL pointer. + * @pre \code stride_length != 0 \endcode The pointer to the stride length + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read + (tng_trajectory_t tng_data, + float **box_shape, + int64_t *stride_length); + +/** + * @brief High-level function for reading the next frame of particle-dependent + * data of a specific type. + * @param tng_data is the trajectory to read from. + * @param block_id is the ID number of the block containing the data of interest. + * @param values will be set to point at a 1-dimensional array containing the + * requested data. The variable may point at already allocated memory or be a + * NULL pointer. The memory must be freed afterwards. + * @param data_type will be pointing to a character indicating the size of the + * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA. + * @param retrieved_frame_number will be pointing at the frame number of the + * returned frame. + * @param retrieved_time will be pointing at the time stamp of the returned + * frame. + * @details If no frame has been read before the first frame of the trajectory + * is read. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code values != 0 \endcode The pointer to the values array + * must not be a NULL pointer. + * @pre \code data_type != 0 \endcode The pointer to the data type of the + * returned data must not be a NULL pointer. + * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame + * number of the returned data must not be a NULL pointer. + * @pre \code retrieved_time != 0 \endcode The pointer to the time of the + * returned data must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_particle_data_next_frame_read + (tng_trajectory_t tng_data, + const int64_t block_id, + void **values, + char *data_type, + int64_t *retrieved_frame_number, + double *retrieved_time); + +/** + * @brief High-level function for reading the next frame of non-particle-dependent + * data of a specific type. + * @param tng_data is the trajectory to read from. + * @param block_id is the ID number of the block containing the data of interest. + * @param values will be set to point at a 1-dimensional array containing the + * requested data. The variable may point at already allocated memory or be a + * NULL pointer. The memory must be freed afterwards. + * @param data_type will be pointing to a character indicating the size of the + * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA. + * @param retrieved_frame_number will be pointing at the frame number of the + * returned frame. + * @param retrieved_time will be pointing at the time stamp of the returned + * frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code values != 0 \endcode The pointer to the values array + * must not be a NULL pointer. + * @pre \code data_type != 0 \endcode The pointer to the data type of the + * returned data must not be a NULL pointer. + * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame + * number of the returned data must not be a NULL pointer. + * @pre \code retrieved_time != 0 \endcode The pointer to the time of the + * returned data must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_non_particle_data_next_frame_read + (tng_trajectory_t tng_data, + const int64_t block_id, + void **values, + char *data_type, + int64_t *retrieved_frame_number, + double *retrieved_time); + +/** + * @brief High-level function for reading the positions of all particles + * from a specific range of frames. + * @param tng_data is the trajectory to read from. + * @param first_frame is the first frame to return position data from. + * @param last_frame is the last frame to return position data from. + * @param positions will be set to point at a 1-dimensional array of floats, + * which will contain the positions. The data is stored sequentially in order + * of frames. For each frame the positions (x, y and z coordinates) are stored. + * The variable may point at already allocated memory or be a NULL pointer. + * The memory must be freed afterwards. + * @param stride_length will be set to the writing interval of the stored data. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before + * the last frame. + * @pre \code positions != 0 \endcode The pointer to the positions array + * must not be a NULL pointer. + * @pre \code stride_length != 0 \endcode The pointer to the stride length + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_pos_read_range + (tng_trajectory_t tng_data, + const int64_t first_frame, + const int64_t last_frame, + float **positions, + int64_t *stride_length); + +/** + * @brief High-level function for reading the velocities of all particles + * from a specific range of frames. + * @param tng_data is the trajectory to read from. + * @param first_frame is the first frame to return position data from. + * @param last_frame is the last frame to return position data from. + * @param velocities will be set to point at a 1-dimensional array of floats, + * which will contain the velocities. The data is stored sequentially in order + * of frames. For each frame the velocities (in x, y and z) are stored. The + * variable may point at already allocated memory or be a NULL pointer. + * The memory must be freed afterwards. + * @param stride_length will be set to the writing interval of the stored data. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before + * the last frame. + * @pre \code velocities != 0 \endcode The pointer to the velocities array + * must not be a NULL pointer. + * @pre \code stride_length != 0 \endcode The pointer to the stride length + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_vel_read_range + (tng_trajectory_t tng_data, + const int64_t first_frame, + const int64_t last_frame, + float **velocities, + int64_t *stride_length); + +/** + * @brief High-level function for reading the forces of all particles + * from a specific range of frames. + * @param tng_data is the trajectory to read from. + * @param first_frame is the first frame to return position data from. + * @param last_frame is the last frame to return position data from. + * @param forces will be set to point at a 1-dimensional array of floats, + * which will contain the forces. The data is stored sequentially in order + * of frames. For each frame the forces (in x, y and z) are stored. The + * variable may point at already allocated memory or be a NULL pointer. + * The memory must be freed afterwards. + * @param stride_length will be set to the writing interval of the stored data. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before + * the last frame. + * @pre \code forces != 0 \endcode The pointer to the forces array + * must not be a NULL pointer. + * @pre \code stride_length != 0 \endcode The pointer to the stride length + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_force_read_range + (tng_trajectory_t tng_data, + const int64_t first_frame, + const int64_t last_frame, + float **forces, + int64_t *stride_length); + +/** + * @brief High-level function for reading the box shape + * from a specific range of frames. + * @param tng_data is the trajectory to read from. + * @param first_frame is the first frame to return position data from. + * @param last_frame is the last frame to return position data from. + * @param box_shape will be set to point at a 1-dimensional array of floats, + * which will contain the box shape. The data is stored sequentially in order + * of frames. + * If the box shape is not modified during the trajectory, but as general data, + * that will be returned instead. The + * variable may point at already allocated memory or be a NULL pointer. + * The memory must be freed afterwards. + * @param stride_length will be set to the writing interval of the stored data. + * @details This function should only be used if number of values used to specify + * the box shape is known (by default TNG uses 9 values) since it does not + * return the number of values in the array. It is recommended to use + * tng_data_vector_interval_get() instead. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before + * the last frame. + * @pre \code box_shape != 0 \endcode The pointer to the box_shape array + * must not be a NULL pointer. + * @pre \code stride_length != 0 \endcode The pointer to the stride length + * must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read_range + (tng_trajectory_t tng_data, + const int64_t first_frame, + const int64_t last_frame, + float **box_shape, + int64_t *stride_length); + +/** + * @brief High-level function for setting the writing interval of data blocks. + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @param n_values_per_frame is the number of values to store per frame. If the + * data is particle dependent there will be n_values_per_frame stored per + * particle each frame. + * @param block_id is the ID of the block, of which to set the output interval. + * @param block_name is a string that will be used as name of the block. Only + * required if the block did not exist, i.e. a new block is created. + * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the + * data is not related to specific particles (e.g. box shape) or + * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. + * positions). Only required if the block did not exist, i.e. a new block is + * created. + * @param compression is the compression routine to use when writing the data. + * Only required if the block did not exist, i.e. a new block is created. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code i >= 0 \endcode The writing interval must be >= 0. + * @details n_values_per_frame, block_name, particle_dependency and + * compression are only used if the data block did not exist before calling + * this function, in which case it is created. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_set + (tng_trajectory_t tng_data, + const int64_t i, + const int64_t n_values_per_frame, + const int64_t block_id, + const char *block_name, + const char particle_dependency, + const char compression); + +/** + * @brief High-level function for setting the writing interval of data blocks + * containing double precision data. + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @param n_values_per_frame is the number of values to store per frame. If the + * data is particle dependent there will be n_values_per_frame stored per + * particle each frame. + * @param block_id is the ID of the block, of which to set the output interval. + * @param block_name is a string that will be used as name of the block. Only + * required if the block did not exist, i.e. a new block is created. + * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the + * data is not related to specific particles (e.g. box shape) or + * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. + * positions). Only required if the block did not exist, i.e. a new block is + * created. + * @param compression is the compression routine to use when writing the data. + * Only required if the block did not exist, i.e. a new block is created. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code i >= 0 \endcode The writing interval must be >= 0. + * @details n_values_per_frame, block_name, particle_dependency and + * compression are only used if the data block did not exist before calling + * this function, in which case it is created. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_double_set + (tng_trajectory_t tng_data, + const int64_t i, + const int64_t n_values_per_frame, + const int64_t block_id, + const char *block_name, + const char particle_dependency, + const char compression); + +/** + * @brief High-level function for setting the writing interval of data blocks. + * Obsolete! Use tng_util_generic_write_interval_set() + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @param n_values_per_frame is the number of values to store per frame. If the + * data is particle dependent there will be n_values_per_frame stored per + * particle each frame. + * @param block_id is the ID of the block, of which to set the output interval. + * @param block_name is a string that will be used as name of the block. Only + * required if the block did not exist, i.e. a new block is created. + * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the + * data is not related to specific particles (e.g. box shape) or + * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. + * positions). Only required if the block did not exist, i.e. a new block is + * created. + * @param compression is the compression routine to use when writing the data. + * Only required if the block did not exist, i.e. a new block is created. + * @details n_values_per_frame, block_name, particle_dependency and + * compression are only used if the data block did not exist before calling + * this function, in which case it is created. + * This function is replaced by the more correcly named + * tng_util_generic_write_interval_set(), but is kept for compatibility. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_frequency_set + (tng_trajectory_t tng_data, + const int64_t i, + const int64_t n_values_per_frame, + const int64_t block_id, + const char *block_name, + const char particle_dependency, + const char compression); + +/** + * @brief High-level function for setting the writing interval of position + * data blocks. + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code i >= 0 \endcode The writing interval must be >= 0. + * @details This function uses tng_util_generic_write_interval_set() and will + * create a positions data block if none exists. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_set + (tng_trajectory_t tng_data, + const int64_t i); + +/** + * @brief High-level function for setting the writing interval of position + * data blocks containing double precision data. + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code i >= 0 \endcode The writing interval must be >= 0. + * @details This function uses tng_util_generic_write_interval_set() and will + * create a positions data block if none exists. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_double_set + (tng_trajectory_t tng_data, + const int64_t i); + +/** + * @brief High-level function for setting the writing interval of position + * data blocks. Obsolete! Use tng_util_pos_write_interval_set() + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code i >= 0 \endcode The writing interval must be >= 0. + * @details This function uses tng_util_generic_write_interval_set() and will + * create a positions data block if none exists. + * This function is replaced by the more correcly named + * tng_util_pos_write_interval_set(), but is kept for compatibility. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_frequency_set + (tng_trajectory_t tng_data, + const int64_t i); + +/** + * @brief High-level function for setting the writing interval of velocity + * data blocks. + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code i >= 0 \endcode The writing interval must be >= 0. + * @details This function uses tng_util_generic_write_interval_set() and will + * create a velocities data block if none exists. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_set + (tng_trajectory_t tng_data, + const int64_t i); + +/** + * @brief High-level function for setting the writing interval of velocity + * data blocks containing double precision data. + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code i >= 0 \endcode The writing interval must be >= 0. + * @details This function uses tng_util_generic_write_interval_set() and will + * create a velocities data block if none exists. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_double_set + (tng_trajectory_t tng_data, + const int64_t i); + +/** + * @brief High-level function for setting the writing interval of velocity + * data blocks. Obsolete! Use tng_util_vel_write_interval_set() + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @details This function uses tng_util_generic_write_interval_set() and will + * create a velocities data block if none exists. + * This function is replaced by the more correcly named + * tng_util_vel_write_interval_set(), but is kept for compatibility. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_frequency_set + (tng_trajectory_t tng_data, + const int64_t i); + +/** + * @brief High-level function for setting the writing interval of force + * data blocks. + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code i >= 0 \endcode The writing interval must be >= 0. + * @details This function uses tng_util_generic_write_interval_set() and will + * create a forces data block if none exists. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_set + (tng_trajectory_t tng_data, + const int64_t i); + +/** + * @brief High-level function for setting the writing interval of force + * data blocks containing double precision data. + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code i >= 0 \endcode The writing interval must be >= 0. + * @details This function uses tng_util_generic_write_interval_set() and will + * create a forces data block if none exists. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_double_set + (tng_trajectory_t tng_data, + const int64_t i); + +/** + * @brief High-level function for setting the writing interval of force + * data blocks. Obsolete! Use tng_util_force_write_interval_set() + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @details This function uses tng_util_generic_write_interval_set() and will + * create a forces data block if none exists. + * This function is replaced by the more correcly named + * tng_util_force_write_interval_set(), but is kept for compatibility. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_force_write_frequency_set + (tng_trajectory_t tng_data, + const int64_t i); + +/** + * @brief High-level function for setting the writing interval of box shape + * data blocks. + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code i >= 0 \endcode The writing interval must be >= 0. + * @details This function uses tng_util_generic_write_interval_set() and will + * create a box shape data block if none exists. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_set + (tng_trajectory_t tng_data, + const int64_t i); + +/** + * @brief High-level function for setting the writing interval of box shape + * data blocks containing double precision data. + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code i >= 0 \endcode The writing interval must be >= 0. + * @details This function uses tng_util_generic_write_interval_set() and will + * create a box shape data block if none exists. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_double_set + (tng_trajectory_t tng_data, + const int64_t i); + +/** + * @brief High-level function for setting the writing interval of velocity + * data blocks. Obsolete! Use tng_util_box_shape_write_interval_set() + * @param tng_data is the trajectory to use. + * @param i is the output interval, i.e. i == 10 means data written every 10th + * frame. + * @details This function uses tng_util_generic_write_interval_set() and will + * create a box shape data block if none exists. + * This function is replaced by the more correcly named + * tng_util_box_shape_write_interval_set(), but is kept for compatibility. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_frequency_set + (tng_trajectory_t tng_data, + const int64_t i); + +/** + * @brief High-level function for writing data of one frame to a data block. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param values is a 1D array of data to add. The array should be of length + * n_particles * n_values_per_frame if writing particle related data, otherwise + * it should be n_values_per_frame. + * @param n_values_per_frame is the number of values to store per frame. If the + * data is particle dependent there will be n_values_per_frame stored per + * particle each frame. + * @param block_id is the ID of the block, of which to set the output interval. + * @param block_name is a string that will be used as name of the block. Only + * required if the block did not exist, i.e. a new block is created. + * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the + * data is not related to specific particles (e.g. box shape) or + * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. + * positions). Only required if the block did not exist, i.e. a new block is + * created. + * @param compression is the compression routine to use when writing the data. + * Only required if the block did not exist, i.e. a new block is created. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code values != 0 \endcode The pointer to the values array must not + * be a NULL pointer. + * @details n_values_per_frame, block_name, particle_dependency and + * compression are only used if the data block did not exist before calling + * this function, in which case it is created. + * N.b. Data is written a whole block at a time. The data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_generic_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const float *values, + const int64_t n_values_per_frame, + const int64_t block_id, + const char *block_name, + const char particle_dependency, + const char compression); + +/** + * @brief High-level function for writing data of one frame to a double precision + * data block. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param values is a 1D array of data to add. The array should be of length + * n_particles * n_values_per_frame if writing particle related data, otherwise + * it should be n_values_per_frame. + * @param n_values_per_frame is the number of values to store per frame. If the + * data is particle dependent there will be n_values_per_frame stored per + * particle each frame. + * @param block_id is the ID of the block, of which to set the output interval. + * @param block_name is a string that will be used as name of the block. Only + * required if the block did not exist, i.e. a new block is created. + * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the + * data is not related to specific particles (e.g. box shape) or + * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. + * positions). Only required if the block did not exist, i.e. a new block is + * created. + * @param compression is the compression routine to use when writing the data. + * Only required if the block did not exist, i.e. a new block is created. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code values != 0 \endcode The pointer to the values array must not + * be a NULL pointer. + * @details n_values_per_frame, block_name, particle_dependency and + * compression are only used if the data block did not exist before calling + * this function, in which case it is created. + * N.b. Data is written a whole block at a time. The data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_generic_double_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double *values, + const int64_t n_values_per_frame, + const int64_t block_id, + const char *block_name, + const char particle_dependency, + const char compression); + +/** + * @brief High-level function for adding data to positions data blocks. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param positions is a 1D array of data to add. The array should be of length + * n_particles * 3. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code positions != 0 \endcode The pointer to the positions array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_write() and will + * create a positions data block if none exists. Positions are stored as three + * values per frame and compressed using TNG compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_pos_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const float *positions); + +/** + * @brief High-level function for adding data to positions data blocks at double + * precision. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param positions is a 1D array of data to add. The array should be of length + * n_particles * 3. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code positions != 0 \endcode The pointer to the positions array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_write() and will + * create a positions data block if none exists. Positions are stored as three + * values per frame and compressed using TNG compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_pos_double_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double *positions); + +/** + * @brief High-level function for adding data to velocities data blocks. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param velocities is a 1D array of data to add. The array should be of length + * n_particles * 3. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code velocities != 0 \endcode The pointer to the velocities array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_write() and will + * create a velocities data block if none exists. Velocities are stored as three + * values per frame and compressed using TNG compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_vel_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const float *velocities); + +/** + * @brief High-level function for adding data to velocities data blocks at double + * precision. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param velocities is a 1D array of data to add. The array should be of length + * n_particles * 3. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code velocities != 0 \endcode The pointer to the velocities array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_write() and will + * create a velocities data block if none exists. Velocities are stored as three + * values per frame and compressed using TNG compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_vel_double_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double *velocities); + +/** + * @brief High-level function for adding data to forces data blocks. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param forces is a 1D array of data to add. The array should be of length + * n_particles * 3. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code forces != 0 \endcode The pointer to the forces array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_write() and will + * create a forces data block if none exists. Forces are stored as three + * values per frame and compressed using gzip compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_force_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const float *forces); + +/** + * @brief High-level function for adding data to forces data blocks at double + * precision. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param forces is a 1D array of data to add. The array should be of length + * n_particles * 3. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code forces != 0 \endcode The pointer to the forces array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_write() and will + * create a forces data block if none exists. Forces are stored as three + * values per frame and compressed using gzip compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_force_double_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double *forces); + +/** + * @brief High-level function for adding data to box shape data blocks. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param box_shape is a 1D array of data to add. The array should be of length 9. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_write() and will + * create a box shape data block if none exists. Box shapes are stored as 9 + * values per frame and compressed using TNG compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const float *box_shape); + +/** + * @brief High-level function for adding data to box shape data blocks at double + * precision. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param box_shape is a 1D array of data to add. The array should be of length 9. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_write() and will + * create a box shape data block if none exists. Box shapes are stored as 9 + * values per frame and compressed using TNG compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_double_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double *box_shape); + +/** + * @brief High-level function for writing data of one frame to a data block. + * If the frame is at the beginning of a frame set the time stamp of the frame + * set is set. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param time is the time stamp of the frame (in seconds). + * @param values is a 1D array of data to add. The array should be of length + * n_particles * n_values_per_frame if writing particle related data, otherwise + * it should be n_values_per_frame. + * @param n_values_per_frame is the number of values to store per frame. If the + * data is particle dependent there will be n_values_per_frame stored per + * particle each frame. + * @param block_id is the ID of the block, of which to set the output interval. + * @param block_name is a string that will be used as name of the block. Only + * required if the block did not exist, i.e. a new block is created. + * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the + * data is not related to specific particles (e.g. box shape) or + * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. + * positions). Only required if the block did not exist, i.e. a new block is + * created. + * @param compression is the compression routine to use when writing the data. + * Only required if the block did not exist, i.e. a new block is created. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code time >= 0 \endcode The time stamp must be >= 0. + * @pre \code values != 0 \endcode The pointer to the values array must not + * be a NULL pointer. + * @details n_values_per_frame, block_name, particle_dependency and + * compression are only used if the data block did not exist before calling + * this function, in which case it is created. + * N.b. Data is written a whole block at a time. The data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double time, + const float *values, + const int64_t n_values_per_frame, + const int64_t block_id, + const char *block_name, + const char particle_dependency, + const char compression); + +/** + * @brief High-level function for writing data of one frame to a double precision + * data block. If the frame is at the beginning of a frame set the time stamp of + * the frame set is set. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param time is the time stamp of the frame (in seconds). + * @param values is a 1D array of data to add. The array should be of length + * n_particles * n_values_per_frame if writing particle related data, otherwise + * it should be n_values_per_frame. + * @param n_values_per_frame is the number of values to store per frame. If the + * data is particle dependent there will be n_values_per_frame stored per + * particle each frame. + * @param block_id is the ID of the block, of which to set the output interval. + * @param block_name is a string that will be used as name of the block. Only + * required if the block did not exist, i.e. a new block is created. + * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the + * data is not related to specific particles (e.g. box shape) or + * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. + * positions). Only required if the block did not exist, i.e. a new block is + * created. + * @param compression is the compression routine to use when writing the data. + * Only required if the block did not exist, i.e. a new block is created. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code time >= 0 \endcode The time stamp must be >= 0. + * @pre \code values != 0 \endcode The pointer to the values array must not + * be a NULL pointer. + * @details n_values_per_frame, block_name, particle_dependency and + * compression are only used if the data block did not exist before calling + * this function, in which case it is created. + * N.b. Data is written a whole block at a time. The data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_double_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double time, + const double *values, + const int64_t n_values_per_frame, + const int64_t block_id, + const char *block_name, + const char particle_dependency, + const char compression); + +/** + * @brief High-level function for adding data to positions data blocks. If the + * frame is at the beginning of a frame set the time stamp of the frame set + * is set. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param time is the time stamp of the frame (in seconds). + * @param positions is a 1D array of data to add. The array should be of length + * n_particles * 3. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code time >= 0 \endcode The time stamp must be >= 0. + * @pre \code positions != 0 \endcode The pointer to the positions array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_with_time_write() and will + * create a positions data block if none exists. Positions are stored as three + * values per frame and compressed using TNG compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double time, + const float *positions); + +/** + * @brief High-level function for adding data to positions data blocks at double + * precision. If the frame is at the beginning of a frame set the time stamp of + * the frame set is set. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param time is the time stamp of the frame (in seconds). + * @param positions is a 1D array of data to add. The array should be of length + * n_particles * 3. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code time >= 0 \endcode The time stamp must be >= 0. + * @pre \code positions != 0 \endcode The pointer to the positions array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_with_time_double_write() and will + * create a positions data block if none exists. Positions are stored as three + * values per frame and compressed using TNG compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_double_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double time, + const double *positions); + +/** + * @brief High-level function for adding data to velocities data blocks. If the + * frame is at the beginning of a frame set the time stamp of the frame set + * is set. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param time is the time stamp of the frame (in seconds). + * @param velocities is a 1D array of data to add. The array should be of length + * n_particles * 3. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code time >= 0 \endcode The time stamp must be >= 0. + * @pre \code velocities != 0 \endcode The pointer to the velocities array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_with_time_write() and will + * create a velocities data block if none exists. Velocities are stored as three + * values per frame and compressed using TNG compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double time, + const float *velocities); + +/** + * @brief High-level function for adding data to velocities data blocks at + * double precision. If the frame is at the beginning of a frame set the + * time stamp of the frame set is set. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param time is the time stamp of the frame (in seconds). + * @param velocities is a 1D array of data to add. The array should be of length + * n_particles * 3. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code time >= 0 \endcode The time stamp must be >= 0. + * @pre \code velocities != 0 \endcode The pointer to the velocities array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_with_time_double_write() and will + * create a velocities data block if none exists. Velocities are stored as three + * values per frame and compressed using TNG compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_double_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double time, + const double *velocities); + +/** + * @brief High-level function for adding data to forces data blocks. If the + * frame is at the beginning of a frame set the time stamp of the frame set + * is set. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param time is the time stamp of the frame (in seconds). + * @param forces is a 1D array of data to add. The array should be of length + * n_particles * 3. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code time >= 0 \endcode The time stamp must be >= 0. + * @pre \code forces != 0 \endcode The pointer to the forces array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_with_time_write() and will + * create a forces data block if none exists. Forces are stored as three + * values per frame and compressed using gzip compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double time, + const float *forces); + +/** + * @brief High-level function for adding data to forces data blocks at + * double precision. If the frame is at the beginning of a frame set + * the time stamp of the frame set is set. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param time is the time stamp of the frame (in seconds). + * @param forces is a 1D array of data to add. The array should be of length + * n_particles * 3. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code time >= 0 \endcode The time stamp must be >= 0. + * @pre \code forces != 0 \endcode The pointer to the forces array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_with_time_double_write() and will + * create a forces data block if none exists. Forces are stored as three + * values per frame and compressed using gzip compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_double_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double time, + const double *forces); + +/** + * @brief High-level function for adding data to box shape data blocks. If the + * frame is at the beginning of a frame set the time stamp of the frame set + * is set. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param time is the time stamp of the frame (in seconds). + * @param box_shape is a 1D array of data to add. The array should be of length 9. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code time >= 0 \endcode The time stamp must be >= 0. + * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_with_time_write() and will + * create a box shape data block if none exists. Box shapes are stored as 9 + * values per frame and compressed using TNG compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double time, + const float *box_shape); + +/** + * @brief High-level function for adding data to box shape data blocks at + * double precision. If the frame is at the beginning of a frame set the + * time stamp of the frame set is set. + * @param tng_data is the trajectory to use. + * @param frame_nr is the frame number of the data. + * @param time is the time stamp of the frame (in seconds). + * @param box_shape is a 1D array of data to add. The array should be of length 9. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. + * @pre \code time >= 0 \endcode The time stamp must be >= 0. + * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not + * be a NULL pointer. + * @details This function uses tng_util_generic_with_time_double_write() and will + * create a box shape data block if none exists. Box shapes are stored as 9 + * values per frame and compressed using TNG compression. + * N.b. Since compressed data is written a whole block at a time the data is not + * actually written to disk until the frame set is finished or the TNG + * trajectory is closed. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_double_write + (tng_trajectory_t tng_data, + const int64_t frame_nr, + const double time, + const double *box_shape); + +/** + * @brief High-level function for getting the compression method and + * multiplication factor of the last read frame of a specific data block. + * @param tng_data is the trajectory to use. + * @param block_id is the ID number of the block containing the data of + * interest. + * @param codec_id will be set to the value of the codec_id of the + * compression of the data block. See tng_compression for more details. + * @param factor will be set to the multiplication factor applied to + * the values before compression, in order to get integers from them. + * factor is 1/precision. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code codec_id != 0 \endcode The pointer to the returned codec id + * must not be a NULL pointer. + * @pre \code factor != 0 \endcode The pointer to the returned multiplication + * factor must not be a NULL pointer. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_frame_current_compression_get + (tng_trajectory_t tng_data, + const int64_t block_id, + int64_t *codec_id, + double *factor); + +/** @brief High-level function for determining the next frame with data and what + * data blocks have data for that frame. The search can be limited to certain + * data blocks. + * @param tng_data is the trajectory to use. + * @param current_frame is the frame that was last read, from where to start + * looking for data. + * @param n_requested_data_block_ids is the number of data blocks listed in + * requested_data_block_ids. If this is 0 all data blocks will be taken into + * account. + * @param requested_data_block_ids is an array of data blocks to look for. + * @param next_frame will be set to the next frame with data. + * @param n_data_blocks_in_next_frame is set to the number of data blocks with + * data for next_frame. + * @param data_block_ids_in_next_frame is set to an array (of length + * n_data_blocks_in_next_frame) that lists the data block IDs with data for + * next_frame. It must be pointing at NULL or previously allocated memory. + * Memory for the array is allocated by this function. + * The memory must be freed by the client afterwards or + * there will be a memory leak. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code next_frame != 0 \endcode The pointer to the next frame must not + * be NULL. + * @pre \code n_data_blocks_in_next_frame != 0 \endcode The pointer to + * n_data_blocks_in_next_frame must not be NULL. + * @pre \code *data_block_ids_in_next_frame != 0 \endcode The pointer to the + * list of data block IDs must not be NULL. + * @pre \code n_requested_data_block_ids == 0 || requested_data_block_ids != 0 \endcode + * If the number of requested data blocks != 0 then the array of data block IDs must not be NULL. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured or TNG_CRITICAL (2) if a major error + * has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_next_frame_present_data_blocks_find + (tng_trajectory_t tng_data, + int64_t current_frame, + const int64_t n_requested_data_block_ids, + const int64_t *requested_data_block_ids, + int64_t *next_frame, + int64_t *n_data_blocks_in_next_frame, + int64_t **data_block_ids_in_next_frame); + +/* @brief High-level function for getting all data block ids and their names + * and stride lengths. + * @param tng_data is the trajectory to use. + * @param n_data_blocks is set to the number of data blocks in the trajectory. + * @param data_block_ids is set to an array (of length + * n_data_blocks) that lists the data block IDs in the trajectory. + * It must be pointing at NULL or previously allocated memory. + * Memory for the array is allocated by this function. + * The memory must be freed by the client afterwards or + * there will be a memory leak. + * @param data_block_names is set to an array (of length + * n_data_blocks) that contains the names of the data blocks. + * It must be pointing at NULL or previously allocated memory. + * Memory for the array is allocated by this function. + * The memory must be freed by the client afterwards or + * there will be a memory leak. + * @param stride_lengths is set to an array (of length + * n_data_blocks) that lists the stride lengths of the data blocks. + * It must be pointing at NULL or previously allocated memory. + * Memory for the array is allocated by this function. + * The memory must be freed by the client afterwards or + * there will be a memory leak. + * @param n_values_per_frame is set to an array (of length + * n_data_blocks) that lists the number of values per frame of the data blocks. + * It must be pointing at NULL or previously allocated memory. + * Memory for the array is allocated by this function. + * The memory must be freed by the client afterwards or + * there will be a memory leak. + * @param block_types is set to an array (of length + * n_data_blocks) that lists the block types of the data blocks. + * It must be pointing at NULL or previously allocated memory. + * Memory for the array is allocated by this function. + * The memory must be freed by the client afterwards or + * there will be a memory leak. + * @param dependencies is set to an array (of length + * n_data_blocks) that lists the dependencies of the data blocks. + * It must be pointing at NULL or previously allocated memory. + * Memory for the array is allocated by this function. + * The memory must be freed by the client afterwards or + * there will be a memory leak. + * @param compressions is set to an array (of length + * n_data_blocks) that lists the compressions of the data blocks. + * It must be pointing at NULL or previously allocated memory. + * Memory for the array is allocated by this function. + * The memory must be freed by the client afterwards or + * there will be a memory leak. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code n_data_blocks != 0 \endcode The pointer to + * n_data_blocks must not be NULL. + * @pre \code data_block_ids != 0 \endcode The pointer to the + * list of data block IDs must not be NULL. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured or TNG_CRITICAL (2) if a major error + * has occured. + */ +/* +tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_all_data_block_types_get + (tng_trajectory_t tng_data, + int64_t *n_data_blocks, + int64_t **data_block_ids, + char ***data_block_names, + int64_t **stride_lengths, + int64_t **n_values_per_frame, + char **block_types, + char **dependencies, + char **compressions); +*/ + +/** @brief Finds the frame set of the specified frame in order to prepare for writing + * after it. + * @param tng_data is the trajectory to use. + * @param prev_frame is the frame after which to start appending. + * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) + * must be initialised before using it. + * @pre \code prev_frame >= 0 \endcode The previous frame must not be negative. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occured (such as not finding the requested frame) or TNG_CRITICAL (2) + * if a major error has occured. + */ +tng_function_status DECLSPECDLLEXPORT tng_util_prepare_append_after_frame + (tng_trajectory_t tng_data, + const int64_t prev_frame); + +/** @} */ /* end of group2 */ + + +#ifdef __cplusplus +} /* end extern "C" */ +#endif + +#endif /* TNG_IO_H */ diff --git a/include/tng/tng_io.hpp b/include/tng/tng_io.hpp new file mode 100644 index 0000000..12172e5 --- /dev/null +++ b/include/tng/tng_io.hpp @@ -0,0 +1,1703 @@ +/* This code is part of the tng binary trajectory format. + * + * Written by Anders Gärdenäs + * Copyright (c) 2012-2013, The GROMACS development team. + * Check out http://www.gromacs.org for more information. + * + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the Revised BSD License. + */ + +#ifndef TNG_IO_HPP +#define TNG_IO_HPP + +#include "tng_io.h" + +namespace Tng +{ +class Trajectory; +class Atom; +class Residue; +class Chain; +class Molecule; +typedef class Molecule * Molecule_t; + + +class Trajectory { +private: + tng_trajectory_t traj; + tng_function_status status; +public: + /** + * @brief Add a molecule to the trajectory. + * @param name is a pointer to the string containing the name of the new molecule. + * @param molecule is a pointer to the newly created molecule. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + + tng_function_status addMolecule(const char *, Molecule_t); + tng_function_status addMoleculeWithId(const char *, int64_t id, Molecule_t); + tng_function_status findMolecule(const char *name, int64_t id, Molecule_t molecule); + friend class Atom; + friend class Residue; + friend class Chain; + friend class Molecule; + + //! Normal constructor + Trajectory() + { status = tng_trajectory_init(&traj); } + + //! Copy constructor + Trajectory(Trajectory * src) + { status = tng_trajectory_init_from_src(traj,&src->traj); } + + //! Detructor + ~Trajectory() + { status = tng_trajectory_destroy(&traj); } + + //! Status + tng_function_status getStatus() + { return status; } + + + /** + * @brief Get the name of the input file. + * @param file_name the string to fill with the name of the input file, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for file_name. This includes \0 terminating character. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ + tng_function_status getInputFile (char *file_name, const int max_len) + { + return status = tng_input_file_get(traj, file_name, max_len); + } + + /** + * @brief Set the name of the input file. + * @param file_name the name of the input file. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setInputFile(const char *file_name) + { + return status = tng_input_file_set(traj, file_name); + } + + + /** + * @brief Get the name of the output file. + * @param file_name the string to fill with the name of the output file, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for file_name. This includes \0 terminating character. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ + tng_function_status getOutputFile(char *file_name, const int max_len) + { + return status = tng_output_file_get(traj, file_name, max_len); + } + + + /** + * @brief Set the name of the output file. + * @param file_name the name of the output file. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setOutputFile(const char *file_name) + { + return status = tng_output_file_set(traj, file_name); + } + + /** + * @brief Get the endianness of the output file. + * current output file. + * @param endianness will contain the enumeration of the endianness. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness + * could not be retrieved. + */ + tng_function_status getOutputFileEndianness + (tng_file_endianness *endianness) + { + return status = tng_output_file_endianness_get(traj, endianness); + } + + /** + * @brief Set the endianness of the output file. + * @param endianness the enumeration of the endianness, can be either + * TNG_BIG_ENDIAN (0) or TNG_LITTLE_ENDIAN (1). + * @details The endianness cannot be changed after file output has started. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness + * could not be set. + */ + tng_function_status setOutputFileEndianness + (const tng_file_endianness endianness) + { + return status = tng_output_file_endianness_set(traj, endianness); + } + + /** + * @brief Get the name of the program used when creating the trajectory. + * @param name the string to fill with the name of the program, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ + tng_function_status getFirstProgramName(char *name, const int max_len) + { + return status = tng_first_program_name_get(traj,name,max_len); + } + + + /** + * @brief Set the name of the program used when creating the trajectory.. + * @param new_name is a string containing the wanted name. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setFirstProgramName(const char *new_name) + { + return status = tng_first_program_name_set(traj, new_name); + } + + + /** + * @brief Get the name of the program used when last modifying the trajectory. + * @param name the string to fill with the name of the program, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ + tng_function_status getLastProgramName(char *name, const int max_len) + { + return status = tng_last_program_name_get(traj, name, max_len); + } + + + /** + * @brief Set the name of the program used when last modifying the trajectory. + * @param new_name is a string containing the wanted name. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setLastProgramName(const char *new_name) + { + return status = tng_last_program_name_set(traj, new_name); + } + + + /** + * @brief Get the name of the user who created the trajectory. + * @param name the string to fill with the name of the user, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ + tng_function_status getFirstUserName(char *name, const int max_len) + { + return status = tng_first_user_name_get(traj,name, max_len); + } + + + /** + * @brief Set the name of the user who created the trajectory. + * @param new_name is a string containing the wanted name. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setFirstUserName(const char *new_name) + { + return status = tng_first_user_name_set(traj, new_name); + } + + + /** + * @brief Get the name of the user who last modified the trajectory. + * @param name the string to fill with the name of the user, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ + tng_function_status getLastUserName(char *name, const int max_len) + { + return status = tng_last_user_name_get(traj,name,max_len); + } + + + /** + * @brief Set the name of the user who last modified the trajectory. + * @param new_name is a string containing the wanted name. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setLastUserName(const char *new_name) + { + return status = tng_last_user_name_set(traj,new_name); + } + + + + /** + * @brief Get the name of the computer used when creating the trajectory. + * @param name the string to fill with the name of the computer, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ + tng_function_status getFirstComputerName(char *name, const int max_len) + { + return status = tng_first_computer_name_get(traj, name, max_len); + } + + + /** + * @brief Set the name of the computer used when creating the trajectory. + * @param new_name is a string containing the wanted name. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setFirstComputerName(const char *new_name) + { + return status = tng_first_computer_name_set(traj, new_name); + } + + + /** + * @brief Get the name of the computer used when last modifying the trajectory. + * @param name the string to fill with the name of the computer, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ + tng_function_status getLastComputerName(char *name, const int max_len) + { + return status = tng_last_computer_name_get(traj,name,max_len); + } + + + /** + * @brief Set the name of the computer used when last modifying the trajectory. + * @param new_name is a string containing the wanted name. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setLastComputerName(const char *new_name) + { + return status = tng_last_computer_name_set(traj,new_name); + } + + + /** + * @brief Get the pgp_signature of the user creating the trajectory. + * @param signature the string to fill with the signature, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ + tng_function_status getFirstSignature(char *signature, const int max_len) + { + return status = tng_last_computer_name_get(traj, signature,max_len); + } + + + /** + * @brief Set the pgp_signature of the user creating the trajectory. + * @param signature is a string containing the pgp_signature. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setFirstSignature(const char *signature) + { + return status = tng_first_signature_set(traj, signature); + } + + + /** + * @brief Get the pgp_signature of the user last modifying the trajectory. + * @param signature the string to fill with the signature, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ + tng_function_status getLastSignature(char *signature, const int max_len) + { + return status = tng_first_signature_get(traj, signature, max_len); + } + + + /** + * @brief Set the pgp_signature of the user last modifying the trajectory. + * @param signature is a string containing the pgp_signature. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setLastSignature(const char *signature) + { + return status = tng_last_signature_set(traj, signature); + } + + + /** + * @brief Get the name of the forcefield used in the trajectory. + * @param name the string to fill with the name of the forcefield, + * memory must be allocated before. + * @param max_len maximum char length of the string, i.e. how much memory has + * been reserved for name. This includes \0 terminating character. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (source string longer than destination string). + */ + tng_function_status getForcefieldName(char *name, const int max_len) + { + return status = tng_last_signature_get(traj,name,max_len); + } + + + /** + * @brief Set the name of the forcefield used in the trajectory. + * @param new_name is a string containing the wanted name. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setForcefieldName(const char *new_name) + { + return status = tng_forcefield_name_set(traj, new_name); + } + + + /** + * @brief Get the medium stride length of the trajectory. + * @param len is pointing to a value set to the stride length. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status getMediumStrideLength(int64_t *len) + { + return status = tng_medium_stride_length_get(traj,len); + } + + + /** + * @brief Set the medium stride length of the trajectory. + * @param len is the wanted medium stride length. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred. + */ + tng_function_status setMediumStrideLength(const int64_t len) + { + return status = tng_medium_stride_length_set(traj,len); + } + + + /** + * @brief Get the long stride length of the trajectory. + * @param len is pointing to a value set to the stride length. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status getLongStrideLength(int64_t *len) + { + return status = tng_long_stride_length_get(traj, len); + } + + + /** + * @brief Set the long stride length of the trajectory. + * @param len is the wanted long stride length. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred. + */ + tng_function_status setLongStrideLength(const int64_t len) + { + return status = tng_long_stride_length_set(traj,len); + } + + + /** + * @brief Get the current time per frame of the trajectory. + * @param len is pointing to a value set to the time per frame. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status getTimePerFrame(double *time) + { + return status = tng_time_per_frame_get(traj, time); + } + + + /** + * @brief Set the time per frame of the trajectory. + * @param len is the new time per frame. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred. + */ + tng_function_status setTimePerFrame(const double time) + { + return status = tng_time_per_frame_set(traj, time); + } + + + /** + * @brief Get the length of the input file. + * @param len is pointing to a value set to the file length. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status getInputFileLen(int64_t *len) + { + return status = tng_input_file_len_get(traj, len); + } + + + /** + * @brief Get the number of frames in the trajectory + * @param n is pointing to a value set to the number of frames. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred (could not find last frame set). + */ + tng_function_status getNumFrames(int64_t *n) + { + return status = tng_num_frames_get(traj, n); + } + + /** + * @brief Get the current number of particles. + * @param n is pointing to a value set to the number of particles. + * @details If variable number of particles are used this function will return + * the number of particles in the current frame set. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status getNumParticles(int64_t *n) + { + return status = tng_num_particles_get(traj, n); + } + + + + + /** + * @brief Get the current total number of molecules. + * @param n is pointing to a value set to the number of molecules. + * @details If variable number of particles are used this function will return + * the total number of molecules in the current frame set. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status getNumMolecules(int64_t *n) + { + return status = tng_num_molecules_get(traj,n); + } + + /** + * @brief Get the exponential used for distances in the trajectory. + * @param exp is pointing to a value set to the distance unit exponential. + * @details Example: If the distances are specified in nm (default) exp is -9. + * If the distances are specified in Å exp is -10. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status getDistanceUnitExponential + (int64_t *exp) + { + return status = tng_distance_unit_exponential_get(traj, exp); + } + + /** + * @brief Set the exponential used for distances in the trajectory. + * @param exp is the distance unit exponential to use. + * @details Example: If the distances are specified in nm (default) exp is -9. + * If the distances are specified in Å exp is -10. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status setDistanceUnitExponential + (int64_t exp) + { + return status = tng_distance_unit_exponential_set(traj, exp); + } + + + /** + * @brief Get the number of frames per frame set. + * per frame set. + * @param n is pointing to a value set to the number of frames per frame set. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status getNumFramesPerFrameSet(int64_t *n) + { + return status = tng_num_frames_per_frame_set_get(traj,n); + } + + /** + * @brief Set the number of frames per frame set. + * @param n is the number of frames per frame set. + * @details This does not affect already existing frame sets. For + * consistency the number of frames per frame set should be set + * betfore creating any frame sets. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status setNumFramesPerFrameSet(const int64_t n) + { + return status = tng_num_frames_per_frame_set_set(traj,n); + } + + /** + * @brief Get the number of frame sets. + * @param n is pointing to a value set to the number of frame sets. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status getNumFrameSets(int64_t *n) + { + return status = tng_num_frame_sets_get(traj, n); + } + + + /** + * @brief Get the current trajectory frame set. + * @param frame_set_p will be set to point at the memory position of + * the found frame set. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status getCurrentFrameSet(tng_trajectory_frame_set_t *frame_set_p) + { + return status = tng_current_frame_set_get(traj, frame_set_p); + } + + + /** + * @brief Find the requested frame set number. + * @param nr is the frame set number to search for. + * @details tng_data->current_trajectory_frame_set will contain the + * found trajectory if successful. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status findFrameSetNr(const int64_t nr) + { + return status = tng_frame_set_nr_find(traj,nr); + } + + + /** + * @brief Find the frame set containing a specific frame. + * @param frame is the frame number to search for. + * @details tng_data->current_trajectory_frame_set will contain the + * found trajectory if successful. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status findFrameSetOfFrame(const int64_t frame) + { + return status = tng_frame_set_of_frame_find(traj, frame); + } + + + /** + * @brief Get the file position of the next frame set in the input file. + * @param frame_set is the frame set of which to get the position of the + * following frame set. + * @param pos is pointing to a value set to the file position. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status getNextFrameSetFilePos + (const tng_trajectory_frame_set_t frame_set,int64_t *pos) + { + return status = tng_frame_set_next_frame_set_file_pos_get(traj,frame_set,pos ); + } + + /** + * @brief Get the file position of the previous frame set in the input file. + * @param frame_set is the frame set of which to get the position of the + * previous frame set. + * @param pos is pointing to a value set to the file position. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status getPrevFrameSetFilePos + (const tng_trajectory_frame_set_t frame_set,int64_t *pos) + { + return status = tng_frame_set_prev_frame_set_file_pos_get(traj, frame_set, pos); + } + + + /** + * @brief Get the first and last frames of the frame set. + * @param frame_set is the frame set of which to get the frame range. + * @param first_frame is set to the first frame of the frame set. + * @param last_frame is set to the last frame of the frame set. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status getFrameSetFrameRange + (const tng_trajectory_frame_set_t frame_set, + int64_t *first_frame, + int64_t *last_frame) + { + return status = tng_frame_set_frame_range_get(traj,frame_set, first_frame, last_frame); + } + + + /** + * @brief Get the molecume name of real particle number (number in mol system). + * @param nr is the real number of the particle in the molecular system. + * @param name is a string, which is set to the name of the molecule. Memory + * must be reserved beforehand. + * @param max_len is the maximum length of name. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error + * has occured. + */ + tng_function_status getMoleculeNameOfParticleNr + (const int64_t nr,char *name,int max_len) + { + return status = tng_molecule_name_of_particle_nr_get(traj,nr,name,max_len); + } + + + /** + * @brief Get the chain name of real particle number (number in mol system). + * @param nr is the real number of the particle in the molecular system. + * @param name is a string, which is set to the name of the chain. Memory + * must be reserved beforehand. + * @param max_len is the maximum length of name. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error + * has occured. + */ + tng_function_status getChainNameOfParticleNr + (const int64_t nr,char *name,int max_len) + { + return status = tng_chain_name_of_particle_nr_get(traj, nr, name, max_len); + } + + + /** + * @brief Get the residue name of real particle number (number in mol system). + * @param nr is the real number of the particle in the molecular system. + * @param name is a string, which is set to the name of the residue. Memory + * must be reserved beforehand. + * @param max_len is the maximum length of name. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error + * has occured. + */ + tng_function_status getResidueNameOfParticleNr + (const int64_t nr,char *name,int max_len) + { + return status = tng_residue_name_of_particle_nr_get(traj,nr,name,max_len); + } + + + /** + * @brief Get the atom name of real particle number (number in mol system). + * @param nr is the real number of the particle in the molecular system. + * @param name is a string, which is set to the name of the atom. Memory + * must be reserved beforehand. + * @param max_len is the maximum length of name. + * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error + * has occured. + */ + tng_function_status getAtomNameOfParticleNr + (const int64_t nr,char *name,int max_len) + { + return status = tng_atom_name_of_particle_nr_get(traj, nr,name,max_len); + } + + + /** + * @brief Add a particle mapping table. + * @details Each particle mapping table will be written as a separate block, + * followed by the data blocks for the corresponding particles. In most cases + * there is one particle mapping block for each thread writing the trajectory. + * @details The mapping information is added to the currently active frame set + * of tng_data + * @param first_particle_number is the first particle number of this mapping + * block. + * @param n_particles is the number of particles in this mapping block. + * @param mapping_table is a list of the real particle numbers (i.e. the numbers + * used in the molecular system). The list is n_particles long. + * @details mapping_table[0] is the real particle number of the first particle + * in the following data blocks. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status addParticleMapping + (const int64_t first_particle_number, + const int64_t n_particles, + const int64_t *mapping_table) + { + return status = tng_particle_mapping_add(traj,first_particle_number,n_particles,mapping_table ); + } + + + /** + * @brief Read the header blocks from the input_file of tng_data. + * @details The trajectory blocks must be read separately and iteratively in chunks + * to fit in memory. + * @details tng_data->input_file_path specifies + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status readFileHeaders(const tng_hash_mode hash_mode) + { + return status = tng_file_headers_read(traj, hash_mode); + } + + + /** + * @brief Write the header blocks to the output_file of tng_data. + * @details The trajectory blocks must be written separately and iteratively in chunks + * to fit in memory. + * @details tng_data->output_file_path + * specifies which file to write to. If the file (output_file) is not open it + * will be opened. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status writeFileHeaders(const tng_hash_mode hash_mode) + { + return status = tng_file_headers_write(traj, hash_mode); + } + + + + /** + * @brief Read one (the next) block (of any kind) from the input_file of tng_data. + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param block_data is a pointer to the struct which will be populated with the + * data. + * @details If block_data->input_file_pos > 0 it is the position from where the + * reading starts otherwise it starts from the current position. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status readNextBlock(const tng_hash_mode hash_mode, tng_gen_block_t block_data) + { + return status = tng_block_read_next(traj,block_data, hash_mode); + } + + + + /** + * @brief Read one (the next) frame set, including mapping and related data blocks + * from the input_file of tng_data. + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status readNextFrameSet(const tng_hash_mode hash_mode) + { + return status = tng_frame_set_read_next(traj, hash_mode); + } + + + /** + * @brief Write one frame set, including mapping and related data blocks + * to the output_file of tng_data. + * @details tng_data->output_file_path specifies + * which file to write to. If the file (output_file) is not open it will be + * opened. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status writeFrameSet(const tng_hash_mode hash_mode) + { + return status = tng_frame_set_write(traj, hash_mode); + } + + + /** + * @brief Create and initialise a frame set. + * @param first_frame is the first frame of the frame set. + * @param n_frames is the number of frames in the frame set. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status newFrameSet(const int64_t first_frame, + const int64_t n_frames) + { + return status = tng_frame_set_new(traj, first_frame, n_frames); + } + + + /** + * @brief Create and initialise a frame set with the time of the first frame + * specified. + * @param first_frame is the first frame of the frame set. + * @param n_frames is the number of frames in the frame set. + * @param first_frame_time is the time stamp of the first frame (in seconds). + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status newFrameSetWithTime + (const int64_t first_frame, + const int64_t n_frames, + const double first_frame_time) + { + return status = tng_frame_set_with_time_new(traj, + first_frame, n_frames, + first_frame_time); + } + + + /** + * @brief Set the time stamp of the first frame of the current frame set. + * @param first_frame_time is the time stamp of the first frame in the + * frame set. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status setTimeOfFirstFrameOfFrameSet + (const double first_frame_time) + { + return status = tng_frame_set_first_frame_time_set(traj, + first_frame_time); + } + + /** + * @brief Add a non-particle dependent data block. + * @param id is the block ID of the block to add. + * @param block_name is a descriptive name of the block to add + * @param datatype is the datatype of the data in the block (e.g. int/float) + * @param block_type_flag indicates if this is a non-trajectory block (added + * directly to tng_data) or if it is a trajectory block (added to the + * frame set) + * @param n_frames is the number of frames of the data block (automatically + * set to 1 if adding a non-trajectory data block) + * @param n_values_per_frame is how many values a stored each frame (e.g. 9 + * for a box shape block) + * @param stride_length is how many frames are between each entry in the + * data block + * @param codec_id is the ID of the codec to compress the data. + * @param new_data is an array of data values to add. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status addDataBlock(const int64_t id, + const char *block_name, + const tng_data_type datatype, + const tng_block_type block_type_flag, + int64_t n_frames, + const int64_t n_values_per_frame, + const int64_t stride_length, + const int64_t codec_id, + void *new_data) + { + return status = tng_data_block_add(traj, id,block_name, + datatype,block_type_flag, n_frames, + n_values_per_frame, stride_length, + codec_id, new_data); + } + + + /** + * @brief Add a particle dependent data block. + * @param id is the block ID of the block to add. + * @param block_name is a descriptive name of the block to add + * @param datatype is the datatype of the data in the block (e.g. int/float) + * @param block_type_flag indicates if this is a non-trajectory block (added + * directly to tng_data) or if it is a trajectory block (added to the + * frame set) + * @param n_frames is the number of frames of the data block (automatically + * set to 1 if adding a non-trajectory data block) + * @param n_values_per_frame is how many values a stored each frame (e.g. 9 + * for a box shape block) + * @param stride_length is how many frames are between each entry in the + * data block + * @param first_particle_number is the number of the first particle stored + * in this data block + * @param n_particles is the number of particles stored in this data block + * @param codec_id is the ID of the codec to compress the data. + * @param new_data is an array of data values to add. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status addParticleDataBlock(const int64_t id, + const char *block_name, + const tng_data_type datatype, + const tng_block_type block_type_flag, + int64_t n_frames, + const int64_t n_values_per_frame, + const int64_t stride_length, + const int64_t first_particle_number, + const int64_t n_particles, + const int64_t codec_id, + void *new_data) + { + return status = tng_particle_data_block_add(traj,id, block_name, + datatype, block_type_flag, n_frames,n_values_per_frame, + stride_length,first_particle_number,n_particles, + codec_id, new_data); + } + + + /** + * @brief Write data of one trajectory frame to the output_file of tng_data. + * @param frame_nr is the index number of the frame to write. + * @param block_id is the ID of the data block to write the data to. + * @param data is an array of data to write. The length of the array should + * equal n_values_per_frame. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status writeFrameData(const int64_t frame_nr, + const int64_t block_id, + const void *data, + const tng_hash_mode hash_mode) + { + return status = tng_frame_data_write(traj,frame_nr,block_id,data,hash_mode); + } + + + /** + * @brief Write particle data of one trajectory frame to the output_file of + * tng_data. + * @param frame_nr is the index number of the frame to write. + * @param block_id is the ID of the data block to write the data to. + * @param val_first_particle is the number of the first particle in the data + * array. + * @param val_n_particles is the number of particles in the data array. + * @param data is a 1D-array of data to write. The length of the array should + * equal n_particles * n_values_per_frame. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status writeFrameParticleData(const int64_t frame_nr, + const int64_t block_id, + const int64_t val_first_particle, + const int64_t val_n_particles, + const void *data, + const tng_hash_mode hash_mode) + { + return status = tng_frame_particle_data_write(traj,frame_nr,block_id,val_first_particle,val_n_particles,data,hash_mode); + } + + + /** + * @brief Free data is an array of values (2D). + * @param values is the 2D array to free and will be set to 0 afterwards. + * @param n_frames is the number of frames in the data array. + * @param n_values_per_frame is the number of values per frame in the data array. + * @param type is the data type of the data in the array (e.g. int/float/char). + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status freeDataValues(union data_values **values, + const int64_t n_frames, + const int64_t n_values_per_frame, + const tng_data_type type) + { + return status = tng_data_values_free(traj, values, n_frames,n_values_per_frame,type); + } + + + /** + * @brief Free data is an array of values (3D). + * @param values is the array to free and will be set to 0 afterwards. + * @param n_frames is the number of frames in the data array. + * @param n_particles is the number of particles in the data array. + * @param n_values_per_frame is the number of values per frame in the data array. + * @param type is the data type of the data in the array (e.g. int/float/char). + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status freeParticleDataValues(union data_values ***values, + const int64_t n_frames, + const int64_t n_particles, + const int64_t n_values_per_frame, + const tng_data_type type) + { + return status = tng_particle_data_values_free(traj, values,n_frames,n_particles,n_values_per_frame,type); + } + + + /** + * @brief Retrieve non-particle data, from the last read frame set. Obsolete! + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param block_id is the id number of the particle data block to read. + * @param values is a pointer to a 2-dimensional array (memory unallocated), which + * will be filled with data. The array will be sized + * (n_frames * n_values_per_frame). + * Since ***values is allocated in this function it is the callers + * responsibility to free the memory. + * @param n_frames is set to the number of particles in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status getData(const int64_t block_id, + union data_values ***values, + int64_t *n_frames, + int64_t *n_values_per_frame, + char *type) + { + return status = tng_data_get(traj, block_id, values, n_frames, + n_values_per_frame, type); + } + + /** + * @brief Retrieve a vector (1D array) of non-particle data, from the last read frame set. + * @param block_id is the id number of the particle data block to read. + * @param values is a pointer to a 1-dimensional array (memory unallocated), which + * will be filled with data. The length of the array will be (n_frames * n_values_per_frame). + * Since **values is allocated in this function it is the callers + * responsibility to free the memory. + * @param n_frames is set to the number of particles in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param stride_length is set to the stride length of the returned data. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @details This does only work for numerical (int, float, double) data. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status getDataVector + (const int64_t block_id, + void **values, + int64_t *n_frames, + int64_t *stride_length, + int64_t *n_values_per_frame, + char *type) + { + return status = tng_data_vector_get(traj, block_id, values, n_frames, + stride_length, n_values_per_frame, + type); + } + + /** + * @brief Read and retrieve non-particle data, in a specific interval. Obsolete! + * which file to read from. If the file (input_file) is not open it will be + * opened. + * @param block_id is the id number of the particle data block to read. + * @param start_frame_nr is the index number of the first frame to read. + * @param end_frame_nr is the index number of the last frame to read. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @param values is a pointer to a 2-dimensional array (memory unallocated), which + * will be filled with data. The array will be sized + * (n_frames * n_values_per_frame). + * Since ***values is allocated in this function it is the callers + * responsibility to free the memory. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status getDataInterval(const int64_t block_id, + const int64_t start_frame_nr, + const int64_t end_frame_nr, + const tng_hash_mode hash_mode, + union data_values ***values, + int64_t *n_values_per_frame, + char *type) + { + return status = tng_data_interval_get(traj, block_id, start_frame_nr, + end_frame_nr, hash_mode, values, + n_values_per_frame, type); + } + + + /** + * @brief Read and retrieve a vector (1D array) of non-particle data, + * in a specific interval. + * @param block_id is the id number of the particle data block to read. + * @param start_frame_nr is the index number of the first frame to read. + * @param end_frame_nr is the index number of the last frame to read. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @param values is a pointer to a 1-dimensional array (memory unallocated), which + * will be filled with data. The length of the array will be (n_frames * n_values_per_frame). + * Since **values is allocated in this function it is the callers + * responsibility to free the memory. + * @param stride_length is set to the stride length (writing frequency) of + * the data. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @details This does only work for numerical (int, float, double) data. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status getDataVectorInterval + (const int64_t block_id, + const int64_t start_frame_nr, + const int64_t end_frame_nr, + const char hash_mode, + void **values, + int64_t *stride_length, + int64_t *n_values_per_frame, + char *type) + { + return status = tng_data_vector_interval_get(traj, block_id, + start_frame_nr, + end_frame_nr, + hash_mode, values, + stride_length, + n_values_per_frame, + type); + } + + /** + * @brief Retrieve particle data, from the last read frame set. Obsolete! + * @details The particle dimension of the returned values array is translated + * to real particle numbering, i.e. the numbering of the actual molecular + * system. + * specifies which file to read from. If the file (input_file) is not open it + * will be opened. + * @param block_id is the id number of the particle data block to read. + * @param values is a pointer to a 3-dimensional array (memory unallocated), which + * will be filled with data. The array will be sized + * (n_frames * n_particles * n_values_per_frame). + * Since ****values is allocated in this function it is the callers + * responsibility to free the memory. + * @param n_frames is set to the number of particles in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param n_particles is set to the number of particles in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status getParticleData(const int64_t block_id, + union data_values ****values, + int64_t *n_frames, + int64_t *n_particles, + int64_t *n_values_per_frame, + char *type) + { + return status = (tng_particle_data_get(traj, block_id, values, n_frames, + n_particles, n_values_per_frame, type)); + } + + + /** + * @brief Retrieve a vector (1D array) of particle data, from the last read frame set. + * @details The particle dimension of the returned values array is translated + * to real particle numbering, i.e. the numbering of the actual molecular + * system. + * @param block_id is the id number of the particle data block to read. + * @param values is a pointer to a 1-dimensional array (memory unallocated), which + * will be filled with data. The length of the array will be + * (n_frames * n_particles * n_values_per_frame). + * Since **values is allocated in this function it is the callers + * responsibility to free the memory. + * @param n_frames is set to the number of frames in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param stride_length is set to the stride length of the returned data. + * @param n_particles is set to the number of particles in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @details This does only work for numerical (int, float, double) data. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status getParticleDataVector + (const int64_t block_id, + void **values, + int64_t *n_frames, + int64_t *stride_length, + int64_t *n_particles, + int64_t *n_values_per_frame, + char *type) + { + return status = tng_particle_data_vector_get(traj, block_id, + values, n_frames, + stride_length, + n_particles, + n_values_per_frame, type); + } + + + /** + * @brief Read and retrieve particle data, in a specific interval. Obsolete! + * @details The particle dimension of the returned values array is translated + * to real particle numbering, i.e. the numbering of the actual molecular + * system. + * @param block_id is the id number of the particle data block to read. + * @param start_frame_nr is the index number of the first frame to read. + * @param end_frame_nr is the index number of the last frame to read. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @param values is a pointer to a 3-dimensional array (memory unallocated), which + * will be filled with data. The array will be sized + * (n_frames * n_particles * n_values_per_frame). + * Since ****values is allocated in this function it is the callers + * responsibility to free the memory. + * @param n_particles is set to the number of particles in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status getParticleDataInterval(const int64_t block_id, + const int64_t start_frame_nr, + const int64_t end_frame_nr, + const tng_hash_mode hash_mode, + union data_values ****values, + int64_t *n_particles, + int64_t *n_values_per_frame, + char *type) + { + return status = (tng_particle_data_interval_get(traj, block_id, start_frame_nr, + end_frame_nr, hash_mode, values, + n_particles, n_values_per_frame, + type)); + } + + + /** + * @brief Read and retrieve a vector (1D array) particle data, in a + * specific interval. + * @details The particle dimension of the returned values array is translated + * to real particle numbering, i.e. the numbering of the actual molecular + * system. + * @param block_id is the id number of the particle data block to read. + * @param start_frame_nr is the index number of the first frame to read. + * @param end_frame_nr is the index number of the last frame to read. + * @param hash_mode is an option to decide whether to use the md5 hash or not. + * If hash_mode == TNG_USE_HASH the md5 hash in the file will be + * compared to the md5 hash of the read contents to ensure valid data. + * @param values is a pointer to a 1-dimensional array (memory unallocated), which + * will be filled with data. The length of the array will be + * (n_frames * n_particles * n_values_per_frame). + * Since **values is allocated in this function it is the callers + * responsibility to free the memory. + * @param stride_length is set to the stride length (writing frequency) of + * the data. + * @param n_particles is set to the number of particles in the returned data. This is + * needed to properly reach and/or free the data afterwards. + * @param n_values_per_frame is set to the number of values per frame in the data. + * This is needed to properly reach and/or free the data afterwards. + * @param type is set to the data type of the data in the array. + * @details This does only work for numerical (int, float, double) data. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status getParticleDataVectorInterval + (const int64_t block_id, + const int64_t start_frame_nr, + const int64_t end_frame_nr, + const tng_hash_mode hash_mode, + void **values, + int64_t *n_particles, + int64_t *stride_length, + int64_t *n_values_per_frame, + char *type) + { + return status = tng_particle_data_vector_interval_get(traj, block_id, + start_frame_nr, + end_frame_nr, + hash_mode, + values, + n_particles, + stride_length, + n_values_per_frame, + type); + } + + + /** @brief Get the date and time of initial file creation in ISO format (string). + * @param time is a pointer to the string in which the date will be stored. Memory + must be reserved beforehand. + * @return TNG_SUCCESS (0) if successful. + */ + tng_function_status getTimeStr(char *time) + { + return status = tng_time_get_str(traj, time); + } + + +}; + + + + + +class Molecule +{ +private: + + tng_molecule_t mol; + Trajectory * traj; + tng_function_status status; +public: + tng_function_status addChain(const char *name, Chain *chain); + tng_function_status findChain(const char *name, int64_t id, Chain *chain); + friend class Trajectory; + //Constructor + Molecule(Trajectory * trajectory) + { + traj = trajectory; + + //status = tng_molecule_init(traj->traj,mol); + } + /** + *@Dose nothing, use ~TngMolecule() + */ + ~Molecule() + { + status = tng_molecule_destroy(traj->traj,mol); + } + //! Status + tng_function_status getStatus() + { return status; } + + + /** + * @brief Set the name of a molecule. + * @param new_name is a string containing the wanted name. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setName(const char *new_name) + { + return status = tng_molecule_name_set(traj->traj,mol,new_name); + } + + /** + * @brief Get the count of a molecule. + * @param cnt is a pointer to the variable to be populated with the count. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status getCnt(int64_t *cnt) + { + return status = tng_molecule_cnt_get(traj->traj,mol,cnt); + } + + /** + * @brief Set the count of a molecule. + * @param cnt is the number of instances of this molecule. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error + * has occurred or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status setCnt(int64_t cnt) + { + return status = tng_molecule_cnt_set(traj->traj,mol,cnt); + } + +}; + + tng_function_status Trajectory::addMolecule(const char *name, Molecule_t molecule) +{ + return status = tng_molecule_add(traj,name, &molecule->mol); +} + + tng_function_status Trajectory::addMoleculeWithId + (const char *name, + const int64_t id, + Molecule_t molecule) +{ + return status = tng_molecule_w_id_add(traj, name, id, &molecule->mol); +} + +/** +* @brief Find a molecule. +* @param tng_data is the trajectory data container containing the molecule. +* @param name is a string containing the name of the molecule. If name is empty +* only id will be used for finding the molecule. +* @param id is the id of the molecule to look for. If id is -1 only the name of +* the molecule will be used for finding the molecule. +* @param molecule is a pointer to the molecule if it was found - otherwise 0. +* @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the +* molecule is not found. +* @details If name is an empty string and id is -1 the first molecule will be +* found. +*/ +tng_function_status Trajectory::findMolecule + (const char *name, + int64_t id, + Molecule_t molecule) +{ + return status = tng_molecule_find(traj, name, id, + &molecule->mol); +} + + +class Atom +{ +private: + tng_atom_t atom; + Trajectory * traj; + tng_function_status status; +public: + friend class Residue; + //constructor + Atom(Trajectory * trajectory) + { + traj = trajectory; + } + //deonstructor + /** + *@Dose nothing, use ~TngMolecule() + */ + ~Atom() + { + //delete atom; + } + //! Status + tng_function_status getStatus() + { return status; } + /** + * @brief Set the name of an atom. + * @param new_name is a string containing the wanted name. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setName(const char *new_name) + { + return status = tng_atom_name_set(traj->traj, atom , new_name); + } + + /** + * @param new_type is a string containing the atom type. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setType(const char *new_type) + { + return status = tng_atom_type_set(traj->traj, atom, new_type); + } +}; + +class Residue +{ + private: + tng_residue_t residue; + Trajectory * traj; + tng_function_status status; +public: + friend class Chain; + //constructor + Residue(Trajectory * trajectory) + { + traj = trajectory; + } + //deonstructor + /** + *@Dose nothing, use ~TngMolecule() + */ + ~Residue() + { + //delete residue; + } + //! Status + tng_function_status getStatus() + { return status; } + /** + * @brief Set the name of a residue. + * @param residue is the residue to rename. + * @param new_name is a string containing the wanted name. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setName(const char *new_name) + { + return status = tng_residue_name_set(traj->traj, residue,new_name); + } + + /** + * @brief Add an atom to a residue. + * @param atom_name is a string containing the name of the atom. + * @param atom_type is a string containing the atom type of the atom. + * @param atom is a pointer to the newly created atom. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status addAtom(const char *atom_name, + const char *atom_type, + Atom * atom) + { + return status = tng_residue_atom_add(traj->traj, residue, atom_name, + atom_type, &atom->atom); + } + + + /** + * @brief Add an atom with a specific ID to a residue. + * @param atom_name is a string containing the name of the atom. + * @param atom_type is a string containing the atom type of the atom. + * @param id is the ID of the created atom. + * @param atom is a pointer to the newly created atom. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could + * not be set properly or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status addAtomWithId + (const char *atom_name, + const char *atom_type, + const int64_t id, + Atom * atom) + { + return status = tng_residue_atom_w_id_add(traj->traj, residue, + atom_name, atom_type, + id, &atom->atom); + } + +}; + +class Chain +{ + private: + tng_chain_t chain; + Trajectory * traj; + tng_function_status status; +public: + friend class Molecule; + //constructor + Chain(Trajectory * trajectory) + { + traj = trajectory; + } + //deonstructor + /** + *@Dose nothing, use ~TngMolecule() + */ + ~Chain() + { + //delete chain; + } + //! Status + tng_function_status getStatus() + { return status; } + /** + * @brief Set the name of a chain. + * @param new_name is a string containing the wanted name. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status setName(const char *new_name) + { + return status = tng_chain_name_set(traj->traj, chain, new_name); + } + + + /** + * @brief Find a residue in a chain. + * @param name is a string containing the name of the residue. + * @param id is the id of the residue to find. If id == -1 the first residue + * that matches the specified name will be found. + * @param residue is a pointer to the residue if it was found - otherwise 0. + * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the + * residue is not found. + * @details If name is an empty string the first residue will be found. + */ + tng_function_status findResidue + (const char *name, + int64_t id, + Residue *residue) + { + return status = tng_chain_residue_find(traj->traj, chain, name, + id, &residue->residue); + } + + /** + * @brief Add a residue to a chain. + * @param name is a string containing the name of the residue. + * @param residue is a pointer to the newly created residue. + * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major + * error has occured. + */ + tng_function_status addResidue(const char *name, + Residue * residue) + { + return status = tng_chain_residue_add(traj->traj, chain, + name, &residue->residue); + } + + /** + * @brief Add a residue with a specific ID to a chain. + * @param name is a string containing the name of the residue. + * @param id is the ID of the created residue. + * @param residue is a pointer to the newly created residue. + * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could + * not be set properly or TNG_CRITICAL (2) if a major error has occured. + */ + tng_function_status addResidueWithId + (const char *name, + const int64_t id, + Residue * residue) + { + return status = tng_chain_residue_w_id_add(traj->traj, chain, + name, id, &residue->residue); + } +}; + +/** +* @brief Add a chain to a molecule. +* @param name is a string containing the name of the chain. +* @param chain s a pointer to the newly created chain. +* @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major +* error has occured. +*/ +tng_function_status Molecule::addChain(const char *name, Chain *chain) +{ + return status = tng_molecule_chain_add(traj->traj,mol,name,&chain->chain); +} + +/** +* @brief Find a chain in a molecule. +* @param name is a string containing the name of the chain. If name is empty +* only id will be used for finding the chain. +* @param id is the id of the chain to look for. If id is -1 only the name of +* the chain will be used for finding the chain. +* @param chain is a pointer to the chain if it was found - otherwise 0. +* @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the +* chain is not found. +* @details If name is an empty string and id is -1 the first chain will be +* found. +*/ +tng_function_status Molecule::findChain + (const char *name, + int64_t id, + Chain *chain) +{ + return status = tng_molecule_chain_find(traj->traj, mol, name, id, + &chain->chain); +} + +} +#endif diff --git a/include/tng/tng_io_fwd.h b/include/tng/tng_io_fwd.h new file mode 100644 index 0000000..8b63a9a --- /dev/null +++ b/include/tng/tng_io_fwd.h @@ -0,0 +1,39 @@ +/* This code is part of the tng binary trajectory format. + * + * Written by Magnus Lundborg + * Copyright (c) 2012-2013, The GROMACS development team. + * Check out http://www.gromacs.org for more information. + * + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the Revised BSD License. + */ + +#ifndef TNG_IO_FWD_H +#define TNG_IO_FWD_H 1 + +/** A pointer to the main trajectory data storage. */ +typedef struct tng_trajectory *tng_trajectory_t; +/** A pointer to a molecule description. */ +typedef struct tng_molecule *tng_molecule_t; +/** A pointer to a molecular chain description. */ +typedef struct tng_chain *tng_chain_t; +/** A pointer to a molecular residue description. */ +typedef struct tng_residue *tng_residue_t; +/** A pointer to a molecular atom description. */ +typedef struct tng_atom *tng_atom_t; +/** A pointer to a bond between two atoms. */ +typedef struct tng_bond *tng_bond_t; +/** A pointer to a structure containing data common to all trajectory blocks, + * such as header and contents. */ +typedef struct tng_gen_block *tng_gen_block_t; +/** A pointer to particle mapping information. */ +typedef struct tng_particle_mapping *tng_particle_mapping_t; +/** A pointer to a structure containing frame set information. */ +typedef struct tng_trajectory_frame_set *tng_trajectory_frame_set_t; +/** A pointer to a particle data container. */ +typedef struct tng_particle_data *tng_particle_data_t; +/** A pointer to a non-particle data container. */ +typedef struct tng_non_particle_data *tng_non_particle_data_t; + +#endif diff --git a/include/tng/version.h.in b/include/tng/version.h.in new file mode 100644 index 0000000..662e68f --- /dev/null +++ b/include/tng/version.h.in @@ -0,0 +1,16 @@ +#ifndef VERSION_CONFIG_H +#define VERSION_CONFIG_H + +/* define the API version (integer) */ +#define TNG_API_VERSION @TNG_API_VERSION@ + +/* define the major and minor versions + of the library */ +#define TNG_VERSION_MAJOR @TNG_MAJOR_VERSION@ +#define TNG_VERSION_MINOR @TNG_MINOR_VERSION@ +/* define the patchlevel of the library */ +#define TNG_VERSION_PATCHLEVEL @TNG_VERSION_PATCH_LEVEL@ +/* define the full version of the library (string) */ +#define TNG_VERSION "@TNG_IO_VERSION@" + +#endif diff --git a/include/tng_io.h b/include/tng_io.h deleted file mode 100644 index 5b89cd6..0000000 --- a/include/tng_io.h +++ /dev/null @@ -1,4815 +0,0 @@ -/* This code is part of the tng binary trajectory format. - * - * Written by Magnus Lundborg - * Copyright (c) 2012-2014, The GROMACS development team. - * Check out http://www.gromacs.org for more information. - * - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the Revised BSD License. - */ - -/** @file tng_io.h - * @brief API for input and output of tng trajectory files - * @mainpage TNG: A flexible binary trajectory format - * @section intro_sec Introduction - * - * The TNG format is developed as part of the ScalaLife EU project. - * It is flexible by design to allow parallel writing, custom data blocks, - * different output frequencies and different compression algorithms. - * - * Each block can contain MD5 hashes to verify data integrity and the file - * can be signed by the user to ensure that the origin is correct. - * - * This is version 1.4 of the TNG API. The intention is that this version of - * the API and ABI should be stable, but it is still possible that future - * changes might make that impossible, in which case that will be clarified. - * - * The API and all examples are released without any warranties. Use them at - * your own risk. - * - * @section authors_sec Authors - * - * The TNG trajectory format is developed by: - * - * Magnus Lundborg magnus.lundborg@scilifelab.se - * - * Daniel Spångberg daniels@mkem.uu.se - * - * Rossen Apostolov rossen@kth.se - * - * The API is implemented mainly by: - * - * Magnus Lundborg - * - * @section License - * - * Copyright (c) 2012, The GROMACS development team. - * check out http://www.gromacs.org for more information. - * - * The TNG API is released under the Revised BSD License and is free to - * redistribute according to that license. - * - * A license file (named COPYING) should be included with each copy of the API. - * - * @section install_sec Installation - * - * \code - * mkdir build - * - * cd build - * - * cmake .. - * - * make - * - * make install - * \endcode - * Test by running: - * \code - * bin/tests/tng_testing - * \endcode - * - * @section change_sec Change Log - * - * See git log for full revision history. - * - * Revisions - * - * v. 1.5 - Third stable release of the API. - * - * - Fortran wrapper split into separate file - * - Added more block IDs. - * - Some new functions and utility functions added. - * - Improved compression precision settings. - * - Improved tests. - * - Make appending to file work better. - * - Modified CMake settings - * - Bugs fixed - * - * v. 1.4 - Changed from LGPL to the Revised BSD License. - * - * - More flexible support for digital signatures in header. - * - Block ID numbers changed. - * - * v. 1.3 - Second stable release of the API. - * - * - Added multiplication factor for coordinate units to general info. - * - Added time stamps and time per frame in frame sets. - * - High-level API functions added (not for managing molecules yet) - * - Added functions for reading data blocks into 1D arrays. - * - TNG compression added. - * - C++ interface added. - * - Avoid memory allocation if no data is submitted when adding data - * blocks. - * - Added function tng_num_frames_per_frame_set_set - * - Added data block IDs for charges, b-factors and occupancy. - * - GZIP compression added. - * - Fixed bug when updating MD5 hashes of data blocks. - * - Fixed bug in chain_name_of_particle_get(...) - * - Update frame set pointers properly. - * - Moved fortran wrapper from header file to source file. - * - Write sparse data in mdrun examples. - * - Fixed bugs related to reading and writing sparse data. - * - Fixed memory leak for non-trajectory particle data blocks. - * - Fixed bug when writing data blocks. - * - Fixed wrong values in dependency constants - * - Write box shape, partial charges and annotation data in tng_testing - * - Bug fixes in tng_testing (frame sets not written before) - * - * v. 1.0 - First stable release of the API. - * - * - * @section examples_sec Examples - * - * There are some examples of how to use the library located in src/tests/ - * - * @subsection tng_subsec TNG files - * - * The build directory contains an example_files directory, which in turn - * contains a very short example of a TNG file containing a few water molecules, - * a box shape description and positions in 10 frames. - * - * It is also possible to run the bin/examples/md_openmp_util - * (see src/tests/md_openmp_util.c) - * testing program, which will save MD simulations output to a new file - * (saved in the example_files directory). - * - * These files can be read using the bin/examples/tng_io_read_pos_util - * program. - * - * @subsection c_subsec C - * - * Example writing data to a TNG file (just an excerpt): - * \code - * for ( step = 1; step < step_num; step++ ) - * { - * compute ( np, nd, pos, vel, mass, force, &potential, &kinetic ); - * - * if(step % step_save == 0) - * { - * // Write positions, velocities and forces - * if(tng_util_pos_write(traj, step, pos) != TNG_SUCCESS) - * { - * printf("Error adding data. %s: %d\n", __FILE__, __LINE__); - * break; - * } - * if(tng_util_vel_write(traj, step, vel) != TNG_SUCCESS) - * { - * printf("Error adding data. %s: %d\n", __FILE__, __LINE__); - * break; - * } - * if(tng_util_force_write(traj, step, force) != TNG_SUCCESS) - * { - * printf("Error adding data. %s: %d\n", __FILE__, __LINE__); - * break; - * } - * } - * update ( np, nd, pos, vel, force, acc, mass, dt ); - * } - * \endcode - * - * Example reading positions from a TNG file: - * \code - * #include - * #include - * #include "tng_io.h" - * - * int main(int argc, char **argv) - * { - * tng_trajectory_t traj; - * // Assume that the data is stored as floats. The data is placed in 1-D - * // arrays - * float *positions = 0, *box_shape = 0; - * int64_t n_particles, n_frames, tot_n_frames, stride_length, i, j; - * // Set a default frame range - * int64_t first_frame = 0, last_frame = 5000; - * int k; - * - * // A reference must be passed to allocate memory - * tng_util_trajectory_open(argv[1], 'r', &traj); - * - * if(tng_num_frames_get(traj, &tot_n_frames) != TNG_SUCCESS) - * { - * printf("Cannot determine the number of frames in the file\n"); - * tng_util_trajectory_close(&traj); - * exit(1); - * } - * - * if(tng_num_particles_get(traj, &n_particles) != TNG_SUCCESS) - * { - * printf("Cannot determine the number of particles in the file\n"); - * tng_util_trajectory_close(&traj); - * exit(1); - * } - * - * printf("%"PRId64" frames in file\n", tot_n_frames); - * - * if(last_frame > tot_n_frames - 1) - * { - * last_frame = tot_n_frames - 1; - * } - * - * if(tng_util_box_shape_read(traj, &box_shape, &stride_length) == - * TNG_SUCCESS) - * { - * printf("Simulation box shape: "); - * for(i=0; i < 9; i++) - * { - * printf("%f ", box_shape[i]); - * } - * printf("\n"); - * } - * else - * { - * printf("Simulation box shape not set in the file (or could not be read)\n"); - * } - * - * n_frames = last_frame - first_frame + 1; - * - * - * // Get the positions of all particles in the requested frame range. - * // The positions are stored in the positions array. - * // N.B. No proper error checks. - * if(tng_util_pos_read_range(traj, 0, last_frame, &positions, &stride_length) - * == TNG_SUCCESS) - * { - * // Print the positions of the wanted particle (zero based) - * for(i=0; i < n_frames; i += stride_length) - * { - * printf("\nFrame %"PRId64":\n", first_frame + i); - * for(j=0; j < n_particles; j++) - * { - * printf("Atom nr: %"PRId64"", j); - * for(k=0; k < 3; k++) - * { - * printf("\t%f", positions[i/stride_length*n_particles* - * 3+j*3+k]); - * } - * printf("\n"); - * } - * } - * } - * else - * { - * printf("Cannot read positions\n"); - * } - * - * // Free memory - * if(positions) - * { - * free(positions); - * } - * tng_util_trajectory_close(&traj); - * - * return(0); - * } - * - * \endcode - * - * @subsection fortran_subsec Fortran - * - * The TNG library can be used from Fortran. It requires cray pointers, which - * are not part of the Fortran 77 standard, but available in most compilers. - * - * To compile the fortran example -DTNG_BUILD_FORTRAN=ON needs to be specified when - * running cmake. - * - */ - -#ifndef TNG_IO_H -#define TNG_IO_H 1 - -#include -#include -#include -#include -#include "tng_io_fwd.h" - -#ifdef USE_STD_INTTYPES_H -#include -#else -/* Visual Studio does not contain inttypes.h and stdint.h. Some defines and - * typedefs are used from the GNU C Library */ -#ifdef _MSC_VER - -typedef __int32 int32_t; -typedef unsigned __int32 uint32_t; -typedef __int64 int64_t; -typedef unsigned __int64 uint64_t; - -#else -#include -#endif /* _MSC_VER */ - -/* This is from inttypes.h (GNU C Library) */ -/* The ISO C99 standard specifies that these macros must only be - defined if explicitly requested. */ -#if !defined __cplusplus || defined __STDC_FORMAT_MACROS - -# if __WORDSIZE == 64 -# define __PRI64_PREFIX "l" -# define __PRIPTR_PREFIX "l" -# else -# define __PRI64_PREFIX "ll" -# define __PRIPTR_PREFIX -# endif - -/* From stdint.h (GNU C Library) */ -/* Macros for printing format specifiers. */ -/* Decimal notation. */ -#ifndef PRId64 -# define PRId64 __PRI64_PREFIX "d" -#endif - -#endif - -#endif /* USE_STD_INTTYPES_H */ - - -#ifndef USE_WINDOWS -#if defined(WIN32) || defined(_WIN32) || defined(WIN64) || defined(_WIN64) -#define USE_WINDOWS -#endif /* win32... */ -#endif /* not defined USE_WINDOWS */ - -#ifndef DECLSPECDLLEXPORT -#ifdef USE_WINDOWS -#define DECLSPECDLLEXPORT __declspec(dllexport) -#else /* USE_WINDOWS */ -#define DECLSPECDLLEXPORT -#endif /* USE_WINDOWS */ -#endif /* DECLSPECDLLEXPORT */ - -/** Flag to indicate frame dependent data. */ -#define TNG_FRAME_DEPENDENT 1 -/** Flag to indicate particle dependent data. */ -#define TNG_PARTICLE_DEPENDENT 2 - -/** The maximum length of a date string */ -#define TNG_MAX_DATE_STR_LEN 24 -/** The length of an MD5 hash */ -#define TNG_MD5_HASH_LEN 16 -/** The maximum allowed length of a string */ -#define TNG_MAX_STR_LEN 1024 - -#ifndef NDEBUG -#define TNG_ASSERT(cnd, msg) if(!(cnd)) {printf("%s\n", msg); assert(cnd);} -#else -#define TNG_ASSERT(cnd, msg) (void)0; -#endif - -/** Flag to specify the endianness of a TNG file */ -typedef enum {TNG_BIG_ENDIAN, - TNG_LITTLE_ENDIAN} tng_file_endianness; - -/** Flag to specify the endianness of 32 bit values of the current architecture. */ -typedef enum {TNG_BIG_ENDIAN_32, - TNG_LITTLE_ENDIAN_32, - TNG_BYTE_PAIR_SWAP_32} tng_endianness_32; - -/** Flag to specify the endianness of 64 bit values of the current architecture. */ -typedef enum {TNG_BIG_ENDIAN_64, - TNG_LITTLE_ENDIAN_64, - TNG_QUAD_SWAP_64, - TNG_BYTE_PAIR_SWAP_64, - TNG_BYTE_SWAP_64} tng_endianness_64; - -/** Compression mode is specified in each data block */ -typedef enum {TNG_UNCOMPRESSED, - TNG_XTC_COMPRESSION, - TNG_TNG_COMPRESSION, - TNG_GZIP_COMPRESSION} tng_compression; - -/** Hash types */ -typedef enum {TNG_NO_HASH, - TNG_MD5, - TNG_SHA256} tng_hash_type; - -/** Non trajectory blocks come before the first frame set block */ -typedef enum {TNG_NON_TRAJECTORY_BLOCK, TNG_TRAJECTORY_BLOCK} tng_block_type; - -/** @defgroup def1 Standard non-trajectory blocks - * Block IDs of standard non-trajectory blocks. - * @{ - */ -#define TNG_GENERAL_INFO 0x0000000000000000LL -#define TNG_MOLECULES 0x0000000000000001LL -#define TNG_TRAJECTORY_FRAME_SET 0x0000000000000002LL -#define TNG_PARTICLE_MAPPING 0x0000000000000003LL -/** @} */ - -/** @defgroup def2 Standard trajectory blocks - * Block IDs of standard trajectory blocks. Box shape and partial charges can - * be either trajectory blocks or non-trajectory blocks - * @{ - */ -#define TNG_TRAJ_BOX_SHAPE 0x0000000010000000LL -#define TNG_TRAJ_POSITIONS 0x0000000010000001LL -#define TNG_TRAJ_VELOCITIES 0x0000000010000002LL -#define TNG_TRAJ_FORCES 0x0000000010000003LL -#define TNG_TRAJ_PARTIAL_CHARGES 0x0000000010000004LL -#define TNG_TRAJ_FORMAL_CHARGES 0x0000000010000005LL -#define TNG_TRAJ_B_FACTORS 0x0000000010000006LL -#define TNG_TRAJ_ANISOTROPIC_B_FACTORS 0x0000000010000007LL -#define TNG_TRAJ_OCCUPANCY 0x0000000010000008LL -#define TNG_TRAJ_GENERAL_COMMENTS 0x0000000010000009LL -/** @} */ - - -/** @defgroup def3 GROMACS data block IDs - * Block IDs of data blocks specific to GROMACS. - * @{ - */ -#define TNG_GMX_LAMBDA 0x1000000010000000LL -#define TNG_GMX_ENERGY_ANGLE 0x1000000010000001LL -#define TNG_GMX_ENERGY_RYCKAERT_BELL 0x1000000010000002LL -#define TNG_GMX_ENERGY_LJ_14 0x1000000010000003LL -#define TNG_GMX_ENERGY_COULOMB_14 0x1000000010000004LL -#define TNG_GMX_ENERGY_LJ_(SR) 0x1000000010000005LL -#define TNG_GMX_ENERGY_COULOMB_(SR) 0x1000000010000006LL -#define TNG_GMX_ENERGY_COUL_RECIP 0x1000000010000007LL -#define TNG_GMX_ENERGY_POTENTIAL 0x1000000010000008LL -#define TNG_GMX_ENERGY_KINETIC_EN 0x1000000010000009LL -#define TNG_GMX_ENERGY_TOTAL_ENERGY 0x1000000010000010LL -#define TNG_GMX_ENERGY_TEMPERATURE 0x1000000010000011LL -#define TNG_GMX_ENERGY_PRESSURE 0x1000000010000012LL -#define TNG_GMX_ENERGY_CONSTR_RMSD 0x1000000010000013LL -#define TNG_GMX_ENERGY_BOX_X 0x1000000010000014LL -#define TNG_GMX_ENERGY_BOX_Y 0x1000000010000015LL -#define TNG_GMX_ENERGY_BOX_Z 0x1000000010000016LL -#define TNG_GMX_ENERGY_VOLUME 0x1000000010000017LL -#define TNG_GMX_ENERGY_DENSITY 0x1000000010000018LL -#define TNG_GMX_ENERGY_PV 0x1000000010000019LL -#define TNG_GMX_ENERGY_ENTHALPY 0x1000000010000020LL -#define TNG_GMX_ENERGY_VIR_XX 0x1000000010000021LL -#define TNG_GMX_ENERGY_VIR_XY 0x1000000010000022LL -#define TNG_GMX_ENERGY_VIR_XZ 0x1000000010000023LL -#define TNG_GMX_ENERGY_VIR_YX 0x1000000010000024LL -#define TNG_GMX_ENERGY_VIR_YY 0x1000000010000025LL -#define TNG_GMX_ENERGY_VIR_YZ 0x1000000010000026LL -#define TNG_GMX_ENERGY_VIR_ZX 0x1000000010000027LL -#define TNG_GMX_ENERGY_VIR_ZY 0x1000000010000028LL -#define TNG_GMX_ENERGY_VIR_ZZ 0x1000000010000029LL -#define TNG_GMX_ENERGY_PRES_XX 0x1000000010000030LL -#define TNG_GMX_ENERGY_PRES_XY 0x1000000010000031LL -#define TNG_GMX_ENERGY_PRES_XZ 0x1000000010000032LL -#define TNG_GMX_ENERGY_PRES_YX 0x1000000010000033LL -#define TNG_GMX_ENERGY_PRES_YY 0x1000000010000034LL -#define TNG_GMX_ENERGY_PRES_YZ 0x1000000010000035LL -#define TNG_GMX_ENERGY_PRES_ZX 0x1000000010000036LL -#define TNG_GMX_ENERGY_PRES_ZY 0x1000000010000037LL -#define TNG_GMX_ENERGY_PRES_ZZ 0x1000000010000038LL -#define TNG_GMX_ENERGY_SURFXSURFTEN 0x1000000010000039LL -#define TNG_GMX_ENERGY_T_SYSTEM 0x1000000010000040LL -#define TNG_GMX_ENERGY_LAMB_SYSTEM 0x1000000010000041LL -#define TNG_GMX_SELECTION_GROUP_NAMES 0x1000000010000042LL -#define TNG_GMX_ATOM_SELECTION_GROUP 0x1000000010000043LL -/** @} */ - -/** Flag to specify if a data block contains data related to particles or not.*/ -typedef enum {TNG_NON_PARTICLE_BLOCK_DATA, - TNG_PARTICLE_BLOCK_DATA} tng_particle_dependency; - - -typedef enum {TNG_FALSE, TNG_TRUE} tng_bool; - -/** Flag to specify if the number of atoms change throughout the trajectory or - * if it is constant. */ -typedef enum {TNG_CONSTANT_N_ATOMS, TNG_VARIABLE_N_ATOMS} - tng_variable_n_atoms_flag; - -/** Return values of API functions. TNG_SUCCESS means that the operation - * was successful. TNG_FAILURE means that the operation failed for some - * reason, but it is possible to try to continue anyhow. TNG_CRITICAL - * means that the error is irrecoverable. */ -typedef enum {TNG_SUCCESS, TNG_FAILURE, TNG_CRITICAL} tng_function_status; - -/** If tng_hash_mode == TNG_USE_HASH md5 hashes will be written to output files - * and when reading a file the md5 hashes of the contents will be compared to - * those in the file (for each block) in order to ensure data integrity */ -typedef enum {TNG_SKIP_HASH, TNG_USE_HASH} tng_hash_mode; - -/** Possible formats of data block contents */ -typedef enum {TNG_CHAR_DATA, - TNG_INT_DATA, - TNG_FLOAT_DATA, - TNG_DOUBLE_DATA} tng_data_type; - - -struct tng_trajectory; -struct tng_molecule; -struct tng_chain; -struct tng_residue; -struct tng_atom; -struct tng_bond; -struct tng_gen_block; -struct tng_particle_mapping; -struct tng_trajectory_frame_set; -struct tng_particle_data; -struct tng_non_particle_data; - -/** Data can be either double, float, int or a string */ -union data_values { - double d; - float f; - int64_t i; - char *c; -}; - - -#ifdef __cplusplus -extern "C" -{ -#endif - -/** @defgroup group1 Low-level API - * These functions give detailed control of the TNG data management. Most - * things can be done using the more convenient high-level API functions - * instead. - * @{ - */ - -/** - * @brief Setup a trajectory data container. - * @param tng_data_p a pointer to memory to initialise as a trajectory. - * @pre tng_data_p must not be pointing at a reserved memory block. - * @details Memory is allocated during initialisation. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_trajectory_init - (tng_trajectory_t *tng_data_p); - -/** - * @brief Clean up a trajectory data container. - * @param tng_data_p a pointer to the trajectory data to destroy. - * @details All allocated memory in the data structure is freed, as well as - * tng_data_p itself. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_trajectory_destroy - (tng_trajectory_t *tng_data_p); - -/** - * @brief Copy a trajectory data container (dest is setup as well). - * @details This initialises dest and copies only what is absolute necessary for - * parallel i/o. This can be used inside pragma omp for setting up a thread - * local copy of src. It can be freed (using tng_trajectory_destroy) at the - * end of the parallel block. - * @param src the original trajectory. - * @param dest_p a pointer to memory to initialise as a trajectory. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre tng_data_p must not be pointing at a reserved memory block. - * @details Memory is allocated during initialisation. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_trajectory_init_from_src - (tng_trajectory_t src, tng_trajectory_t *dest_p); - -/** - * @brief Get the name of the input file. - * @param tng_data the trajectory of which to get the input file name. - * @param file_name the string to fill with the name of the input file, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for file_name. This includes \0 terminating character. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code file_name != 0 \endcode The pointer to the file name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_input_file_get - (const tng_trajectory_t tng_data, - char *file_name, const int max_len); - -/** - * @brief Set the name of the input file. - * @param tng_data the trajectory of which to set the input file name. - * @param file_name the name of the input file. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code file_name != 0 \endcode The pointer to the file name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_input_file_set - (tng_trajectory_t tng_data, - const char *file_name); - -/** - * @brief Get the name of the output file. - * @param tng_data the trajectory of which to get the input file name. - * @param file_name the string to fill with the name of the output file, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for file_name. This includes \0 terminating character. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code file_name != 0 \endcode The pointer to the file name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_output_file_get - (const tng_trajectory_t tng_data, - char *file_name, const int max_len); - -/** - * @brief Set the name of the output file. - * @param tng_data the trajectory of which to set the output file name. - * @param file_name the name of the output file. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code file_name != 0 \endcode The pointer to the file name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_output_file_set - (tng_trajectory_t tng_data, - const char *file_name); - -/** - * @brief Set the name of the output file for appending. The output file - * will not be overwritten. - * @param tng_data the trajectory of which to set the output file name. - * @param file_name the name of the output file to append to. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code file_name != 0 \endcode The pointer to the file name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_output_append_file_set - (tng_trajectory_t tng_data, - const char *file_name); - -/** - * @brief Get the endianness of the output file. - * @param tng_data the trajectory of which to get the endianness of the current - * output file. - * @param endianness will contain the enumeration of the endianness. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code endianness != 0 \endcode The pointer to the endianness container - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness - * could not be retrieved. - */ -tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_get - (const tng_trajectory_t tng_data, tng_file_endianness *endianness); - -/** - * @brief Set the endianness of the output file. - * @param tng_data the trajectory of which to set the endianness of the current - * output file. - * @param endianness the enumeration of the endianness, can be either - * TNG_BIG_ENDIAN (0) or TNG_LITTLE_ENDIAN (1). - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @details The endianness cannot be changed after file output has started. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness - * could not be set. - */ -tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_set - (tng_trajectory_t tng_data, - const tng_file_endianness endianness); - -/** - * @brief Get the name of the program used when creating the trajectory. - * @param tng_data the trajectory of which to get the program name. - * @param name the string to fill with the name of the program, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_first_program_name_get - (const tng_trajectory_t tng_data, - char *name, const int max_len); - -/** - * @brief Set the name of the program used when creating the trajectory. - * @param tng_data the trajectory of which to set the program name. - * @param new_name is a string containing the wanted name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code new_name != 0 \endcode The pointer to the new_name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_first_program_name_set - (tng_trajectory_t tng_data, - const char *new_name); - -/** - * @brief Get the name of the program used when last modifying the trajectory. - * @param tng_data the trajectory of which to get the program name. - * @param name the string to fill with the name of the program, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_last_program_name_get - (const tng_trajectory_t tng_data, - char *name, const int max_len); - -/** - * @brief Set the name of the program used when last modifying the trajectory. - * @param tng_data the trajectory of which to set the program name. - * @param new_name is a string containing the wanted name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code new_name != 0 \endcode The pointer to the new_name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_last_program_name_set - (tng_trajectory_t tng_data, - const char *new_name); - -/** - * @brief Get the name of the user who created the trajectory. - * @param tng_data the trajectory of which to get the user name. - * @param name the string to fill with the name of the user, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_first_user_name_get - (const tng_trajectory_t tng_data, - char *name, const int max_len); - -/** - * @brief Set the name of the user who created the trajectory. - * @param tng_data the trajectory of which to set the user name. - * @param new_name is a string containing the wanted name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code new_name != 0 \endcode The pointer to the new_name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_first_user_name_set - (tng_trajectory_t tng_data, - const char *new_name); - -/** - * @brief Get the name of the user who last modified the trajectory. - * @param tng_data the trajectory of which to get the user name. - * @param name the string to fill with the name of the user, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_last_user_name_get - (const tng_trajectory_t tng_data, - char *name, const int max_len); - -/** - * @brief Set the name of the user who last modified the trajectory. - * @param tng_data the trajectory of which to set the user name. - * @param new_name is a string containing the wanted name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code new_name != 0 \endcode The pointer to the new_name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_last_user_name_set - (tng_trajectory_t tng_data, - const char *new_name); - -/** - * @brief Get the name of the computer used when creating the trajectory. - * @param tng_data the trajectory of which to get the computer name. - * @param name the string to fill with the name of the computer, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_get - (const tng_trajectory_t tng_data, - char *name, const int max_len); - -/** - * @brief Set the name of the computer used when creating the trajectory. - * @param tng_data the trajectory of which to set the computer name. - * @param new_name is a string containing the wanted name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code new_name != 0 \endcode The pointer to the new_name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_set - (tng_trajectory_t tng_data, - const char *new_name); - -/** - * @brief Get the name of the computer used when last modifying the trajectory. - * @param tng_data the trajectory of which to get the computer name. - * @param name the string to fill with the name of the computer, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_get - (const tng_trajectory_t tng_data, - char *name, const int max_len); - -/** - * @brief Set the name of the computer used when last modifying the trajectory. - * @param tng_data the trajectory of which to set the computer name. - * @param new_name is a string containing the wanted name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code new_name != 0 \endcode The pointer to the new_name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_set - (tng_trajectory_t tng_data, - const char *new_name); - -/** - * @brief Get the pgp_signature of the user creating the trajectory. - * @param tng_data the trajectory of which to get the computer name. - * @param signature the string to fill with the signature, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code signature != 0 \endcode The pointer to the signature - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_first_signature_get - (const tng_trajectory_t tng_data, - char *signature, const int max_len); - -/** - * @brief Set the pgp_signature of the user creating the trajectory. - * @param tng_data the trajectory of which to set the computer name. - * @param signature is a string containing the pgp_signature. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code signature != 0 \endcode The pointer to the signature - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_first_signature_set - (tng_trajectory_t tng_data, - const char *signature); - -/** - * @brief Get the pgp_signature of the user last modifying the trajectory. - * @param tng_data the trajectory of which to get the computer name. - * @param signature the string to fill with the signature, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code signature != 0 \endcode The pointer to the signature - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_last_signature_get - (const tng_trajectory_t tng_data, - char *signature, const int max_len); - -/** - * @brief Set the pgp_signature of the user last modifying the trajectory. - * @param tng_data the trajectory of which to set the computer name. - * @param signature is a string containing the pgp_signature. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code signature != 0 \endcode The pointer to the signature - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_last_signature_set - (tng_trajectory_t tng_data, - const char *signature); - -/** - * @brief Get the name of the forcefield used in the trajectory. - * @param tng_data the trajectory of which to get the forcefield name. - * @param name the string to fill with the name of the forcefield, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_get - (const tng_trajectory_t tng_data, - char *name, const int max_len); - -/** - * @brief Set the name of the forcefield used in the trajectory. - * @param tng_data the trajectory of which to set the forcefield name. - * @param new_name is a string containing the wanted name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code new_name != 0 \endcode The pointer to the new_name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_set - (tng_trajectory_t tng_data, - const char *new_name); - -/** - * @brief Get the medium stride length of the trajectory. - * @param tng_data is the trajectory from which to get the stride length. - * @param len is pointing to a value set to the stride length. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_get - (const tng_trajectory_t tng_data, - int64_t *len); - -/** - * @brief Set the medium stride length of the trajectory. - * @param tng_data is the trajectory of which to set the stride length. - * @param len is the wanted medium stride length. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred. - */ -tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_set - (tng_trajectory_t tng_data, - const int64_t len); - -/** - * @brief Get the long stride length of the trajectory. - * @param tng_data is the trajectory from which to get the stride length. - * @param len is pointing to a value set to the stride length. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_get - (const tng_trajectory_t tng_data, - int64_t *len); - -/** - * @brief Set the long stride length of the trajectory. - * @param tng_data is the trajectory of which to set the stride length. - * @param len is the wanted long stride length. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred. - */ -tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_set - (tng_trajectory_t tng_data, - const int64_t len); - -/** - * @brief Get the current time per frame of the trajectory. - * @param tng_data is the trajectory from which to get the time per frame. - * @param time is pointing to a value set to the time per frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code time != 0 \endcode The pointer to time must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_get - (const tng_trajectory_t tng_data, - double *time); - -/** - * @brief Set the time per frame of the trajectory. - * @param tng_data is the trajectory of which to set the time per frame. - * @param time is the new time per frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code time > 0 \endcode The time per frame must be >= 0. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred. - */ -tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_set - (tng_trajectory_t tng_data, - const double time); - -/** - * @brief Get the length of the input file. - * @param tng_data is the trajectory from which to get the input file length. - * @param len is pointing to a value set to the file length. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code len != 0 \endcode The pointer to len must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_input_file_len_get - (const tng_trajectory_t tng_data, - int64_t *len); - -/** - * @brief Get the number of frames in the trajectory - * @param tng_data is the trajectory of which to get the number of frames. - * @param n is pointing to a value set to the number of frames. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code tng_data->input_file != 0 \endcode An input file must be open - * to find the next frame set. - * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (could not find last frame set). - */ -tng_function_status DECLSPECDLLEXPORT tng_num_frames_get - (const tng_trajectory_t tng_data, - int64_t *n); - -/** - * @brief Get the precision of lossy compression. - * @param tng_data is the trajectory of which to get the compression precision. - * @param precision will be pointing to the retrieved compression precision. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @details A compression precision of 0.001 (the default) means that the - * compressed values are accurate to the third decimal. This function does - * not check actual precision of compressed data, but just returns what has - * previously been set using tng_compression_precision_set(). - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_compression_precision_get - (const tng_trajectory_t tng_data, - double *precision); - -/** - * @brief Set the precision of lossy compression. - * @param tng_data is the trajectory of which to set the compression precision. - * @param precision is the new compression precision. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @details A compression precision of 0.001 (the default) means that the - * compressed values are accurate to the third decimal. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_compression_precision_set - (tng_trajectory_t tng_data, - const double precision); - -/** - * @brief Set the number of particles, in the case no molecular system is used. - * @param tng_data is the trajectory of which to get the number of particles. - * @param n is the number of particles to use. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @details When creating a molecular system the number of particles are set - * automatically. This should only be used when there is no molecular system - * specified or if the number of atoms needs to be overridden for some reason. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_implicit_num_particles_set - (tng_trajectory_t tng_data, - const int64_t n); - -/** - * @brief Get the current number of particles. - * @param tng_data is the trajectory from which to get the number of particles. - * @param n is pointing to a value set to the number of particles. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. - * @details If variable number of particles are used this function will return - * the number of particles in the current frame set. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_num_particles_get - (const tng_trajectory_t tng_data, - int64_t *n); - -/** - * @brief Get if the number of particle can be varied during the simulation. - * @param tng_data is the trajectory from which to get the number of particles. - * @param variable is pointing to a value set to TNG_CONSTANT_N_ATOMS if the - * number of particles cannot change or TNG_VARIABLE_N_ATOMS if the number of - * particles can change. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code variable != 0 \endcode The pointer to variable must not be - * a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_num_particles_variable_get - (const tng_trajectory_t tng_data, - char *variable); - -/** - * @brief Get the number of molecule types (length of tng_data->molecules). - * @param tng_data is the trajectory from which to get the number of molecules. - * @param n is pointing to a value set to the number of molecule types. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_num_molecule_types_get - (const tng_trajectory_t tng_data, - int64_t *n); - -/** - * @brief Get the current total number of molecules. - * @param tng_data is the trajectory from which to get the number of molecules. - * @param n is pointing to a value set to the number of molecules. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. - * @details If variable number of particles are used this function will return - * the total number of molecules in the current frame set. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_num_molecules_get - (const tng_trajectory_t tng_data, - int64_t *n); - -/** @brief Get the list of the count of each molecule. - * @param tng_data is the trajectory from which to get the molecule count list. - * @param mol_cnt_list is a list of the count of each molecule in the - * mol system. This is a pointer to the list in the TNG container, which - * means that it should be handled carefully, e.g. not freed. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE(1) if the list of - * molecule counts was not valid. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_list_get - (const tng_trajectory_t tng_data, - int64_t **mol_cnt_list); - -/** - * @brief Get the exponent used for distances in the trajectory. - * @param tng_data is the trajectory from which to get the information. - * @param exp is pointing to a value set to the distance unit exponent. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code exp != 0 \endcode The pointer to exp must not be a NULL pointer. - * @details Example: If the distances are specified in nm (default) exp is -9. - * If the distances are specified in Å exp is -10. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_get - (const tng_trajectory_t tng_data, - int64_t *exp); - -/** - * @brief Set the exponent used for distances in the trajectory. - * @param tng_data is the trajectory of which to set the unit exponent. - * @param exp is the distance unit exponent to use. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @details Example: If the distances are specified in nm (default) exp is -9. - * If the distances are specified in Å exp is -10. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_set - (const tng_trajectory_t tng_data, - const int64_t exp); - -/** - * @brief Get the number of frames per frame set. - * @param tng_data is the trajectory from which to get the number of frames - * per frame set. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. - * @param n is pointing to a value set to the number of frames per frame set. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_get - (const tng_trajectory_t tng_data, - int64_t *n); - -/** - * @brief Set the number of frames per frame set. - * @param tng_data is the trajectory of which to set the number of frames - * per frame set. - * @param n is the number of frames per frame set. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @details This does not affect already existing frame sets. For - * consistency the number of frames per frame set should be set - * betfore creating any frame sets. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_set - (const tng_trajectory_t tng_data, - const int64_t n); - -/** - * @brief Get the number of frame sets. - * @details This updates tng_data->n_trajectory_frame_sets before returning it. - * @param tng_data is the trajectory from which to get the number of frame sets. - * @param n is pointing to a value set to the number of frame sets. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_num_frame_sets_get - (const tng_trajectory_t tng_data, - int64_t *n); - -/** - * @brief Get the current trajectory frame set. - * @param tng_data is the trajectory from which to get the frame set. - * @param frame_set_p will be set to point at the memory position of - * the found frame set. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_current_frame_set_get - (const tng_trajectory_t tng_data, - tng_trajectory_frame_set_t *frame_set_p); - -/** - * @brief Find the requested frame set number. - * @param tng_data is the trajectory from which to get the frame set. - * @param nr is the frame set number to search for. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code nr >= 0 \endcode The frame set number (nr) must be >= 0. - * @details tng_data->current_trajectory_frame_set will contain the - * found trajectory if successful. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_nr_find - (tng_trajectory_t tng_data, - const int64_t nr); - -/** - * @brief Find the frame set containing a specific frame. - * @param tng_data is the trajectory from which to get the frame set. - * @param frame is the frame number to search for. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame >= 0 \endcode The frame number must be >= 0. - * @details tng_data->current_trajectory_frame_set will contain the - * found trajectory if successful. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_of_frame_find - (tng_trajectory_t tng_data, - const int64_t frame); - -/** - * @brief Get the file position of the next frame set in the input file. - * @param tng_data is a trajectory data container. - * @param frame_set is the frame set of which to get the position of the - * following frame set. - * @param pos is pointing to a value set to the file position. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_next_frame_set_file_pos_get - (const tng_trajectory_t tng_data, - const tng_trajectory_frame_set_t frame_set, - int64_t *pos); - -/** - * @brief Get the file position of the previous frame set in the input file. - * @param tng_data is a trajectory data container. - * @param frame_set is the frame set of which to get the position of the - * previous frame set. - * @param pos is pointing to a value set to the file position. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code pos != 0 \endcode The pointer to pos must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_prev_frame_set_file_pos_get - (const tng_trajectory_t tng_data, - const tng_trajectory_frame_set_t frame_set, - int64_t *pos); - -/** - * @brief Get the first and last frames of the frame set. - * @param tng_data is a trajectory data container. - * @param frame_set is the frame set of which to get the frame range. - * @param first_frame is set to the first frame of the frame set. - * @param last_frame is set to the last frame of the frame set. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code first_frame != 0 \endcode The pointer to first_frame must - * not be a NULL pointer. - * @pre \code last_frame != 0 \endcode The pointer to last_frame must - * not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_frame_range_get - (const tng_trajectory_t tng_data, - const tng_trajectory_frame_set_t frame_set, - int64_t *first_frame, - int64_t *last_frame); - -/** - * @brief Allocate memory for and setup a molecule container. - * @param tng_data is a trajectory data container. - * @param molecule_p is a pointer to molecule to allocate and initialise. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_alloc(const tng_trajectory_t tng_data, - tng_molecule_t *molecule_p); - -/** - * @brief Clean up a molecule container and free its allocated memory. - * @param tng_data is a trajectory data container. - * @param molecule_p is the molecule to destroy. - * @details All allocated memory in the data structure is freed and also the memory - * of the molecule itself. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_free(const tng_trajectory_t tng_data, - tng_molecule_t *molecule_p); - -/** - * @brief Setup a molecule container. - * @param tng_data is a trajectory data container. - * @param molecule is the molecule to initialise. Memory must be preallocated. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_init - (const tng_trajectory_t tng_data, - tng_molecule_t molecule); - -/** - * @brief Clean up a molecule container. - * @param tng_data is a trajectory data container. - * @param molecule is the molecule to destroy. - * @details All allocated memory in the data structure is freed, but not the - * memory of molecule itself. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_destroy - (const tng_trajectory_t tng_data, - tng_molecule_t molecule); - -/** - * @brief Add a molecule to the trajectory. - * @param tng_data is the trajectory data container containing the block.. - * @param name is a pointer to the string containing the name of the new molecule. - * @param molecule is a pointer to the newly created molecule. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could - * not be set properly or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_add - (tng_trajectory_t tng_data, - const char *name, - tng_molecule_t *molecule); - -/** - * @brief Add a molecule with a specific ID to the trajectory. - * @param tng_data is the trajectory data container containing the block.. - * @param name is a pointer to the string containing the name of the new molecule. - * @param id is the ID of the created molecule. - * @param molecule is a pointer to the newly created molecule. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could - * not be set properly or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_w_id_add - (tng_trajectory_t tng_data, - const char *name, - const int64_t id, - tng_molecule_t *molecule); - -/** - * @brief Add an existing molecule (from a molecule container) to the trajectory. - * @param tng_data is the trajectory data container containing the block.. - * @param molecule is a pointer to the molecule to add to the trajectory and will - * afterwards point to the molecule in the trajectory. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_existing_add - (tng_trajectory_t tng_data, - tng_molecule_t *molecule); - -/** - * @brief Get the name of a molecule. - * @param tng_data the trajectory containing the molecule. - * @param molecule the molecule of which to get the name. - * @param name the string to fill with the name of the molecule, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @pre \code molecule != 0 \endcode The molecule must not be NULL. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_name_get - (const tng_trajectory_t tng_data, - const tng_molecule_t molecule, - char *name, - const int max_len); - -/** - * @brief Set the name of a molecule. - * @param tng_data is the trajectory data container containing the molecule.. - * @param molecule is the molecule to rename. - * @param new_name is a string containing the wanted name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code new_name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_name_set - (tng_trajectory_t tng_data, - tng_molecule_t molecule, - const char *new_name); - -/** - * @brief Get the count of a molecule. - * @param tng_data is the trajectory data container containing the molecule.. - * @param molecule is the molecule of which to get the count. - * @param cnt is a pointer to the variable to be populated with the count. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code cnt != 0 \endcode The pointer to the molecule count - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_get - (const tng_trajectory_t tng_data, - const tng_molecule_t molecule, - int64_t *cnt); - -/** - * @brief Set the count of a molecule. - * @param tng_data is the trajectory data container containing the molecule.. - * @param molecule is the molecule of which to set the count. - * @param cnt is the number of instances of this molecule. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_set - (tng_trajectory_t tng_data, - tng_molecule_t molecule, - const int64_t cnt); - -/** - * @brief Find a molecule. - * @param tng_data is the trajectory data container containing the molecule. - * @param name is a string containing the name of the molecule. If name is empty - * only id will be used for finding the molecule. - * @param id is the id of the molecule to look for. If id is -1 only the name of - * the molecule will be used for finding the molecule. - * @param molecule is a pointer to the molecule if it was found - otherwise 0. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the - * molecule is not found. - * @details If name is an empty string and id == -1 the first residue will - * be found. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_find - (tng_trajectory_t tng_data, - const char *name, - int64_t id, - tng_molecule_t *molecule); - -/** - * @brief Retrieve the molecule with specified index in the list of molecules. - * @param tng_data is the trajectory data container containing the molecule. - * @param index is the index (in tng_data->molecules) of the molecule to return - * @param molecule is a pointer to the molecule if it was found - otherwise 0. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. - * @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the - * molecule is not found. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_of_index_get - (tng_trajectory_t tng_data, - int64_t index, - tng_molecule_t *molecule); - -/** - * @brief Copy all molecules and the molecule counts from one TNG trajectory - * to another. - * @param tng_data_src is the source trajectory containing the molecular - * system to copy. - * @param tng_data_dest is the destination trajectory. - * @pre \code tng_data_src != 0 \endcode The trajectory container (tng_data_src) - * must be initialised before using it. - * @pre \code tng_data_dest != 0 \endcode The trajectory container (tng_data_dest) - * must be initialised before using it. - * @details The molecular system in tng_data_dest will be overwritten. - * @return TNG_SUCCESS(0) if the copying is successful, TNG_FAILURE if a minor - * error has occured or TNG_CRITICAL(2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_system_copy(tng_trajectory_t tng_data_src, - tng_trajectory_t tng_data_dest); - -/** - * @brief Get the number of chains in a molecule. - * @param tng_data is the trajectory containing the molecule. - * @param molecule is the molecule of which to get the number of chains. - * @param n is pointing to a value set to the number of chains. - * @pre \code molecule != 0 \endcode The molecule must not be NULL. - * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_num_chains_get - (const tng_trajectory_t tng_data, - const tng_molecule_t molecule, - int64_t *n); - -/** - * @brief Retrieve the chain of a molecule with specified index in the list - * of chains. - * @param tng_data is the trajectory data container containing the molecule. - * @param index is the index (in molecule->chains) of the chain to return - * @param molecule is the molecule from which to get the chain. - * @param chain is a pointer to the chain if it was found - otherwise 0. - * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. - * @pre \code chain != 0 \endcode chain must not be a NULL pointer. - * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the - * chain is not found. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_of_index_get - (tng_trajectory_t tng_data, - tng_molecule_t molecule, - int64_t index, - tng_chain_t *chain); - -/** - * @brief Get the number of residues in a molecule. - * @param tng_data is the trajectory containing the molecule. - * @param molecule is the molecule of which to get the number residues. - * @param n is pointing to a value set to the number of residues. - * @pre \code molecule != 0 \endcode The molecule must not be NULL. - * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_num_residues_get - (const tng_trajectory_t tng_data, - const tng_molecule_t molecule, - int64_t *n); - -/** - * @brief Retrieve the residue of a molecule with specified index in the list - * of chains. - * @param tng_data is the trajectory data container containing the molecule. - * @param index is the index (in molecule->residues) of the residue to return - * @param molecule is the molecule from which to get the residue. - * @param residue is a pointer to the residue if it was found - otherwise 0. - * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. - * @pre \code residue != 0 \endcode residue must not be a NULL pointer. - * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the - * residue is not found. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_residue_of_index_get - (const tng_trajectory_t tng_data, - const tng_molecule_t molecule, - const int64_t index, - tng_residue_t *residue); - -/** - * @brief Get the number of atoms in a molecule. - * @param tng_data is the trajectory containing the molecule. - * @param molecule is the molecule of which to get the number of atoms. - * @param n is pointing to a value set to the number of atoms. - * @pre \code molecule != 0 \endcode The molecule must not be NULL. - * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_num_atoms_get - (const tng_trajectory_t tng_data, - const tng_molecule_t molecule, - int64_t *n); - -/** - * @brief Retrieve the atom of a molecule with specified index in the list - * of atoms. - * @param tng_data is the trajectory data container containing the molecule. - * @param index is the index (in molecule->atoms) of the atom to return - * @param molecule is the molecule from which to get the atom. - * @param atom is a pointer to the atom if it was found - otherwise 0. - * @pre \code molecule != 0 \endcode molecule must not be a NULL pointer. - * @pre \code atom != 0 \endcode atom must not be a NULL pointer. - * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the - * atom is not found. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_of_index_get - (const tng_trajectory_t tng_data, - const tng_molecule_t molecule, - const int64_t index, - tng_atom_t *atom); - -/** - * @brief Find a chain in a molecule. - * @param tng_data is the trajectory data container containing the molecule. - * @param molecule is the molecule in which to search for the chain. - * @param name is a string containing the name of the chain. If name is empty - * only id will be used for finding the chain. - * @param id is the id of the chain to look for. If id is -1 only the name of - * the chain will be used for finding the chain. - * @param chain is a pointer to the chain if it was found - otherwise 0. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the - * chain is not found. - * @details If name is an empty string and id == -1 the first residue will - * be found. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_find - (tng_trajectory_t tng_data, - tng_molecule_t molecule, - const char *name, - int64_t id, - tng_chain_t *chain); - -/** - * @brief Add a chain to a molecule. - * @param tng_data is the trajectory data container containing the molecule.. - * @param molecule is the molecule to add a chain to. - * @param name is a string containing the name of the chain. - * @param chain is a pointer to the newly created chain. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could - * not be set properly or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_add - (tng_trajectory_t tng_data, - tng_molecule_t molecule, - const char *name, - tng_chain_t *chain); - -/** - * @brief Add a chain with a specific id to a molecule. - * @param tng_data is the trajectory data container containing the molecule.. - * @param molecule is the molecule to add a chain to. - * @param name is a string containing the name of the chain. - * @param id is the ID of the created chain. - * @param chain is a pointer to the newly created chain. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could - * not be set properly or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_w_id_add - (tng_trajectory_t tng_data, - tng_molecule_t molecule, - const char *name, - const int64_t id, - tng_chain_t *chain); - -/** - * @brief Add a bond between two atoms to a molecule. - * @param tng_data is the trajectory data container containing the molecule. - * @param molecule is the molecule containing the atoms to connect. - * @param from_atom_id is the id of one of the two atoms in the bond. - * @param to_atom_id is the id of the other atom in the bond. - * @param bond is a pointer to the newly created bond. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (!) if a minor error - * has occured or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_bond_add - (const tng_trajectory_t tng_data, - tng_molecule_t molecule, - const int64_t from_atom_id, - const int64_t to_atom_id, - tng_bond_t *bond); - -/** - * @brief Find an atom in a molecule. - * @param tng_data is the trajectory data container containing the molecule. - * @param molecule is the molecule in which to search for the atom. - * @param name is a string containing the name of the atom. If name is an - * empty string only id will be used for searching. - * @param id is the id of the atom to find. If id == -1 the first atom - * that matches the specified name will be found. - * @param atom is a pointer to the atom if it was found - otherwise 0. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the - * atom is not found. - * @details If name is an empty string and id == -1 the first residue will - * be found. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_find - (tng_trajectory_t tng_data, - tng_molecule_t molecule, - const char *name, - int64_t id, - tng_atom_t *atom); - -/** - * @brief Get the name of a chain. - * @param tng_data the trajectory containing the chain. - * @param chain the chain of which to get the name. - * @param name the string to fill with the name of the chain, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @pre \code chain != 0 \endcode The chain must not be NULL. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_chain_name_get - (const tng_trajectory_t tng_data, - const tng_chain_t chain, - char *name, - const int max_len); - -/** - * @brief Set the name of a chain. - * @param tng_data is the trajectory data container containing the atom.. - * @param chain is the chain to rename. - * @param new_name is a string containing the wanted name. - * @pre \code new_name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_chain_name_set - (tng_trajectory_t tng_data, - tng_chain_t chain, - const char *new_name); - -/** - * @brief Get the number of residues in a molecule chain. - * @param tng_data is the trajectory containing the chain. - * @param chain is the chain of which to get the number of residues. - * @param n is pointing to a value set to the number of residues. - * @pre \code chain != 0 \endcode The chain must not be NULL. - * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_chain_num_residues_get - (const tng_trajectory_t tng_data, - const tng_chain_t chain, - int64_t *n); - -/** - * @brief Retrieve the residue of a chain with specified index in the list - * of residues. - * @param tng_data is the trajectory data container containing the chain. - * @param index is the index (in chain->residues) of the residue to return - * @param chain is the chain from which to get the residue. - * @param residue is a pointer to the residue if it was found - otherwise 0. - * @pre \code chain != 0 \endcode chain must not be a NULL pointer. - * @pre \code residue != 0 \endcode residue must not be a NULL pointer. - * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the - * residue is not found. - */ -tng_function_status DECLSPECDLLEXPORT tng_chain_residue_of_index_get - (const tng_trajectory_t tng_data, - const tng_chain_t chain, - const int64_t index, - tng_residue_t *residue); - -/** - * @brief Find a residue in a chain. - * @param tng_data is the trajectory data container containing the chain. - * @param chain is the chain in which to search for the residue. - * @param name is a string containing the name of the residue. If name is an - * empty string only id will be used for searching. - * @param id is the id of the residue to find. If id == -1 the first residue - * that matches the specified name will be found. - * @param residue is a pointer to the residue if it was found - otherwise 0. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the - * residue is not found. - * @details If name is an empty string and id == -1 the first residue will - * be found. - */ -tng_function_status DECLSPECDLLEXPORT tng_chain_residue_find - (tng_trajectory_t tng_data, - tng_chain_t chain, - const char *name, - int64_t id, - tng_residue_t *residue); - -/** - * @brief Add a residue to a chain. - * @param tng_data is the trajectory data container containing the chain.. - * @param chain is the chain to add a residue to. - * @param name is a string containing the name of the residue. - * @param residue is a pointer to the newly created residue. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could - * not be set properly or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_chain_residue_add - (tng_trajectory_t tng_data, - tng_chain_t chain, - const char *name, - tng_residue_t *residue); - -/** - * @brief Add a residue with a specific ID to a chain. - * @param tng_data is the trajectory data container containing the chain.. - * @param chain is the chain to add a residue to. - * @param name is a string containing the name of the residue. - * @param id is the ID of the created residue. - * @param residue is a pointer to the newly created residue. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could - * not be set properly or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_chain_residue_w_id_add - (tng_trajectory_t tng_data, - tng_chain_t chain, - const char *name, - const int64_t id, - tng_residue_t *residue); - -/** - * @brief Get the name of a residue. - * @param tng_data the trajectory containing the residue. - * @param residue the residue of which to get the name. - * @param name the string to fill with the name of the residue, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @pre \code residue != 0 \endcode The residue must not be NULL. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_residue_name_get - (const tng_trajectory_t tng_data, - const tng_residue_t residue, - char *name, - const int max_len); - -/** - * @brief Set the name of a residue. - * @param tng_data is the trajectory data container containing the residue. - * @param residue is the residue to rename. - * @param new_name is a string containing the wanted name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code new_name != 0 \endcode The new name to set (new_name) must - * not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_residue_name_set - (tng_trajectory_t tng_data, - tng_residue_t residue, - const char *new_name); - -/** - * @brief Get the number of atoms in a residue. - * @param tng_data is the trajectory containing the residue. - * @param residue is the residue of which to get the number atoms. - * @param n is pointing to a value set to the number of atoms. - * @pre \code residue != 0 \endcode The residue must not be NULL. - * @pre \code n != 0 \endcode The pointer to n must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_residue_num_atoms_get - (const tng_trajectory_t tng_data, - const tng_residue_t residue, - int64_t *n); - -/** - * @brief Retrieve the atom of a residue with specified index in the list - * of atoms. - * @param tng_data is the trajectory data container containing the residue. - * @param index is the index (in residue->atoms) of the atom to return - * @param residue is the residue from which to get the atom. - * @param atom is a pointer to the atom if it was found - otherwise 0. - * @pre \code residue != 0 \endcode residue must not be a NULL pointer. - * @pre \code atom != 0 \endcode atom must not be a NULL pointer. - * @return TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the - * atom is not found. - */ -tng_function_status DECLSPECDLLEXPORT tng_residue_atom_of_index_get - (const tng_trajectory_t tng_data, - const tng_residue_t residue, - const int64_t index, - tng_atom_t *atom); - -/** - * @brief Add an atom to a residue. - * @param tng_data is the trajectory containing the residue. - * @param residue is the residue to add an atom to. - * @param atom_name is a string containing the name of the atom. - * @param atom_type is a string containing the atom type of the atom. - * @param atom is a pointer to the newly created atom. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code atom_name != 0 \endcode The pointer to the atom name string - * must not be a NULL pointer. - * @pre \code atom_type != 0 \endcode The pointer to the atom_type string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could - * not be set properly or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_residue_atom_add - (tng_trajectory_t tng_data, - tng_residue_t residue, - const char *atom_name, - const char *atom_type, - tng_atom_t *atom); - -/** - * @brief Add an atom with a specific ID to a residue. - * @param tng_data is the trajectory containing the residue. - * @param residue is the residue to add an atom to. - * @param atom_name is a string containing the name of the atom. - * @param atom_type is a string containing the atom type of the atom. - * @param id is the ID of the created atom. - * @param atom is a pointer to the newly created atom. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code atom_name != 0 \endcode The pointer to the atom name string - * must not be a NULL pointer. - * @pre \code atom_type != 0 \endcode The pointer to the atom_type string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could - * not be set properly or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_residue_atom_w_id_add - (tng_trajectory_t tng_data, - tng_residue_t residue, - const char *atom_name, - const char *atom_type, - const int64_t id, - tng_atom_t *atom); - -/** - * @brief Get the residue of an atom. - * @param tng_data the trajectory containing the atom. - * @param atom the atom of which to get the name. - * @param residue is set to the residue of the atom. - * @pre \code atom != 0 \endcode The atom must not be NULL. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status tng_atom_residue_get(const tng_trajectory_t tng_data, - const tng_atom_t atom, - tng_residue_t *residue); - -/** - * @brief Get the name of an atom. - * @param tng_data the trajectory containing the atom. - * @param atom the atom of which to get the name. - * @param name the string to fill with the name of the atom, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @pre \code atom != 0 \endcode The atom must not be NULL. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_atom_name_get - (const tng_trajectory_t tng_data, - const tng_atom_t atom, - char *name, - const int max_len); - -/** - * @brief Set the name of an atom. - * @param tng_data is the trajectory data container containing the atom. - * @param atom is the atom to rename. - * @param new_name is a string containing the wanted name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code new_name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_atom_name_set - (tng_trajectory_t tng_data, - tng_atom_t atom, - const char *new_name); - -/** - * @brief Get the type of an atom. - * @param tng_data the trajectory containing the atom. - * @param atom the atom of which to get the type. - * @param type the string to fill with the type of the atom, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for type. This includes \0 terminating character. - * @pre \code atom != 0 \endcode The atom must not be NULL. - * @pre \code type != 0 \endcode The pointer to the type string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ -tng_function_status DECLSPECDLLEXPORT tng_atom_type_get - (const tng_trajectory_t tng_data, - const tng_atom_t atom, - char *type, - const int max_len); - -/** - * @brief Set the atom type of an atom. - * @param tng_data is the trajectory data container containing the atom. - * @param atom is the atom to change. - * @param new_type is a string containing the atom type. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code new_type != 0 \endcode The pointer to the atom type string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_atom_type_set - (tng_trajectory_t tng_data, - tng_atom_t atom, - const char *new_type); - -/** - * @brief Get the molecule name of real particle number (number in mol system). - * @param tng_data is the trajectory data container containing the atom. - * @param nr is the real number of the particle in the molecular system. - * @param name is a string, which is set to the name of the molecule. Memory - * must be reserved beforehand. - * @param max_len is the maximum length of name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_name_of_particle_nr_get - (const tng_trajectory_t tng_data, - const int64_t nr, - char *name, - int max_len); - -/** - * @brief Get the molecule id of real particle number (number in mol system). - * @param tng_data is the trajectory data container containing the atom. - * @param nr is the real number of the particle in the molecular system. - * @param id is will be set to the id of the molecule. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molecule_id_of_particle_nr_get - (const tng_trajectory_t tng_data, - const int64_t nr, - int64_t *id); - -/** - * @brief Get the bonds of the current molecular system. - * @param tng_data is the trajectory data container containing the molecular - * system. - * @param n_bonds is set to the number of bonds in the molecular system and - * thereby also the lengths of the two lists: from_atoms and to_atoms. - * @param from_atoms is a list (memory reserved by this function) of atoms - * (number of atom in mol system) in bonds. - * @param to_atoms is a list (memory reserved by this function) of atoms - * (number of atom in mol system) in bonds. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n_bonds != 0 \endcode The pointer to n_bonds must not be a - * NULL pointer. - * @pre \code from_atoms != 0 \endcode The pointer to from_atoms must not - * be a NULL pointer. - * @pre \code to_atoms != 0 \endcode The pointer to to_atoms must not - * be a NULL pointer. - * @details The two lists of atoms use the same index, i.e. from_atoms[0] - * and to_atoms[0] are linked with a bond. Since memory is reserved in - * this function it must be freed afterwards. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_molsystem_bonds_get - (const tng_trajectory_t tng_data, - int64_t *n_bonds, - int64_t **from_atoms, - int64_t **to_atoms); - -/** - * @brief Get the chain name of real particle number (number in mol system). - * @param tng_data is the trajectory data container containing the atom. - * @param nr is the real number of the particle in the molecular system. - * @param name is a string, which is set to the name of the chain. Memory - * must be reserved beforehand. - * @param max_len is the maximum length of name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_chain_name_of_particle_nr_get - (const tng_trajectory_t tng_data, - const int64_t nr, - char *name, - int max_len); - -/** - * @brief Get the residue name of real particle number (number in mol system). - * @param tng_data is the trajectory data container containing the atom. - * @param nr is the real number of the particle in the molecular system. - * @param name is a string, which is set to the name of the residue. Memory - * must be reserved beforehand. - * @param max_len is the maximum length of name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_residue_name_of_particle_nr_get - (const tng_trajectory_t tng_data, - const int64_t nr, - char *name, - int max_len); - -/** - * @brief Get the residue id (local to molecule) of real particle number - * (number in mol system). - * @param tng_data is the trajectory data container containing the atom. - * @param nr is the real number of the particle in the molecular system. - * @param id is a pointer to the variable, which will be set to the ID. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_residue_id_of_particle_nr_get - (const tng_trajectory_t tng_data, - const int64_t nr, - int64_t *id); - -/** - * @brief Get the residue id (based on other molecules and molecule counts) - * of real particle number (number in mol system). - * @param tng_data is the trajectory data container containing the atom. - * @param nr is the real number of the particle in the molecular system. - * @param id is a pointer to the variable, which will be set to the ID. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code id != 0 \endcode The pointer to id must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_global_residue_id_of_particle_nr_get - (const tng_trajectory_t tng_data, - const int64_t nr, - int64_t *id); - -/** - * @brief Get the atom name of real particle number (number in mol system). - * @param tng_data is the trajectory data container containing the atom. - * @param nr is the real number of the particle in the molecular system. - * @param name is a string, which is set to the name of the atom. Memory - * must be reserved beforehand. - * @param max_len is the maximum length of name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_atom_name_of_particle_nr_get - (const tng_trajectory_t tng_data, - const int64_t nr, - char *name, - int max_len); - -/** - * @brief Get the atom type of real particle number (number in mol system). - * @param tng_data is the trajectory data container containing the atom. - * @param nr is the real number of the particle in the molecular system. - * @param type is a string, which is set to the type of the atom. Memory - * must be reserved beforehand. - * @param max_len is the maximum length of type. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code type != 0 \endcode The pointer to the type string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_atom_type_of_particle_nr_get - (const tng_trajectory_t tng_data, - const int64_t nr, - char *type, - int max_len); - -/** - * @brief Add a particle mapping table. - * @details Each particle mapping table will be written as a separate block, - * followed by the data blocks for the corresponding particles. In most cases - * there is one particle mapping block for each thread writing the trajectory. - * @param tng_data is the trajectory, with the frame set to which to add - * the mapping block. - * @details The mapping information is added to the currently active frame set - * of tng_data - * @param num_first_particle is the first particle number of this mapping - * block. - * @param n_particles is the number of particles in this mapping block. - * @param mapping_table is a list of the real particle numbers (i.e. the numbers - * used in the molecular system). The list is n_particles long. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @details mapping_table[0] is the real particle number of the first particle - * in the following data blocks. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_particle_mapping_add - (tng_trajectory_t tng_data, - const int64_t num_first_particle, - const int64_t n_particles, - const int64_t *mapping_table); - -/** - * @brief Remove all particle mappings (in memory) from the current frame set. - * @details Clears the currently setup particle mappings of the current frame - * set. - * @param tng_data is the trajectory, with the frame set of which to clear - * all particle mappings. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_particle_mapping_free - (tng_trajectory_t tng_data); - -/** - * @brief Read the header blocks from the input_file of tng_data. - * @details The trajectory blocks must be read separately and iteratively in chunks - * to fit in memory. - * @param tng_data is a trajectory data container. - * @details tng_data->input_file_path specifies - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_file_headers_read - (tng_trajectory_t tng_data, - const char hash_mode); - -/** - * @brief Write the header blocks to the output_file of tng_data. - * @details The trajectory blocks must be written separately and iteratively in chunks - * to fit in memory. - * @param tng_data is a trajectory data container. - * @details tng_data->output_file_path - * specifies which file to write to. If the file (output_file) is not open it - * will be opened. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_file_headers_write - (tng_trajectory_t tng_data, - const char hash_mode); - -/** - * @brief Read one (the next) block (of any kind) from the input_file of tng_data. - * @param tng_data is a trajectory data container. - * @details tng_data->input_file_path specifies - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param block_data is a pointer to the struct which will be populated with the - * data. - * @details If block_data->input_file_pos > 0 it is the position from where the - * reading starts otherwise it starts from the current position. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code block != 0 \endcode The block container (block) must be - * initialised before using it. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_block_read_next - (tng_trajectory_t tng_data, - tng_gen_block_t block_data, - const char hash_mode); - -/** - * @brief Read one frame set, including all particle mapping blocks and data - * blocks, starting from the current file position. - * @param tng_data is a trajectory data container. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_read - (tng_trajectory_t tng_data, - const char hash_mode); - -/** - * @brief Read data from the current frame set from the input_file. Only read - * particle mapping and data blocks matching the specified block_id. - * @param tng_data is a trajectory data container. - * @details tng_data->input_file_path specifies - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @param block_id is the ID of the data block to read from file. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_current_only_data_from_block_id - (tng_trajectory_t tng_data, - const char hash_mode, - const int64_t block_id); - -/** - * @brief Read one (the next) frame set, including particle mapping and related data blocks - * from the input_file of tng_data. - * @param tng_data is a trajectory data container. - * @details tng_data->input_file_path specifies - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next - (tng_trajectory_t tng_data, - const char hash_mode); - -/** - * @brief Read one (the next) frame set, including particle mapping and data blocks with a - * specific block id from the input_file of tng_data. - * @param tng_data is a trajectory data container. - * @details tng_data->input_file_path specifies - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @param block_id is the ID number of the blocks that should be read from file. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next_only_data_from_block_id - (tng_trajectory_t tng_data, - const char hash_mode, - const int64_t block_id); - -/** - * @brief Write one frame set, including mapping and related data blocks - * to the output_file of tng_data. - * @param tng_data is a trajectory data container. - * @details tng_data->output_file_path specifies - * which file to write to. If the file (output_file) is not open it will be - * opened. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_write - (tng_trajectory_t tng_data, - const char hash_mode); - -/** - * @brief Write one frame set even if it does not have as many frames as - * expected. The function also writes mapping and related data blocks - * to the output_file of tng_data. - * @param tng_data is a trajectory data container. - * @details tng_data->output_file_path specifies - * which file to write to. If the file (output_file) is not open it will be - * opened. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @details The number of frames in the frame set is set to the number of - * frames of the data blocks before writing it to disk. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_premature_write - (tng_trajectory_t tng_data, - const char hash_mode); - -/** - * @brief Create and initialise a frame set. - * @details Particle mappings are retained from previous frame set (if any). - * To explicitly clear particle mappings use tng_frame_set_particle_mapping_free(). - * @param tng_data is the trajectory data container in which to add the frame - * set. - * @param first_frame is the first frame of the frame set. - * @param n_frames is the number of frames in the frame set. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code first_frame >= 0 \endcode The first frame must not be negative. - * @pre \code n_frames >= 0 \endcode The number of frames must not be negative. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_new - (tng_trajectory_t tng_data, - const int64_t first_frame, - const int64_t n_frames); - -/** - * @brief Create and initialise a frame set with the time of the first frame - * specified. - * @param tng_data is the trajectory data container in which to add the frame - * set. - * @param first_frame is the first frame of the frame set. - * @param n_frames is the number of frames in the frame set. - * @param first_frame_time is the time stamp of the first frame (in seconds). - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code first_frame >= 0 \endcode The first frame must not be negative. - * @pre \code n_frames >= 0 \endcode The number of frames must not be negative. - * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame - * must not be negative. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_with_time_new - (tng_trajectory_t tng_data, - const int64_t first_frame, - const int64_t n_frames, - const double first_frame_time); - -/** - * @brief Set the time stamp of the first frame of the current frame set. - * @param tng_data is the trajectory containing the frame set. - * @param first_frame_time is the time stamp of the first frame in the - * frame set. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code first_frame_time >= 0 \endcode The time stamp of the first frame - * must not be negative. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_set_first_frame_time_set - (tng_trajectory_t tng_data, - const double first_frame_time); - -/** - * @brief Read the number of the first frame of the next frame set. - * @param tng_data is the trajectory containing the frame set. - * @param frame is set to the frame number of the first frame in the - * next frame set. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code tng_data->input_file != 0 \endcode An input file must be open - * to find the next frame set. - * @pre \code frame != 0 \endcode The pointer to the frame must not be a NULL - * pointer. - * @return TNG_SUCCESS(0) if successful, TNG_FAILURE(1) if there is no next - * frame set or TNG_CRITICAL(2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_first_frame_nr_of_next_frame_set_get - (const tng_trajectory_t tng_data, - int64_t *frame); - -/** - * @brief Add a non-particle dependent data block. - * @param tng_data is the trajectory data container in which to add the data - * block - * @param id is the block ID of the block to add. - * @param block_name is a descriptive name of the block to add - * @param datatype is the datatype of the data in the block (e.g. int/float) - * @param block_type_flag indicates if this is a non-trajectory block (added - * directly to tng_data) or if it is a trajectory block (added to the - * frame set) - * @param n_frames is the number of frames of the data block (automatically - * set to 1 if adding a non-trajectory data block) - * @param n_values_per_frame is how many values a stored each frame (e.g. 9 - * for a box shape block) - * @param stride_length is how many frames are between each entry in the - * data block - * @param codec_id is the ID of the codec to compress the data. - * @param new_data is an array of data values to add. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code block_name != 0 \endcode The pointer to the block name must - * not be a NULL pointer. - * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be - * a positive integer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_data_block_add - (tng_trajectory_t tng_data, - const int64_t id, - const char *block_name, - const char datatype, - const char block_type_flag, - int64_t n_frames, - const int64_t n_values_per_frame, - int64_t stride_length, - const int64_t codec_id, - void *new_data); - -/** - * @brief Add a particle dependent data block. - * @param tng_data is the trajectory data container in which to add the data - * block - * @param id is the block ID of the block to add. - * @param block_name is a descriptive name of the block to add - * @param datatype is the datatype of the data in the block (e.g. int/float) - * @param block_type_flag indicates if this is a non-trajectory block (added - * directly to tng_data) or if it is a trajectory block (added to the - * frame set) - * @param n_frames is the number of frames of the data block (automatically - * set to 1 if adding a non-trajectory data block) - * @param n_values_per_frame is how many values a stored each frame (e.g. 9 - * for a box shape block) - * @param stride_length is how many frames are between each entry in the - * data block - * @param num_first_particle is the number of the first particle stored - * in this data block - * @param n_particles is the number of particles stored in this data block - * @param codec_id is the ID of the codec to compress the data. - * @param new_data is an array of data values to add. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code block_name != 0 \endcode The pointer to the block name must - * not be a NULL pointer. - * @pre \code n_values_per_frame > 0 \endcode n_values_per_frame must be - * a positive integer. - * @pre \code num_first_particle >= 0 \endcode The number of the - * first particle must be >= 0. - * @pre \code n_particles >= 0 \endcode n_particles must be >= 0. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_particle_data_block_add - (tng_trajectory_t tng_data, - const int64_t id, - const char *block_name, - const char datatype, - const char block_type_flag, - int64_t n_frames, - const int64_t n_values_per_frame, - int64_t stride_length, - const int64_t num_first_particle, - const int64_t n_particles, - const int64_t codec_id, - void *new_data); - -/** @brief Get the name of a data block of a specific ID. - * @param tng_data is the trajectory data container. - * @param block_id is the ID of the data block of which to get the name. - * @param name is a string, which is set to the name of the data block. - * Memory must be reserved beforehand. - * @param max_len is the maximum length of name. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code name != 0 \endcode The pointer to the name string - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1) - * if a minor error has occured or the data block is not found or - * TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_data_block_name_get - (tng_trajectory_t tng_data, - int64_t block_id, - char *name, - int max_len); - -/** @brief Get the dependency of a data block of a specific ID. - * @param tng_data is the trajectory data container. - * @param block_id is the ID of the data block of which to get the name. - * @param block_dependency is a pointer to the dependency of the data block. - * If the block is frame dependent it will be set to TNG_FRAME_DEPENDENT, - * if it is particle dependent it will be set to TNG_PARTICLE_DEPENDENT and - * if it is both it will be set to TNG_FRAME_DEPENDENT & TNG_PARTICLE_DEPENDENT. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code block_dependency != 0 \endcode The pointer to the block dependency - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1) - * if a minor error has occured or the data block is not found or - * TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_data_block_dependency_get - (const tng_trajectory_t tng_data, - int64_t block_id, - int *block_dependency); - -/** @brief Get the number of values per frame of a data block of a specific ID. - * @param tng_data is the trajectory data container. - * @param block_id is the ID of the data block of which to get the name. - * @param n_values_per_frame is a pointer set to the number of values per frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of values - * per frame must not be a NULL pointer. - * @return TNG_SUCCESS (0) if the data block is found, TNG_FAILURE (1) - * if a minor error has occured or the data block is not found or - * TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_data_block_num_values_per_frame_get - (const tng_trajectory_t tng_data, - int64_t block_id, - int64_t *n_values_per_frame); - -/** - * @brief Write data of one trajectory frame to the output_file of tng_data. - * @param tng_data is a trajectory data container. tng_data->output_file_path - * specifies which file to write to. If the file (output_file) is not open it - * will be opened. - * @param frame_nr is the index number of the frame to write. - * @param block_id is the ID of the data block to write the data to. - * @param values is an array of data to write. The length of the array should - * equal n_values_per_frame. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code values != 0 \endcode The pointer to the values must not be a NULL - * pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_data_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const int64_t block_id, - const void *values, - const char hash_mode); - -/** - * @brief Write particle data of one trajectory frame to the output_file of - * tng_data. - * @param tng_data is a trajectory data container. tng_data->output_file_path - * specifies which file to write to. If the file (output_file) is not open it - * will be opened. - * @param frame_nr is the index number of the frame to write. - * @param block_id is the ID of the data block to write the data to. - * @param val_first_particle is the number of the first particle in the data - * array. - * @param val_n_particles is the number of particles in the data array. - * @param values is a 1D-array of data to write. The length of the array should - * equal n_particles * n_values_per_frame. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code val_first_particle >= 0 \endcode The number of the - * first particle must be >= 0. - * @pre \code val_n_particles >= 0 \endcode The number of particles must be >= 0. - * @pre \code values != 0 \endcode The pointer to the values must not be a NULL - * pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_frame_particle_data_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const int64_t block_id, - const int64_t val_first_particle, - const int64_t val_n_particles, - const void *values, - const char hash_mode); - -/** - * @brief Free data of an array of values (2D). - * @param tng_data is a trajectory data container. - * @param values is the 2D array to free and will be set to 0 afterwards. - * @param n_frames is the number of frames in the data array. - * @param n_values_per_frame is the number of values per frame in the data array. - * @param type is the data type of the data in the array (e.g. int/float/char). - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_data_values_free - (const tng_trajectory_t tng_data, - union data_values **values, - const int64_t n_frames, - const int64_t n_values_per_frame, - const char type); - -/** - * @brief Free data of an array of values (3D). - * @param tng_data is a trajectory data container. - * @param values is the array to free and will be set to 0 afterwards. - * @param n_frames is the number of frames in the data array. - * @param n_particles is the number of particles in the data array. - * @param n_values_per_frame is the number of values per frame in the data array. - * @param type is the data type of the data in the array (e.g. int/float/char). - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_particle_data_values_free - (const tng_trajectory_t tng_data, - union data_values ***values, - const int64_t n_frames, - const int64_t n_particles, - const int64_t n_values_per_frame, - const char type); - -/** - * @brief Retrieve non-particle data, from the last read frame set. Obsolete! - * @param tng_data is a trajectory data container. tng_data->input_file_path specifies - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param block_id is the id number of the particle data block to read. - * @param values is a pointer to a 2-dimensional array (memory unallocated), which - * will be filled with data. The array will be sized - * (n_frames * n_values_per_frame). - * Since ***values is allocated in this function it is the callers - * responsibility to free the memory. - * @param n_frames is set to the number of frames in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n_frames != 0 \endcode The pointer to the number of frames - * must not be a NULL pointer. - * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of - * values per frame must not be a NULL pointer. - * @pre \code type != 0 \endcode The pointer to the data type must not - * be a NULL pointer. - * @details This function is obsolete and only retained for compatibility. Use - * tng_data_vector_get() instead. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_data_get(tng_trajectory_t tng_data, - const int64_t block_id, - union data_values ***values, - int64_t *n_frames, - int64_t *n_values_per_frame, - char *type); - -/** - * @brief Retrieve a vector (1D array) of non-particle data, from the last read frame set. - * @param tng_data is a trajectory data container. tng_data->input_file_path specifies - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param block_id is the id number of the particle data block to read. - * @param values is a pointer to a 1-dimensional array (memory unallocated), which - * will be filled with data. The length of the array will be (n_frames * n_values_per_frame). - * Since **values is allocated in this function it is the callers - * responsibility to free the memory. - * @param n_frames is set to the number of particles in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param stride_length is set to the stride length of the returned data. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n_frames != 0 \endcode The pointer to the number of frames - * must not be a NULL pointer. - * @pre \code stride_length != 0 \endcode The pointer to the stride length - * must not be a NULL pointer. - * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of - * values per frame must not be a NULL pointer. - * @pre \code type != 0 \endcode The pointer to the data type must not - * be a NULL pointer. - * @details This does only work for numerical (int, float, double) data. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_data_vector_get - (tng_trajectory_t tng_data, - const int64_t block_id, - void **values, - int64_t *n_frames, - int64_t *stride_length, - int64_t *n_values_per_frame, - char *type); - -/** - * @brief Read and retrieve non-particle data, in a specific interval. Obsolete! - * @param tng_data is a trajectory data container. tng_data->input_file_path specifies - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param block_id is the id number of the particle data block to read. - * @param start_frame_nr is the index number of the first frame to read. - * @param end_frame_nr is the index number of the last frame to read. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @param values is a pointer to a 2-dimensional array (memory unallocated), which - * will be filled with data. The array will be sized - * (n_frames * n_values_per_frame). - * Since ***values is allocated in this function it is the callers - * responsibility to free the memory. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before - * the last frame. - * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of - * values per frame must not be a NULL pointer. - * @pre \code type != 0 \endcode The pointer to the data type must not - * be a NULL pointer. - * @details This function is obsolete and only retained for compatibility. Use - * tng_data_vector_interval_get() instead. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_data_interval_get - (tng_trajectory_t tng_data, - const int64_t block_id, - const int64_t start_frame_nr, - const int64_t end_frame_nr, - const char hash_mode, - union data_values ***values, - int64_t *n_values_per_frame, - char *type); - -/** - * @brief Read and retrieve a vector (1D array) of non-particle data, - * in a specific interval. - * @param tng_data is a trajectory data container. tng_data->input_file_path specifies - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param block_id is the id number of the particle data block to read. - * @param start_frame_nr is the index number of the first frame to read. - * @param end_frame_nr is the index number of the last frame to read. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @param values is a pointer to a 1-dimensional array (memory unallocated), which - * will be filled with data. The length of the array will be (n_frames * n_values_per_frame). - * Since **values is allocated in this function it is the callers - * responsibility to free the memory. - * @param stride_length is set to the stride length (writing interval) of - * the data. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before - * the last frame. - * @pre \code stride_length != 0 \endcode The pointer to the stride length - * must not be a NULL pointer. - * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of - * values per frame must not be a NULL pointer. - * @pre \code type != 0 \endcode The pointer to the data type must not - * be a NULL pointer. - * @details This does only work for numerical (int, float, double) data. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_data_vector_interval_get - (tng_trajectory_t tng_data, - const int64_t block_id, - const int64_t start_frame_nr, - const int64_t end_frame_nr, - const char hash_mode, - void **values, - int64_t *stride_length, - int64_t *n_values_per_frame, - char *type); - -/** - * @brief Retrieve particle data, from the last read frame set. Obsolete! - * @details The particle dimension of the returned values array is translated - * to real particle numbering, i.e. the numbering of the actual molecular - * system. - * @param tng_data is a trajectory data container. tng_data->input_file_path - * specifies which file to read from. If the file (input_file) is not open it - * will be opened. - * @param block_id is the id number of the particle data block to read. - * @param values is a pointer to a 3-dimensional array (memory unallocated), which - * will be filled with data. The array will be sized - * (n_frames * n_particles * n_values_per_frame). - * Since ****values is allocated in this function it is the callers - * responsibility to free the memory. - * @param n_frames is set to the number of frames in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param n_particles is set to the number of particles in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n_frames != 0 \endcode The pointer to the number of frames - * must not be a NULL pointer. - * @pre \code n_particles != 0 \endcode The pointer to the number of particles must - * not be a NULL pointer. - * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of - * values per frame must not be a NULL pointer. - * @pre \code type != 0 \endcode The pointer to the data type must not - * be a NULL pointer. - * @details This function is obsolete and only retained for compatibility. Use - * tng_particle_data_vector_get() instead. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_particle_data_get - (tng_trajectory_t tng_data, - const int64_t block_id, - union data_values ****values, - int64_t *n_frames, - int64_t *n_particles, - int64_t *n_values_per_frame, - char *type); - -/** - * @brief Retrieve a vector (1D array) of particle data, from the last read frame set. - * @details The particle dimension of the returned values array is translated - * to real particle numbering, i.e. the numbering of the actual molecular - * system. - * @param tng_data is a trajectory data container. tng_data->input_file_path - * specifies which file to read from. If the file (input_file) is not open it - * will be opened. - * @param block_id is the id number of the particle data block to read. - * @param values is a pointer to a 1-dimensional array (memory unallocated), which - * will be filled with data. The length of the array will be - * (n_frames * n_particles * n_values_per_frame). - * Since **values is allocated in this function it is the callers - * responsibility to free the memory. - * @param n_frames is set to the number of frames in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param stride_length is set to the stride length of the returned data. - * @param n_particles is set to the number of particles in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n_particles != 0 \endcode The pointer to the number of particles must - * not be a NULL pointer. - * @pre \code stride_length != 0 \endcode The pointer to the stride length - * must not be a NULL pointer. - * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of - * values per frame must not be a NULL pointer. - * @pre \code type != 0 \endcode The pointer to the data type must not - * be a NULL pointer. - * @details This does only work for numerical (int, float, double) data. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_get - (tng_trajectory_t tng_data, - const int64_t block_id, - void **values, - int64_t *n_frames, - int64_t *stride_length, - int64_t *n_particles, - int64_t *n_values_per_frame, - char *type); - -/** - * @brief Read and retrieve particle data, in a specific interval. Obsolete! - * @details The particle dimension of the returned values array is translated - * to real particle numbering, i.e. the numbering of the actual molecular - * system. - * @param tng_data is a trajectory data container. tng_data->input_file_path specifies - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param block_id is the id number of the particle data block to read. - * @param start_frame_nr is the index number of the first frame to read. - * @param end_frame_nr is the index number of the last frame to read. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @param values is a pointer to a 3-dimensional array (memory unallocated), which - * will be filled with data. The array will be sized - * (n_frames * n_particles * n_values_per_frame). - * Since ****values is allocated in this function it is the callers - * responsibility to free the memory. - * @param n_particles is set to the number of particles in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n_frames != 0 \endcode The pointer to the number of frames - * must not be a NULL pointer. - * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before - * the last frame. - * @pre \code n_particles != 0 \endcode The pointer to the number of particles must - * not be a NULL pointer. - * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of - * values per frame must not be a NULL pointer. - * @pre \code type != 0 \endcode The pointer to the data type must not - * be a NULL pointer. - * @details This function is obsolete and only retained for compatibility. Use - * tng_particle_data_vector_interval_get() instead. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_particle_data_interval_get - (tng_trajectory_t tng_data, - const int64_t block_id, - const int64_t start_frame_nr, - const int64_t end_frame_nr, - const char hash_mode, - union data_values ****values, - int64_t *n_particles, - int64_t *n_values_per_frame, - char *type); - -/** - * @brief Read and retrieve a vector (1D array) particle data, in a - * specific interval. - * @details The particle dimension of the returned values array is translated - * to real particle numbering, i.e. the numbering of the actual molecular - * system. - * @param tng_data is a trajectory data container. tng_data->input_file_path specifies - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param block_id is the id number of the particle data block to read. - * @param start_frame_nr is the index number of the first frame to read. - * @param end_frame_nr is the index number of the last frame to read. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @param values is a pointer to a 1-dimensional array (memory unallocated), which - * will be filled with data. The length of the array will be - * (n_frames * n_particles * n_values_per_frame). - * Since **values is allocated in this function it is the callers - * responsibility to free the memory. - * @param stride_length is set to the stride length (writing interval) of - * the data. - * @param n_particles is set to the number of particles in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before - * the last frame. - * @pre \code n_particles != 0 \endcode The pointer to the number of particles must - * not be a NULL pointer. - * @pre \code stride_length != 0 \endcode The pointer to the stride length - * must not be a NULL pointer. - * @pre \code n_values_per_frame != 0 \endcode The pointer to the number of - * values per frame must not be a NULL pointer. - * @pre \code type != 0 \endcode The pointer to the data type must not - * be a NULL pointer. - * @details This does only work for numerical (int, float, double) data. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_interval_get - (tng_trajectory_t tng_data, - const int64_t block_id, - const int64_t start_frame_nr, - const int64_t end_frame_nr, - const char hash_mode, - void **values, - int64_t *n_particles, - int64_t *stride_length, - int64_t *n_values_per_frame, - char *type); - -/** - * @brief Get the stride length of a specific data (particle dependency does not matter) - * block, either in the current frame set or of a specific frame. - * @param tng_data is the trajectory data container. - * @param block_id is the block ID of the data block, of which to retrieve the - * stride length of the data. - * @param frame is the frame from which to get the stride length. If frame is set to -1 - * no specific frame will be used, but instead the first frame, starting from the last read - * frame set, containing the data block will be used. - * @param stride_length is set to the value of the stride length of the data block. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_data_get_stride_length - (const tng_trajectory_t tng_data, - const int64_t block_id, - int64_t frame, - int64_t *stride_length); - -/** - * @brief Get the date and time of initial file creation in ISO format (string). - * @param tng_data is a trajectory data container. - * @param time is a pointer to the string in which the date will be stored. Memory - * must be reserved beforehand. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code time != 0 \endcode The pointer to the time must not be a NULL - * pointer. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_time_get_str - (const tng_trajectory_t tng_data, - char *time); -/** @} */ /* end of group1 */ - -/** @defgroup group2 High-level API - * These functions make it easier to access and output TNG data. They - * are recommended unless there is a special reason to use the more - * detailed functions available in the low-level API. - * @{ - */ - -/** - * @brief High-level function for opening and initializing a TNG trajectory. - * @param filename is a string containing the name of the trajectory to open. - * @param mode specifies the file mode of the trajectory. Can be set to 'r', - * 'w' or 'a' for reading, writing or appending respectively. - * @param tng_data_p is a pointer to the opened trajectory. This will be - * allocated by the TNG library. The trajectory must be - * closed by the user, whereby memory is freed. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code filename != 0 \endcode The pointer to the filename must not be a - * NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_open - (const char *filename, - const char mode, - tng_trajectory_t *tng_data_p); - -/** - * @brief High-level function for closing a TNG trajectory. - * @param tng_data_p is a pointer to the trajectory to close. The memory - * will be freed after finalising the writing. - * @return TNG_SUCCESS (0) if successful. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_close - (tng_trajectory_t *tng_data_p); - -/** - * @brief High-level function for getting the time (in seconds) of a frame. - * @param tng_data is the trajectory containing the frame. - * @param frame_nr is the frame number of which to get the time. - * @param time is set to the time (in seconds) of the specified frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code time != 0 \endcode The pointer to the time must not be a - * NULL pointer. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if a - * minor error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_time_of_frame_get - (tng_trajectory_t tng_data, - const int64_t frame_nr, - double *time); - -/* - * @brief High-level function for getting the molecules in the mol system. - * @param tng_data is the trajectory containing the mol system. - * @param n_mols is set to the number of molecules in the system. - * @param molecule_cnt_list will be pointing to the list of counts of each molecule - * in the mol system. - * @param mols pointing to the list of molecules in the mol system. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n_mols != 0 \endcode The pointer to the number of molecules must - * not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful. - */ -/*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecules_get - (tng_trajectory_t tng_data, - int64_t *n_mols, - int64_t **molecule_cnt_list, - tng_molecule_t *mols); -*/ -/* - * @brief High-level function for adding a molecule to the mol system. - * @param tng_data is the trajectory containing the mol system. - * @param name is the name of the molecule to add. - * @param cnt is the count of the molecule. - * @param mol is set to point to the newly created molecule. - * @pre \code name != 0 \endcode The pointer to the name must not be a - * NULL pointer. - * @pre \code cnt >= 0 \endcode The requested count must be >= 0. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured or TNG_CRITICAL (2) if a major error has occured. - */ -/*tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_molecule_add - (tng_trajectory_t tng_data, - const char *name, - const int64_t cnt, - tng_molecule_t *mol); -*/ -/* -// tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_get -// (tng_trajectory_t tng_data, -// const tng_molecule_t mol, -// int64_t *n_particles, -// char ***names, -// char ***types, -// char ***res_names, -// int64_t **res_ids, -// char ***chain_names, -// int64_t **chain_ids); -// -// tng_function_status DECLSPECDLLEXPORT tng_util_molecule_particles_set -// (tng_trajectory_t tng_data, -// tng_molecule_t mol, -// const int64_t n_particles, -// const char **names, -// const char **types, -// const char **res_names, -// const int64_t *res_ids, -// const char **chain_names, -// const int64_t *chain_ids); -*/ -/** - * @brief High-level function for reading the positions of all particles - * from all frames. - * @param tng_data is the trajectory to read from. - * @param positions will be set to point at a 1-dimensional array of floats, - * which will contain the positions. The data is stored sequentially in order - * of frames. For each frame the positions (x, y and z coordinates) are stored. - * The variable may point at already allocated memory or be a NULL pointer. - * The memory must be freed afterwards. - * @param stride_length will be set to the writing interval of the stored data. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code positions != 0 \endcode The pointer to the positions array - * must not be a NULL pointer. - * @pre \code stride_length != 0 \endcode The pointer to the stride length - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_pos_read - (tng_trajectory_t tng_data, - float **positions, - int64_t *stride_length); - -/** - * @brief High-level function for reading the velocities of all particles - * from all frames. - * @param tng_data is the trajectory to read from. - * @param velocities will be set to point at a 1-dimensional array of floats, - * which will contain the velocities. The data is stored sequentially in order - * of frames. For each frame the velocities (in x, y and z) are stored. The - * variable may point at already allocated memory or be a NULL pointer. - * The memory must be freed afterwards. - * @param stride_length will be set to the writing interval of the stored data. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code velocities != 0 \endcode The pointer to the velocities array - * must not be a NULL pointer. - * @pre \code stride_length != 0 \endcode The pointer to the stride length - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_vel_read - (tng_trajectory_t tng_data, - float **velocities, - int64_t *stride_length); - -/** - * @brief High-level function for reading the forces of all particles - * from all frames. - * @param tng_data is the trajectory to read from. - * @param forces will be set to point at a 1-dimensional array of floats, - * which will contain the forces. The data is stored sequentially in order - * of frames. For each frame the forces (in x, y and z) are stored. The - * variable may point at already allocated memory or be a NULL pointer. - * The memory must be freed afterwards. - * @param stride_length will be set to the writing interval of the stored data. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code forces != 0 \endcode The pointer to the forces array - * must not be a NULL pointer. - * @pre \code stride_length != 0 \endcode The pointer to the stride length - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_force_read - (tng_trajectory_t tng_data, - float **forces, - int64_t *stride_length); - -/** - * @brief High-level function for reading the box shape from all frames. - * @param tng_data is the trajectory to read from. - * @param box_shape will be set to point at a 1-dimensional array of floats, - * which will contain the box shape. The data is stored sequentially in order - * of frames. The variable may point at already allocated memory or be a NULL pointer. - * If the box shape is not modified during the trajectory, but as general data, - * that will be returned instead. - * @param stride_length will be set to the writing interval of the stored data. - * @details This function should only be used if number of values used to specify - * the box shape is known (by default TNG uses 9 values) since it does not - * return the number of values in the array. It is recommended to use - * tng_data_vector_interval_get() instead. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code box_shape != 0 \endcode The pointer to the box_shape array - * must not be a NULL pointer. - * @pre \code stride_length != 0 \endcode The pointer to the stride length - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read - (tng_trajectory_t tng_data, - float **box_shape, - int64_t *stride_length); - -/** - * @brief High-level function for reading the next frame of particle-dependent - * data of a specific type. - * @param tng_data is the trajectory to read from. - * @param block_id is the ID number of the block containing the data of interest. - * @param values will be set to point at a 1-dimensional array containing the - * requested data. The variable may point at already allocated memory or be a - * NULL pointer. The memory must be freed afterwards. - * @param data_type will be pointing to a character indicating the size of the - * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA. - * @param retrieved_frame_number will be pointing at the frame number of the - * returned frame. - * @param retrieved_time will be pointing at the time stamp of the returned - * frame. - * @details If no frame has been read before the first frame of the trajectory - * is read. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code values != 0 \endcode The pointer to the values array - * must not be a NULL pointer. - * @pre \code data_type != 0 \endcode The pointer to the data type of the - * returned data must not be a NULL pointer. - * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame - * number of the returned data must not be a NULL pointer. - * @pre \code retrieved_time != 0 \endcode The pointer to the time of the - * returned data must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_particle_data_next_frame_read - (tng_trajectory_t tng_data, - const int64_t block_id, - void **values, - char *data_type, - int64_t *retrieved_frame_number, - double *retrieved_time); - -/** - * @brief High-level function for reading the next frame of non-particle-dependent - * data of a specific type. - * @param tng_data is the trajectory to read from. - * @param block_id is the ID number of the block containing the data of interest. - * @param values will be set to point at a 1-dimensional array containing the - * requested data. The variable may point at already allocated memory or be a - * NULL pointer. The memory must be freed afterwards. - * @param data_type will be pointing to a character indicating the size of the - * data of the returned values, e.g. TNG_INT_DATA, TNG_FLOAT_DATA or TNG_DOUBLE_DATA. - * @param retrieved_frame_number will be pointing at the frame number of the - * returned frame. - * @param retrieved_time will be pointing at the time stamp of the returned - * frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code values != 0 \endcode The pointer to the values array - * must not be a NULL pointer. - * @pre \code data_type != 0 \endcode The pointer to the data type of the - * returned data must not be a NULL pointer. - * @pre \code retrieved_frame_number != 0 \endcode The pointer to the frame - * number of the returned data must not be a NULL pointer. - * @pre \code retrieved_time != 0 \endcode The pointer to the time of the - * returned data must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_non_particle_data_next_frame_read - (tng_trajectory_t tng_data, - const int64_t block_id, - void **values, - char *data_type, - int64_t *retrieved_frame_number, - double *retrieved_time); - -/** - * @brief High-level function for reading the positions of all particles - * from a specific range of frames. - * @param tng_data is the trajectory to read from. - * @param first_frame is the first frame to return position data from. - * @param last_frame is the last frame to return position data from. - * @param positions will be set to point at a 1-dimensional array of floats, - * which will contain the positions. The data is stored sequentially in order - * of frames. For each frame the positions (x, y and z coordinates) are stored. - * The variable may point at already allocated memory or be a NULL pointer. - * The memory must be freed afterwards. - * @param stride_length will be set to the writing interval of the stored data. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before - * the last frame. - * @pre \code positions != 0 \endcode The pointer to the positions array - * must not be a NULL pointer. - * @pre \code stride_length != 0 \endcode The pointer to the stride length - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_pos_read_range - (tng_trajectory_t tng_data, - const int64_t first_frame, - const int64_t last_frame, - float **positions, - int64_t *stride_length); - -/** - * @brief High-level function for reading the velocities of all particles - * from a specific range of frames. - * @param tng_data is the trajectory to read from. - * @param first_frame is the first frame to return position data from. - * @param last_frame is the last frame to return position data from. - * @param velocities will be set to point at a 1-dimensional array of floats, - * which will contain the velocities. The data is stored sequentially in order - * of frames. For each frame the velocities (in x, y and z) are stored. The - * variable may point at already allocated memory or be a NULL pointer. - * The memory must be freed afterwards. - * @param stride_length will be set to the writing interval of the stored data. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before - * the last frame. - * @pre \code velocities != 0 \endcode The pointer to the velocities array - * must not be a NULL pointer. - * @pre \code stride_length != 0 \endcode The pointer to the stride length - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_vel_read_range - (tng_trajectory_t tng_data, - const int64_t first_frame, - const int64_t last_frame, - float **velocities, - int64_t *stride_length); - -/** - * @brief High-level function for reading the forces of all particles - * from a specific range of frames. - * @param tng_data is the trajectory to read from. - * @param first_frame is the first frame to return position data from. - * @param last_frame is the last frame to return position data from. - * @param forces will be set to point at a 1-dimensional array of floats, - * which will contain the forces. The data is stored sequentially in order - * of frames. For each frame the forces (in x, y and z) are stored. The - * variable may point at already allocated memory or be a NULL pointer. - * The memory must be freed afterwards. - * @param stride_length will be set to the writing interval of the stored data. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before - * the last frame. - * @pre \code forces != 0 \endcode The pointer to the forces array - * must not be a NULL pointer. - * @pre \code stride_length != 0 \endcode The pointer to the stride length - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_force_read_range - (tng_trajectory_t tng_data, - const int64_t first_frame, - const int64_t last_frame, - float **forces, - int64_t *stride_length); - -/** - * @brief High-level function for reading the box shape - * from a specific range of frames. - * @param tng_data is the trajectory to read from. - * @param first_frame is the first frame to return position data from. - * @param last_frame is the last frame to return position data from. - * @param box_shape will be set to point at a 1-dimensional array of floats, - * which will contain the box shape. The data is stored sequentially in order - * of frames. - * If the box shape is not modified during the trajectory, but as general data, - * that will be returned instead. The - * variable may point at already allocated memory or be a NULL pointer. - * The memory must be freed afterwards. - * @param stride_length will be set to the writing interval of the stored data. - * @details This function should only be used if number of values used to specify - * the box shape is known (by default TNG uses 9 values) since it does not - * return the number of values in the array. It is recommended to use - * tng_data_vector_interval_get() instead. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code start_frame_nr <= end_frame_nr \endcode The first frame must be before - * the last frame. - * @pre \code box_shape != 0 \endcode The pointer to the box_shape array - * must not be a NULL pointer. - * @pre \code stride_length != 0 \endcode The pointer to the stride length - * must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read_range - (tng_trajectory_t tng_data, - const int64_t first_frame, - const int64_t last_frame, - float **box_shape, - int64_t *stride_length); - -/** - * @brief High-level function for setting the writing interval of data blocks. - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @param n_values_per_frame is the number of values to store per frame. If the - * data is particle dependent there will be n_values_per_frame stored per - * particle each frame. - * @param block_id is the ID of the block, of which to set the output interval. - * @param block_name is a string that will be used as name of the block. Only - * required if the block did not exist, i.e. a new block is created. - * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the - * data is not related to specific particles (e.g. box shape) or - * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. - * positions). Only required if the block did not exist, i.e. a new block is - * created. - * @param compression is the compression routine to use when writing the data. - * Only required if the block did not exist, i.e. a new block is created. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code i >= 0 \endcode The writing interval must be >= 0. - * @details n_values_per_frame, block_name, particle_dependency and - * compression are only used if the data block did not exist before calling - * this function, in which case it is created. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_set - (tng_trajectory_t tng_data, - const int64_t i, - const int64_t n_values_per_frame, - const int64_t block_id, - const char *block_name, - const char particle_dependency, - const char compression); - -/** - * @brief High-level function for setting the writing interval of data blocks - * containing double precision data. - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @param n_values_per_frame is the number of values to store per frame. If the - * data is particle dependent there will be n_values_per_frame stored per - * particle each frame. - * @param block_id is the ID of the block, of which to set the output interval. - * @param block_name is a string that will be used as name of the block. Only - * required if the block did not exist, i.e. a new block is created. - * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the - * data is not related to specific particles (e.g. box shape) or - * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. - * positions). Only required if the block did not exist, i.e. a new block is - * created. - * @param compression is the compression routine to use when writing the data. - * Only required if the block did not exist, i.e. a new block is created. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code i >= 0 \endcode The writing interval must be >= 0. - * @details n_values_per_frame, block_name, particle_dependency and - * compression are only used if the data block did not exist before calling - * this function, in which case it is created. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_double_set - (tng_trajectory_t tng_data, - const int64_t i, - const int64_t n_values_per_frame, - const int64_t block_id, - const char *block_name, - const char particle_dependency, - const char compression); - -/** - * @brief High-level function for setting the writing interval of data blocks. - * Obsolete! Use tng_util_generic_write_interval_set() - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @param n_values_per_frame is the number of values to store per frame. If the - * data is particle dependent there will be n_values_per_frame stored per - * particle each frame. - * @param block_id is the ID of the block, of which to set the output interval. - * @param block_name is a string that will be used as name of the block. Only - * required if the block did not exist, i.e. a new block is created. - * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the - * data is not related to specific particles (e.g. box shape) or - * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. - * positions). Only required if the block did not exist, i.e. a new block is - * created. - * @param compression is the compression routine to use when writing the data. - * Only required if the block did not exist, i.e. a new block is created. - * @details n_values_per_frame, block_name, particle_dependency and - * compression are only used if the data block did not exist before calling - * this function, in which case it is created. - * This function is replaced by the more correcly named - * tng_util_generic_write_interval_set(), but is kept for compatibility. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_frequency_set - (tng_trajectory_t tng_data, - const int64_t i, - const int64_t n_values_per_frame, - const int64_t block_id, - const char *block_name, - const char particle_dependency, - const char compression); - -/** - * @brief High-level function for setting the writing interval of position - * data blocks. - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code i >= 0 \endcode The writing interval must be >= 0. - * @details This function uses tng_util_generic_write_interval_set() and will - * create a positions data block if none exists. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_set - (tng_trajectory_t tng_data, - const int64_t i); - -/** - * @brief High-level function for setting the writing interval of position - * data blocks containing double precision data. - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code i >= 0 \endcode The writing interval must be >= 0. - * @details This function uses tng_util_generic_write_interval_set() and will - * create a positions data block if none exists. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_double_set - (tng_trajectory_t tng_data, - const int64_t i); - -/** - * @brief High-level function for setting the writing interval of position - * data blocks. Obsolete! Use tng_util_pos_write_interval_set() - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code i >= 0 \endcode The writing interval must be >= 0. - * @details This function uses tng_util_generic_write_interval_set() and will - * create a positions data block if none exists. - * This function is replaced by the more correcly named - * tng_util_pos_write_interval_set(), but is kept for compatibility. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_frequency_set - (tng_trajectory_t tng_data, - const int64_t i); - -/** - * @brief High-level function for setting the writing interval of velocity - * data blocks. - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code i >= 0 \endcode The writing interval must be >= 0. - * @details This function uses tng_util_generic_write_interval_set() and will - * create a velocities data block if none exists. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_set - (tng_trajectory_t tng_data, - const int64_t i); - -/** - * @brief High-level function for setting the writing interval of velocity - * data blocks containing double precision data. - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code i >= 0 \endcode The writing interval must be >= 0. - * @details This function uses tng_util_generic_write_interval_set() and will - * create a velocities data block if none exists. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_double_set - (tng_trajectory_t tng_data, - const int64_t i); - -/** - * @brief High-level function for setting the writing interval of velocity - * data blocks. Obsolete! Use tng_util_vel_write_interval_set() - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @details This function uses tng_util_generic_write_interval_set() and will - * create a velocities data block if none exists. - * This function is replaced by the more correcly named - * tng_util_vel_write_interval_set(), but is kept for compatibility. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_frequency_set - (tng_trajectory_t tng_data, - const int64_t i); - -/** - * @brief High-level function for setting the writing interval of force - * data blocks. - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code i >= 0 \endcode The writing interval must be >= 0. - * @details This function uses tng_util_generic_write_interval_set() and will - * create a forces data block if none exists. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_set - (tng_trajectory_t tng_data, - const int64_t i); - -/** - * @brief High-level function for setting the writing interval of force - * data blocks containing double precision data. - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code i >= 0 \endcode The writing interval must be >= 0. - * @details This function uses tng_util_generic_write_interval_set() and will - * create a forces data block if none exists. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_double_set - (tng_trajectory_t tng_data, - const int64_t i); - -/** - * @brief High-level function for setting the writing interval of force - * data blocks. Obsolete! Use tng_util_force_write_interval_set() - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @details This function uses tng_util_generic_write_interval_set() and will - * create a forces data block if none exists. - * This function is replaced by the more correcly named - * tng_util_force_write_interval_set(), but is kept for compatibility. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_force_write_frequency_set - (tng_trajectory_t tng_data, - const int64_t i); - -/** - * @brief High-level function for setting the writing interval of box shape - * data blocks. - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code i >= 0 \endcode The writing interval must be >= 0. - * @details This function uses tng_util_generic_write_interval_set() and will - * create a box shape data block if none exists. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_set - (tng_trajectory_t tng_data, - const int64_t i); - -/** - * @brief High-level function for setting the writing interval of box shape - * data blocks containing double precision data. - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code i >= 0 \endcode The writing interval must be >= 0. - * @details This function uses tng_util_generic_write_interval_set() and will - * create a box shape data block if none exists. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_double_set - (tng_trajectory_t tng_data, - const int64_t i); - -/** - * @brief High-level function for setting the writing interval of velocity - * data blocks. Obsolete! Use tng_util_box_shape_write_interval_set() - * @param tng_data is the trajectory to use. - * @param i is the output interval, i.e. i == 10 means data written every 10th - * frame. - * @details This function uses tng_util_generic_write_interval_set() and will - * create a box shape data block if none exists. - * This function is replaced by the more correcly named - * tng_util_box_shape_write_interval_set(), but is kept for compatibility. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_frequency_set - (tng_trajectory_t tng_data, - const int64_t i); - -/** - * @brief High-level function for writing data of one frame to a data block. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param values is a 1D array of data to add. The array should be of length - * n_particles * n_values_per_frame if writing particle related data, otherwise - * it should be n_values_per_frame. - * @param n_values_per_frame is the number of values to store per frame. If the - * data is particle dependent there will be n_values_per_frame stored per - * particle each frame. - * @param block_id is the ID of the block, of which to set the output interval. - * @param block_name is a string that will be used as name of the block. Only - * required if the block did not exist, i.e. a new block is created. - * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the - * data is not related to specific particles (e.g. box shape) or - * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. - * positions). Only required if the block did not exist, i.e. a new block is - * created. - * @param compression is the compression routine to use when writing the data. - * Only required if the block did not exist, i.e. a new block is created. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code values != 0 \endcode The pointer to the values array must not - * be a NULL pointer. - * @details n_values_per_frame, block_name, particle_dependency and - * compression are only used if the data block did not exist before calling - * this function, in which case it is created. - * N.b. Data is written a whole block at a time. The data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_generic_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const float *values, - const int64_t n_values_per_frame, - const int64_t block_id, - const char *block_name, - const char particle_dependency, - const char compression); - -/** - * @brief High-level function for writing data of one frame to a double precision - * data block. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param values is a 1D array of data to add. The array should be of length - * n_particles * n_values_per_frame if writing particle related data, otherwise - * it should be n_values_per_frame. - * @param n_values_per_frame is the number of values to store per frame. If the - * data is particle dependent there will be n_values_per_frame stored per - * particle each frame. - * @param block_id is the ID of the block, of which to set the output interval. - * @param block_name is a string that will be used as name of the block. Only - * required if the block did not exist, i.e. a new block is created. - * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the - * data is not related to specific particles (e.g. box shape) or - * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. - * positions). Only required if the block did not exist, i.e. a new block is - * created. - * @param compression is the compression routine to use when writing the data. - * Only required if the block did not exist, i.e. a new block is created. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code values != 0 \endcode The pointer to the values array must not - * be a NULL pointer. - * @details n_values_per_frame, block_name, particle_dependency and - * compression are only used if the data block did not exist before calling - * this function, in which case it is created. - * N.b. Data is written a whole block at a time. The data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_generic_double_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double *values, - const int64_t n_values_per_frame, - const int64_t block_id, - const char *block_name, - const char particle_dependency, - const char compression); - -/** - * @brief High-level function for adding data to positions data blocks. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param positions is a 1D array of data to add. The array should be of length - * n_particles * 3. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code positions != 0 \endcode The pointer to the positions array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_write() and will - * create a positions data block if none exists. Positions are stored as three - * values per frame and compressed using TNG compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_pos_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const float *positions); - -/** - * @brief High-level function for adding data to positions data blocks at double - * precision. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param positions is a 1D array of data to add. The array should be of length - * n_particles * 3. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code positions != 0 \endcode The pointer to the positions array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_write() and will - * create a positions data block if none exists. Positions are stored as three - * values per frame and compressed using TNG compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_pos_double_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double *positions); - -/** - * @brief High-level function for adding data to velocities data blocks. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param velocities is a 1D array of data to add. The array should be of length - * n_particles * 3. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code velocities != 0 \endcode The pointer to the velocities array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_write() and will - * create a velocities data block if none exists. Velocities are stored as three - * values per frame and compressed using TNG compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_vel_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const float *velocities); - -/** - * @brief High-level function for adding data to velocities data blocks at double - * precision. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param velocities is a 1D array of data to add. The array should be of length - * n_particles * 3. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code velocities != 0 \endcode The pointer to the velocities array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_write() and will - * create a velocities data block if none exists. Velocities are stored as three - * values per frame and compressed using TNG compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_vel_double_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double *velocities); - -/** - * @brief High-level function for adding data to forces data blocks. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param forces is a 1D array of data to add. The array should be of length - * n_particles * 3. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code forces != 0 \endcode The pointer to the forces array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_write() and will - * create a forces data block if none exists. Forces are stored as three - * values per frame and compressed using gzip compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_force_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const float *forces); - -/** - * @brief High-level function for adding data to forces data blocks at double - * precision. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param forces is a 1D array of data to add. The array should be of length - * n_particles * 3. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code forces != 0 \endcode The pointer to the forces array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_write() and will - * create a forces data block if none exists. Forces are stored as three - * values per frame and compressed using gzip compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_force_double_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double *forces); - -/** - * @brief High-level function for adding data to box shape data blocks. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param box_shape is a 1D array of data to add. The array should be of length 9. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_write() and will - * create a box shape data block if none exists. Box shapes are stored as 9 - * values per frame and compressed using TNG compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const float *box_shape); - -/** - * @brief High-level function for adding data to box shape data blocks at double - * precision. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param box_shape is a 1D array of data to add. The array should be of length 9. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_write() and will - * create a box shape data block if none exists. Box shapes are stored as 9 - * values per frame and compressed using TNG compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_double_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double *box_shape); - -/** - * @brief High-level function for writing data of one frame to a data block. - * If the frame is at the beginning of a frame set the time stamp of the frame - * set is set. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param time is the time stamp of the frame (in seconds). - * @param values is a 1D array of data to add. The array should be of length - * n_particles * n_values_per_frame if writing particle related data, otherwise - * it should be n_values_per_frame. - * @param n_values_per_frame is the number of values to store per frame. If the - * data is particle dependent there will be n_values_per_frame stored per - * particle each frame. - * @param block_id is the ID of the block, of which to set the output interval. - * @param block_name is a string that will be used as name of the block. Only - * required if the block did not exist, i.e. a new block is created. - * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the - * data is not related to specific particles (e.g. box shape) or - * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. - * positions). Only required if the block did not exist, i.e. a new block is - * created. - * @param compression is the compression routine to use when writing the data. - * Only required if the block did not exist, i.e. a new block is created. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code time >= 0 \endcode The time stamp must be >= 0. - * @pre \code values != 0 \endcode The pointer to the values array must not - * be a NULL pointer. - * @details n_values_per_frame, block_name, particle_dependency and - * compression are only used if the data block did not exist before calling - * this function, in which case it is created. - * N.b. Data is written a whole block at a time. The data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double time, - const float *values, - const int64_t n_values_per_frame, - const int64_t block_id, - const char *block_name, - const char particle_dependency, - const char compression); - -/** - * @brief High-level function for writing data of one frame to a double precision - * data block. If the frame is at the beginning of a frame set the time stamp of - * the frame set is set. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param time is the time stamp of the frame (in seconds). - * @param values is a 1D array of data to add. The array should be of length - * n_particles * n_values_per_frame if writing particle related data, otherwise - * it should be n_values_per_frame. - * @param n_values_per_frame is the number of values to store per frame. If the - * data is particle dependent there will be n_values_per_frame stored per - * particle each frame. - * @param block_id is the ID of the block, of which to set the output interval. - * @param block_name is a string that will be used as name of the block. Only - * required if the block did not exist, i.e. a new block is created. - * @param particle_dependency should be TNG_NON_PARTICLE_BLOCK_DATA (0) if the - * data is not related to specific particles (e.g. box shape) or - * TNG_PARTICLE_BLOCK_DATA (1) is it is related to specific particles (e.g. - * positions). Only required if the block did not exist, i.e. a new block is - * created. - * @param compression is the compression routine to use when writing the data. - * Only required if the block did not exist, i.e. a new block is created. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code time >= 0 \endcode The time stamp must be >= 0. - * @pre \code values != 0 \endcode The pointer to the values array must not - * be a NULL pointer. - * @details n_values_per_frame, block_name, particle_dependency and - * compression are only used if the data block did not exist before calling - * this function, in which case it is created. - * N.b. Data is written a whole block at a time. The data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_double_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double time, - const double *values, - const int64_t n_values_per_frame, - const int64_t block_id, - const char *block_name, - const char particle_dependency, - const char compression); - -/** - * @brief High-level function for adding data to positions data blocks. If the - * frame is at the beginning of a frame set the time stamp of the frame set - * is set. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param time is the time stamp of the frame (in seconds). - * @param positions is a 1D array of data to add. The array should be of length - * n_particles * 3. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code time >= 0 \endcode The time stamp must be >= 0. - * @pre \code positions != 0 \endcode The pointer to the positions array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_with_time_write() and will - * create a positions data block if none exists. Positions are stored as three - * values per frame and compressed using TNG compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double time, - const float *positions); - -/** - * @brief High-level function for adding data to positions data blocks at double - * precision. If the frame is at the beginning of a frame set the time stamp of - * the frame set is set. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param time is the time stamp of the frame (in seconds). - * @param positions is a 1D array of data to add. The array should be of length - * n_particles * 3. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code time >= 0 \endcode The time stamp must be >= 0. - * @pre \code positions != 0 \endcode The pointer to the positions array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_with_time_double_write() and will - * create a positions data block if none exists. Positions are stored as three - * values per frame and compressed using TNG compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_double_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double time, - const double *positions); - -/** - * @brief High-level function for adding data to velocities data blocks. If the - * frame is at the beginning of a frame set the time stamp of the frame set - * is set. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param time is the time stamp of the frame (in seconds). - * @param velocities is a 1D array of data to add. The array should be of length - * n_particles * 3. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code time >= 0 \endcode The time stamp must be >= 0. - * @pre \code velocities != 0 \endcode The pointer to the velocities array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_with_time_write() and will - * create a velocities data block if none exists. Velocities are stored as three - * values per frame and compressed using TNG compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double time, - const float *velocities); - -/** - * @brief High-level function for adding data to velocities data blocks at - * double precision. If the frame is at the beginning of a frame set the - * time stamp of the frame set is set. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param time is the time stamp of the frame (in seconds). - * @param velocities is a 1D array of data to add. The array should be of length - * n_particles * 3. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code time >= 0 \endcode The time stamp must be >= 0. - * @pre \code velocities != 0 \endcode The pointer to the velocities array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_with_time_double_write() and will - * create a velocities data block if none exists. Velocities are stored as three - * values per frame and compressed using TNG compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_double_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double time, - const double *velocities); - -/** - * @brief High-level function for adding data to forces data blocks. If the - * frame is at the beginning of a frame set the time stamp of the frame set - * is set. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param time is the time stamp of the frame (in seconds). - * @param forces is a 1D array of data to add. The array should be of length - * n_particles * 3. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code time >= 0 \endcode The time stamp must be >= 0. - * @pre \code forces != 0 \endcode The pointer to the forces array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_with_time_write() and will - * create a forces data block if none exists. Forces are stored as three - * values per frame and compressed using gzip compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double time, - const float *forces); - -/** - * @brief High-level function for adding data to forces data blocks at - * double precision. If the frame is at the beginning of a frame set - * the time stamp of the frame set is set. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param time is the time stamp of the frame (in seconds). - * @param forces is a 1D array of data to add. The array should be of length - * n_particles * 3. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code time >= 0 \endcode The time stamp must be >= 0. - * @pre \code forces != 0 \endcode The pointer to the forces array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_with_time_double_write() and will - * create a forces data block if none exists. Forces are stored as three - * values per frame and compressed using gzip compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_double_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double time, - const double *forces); - -/** - * @brief High-level function for adding data to box shape data blocks. If the - * frame is at the beginning of a frame set the time stamp of the frame set - * is set. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param time is the time stamp of the frame (in seconds). - * @param box_shape is a 1D array of data to add. The array should be of length 9. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code time >= 0 \endcode The time stamp must be >= 0. - * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_with_time_write() and will - * create a box shape data block if none exists. Box shapes are stored as 9 - * values per frame and compressed using TNG compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double time, - const float *box_shape); - -/** - * @brief High-level function for adding data to box shape data blocks at - * double precision. If the frame is at the beginning of a frame set the - * time stamp of the frame set is set. - * @param tng_data is the trajectory to use. - * @param frame_nr is the frame number of the data. - * @param time is the time stamp of the frame (in seconds). - * @param box_shape is a 1D array of data to add. The array should be of length 9. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code frame_nr >= 0 \endcode The frame number to write must be >= 0. - * @pre \code time >= 0 \endcode The time stamp must be >= 0. - * @pre \code box_shape != 0 \endcode The pointer to the box_shape array must not - * be a NULL pointer. - * @details This function uses tng_util_generic_with_time_double_write() and will - * create a box shape data block if none exists. Box shapes are stored as 9 - * values per frame and compressed using TNG compression. - * N.b. Since compressed data is written a whole block at a time the data is not - * actually written to disk until the frame set is finished or the TNG - * trajectory is closed. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_double_write - (tng_trajectory_t tng_data, - const int64_t frame_nr, - const double time, - const double *box_shape); - -/** - * @brief High-level function for getting the compression method and - * multiplication factor of the last read frame of a specific data block. - * @param tng_data is the trajectory to use. - * @param block_id is the ID number of the block containing the data of - * interest. - * @param codec_id will be set to the value of the codec_id of the - * compression of the data block. See tng_compression for more details. - * @param factor will be set to the multiplication factor applied to - * the values before compression, in order to get integers from them. - * factor is 1/precision. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code codec_id != 0 \endcode The pointer to the returned codec id - * must not be a NULL pointer. - * @pre \code factor != 0 \endcode The pointer to the returned multiplication - * factor must not be a NULL pointer. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as invalid mode) or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_frame_current_compression_get - (tng_trajectory_t tng_data, - const int64_t block_id, - int64_t *codec_id, - float *factor); - -/** @brief High-level function for determining the next frame with data and what - * data blocks have data for that frame. The search can be limited to certain - * data blocks. - * @param tng_data is the trajectory to use. - * @param current_frame is the frame that was last read, from where to start - * looking for data. - * @param n_requested_data_block_ids is the number of data blocks listed in - * requested_data_block_ids. If this is 0 all data blocks will be taken into - * account. - * @param requested_data_block_ids is an array of data blocks to look for. - * @param next_frame will be set to the next frame with data. - * @param n_data_blocks_in_next_frame is set to the number of data blocks with - * data for next_frame. - * @param data_block_ids_in_next_frame is set to an array (of length - * n_data_blocks_in_next_frame) that lists the data block IDs with data for - * next_frame. It must be pointing at NULL or previously allocated memory. - * Memory for the array is allocated by this function. - * The memory must be freed by the client afterwards or - * there will be a memory leak. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code next_frame != 0 \endcode The pointer to the next frame must not - * be NULL. - * @pre \code n_data_blocks_in_next_frame != 0 \endcode The pointer to - * n_data_blocks_in_next_frame must not be NULL. - * @pre \code *data_block_ids_in_next_frame != 0 \endcode The pointer to the - * list of data block IDs must not be NULL. - * @pre \code n_requested_data_block_ids == 0 || requested_data_block_ids != 0 \endcode - * If the number of requested data blocks != 0 then the array of data block IDs must not be NULL. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured or TNG_CRITICAL (2) if a major error - * has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_next_frame_present_data_blocks_find - (tng_trajectory_t tng_data, - int64_t current_frame, - const int64_t n_requested_data_block_ids, - const int64_t *requested_data_block_ids, - int64_t *next_frame, - int64_t *n_data_blocks_in_next_frame, - int64_t **data_block_ids_in_next_frame); - -/* @brief High-level function for getting all data block ids and their names - * and stride lengths. - * @param tng_data is the trajectory to use. - * @param n_data_blocks is set to the number of data blocks in the trajectory. - * @param data_block_ids is set to an array (of length - * n_data_blocks) that lists the data block IDs in the trajectory. - * It must be pointing at NULL or previously allocated memory. - * Memory for the array is allocated by this function. - * The memory must be freed by the client afterwards or - * there will be a memory leak. - * @param data_block_names is set to an array (of length - * n_data_blocks) that contains the names of the data blocks. - * It must be pointing at NULL or previously allocated memory. - * Memory for the array is allocated by this function. - * The memory must be freed by the client afterwards or - * there will be a memory leak. - * @param stride_lengths is set to an array (of length - * n_data_blocks) that lists the stride lengths of the data blocks. - * It must be pointing at NULL or previously allocated memory. - * Memory for the array is allocated by this function. - * The memory must be freed by the client afterwards or - * there will be a memory leak. - * @param n_values_per_frame is set to an array (of length - * n_data_blocks) that lists the number of values per frame of the data blocks. - * It must be pointing at NULL or previously allocated memory. - * Memory for the array is allocated by this function. - * The memory must be freed by the client afterwards or - * there will be a memory leak. - * @param block_types is set to an array (of length - * n_data_blocks) that lists the block types of the data blocks. - * It must be pointing at NULL or previously allocated memory. - * Memory for the array is allocated by this function. - * The memory must be freed by the client afterwards or - * there will be a memory leak. - * @param dependencies is set to an array (of length - * n_data_blocks) that lists the dependencies of the data blocks. - * It must be pointing at NULL or previously allocated memory. - * Memory for the array is allocated by this function. - * The memory must be freed by the client afterwards or - * there will be a memory leak. - * @param compressions is set to an array (of length - * n_data_blocks) that lists the compressions of the data blocks. - * It must be pointing at NULL or previously allocated memory. - * Memory for the array is allocated by this function. - * The memory must be freed by the client afterwards or - * there will be a memory leak. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code n_data_blocks != 0 \endcode The pointer to - * n_data_blocks must not be NULL. - * @pre \code data_block_ids != 0 \endcode The pointer to the - * list of data block IDs must not be NULL. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured or TNG_CRITICAL (2) if a major error - * has occured. - */ -/* -tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_all_data_block_types_get - (tng_trajectory_t tng_data, - int64_t *n_data_blocks, - int64_t **data_block_ids, - char ***data_block_names, - int64_t **stride_lengths, - int64_t **n_values_per_frame, - char **block_types, - char **dependencies, - char **compressions); -*/ - -/** @brief Finds the frame set of the specified frame in order to prepare for writing - * after it. - * @param tng_data is the trajectory to use. - * @param prev_frame is the frame after which to start appending. - * @pre \code tng_data != 0 \endcode The trajectory container (tng_data) - * must be initialised before using it. - * @pre \code prev_frame >= 0 \endcode The previous frame must not be negative. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occured (such as not finding the requested frame) or TNG_CRITICAL (2) - * if a major error has occured. - */ -tng_function_status DECLSPECDLLEXPORT tng_util_prepare_append_after_frame - (tng_trajectory_t tng_data, - const int64_t prev_frame); - -/** @} */ /* end of group2 */ - - -#ifdef __cplusplus -} /* end extern "C" */ -#endif - -#endif /* TNG_IO_H */ diff --git a/include/tng_io.hpp b/include/tng_io.hpp deleted file mode 100644 index 12172e5..0000000 --- a/include/tng_io.hpp +++ /dev/null @@ -1,1703 +0,0 @@ -/* This code is part of the tng binary trajectory format. - * - * Written by Anders Gärdenäs - * Copyright (c) 2012-2013, The GROMACS development team. - * Check out http://www.gromacs.org for more information. - * - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the Revised BSD License. - */ - -#ifndef TNG_IO_HPP -#define TNG_IO_HPP - -#include "tng_io.h" - -namespace Tng -{ -class Trajectory; -class Atom; -class Residue; -class Chain; -class Molecule; -typedef class Molecule * Molecule_t; - - -class Trajectory { -private: - tng_trajectory_t traj; - tng_function_status status; -public: - /** - * @brief Add a molecule to the trajectory. - * @param name is a pointer to the string containing the name of the new molecule. - * @param molecule is a pointer to the newly created molecule. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - - tng_function_status addMolecule(const char *, Molecule_t); - tng_function_status addMoleculeWithId(const char *, int64_t id, Molecule_t); - tng_function_status findMolecule(const char *name, int64_t id, Molecule_t molecule); - friend class Atom; - friend class Residue; - friend class Chain; - friend class Molecule; - - //! Normal constructor - Trajectory() - { status = tng_trajectory_init(&traj); } - - //! Copy constructor - Trajectory(Trajectory * src) - { status = tng_trajectory_init_from_src(traj,&src->traj); } - - //! Detructor - ~Trajectory() - { status = tng_trajectory_destroy(&traj); } - - //! Status - tng_function_status getStatus() - { return status; } - - - /** - * @brief Get the name of the input file. - * @param file_name the string to fill with the name of the input file, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for file_name. This includes \0 terminating character. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ - tng_function_status getInputFile (char *file_name, const int max_len) - { - return status = tng_input_file_get(traj, file_name, max_len); - } - - /** - * @brief Set the name of the input file. - * @param file_name the name of the input file. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setInputFile(const char *file_name) - { - return status = tng_input_file_set(traj, file_name); - } - - - /** - * @brief Get the name of the output file. - * @param file_name the string to fill with the name of the output file, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for file_name. This includes \0 terminating character. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ - tng_function_status getOutputFile(char *file_name, const int max_len) - { - return status = tng_output_file_get(traj, file_name, max_len); - } - - - /** - * @brief Set the name of the output file. - * @param file_name the name of the output file. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setOutputFile(const char *file_name) - { - return status = tng_output_file_set(traj, file_name); - } - - /** - * @brief Get the endianness of the output file. - * current output file. - * @param endianness will contain the enumeration of the endianness. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness - * could not be retrieved. - */ - tng_function_status getOutputFileEndianness - (tng_file_endianness *endianness) - { - return status = tng_output_file_endianness_get(traj, endianness); - } - - /** - * @brief Set the endianness of the output file. - * @param endianness the enumeration of the endianness, can be either - * TNG_BIG_ENDIAN (0) or TNG_LITTLE_ENDIAN (1). - * @details The endianness cannot be changed after file output has started. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness - * could not be set. - */ - tng_function_status setOutputFileEndianness - (const tng_file_endianness endianness) - { - return status = tng_output_file_endianness_set(traj, endianness); - } - - /** - * @brief Get the name of the program used when creating the trajectory. - * @param name the string to fill with the name of the program, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ - tng_function_status getFirstProgramName(char *name, const int max_len) - { - return status = tng_first_program_name_get(traj,name,max_len); - } - - - /** - * @brief Set the name of the program used when creating the trajectory.. - * @param new_name is a string containing the wanted name. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setFirstProgramName(const char *new_name) - { - return status = tng_first_program_name_set(traj, new_name); - } - - - /** - * @brief Get the name of the program used when last modifying the trajectory. - * @param name the string to fill with the name of the program, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ - tng_function_status getLastProgramName(char *name, const int max_len) - { - return status = tng_last_program_name_get(traj, name, max_len); - } - - - /** - * @brief Set the name of the program used when last modifying the trajectory. - * @param new_name is a string containing the wanted name. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setLastProgramName(const char *new_name) - { - return status = tng_last_program_name_set(traj, new_name); - } - - - /** - * @brief Get the name of the user who created the trajectory. - * @param name the string to fill with the name of the user, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ - tng_function_status getFirstUserName(char *name, const int max_len) - { - return status = tng_first_user_name_get(traj,name, max_len); - } - - - /** - * @brief Set the name of the user who created the trajectory. - * @param new_name is a string containing the wanted name. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setFirstUserName(const char *new_name) - { - return status = tng_first_user_name_set(traj, new_name); - } - - - /** - * @brief Get the name of the user who last modified the trajectory. - * @param name the string to fill with the name of the user, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ - tng_function_status getLastUserName(char *name, const int max_len) - { - return status = tng_last_user_name_get(traj,name,max_len); - } - - - /** - * @brief Set the name of the user who last modified the trajectory. - * @param new_name is a string containing the wanted name. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setLastUserName(const char *new_name) - { - return status = tng_last_user_name_set(traj,new_name); - } - - - - /** - * @brief Get the name of the computer used when creating the trajectory. - * @param name the string to fill with the name of the computer, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ - tng_function_status getFirstComputerName(char *name, const int max_len) - { - return status = tng_first_computer_name_get(traj, name, max_len); - } - - - /** - * @brief Set the name of the computer used when creating the trajectory. - * @param new_name is a string containing the wanted name. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setFirstComputerName(const char *new_name) - { - return status = tng_first_computer_name_set(traj, new_name); - } - - - /** - * @brief Get the name of the computer used when last modifying the trajectory. - * @param name the string to fill with the name of the computer, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ - tng_function_status getLastComputerName(char *name, const int max_len) - { - return status = tng_last_computer_name_get(traj,name,max_len); - } - - - /** - * @brief Set the name of the computer used when last modifying the trajectory. - * @param new_name is a string containing the wanted name. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setLastComputerName(const char *new_name) - { - return status = tng_last_computer_name_set(traj,new_name); - } - - - /** - * @brief Get the pgp_signature of the user creating the trajectory. - * @param signature the string to fill with the signature, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ - tng_function_status getFirstSignature(char *signature, const int max_len) - { - return status = tng_last_computer_name_get(traj, signature,max_len); - } - - - /** - * @brief Set the pgp_signature of the user creating the trajectory. - * @param signature is a string containing the pgp_signature. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setFirstSignature(const char *signature) - { - return status = tng_first_signature_set(traj, signature); - } - - - /** - * @brief Get the pgp_signature of the user last modifying the trajectory. - * @param signature the string to fill with the signature, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ - tng_function_status getLastSignature(char *signature, const int max_len) - { - return status = tng_first_signature_get(traj, signature, max_len); - } - - - /** - * @brief Set the pgp_signature of the user last modifying the trajectory. - * @param signature is a string containing the pgp_signature. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setLastSignature(const char *signature) - { - return status = tng_last_signature_set(traj, signature); - } - - - /** - * @brief Get the name of the forcefield used in the trajectory. - * @param name the string to fill with the name of the forcefield, - * memory must be allocated before. - * @param max_len maximum char length of the string, i.e. how much memory has - * been reserved for name. This includes \0 terminating character. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (source string longer than destination string). - */ - tng_function_status getForcefieldName(char *name, const int max_len) - { - return status = tng_last_signature_get(traj,name,max_len); - } - - - /** - * @brief Set the name of the forcefield used in the trajectory. - * @param new_name is a string containing the wanted name. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setForcefieldName(const char *new_name) - { - return status = tng_forcefield_name_set(traj, new_name); - } - - - /** - * @brief Get the medium stride length of the trajectory. - * @param len is pointing to a value set to the stride length. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status getMediumStrideLength(int64_t *len) - { - return status = tng_medium_stride_length_get(traj,len); - } - - - /** - * @brief Set the medium stride length of the trajectory. - * @param len is the wanted medium stride length. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred. - */ - tng_function_status setMediumStrideLength(const int64_t len) - { - return status = tng_medium_stride_length_set(traj,len); - } - - - /** - * @brief Get the long stride length of the trajectory. - * @param len is pointing to a value set to the stride length. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status getLongStrideLength(int64_t *len) - { - return status = tng_long_stride_length_get(traj, len); - } - - - /** - * @brief Set the long stride length of the trajectory. - * @param len is the wanted long stride length. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred. - */ - tng_function_status setLongStrideLength(const int64_t len) - { - return status = tng_long_stride_length_set(traj,len); - } - - - /** - * @brief Get the current time per frame of the trajectory. - * @param len is pointing to a value set to the time per frame. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status getTimePerFrame(double *time) - { - return status = tng_time_per_frame_get(traj, time); - } - - - /** - * @brief Set the time per frame of the trajectory. - * @param len is the new time per frame. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred. - */ - tng_function_status setTimePerFrame(const double time) - { - return status = tng_time_per_frame_set(traj, time); - } - - - /** - * @brief Get the length of the input file. - * @param len is pointing to a value set to the file length. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status getInputFileLen(int64_t *len) - { - return status = tng_input_file_len_get(traj, len); - } - - - /** - * @brief Get the number of frames in the trajectory - * @param n is pointing to a value set to the number of frames. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred (could not find last frame set). - */ - tng_function_status getNumFrames(int64_t *n) - { - return status = tng_num_frames_get(traj, n); - } - - /** - * @brief Get the current number of particles. - * @param n is pointing to a value set to the number of particles. - * @details If variable number of particles are used this function will return - * the number of particles in the current frame set. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status getNumParticles(int64_t *n) - { - return status = tng_num_particles_get(traj, n); - } - - - - - /** - * @brief Get the current total number of molecules. - * @param n is pointing to a value set to the number of molecules. - * @details If variable number of particles are used this function will return - * the total number of molecules in the current frame set. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status getNumMolecules(int64_t *n) - { - return status = tng_num_molecules_get(traj,n); - } - - /** - * @brief Get the exponential used for distances in the trajectory. - * @param exp is pointing to a value set to the distance unit exponential. - * @details Example: If the distances are specified in nm (default) exp is -9. - * If the distances are specified in Å exp is -10. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status getDistanceUnitExponential - (int64_t *exp) - { - return status = tng_distance_unit_exponential_get(traj, exp); - } - - /** - * @brief Set the exponential used for distances in the trajectory. - * @param exp is the distance unit exponential to use. - * @details Example: If the distances are specified in nm (default) exp is -9. - * If the distances are specified in Å exp is -10. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status setDistanceUnitExponential - (int64_t exp) - { - return status = tng_distance_unit_exponential_set(traj, exp); - } - - - /** - * @brief Get the number of frames per frame set. - * per frame set. - * @param n is pointing to a value set to the number of frames per frame set. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status getNumFramesPerFrameSet(int64_t *n) - { - return status = tng_num_frames_per_frame_set_get(traj,n); - } - - /** - * @brief Set the number of frames per frame set. - * @param n is the number of frames per frame set. - * @details This does not affect already existing frame sets. For - * consistency the number of frames per frame set should be set - * betfore creating any frame sets. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status setNumFramesPerFrameSet(const int64_t n) - { - return status = tng_num_frames_per_frame_set_set(traj,n); - } - - /** - * @brief Get the number of frame sets. - * @param n is pointing to a value set to the number of frame sets. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status getNumFrameSets(int64_t *n) - { - return status = tng_num_frame_sets_get(traj, n); - } - - - /** - * @brief Get the current trajectory frame set. - * @param frame_set_p will be set to point at the memory position of - * the found frame set. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status getCurrentFrameSet(tng_trajectory_frame_set_t *frame_set_p) - { - return status = tng_current_frame_set_get(traj, frame_set_p); - } - - - /** - * @brief Find the requested frame set number. - * @param nr is the frame set number to search for. - * @details tng_data->current_trajectory_frame_set will contain the - * found trajectory if successful. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status findFrameSetNr(const int64_t nr) - { - return status = tng_frame_set_nr_find(traj,nr); - } - - - /** - * @brief Find the frame set containing a specific frame. - * @param frame is the frame number to search for. - * @details tng_data->current_trajectory_frame_set will contain the - * found trajectory if successful. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status findFrameSetOfFrame(const int64_t frame) - { - return status = tng_frame_set_of_frame_find(traj, frame); - } - - - /** - * @brief Get the file position of the next frame set in the input file. - * @param frame_set is the frame set of which to get the position of the - * following frame set. - * @param pos is pointing to a value set to the file position. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status getNextFrameSetFilePos - (const tng_trajectory_frame_set_t frame_set,int64_t *pos) - { - return status = tng_frame_set_next_frame_set_file_pos_get(traj,frame_set,pos ); - } - - /** - * @brief Get the file position of the previous frame set in the input file. - * @param frame_set is the frame set of which to get the position of the - * previous frame set. - * @param pos is pointing to a value set to the file position. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status getPrevFrameSetFilePos - (const tng_trajectory_frame_set_t frame_set,int64_t *pos) - { - return status = tng_frame_set_prev_frame_set_file_pos_get(traj, frame_set, pos); - } - - - /** - * @brief Get the first and last frames of the frame set. - * @param frame_set is the frame set of which to get the frame range. - * @param first_frame is set to the first frame of the frame set. - * @param last_frame is set to the last frame of the frame set. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status getFrameSetFrameRange - (const tng_trajectory_frame_set_t frame_set, - int64_t *first_frame, - int64_t *last_frame) - { - return status = tng_frame_set_frame_range_get(traj,frame_set, first_frame, last_frame); - } - - - /** - * @brief Get the molecume name of real particle number (number in mol system). - * @param nr is the real number of the particle in the molecular system. - * @param name is a string, which is set to the name of the molecule. Memory - * must be reserved beforehand. - * @param max_len is the maximum length of name. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error - * has occured. - */ - tng_function_status getMoleculeNameOfParticleNr - (const int64_t nr,char *name,int max_len) - { - return status = tng_molecule_name_of_particle_nr_get(traj,nr,name,max_len); - } - - - /** - * @brief Get the chain name of real particle number (number in mol system). - * @param nr is the real number of the particle in the molecular system. - * @param name is a string, which is set to the name of the chain. Memory - * must be reserved beforehand. - * @param max_len is the maximum length of name. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error - * has occured. - */ - tng_function_status getChainNameOfParticleNr - (const int64_t nr,char *name,int max_len) - { - return status = tng_chain_name_of_particle_nr_get(traj, nr, name, max_len); - } - - - /** - * @brief Get the residue name of real particle number (number in mol system). - * @param nr is the real number of the particle in the molecular system. - * @param name is a string, which is set to the name of the residue. Memory - * must be reserved beforehand. - * @param max_len is the maximum length of name. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error - * has occured. - */ - tng_function_status getResidueNameOfParticleNr - (const int64_t nr,char *name,int max_len) - { - return status = tng_residue_name_of_particle_nr_get(traj,nr,name,max_len); - } - - - /** - * @brief Get the atom name of real particle number (number in mol system). - * @param nr is the real number of the particle in the molecular system. - * @param name is a string, which is set to the name of the atom. Memory - * must be reserved beforehand. - * @param max_len is the maximum length of name. - * @return TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error - * has occured. - */ - tng_function_status getAtomNameOfParticleNr - (const int64_t nr,char *name,int max_len) - { - return status = tng_atom_name_of_particle_nr_get(traj, nr,name,max_len); - } - - - /** - * @brief Add a particle mapping table. - * @details Each particle mapping table will be written as a separate block, - * followed by the data blocks for the corresponding particles. In most cases - * there is one particle mapping block for each thread writing the trajectory. - * @details The mapping information is added to the currently active frame set - * of tng_data - * @param first_particle_number is the first particle number of this mapping - * block. - * @param n_particles is the number of particles in this mapping block. - * @param mapping_table is a list of the real particle numbers (i.e. the numbers - * used in the molecular system). The list is n_particles long. - * @details mapping_table[0] is the real particle number of the first particle - * in the following data blocks. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status addParticleMapping - (const int64_t first_particle_number, - const int64_t n_particles, - const int64_t *mapping_table) - { - return status = tng_particle_mapping_add(traj,first_particle_number,n_particles,mapping_table ); - } - - - /** - * @brief Read the header blocks from the input_file of tng_data. - * @details The trajectory blocks must be read separately and iteratively in chunks - * to fit in memory. - * @details tng_data->input_file_path specifies - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status readFileHeaders(const tng_hash_mode hash_mode) - { - return status = tng_file_headers_read(traj, hash_mode); - } - - - /** - * @brief Write the header blocks to the output_file of tng_data. - * @details The trajectory blocks must be written separately and iteratively in chunks - * to fit in memory. - * @details tng_data->output_file_path - * specifies which file to write to. If the file (output_file) is not open it - * will be opened. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status writeFileHeaders(const tng_hash_mode hash_mode) - { - return status = tng_file_headers_write(traj, hash_mode); - } - - - - /** - * @brief Read one (the next) block (of any kind) from the input_file of tng_data. - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param block_data is a pointer to the struct which will be populated with the - * data. - * @details If block_data->input_file_pos > 0 it is the position from where the - * reading starts otherwise it starts from the current position. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status readNextBlock(const tng_hash_mode hash_mode, tng_gen_block_t block_data) - { - return status = tng_block_read_next(traj,block_data, hash_mode); - } - - - - /** - * @brief Read one (the next) frame set, including mapping and related data blocks - * from the input_file of tng_data. - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status readNextFrameSet(const tng_hash_mode hash_mode) - { - return status = tng_frame_set_read_next(traj, hash_mode); - } - - - /** - * @brief Write one frame set, including mapping and related data blocks - * to the output_file of tng_data. - * @details tng_data->output_file_path specifies - * which file to write to. If the file (output_file) is not open it will be - * opened. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH an md5 hash for each header block will be generated. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status writeFrameSet(const tng_hash_mode hash_mode) - { - return status = tng_frame_set_write(traj, hash_mode); - } - - - /** - * @brief Create and initialise a frame set. - * @param first_frame is the first frame of the frame set. - * @param n_frames is the number of frames in the frame set. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status newFrameSet(const int64_t first_frame, - const int64_t n_frames) - { - return status = tng_frame_set_new(traj, first_frame, n_frames); - } - - - /** - * @brief Create and initialise a frame set with the time of the first frame - * specified. - * @param first_frame is the first frame of the frame set. - * @param n_frames is the number of frames in the frame set. - * @param first_frame_time is the time stamp of the first frame (in seconds). - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status newFrameSetWithTime - (const int64_t first_frame, - const int64_t n_frames, - const double first_frame_time) - { - return status = tng_frame_set_with_time_new(traj, - first_frame, n_frames, - first_frame_time); - } - - - /** - * @brief Set the time stamp of the first frame of the current frame set. - * @param first_frame_time is the time stamp of the first frame in the - * frame set. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status setTimeOfFirstFrameOfFrameSet - (const double first_frame_time) - { - return status = tng_frame_set_first_frame_time_set(traj, - first_frame_time); - } - - /** - * @brief Add a non-particle dependent data block. - * @param id is the block ID of the block to add. - * @param block_name is a descriptive name of the block to add - * @param datatype is the datatype of the data in the block (e.g. int/float) - * @param block_type_flag indicates if this is a non-trajectory block (added - * directly to tng_data) or if it is a trajectory block (added to the - * frame set) - * @param n_frames is the number of frames of the data block (automatically - * set to 1 if adding a non-trajectory data block) - * @param n_values_per_frame is how many values a stored each frame (e.g. 9 - * for a box shape block) - * @param stride_length is how many frames are between each entry in the - * data block - * @param codec_id is the ID of the codec to compress the data. - * @param new_data is an array of data values to add. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status addDataBlock(const int64_t id, - const char *block_name, - const tng_data_type datatype, - const tng_block_type block_type_flag, - int64_t n_frames, - const int64_t n_values_per_frame, - const int64_t stride_length, - const int64_t codec_id, - void *new_data) - { - return status = tng_data_block_add(traj, id,block_name, - datatype,block_type_flag, n_frames, - n_values_per_frame, stride_length, - codec_id, new_data); - } - - - /** - * @brief Add a particle dependent data block. - * @param id is the block ID of the block to add. - * @param block_name is a descriptive name of the block to add - * @param datatype is the datatype of the data in the block (e.g. int/float) - * @param block_type_flag indicates if this is a non-trajectory block (added - * directly to tng_data) or if it is a trajectory block (added to the - * frame set) - * @param n_frames is the number of frames of the data block (automatically - * set to 1 if adding a non-trajectory data block) - * @param n_values_per_frame is how many values a stored each frame (e.g. 9 - * for a box shape block) - * @param stride_length is how many frames are between each entry in the - * data block - * @param first_particle_number is the number of the first particle stored - * in this data block - * @param n_particles is the number of particles stored in this data block - * @param codec_id is the ID of the codec to compress the data. - * @param new_data is an array of data values to add. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status addParticleDataBlock(const int64_t id, - const char *block_name, - const tng_data_type datatype, - const tng_block_type block_type_flag, - int64_t n_frames, - const int64_t n_values_per_frame, - const int64_t stride_length, - const int64_t first_particle_number, - const int64_t n_particles, - const int64_t codec_id, - void *new_data) - { - return status = tng_particle_data_block_add(traj,id, block_name, - datatype, block_type_flag, n_frames,n_values_per_frame, - stride_length,first_particle_number,n_particles, - codec_id, new_data); - } - - - /** - * @brief Write data of one trajectory frame to the output_file of tng_data. - * @param frame_nr is the index number of the frame to write. - * @param block_id is the ID of the data block to write the data to. - * @param data is an array of data to write. The length of the array should - * equal n_values_per_frame. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status writeFrameData(const int64_t frame_nr, - const int64_t block_id, - const void *data, - const tng_hash_mode hash_mode) - { - return status = tng_frame_data_write(traj,frame_nr,block_id,data,hash_mode); - } - - - /** - * @brief Write particle data of one trajectory frame to the output_file of - * tng_data. - * @param frame_nr is the index number of the frame to write. - * @param block_id is the ID of the data block to write the data to. - * @param val_first_particle is the number of the first particle in the data - * array. - * @param val_n_particles is the number of particles in the data array. - * @param data is a 1D-array of data to write. The length of the array should - * equal n_particles * n_values_per_frame. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the written md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status writeFrameParticleData(const int64_t frame_nr, - const int64_t block_id, - const int64_t val_first_particle, - const int64_t val_n_particles, - const void *data, - const tng_hash_mode hash_mode) - { - return status = tng_frame_particle_data_write(traj,frame_nr,block_id,val_first_particle,val_n_particles,data,hash_mode); - } - - - /** - * @brief Free data is an array of values (2D). - * @param values is the 2D array to free and will be set to 0 afterwards. - * @param n_frames is the number of frames in the data array. - * @param n_values_per_frame is the number of values per frame in the data array. - * @param type is the data type of the data in the array (e.g. int/float/char). - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status freeDataValues(union data_values **values, - const int64_t n_frames, - const int64_t n_values_per_frame, - const tng_data_type type) - { - return status = tng_data_values_free(traj, values, n_frames,n_values_per_frame,type); - } - - - /** - * @brief Free data is an array of values (3D). - * @param values is the array to free and will be set to 0 afterwards. - * @param n_frames is the number of frames in the data array. - * @param n_particles is the number of particles in the data array. - * @param n_values_per_frame is the number of values per frame in the data array. - * @param type is the data type of the data in the array (e.g. int/float/char). - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status freeParticleDataValues(union data_values ***values, - const int64_t n_frames, - const int64_t n_particles, - const int64_t n_values_per_frame, - const tng_data_type type) - { - return status = tng_particle_data_values_free(traj, values,n_frames,n_particles,n_values_per_frame,type); - } - - - /** - * @brief Retrieve non-particle data, from the last read frame set. Obsolete! - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param block_id is the id number of the particle data block to read. - * @param values is a pointer to a 2-dimensional array (memory unallocated), which - * will be filled with data. The array will be sized - * (n_frames * n_values_per_frame). - * Since ***values is allocated in this function it is the callers - * responsibility to free the memory. - * @param n_frames is set to the number of particles in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status getData(const int64_t block_id, - union data_values ***values, - int64_t *n_frames, - int64_t *n_values_per_frame, - char *type) - { - return status = tng_data_get(traj, block_id, values, n_frames, - n_values_per_frame, type); - } - - /** - * @brief Retrieve a vector (1D array) of non-particle data, from the last read frame set. - * @param block_id is the id number of the particle data block to read. - * @param values is a pointer to a 1-dimensional array (memory unallocated), which - * will be filled with data. The length of the array will be (n_frames * n_values_per_frame). - * Since **values is allocated in this function it is the callers - * responsibility to free the memory. - * @param n_frames is set to the number of particles in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param stride_length is set to the stride length of the returned data. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @details This does only work for numerical (int, float, double) data. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status getDataVector - (const int64_t block_id, - void **values, - int64_t *n_frames, - int64_t *stride_length, - int64_t *n_values_per_frame, - char *type) - { - return status = tng_data_vector_get(traj, block_id, values, n_frames, - stride_length, n_values_per_frame, - type); - } - - /** - * @brief Read and retrieve non-particle data, in a specific interval. Obsolete! - * which file to read from. If the file (input_file) is not open it will be - * opened. - * @param block_id is the id number of the particle data block to read. - * @param start_frame_nr is the index number of the first frame to read. - * @param end_frame_nr is the index number of the last frame to read. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @param values is a pointer to a 2-dimensional array (memory unallocated), which - * will be filled with data. The array will be sized - * (n_frames * n_values_per_frame). - * Since ***values is allocated in this function it is the callers - * responsibility to free the memory. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status getDataInterval(const int64_t block_id, - const int64_t start_frame_nr, - const int64_t end_frame_nr, - const tng_hash_mode hash_mode, - union data_values ***values, - int64_t *n_values_per_frame, - char *type) - { - return status = tng_data_interval_get(traj, block_id, start_frame_nr, - end_frame_nr, hash_mode, values, - n_values_per_frame, type); - } - - - /** - * @brief Read and retrieve a vector (1D array) of non-particle data, - * in a specific interval. - * @param block_id is the id number of the particle data block to read. - * @param start_frame_nr is the index number of the first frame to read. - * @param end_frame_nr is the index number of the last frame to read. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @param values is a pointer to a 1-dimensional array (memory unallocated), which - * will be filled with data. The length of the array will be (n_frames * n_values_per_frame). - * Since **values is allocated in this function it is the callers - * responsibility to free the memory. - * @param stride_length is set to the stride length (writing frequency) of - * the data. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @details This does only work for numerical (int, float, double) data. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status getDataVectorInterval - (const int64_t block_id, - const int64_t start_frame_nr, - const int64_t end_frame_nr, - const char hash_mode, - void **values, - int64_t *stride_length, - int64_t *n_values_per_frame, - char *type) - { - return status = tng_data_vector_interval_get(traj, block_id, - start_frame_nr, - end_frame_nr, - hash_mode, values, - stride_length, - n_values_per_frame, - type); - } - - /** - * @brief Retrieve particle data, from the last read frame set. Obsolete! - * @details The particle dimension of the returned values array is translated - * to real particle numbering, i.e. the numbering of the actual molecular - * system. - * specifies which file to read from. If the file (input_file) is not open it - * will be opened. - * @param block_id is the id number of the particle data block to read. - * @param values is a pointer to a 3-dimensional array (memory unallocated), which - * will be filled with data. The array will be sized - * (n_frames * n_particles * n_values_per_frame). - * Since ****values is allocated in this function it is the callers - * responsibility to free the memory. - * @param n_frames is set to the number of particles in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param n_particles is set to the number of particles in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status getParticleData(const int64_t block_id, - union data_values ****values, - int64_t *n_frames, - int64_t *n_particles, - int64_t *n_values_per_frame, - char *type) - { - return status = (tng_particle_data_get(traj, block_id, values, n_frames, - n_particles, n_values_per_frame, type)); - } - - - /** - * @brief Retrieve a vector (1D array) of particle data, from the last read frame set. - * @details The particle dimension of the returned values array is translated - * to real particle numbering, i.e. the numbering of the actual molecular - * system. - * @param block_id is the id number of the particle data block to read. - * @param values is a pointer to a 1-dimensional array (memory unallocated), which - * will be filled with data. The length of the array will be - * (n_frames * n_particles * n_values_per_frame). - * Since **values is allocated in this function it is the callers - * responsibility to free the memory. - * @param n_frames is set to the number of frames in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param stride_length is set to the stride length of the returned data. - * @param n_particles is set to the number of particles in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @details This does only work for numerical (int, float, double) data. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status getParticleDataVector - (const int64_t block_id, - void **values, - int64_t *n_frames, - int64_t *stride_length, - int64_t *n_particles, - int64_t *n_values_per_frame, - char *type) - { - return status = tng_particle_data_vector_get(traj, block_id, - values, n_frames, - stride_length, - n_particles, - n_values_per_frame, type); - } - - - /** - * @brief Read and retrieve particle data, in a specific interval. Obsolete! - * @details The particle dimension of the returned values array is translated - * to real particle numbering, i.e. the numbering of the actual molecular - * system. - * @param block_id is the id number of the particle data block to read. - * @param start_frame_nr is the index number of the first frame to read. - * @param end_frame_nr is the index number of the last frame to read. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @param values is a pointer to a 3-dimensional array (memory unallocated), which - * will be filled with data. The array will be sized - * (n_frames * n_particles * n_values_per_frame). - * Since ****values is allocated in this function it is the callers - * responsibility to free the memory. - * @param n_particles is set to the number of particles in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status getParticleDataInterval(const int64_t block_id, - const int64_t start_frame_nr, - const int64_t end_frame_nr, - const tng_hash_mode hash_mode, - union data_values ****values, - int64_t *n_particles, - int64_t *n_values_per_frame, - char *type) - { - return status = (tng_particle_data_interval_get(traj, block_id, start_frame_nr, - end_frame_nr, hash_mode, values, - n_particles, n_values_per_frame, - type)); - } - - - /** - * @brief Read and retrieve a vector (1D array) particle data, in a - * specific interval. - * @details The particle dimension of the returned values array is translated - * to real particle numbering, i.e. the numbering of the actual molecular - * system. - * @param block_id is the id number of the particle data block to read. - * @param start_frame_nr is the index number of the first frame to read. - * @param end_frame_nr is the index number of the last frame to read. - * @param hash_mode is an option to decide whether to use the md5 hash or not. - * If hash_mode == TNG_USE_HASH the md5 hash in the file will be - * compared to the md5 hash of the read contents to ensure valid data. - * @param values is a pointer to a 1-dimensional array (memory unallocated), which - * will be filled with data. The length of the array will be - * (n_frames * n_particles * n_values_per_frame). - * Since **values is allocated in this function it is the callers - * responsibility to free the memory. - * @param stride_length is set to the stride length (writing frequency) of - * the data. - * @param n_particles is set to the number of particles in the returned data. This is - * needed to properly reach and/or free the data afterwards. - * @param n_values_per_frame is set to the number of values per frame in the data. - * This is needed to properly reach and/or free the data afterwards. - * @param type is set to the data type of the data in the array. - * @details This does only work for numerical (int, float, double) data. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status getParticleDataVectorInterval - (const int64_t block_id, - const int64_t start_frame_nr, - const int64_t end_frame_nr, - const tng_hash_mode hash_mode, - void **values, - int64_t *n_particles, - int64_t *stride_length, - int64_t *n_values_per_frame, - char *type) - { - return status = tng_particle_data_vector_interval_get(traj, block_id, - start_frame_nr, - end_frame_nr, - hash_mode, - values, - n_particles, - stride_length, - n_values_per_frame, - type); - } - - - /** @brief Get the date and time of initial file creation in ISO format (string). - * @param time is a pointer to the string in which the date will be stored. Memory - must be reserved beforehand. - * @return TNG_SUCCESS (0) if successful. - */ - tng_function_status getTimeStr(char *time) - { - return status = tng_time_get_str(traj, time); - } - - -}; - - - - - -class Molecule -{ -private: - - tng_molecule_t mol; - Trajectory * traj; - tng_function_status status; -public: - tng_function_status addChain(const char *name, Chain *chain); - tng_function_status findChain(const char *name, int64_t id, Chain *chain); - friend class Trajectory; - //Constructor - Molecule(Trajectory * trajectory) - { - traj = trajectory; - - //status = tng_molecule_init(traj->traj,mol); - } - /** - *@Dose nothing, use ~TngMolecule() - */ - ~Molecule() - { - status = tng_molecule_destroy(traj->traj,mol); - } - //! Status - tng_function_status getStatus() - { return status; } - - - /** - * @brief Set the name of a molecule. - * @param new_name is a string containing the wanted name. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setName(const char *new_name) - { - return status = tng_molecule_name_set(traj->traj,mol,new_name); - } - - /** - * @brief Get the count of a molecule. - * @param cnt is a pointer to the variable to be populated with the count. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status getCnt(int64_t *cnt) - { - return status = tng_molecule_cnt_get(traj->traj,mol,cnt); - } - - /** - * @brief Set the count of a molecule. - * @param cnt is the number of instances of this molecule. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error - * has occurred or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status setCnt(int64_t cnt) - { - return status = tng_molecule_cnt_set(traj->traj,mol,cnt); - } - -}; - - tng_function_status Trajectory::addMolecule(const char *name, Molecule_t molecule) -{ - return status = tng_molecule_add(traj,name, &molecule->mol); -} - - tng_function_status Trajectory::addMoleculeWithId - (const char *name, - const int64_t id, - Molecule_t molecule) -{ - return status = tng_molecule_w_id_add(traj, name, id, &molecule->mol); -} - -/** -* @brief Find a molecule. -* @param tng_data is the trajectory data container containing the molecule. -* @param name is a string containing the name of the molecule. If name is empty -* only id will be used for finding the molecule. -* @param id is the id of the molecule to look for. If id is -1 only the name of -* the molecule will be used for finding the molecule. -* @param molecule is a pointer to the molecule if it was found - otherwise 0. -* @return TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the -* molecule is not found. -* @details If name is an empty string and id is -1 the first molecule will be -* found. -*/ -tng_function_status Trajectory::findMolecule - (const char *name, - int64_t id, - Molecule_t molecule) -{ - return status = tng_molecule_find(traj, name, id, - &molecule->mol); -} - - -class Atom -{ -private: - tng_atom_t atom; - Trajectory * traj; - tng_function_status status; -public: - friend class Residue; - //constructor - Atom(Trajectory * trajectory) - { - traj = trajectory; - } - //deonstructor - /** - *@Dose nothing, use ~TngMolecule() - */ - ~Atom() - { - //delete atom; - } - //! Status - tng_function_status getStatus() - { return status; } - /** - * @brief Set the name of an atom. - * @param new_name is a string containing the wanted name. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setName(const char *new_name) - { - return status = tng_atom_name_set(traj->traj, atom , new_name); - } - - /** - * @param new_type is a string containing the atom type. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setType(const char *new_type) - { - return status = tng_atom_type_set(traj->traj, atom, new_type); - } -}; - -class Residue -{ - private: - tng_residue_t residue; - Trajectory * traj; - tng_function_status status; -public: - friend class Chain; - //constructor - Residue(Trajectory * trajectory) - { - traj = trajectory; - } - //deonstructor - /** - *@Dose nothing, use ~TngMolecule() - */ - ~Residue() - { - //delete residue; - } - //! Status - tng_function_status getStatus() - { return status; } - /** - * @brief Set the name of a residue. - * @param residue is the residue to rename. - * @param new_name is a string containing the wanted name. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setName(const char *new_name) - { - return status = tng_residue_name_set(traj->traj, residue,new_name); - } - - /** - * @brief Add an atom to a residue. - * @param atom_name is a string containing the name of the atom. - * @param atom_type is a string containing the atom type of the atom. - * @param atom is a pointer to the newly created atom. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status addAtom(const char *atom_name, - const char *atom_type, - Atom * atom) - { - return status = tng_residue_atom_add(traj->traj, residue, atom_name, - atom_type, &atom->atom); - } - - - /** - * @brief Add an atom with a specific ID to a residue. - * @param atom_name is a string containing the name of the atom. - * @param atom_type is a string containing the atom type of the atom. - * @param id is the ID of the created atom. - * @param atom is a pointer to the newly created atom. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could - * not be set properly or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status addAtomWithId - (const char *atom_name, - const char *atom_type, - const int64_t id, - Atom * atom) - { - return status = tng_residue_atom_w_id_add(traj->traj, residue, - atom_name, atom_type, - id, &atom->atom); - } - -}; - -class Chain -{ - private: - tng_chain_t chain; - Trajectory * traj; - tng_function_status status; -public: - friend class Molecule; - //constructor - Chain(Trajectory * trajectory) - { - traj = trajectory; - } - //deonstructor - /** - *@Dose nothing, use ~TngMolecule() - */ - ~Chain() - { - //delete chain; - } - //! Status - tng_function_status getStatus() - { return status; } - /** - * @brief Set the name of a chain. - * @param new_name is a string containing the wanted name. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status setName(const char *new_name) - { - return status = tng_chain_name_set(traj->traj, chain, new_name); - } - - - /** - * @brief Find a residue in a chain. - * @param name is a string containing the name of the residue. - * @param id is the id of the residue to find. If id == -1 the first residue - * that matches the specified name will be found. - * @param residue is a pointer to the residue if it was found - otherwise 0. - * @return TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the - * residue is not found. - * @details If name is an empty string the first residue will be found. - */ - tng_function_status findResidue - (const char *name, - int64_t id, - Residue *residue) - { - return status = tng_chain_residue_find(traj->traj, chain, name, - id, &residue->residue); - } - - /** - * @brief Add a residue to a chain. - * @param name is a string containing the name of the residue. - * @param residue is a pointer to the newly created residue. - * @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major - * error has occured. - */ - tng_function_status addResidue(const char *name, - Residue * residue) - { - return status = tng_chain_residue_add(traj->traj, chain, - name, &residue->residue); - } - - /** - * @brief Add a residue with a specific ID to a chain. - * @param name is a string containing the name of the residue. - * @param id is the ID of the created residue. - * @param residue is a pointer to the newly created residue. - * @return TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if the ID could - * not be set properly or TNG_CRITICAL (2) if a major error has occured. - */ - tng_function_status addResidueWithId - (const char *name, - const int64_t id, - Residue * residue) - { - return status = tng_chain_residue_w_id_add(traj->traj, chain, - name, id, &residue->residue); - } -}; - -/** -* @brief Add a chain to a molecule. -* @param name is a string containing the name of the chain. -* @param chain s a pointer to the newly created chain. -* @return TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major -* error has occured. -*/ -tng_function_status Molecule::addChain(const char *name, Chain *chain) -{ - return status = tng_molecule_chain_add(traj->traj,mol,name,&chain->chain); -} - -/** -* @brief Find a chain in a molecule. -* @param name is a string containing the name of the chain. If name is empty -* only id will be used for finding the chain. -* @param id is the id of the chain to look for. If id is -1 only the name of -* the chain will be used for finding the chain. -* @param chain is a pointer to the chain if it was found - otherwise 0. -* @return TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the -* chain is not found. -* @details If name is an empty string and id is -1 the first chain will be -* found. -*/ -tng_function_status Molecule::findChain - (const char *name, - int64_t id, - Chain *chain) -{ - return status = tng_molecule_chain_find(traj->traj, mol, name, id, - &chain->chain); -} - -} -#endif diff --git a/include/tng_io_fwd.h b/include/tng_io_fwd.h deleted file mode 100644 index 8b63a9a..0000000 --- a/include/tng_io_fwd.h +++ /dev/null @@ -1,39 +0,0 @@ -/* This code is part of the tng binary trajectory format. - * - * Written by Magnus Lundborg - * Copyright (c) 2012-2013, The GROMACS development team. - * Check out http://www.gromacs.org for more information. - * - * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the Revised BSD License. - */ - -#ifndef TNG_IO_FWD_H -#define TNG_IO_FWD_H 1 - -/** A pointer to the main trajectory data storage. */ -typedef struct tng_trajectory *tng_trajectory_t; -/** A pointer to a molecule description. */ -typedef struct tng_molecule *tng_molecule_t; -/** A pointer to a molecular chain description. */ -typedef struct tng_chain *tng_chain_t; -/** A pointer to a molecular residue description. */ -typedef struct tng_residue *tng_residue_t; -/** A pointer to a molecular atom description. */ -typedef struct tng_atom *tng_atom_t; -/** A pointer to a bond between two atoms. */ -typedef struct tng_bond *tng_bond_t; -/** A pointer to a structure containing data common to all trajectory blocks, - * such as header and contents. */ -typedef struct tng_gen_block *tng_gen_block_t; -/** A pointer to particle mapping information. */ -typedef struct tng_particle_mapping *tng_particle_mapping_t; -/** A pointer to a structure containing frame set information. */ -typedef struct tng_trajectory_frame_set *tng_trajectory_frame_set_t; -/** A pointer to a particle data container. */ -typedef struct tng_particle_data *tng_particle_data_t; -/** A pointer to a non-particle data container. */ -typedef struct tng_non_particle_data *tng_non_particle_data_t; - -#endif diff --git a/include/version.h.in b/include/version.h.in deleted file mode 100644 index 840e454..0000000 --- a/include/version.h.in +++ /dev/null @@ -1,7 +0,0 @@ -#ifndef VERSION_CONFIG_H -#define VERSION_CONFIG_H - -/* define the API version */ -#define TNG_API_VERSION @API_VERSION@ - -#endif diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index d5f2bc0..88c0516 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -1,3 +1 @@ -add_subdirectory(compression) -add_subdirectory(lib) add_subdirectory(tests) diff --git a/src/compression/CMakeLists.txt b/src/compression/CMakeLists.txt deleted file mode 100644 index 8bb0220..0000000 --- a/src/compression/CMakeLists.txt +++ /dev/null @@ -1,15 +0,0 @@ -set(source_files bwlzh.c bwt.c coder.c dict.c fixpoint.c huffman.c huffmem.c lz77.c merge_sort.c mtf.c rle.c tng_compress.c vals16.c warnmalloc.c widemuldiv.c xtc2.c xtc3.c) - -add_library(tng_compress ${source_files}) - -# Append the required library dependencies -if(UNIX) - target_link_libraries(tng_compress m) -endif() - -# Use GNUInstallDirst to set paths on multiarch systems -include(GNUInstallDirs) - -install(TARGETS tng_compress - LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} - ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}) diff --git a/src/lib/CMakeLists.txt b/src/lib/CMakeLists.txt deleted file mode 100644 index 838f827..0000000 --- a/src/lib/CMakeLists.txt +++ /dev/null @@ -1,37 +0,0 @@ -set(source_files tng_io.c md5.c) -if(TNG_BUILD_FORTRAN) - list(APPEND source_files tng_io_fortran.c) -endif() - -add_library(tng_io ${source_files}) - -# Now add source-file compilation properties to the source-file -# targets - -if(HAVE_INTTYPES_H) - set_property(SOURCE tng_io.c APPEND PROPERTY COMPILE_DEFINITIONS USE_STD_INTTYPES_H) -endif() -if(TNG_BUILD_WITH_ZLIB) - set_property(SOURCE tng_io.c APPEND PROPERTY COMPILE_DEFINITIONS USE_ZLIB) -endif() - -# This test is for md5. The TNG library itself determines the actual byte order - -# not just if it is small or big endian. -include(TestBigEndian) -test_big_endian(TNG_INTEGER_BIG_ENDIAN) -if(TNG_INTEGER_BIG_ENDIAN) - set_property(SOURCE md5.c APPEND PROPERTY COMPILE_DEFINITIONS TNG_INTEGER_BIG_ENDIAN) -endif() - -# Append the required library dependencies -target_link_libraries(tng_io tng_compress) -if(TNG_BUILD_WITH_ZLIB) - target_link_libraries(tng_io ${ZLIB_LIBRARIES}) -endif() - -# Use GNUInstallDirst to set paths on multiarch systems -include(GNUInstallDirs) - -install(TARGETS tng_io - LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} - ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}) diff --git a/src/lib/md5.c b/src/lib/md5.c index ea8bb37..f6a2391 100644 --- a/src/lib/md5.c +++ b/src/lib/md5.c @@ -75,7 +75,7 @@ 1999-05-03 lpd Original version. */ -#include "../../include/md5.h" +#include "tng/md5.h" #include #undef BYTE_ORDER /* 1 = big-endian, -1 = little-endian, 0 = unknown */ diff --git a/src/lib/tng_io-config.cmake.in b/src/lib/tng_io-config.cmake.in new file mode 100644 index 0000000..06c0470 --- /dev/null +++ b/src/lib/tng_io-config.cmake.in @@ -0,0 +1,13 @@ +# - Config file for the TNG_IO package +# It defines the following variables +# TNG_IO_INCLUDE_DIRS - include directories for TNG_IO +# TNG_IO_LIBRARIES - libraries to link against +# TNG_IO_DEFINITIONS - definitions used when compiling + +# Compute paths +get_filename_component(TNG_IO_CMAKE_DIR "${CMAKE_CURRENT_LIST_FILE}" PATH) +set(TNG_IO_INCLUDE_DIRS "@CONF_INCLUDE_DIRS@") +set(TNG_IO_DEFINITIONS "@TNG_COMPILE_DEFS@") + +set(TNG_IO_LIBRARIES tng_io) + diff --git a/src/lib/tng_io-configVersion.cmake.in b/src/lib/tng_io-configVersion.cmake.in new file mode 100644 index 0000000..8946f5e --- /dev/null +++ b/src/lib/tng_io-configVersion.cmake.in @@ -0,0 +1,12 @@ +set(PACKAGE_VERSION "@TNG_IO_VERSION@") + +# Check whether the requested PACKAGE_FIND_VERSION is compatible +if("${PACKAGE_VERSION}" VERSION_LESS "${PACKAGE_FIND_VERSION}") + set(PACKAGE_VERSION_COMPATIBLE FALSE) +else() + set(PACKAGE_VERSION_COMPATIBLE TRUE) + if ("${PACKAGE_VERSION}" VERSION_EQUAL "${PACKAGE_FIND_VERSION}") + set(PACKAGE_VERSION_EXACT TRUE) + endif() +endif() + diff --git a/src/lib/tng_io.c b/src/lib/tng_io.c index 252cbb2..792be2e 100644 --- a/src/lib/tng_io.c +++ b/src/lib/tng_io.c @@ -22,10 +22,10 @@ #include #endif -#include "../../include/tng_io.h" -#include "../../include/md5.h" -#include "../../include/compression/tng_compress.h" -#include "../include/version.h" +#include "tng/tng_io.h" +#include "tng/md5.h" +#include "compression/tng_compress.h" +#include "tng/version.h" struct tng_bond { @@ -7852,6 +7852,52 @@ static tng_function_status tng_atom_destroy(tng_atom_t atom) return(TNG_SUCCESS); } +tng_function_status DECLSPECDLLEXPORT tng_version_major + (const tng_trajectory_t tng_data, + int *version) +{ + (void)tng_data; + + *version = TNG_VERSION_MAJOR; + + return(TNG_SUCCESS); +} + +tng_function_status DECLSPECDLLEXPORT tng_version_minor + (const tng_trajectory_t tng_data, + int *version) +{ + (void)tng_data; + + *version = TNG_VERSION_MINOR; + + return(TNG_SUCCESS); +} + +tng_function_status DECLSPECDLLEXPORT tng_version_patchlevel + (const tng_trajectory_t tng_data, + int *patch_level) +{ + (void)tng_data; + + *patch_level = TNG_VERSION_PATCHLEVEL; + + return(TNG_SUCCESS); +} + +tng_function_status DECLSPECDLLEXPORT tng_version + (const tng_trajectory_t tng_data, + char *version, + const int max_len) +{ + (void)tng_data; + TNG_ASSERT(version, "TNG library: version must not be a NULL pointer"); + + TNG_SNPRINTF(version, max_len, "%s", TNG_VERSION); + + return(TNG_SUCCESS); +} + tng_function_status DECLSPECDLLEXPORT tng_molecule_add (tng_trajectory_t tng_data, const char *name, @@ -18889,7 +18935,7 @@ tng_function_status DECLSPECDLLEXPORT tng_util_frame_current_compression_get (tng_trajectory_t tng_data, const int64_t block_id, int64_t *codec_id, - float *factor) + double *factor) { tng_trajectory_frame_set_t frame_set; tng_particle_data_t p_data = 0; @@ -18986,12 +19032,12 @@ tng_function_status DECLSPECDLLEXPORT tng_util_frame_current_compression_get if(block_type == TNG_PARTICLE_BLOCK_DATA) { *codec_id = p_data->codec_id; - *factor = (float)p_data->compression_multiplier; + *factor = p_data->compression_multiplier; } else if(block_type == TNG_NON_PARTICLE_BLOCK_DATA) { *codec_id = np_data->codec_id; - *factor = (float)np_data->compression_multiplier; + *factor = np_data->compression_multiplier; } return(TNG_SUCCESS); } diff --git a/src/tests/compression/CMakeLists.txt b/src/tests/compression/CMakeLists.txt index 075b06b..d29791b 100644 --- a/src/tests/compression/CMakeLists.txt +++ b/src/tests/compression/CMakeLists.txt @@ -4,8 +4,6 @@ add_definitions(-DTNG_COMPRESS_FILES_DIR="${CMAKE_BINARY_DIR}/test_tng_compress_ file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/test_tng_compress_files) -include_directories(${CMAKE_BINARY_DIR}/include/) - set(number 0) set(numtests 78) @@ -14,7 +12,7 @@ while( number LESS ${numtests}) math( EXPR number "${number} + 1" ) add_executable(test_tng_compress_gen${number} testsuite.c) -target_link_libraries(test_tng_compress_gen${number} tng_compress) +target_link_libraries(test_tng_compress_gen${number} tng_io) if(UNIX) target_link_libraries(test_tng_compress_gen${number} m) endif() @@ -25,7 +23,7 @@ add_dependencies(test_tng_compress_gen${number} test${number}.h) set_property(TARGET test_tng_compress_gen${number} PROPERTY RUNTIME_OUTPUT_DIRECTORY ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/compression_tests) add_executable(test_tng_compress_read${number} testsuite.c) -target_link_libraries(test_tng_compress_read${number} tng_compress) +target_link_libraries(test_tng_compress_read${number} tng_io) if(UNIX) target_link_libraries(test_tng_compress_read${number} m) endif() diff --git a/src/tests/compression/testsuite.c b/src/tests/compression/testsuite.c index 2cfe05e..e266c11 100644 --- a/src/tests/compression/testsuite.c +++ b/src/tests/compression/testsuite.c @@ -8,7 +8,7 @@ #include #include #include -#include "../../../include/compression/tng_compress.h" +#include "compression/tng_compress.h" #include TESTPARAM #ifdef TEST_FLOAT diff --git a/src/tests/md_openmp.c b/src/tests/md_openmp.c index fd9f4b0..aac8b3b 100644 --- a/src/tests/md_openmp.c +++ b/src/tests/md_openmp.c @@ -1,11 +1,11 @@ #ifdef TNG_BUILD_OPENMP_EXAMPLES -# include -# include -# include -# include -# include -#include "../../include/tng_io.h" +#include +#include +#include +#include +#include +#include "tng/tng_io.h" int main (); void compute ( int np, int nd, double pos[], double vel[], diff --git a/src/tests/md_openmp_util.c b/src/tests/md_openmp_util.c index 8c332f3..9fe6c91 100644 --- a/src/tests/md_openmp_util.c +++ b/src/tests/md_openmp_util.c @@ -1,11 +1,11 @@ #ifdef TNG_BUILD_OPENMP_EXAMPLES -# include -# include -# include -# include -# include -#include "../../include/tng_io.h" +#include +#include +#include +#include +#include +#include "tng/tng_io.h" int main (); void compute ( int np, int nd, float pos[], float vel[], diff --git a/src/tests/tng_io_read_pos.c b/src/tests/tng_io_read_pos.c index 2a0bb09..b29cec7 100644 --- a/src/tests/tng_io_read_pos.c +++ b/src/tests/tng_io_read_pos.c @@ -15,7 +15,7 @@ #include #include -#include "../../include/tng_io.h" +#include "tng/tng_io.h" int main(int argc, char **argv) { diff --git a/src/tests/tng_io_read_pos_util.c b/src/tests/tng_io_read_pos_util.c index 1667bae..b237dad 100644 --- a/src/tests/tng_io_read_pos_util.c +++ b/src/tests/tng_io_read_pos_util.c @@ -17,7 +17,7 @@ #include #include -#include "../../include/tng_io.h" +#include "tng/tng_io.h" int main(int argc, char **argv) { diff --git a/src/tests/tng_io_testing.c b/src/tests/tng_io_testing.c index dd13d92..e1e2726 100644 --- a/src/tests/tng_io_testing.c +++ b/src/tests/tng_io_testing.c @@ -15,7 +15,8 @@ #include #include -#include "../../include/tng_io.h" +#include "tng/tng_io.h" +#include "tng/version.h" static tng_function_status tng_test_setup_molecules(tng_trajectory_t traj) { @@ -595,6 +596,17 @@ int main() tng_trajectory_t traj; tng_function_status stat; char time_str[TNG_MAX_DATE_STR_LEN]; + char version_str[TNG_MAX_STR_LEN]; + + tng_version(traj, version_str, TNG_MAX_STR_LEN); + if(strncmp(TNG_VERSION, version_str, TNG_MAX_STR_LEN) == 0) + { + printf("Test version control: \t\t\t\tSucceeded.\n"); + } + else + { + printf("Test version control: \t\t\t\tFailed.\n"); + } if(tng_trajectory_init(&traj) != TNG_SUCCESS) { diff --git a/src/tests/tng_parallel_read.c b/src/tests/tng_parallel_read.c index e2e23c6..44e8f79 100644 --- a/src/tests/tng_parallel_read.c +++ b/src/tests/tng_parallel_read.c @@ -13,7 +13,7 @@ #include #include -#include "../../include/tng_io.h" +#include "tng/tng_io.h" /* N.B. this code is for testing parallel reading of trajectory frame sets. The -- cgit v0.10.1