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. ACHFL_TRAJECTORY*
behave a bit like aFILE*
pointer, allowing to read and/or writeCHFL_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 givenmode
.Valid modes are ‘r
for read,
’w’for write and
’a’` for append.The caller of this function should free the allocated memory using
chfl_trajectory_close
.CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.xyz", 'r'); if (trajectory == NULL) { /* handle error */ } chfl_trajectory_close(trajectory);
- Return
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 fileformat
and the givenmode
.Valid modes are ‘r
for 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. Ifformat
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
.CHFL_TRAJECTORY* trajectory = chfl_trajectory_with_format("water.zeo", 'r', "XYZ"); if (trajectory == NULL) { /* handle error */ } chfl_trajectory_close(trajectory);
- Return
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 bysize
. Theformat
parameter is required and may contain a compression method.The caller of this function should free the allocated memory using
chfl_trajectory_close
.const char* memory_buffer = "c1ccccc1\nc1ccco1\nc1ccccn1\n"; CHFL_TRAJECTORY* trajectory = chfl_trajectory_memory_reader(memory_buffer, strlen(memory_buffer), "SMI"); if (trajectory == NULL) { /* handle error */ } chfl_trajectory_close(trajectory);
- Return
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 theCHFL_TRAJECTORY
, use the functionchfl_trajectory_memory_buffer
.The caller of this function should free the allocated memory using
chfl_trajectory_close
.CHFL_FRAME* frame = chfl_frame(); /* Add atoms to the frame */ CHFL_TRAJECTORY* trajectory = chfl_trajectory_memory_writer("XYZ"); if (chfl_trajectory_write(trajectory, frame) != CHFL_SUCCESS) { /* handle error */ } chfl_trajectory_close(trajectory); chfl_free(frame);
- Return
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 thepath
buffer.The buffer size must be passed in
buffsize
. This function will truncate the selection string to fit in the buffer.CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.xyz", 'r'); char path[256] = {0}; chfl_trajectory_path(trajectory, path, sizeof(path)); assert(strcmp(path, "water.xyz") == 0); chfl_trajectory_close(trajectory);
- Return
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.
-
chfl_status
chfl_trajectory_read
(CHFL_TRAJECTORY *trajectory, CHFL_FRAME *frame)¶ Read the next step of the
trajectory
into aframe
.If the number of atoms in frame does not correspond to the number of atom in the next step, the frame is resized.
CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.xyz", 'r'); CHFL_FRAME* frame = chfl_frame(); chfl_trajectory_read(trajectory, frame); /* We can use the first frame here */ chfl_trajectory_read(trajectory, frame); /* We can use the second frame here */ chfl_free(frame); chfl_trajectory_close(trajectory);
- Return
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.
-
chfl_status
chfl_trajectory_read_step
(CHFL_TRAJECTORY *trajectory, uint64_t step, CHFL_FRAME *frame)¶ Read a specific
step
of thetrajectory
into aframe
.If the number of atoms in frame does not correspond to the number of atom in the step, the frame is resized.
CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.xyz", 'r'); CHFL_FRAME* frame = chfl_frame(); chfl_trajectory_read_step(trajectory, 42, frame); /* We can use the 42nd frame here */ chfl_free(frame); chfl_trajectory_close(trajectory);
- Return
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.
-
chfl_status
chfl_trajectory_write
(CHFL_TRAJECTORY *trajectory, const CHFL_FRAME *frame)¶ Write a single
frame
to thetrajectory
.CHFL_FRAME* frame = chfl_frame(); /* Add atoms to the frame */ CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.xyz", 'w'); if (chfl_trajectory_write(trajectory, frame) != CHFL_SUCCESS) { /* handle error */ } chfl_trajectory_close(trajectory); chfl_free(frame);
- Return
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.
-
chfl_status
chfl_trajectory_set_cell
(CHFL_TRAJECTORY *trajectory, const CHFL_CELL *cell)¶ Set the unit
cell
associated with atrajectory
. This cell will be used when reading and writing the files, replacing any pre-existing unit cell.CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.xyz", 'r'); CHFL_CELL* cell = chfl_cell((chfl_vector3d){22, 22, 34}, NULL); chfl_trajectory_set_cell(trajectory, cell); /* Reading from the trajectory use the cell */ chfl_free(cell); chfl_trajectory_close(trajectory);
- Return
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.
-
chfl_status
chfl_trajectory_set_topology
(CHFL_TRAJECTORY *trajectory, const CHFL_TOPOLOGY *topology)¶ Set the
topology
associated with atrajectory
. This topology will be used when reading and writing the files, replacing any topology in the frames or files.CHFL_TOPOLOGY* topology = chfl_topology(); /* Build the topology by hand or by reading a file */ CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.xyz", 'r'); chfl_trajectory_set_topology(trajectory, topology); /* Reading from the trajectory use the topology we built */ chfl_free(topology); chfl_trajectory_close(trajectory);
- Return
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_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 givenpath
using the file format informat
; and extracting the topology of this frame.If
format
is an empty string orNULL
, the format will be guessed from the path extension.CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.nc", 'r'); chfl_trajectory_topology_file(trajectory, "water.pdb", NULL); /* Reading the trajectory will use topology from water.pdb */ chfl_trajectory_topology_file(trajectory, "water.topo", "PDB"); /* Reading the trajectory will use topology from water.topo using the PDB format. */ chfl_trajectory_close(trajectory);
- Return
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.
-
chfl_status
chfl_trajectory_nsteps
(CHFL_TRAJECTORY *trajectory, uint64_t *nsteps)¶ Store the number of steps (the number of frames) from the
trajectory
innsteps
.CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.nc", 'r'); uint64_t nsteps = 0; chfl_trajectory_nsteps(trajectory, &nsteps); /* Read all steps in the trajectory */ CHFL_FRAME* frame = chfl_frame(); for (uint64_t i=0; i<nsteps; i++) { chfl_trajectory_read(trajectory, frame); /* Do stuff with the frame */ } chfl_free(frame); chfl_trajectory_close(trajectory);
- Return
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_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 thatdata
is null terminated, and the size of the buffer, not including the finalNULL
character, is passed insize
CHFL_FRAME* frame = chfl_frame(); /* Add atoms to the frame */ CHFL_TRAJECTORY* trajectory = chfl_trajectory_memory_writer("XYZ"); if (chfl_trajectory_write(trajectory, frame) != CHFL_SUCCESS) { /* handle error */ } const char* result = NULL; uint64_t size_of_result; chfl_trajectory_memory_buffer(trajectory, &result, &size_of_result); chfl_trajectory_close(trajectory); chfl_free(frame);
- Return
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_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.
CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.xyz", 'r'); if (trajectory == NULL) { /* handle error */ } chfl_trajectory_close(trajectory);