CHFL_TRAJECTORY

typedef struct CHFL_TRAJECTORY CHFL_TRAJECTORY

An opaque type handling trajectories files.

The CHFL_TRAJECTORY type is the main entry point when using chemfiles. A CHFL_TRAJECTORY* behave a bit like a FILE* pointer, allowing to read and/or write CHFL_FRAME* to a file.

Here is the full list of functions acting on CHFL_TRAJECTORY:

CHFL_TRAJECTORY *chfl_trajectory_open(const char *path, char mode)

Open the file at the given path using the given mode.

Valid modes are ‘rfor read,’w’for write and’a’` for append.

The caller of this function should free the allocated memory using chfl_trajectory_close.

Returns:

A pointer to the trajectory, or NULL in case of error. You can use chfl_last_error to learn about the error.

CHFL_TRAJECTORY *chfl_trajectory_with_format(const char *path, char mode, const char *format)

Open the file at the given path using a specific file format and the given mode.

Valid modes are ‘rfor read,’w’for write and’a’` for append.

The format parameter is needed when the file format does not match the extension, or when there is not standard extension for this format. If format is an empty string, the format will be guessed from the extension.

The caller of this function should free the allocated memory using chfl_trajectory_close.

Returns:

A pointer to the trajectory, or NULL in case of error. You can use chfl_last_error to learn about the error.

CHFL_TRAJECTORY *chfl_trajectory_memory_reader(const char *memory, uint64_t size, const char *format)

Read a memory buffer as though it were a formatted file

The start of the memory buffer used to store the file is given using the data argument and the size of the buffer is given by size. The format parameter is required and may contain a compression method.

The caller of this function should free the allocated memory using chfl_trajectory_close.

Returns:

A pointer to the trajectory, or NULL in case of error. You can use chfl_last_error to learn about the error.

CHFL_TRAJECTORY *chfl_trajectory_memory_writer(const char *format)

Write to a memory buffer as though it were a formatted file

The format parameter is required. To retreive the memory written to by the CHFL_TRAJECTORY, use the function chfl_trajectory_memory_buffer.

The caller of this function should free the allocated memory using chfl_trajectory_close.

Returns:

A pointer to the trajectory, or NULL in case of error. You can use chfl_last_error to learn about the error.

chfl_status chfl_trajectory_path(const CHFL_TRAJECTORY *trajectory, char *path, uint64_t buffsize)

Get the path used to open the trajectory in the path buffer.

The buffer size must be passed in buffsize. This function will truncate the selection string to fit in the buffer.

Returns:

The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_trajectory_read(CHFL_TRAJECTORY *trajectory, CHFL_FRAME *frame)

Read the next step of the trajectory into a frame.

If the number of atoms in frame does not correspond to the number of atom in the next step, the frame is resized.

Returns:

The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_trajectory_read_step(CHFL_TRAJECTORY *trajectory, uint64_t step, CHFL_FRAME *frame)

Read a specific step of the trajectory into a frame.

If the number of atoms in frame does not correspond to the number of atom in the step, the frame is resized.

Returns:

The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_trajectory_write(CHFL_TRAJECTORY *trajectory, const CHFL_FRAME *frame)

Write a single frame to the trajectory.

Returns:

The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_trajectory_set_cell(CHFL_TRAJECTORY *trajectory, const CHFL_CELL *cell)

Set the unit cell associated with a trajectory. This cell will be used when reading and writing the files, replacing any pre-existing unit cell.

Returns:

The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_trajectory_set_topology(CHFL_TRAJECTORY *trajectory, const CHFL_TOPOLOGY *topology)

Set the topology associated with a trajectory. This topology will be used when reading and writing the files, replacing any topology in the frames or files.

Returns:

The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_trajectory_topology_file(CHFL_TRAJECTORY *trajectory, const char *path, const char *format)

Set the topology associated with a trajectory by reading the first frame of the file at the given path using the file format in format; and extracting the topology of this frame.

If format is an empty string or NULL, the format will be guessed from the path extension.

Returns:

The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_trajectory_nsteps(CHFL_TRAJECTORY *trajectory, uint64_t *nsteps)

Store the number of steps (the number of frames) from the trajectory in nsteps.

Returns:

The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_trajectory_memory_buffer(const CHFL_TRAJECTORY *trajectory, const char **data, uint64_t *size)

Obtain the memory buffer written to by the trajectory.

The user is not responsible for freeing data and this will be done automatically when the trajectory is closed. It is guaranteed that data is null terminated, and the size of the buffer, not including the final NULL character, is passed in size

Returns:

The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

void chfl_trajectory_close(const CHFL_TRAJECTORY *trajectory)

Close a trajectory file, and free the associated memory.

Closing a file will synchronize all changes made to the file with the storage (hard drive, network, …) used for this file.