TNG API  1.8.2
A flexible binary trajectory format
Low-level API

Functions

tng_function_status DECLSPECDLLEXPORT tng_version_major (const tng_trajectory_t tng_data, int *version)
 Get the major version of the TNG library. More...
 
tng_function_status DECLSPECDLLEXPORT tng_version_minor (const tng_trajectory_t tng_data, int *version)
 Get the minor version of the TNG library. More...
 
tng_function_status DECLSPECDLLEXPORT tng_version_patchlevel (const tng_trajectory_t tng_data, int *patch_level)
 Get the patch level of the TNG library. More...
 
tng_function_status DECLSPECDLLEXPORT tng_version (const tng_trajectory_t tng_data, char *version, const int max_len)
 Get the full version string of the TNG library. More...
 
tng_function_status DECLSPECDLLEXPORT tng_trajectory_init (tng_trajectory_t *tng_data_p)
 Setup a trajectory data container. More...
 
tng_function_status DECLSPECDLLEXPORT tng_trajectory_destroy (tng_trajectory_t *tng_data_p)
 Clean up a trajectory data container. More...
 
tng_function_status DECLSPECDLLEXPORT tng_trajectory_init_from_src (const tng_trajectory_t src, tng_trajectory_t *dest_p)
 Copy a trajectory data container (dest is setup as well). More...
 
tng_function_status DECLSPECDLLEXPORT tng_input_file_get (const tng_trajectory_t tng_data, char *file_name, const int max_len)
 Get the name of the input file. More...
 
tng_function_status DECLSPECDLLEXPORT tng_input_file_set (const tng_trajectory_t tng_data, const char *file_name)
 Set the name of the input file. More...
 
tng_function_status DECLSPECDLLEXPORT tng_output_append_file_set (const tng_trajectory_t tng_data, const char *file_name)
 Set the name of the output file for appending. The output file will not be overwritten. More...
 
tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_get (const tng_trajectory_t tng_data, tng_file_endianness *endianness)
 Get the endianness of the output file. More...
 
tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_set (const tng_trajectory_t tng_data, const tng_file_endianness endianness)
 Set the endianness of the output file. More...
 
tng_function_status DECLSPECDLLEXPORT tng_first_program_name_get (const tng_trajectory_t tng_data, char *name, const int max_len)
 Get the name of the program used when creating the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_first_program_name_set (const tng_trajectory_t tng_data, const char *new_name)
 Set the name of the program used when creating the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_last_program_name_get (const tng_trajectory_t tng_data, char *name, const int max_len)
 Get the name of the program used when last modifying the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_last_program_name_set (const tng_trajectory_t tng_data, const char *new_name)
 Set the name of the program used when last modifying the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_first_user_name_get (const tng_trajectory_t tng_data, char *name, const int max_len)
 Get the name of the user who created the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_first_user_name_set (const tng_trajectory_t tng_data, const char *new_name)
 Set the name of the user who created the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_last_user_name_get (const tng_trajectory_t tng_data, char *name, const int max_len)
 Get the name of the user who last modified the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_last_user_name_set (const tng_trajectory_t tng_data, const char *new_name)
 Set the name of the user who last modified the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_get (const tng_trajectory_t tng_data, char *name, const int max_len)
 Get the name of the computer used when creating the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_set (const tng_trajectory_t tng_data, const char *new_name)
 Set the name of the computer used when creating the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_get (const tng_trajectory_t tng_data, char *name, const int max_len)
 Get the name of the computer used when last modifying the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_set (const tng_trajectory_t tng_data, const char *new_name)
 Set the name of the computer used when last modifying the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_first_signature_get (const tng_trajectory_t tng_data, char *signature, const int max_len)
 Get the pgp_signature of the user creating the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_first_signature_set (const tng_trajectory_t tng_data, const char *signature)
 Set the pgp_signature of the user creating the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_last_signature_get (const tng_trajectory_t tng_data, char *signature, const int max_len)
 Get the pgp_signature of the user last modifying the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_last_signature_set (const tng_trajectory_t tng_data, const char *signature)
 Set the pgp_signature of the user last modifying the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_get (const tng_trajectory_t tng_data, char *name, const int max_len)
 Get the name of the forcefield used in the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_set (const tng_trajectory_t tng_data, const char *new_name)
 Set the name of the forcefield used in the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_get (const tng_trajectory_t tng_data, int64_t *len)
 Get the medium stride length of the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_set (const tng_trajectory_t tng_data, const int64_t len)
 Set the medium stride length of the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_get (const tng_trajectory_t tng_data, int64_t *len)
 Get the long stride length of the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_set (const tng_trajectory_t tng_data, const int64_t len)
 Set the long stride length of the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_get (const tng_trajectory_t tng_data, double *time)
 Get the current time per frame of the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_set (const tng_trajectory_t tng_data, const double time)
 Set the time per frame of the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_input_file_len_get (const tng_trajectory_t tng_data, int64_t *len)
 Get the length of the input file. More...
 
tng_function_status DECLSPECDLLEXPORT tng_num_frames_get (const tng_trajectory_t tng_data, int64_t *n)
 Get the number of frames in the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_compression_precision_get (const tng_trajectory_t tng_data, double *precision)
 Get the precision of lossy compression. More...
 
tng_function_status DECLSPECDLLEXPORT tng_compression_precision_set (const tng_trajectory_t tng_data, const double precision)
 Set the precision of lossy compression. More...
 
tng_function_status DECLSPECDLLEXPORT tng_implicit_num_particles_set (const tng_trajectory_t tng_data, const int64_t n)
 Set the number of particles, in the case no molecular system is used. More...
 
tng_function_status DECLSPECDLLEXPORT tng_num_particles_get (const tng_trajectory_t tng_data, int64_t *n)
 Get the current number of particles. More...
 
tng_function_status DECLSPECDLLEXPORT tng_num_particles_variable_get (const tng_trajectory_t tng_data, char *variable)
 Get if the number of particle can be varied during the simulation. More...
 
tng_function_status DECLSPECDLLEXPORT tng_num_molecule_types_get (const tng_trajectory_t tng_data, int64_t *n)
 Get the number of molecule types (length of tng_data->molecules). More...
 
tng_function_status DECLSPECDLLEXPORT tng_num_molecules_get (const tng_trajectory_t tng_data, int64_t *n)
 Get the current total number of molecules. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_list_get (const tng_trajectory_t tng_data, int64_t **mol_cnt_list)
 Get the list of the count of each molecule. More...
 
tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_get (const tng_trajectory_t tng_data, int64_t *exp)
 Get the exponent used for distances in the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_set (const tng_trajectory_t tng_data, const int64_t exp)
 Set the exponent used for distances in the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_get (const tng_trajectory_t tng_data, int64_t *n)
 Get the number of frames per frame set. More...
 
tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_set (const tng_trajectory_t tng_data, const int64_t n)
 Set the number of frames per frame set. More...
 
tng_function_status DECLSPECDLLEXPORT tng_num_frame_sets_get (const tng_trajectory_t tng_data, int64_t *n)
 Get the number of frame sets. More...
 
tng_function_status DECLSPECDLLEXPORT tng_current_frame_set_get (const tng_trajectory_t tng_data, tng_trajectory_frame_set_t *frame_set_p)
 Get the current trajectory frame set. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_set_nr_find (const tng_trajectory_t tng_data, const int64_t nr)
 Find the requested frame set number. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_set_of_frame_find (const tng_trajectory_t tng_data, const int64_t frame)
 Find the frame set containing a specific frame. More...
 
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)
 Get the file position of the next frame set in the input file. More...
 
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)
 Get the file position of the previous frame set in the input file. More...
 
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)
 Get the first and last frames of the frame set. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_alloc (const tng_trajectory_t tng_data, tng_molecule_t *molecule_p)
 Allocate memory for and setup a molecule container. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_free (const tng_trajectory_t tng_data, tng_molecule_t *molecule_p)
 Clean up a molecule container and free its allocated memory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_init (const tng_trajectory_t tng_data, const tng_molecule_t molecule)
 Setup a molecule container. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_destroy (const tng_trajectory_t tng_data, const tng_molecule_t molecule)
 Clean up a molecule container. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_add (const tng_trajectory_t tng_data, const char *name, tng_molecule_t *molecule)
 Add a molecule to the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_w_id_add (const tng_trajectory_t tng_data, const char *name, const int64_t id, tng_molecule_t *molecule)
 Add a molecule with a specific ID to the trajectory. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_existing_add (const tng_trajectory_t tng_data, tng_molecule_t *molecule)
 Add an existing molecule (from a molecule container) to the trajectory. More...
 
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)
 Get the name of a molecule. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_name_set (const tng_trajectory_t tng_data, const tng_molecule_t molecule, const char *new_name)
 Set the name of a molecule. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_get (const tng_trajectory_t tng_data, const tng_molecule_t molecule, int64_t *cnt)
 Get the count of a molecule. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_set (const tng_trajectory_t tng_data, const tng_molecule_t molecule, const int64_t cnt)
 Set the count of a molecule. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_find (const tng_trajectory_t tng_data, const char *name, const int64_t id, tng_molecule_t *molecule)
 Find a molecule. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_of_index_get (const tng_trajectory_t tng_data, const int64_t index, tng_molecule_t *molecule)
 Retrieve the molecule with specified index in the list of molecules. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_system_copy (const tng_trajectory_t tng_data_src, const tng_trajectory_t tng_data_dest)
 Copy all molecules and the molecule counts from one TNG trajectory to another. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_num_chains_get (const tng_trajectory_t tng_data, const tng_molecule_t molecule, int64_t *n)
 Get the number of chains in a molecule. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_of_index_get (const tng_trajectory_t tng_data, const tng_molecule_t molecule, const int64_t index, tng_chain_t *chain)
 Retrieve the chain of a molecule with specified index in the list of chains. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_num_residues_get (const tng_trajectory_t tng_data, const tng_molecule_t molecule, int64_t *n)
 Get the number of residues in a molecule. More...
 
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)
 Retrieve the residue of a molecule with specified index in the list of chains. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_num_atoms_get (const tng_trajectory_t tng_data, const tng_molecule_t molecule, int64_t *n)
 Get the number of atoms in a molecule. More...
 
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)
 Retrieve the atom of a molecule with specified index in the list of atoms. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_find (const tng_trajectory_t tng_data, const tng_molecule_t molecule, const char *name, const int64_t id, tng_chain_t *chain)
 Find a chain in a molecule. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_add (const tng_trajectory_t tng_data, const tng_molecule_t molecule, const char *name, tng_chain_t *chain)
 Add a chain to a molecule. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_w_id_add (const tng_trajectory_t tng_data, const tng_molecule_t molecule, const char *name, const int64_t id, tng_chain_t *chain)
 Add a chain with a specific id to a molecule. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_bond_add (const tng_trajectory_t tng_data, const tng_molecule_t molecule, const int64_t from_atom_id, const int64_t to_atom_id, tng_bond_t *bond)
 Add a bond between two atoms to a molecule. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_find (const tng_trajectory_t tng_data, const tng_molecule_t molecule, const char *name, const int64_t id, tng_atom_t *atom)
 Find an atom in a molecule. More...
 
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)
 Get the name of a chain. More...
 
