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_last_error
to learn about the error.
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 '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. 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_last_error
to learn about the error.
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.
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_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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.
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_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
chfl_trajectory_write
(CHFL_TRAJECTORY *trajectory, const CHFL_FRAME *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_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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.
CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.xyz", 'r');
CHFL_CELL* cell = chfl_cell((chfl_vector3d){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_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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.
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_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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.
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_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
chfl_trajectory_nsteps
(CHFL_TRAJECTORY *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_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
CHFL_SUCCESS