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

CHFL_TRAJECTORY *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);
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`.

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);
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_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);
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 *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);
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 *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);
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 *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);
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 *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);
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 *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);
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 *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);
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_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);
Return
`CHFL_SUCCESS`