tng_function_status DECLSPECDLLEXPORT tng_chain_name_set (const tng_trajectory_t tng_data, const tng_chain_t chain, const char *new_name)
 Set the name of a chain. More...
 
tng_function_status DECLSPECDLLEXPORT tng_chain_num_residues_get (const tng_trajectory_t tng_data, const tng_chain_t chain, int64_t *n)
 Get the number of residues in a molecule chain. More...
 
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)
 Retrieve the residue of a chain with specified index in the list of residues. More...
 
tng_function_status DECLSPECDLLEXPORT tng_chain_residue_find (const tng_trajectory_t tng_data, const tng_chain_t chain, const char *name, const int64_t id, tng_residue_t *residue)
 Find a residue in a chain. More...
 
tng_function_status DECLSPECDLLEXPORT tng_chain_residue_add (const tng_trajectory_t tng_data, const tng_chain_t chain, const char *name, tng_residue_t *residue)
 Add a residue to a chain. More...
 
tng_function_status DECLSPECDLLEXPORT tng_chain_residue_w_id_add (const tng_trajectory_t tng_data, const tng_chain_t chain, const char *name, const int64_t id, tng_residue_t *residue)
 Add a residue with a specific ID to a chain. More...
 
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)
 Get the name of a residue. More...
 
tng_function_status DECLSPECDLLEXPORT tng_residue_name_set (const tng_trajectory_t tng_data, const tng_residue_t residue, const char *new_name)
 Set the name of a residue. More...
 
tng_function_status DECLSPECDLLEXPORT tng_residue_num_atoms_get (const tng_trajectory_t tng_data, const tng_residue_t residue, int64_t *n)
 Get the number of atoms in a residue. More...
 
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)
 Retrieve the atom of a residue with specified index in the list of atoms. More...
 
tng_function_status DECLSPECDLLEXPORT tng_residue_atom_add (const tng_trajectory_t tng_data, const tng_residue_t residue, const char *atom_name, const char *atom_type, tng_atom_t *atom)
 Add an atom to a residue. More...
 
tng_function_status DECLSPECDLLEXPORT tng_residue_atom_w_id_add (const tng_trajectory_t tng_data, const tng_residue_t residue, const char *atom_name, const char *atom_type, const int64_t id, tng_atom_t *atom)
 Add an atom with a specific ID to a residue. More...
 
tng_function_status DECLSPECDLLEXPORT tng_atom_residue_get (const tng_trajectory_t tng_data, const tng_atom_t atom, tng_residue_t *residue)
 Get the residue of an atom. More...
 
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)
 Get the name of an atom. More...
 
tng_function_status DECLSPECDLLEXPORT tng_atom_name_set (const tng_trajectory_t tng_data, const tng_atom_t atom, const char *new_name)
 Set the name of an atom. More...
 
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)
 Get the type of an atom. More...
 
tng_function_status DECLSPECDLLEXPORT tng_atom_type_set (const tng_trajectory_t tng_data, const tng_atom_t atom, const char *new_type)
 Set the atom type of an atom. More...
 
tng_function_status DECLSPECDLLEXPORT tng_molecule_id_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, int64_t *id)
 Get the molecule id of real particle number (number in mol system). More...
 
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)
 Get the bonds of the current molecular system. More...
 
tng_function_status DECLSPECDLLEXPORT tng_chain_name_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, char *name, const int max_len)
 Get the chain name of real particle number (number in mol system). More...
 
tng_function_status DECLSPECDLLEXPORT tng_residue_name_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, char *name, const int max_len)
 Get the residue name of real particle number (number in mol system). More...
 
tng_function_status DECLSPECDLLEXPORT tng_residue_id_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, int64_t *id)
 Get the residue id (local to molecule) of real particle number (number in mol system). More...
 
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)
 Get the residue id (based on other molecules and molecule counts) of real particle number (number in mol system). More...
 
tng_function_status DECLSPECDLLEXPORT tng_atom_name_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, char *name, const int max_len)
 Get the atom name of real particle number (number in mol system). More...
 
tng_function_status DECLSPECDLLEXPORT tng_atom_type_of_particle_nr_get (const tng_trajectory_t tng_data, const int64_t nr, char *type, const int max_len)
 Get the atom type of real particle number (number in mol system). More...
 
tng_function_status DECLSPECDLLEXPORT tng_particle_mapping_add (const tng_trajectory_t tng_data, const int64_t num_first_particle, const int64_t n_particles, const int64_t *mapping_table)
 Add a particle mapping table. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_set_particle_mapping_free (const tng_trajectory_t tng_data)
 Remove all particle mappings (in memory) from the current frame set. More...
 
tng_function_status DECLSPECDLLEXPORT tng_file_headers_read (const tng_trajectory_t tng_data, const char hash_mode)
 Read the header blocks from the input_file of tng_data. More...
 
tng_function_status DECLSPECDLLEXPORT tng_file_headers_write (const tng_trajectory_t tng_data, const char hash_mode)
 Write the header blocks to the output_file of tng_data. More...
 
tng_function_status DECLSPECDLLEXPORT tng_block_read_next (const tng_trajectory_t tng_data, const tng_gen_block_t block_data, const char hash_mode)
 Read one (the next) block (of any kind) from the input_file of tng_data. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_set_read (const tng_trajectory_t tng_data, const char hash_mode)
 Read one frame set, including all particle mapping blocks and data blocks, starting from the current file position. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_current_only_data_from_block_id (const tng_trajectory_t tng_data, const char hash_mode, const int64_t block_id)
 Read data from the current frame set from the input_file. Only read particle mapping and data blocks matching the specified block_id. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next (const tng_trajectory_t tng_data, const char hash_mode)
 Read one (the next) frame set, including particle mapping and related data blocks from the input_file of tng_data. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next_only_data_from_block_id (const tng_trajectory_t tng_data, const char hash_mode, const int64_t block_id)
 Read one (the next) frame set, including particle mapping and data blocks with a specific block id from the input_file of tng_data. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_set_write (const tng_trajectory_t tng_data, const char hash_mode)
 Write one frame set, including mapping and related data blocks to the output_file of tng_data. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_set_premature_write (const tng_trajectory_t tng_data, const char hash_mode)
 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. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_set_new (const tng_trajectory_t tng_data, const int64_t first_frame, const int64_t n_frames)
 Create and initialise a frame set. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_set_with_time_new (const tng_trajectory_t tng_data, const int64_t first_frame, const int64_t n_frames, const double first_frame_time)
 Create and initialise a frame set with the time of the first frame specified. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_set_first_frame_time_set (const tng_trajectory_t tng_data, const double first_frame_time)
 Set the time stamp of the first frame of the current frame set. More...
 
tng_function_status DECLSPECDLLEXPORT tng_first_frame_nr_of_next_frame_set_get (const tng_trajectory_t tng_data, int64_t *frame)
 Read the number of the first frame of the next frame set. More...
 
tng_function_status DECLSPECDLLEXPORT tng_data_block_add (const 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)
 Add a non-particle dependent data block. More...
 
tng_function_status DECLSPECDLLEXPORT tng_particle_data_block_add (const 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)
 Add a particle dependent data block. More...
 
tng_function_status DECLSPECDLLEXPORT tng_data_block_name_get (const tng_trajectory_t tng_data, const int64_t block_id, char *name, const int max_len)
 Get the name of a data block of a specific ID. More...
 
tng_function_status DECLSPECDLLEXPORT tng_data_block_dependency_get (const tng_trajectory_t tng_data, const int64_t block_id, int *block_dependency)
 Get the dependency of a data block of a specific ID. More...
 
tng_function_status DECLSPECDLLEXPORT tng_data_block_num_values_per_frame_get (const tng_trajectory_t tng_data, const int64_t block_id, int64_t *n_values_per_frame)
 Get the number of values per frame of a data block of a specific ID. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_data_write (const tng_trajectory_t tng_data, const int64_t frame_nr, const int64_t block_id, const void *values, const char hash_mode)
 Write data of one trajectory frame to the output_file of tng_data. More...
 
tng_function_status DECLSPECDLLEXPORT tng_frame_particle_data_write (const 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)
 Write particle data of one trajectory frame to the output_file of tng_data. More...
 
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)
 Free data of an array of values (3D). More...
 
tng_function_status DECLSPECDLLEXPORT tng_data_get (const 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)
 Retrieve non-particle data, from the last read frame set. Obsolete! More...
 
tng_function_status DECLSPECDLLEXPORT tng_data_interval_get (const 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)
 Read and retrieve non-particle data, in a specific interval. Obsolete! More...
 
tng_function_status DECLSPECDLLEXPORT tng_data_vector_interval_get (const 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)
 Read and retrieve a vector (1D array) of non-particle data, in a specific interval. More...
 
tng_function_status DECLSPECDLLEXPORT tng_particle_data_get (const 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)
 Retrieve particle data, from the last read frame set. Obsolete! More...
 
tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_get (const 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)
 Retrieve a vector (1D array) of particle data, from the last read frame set. More...
 
tng_function_status DECLSPECDLLEXPORT tng_particle_data_interval_get (const 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)
 Read and retrieve particle data, in a specific interval. Obsolete! More...
 
tng_function_status DECLSPECDLLEXPORT tng_particle_data_vector_interval_get (const 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)
 Read and retrieve a vector (1D array) particle data, in a specific interval. More...
 
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)
 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. More...
 
tng_function_status DECLSPECDLLEXPORT tng_time_get_str (const tng_trajectory_t tng_data, char *time)
 Get the date and time of initial file creation in ISO format (string). More...
 

Detailed Description

These functions give detailed control of the TNG data management. Most things can be done using the more convenient high-level API functions instead.

Function Documentation

◆ tng_atom_name_get()

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 
)

Get the name of an atom.

Parameters
tng_datathe trajectory containing the atom.
atomthe atom of which to get the name.
namethe string to fill with the name of the atom, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for name. This includes \0 terminating character.
Precondition
atom != 0
The atom must not be NULL.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_atom_name_of_particle_nr_get()

tng_function_status DECLSPECDLLEXPORT tng_atom_name_of_particle_nr_get ( const tng_trajectory_t  tng_data,
const int64_t  nr,
char *  name,
const int  max_len 
)

Get the atom name of real particle number (number in mol system).

