TNG API
A flexible binary trajectory format
High-level API

Functions

tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_open (const char *filename, const char mode, tng_trajectory_t *tng_data_p)
 High-level function for opening and initializing a TNG trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_close (tng_trajectory_t *tng_data_p)
 High-level function for closing a TNG trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_time_of_frame_get (const tng_trajectory_t tng_data, const int64_t frame_nr, double *time)
 High-level function for getting the time (in seconds) of a frame. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_pos_read (const tng_trajectory_t tng_data, float **positions, int64_t *stride_length)
 High-level function for reading the positions of all particles from all frames. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_vel_read (const tng_trajectory_t tng_data, float **velocities, int64_t *stride_length)
 High-level function for reading the velocities of all particles from all frames. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_force_read (const tng_trajectory_t tng_data, float **forces, int64_t *stride_length)
 High-level function for reading the forces of all particles from all frames. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read (const tng_trajectory_t tng_data, float **box_shape, int64_t *stride_length)
 High-level function for reading the box shape from all frames. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_particle_data_next_frame_read (const tng_trajectory_t tng_data, const int64_t block_id, void **values, char *data_type, int64_t *retrieved_frame_number, double *retrieved_time)
 High-level function for reading the next frame of particle-dependent data of a specific type. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_non_particle_data_next_frame_read (const tng_trajectory_t tng_data, const int64_t block_id, void **values, char *data_type, int64_t *retrieved_frame_number, double *retrieved_time)
 High-level function for reading the next frame of non-particle-dependent data of a specific type. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_pos_read_range (const tng_trajectory_t tng_data, const int64_t first_frame, const int64_t last_frame, float **positions, int64_t *stride_length)
 High-level function for reading the positions of all particles from a specific range of frames. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_vel_read_range (const tng_trajectory_t tng_data, const int64_t first_frame, const int64_t last_frame, float **velocities, int64_t *stride_length)
 High-level function for reading the velocities of all particles from a specific range of frames. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_force_read_range (const tng_trajectory_t tng_data, const int64_t first_frame, const int64_t last_frame, float **forces, int64_t *stride_length)
 High-level function for reading the forces of all particles from a specific range of frames. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read_range (const tng_trajectory_t tng_data, const int64_t first_frame, const int64_t last_frame, float **box_shape, int64_t *stride_length)
 High-level function for reading the box shape from a specific range of frames. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_set (const 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)
 High-level function for setting the writing interval of data blocks. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_double_set (const 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)
 High-level function for setting the writing interval of data blocks containing double precision data. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_set (const tng_trajectory_t tng_data, const int64_t i)
 High-level function for setting the writing interval of position data blocks. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_double_set (const tng_trajectory_t tng_data, const int64_t i)
 High-level function for setting the writing interval of position data blocks containing double precision data. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_frequency_set (const tng_trajectory_t tng_data, const int64_t i)
 High-level function for setting the writing interval of position data blocks. Obsolete! Use tng_util_pos_write_interval_set() More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_set (const tng_trajectory_t tng_data, const int64_t i)
 High-level function for setting the writing interval of velocity data blocks. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_double_set (const tng_trajectory_t tng_data, const int64_t i)
 High-level function for setting the writing interval of velocity data blocks containing double precision data. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_frequency_set (const tng_trajectory_t tng_data, const int64_t i)
 High-level function for setting the writing interval of velocity data blocks. Obsolete! Use tng_util_vel_write_interval_set() More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_set (const tng_trajectory_t tng_data, const int64_t i)
 High-level function for setting the writing interval of force data blocks. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_double_set (const tng_trajectory_t tng_data, const int64_t i)
 High-level function for setting the writing interval of force data blocks containing double precision data. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_force_write_frequency_set (const tng_trajectory_t tng_data, const int64_t i)
 High-level function for setting the writing interval of force data blocks. Obsolete! Use tng_util_force_write_interval_set() More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_set (const tng_trajectory_t tng_data, const int64_t i)
 High-level function for setting the writing interval of box shape data blocks. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_double_set (const tng_trajectory_t tng_data, const int64_t i)
 High-level function for setting the writing interval of box shape data blocks containing double precision data. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_frequency_set (const tng_trajectory_t tng_data, const int64_t i)
 High-level function for setting the writing interval of velocity data blocks. Obsolete! Use tng_util_box_shape_write_interval_set() More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_generic_write (const 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)
 High-level function for writing data of one frame to a data block. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_generic_double_write (const 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)
 High-level function for writing data of one frame to a double precision data block. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_pos_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const float *positions)
 High-level function for adding data to positions data blocks. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_pos_double_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const double *positions)
 High-level function for adding data to positions data blocks at double precision. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_vel_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const float *velocities)
 High-level function for adding data to velocities data blocks. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_vel_double_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const double *velocities)
 High-level function for adding data to velocities data blocks at double precision. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_force_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const float *forces)
 High-level function for adding data to forces data blocks. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_force_double_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const double *forces)
 High-level function for adding data to forces data blocks at double precision. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const float *box_shape)
 High-level function for adding data to box shape data blocks. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_double_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const double *box_shape)
 High-level function for adding data to box shape data blocks at double precision. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_write (const 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)
 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. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_double_write (const 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)
 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. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const float *positions)
 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. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_double_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const double *positions)
 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. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const float *velocities)
 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. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_double_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const double *velocities)
 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. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const float *forces)
 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. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_double_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const double *forces)
 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. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const float *box_shape)
 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. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_double_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const double time, const double *box_shape)
 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. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_frame_current_compression_get (const tng_trajectory_t tng_data, const int64_t block_id, int64_t *codec_id, double *factor)
 High-level function for getting the compression method and multiplication factor of the last read frame of a specific data block. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_next_frame_present_data_blocks_find (const 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)
 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. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_prepare_append_after_frame (const tng_trajectory_t tng_data, const int64_t prev_frame)
 Finds the frame set of the specified frame in order to prepare for writing after it. More...
 
