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.
chfl_trajectory_open
(const char *path, char mode)¶Open the file at the given `path` using the given `mode`.
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);
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`.
This is be needed when the file format does not match the extension, or when there is not standard extension for this format. Valid modes are `’r’` for read, `’w’` for write and `’a’` for append. 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`.
CHFL_TRAJECTORY* trajectory = chfl_trajectory_with_format("water.zeo", 'r', "XYZ");
if (trajectory == NULL) {
/* handle error */
}
chfl_trajectory_close(trajectory);
chfl_trajectory_read
(CHFL_TRAJECTORY *const trajectory, CHFL_FRAME *const 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.
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_frame_free(frame);
chfl_trajectory_close(trajectory);
chfl_trajectory_read_step
(CHFL_TRAJECTORY *const trajectory, uint64_t step, CHFL_FRAME *const 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.
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_frame_free(frame);
chfl_trajectory_close(trajectory);
chfl_trajectory_write
(CHFL_TRAJECTORY *const trajectory, const CHFL_FRAME *const frame)¶Write a single `frame` to the `trajectory`.
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_frame_free(frame);
chfl_trajectory_set_cell
(CHFL_TRAJECTORY *const trajectory, const CHFL_CELL *const 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.
CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.xyz", 'r');
CHFL_CELL* cell = chfl_cell((chfl_vector_t){22, 22, 34});
chfl_trajectory_set_cell(trajectory, cell);
/* Reading from the trajectory use the cell */
chfl_cell_free(cell);
chfl_trajectory_close(trajectory);
chfl_trajectory_set_topology
(CHFL_TRAJECTORY *const trajectory, const CHFL_TOPOLOGY *const 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.
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_topology_free(topology);
chfl_trajectory_close(trajectory);
chfl_trajectory_topology_file
(CHFL_TRAJECTORY *const 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.
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);
chfl_trajectory_nsteps
(CHFL_TRAJECTORY *const trajectory, uint64_t *nsteps)¶Store the number of steps (the number of frames) from the `trajectory` in `nsteps`.
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_frame_free(frame);
chfl_trajectory_close(trajectory);
chfl_trajectory_close
(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);