Parameters
tng_datais the trajectory data container containing the atom.
nris the real number of the particle in the molecular system.
nameis a string, which is set to the name of the atom. Memory must be reserved beforehand.
max_lenis the maximum length of name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error has occured.

◆ tng_atom_name_set()

tng_function_status DECLSPECDLLEXPORT tng_atom_name_set ( const tng_trajectory_t  tng_data,
const tng_atom_t  atom,
const char *  new_name 
)

Set the name of an atom.

Parameters
tng_datais the trajectory data container containing the atom.
atomis the atom to rename.
new_nameis a string containing the wanted name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
new_name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_atom_residue_get()

tng_function_status DECLSPECDLLEXPORT tng_atom_residue_get ( const tng_trajectory_t  tng_data,
const tng_atom_t  atom,
tng_residue_t residue 
)

Get the residue of an atom.

Parameters
tng_datathe trajectory containing the atom.
atomthe atom of which to get the name.
residueis set to the residue of the atom.
Precondition
atom != 0
The atom must not be NULL.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_atom_type_get()

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 
)

Get the type of an atom.

Parameters
tng_datathe trajectory containing the atom.
atomthe atom of which to get the type.
typethe string to fill with the type of the atom, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for type. This includes \0 terminating character.
Precondition
atom != 0
The atom must not be NULL.
type != 0
The pointer to the type string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_atom_type_of_particle_nr_get()

tng_function_status DECLSPECDLLEXPORT tng_atom_type_of_particle_nr_get ( const tng_trajectory_t  tng_data,
const int64_t  nr,
char *  type,
const int  max_len 
)

Get the atom type of real particle number (number in mol system).

Parameters
tng_datais the trajectory data container containing the atom.
nris the real number of the particle in the molecular system.
typeis a string, which is set to the type of the atom. Memory must be reserved beforehand.
max_lenis the maximum length of type.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
type != 0
The pointer to the type string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error has occured.

◆ tng_atom_type_set()

tng_function_status DECLSPECDLLEXPORT tng_atom_type_set ( const tng_trajectory_t  tng_data,
const tng_atom_t  atom,
const char *  new_type 
)

Set the atom type of an atom.

Parameters
tng_datais the trajectory data container containing the atom.
atomis the atom to change.
new_typeis a string containing the atom type.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
new_type != 0
The pointer to the atom type string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_block_read_next()

tng_function_status DECLSPECDLLEXPORT tng_block_read_next ( const tng_trajectory_t  tng_data,
const tng_gen_block_t  block_data,
const char  hash_mode 
)

Read one (the next) block (of any kind) from the input_file of tng_data.

Parameters
tng_datais 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.

Parameters
block_datais a pointer to the struct which will be populated with the data.

If block_data->input_file_pos > 0 it is the position from where the reading starts otherwise it starts from the current position.

Parameters
hash_modeis 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.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
block != 0
The block container (block) must be initialised before using it.
Returns
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_chain_name_get()

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 
)

Get the name of a chain.

Parameters
tng_datathe trajectory containing the chain.
chainthe chain of which to get the name.
namethe string to fill with the name of the chain, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for name. This includes \0 terminating character.
Precondition
chain != 0
The chain must not be NULL.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_chain_name_of_particle_nr_get()

tng_function_status DECLSPECDLLEXPORT tng_chain_name_of_particle_nr_get ( const tng_trajectory_t  tng_data,
const int64_t  nr,
char *  name,
const int  max_len 
)

Get the chain name of real particle number (number in mol system).

Parameters
tng_datais the trajectory data container containing the atom.
nris the real number of the particle in the molecular system.
nameis a string, which is set to the name of the chain. Memory must be reserved beforehand.
max_lenis the maximum length of name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error has occured.

◆ tng_chain_name_set()

tng_function_status DECLSPECDLLEXPORT tng_chain_name_set ( const tng_trajectory_t  tng_data,
const tng_chain_t  chain,
const char *  new_name 
)

Set the name of a chain.

Parameters
tng_datais the trajectory data container containing the atom..
chainis the chain to rename.
new_nameis a string containing the wanted name.
Precondition
new_name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_chain_num_residues_get()

tng_function_status DECLSPECDLLEXPORT tng_chain_num_residues_get ( const tng_trajectory_t  tng_data,
const tng_chain_t  chain,
int64_t *  n 
)

Get the number of residues in a molecule chain.

Parameters
tng_datais the trajectory containing the chain.
chainis the chain of which to get the number of residues.
nis pointing to a value set to the number of residues.
Precondition
chain != 0
The chain must not be NULL.
n != 0
The pointer to n must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_chain_residue_add()

tng_function_status DECLSPECDLLEXPORT tng_chain_residue_add ( const tng_trajectory_t  tng_data,
const tng_chain_t  chain,
const char *  name,
tng_residue_t residue 
)

Add a residue to a chain.

Parameters
tng_datais the trajectory data container containing the chain..
chainis the chain to add a residue to.
nameis a string containing the name of the residue.
residueis a pointer to the newly created residue.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
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_chain_residue_find()

tng_function_status DECLSPECDLLEXPORT tng_chain_residue_find ( const tng_trajectory_t  tng_data,
const tng_chain_t  chain,
const char *  name,
const int64_t  id,
tng_residue_t residue 
)

Find a residue in a chain.

Parameters
tng_datais the trajectory data container containing the chain.
chainis the chain in which to search for the residue.
nameis a string containing the name of the residue. If name is an empty string only id will be used for searching.
idis the id of the residue to find. If id == -1 the first residue that matches the specified name will be found.
residueis a pointer to the residue if it was found - otherwise 0.
Precondition
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the residue is not found.

If name is an empty string and id == -1 the first residue will be found.

◆ tng_chain_residue_of_index_get()

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 
)

Retrieve the residue of a chain with specified index in the list of residues.

Parameters
tng_datais the trajectory data container containing the chain.
indexis the index (in chain->residues) of the residue to return
chainis the chain from which to get the residue.
residueis a pointer to the residue if it was found - otherwise 0.
Precondition
chain != 0
chain must not be a NULL pointer.
residue != 0
residue must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the residue is not found.

◆ tng_chain_residue_w_id_add()

tng_function_status DECLSPECDLLEXPORT tng_chain_residue_w_id_add ( const tng_trajectory_t  tng_data,
const tng_chain_t  chain,
const char *  name,
const int64_t  id,
tng_residue_t residue 
)

Add a residue with a specific ID to a chain.

Parameters
tng_datais the trajectory data container containing the chain..
chainis the chain to add a residue to.
nameis a string containing the name of the residue.
idis the ID of the created residue.
residueis a pointer to the newly created residue.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
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_compression_precision_get()

tng_function_status DECLSPECDLLEXPORT tng_compression_precision_get ( const tng_trajectory_t  tng_data,
double *  precision 
)

Get the precision of lossy compression.

Parameters
tng_datais the trajectory of which to get the compression precision.
precisionwill be pointing to the retrieved compression precision.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.

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().

Returns
TNG_SUCCESS (0) if successful.

◆ tng_compression_precision_set()

tng_function_status DECLSPECDLLEXPORT tng_compression_precision_set ( const tng_trajectory_t  tng_data,
const double  precision 
)

Set the precision of lossy compression.

Parameters
tng_datais the trajectory of which to set the compression precision.
precisionis the new compression precision.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.

A compression precision of 0.001 (the default) means that the compressed values are accurate to the third decimal.

Returns
TNG_SUCCESS (0) if successful.

◆ tng_current_frame_set_get()

tng_function_status DECLSPECDLLEXPORT tng_current_frame_set_get ( const tng_trajectory_t  tng_data,
tng_trajectory_frame_set_t frame_set_p 
)

Get the current trajectory frame set.

Parameters
tng_datais the trajectory from which to get the frame set.
frame_set_pwill be set to point at the memory position of the found frame set.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_data_block_add()

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

Add a non-particle dependent data block.

Parameters
tng_datais the trajectory data container in which to add the data block
idis the block ID of the block to add.
block_nameis a descriptive name of the block to add
datatypeis the datatype of the data in the block (e.g. int/float)
block_type_flagindicates if this is a non-trajectory block (added directly to tng_data) or if it is a trajectory block (added to the frame set)
n_framesis the number of frames of the data block (automatically set to 1 if adding a non-trajectory data block)
n_values_per_frameis how many values a stored each frame (e.g. 9 for a box shape block)
stride_lengthis how many frames are between each entry in the data block
codec_idis the ID of the codec to compress the data.
new_datais an array of data values to add.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
block_name != 0
The pointer to the block name must not be a NULL pointer.
n_values_per_frame > 0
n_values_per_frame must be a positive integer.
Returns
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_data_block_dependency_get()

tng_function_status DECLSPECDLLEXPORT tng_data_block_dependency_get ( const tng_trajectory_t  tng_data,
const int64_t  block_id,
int *  block_dependency 
)

Get the dependency of a data block of a specific ID.

Parameters
tng_datais the trajectory data container.
block_idis the ID of the data block of which to get the name.
block_dependencyis 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.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
block_dependency != 0
The pointer to the block dependency must not be a NULL pointer.
Returns
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_data_block_name_get()

tng_function_status DECLSPECDLLEXPORT tng_data_block_name_get ( const tng_trajectory_t  tng_data,
const int64_t  block_id,
char *  name,
const int  max_len 
)

Get the name of a data block of a specific ID.

Parameters
tng_datais the trajectory data container.
block_idis the ID of the data block of which to get the name.
nameis a string, which is set to the name of the data block. Memory must be reserved beforehand.
max_lenis the maximum length of name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
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_data_block_num_values_per_frame_get()

tng_function_status DECLSPECDLLEXPORT tng_data_block_num_values_per_frame_get ( const tng_trajectory_t  tng_data,
const int64_t  block_id,
int64_t *  n_values_per_frame 
)

Get the number of values per frame of a data block of a specific ID.

Parameters
tng_datais the trajectory data container.
block_idis the ID of the data block of which to get the name.
n_values_per_frameis a pointer set to the number of values per frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
n_values_per_frame != 0
The pointer to the number of values per frame must not be a NULL pointer.
Returns
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_data_get()

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

Retrieve non-particle data, from the last read frame set. Obsolete!

Parameters
tng_datais 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.
block_idis the id number of the particle data block to read.
valuesis 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.
n_framesis set to the number of frames in the returned data. This is needed to properly reach and/or free the data afterwards.
n_values_per_frameis set to the number of values per frame in the data. This is needed to properly reach and/or free the data afterwards.
typeis set to the data type of the data in the array.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
n_frames != 0
The pointer to the number of frames must not be a NULL pointer.
n_values_per_frame != 0
The pointer to the number of values per frame must not be a NULL pointer.
type != 0
The pointer to the data type must not be a NULL pointer.