tng_function_status DECLSPECDLLEXPORT tng_util_num_frames_with_data_of_block_id_get (const tng_trajectory_t tng_data, const int64_t block_id, int64_t *n_frames)
 Get the number of frames containing data of a specific type. More...
 

Detailed Description

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.

Function Documentation

◆ tng_util_box_shape_double_write()

tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_double_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const double *  box_shape 
)

High-level function for adding data to box shape data blocks at double precision.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data. If frame_nr < 0 the data is written as non-trajectory data.
box_shapeis a 1D array of data to add. The array should be of length 9.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
box_shape != 0
The pointer to the box_shape array must not be a NULL pointer.

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.

Returns
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_util_box_shape_read()

tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read ( const tng_trajectory_t  tng_data,
float **  box_shape,
int64_t *  stride_length 
)

High-level function for reading the box shape from all frames.

Parameters
tng_datais the trajectory to read from.
box_shapewill 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.
stride_lengthwill be set to the writing interval of the stored data.

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.

Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
box_shape != 0
The pointer to the box_shape array must not be a NULL pointer.
stride_length != 0
The pointer to the stride length must not be a NULL pointer.
Returns
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_util_box_shape_read_range()

tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_read_range ( const tng_trajectory_t  tng_data,
const int64_t  first_frame,
const int64_t  last_frame,
float **  box_shape,
int64_t *  stride_length 
)

High-level function for reading the box shape from a specific range of frames.

Parameters
tng_datais the trajectory to read from.
first_frameis the first frame to return position data from.
last_frameis the last frame to return position data from.
box_shapewill 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.
stride_lengthwill be set to the writing interval of the stored data.

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.

Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
start_frame_nr <= end_frame_nr
The first frame must be before the last frame.
box_shape != 0
The pointer to the box_shape array must not be a NULL pointer.
stride_length != 0
The pointer to the stride length must not be a NULL pointer.
Returns
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_util_box_shape_with_time_double_write()

tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_double_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const double  time,
const double *  box_shape 
)

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.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data.
timeis the time stamp of the frame (in seconds).
box_shapeis a 1D array of data to add. The array should be of length 9.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
frame_nr >= 0
The frame number to write must be >= 0.
time >= 0
The time stamp must be >= 0.
box_shape != 0
The pointer to the box_shape array must not be a NULL pointer.

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.

Returns
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_util_box_shape_with_time_write()

tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_with_time_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const double  time,
const float *  box_shape 
)

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.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data.
timeis the time stamp of the frame (in seconds).
box_shapeis a 1D array of data to add. The array should be of length 9.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
frame_nr >= 0
The frame number to write must be >= 0.
time >= 0
The time stamp must be >= 0.
box_shape != 0
The pointer to the box_shape array must not be a NULL pointer.

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.

Returns
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_util_box_shape_write()

tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const float *  box_shape 
)

High-level function for adding data to box shape data blocks.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data. If frame_nr < 0 the data is written as non-trajectory data.
box_shapeis a 1D array of data to add. The array should be of length 9.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
box_shape != 0
The pointer to the box_shape array must not be a NULL pointer.

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.

Returns
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_util_box_shape_write_frequency_set()

tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_frequency_set ( const tng_trajectory_t  tng_data,
const int64_t  i 
)

High-level function for setting the writing interval of velocity data blocks. Obsolete! Use tng_util_box_shape_write_interval_set()

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.

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.

Returns
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_util_box_shape_write_interval_double_set()

tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_double_set ( const tng_trajectory_t  tng_data,
const int64_t  i 
)

High-level function for setting the writing interval of box shape data blocks containing double precision data.

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
i >= 0
The writing interval must be >= 0.

This function uses tng_util_generic_write_interval_set() and will create a box shape data block if none exists.

Returns
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_util_box_shape_write_interval_set()

tng_function_status DECLSPECDLLEXPORT tng_util_box_shape_write_interval_set ( const tng_trajectory_t  tng_data,
const int64_t  i 
)

High-level function for setting the writing interval of box shape data blocks.

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
i >= 0
The writing interval must be >= 0.

This function uses tng_util_generic_write_interval_set() and will create a box shape data block if none exists.

Returns
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_util_force_double_write()

tng_function_status DECLSPECDLLEXPORT tng_util_force_double_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const double *  forces 
)

High-level function for adding data to forces data blocks at double precision.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data. If frame_nr < 0 the data is written as non-trajectory data.
forcesis a 1D array of data to add. The array should be of length n_particles * 3.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
forces != 0
The pointer to the forces array must not be a NULL pointer.

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.

Returns
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_util_force_read()

tng_function_status DECLSPECDLLEXPORT tng_util_force_read ( const tng_trajectory_t  tng_data,
float **  forces,
int64_t *  stride_length 
)

High-level function for reading the forces of all particles from all frames.

Parameters
tng_datais the trajectory to read from.
forceswill 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.
stride_lengthwill be set to the writing interval of the stored data.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
forces != 0
The pointer to the forces array must not be a NULL pointer.
stride_length != 0
The pointer to the stride length must not be a NULL pointer.
Returns
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_util_force_read_range()

tng_function_status DECLSPECDLLEXPORT tng_util_force_read_range ( const tng_trajectory_t  tng_data,
const int64_t  first_frame,
const int64_t  last_frame,
float **  forces,
int64_t *  stride_length 
)

High-level function for reading the forces of all particles from a specific range of frames.

Parameters
tng_datais the trajectory to read from.
first_frameis the first frame to return position data from.
last_frameis the last frame to return position data from.
forceswill 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.
stride_lengthwill be set to the writing interval of the stored data.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
start_frame_nr <= end_frame_nr
The first frame must be before the last frame.
forces != 0
The pointer to the forces array must not be a NULL pointer.
stride_length != 0
The pointer to the stride length must not be a NULL pointer.
Returns
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_util_force_with_time_double_write()

tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_double_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const double  time,
const double *  forces 
)

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.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data.
timeis the time stamp of the frame (in seconds).
forcesis a 1D array of data to add. The array should be of length n_particles * 3.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
frame_nr >= 0
The frame number to write must be >= 0.
time >= 0
The time stamp must be >= 0.
forces != 0
The pointer to the forces array must not be a NULL pointer.

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.

