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.

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

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_status chfl_trajectory_path(const CHFL_TRAJECTORY *trajectory, const char **path)

Get the path used to open the trajectory in path.

The path will point to memory allocated inside the trajectory, and it is only valid until the trajectory is closed (chfl_trajectory_close). There is no need to free the corresponding memory

CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.xyz", 'r');

const char* path = NULL;
chfl_trajectory_path(trajectory, &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 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.

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

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 not CHFL_SUCCESS.

chfl_status 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_free(frame);
Return
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.

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_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 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.

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

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

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

CHFL_TRAJECTORY* trajectory = chfl_trajectory_open("water.xyz", 'r');

if (trajectory == NULL) {
    /* handle error */
}

chfl_trajectory_close(trajectory);