This function is obsolete and only retained for compatibility. Use tng_data_vector_get() instead.

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

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 
)

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.

Parameters
tng_datais the trajectory data container.
block_idis the block ID of the data block, of which to retrieve the stride length of the data.
frameis 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.
stride_lengthis set to the value of the stride length of the data block.
Returns
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_data_interval_get()

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

Read and retrieve non-particle data, in a specific interval. Obsolete!

Parameters
tng_datais 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.
block_idis the id number of the particle data block to read.
start_frame_nris the index number of the first frame to read.
end_frame_nris the index number of the last frame to read.
hash_modeis 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.
valuesis 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.
n_values_per_frameis set to the number of values per frame in the data. This is needed to properly reach and/or free the data afterwards.
typeis set to the data type of the data in the array.
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.
n_values_per_frame != 0
The pointer to the number of values per frame must not be a NULL pointer.
type != 0
The pointer to the data type must not be a NULL pointer.

This function is obsolete and only retained for compatibility. Use tng_data_vector_interval_get() instead.

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

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

Read and retrieve a vector (1D array) of non-particle data, in a specific interval.

Parameters
tng_datais 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.
block_idis the id number of the particle data block to read.
start_frame_nris the index number of the first frame to read.
end_frame_nris the index number of the last frame to read.
hash_modeis 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.
valuesis a pointer to a 1-dimensional array (memory unallocated), which will be filled with data. The length of the array will be (n_frames_with_data (see stride_length) * n_values_per_frame). Since **values is allocated in this function it is the callers responsibility to free the memory.
stride_lengthis set to the stride length (writing interval) of the data.
n_values_per_frameis set to the number of values per frame in the data. This is needed to properly reach and/or free the data afterwards.
typeis set to the data type of the data in the array.
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.
stride_length != 0
The pointer to the stride length must not be a NULL pointer.
n_values_per_frame != 0
The pointer to the number of values per frame must not be a NULL pointer.
type != 0
The pointer to the data type must not be a NULL pointer.

This does only work for numerical (int, float, double) data.

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

tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_get ( const tng_trajectory_t  tng_data,
int64_t *  exp 
)

Get the exponent used for distances in the trajectory.

Parameters
tng_datais the trajectory from which to get the information.
expis pointing to a value set to the distance unit exponent.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
exp != 0
The pointer to exp must not be a NULL pointer.

Example: If the distances are specified in nm (default) exp is -9. If the distances are specified in Ã… exp is -10.

Returns
TNG_SUCCESS (0) if successful.

◆ tng_distance_unit_exponential_set()

tng_function_status DECLSPECDLLEXPORT tng_distance_unit_exponential_set ( const tng_trajectory_t  tng_data,
const int64_t  exp 
)

Set the exponent used for distances in the trajectory.

Parameters
tng_datais the trajectory of which to set the unit exponent.
expis the distance unit exponent to use.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.

Example: If the distances are specified in nm (default) exp is -9. If the distances are specified in Ã… exp is -10.

Returns
TNG_SUCCESS (0) if successful.

◆ tng_file_headers_read()

tng_function_status DECLSPECDLLEXPORT tng_file_headers_read ( const tng_trajectory_t  tng_data,
const char  hash_mode 
)

Read the header blocks from the input_file of tng_data.

The trajectory blocks must be read separately and iteratively in chunks to fit in memory.

Parameters
tng_datais 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.

Parameters
hash_modeis 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.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_file_headers_write()

tng_function_status DECLSPECDLLEXPORT tng_file_headers_write ( const tng_trajectory_t  tng_data,
const char  hash_mode 
)

Write the header blocks to the output_file of tng_data.

The trajectory blocks must be written separately and iteratively in chunks to fit in memory.

Parameters
tng_datais 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.

Parameters
hash_modeis 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.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_first_computer_name_get()

tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_get ( const tng_trajectory_t  tng_data,
char *  name,
const int  max_len 
)

Get the name of the computer used when creating the trajectory.

Parameters
tng_datathe trajectory of which to get the computer name.
namethe string to fill with the name of the computer, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for name. This includes \0 terminating character.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_first_computer_name_set()

tng_function_status DECLSPECDLLEXPORT tng_first_computer_name_set ( const tng_trajectory_t  tng_data,
const char *  new_name 
)

Set the name of the computer used when creating the trajectory.

Parameters
tng_datathe trajectory of which to set the computer name.
new_nameis a string containing the wanted name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
new_name != 0
The pointer to the new_name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_first_frame_nr_of_next_frame_set_get()

tng_function_status DECLSPECDLLEXPORT tng_first_frame_nr_of_next_frame_set_get ( const tng_trajectory_t  tng_data,
int64_t *  frame 
)

Read the number of the first frame of the next frame set.

Parameters
tng_datais the trajectory containing the frame set.
frameis set to the frame number of the first frame in the next frame set.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
tng_data->input_file != 0
An input file must be open to find the next frame set.
frame != 0
The pointer to the frame must not be a NULL pointer.
Returns
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_first_program_name_get()

tng_function_status DECLSPECDLLEXPORT tng_first_program_name_get ( const tng_trajectory_t  tng_data,
char *  name,
const int  max_len 
)

Get the name of the program used when creating the trajectory.

Parameters
tng_datathe trajectory of which to get the program name.
namethe string to fill with the name of the program, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for name. This includes \0 terminating character.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_first_program_name_set()

tng_function_status DECLSPECDLLEXPORT tng_first_program_name_set ( const tng_trajectory_t  tng_data,
const char *  new_name 
)

Set the name of the program used when creating the trajectory.

Parameters
tng_datathe trajectory of which to set the program name.
new_nameis a string containing the wanted name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
new_name != 0
The pointer to the new_name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_first_signature_get()

tng_function_status DECLSPECDLLEXPORT tng_first_signature_get ( const tng_trajectory_t  tng_data,
char *  signature,
const int  max_len 
)

Get the pgp_signature of the user creating the trajectory.

Parameters
tng_datathe trajectory of which to get the computer name.
signaturethe string to fill with the signature, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for name. This includes \0 terminating character.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
signature != 0
The pointer to the signature must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_first_signature_set()

tng_function_status DECLSPECDLLEXPORT tng_first_signature_set ( const tng_trajectory_t  tng_data,
const char *  signature 
)

Set the pgp_signature of the user creating the trajectory.

Parameters
tng_datathe trajectory of which to set the computer name.
signatureis a string containing the pgp_signature.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
signature != 0
The pointer to the signature must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_first_user_name_get()

tng_function_status DECLSPECDLLEXPORT tng_first_user_name_get ( const tng_trajectory_t  tng_data,
char *  name,
const int  max_len 
)

Get the name of the user who created the trajectory.

Parameters
tng_datathe trajectory of which to get the user name.
namethe string to fill with the name of the user, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for name. This includes \0 terminating character.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_first_user_name_set()

tng_function_status DECLSPECDLLEXPORT tng_first_user_name_set ( const tng_trajectory_t  tng_data,
const char *  new_name 
)

Set the name of the user who created the trajectory.

Parameters
tng_datathe trajectory of which to set the user name.
new_nameis a string containing the wanted name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
new_name != 0
The pointer to the new_name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_forcefield_name_get()

tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_get ( const tng_trajectory_t  tng_data,
char *  name,
const int  max_len 
)

Get the name of the forcefield used in the trajectory.

Parameters
tng_datathe trajectory of which to get the forcefield name.
namethe string to fill with the name of the forcefield, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for name. This includes \0 terminating character.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_forcefield_name_set()

tng_function_status DECLSPECDLLEXPORT tng_forcefield_name_set ( const tng_trajectory_t  tng_data,
const char *  new_name 
)

Set the name of the forcefield used in the trajectory.

Parameters
tng_datathe trajectory of which to set the forcefield name.
new_nameis a string containing the wanted name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
new_name != 0
The pointer to the new_name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_frame_data_write()

tng_function_status DECLSPECDLLEXPORT tng_frame_data_write ( const tng_trajectory_t  tng_data,
const int64_t  frame_nr,
const int64_t  block_id,
const void *  values,
const char  hash_mode 
)

Write data of one trajectory frame to the output_file of tng_data.

Parameters
tng_datais 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.
frame_nris the index number of the frame to write.
block_idis the ID of the data block to write the data to.
valuesis an array of data to write. The length of the array should equal n_values_per_frame.
hash_modeis 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.
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.
values != 0
The pointer to the values must not be a NULL pointer.
Returns
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_frame_particle_data_write()

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

Write particle data of one trajectory frame to the output_file of tng_data.

Parameters
tng_datais 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.
frame_nris the index number of the frame to write.
block_idis the ID of the data block to write the data to.
val_first_particleis the number of the first particle in the data array.
val_n_particlesis the number of particles in the data array.
valuesis a 1D-array of data to write. The length of the array should equal n_particles * n_values_per_frame.
hash_modeis 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.
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.
val_first_particle >= 0
The number of the first particle must be >= 0.
val_n_particles >= 0
The number of particles must be >= 0.
values != 0
The pointer to the values must not be a NULL pointer.
Returns
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_frame_set_first_frame_time_set()

tng_function_status DECLSPECDLLEXPORT tng_frame_set_first_frame_time_set ( const tng_trajectory_t  tng_data,
const double  first_frame_time 
)

Set the time stamp of the first frame of the current frame set.

Parameters
tng_datais the trajectory containing the frame set.
first_frame_timeis the time stamp of the first frame in the frame set.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
first_frame_time >= 0
The time stamp of the first frame must not be negative.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_frame_set_frame_range_get()

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 
)

Get the first and last frames of the frame set.

Parameters
tng_datais a trajectory data container.
frame_setis the frame set of which to get the frame range.
first_frameis set to the first frame of the frame set.
last_frameis set to the last frame of the frame set.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
first_frame != 0
The pointer to first_frame must not be a NULL pointer.
last_frame != 0
The pointer to last_frame must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_frame_set_new()

tng_function_status DECLSPECDLLEXPORT tng_frame_set_new ( const tng_trajectory_t  tng_data,
const int64_t  first_frame,
const int64_t  n_frames 
)

Create and initialise a frame set.

Particle mappings are retained from previous frame set (if any). To explicitly clear particle mappings use tng_frame_set_particle_mapping_free().

Parameters
tng_datais the trajectory data container in which to add the frame set.
first_frameis the first frame of the frame set.
n_framesis the number of frames in the frame set.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
first_frame >= 0
The first frame must not be negative.
n_frames >= 0
The number of frames must not be negative.
Returns
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_frame_set_next_frame_set_file_pos_get()

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 
)

Get the file position of the next frame set in the input file.