Returns
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_util_force_with_time_write()

tng_function_status DECLSPECDLLEXPORT tng_util_force_with_time_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const double  time,
const float *  forces 
)

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.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data.
timeis the time stamp of the frame (in seconds).
forcesis a 1D array of data to add. The array should be of length n_particles * 3.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
frame_nr >= 0
The frame number to write must be >= 0.
time >= 0
The time stamp must be >= 0.
forces != 0
The pointer to the forces array must not be a NULL pointer.

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.

Returns
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_util_force_write()

tng_function_status DECLSPECDLLEXPORT tng_util_force_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const float *  forces 
)

High-level function for adding data to forces data blocks.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data. If frame_nr < 0 the data is written as non-trajectory data.
forcesis a 1D array of data to add. The array should be of length n_particles * 3.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
forces != 0
The pointer to the forces array must not be a NULL pointer.

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.

Returns
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_util_force_write_frequency_set()

tng_function_status DECLSPECDLLEXPORT tng_util_force_write_frequency_set ( const tng_trajectory_t  tng_data,
const int64_t  i 
)

High-level function for setting the writing interval of force data blocks. Obsolete! Use tng_util_force_write_interval_set()

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.

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.

Returns
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_util_force_write_interval_double_set()

tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_double_set ( const tng_trajectory_t  tng_data,
const int64_t  i 
)

High-level function for setting the writing interval of force data blocks containing double precision data.

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
i >= 0
The writing interval must be >= 0.

This function uses tng_util_generic_write_interval_set() and will create a forces data block if none exists.

Returns
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_util_force_write_interval_set()

tng_function_status DECLSPECDLLEXPORT tng_util_force_write_interval_set ( const tng_trajectory_t  tng_data,
const int64_t  i 
)

High-level function for setting the writing interval of force data blocks.

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
i >= 0
The writing interval must be >= 0.

This function uses tng_util_generic_write_interval_set() and will create a forces data block if none exists.

Returns
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_util_frame_current_compression_get()

tng_function_status DECLSPECDLLEXPORT tng_util_frame_current_compression_get ( const tng_trajectory_t  tng_data,
const int64_t  block_id,
int64_t *  codec_id,
double *  factor 
)

High-level function for getting the compression method and multiplication factor of the last read frame of a specific data block.

Parameters
tng_datais the trajectory to use.
block_idis the ID number of the block containing the data of interest.
codec_idwill be set to the value of the codec_id of the compression of the data block. See tng_compression for more details.
factorwill be set to the multiplication factor applied to the values before compression, in order to get integers from them. factor is 1/precision.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
codec_id != 0
The pointer to the returned codec id must not be a NULL pointer.
factor != 0
The pointer to the returned multiplication factor must not be a NULL pointer.
Returns
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_util_generic_double_write()

tng_function_status DECLSPECDLLEXPORT tng_util_generic_double_write ( const 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 
)

High-level function for writing data of one frame to a double precision data block.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data. If frame_nr < 0 the data is written as non-trajectory data.
valuesis 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.
n_values_per_frameis 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.
block_idis the ID of the block, of which to set the output interval.
block_nameis 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.
particle_dependencyshould 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.
compressionis the compression routine to use when writing the data. Only required if the block did not exist, i.e. a new block is created.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
values != 0
The pointer to the values array must not be a NULL pointer.

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.

Returns
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_util_generic_with_time_double_write()

tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_double_write ( const 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 
)

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.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data.
timeis the time stamp of the frame (in seconds).
valuesis 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.
n_values_per_frameis 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.
block_idis the ID of the block, of which to set the output interval.
block_nameis 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.
particle_dependencyshould 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.
compressionis the compression routine to use when writing the data. Only required if the block did not exist, i.e. a new block is created.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
frame_nr >= 0
The frame number to write must be >= 0.
time >= 0
The time stamp must be >= 0.
values != 0
The pointer to the values array must not be a NULL pointer.

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.