Parameters
tng_datais a trajectory data container.
frame_setis the frame set of which to get the position of the following frame set.
posis pointing to a value set to the file position.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
pos != 0
The pointer to pos must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_frame_set_nr_find()

tng_function_status DECLSPECDLLEXPORT tng_frame_set_nr_find ( const tng_trajectory_t  tng_data,
const int64_t  nr 
)

Find the requested frame set number.

Parameters
tng_datais the trajectory from which to get the frame set.
nris the frame set number to search for.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
nr >= 0
The frame set number (nr) must be >= 0.

tng_data->current_trajectory_frame_set will contain the found trajectory if successful.

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

tng_function_status DECLSPECDLLEXPORT tng_frame_set_of_frame_find ( const tng_trajectory_t  tng_data,
const int64_t  frame 
)

Find the frame set containing a specific frame.

Parameters
tng_datais the trajectory from which to get the frame set.
frameis the frame number to search for.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
frame >= 0
The frame number must be >= 0.

tng_data->current_trajectory_frame_set will contain the found trajectory if successful.

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

tng_function_status DECLSPECDLLEXPORT tng_frame_set_particle_mapping_free ( const tng_trajectory_t  tng_data)

Remove all particle mappings (in memory) from the current frame set.

Clears the currently setup particle mappings of the current frame set.

Parameters
tng_datais the trajectory, with the frame set of which to clear all particle mappings.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_frame_set_premature_write()

tng_function_status DECLSPECDLLEXPORT tng_frame_set_premature_write ( const tng_trajectory_t  tng_data,
const char  hash_mode 
)

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.

Parameters
tng_datais 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.

Parameters
hash_modeis 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.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.

The number of frames in the frame set is set to the number of frames of the data blocks before writing it to disk.

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

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 
)

Get the file position of the previous frame set in the input file.

Parameters
tng_datais a trajectory data container.
frame_setis the frame set of which to get the position of the previous frame set.
posis pointing to a value set to the file position.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
pos != 0
The pointer to pos must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_frame_set_read()

tng_function_status DECLSPECDLLEXPORT tng_frame_set_read ( const tng_trajectory_t  tng_data,
const char  hash_mode 
)

Read one frame set, including all particle mapping blocks and data blocks, starting from the current file position.

Parameters
tng_datais a trajectory data container.
hash_modeis 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.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
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_frame_set_read_current_only_data_from_block_id()

tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_current_only_data_from_block_id ( const tng_trajectory_t  tng_data,
const char  hash_mode,
const int64_t  block_id 
)

Read data from the current frame set from the input_file. Only read particle mapping and data blocks matching the specified block_id.

Parameters
tng_datais 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.

Parameters
hash_modeis 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.
block_idis the ID of the data block to read from file.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
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_frame_set_read_next()

tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next ( const tng_trajectory_t  tng_data,
const char  hash_mode 
)

Read one (the next) frame set, including particle mapping and related data blocks from the input_file of tng_data.

Parameters
tng_datais 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.

Parameters
hash_modeis 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.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
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_frame_set_read_next_only_data_from_block_id()

tng_function_status DECLSPECDLLEXPORT tng_frame_set_read_next_only_data_from_block_id ( const tng_trajectory_t  tng_data,
const char  hash_mode,
const int64_t  block_id 
)

Read one (the next) frame set, including particle mapping and data blocks with a specific block id from the input_file of tng_data.

Parameters
tng_datais 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.

Parameters
hash_modeis 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.
block_idis the ID number of the blocks that should be read from file.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
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_frame_set_with_time_new()

tng_function_status DECLSPECDLLEXPORT tng_frame_set_with_time_new ( const tng_trajectory_t  tng_data,
const int64_t  first_frame,
const int64_t  n_frames,
const double  first_frame_time 
)

Create and initialise a frame set with the time of the first frame specified.

Parameters
tng_datais the trajectory data container in which to add the frame set.
first_frameis the first frame of the frame set.
n_framesis the number of frames in the frame set.
first_frame_timeis the time stamp of the first frame (in seconds).
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
first_frame >= 0
The first frame must not be negative.
n_frames >= 0
The number of frames must not be negative.
first_frame_time >= 0
The time stamp of the first frame must not be negative.
Returns
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_frame_set_write()

tng_function_status DECLSPECDLLEXPORT tng_frame_set_write ( const tng_trajectory_t  tng_data,
const char  hash_mode 
)

Write one frame set, including mapping and related data blocks to the output_file of tng_data.

Parameters
tng_datais 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.

Parameters
hash_modeis 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.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
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_global_residue_id_of_particle_nr_get()

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 
)

Get the residue id (based on other molecules and molecule counts) of real particle number (number in mol system).

Parameters
tng_datais the trajectory data container containing the atom.
nris the real number of the particle in the molecular system.
idis a pointer to the variable, which will be set to the ID.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
id != 0
The pointer to id must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error has occured.

◆ tng_implicit_num_particles_set()

tng_function_status DECLSPECDLLEXPORT tng_implicit_num_particles_set ( const tng_trajectory_t  tng_data,
const int64_t  n 
)

Set the number of particles, in the case no molecular system is used.

Parameters
tng_datais the trajectory of which to get the number of particles.
nis the number of particles to use.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.

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.

Returns
TNG_SUCCESS (0) if successful.

◆ tng_input_file_get()

tng_function_status DECLSPECDLLEXPORT tng_input_file_get ( const tng_trajectory_t  tng_data,
char *  file_name,
const int  max_len 
)

Get the name of the input file.

Parameters
tng_datathe trajectory of which to get the input file name.
file_namethe string to fill with the name of the input file, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for file_name. This includes \0 terminating character.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
file_name != 0
The pointer to the file name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_input_file_len_get()

tng_function_status DECLSPECDLLEXPORT tng_input_file_len_get ( const tng_trajectory_t  tng_data,
int64_t *  len 
)

Get the length of the input file.

Parameters
tng_datais the trajectory from which to get the input file length.
lenis pointing to a value set to the file length.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
len != 0
The pointer to len must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_input_file_set()

tng_function_status DECLSPECDLLEXPORT tng_input_file_set ( const tng_trajectory_t  tng_data,
const char *  file_name 
)

Set the name of the input file.

Parameters
tng_datathe trajectory of which to set the input file name.
file_namethe name of the input file.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
file_name != 0
The pointer to the file name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_last_computer_name_get()

tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_get ( const tng_trajectory_t  tng_data,
char *  name,
const int  max_len 
)

Get the name of the computer used when last modifying the trajectory.

Parameters
tng_datathe trajectory of which to get the computer name.
namethe string to fill with the name of the computer, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for name. This includes \0 terminating character.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_last_computer_name_set()

tng_function_status DECLSPECDLLEXPORT tng_last_computer_name_set ( const tng_trajectory_t  tng_data,
const char *  new_name 
)

Set the name of the computer used when last modifying the trajectory.

Parameters
tng_datathe trajectory of which to set the computer name.
new_nameis a string containing the wanted name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
new_name != 0
The pointer to the new_name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_last_program_name_get()

tng_function_status DECLSPECDLLEXPORT tng_last_program_name_get ( const tng_trajectory_t  tng_data,
char *  name,
const int  max_len 
)

Get the name of the program used when last modifying the trajectory.

Parameters
tng_datathe trajectory of which to get the program name.
namethe string to fill with the name of the program, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for name. This includes \0 terminating character.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_last_program_name_set()

tng_function_status DECLSPECDLLEXPORT tng_last_program_name_set ( const tng_trajectory_t  tng_data,
const char *  new_name 
)

Set the name of the program used when last modifying the trajectory.

Parameters
tng_datathe trajectory of which to set the program name.
new_nameis a string containing the wanted name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
new_name != 0
The pointer to the new_name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_last_signature_get()

tng_function_status DECLSPECDLLEXPORT tng_last_signature_get ( const tng_trajectory_t  tng_data,
char *  signature,
const int  max_len 
)

Get the pgp_signature of the user last modifying the trajectory.

Parameters
tng_datathe trajectory of which to get the computer name.
signaturethe string to fill with the signature, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for name. This includes \0 terminating character.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
signature != 0
The pointer to the signature must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_last_signature_set()

tng_function_status DECLSPECDLLEXPORT tng_last_signature_set ( const tng_trajectory_t  tng_data,
const char *  signature 
)

Set the pgp_signature of the user last modifying the trajectory.

Parameters
tng_datathe trajectory of which to set the computer name.
signatureis a string containing the pgp_signature.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
signature != 0
The pointer to the signature must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_last_user_name_get()

tng_function_status DECLSPECDLLEXPORT tng_last_user_name_get ( const tng_trajectory_t  tng_data,
char *  name,
const int  max_len 
)

Get the name of the user who last modified the trajectory.

Parameters
tng_datathe trajectory of which to get the user name.
namethe string to fill with the name of the user, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for name. This includes \0 terminating character.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_last_user_name_set()

tng_function_status DECLSPECDLLEXPORT tng_last_user_name_set ( const tng_trajectory_t  tng_data,
const char *  new_name 
)

Set the name of the user who last modified the trajectory.

Parameters
tng_datathe trajectory of which to set the user name.
new_nameis a string containing the wanted name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
new_name != 0
The pointer to the new_name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_long_stride_length_get()

tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_get ( const tng_trajectory_t  tng_data,
int64_t *  len 
)

Get the long stride length of the trajectory.

Parameters
tng_datais the trajectory from which to get the stride length.
lenis pointing to a value set to the stride length.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
len != 0
The pointer to len must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_long_stride_length_set()

tng_function_status DECLSPECDLLEXPORT tng_long_stride_length_set ( const tng_trajectory_t  tng_data,
const int64_t  len 
)

Set the long stride length of the trajectory.

Parameters
tng_datais the trajectory of which to set the stride length.
lenis the wanted long stride length.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred.

◆ tng_medium_stride_length_get()

tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_get ( const tng_trajectory_t  tng_data,
int64_t *  len 
)

Get the medium stride length of the trajectory.

Parameters
tng_datais the trajectory from which to get the stride length.
lenis pointing to a value set to the stride length.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
len != 0
The pointer to len must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_medium_stride_length_set()

tng_function_status DECLSPECDLLEXPORT tng_medium_stride_length_set ( const tng_trajectory_t  tng_data,
const int64_t  len 
)

Set the medium stride length of the trajectory.

Parameters
tng_datais the trajectory of which to set the stride length.
lenis the wanted medium stride length.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred.

◆ tng_molecule_add()

tng_function_status DECLSPECDLLEXPORT tng_molecule_add ( const tng_trajectory_t  tng_data,
const char *  name,
tng_molecule_t molecule 
)

Add a molecule to the trajectory.

Parameters
tng_datais the trajectory data container containing the block..
nameis a pointer to the string containing the name of the new molecule.
moleculeis a pointer to the newly created molecule.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
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_molecule_alloc()

tng_function_status DECLSPECDLLEXPORT tng_molecule_alloc ( const tng_trajectory_t  tng_data,
tng_molecule_t molecule_p 
)

Allocate memory for and setup a molecule container.

Parameters
tng_datais a trajectory data container.
molecule_pis a pointer to molecule to allocate and initialise.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_molecule_atom_find()

tng_function_status DECLSPECDLLEXPORT tng_molecule_atom_find ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule,
const char *  name,
const int64_t  id,
tng_atom_t atom 
)

Find an atom in a molecule.

Parameters
tng_datais the trajectory data container containing the molecule.
moleculeis the molecule in which to search for the atom.
nameis a string containing the name of the atom. If name is an empty string only id will be used for searching.
idis the id of the atom to find. If id == -1 the first atom that matches the specified name will be found.
atomis a pointer to the atom if it was found - otherwise 0.
Precondition
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the atom is not found.

If name is an empty string and id == -1 the first residue will be found.

◆ tng_molecule_atom_of_index_get()

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 
)

Retrieve the atom of a molecule with specified index in the list of atoms.

Parameters
tng_datais the trajectory data container containing the molecule.
indexis the index (in molecule->atoms) of the atom to return
moleculeis the molecule from which to get the atom.
atomis a pointer to the atom if it was found - otherwise 0.
Precondition
molecule != 0
molecule must not be a NULL pointer.
atom != 0
atom must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the atom is not found.

◆ tng_molecule_bond_add()

tng_function_status DECLSPECDLLEXPORT tng_molecule_bond_add ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule,
const int64_t  from_atom_id,
const int64_t  to_atom_id,
tng_bond_t bond 
)

Add a bond between two atoms to a molecule.

Parameters
tng_datais the trajectory data container containing the molecule.
moleculeis the molecule containing the atoms to connect.
from_atom_idis the id of one of the two atoms in the bond.
to_atom_idis the id of the other atom in the bond.
bondis a pointer to the newly created bond.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (!) if a minor error has occured or TNG_CRITICAL (2) if a major error has occured.

◆ tng_molecule_chain_add()

tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_add ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule,
const char *  name,
tng_chain_t chain 
)

Add a chain to a molecule.

Parameters
tng_datais the trajectory data container containing the molecule..
moleculeis the molecule to add a chain to.
nameis a string containing the name of the chain.
chainis a pointer to the newly created chain.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
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_molecule_chain_find()

tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_find ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule,
const char *  name,
const int64_t  id,
tng_chain_t chain 
)

Find a chain in a molecule.

Parameters
tng_datais the trajectory data container containing the molecule.
moleculeis the molecule in which to search for the chain.
nameis a string containing the name of the chain. If name is empty only id will be used for finding the chain.
idis 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.
chainis a pointer to the chain if it was found - otherwise 0.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the chain is not found.

If name is an empty string and id == -1 the first residue will be found.

◆ tng_molecule_chain_of_index_get()

tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_of_index_get ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule,
const int64_t  index,
tng_chain_t chain 
)

Retrieve the chain of a molecule with specified index in the list of chains.

Parameters
tng_datais the trajectory data container containing the molecule.
indexis the index (in molecule->chains) of the chain to return
moleculeis the molecule from which to get the chain.
chainis a pointer to the chain if it was found - otherwise 0.
Precondition
molecule != 0
molecule must not be a NULL pointer.
chain != 0
chain must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if the chain is found or TNG_FAILURE (1) if the chain is not found.

◆ tng_molecule_chain_w_id_add()

tng_function_status DECLSPECDLLEXPORT tng_molecule_chain_w_id_add ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule,
const char *  name,
const int64_t  id,
tng_chain_t chain 
)

Add a chain with a specific id to a molecule.

Parameters
tng_datais the trajectory data container containing the molecule..
moleculeis the molecule to add a chain to.
nameis a string containing the name of the chain.
idis the ID of the created chain.
chainis a pointer to the newly created chain.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
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_molecule_cnt_get()

tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_get ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule,
int64_t *  cnt 
)

Get the count of a molecule.

Parameters
tng_datais the trajectory data container containing the molecule..
moleculeis the molecule of which to get the count.
cntis a pointer to the variable to be populated with the count.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
cnt != 0
The pointer to the molecule count must not be a NULL pointer.
Returns
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_molecule_cnt_list_get()

tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_list_get ( const tng_trajectory_t  tng_data,
int64_t **  mol_cnt_list 
)

Get the list of the count of each molecule.

Parameters
tng_datais the trajectory from which to get the molecule count list.
mol_cnt_listis 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.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
TNG_SUCCESS (0) if successful or TNG_FAILURE(1) if the list of molecule counts was not valid.

◆ tng_molecule_cnt_set()

tng_function_status DECLSPECDLLEXPORT tng_molecule_cnt_set ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule,
const int64_t  cnt 
)

Set the count of a molecule.

Parameters
tng_datais the trajectory data container containing the molecule..
moleculeis the molecule of which to set the count.
cntis the number of instances of this molecule.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
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_molecule_destroy()

tng_function_status DECLSPECDLLEXPORT tng_molecule_destroy ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule 
)

Clean up a molecule container.

Parameters
tng_datais a trajectory data container.
moleculeis the molecule to destroy.

All allocated memory in the data structure is freed, but not the memory of molecule itself.

Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_molecule_existing_add()

tng_function_status DECLSPECDLLEXPORT tng_molecule_existing_add ( const tng_trajectory_t  tng_data,
tng_molecule_t molecule 
)

Add an existing molecule (from a molecule container) to the trajectory.

Parameters
tng_datais the trajectory data container containing the block..
moleculeis a pointer to the molecule to add to the trajectory and will afterwards point to the molecule in the trajectory.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_molecule_find()

tng_function_status DECLSPECDLLEXPORT tng_molecule_find ( const tng_trajectory_t  tng_data,
const char *  name,
const int64_t  id,
tng_molecule_t molecule 
)

Find a molecule.

Parameters
tng_datais the trajectory data container containing the molecule.
nameis a string containing the name of the molecule. If name is empty only id will be used for finding the molecule.
idis 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.
moleculeis a pointer to the molecule if it was found - otherwise 0.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the molecule is not found.

If name is an empty string and id == -1 the first residue will be found.

◆ tng_molecule_free()

tng_function_status DECLSPECDLLEXPORT tng_molecule_free ( const tng_trajectory_t  tng_data,
tng_molecule_t molecule_p 
)

Clean up a molecule container and free its allocated memory.

Parameters
tng_datais a trajectory data container.
molecule_pis the molecule to destroy.

All allocated memory in the data structure is freed and also the memory of the molecule itself.

Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_molecule_id_of_particle_nr_get()

tng_function_status DECLSPECDLLEXPORT tng_molecule_id_of_particle_nr_get ( const tng_trajectory_t  tng_data,
const int64_t  nr,
int64_t *  id 
)

Get the molecule id of real particle number (number in mol system).

Parameters
tng_datais the trajectory data container containing the atom.
nris the real number of the particle in the molecular system.
idis will be set to the id of the molecule.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
id != 0
The pointer to id must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error has occured.

◆ tng_molecule_init()

tng_function_status DECLSPECDLLEXPORT tng_molecule_init ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule 
)

Setup a molecule container.

Parameters
tng_datais a trajectory data container.
moleculeis the molecule to initialise. Memory must be preallocated.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_molecule_name_get()

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 
)

Get the name of a molecule.

Parameters
tng_datathe trajectory containing the molecule.
moleculethe molecule of which to get the name.
namethe string to fill with the name of the molecule, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for name. This includes \0 terminating character.
Precondition
molecule != 0
The molecule must not be NULL.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_molecule_name_set()

tng_function_status DECLSPECDLLEXPORT tng_molecule_name_set ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule,
const char *  new_name 
)

Set the name of a molecule.

Parameters
tng_datais the trajectory data container containing the molecule..
moleculeis the molecule to rename.
new_nameis a string containing the wanted name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
new_name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_molecule_num_atoms_get()

tng_function_status DECLSPECDLLEXPORT tng_molecule_num_atoms_get ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule,
int64_t *  n 
)

Get the number of atoms in a molecule.

Parameters
tng_datais the trajectory containing the molecule.
moleculeis the molecule of which to get the number of atoms.
nis pointing to a value set to the number of atoms.
Precondition
molecule != 0
The molecule must not be NULL.
n != 0
The pointer to n must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_molecule_num_chains_get()

tng_function_status DECLSPECDLLEXPORT tng_molecule_num_chains_get ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule,
int64_t *  n 
)

Get the number of chains in a molecule.

Parameters
tng_datais the trajectory containing the molecule.
moleculeis the molecule of which to get the number of chains.
nis pointing to a value set to the number of chains.
Precondition
molecule != 0
The molecule must not be NULL.
n != 0
The pointer to n must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_molecule_num_residues_get()

tng_function_status DECLSPECDLLEXPORT tng_molecule_num_residues_get ( const tng_trajectory_t  tng_data,
const tng_molecule_t  molecule,
int64_t *  n 
)

Get the number of residues in a molecule.

Parameters
tng_datais the trajectory containing the molecule.
moleculeis the molecule of which to get the number residues.
nis pointing to a value set to the number of residues.
Precondition
molecule != 0
The molecule must not be NULL.
n != 0
The pointer to n must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_molecule_of_index_get()

tng_function_status DECLSPECDLLEXPORT tng_molecule_of_index_get ( const tng_trajectory_t  tng_data,
const int64_t  index,
tng_molecule_t molecule 
)

Retrieve the molecule with specified index in the list of molecules.

Parameters
tng_datais the trajectory data container containing the molecule.
indexis the index (in tng_data->molecules) of the molecule to return
moleculeis a pointer to the molecule if it was found - otherwise 0.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
molecule != 0
molecule must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if the molecule is found or TNG_FAILURE (1) if the molecule is not found.

◆ tng_molecule_residue_of_index_get()

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 
)

Retrieve the residue of a molecule with specified index in the list of chains.

Parameters
tng_datais the trajectory data container containing the molecule.
indexis the index (in molecule->residues) of the residue to return
moleculeis the molecule from which to get the residue.
residueis a pointer to the residue if it was found - otherwise 0.
Precondition
molecule != 0
molecule must not be a NULL pointer.
residue != 0
residue must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if the residue is found or TNG_FAILURE (1) if the residue is not found.

◆ tng_molecule_system_copy()

tng_function_status DECLSPECDLLEXPORT tng_molecule_system_copy ( const tng_trajectory_t  tng_data_src,
const tng_trajectory_t  tng_data_dest 
)

Copy all molecules and the molecule counts from one TNG trajectory to another.