Returns
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_util_generic_with_time_write()

tng_function_status DECLSPECDLLEXPORT tng_util_generic_with_time_write ( const 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 
)

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.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data.
timeis the time stamp of the frame (in seconds).
valuesis 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.
n_values_per_frameis 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.
block_idis the ID of the block, of which to set the output interval.
block_nameis 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.
particle_dependencyshould 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.
compressionis the compression routine to use when writing the data. Only required if the block did not exist, i.e. a new block is created.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
frame_nr >= 0
The frame number to write must be >= 0.
time >= 0
The time stamp must be >= 0.
values != 0
The pointer to the values array must not be a NULL pointer.

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.

Returns
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_util_generic_write()

tng_function_status DECLSPECDLLEXPORT tng_util_generic_write ( const 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 
)

High-level function for writing data of one frame to a data block.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data. If frame_nr < 0 the data is written as non-trajectory data.
valuesis 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.
n_values_per_frameis 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.
block_idis the ID of the block, of which to set the output interval.
block_nameis 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.
particle_dependencyshould 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.
compressionis the compression routine to use when writing the data. Only required if the block did not exist, i.e. a new block is created.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
values != 0
The pointer to the values array must not be a NULL pointer.

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.

Returns
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_util_generic_write_interval_double_set()

tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_double_set ( const 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 
)

High-level function for setting the writing interval of data blocks containing double precision data.

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.
n_values_per_frameis 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.
block_idis the ID of the block, of which to set the output interval.
block_nameis 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.
particle_dependencyshould 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.
compressionis the compression routine to use when writing the data. Only required if the block did not exist, i.e. a new block is created.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
i >= 0
The writing interval must be >= 0.

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.

Returns
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_util_generic_write_interval_set()

tng_function_status DECLSPECDLLEXPORT tng_util_generic_write_interval_set ( const 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 
)

High-level function for setting the writing interval of data blocks.

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.
n_values_per_frameis 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.
block_idis the ID of the block, of which to set the output interval.
block_nameis 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.
particle_dependencyshould 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.
compressionis the compression routine to use when writing the data. Only required if the block did not exist, i.e. a new block is created.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
i >= 0
The writing interval must be >= 0.

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.

Returns
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_util_non_particle_data_next_frame_read()

tng_function_status DECLSPECDLLEXPORT tng_util_non_particle_data_next_frame_read ( const tng_trajectory_t  tng_data,
const int64_t  block_id,
void **  values,
char *  data_type,
int64_t *  retrieved_frame_number,
double *  retrieved_time 
)

High-level function for reading the next frame of non-particle-dependent data of a specific type.

Parameters
tng_datais the trajectory to read from.
block_idis the ID number of the block containing the data of interest.
valueswill 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.
data_typewill 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.
retrieved_frame_numberwill be pointing at the frame number of the returned frame.
retrieved_timewill be pointing at the time stamp of the returned frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
values != 0
The pointer to the values array must not be a NULL pointer.
data_type != 0
The pointer to the data type of the returned data must not be a NULL pointer.
retrieved_frame_number != 0
The pointer to the frame number of the returned data must not be a NULL pointer.
retrieved_time != 0
The pointer to the time of the returned data must not be a NULL pointer.
Returns
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_util_num_frames_with_data_of_block_id_get()

tng_function_status DECLSPECDLLEXPORT tng_util_num_frames_with_data_of_block_id_get ( const tng_trajectory_t  tng_data,
const int64_t  block_id,
int64_t *  n_frames 
)

Get the number of frames containing data of a specific type.

Parameters
tng_datais the trajectory to use.
block_idis the id of the block of the data type.
n_framesis set to the number of frames containing data of the requested data type.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_util_particle_data_next_frame_read()

tng_function_status DECLSPECDLLEXPORT tng_util_particle_data_next_frame_read ( const tng_trajectory_t  tng_data,
const int64_t  block_id,
void **  values,
char *  data_type,
int64_t *  retrieved_frame_number,
double *  retrieved_time 
)