Parameters
tng_data_srcis the source trajectory containing the molecular system to copy.
tng_data_destis the destination trajectory.
Precondition
tng_data_src != 0
The trajectory container (tng_data_src) must be initialised before using it.
tng_data_dest != 0
The trajectory container (tng_data_dest) must be initialised before using it.

The molecular system in tng_data_dest will be overwritten.

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

tng_function_status DECLSPECDLLEXPORT tng_molecule_w_id_add ( const tng_trajectory_t  tng_data,
const char *  name,
const int64_t  id,
tng_molecule_t molecule 
)

Add a molecule with a specific ID to the trajectory.

Parameters
tng_datais the trajectory data container containing the block..
nameis a pointer to the string containing the name of the new molecule.
idis the ID of the created molecule.
moleculeis a pointer to the newly created molecule.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
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_molsystem_bonds_get()

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 
)

Get the bonds of the current molecular system.

Parameters
tng_datais the trajectory data container containing the molecular system.
n_bondsis set to the number of bonds in the molecular system and thereby also the lengths of the two lists: from_atoms and to_atoms.
from_atomsis a list (memory reserved by this function) of atoms (number of atom in mol system) in bonds.
to_atomsis a list (memory reserved by this function) of atoms (number of atom in mol system) in bonds.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
n_bonds != 0
The pointer to n_bonds must not be a NULL pointer.
from_atoms != 0
The pointer to from_atoms must not be a NULL pointer.
to_atoms != 0
The pointer to to_atoms must not be a NULL pointer.

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.

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

tng_function_status DECLSPECDLLEXPORT tng_num_frame_sets_get ( const tng_trajectory_t  tng_data,
int64_t *  n 
)

Get the number of frame sets.

This updates tng_data->n_trajectory_frame_sets before returning it.

Parameters
tng_datais the trajectory from which to get the number of frame sets.
nis pointing to a value set to the number of frame sets.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
n != 0
The pointer to n must not be a NULL pointer.
Returns
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_num_frames_get()

tng_function_status DECLSPECDLLEXPORT tng_num_frames_get ( const tng_trajectory_t  tng_data,
int64_t *  n 
)

Get the number of frames in the trajectory.

Parameters
tng_datais the trajectory of which to get the number of frames.
nis pointing to a value set to the number of frames.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
tng_data->input_file != 0
An input file must be open to find the next frame set.
n != 0
The pointer to n must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (could not find last frame set).

◆ tng_num_frames_per_frame_set_get()

tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_get ( const tng_trajectory_t  tng_data,
int64_t *  n 
)

Get the number of frames per frame set.

Parameters
tng_datais the trajectory from which to get the number of frames per frame set.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
n != 0
The pointer to n must not be a NULL pointer.
Parameters
nis pointing to a value set to the number of frames per frame set.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_num_frames_per_frame_set_set()

tng_function_status DECLSPECDLLEXPORT tng_num_frames_per_frame_set_set ( const tng_trajectory_t  tng_data,
const int64_t  n 
)

Set the number of frames per frame set.

Parameters
tng_datais the trajectory of which to set the number of frames per frame set.
nis the number of frames per frame set.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.

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.

Returns
TNG_SUCCESS (0) if successful.

◆ tng_num_molecule_types_get()

tng_function_status DECLSPECDLLEXPORT tng_num_molecule_types_get ( const tng_trajectory_t  tng_data,
int64_t *  n 
)

Get the number of molecule types (length of tng_data->molecules).

Parameters
tng_datais the trajectory from which to get the number of molecules.
nis pointing to a value set to the number of molecule types.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
n != 0
The pointer to n must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_num_molecules_get()

tng_function_status DECLSPECDLLEXPORT tng_num_molecules_get ( const tng_trajectory_t  tng_data,
int64_t *  n 
)

Get the current total number of molecules.

Parameters
tng_datais the trajectory from which to get the number of molecules.
nis pointing to a value set to the number of molecules.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
n != 0
The pointer to n must not be a NULL pointer.

If variable number of particles are used this function will return the total number of molecules in the current frame set.

Returns
TNG_SUCCESS (0) if successful.

◆ tng_num_particles_get()

tng_function_status DECLSPECDLLEXPORT tng_num_particles_get ( const tng_trajectory_t  tng_data,
int64_t *  n 
)

Get the current number of particles.

Parameters
tng_datais the trajectory from which to get the number of particles.
nis pointing to a value set to the number of particles.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
n != 0
The pointer to n must not be a NULL pointer.

If variable number of particles are used this function will return the number of particles in the current frame set.

Returns
TNG_SUCCESS (0) if successful.

◆ tng_num_particles_variable_get()

tng_function_status DECLSPECDLLEXPORT tng_num_particles_variable_get ( const tng_trajectory_t  tng_data,
char *  variable 
)

Get if the number of particle can be varied during the simulation.

Parameters
tng_datais the trajectory from which to get the number of particles.
variableis 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.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
variable != 0
The pointer to variable must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_output_append_file_set()

tng_function_status DECLSPECDLLEXPORT tng_output_append_file_set ( const tng_trajectory_t  tng_data,
const char *  file_name 
)

Set the name of the output file for appending. The output file will not be overwritten.

Parameters
tng_datathe trajectory of which to set the output file name.
file_namethe name of the output file to append to.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
file_name != 0
The pointer to the file name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_output_file_endianness_get()

tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_get ( const tng_trajectory_t  tng_data,
tng_file_endianness endianness 
)

Get the endianness of the output file.

Parameters
tng_datathe trajectory of which to get the endianness of the current output file.
endiannesswill contain the enumeration of the endianness.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
endianness != 0
The pointer to the endianness container must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness could not be retrieved.

◆ tng_output_file_endianness_set()

tng_function_status DECLSPECDLLEXPORT tng_output_file_endianness_set ( const tng_trajectory_t  tng_data,
const tng_file_endianness  endianness 
)

Set the endianness of the output file.

Parameters
tng_datathe trajectory of which to set the endianness of the current output file.
endiannessthe enumeration of the endianness, can be either TNG_BIG_ENDIAN (0) or TNG_LITTLE_ENDIAN (1).
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.

The endianness cannot be changed after file output has started.

Returns
TNG_SUCCESS (0) if successful or TNG_FAILURE (1) if the endianness could not be set.

◆ tng_particle_data_block_add()

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

Add a particle dependent data block.

Parameters
tng_datais the trajectory data container in which to add the data block
idis the block ID of the block to add.
block_nameis a descriptive name of the block to add
datatypeis the datatype of the data in the block (e.g. int/float)
block_type_flagindicates if this is a non-trajectory block (added directly to tng_data) or if it is a trajectory block (added to the frame set)
n_framesis the number of frames of the data block (automatically set to 1 if adding a non-trajectory data block)
n_values_per_frameis how many values a stored each frame (e.g. 9 for a box shape block)
stride_lengthis how many frames are between each entry in the data block
num_first_particleis the number of the first particle stored in this data block
n_particlesis the number of particles stored in this data block
codec_idis the ID of the codec to compress the data.
new_datais an array of data values to add.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
block_name != 0
The pointer to the block name must not be a NULL pointer.
n_values_per_frame > 0
n_values_per_frame must be a positive integer.
num_first_particle >= 0
The number of the first particle must be >= 0.
n_particles >= 0
n_particles must be >= 0.
Returns
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_particle_data_get()

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

Retrieve particle data, from the last read frame set. Obsolete!

The particle dimension of the returned values array is translated to real particle numbering, i.e. the numbering of the actual molecular system.

Parameters
tng_datais 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.
block_idis the id number of the particle data block to read.
valuesis 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.
n_framesis set to the number of frames in the returned data. This is needed to properly reach and/or free the data afterwards.
n_particlesis set to the number of particles in the returned data. This is needed to properly reach and/or free the data afterwards.
n_values_per_frameis set to the number of values per frame in the data. This is needed to properly reach and/or free the data afterwards.
typeis set to the data type of the data in the array.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
n_frames != 0
The pointer to the number of frames must not be a NULL pointer.
n_particles != 0
The pointer to the number of particles must not be a NULL pointer.
n_values_per_frame != 0
The pointer to the number of values per frame must not be a NULL pointer.
type != 0
The pointer to the data type must not be a NULL pointer.

This function is obsolete and only retained for compatibility. Use tng_particle_data_vector_get() instead.

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

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

Read and retrieve particle data, in a specific interval. Obsolete!

The particle dimension of the returned values array is translated to real particle numbering, i.e. the numbering of the actual molecular system.

Parameters
tng_datais 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.
block_idis the id number of the particle data block to read.
start_frame_nris the index number of the first frame to read.
end_frame_nris the index number of the last frame to read.
hash_modeis 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.
valuesis 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.
n_particlesis set to the number of particles in the returned data. This is needed to properly reach and/or free the data afterwards.
n_values_per_frameis set to the number of values per frame in the data. This is needed to properly reach and/or free the data afterwards.
typeis set to the data type of the data in the array.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
n_frames != 0
The pointer to the number of frames must not be a NULL pointer.
start_frame_nr <= end_frame_nr
The first frame must be before the last frame.
n_particles != 0
The pointer to the number of particles must not be a NULL pointer.
n_values_per_frame != 0
The pointer to the number of values per frame must not be a NULL pointer.
type != 0
The pointer to the data type must not be a NULL pointer.

This function is obsolete and only retained for compatibility. Use tng_particle_data_vector_interval_get() instead.

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

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 
)

Free data of an array of values (3D).

Parameters
tng_datais a trajectory data container.
valuesis the array to free and will be set to 0 afterwards.
n_framesis the number of frames in the data array.
n_particlesis the number of particles in the data array.
n_values_per_frameis the number of values per frame in the data array.
typeis the data type of the data in the array (e.g. int/float/char).

This function should not be used. The data_values union is obsolete. This function also causes memory leaks, but its signature cannot be changed without disturbing the API.

Returns
TNG_SUCCESS (0) if successful.

◆ tng_particle_data_vector_get()

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

Retrieve a vector (1D array) of particle data, from the last read frame set.

The particle dimension of the returned values array is translated to real particle numbering, i.e. the numbering of the actual molecular system.

Parameters
tng_datais 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.
block_idis the id number of the particle data block to read.
valuesis a pointer to a 1-dimensional array (memory unallocated), which will be filled with data. The length of the array will be (n_frames_with_data (see stride_length) * n_particles * n_values_per_frame). Since **values is allocated in this function it is the callers responsibility to free the memory.
n_framesis set to the number of frames in the returned data. This is needed to properly reach and/or free the data afterwards.
stride_lengthis set to the stride length of the returned data.
n_particlesis set to the number of particles in the returned data. This is needed to properly reach and/or free the data afterwards.
n_values_per_frameis set to the number of values per frame in the data. This is needed to properly reach and/or free the data afterwards.
typeis set to the data type of the data in the array.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
n_particles != 0
The pointer to the number of particles must not be a NULL pointer.
stride_length != 0
The pointer to the stride length must not be a NULL pointer.
n_values_per_frame != 0
The pointer to the number of values per frame must not be a NULL pointer.
type != 0
The pointer to the data type must not be a NULL pointer.