High-level function for reading the next frame of particle-dependent data of a specific type.

Parameters
tng_datais the trajectory to read from.
block_idis the ID number of the block containing the data of interest.
valueswill be set to point at a 1-dimensional array containing the requested data. The variable may point at already allocated memory (which will be reallocated with realloc()), or be a NULL pointer. The calling code must free the memory afterwards.
data_typewill 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.
retrieved_frame_numberwill be pointing at the frame number of the returned frame.
retrieved_timewill be pointing at the time stamp of the returned frame.

If no frame has been read before the first frame of the trajectory is read.

Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
values != 0
The pointer to the values array must not be a NULL pointer.
data_type != 0
The pointer to the data type of the returned data must not be a NULL pointer.
retrieved_frame_number != 0
The pointer to the frame number of the returned data must not be a NULL pointer.
retrieved_time != 0
The pointer to the time of the returned data must not be a NULL pointer.
Returns
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_util_pos_double_write()

tng_function_status DECLSPECDLLEXPORT tng_util_pos_double_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const double *  positions 
)

High-level function for adding data to positions data blocks at double precision.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data. If frame_nr < 0 the data is written as non-trajectory data.
positionsis a 1D array of data to add. The array should be of length n_particles * 3.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
positions != 0
The pointer to the positions array must not be a NULL pointer.

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.

Returns
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_util_pos_read()

tng_function_status DECLSPECDLLEXPORT tng_util_pos_read ( const tng_trajectory_t  tng_data,
float **  positions,
int64_t *  stride_length 
)

High-level function for reading the positions of all particles from all frames.

Parameters
tng_datais the trajectory to read from.
positionswill 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.
stride_lengthwill be set to the writing interval of the stored data.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
positions != 0
The pointer to the positions array must not be a NULL pointer.
stride_length != 0
The pointer to the stride length must not be a NULL pointer.
Returns
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_util_pos_read_range()

tng_function_status DECLSPECDLLEXPORT tng_util_pos_read_range ( const tng_trajectory_t  tng_data,
const int64_t  first_frame,
const int64_t  last_frame,
float **  positions,
int64_t *  stride_length 
)

High-level function for reading the positions of all particles from a specific range of frames.

Parameters
tng_datais the trajectory to read from.
first_frameis the first frame to return position data from.
last_frameis the last frame to return position data from.
positionswill 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.
stride_lengthwill be set to the writing interval of the stored data.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
start_frame_nr <= end_frame_nr
The first frame must be before the last frame.
positions != 0
The pointer to the positions array must not be a NULL pointer.
stride_length != 0
The pointer to the stride length must not be a NULL pointer.
Returns
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_util_pos_with_time_double_write()

tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_double_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const double  time,
const double *  positions 
)

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.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data.
timeis the time stamp of the frame (in seconds).
positionsis a 1D array of data to add. The array should be of length n_particles * 3.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
frame_nr >= 0
The frame number to write must be >= 0.
time >= 0
The time stamp must be >= 0.
positions != 0
The pointer to the positions array must not be a NULL pointer.

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.

Returns
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_util_pos_with_time_write()

tng_function_status DECLSPECDLLEXPORT tng_util_pos_with_time_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const double  time,
const float *  positions 
)

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.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data.
timeis the time stamp of the frame (in seconds).
positionsis a 1D array of data to add. The array should be of length n_particles * 3.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
frame_nr >= 0
The frame number to write must be >= 0.
time >= 0
The time stamp must be >= 0.
positions != 0
The pointer to the positions array must not be a NULL pointer.

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.

Returns
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_util_pos_write()

tng_function_status DECLSPECDLLEXPORT tng_util_pos_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const float *  positions 
)

High-level function for adding data to positions data blocks.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data. If frame_nr < 0 the data is written as non-trajectory data.
positionsis a 1D array of data to add. The array should be of length n_particles * 3.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
positions != 0
The pointer to the positions array must not be a NULL pointer.

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.

Returns
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_util_pos_write_frequency_set()

tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_frequency_set ( const tng_trajectory_t  tng_data,
const int64_t  i 
)

High-level function for setting the writing interval of position data blocks. Obsolete! Use tng_util_pos_write_interval_set()

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
i >= 0
The writing interval must be >= 0.

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.

Returns
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_util_pos_write_interval_double_set()

tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_double_set ( const tng_trajectory_t  tng_data,
const int64_t  i 
)

High-level function for setting the writing interval of position data blocks containing double precision data.

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
i >= 0
The writing interval must be >= 0.

This function uses tng_util_generic_write_interval_set() and will create a positions data block if none exists.

Returns
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_util_pos_write_interval_set()

tng_function_status DECLSPECDLLEXPORT tng_util_pos_write_interval_set ( const tng_trajectory_t  tng_data,
const int64_t  i 
)

High-level function for setting the writing interval of position data blocks.

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
i >= 0
The writing interval must be >= 0.

This function uses tng_util_generic_write_interval_set() and will create a positions data block if none exists.

Returns
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_util_prepare_append_after_frame()

tng_function_status DECLSPECDLLEXPORT tng_util_prepare_append_after_frame ( const tng_trajectory_t  tng_data,
const int64_t  prev_frame 
)

Finds the frame set of the specified frame in order to prepare for writing after it.

Parameters
tng_datais the trajectory to use.
prev_frameis the frame after which to start appending.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
prev_frame >= 0
The previous frame must not be negative.
Returns
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_util_time_of_frame_get()

tng_function_status DECLSPECDLLEXPORT tng_util_time_of_frame_get ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
double *  time 
)

High-level function for getting the time (in seconds) of a frame.

Parameters
tng_datais the trajectory containing the frame.
frame_nris the frame number of which to get the time.
timeis set to the time (in seconds) of the specified frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
time != 0
The pointer to the time must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if a minor error has occured.

◆ tng_util_trajectory_close()

tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_close ( tng_trajectory_t tng_data_p)

High-level function for closing a TNG trajectory.

Parameters
tng_data_pis a pointer to the trajectory to close. The memory will be freed after finalising the writing.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_util_trajectory_next_frame_present_data_blocks_find()

tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_next_frame_present_data_blocks_find ( const 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 
)

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.

Parameters
tng_datais the trajectory to use.
current_frameis the frame that was last read, from where to start looking for data.
n_requested_data_block_idsis the number of data blocks listed in requested_data_block_ids. If this is 0 all data blocks will be taken into account.
requested_data_block_idsis an array of data blocks to look for.
next_framewill be set to the next frame with data.
n_data_blocks_in_next_frameis set to the number of data blocks with data for next_frame.
data_block_ids_in_next_frameis 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 reallocated by this function using realloc(). The memory must be freed by the client afterwards or there will be a memory leak.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
next_frame != 0
The pointer to the next frame must not be NULL.
n_data_blocks_in_next_frame != 0
The pointer to n_data_blocks_in_next_frame must not be NULL.
*data_block_ids_in_next_frame != 0
The pointer to the list of data block IDs must not be NULL.
n_requested_data_block_ids == 0 || requested_data_block_ids != 0
If the number of requested data blocks != 0 then the array of data block IDs must not be NULL.
Returns
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_util_trajectory_open()

tng_function_status DECLSPECDLLEXPORT tng_util_trajectory_open ( const char *  filename,
const char  mode,
tng_trajectory_t tng_data_p 
)

High-level function for opening and initializing a TNG trajectory.

Parameters
filenameis a string containing the name of the trajectory to open.
modespecifies the file mode of the trajectory. Can be set to 'r', 'w' or 'a' for reading, writing or appending respectively.
tng_data_pis 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.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
filename != 0
The pointer to the filename must not be a NULL pointer.
Returns
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_util_vel_double_write()

tng_function_status DECLSPECDLLEXPORT tng_util_vel_double_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const double *  velocities 
)

High-level function for adding data to velocities data blocks at double precision.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data. If frame_nr < 0 the data is written as non-trajectory data.
velocitiesis a 1D array of data to add. The array should be of length n_particles * 3.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
velocities != 0
The pointer to the velocities array must not be a NULL pointer.

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.