This does only work for numerical (int, float, double) data.

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

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

Read and retrieve a vector (1D array) particle data, in a specific interval.

The particle dimension of the returned values array is translated to real particle numbering, i.e. the numbering of the actual molecular system.

Parameters
tng_datais 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.
block_idis the id number of the particle data block to read.
start_frame_nris the index number of the first frame to read.
end_frame_nris the index number of the last frame to read.
hash_modeis 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.
valuesis a pointer to a 1-dimensional array (memory unallocated), which will be filled with data. The length of the array will be (n_frames_with_data (see stride_length) * n_particles * n_values_per_frame). Since **values is allocated in this function it is the callers responsibility to free the memory.
stride_lengthis set to the stride length (writing interval) of the data.
n_particlesis set to the number of particles in the returned data. This is needed to properly reach and/or free the data afterwards.
n_values_per_frameis set to the number of values per frame in the data. This is needed to properly reach and/or free the data afterwards.
typeis set to the data type of the data in the array.
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.
n_particles != 0
The pointer to the number of particles must not be a NULL pointer.
stride_length != 0
The pointer to the stride length must not be a NULL pointer.
n_values_per_frame != 0
The pointer to the number of values per frame must not be a NULL pointer.
type != 0
The pointer to the data type must not be a NULL pointer.

This does only work for numerical (int, float, double) data.

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

tng_function_status DECLSPECDLLEXPORT tng_particle_mapping_add ( const tng_trajectory_t  tng_data,
const int64_t  num_first_particle,
const int64_t  n_particles,
const int64_t *  mapping_table 
)

Add a particle mapping table.

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.

Parameters
tng_datais the trajectory, with the frame set to which to add the mapping block.

The mapping information is added to the currently active frame set of tng_data

Parameters
num_first_particleis the first particle number of this mapping block.
n_particlesis the number of particles in this mapping block.
mapping_tableis a list of the real particle numbers (i.e. the numbers used in the molecular system). The list is n_particles long.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.

mapping_table[0] is the real particle number of the first particle in the following data blocks.

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

tng_function_status DECLSPECDLLEXPORT tng_residue_atom_add ( const tng_trajectory_t  tng_data,
const tng_residue_t  residue,
const char *  atom_name,
const char *  atom_type,
tng_atom_t atom 
)

Add an atom to a residue.

Parameters
tng_datais the trajectory containing the residue.
residueis the residue to add an atom to.
atom_nameis a string containing the name of the atom.
atom_typeis a string containing the atom type of the atom.
atomis a pointer to the newly created atom.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
atom_name != 0
The pointer to the atom name string must not be a NULL pointer.
atom_type != 0
The pointer to the atom_type string must not be a NULL pointer.
Returns
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_residue_atom_of_index_get()

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 
)

Retrieve the atom of a residue with specified index in the list of atoms.

Parameters
tng_datais the trajectory data container containing the residue.
indexis the index (in residue->atoms) of the atom to return
residueis the residue from which to get the atom.
atomis a pointer to the atom if it was found - otherwise 0.
Precondition
residue != 0
residue must not be a NULL pointer.
atom != 0
atom must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if the atom is found or TNG_FAILURE (1) if the atom is not found.

◆ tng_residue_atom_w_id_add()

tng_function_status DECLSPECDLLEXPORT tng_residue_atom_w_id_add ( const tng_trajectory_t  tng_data,
const tng_residue_t  residue,
const char *  atom_name,
const char *  atom_type,
const int64_t  id,
tng_atom_t atom 
)

Add an atom with a specific ID to a residue.

Parameters
tng_datais the trajectory containing the residue.
residueis the residue to add an atom to.
atom_nameis a string containing the name of the atom.
atom_typeis a string containing the atom type of the atom.
idis the ID of the created atom.
atomis a pointer to the newly created atom.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
atom_name != 0
The pointer to the atom name string must not be a NULL pointer.
atom_type != 0
The pointer to the atom_type string must not be a NULL pointer.
Returns
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_residue_id_of_particle_nr_get()

tng_function_status DECLSPECDLLEXPORT tng_residue_id_of_particle_nr_get ( const tng_trajectory_t  tng_data,
const int64_t  nr,
int64_t *  id 
)

Get the residue id (local to molecule) of real particle number (number in mol system).

Parameters
tng_datais the trajectory data container containing the atom.
nris the real number of the particle in the molecular system.
idis a pointer to the variable, which will be set to the ID.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
id != 0
The pointer to id must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error has occured.

◆ tng_residue_name_get()

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 
)

Get the name of a residue.

Parameters
tng_datathe trajectory containing the residue.
residuethe residue of which to get the name.
namethe string to fill with the name of the residue, memory must be allocated before.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for name. This includes \0 terminating character.
Precondition
residue != 0
The residue must not be NULL.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred (source string longer than destination string).

◆ tng_residue_name_of_particle_nr_get()

tng_function_status DECLSPECDLLEXPORT tng_residue_name_of_particle_nr_get ( const tng_trajectory_t  tng_data,
const int64_t  nr,
char *  name,
const int  max_len 
)

Get the residue name of real particle number (number in mol system).

Parameters
tng_datais the trajectory data container containing the atom.
nris the real number of the particle in the molecular system.
nameis a string, which is set to the name of the residue. Memory must be reserved beforehand.
max_lenis the maximum length of name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
name != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_FAILURE (!) if a minor error has occured.

◆ tng_residue_name_set()

tng_function_status DECLSPECDLLEXPORT tng_residue_name_set ( const tng_trajectory_t  tng_data,
const tng_residue_t  residue,
const char *  new_name 
)

Set the name of a residue.

Parameters
tng_datais the trajectory data container containing the residue.
residueis the residue to rename.
new_nameis a string containing the wanted name.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
new_name != 0
The new name to set (new_name) must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_residue_num_atoms_get()

tng_function_status DECLSPECDLLEXPORT tng_residue_num_atoms_get ( const tng_trajectory_t  tng_data,
const tng_residue_t  residue,
int64_t *  n 
)

Get the number of atoms in a residue.

Parameters
tng_datais the trajectory containing the residue.
residueis the residue of which to get the number atoms.
nis pointing to a value set to the number of atoms.
Precondition
residue != 0
The residue must not be NULL.
n != 0
The pointer to n must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_time_get_str()

tng_function_status DECLSPECDLLEXPORT tng_time_get_str ( const tng_trajectory_t  tng_data,
char *  time 
)

Get the date and time of initial file creation in ISO format (string).

Parameters
tng_datais a trajectory data container.
timeis a pointer to the string in which the date will be stored. Memory must be reserved beforehand.
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.

◆ tng_time_per_frame_get()

tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_get ( const tng_trajectory_t  tng_data,
double *  time 
)

Get the current time per frame of the trajectory.

Parameters
tng_datais the trajectory from which to get the time per frame.
timeis pointing to a value set to the time per frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
time != 0
The pointer to time must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_time_per_frame_set()

tng_function_status DECLSPECDLLEXPORT tng_time_per_frame_set ( const tng_trajectory_t  tng_data,
const double  time 
)

Set the time per frame of the trajectory.

Parameters
tng_datais the trajectory of which to set the time per frame.
timeis the new time per frame.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
time > 0
The time per frame must be >= 0.
Returns
TNG_SUCCESS (0) if successful, TNG_FAILURE (1) if a minor error has occurred.

◆ tng_trajectory_destroy()

tng_function_status DECLSPECDLLEXPORT tng_trajectory_destroy ( tng_trajectory_t tng_data_p)

Clean up a trajectory data container.

Parameters
tng_data_pa pointer to the trajectory data to destroy.

All allocated memory in the data structure is freed, as well as tng_data_p itself.

Returns
TNG_SUCCESS (0) if successful.

◆ tng_trajectory_init()

tng_function_status DECLSPECDLLEXPORT tng_trajectory_init ( tng_trajectory_t tng_data_p)

Setup a trajectory data container.

Parameters
tng_data_pa pointer to memory to initialise as a trajectory.
Precondition
tng_data_p must not be pointing at a reserved memory block.

Memory is allocated during initialisation.

Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_trajectory_init_from_src()

tng_function_status DECLSPECDLLEXPORT tng_trajectory_init_from_src ( const tng_trajectory_t  src,
tng_trajectory_t dest_p 
)

Copy a trajectory data container (dest is setup as well).

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.

Parameters
srcthe original trajectory.
dest_pa pointer to memory to initialise as a trajectory.
Precondition
tng_data != 0
The trajectory container (tng_data) must be initialised before using it.
tng_data_p must not be pointing at a reserved memory block.

Memory is allocated during initialisation.

Returns
TNG_SUCCESS (0) if successful or TNG_CRITICAL (2) if a major error has occured.

◆ tng_version()

tng_function_status DECLSPECDLLEXPORT tng_version ( const tng_trajectory_t  tng_data,
char *  version,
const int  max_len 
)

Get the full version string of the TNG library.

Parameters
tng_datais a trajectory data container, it does not have to be initialized beforehand.
versionis pointing to a value set to the major version of the library.
max_lenmaximum char length of the string, i.e. how much memory has been reserved for version. This includes \0 terminating character.
Precondition
version != 0
The pointer to the name string must not be a NULL pointer.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_version_major()

tng_function_status DECLSPECDLLEXPORT tng_version_major ( const tng_trajectory_t  tng_data,
int *  version 
)

Get the major version of the TNG library.

Parameters
tng_datais a trajectory data container, it does not have to be initialized beforehand.
versionis pointing to a value set to the major version of the library.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_version_minor()

tng_function_status DECLSPECDLLEXPORT tng_version_minor ( const tng_trajectory_t  tng_data,
int *  version 
)

Get the minor version of the TNG library.

Parameters
tng_datais a trajectory data container, it does not have to be initialized beforehand.
versionis pointing to a value set to the minor version of the library.
Returns
TNG_SUCCESS (0) if successful.

◆ tng_version_patchlevel()

tng_function_status DECLSPECDLLEXPORT tng_version_patchlevel ( const tng_trajectory_t  tng_data,
int *  patch_level 
)

Get the patch level of the TNG library.

Parameters
tng_datais a trajectory data container, it does not have to be initialized beforehand.
patch_levelis the string to fill with the full version, memory must be allocated before.
Returns
TNG_SUCCESS (0) if successful.