Returns
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_util_vel_read()

tng_function_status DECLSPECDLLEXPORT tng_util_vel_read ( const tng_trajectory_t  tng_data,
float **  velocities,
int64_t *  stride_length 
)

High-level function for reading the velocities of all particles from all frames.

Parameters
tng_datais the trajectory to read from.
velocitieswill 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.
stride_lengthwill be set to the writing interval of the stored data.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
velocities != 0
The pointer to the velocities array must not be a NULL pointer.
stride_length != 0
The pointer to the stride length must not be a NULL pointer.
Returns
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_util_vel_read_range()

tng_function_status DECLSPECDLLEXPORT tng_util_vel_read_range ( const tng_trajectory_t  tng_data,
const int64_t  first_frame,
const int64_t  last_frame,
float **  velocities,
int64_t *  stride_length 
)

High-level function for reading the velocities of all particles from a specific range of frames.

Parameters
tng_datais the trajectory to read from.
first_frameis the first frame to return position data from.
last_frameis the last frame to return position data from.
velocitieswill 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.
stride_lengthwill be set to the writing interval of the stored data.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
start_frame_nr <= end_frame_nr
The first frame must be before the last frame.
velocities != 0
The pointer to the velocities array must not be a NULL pointer.
stride_length != 0
The pointer to the stride length must not be a NULL pointer.
Returns
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_util_vel_with_time_double_write()

tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_double_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const double  time,
const double *  velocities 
)

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.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data.
timeis the time stamp of the frame (in seconds).
velocitiesis a 1D array of data to add. The array should be of length n_particles * 3.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
frame_nr >= 0
The frame number to write must be >= 0.
time >= 0
The time stamp must be >= 0.
velocities != 0
The pointer to the velocities array must not be a NULL pointer.

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.

Returns
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_util_vel_with_time_write()

tng_function_status DECLSPECDLLEXPORT tng_util_vel_with_time_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const double  time,
const float *  velocities 
)

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.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data.
timeis the time stamp of the frame (in seconds).
velocitiesis a 1D array of data to add. The array should be of length n_particles * 3.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
frame_nr >= 0
The frame number to write must be >= 0.
time >= 0
The time stamp must be >= 0.
velocities != 0
The pointer to the velocities array must not be a NULL pointer.

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.

Returns
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_util_vel_write()

tng_function_status DECLSPECDLLEXPORT tng_util_vel_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const float *  velocities 
)

High-level function for adding data to velocities data blocks.

Parameters
tng_datais the trajectory to use.
frame_nris the frame number of the data. If frame_nr < 0 the data is written as non-trajectory data.
velocitiesis a 1D array of data to add. The array should be of length n_particles * 3.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
velocities != 0
The pointer to the velocities array must not be a NULL pointer.

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.

Returns
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_util_vel_write_frequency_set()

tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_frequency_set ( const tng_trajectory_t  tng_data,
const int64_t  i 
)

High-level function for setting the writing interval of velocity data blocks. Obsolete! Use tng_util_vel_write_interval_set()

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.

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.

Returns
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_util_vel_write_interval_double_set()

tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_double_set ( const tng_trajectory_t  tng_data,
const int64_t  i 
)

High-level function for setting the writing interval of velocity data blocks containing double precision data.

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
i >= 0
The writing interval must be >= 0.

This function uses tng_util_generic_write_interval_set() and will create a velocities data block if none exists.

Returns
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_util_vel_write_interval_set()

tng_function_status DECLSPECDLLEXPORT tng_util_vel_write_interval_set ( const tng_trajectory_t  tng_data,
const int64_t  i 
)

High-level function for setting the writing interval of velocity data blocks.

Parameters
tng_datais the trajectory to use.
iis the output interval, i.e. i == 10 means data written every 10th frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
i >= 0
The writing interval must be >= 0.

This function uses tng_util_generic_write_interval_set() and will create a velocities data block if none exists.

Returns
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.