C interface reference

The C interface is define in the chemfiles.h header, which should be included in all the programs using chemfiles. All the functions and enums have a chfl_ prefix indicating the provenance of the functions. The types are defined as opaque pointer types, in all caps. The following types are defined:

The user is reponsible for memory management when using these types. Constructors functions (functions returning pointers to types defined above) return freshly allocated memory, and calling the chfl_*_free functions return the corresponding memory to the operating system.

In addition to the functions below, the same macro as in the C++ interface are defined, and the chfl_version function allow to access the version of the Chemfiles library.

const char * chfl_version(void)

Get the version of the chemfiles library.

Return
A null-terminated string containing the version of Chemfiles.

Functions for errors handling

Apart from the constructor functions (the functions returning pointers to the types defined above); all the functions return a status code, which is 0 if nothing went wrong, and another value in case of error. The following function allow for error handling from the C side.

const char * chfl_strerror(int status)

Get the error message corresponding to an error code.

Return
A null-terminated string encoding the textual representation of the status.
Parameters
  • status -

    The error code

const char * chfl_last_error()

Get the last error message.

Return
A null-terminated string encoding the textual representation of the last error.

CHFL_LOG_LEVEL enum

Available logging level.

Values:

  • CHFL_LOG_ERROR = = 0 -

    Only log on errors.

  • CHFL_LOG_WARNING = = 1 -

    Log warnings and erors.

  • CHFL_LOG_INFO = = 2 -

    Log infos, warnings and errors.

  • CHFL_LOG_DEBUG = = 3 -

    Log everything.

int chfl_loglevel(chfl_log_level_t * level)

Get the current maximal logging level.

Return
The status code
Parameters
  • level -

    The logging level

int chfl_set_loglevel(chfl_log_level_t level)

Set the current maximal logging level to level.

Return
The status code
Parameters
  • level -

    The new logging level

int chfl_logfile(const char * file)

Redirect the logs to file, overwriting the file if it exists.

Return
The status code
Parameters
  • file -

    The filename for the new log file.

int chfl_log_stderr()

Redirect the logs to the standard error output. This is enabled by default.

Return
The status code

The return values for this status code correspond to the following macros:

CHFL_SUCCESS

Status code for success.

CHFL_MEMORY_ERROR

Memory error: out of memory, wrong size for arrays parameters, ...

CHFL_FILE_ERROR

File error: file do not exist, you do not have rights to open it, ...

CHFL_FORMAT_ERROR

Error in file formating.

CHFL_GENERIC_ERROR

Any other error from Chemfiles.

CHFL_CXX_ERROR

Error in the C++ standard library.

Function manipulating CHFL_TRAJECTORY

The Trajectory type is the main entry point when using chemfiles. A trajectory behave a bit like a FILE* pointer, and the chfl_close free the memory associated with the file.

CHFL_TRAJECTORY * chfl_trajectory_open(const char * filename, const char * mode)

Open a trajectory file.

Return
A pointer to the file
Parameters
  • filename -

    The path to the trajectory file

  • mode -

    The opening mode: “r” for read, “w” for write and “a” for append.

CHFL_TRAJECTORY * chfl_trajectory_with_format(const char * filename, const char * mode, const char * format)

Open a trajectory file using a given format to read the file.

Return
A pointer to the file
Parameters
  • filename -

    The path to the trajectory file

  • mode -

    The opening mode: “r” for read, “w” for write and “a” for append.

  • format -

    The format to use

int chfl_trajectory_read(CHFL_TRAJECTORY * file, CHFL_FRAME * frame)

Read the next step of the trajectory into a frame.

Return
The status code.
Parameters
  • file -

    A pointer to the trajectory

  • frame -

    A frame to fill with the data

int chfl_trajectory_read_step(CHFL_TRAJECTORY * file, size_t step, CHFL_FRAME * frame)

Read a specific step of the trajectory in a frame.

Return
The status code.
Parameters
  • file -

    A pointer to the trajectory

  • step -

    The step to read

  • frame -

    A frame to fill with the data

int chfl_trajectory_write(CHFL_TRAJECTORY * file, const CHFL_FRAME * frame)

Write a frame to the trajectory.

Return
The status code.
Parameters
  • file -

    The trajectory to write

  • frame -

    the frame which will be writen to the file

int chfl_trajectory_set_topology(CHFL_TRAJECTORY * file, 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.

Return
The status code.
Parameters
  • file -

    A pointer to the trajectory

  • topology -

    The new topology to use

int chfl_trajectory_set_topology_file(CHFL_TRAJECTORY * file, const char * filename)

Set the topology associated with a trajectory by reading the first frame of filename; and extracting the topology of this frame.

Return
The status code.
Parameters
  • file -

    A pointer to the trajectory

  • filename -

    The file to read in order to get the new topology

int chfl_trajectory_nsteps(CHFL_TRAJECTORY * file, size_t * nsteps)

Get the number of steps (the number of frames) in a trajectory.

Return
The status code.
Parameters
  • file -

    A pointer to the trajectory

  • nsteps -

    This will contain the number of steps

int chfl_trajectory_close(CHFL_TRAJECTORY * file)

Close a trajectory file, and free the associated memory.

Return
The status code
Parameters
  • file -

    A pointer to the file

Function manipulating CHFL_FRAME

CHFL_FRAME * chfl_frame(size_t natoms)

Create an empty frame with initial capacity of natoms. It will be resized by the library as needed.

Return
A pointer to the frame
Parameters
  • natoms -

    the size of the wanted frame

int chfl_frame_atoms_count(const CHFL_FRAME * frame, size_t * natoms)

Get the current number of atoms in the frame.

Return
The status code
Parameters
  • frame -

    The frame to analyse

  • natoms -

    the number of atoms in the frame

int chfl_frame_resize(CHFL_FRAME * frame, size_t natoms)

Resize the positions and the velocities in frame, to make space for N atoms. This function may invalidate any pointer to the positions or the velocities if the new size is bigger than the old one. In all the cases, previous data is conserved. This function conserve the presence of abscence of velocities.

Return
The status code
Parameters
  • frame -

    The frame

  • natoms -

    The new number of atoms.

int chfl_frame_positions(CHFL_FRAME * frame, float(**) data[3], size_t * size)

Get a pointer to the positions array from a frame. The positions are stored as a N x 3 array, this function set a pointer to point to the first element of this array, and give the value of N. If the frame is resized (by writing to it, or calling chfl_frame_resize), the pointer is invalidated.

Return
The status code
Parameters
  • frame -

    The frame

  • data -

    A pointer to a pointer to float[3] array, which will point to the data

  • size -

    A pointer to the an integer to be filled with the array size

int chfl_frame_velocities(CHFL_FRAME * frame, float(**) data[3], size_t * size)

Get a pointer to the velocities array from a frame. The velocities are stored as a N x 3 array, this function set a pointer to point to the first element of this array, and give the value of N. If the frame is resized (by writing to it, or calling chfl_frame_resize), the pointer is invalidated.

     If the frame do not have velocity, this will return an error. Use
     `chfl_frame_add_velocities` to add velocities to a frame before calling this
     function.
Return
The status code
Parameters
  • frame -

    The frame

  • data -

    A pointer to a pointer to float[3] array, which will point to the data

  • size -

    A pointer to the an integer to be filled with the array size

int chfl_frame_has_velocities(const CHFL_FRAME * frame, bool * has_velocities)

Ask wether this frame contains velocity data or not.

Return
The status code
Parameters
  • frame -

    The frame

  • has_velocities -

    A boolean, will be true if the frame have velocities, false otherwise.

int chfl_frame_add_velocities(CHFL_FRAME * frame)

Add velocity storage to this frame. The storage is initialized with the result of chfl_frame_atoms_count as number of atoms. If the frame already have velocities, this does nothing.

Return
The status code
Parameters
  • frame -

    The frame

int chfl_frame_set_cell(CHFL_FRAME * frame, const CHFL_CELL * cell)

Set the UnitCell of a Frame.

Return
The status code
Parameters
  • frame -

    The frame

  • cell -

    The new cell

int chfl_frame_set_topology(CHFL_FRAME * frame, const CHFL_TOPOLOGY * topology)

Set the Topology of a Frame.

Return
The status code
Parameters
  • frame -

    The frame

  • topology -

    The new topology

int chfl_frame_step(const CHFL_FRAME * frame, size_t * step)

Get the Frame step, i.e. the frame number in the trajectory.

Return
The status code
Parameters
  • frame -

    The frame

  • step -

    This will contains the step number

int chfl_frame_set_step(CHFL_FRAME * frame, size_t step)

Set the Frame step.

Return
The status code
Parameters
  • frame -

    The frame

  • step -

    The new frame step

int chfl_frame_guess_topology(CHFL_FRAME * frame, bool bonds)

Try to guess the bonds, angles and dihedrals in the system. If bonds is true, guess everything; else only guess the angles and dihedrals from the topology bond list.

Return
The status code
Parameters
  • frame -

    The Frame to analyse

  • bonds -

    Should we recompute the bonds from the positions or not ?

int chfl_frame_selection(const CHFL_FRAME * frame, const char * selection, bool matched[], size_t natoms)

Select atoms in a frame, from a specific selection string.

This function select atoms in a frame matching a selection string. For example, “name H and x > 4” will select all the atoms with name “H” and $x$ coordinate less than 4. See the C++ documentation for the full selection language.

Results of this function are used to fill a pre-allocated array containing natoms bool, where natoms is the number of atoms in the frame. The array will contain true at position i if the atom at position i matches the selection string, and false otherwise.

Pre
The range from matched to (matched + natoms) is a valid adress range.
Return
The status code
Parameters
  • frame -

    The frame to analyse

  • selection -

    A null-terminated string containing the selection string

  • matched -

    a pre-allocated array, with space for natoms booleans

  • natoms -

    the size of the matched array. This MUST be the same number as the frame number of atoms.

int chfl_frame_free(CHFL_FRAME * frame)

Destroy a frame, and free the associated memory.

Return
The status code
Parameters
  • frame -

    The frame to destroy

Function manipulating CHFL_CELL

CHFL_CELL * chfl_cell(double a, double b, double c)

Create an ORTHOROMBIC UnitCell from the three lenghts.

Return
A pointer to the UnitCell
Parameters
  • a -

    first lenght of the cell (in Angstroms)

  • b -

    second lenght of the cell (in Angstroms)

  • c -

    third lenght of the cell (in Angstroms)

CHFL_CELL * chfl_cell_from_frame(const CHFL_FRAME * frame)

Get the UnitCell from a frame.

Return
A pointer to the UnitCell
Parameters
  • frame -

    the frame

int chfl_cell_lengths(const CHFL_CELL * cell, double * a, double * b, double * c)

Get the cell lenghts.

Return
The status code
Parameters
  • cell -

    the unit cell to read

  • a -

    first lenght of the cell (in Angstroms)

  • b -

    second lenght of the cell (in Angstroms)

  • c -

    third lenght of the cell (in Angstroms)

int chfl_cell_set_lengths(CHFL_CELL * cell, double a, double b, double c)

Set the unit cell lenghts.

Return
The status code
Parameters
  • cell -

    the unit cell to modify

  • a -

    first lenght of the cell (in Angstroms)

  • b -

    second lenght of the cell (in Angstroms)

  • c -

    third lenght of the cell (in Angstroms)

int chfl_cell_angles(const CHFL_CELL * cell, double * alpha, double * beta, double * gamma)

Get the cell angles, in degrees.

Return
The status code
Parameters
  • cell -

    the cell to read

  • alpha -

    angle of the cell between the vectors b and c (in degree)

  • beta -

    angle of the cell between the vectors a and c (in degree)

  • gamma -

    angle of the cell between the vectors a and b (in degree)

int chfl_cell_set_angles(CHFL_CELL * cell, double alpha, double beta, double gamma)

Set the cell angles, in degrees. This is only possible for TRICLINIC cells.

Return
The status code
Parameters
  • cell -

    the unit cell to modify

  • alpha -

    angle of the cell between the vectors b and c (in degree)

  • beta -

    angle of the cell between the vectors a and c (in degree)

  • gamma -

    angle of the cell between the vectors a and b (in degree)

int chfl_cell_matrix(const CHFL_CELL * cell, double matrix[3][3])

Get the unit cell matricial representation.

Return
The status code
Parameters
  • cell -

    the unit cell to use

  • matrix -

    the matrix to fill. It should be a 3x3 matrix.

CHFL_CELL_TYPES enum

Available cell types in chemfiles.

Values:

  • CHFL_CELL_ORTHOROMBIC = = 0 -

    The three angles are 90°

  • CHFL_CELL_TRICLINIC = = 1 -

    The three angles may not be 90°

  • CHFL_CELL_INFINITE = = 2 -

    Cell type when there is no periodic boundary conditions.

int chfl_cell_type(const CHFL_CELL * cell, chfl_cell_type_t * type)

Get the cell type.

Return
The status code
Parameters
  • cell -

    the unit cell to read

  • type -

    the type of the cell

int chfl_cell_set_type(CHFL_CELL * cell, chfl_cell_type_t type)

Set the cell type.

Return
The status code
Parameters
  • cell -

    the cell to modify

  • type -

    the new type of the cell

int chfl_cell_free(CHFL_CELL * cell)

Destroy an unit cell, and free the associated memory.

Return
The status code
Parameters
  • cell -

    The cell to destroy

Function manipulating CHFL_TOPOLOGY

CHFL_TOPOLOGY * chfl_topology()

Create a new empty topology.

Return
A pointer to the new Topology

CHFL_TOPOLOGY * chfl_topology_from_frame(const CHFL_FRAME * frame)

Get a copy of the topology of a frame.

Return
A pointer to the new Topology
Parameters
  • frame -

    The frame

int chfl_topology_atoms_count(const CHFL_TOPOLOGY * topology, size_t * natoms)

Get the current number of atoms in the topology.

Return
The status code
Parameters
  • topology -

    The topology to analyse

  • natoms -

    Will contain the number of atoms in the frame

int chfl_topology_append(CHFL_TOPOLOGY * topology, const CHFL_ATOM * atom)

Add an atom at the end of a topology.

Return
The status code
Parameters
  • topology -

    The topology

  • atom -

    The atom to be added

int chfl_topology_remove(CHFL_TOPOLOGY * topology, size_t i)

Remove an atom from a topology by index. This modify all the other atoms indexes.

Return
The status code
Parameters
  • topology -

    The topology

  • i -

    The atomic index

int chfl_topology_isbond(const CHFL_TOPOLOGY * topology, size_t i, size_t j, bool * result)

Tell if the atoms i and j are bonded together.

Return
The status code
Parameters
  • topology -

    The topology

  • i -

    index of the first atom in the topology

  • j -

    index of the second atom in the topology

  • result -

    true if the atoms are bonded, false otherwise

int chfl_topology_isangle(const CHFL_TOPOLOGY * topology, size_t i, size_t j, size_t k, bool * result)

Tell if the atoms i, j and k constitues an angle.

Return
The status code
Parameters
  • topology -

    The topology

  • i -

    index of the first atom in the topology

  • j -

    index of the second atom in the topology

  • k -

    index of the third atom in the topology

  • result -

    true if the atoms constitues an angle, false otherwise

int chfl_topology_isdihedral(const CHFL_TOPOLOGY * topology, size_t i, size_t j, size_t k, size_t m, bool * result)

Tell if the atoms i, j, k and m constitues a dihedral angle.

Return
The status code
Parameters
  • topology -

    The topology

  • i -

    index of the first atom in the topology

  • j -

    index of the second atom in the topology

  • k -

    index of the third atom in the topology

  • m -

    index of the fourth atom in the topology

  • result -

    true if the atoms constitues a dihedral angle, false otherwise

int chfl_topology_bonds_count(const CHFL_TOPOLOGY * topology, size_t * nbonds)

Get the number of bonds in the system.

Return
The status code
Parameters
  • topology -

    The topology

  • nbonds -

    After the call, contains the number of bond

int chfl_topology_angles_count(const CHFL_TOPOLOGY * topology, size_t * nangles)

Get the number of angles in the system.

Return
The status code
Parameters
  • topology -

    The topology

  • nangles -

    After the call, contains the number of angles

int chfl_topology_dihedrals_count(const CHFL_TOPOLOGY * topology, size_t * ndihedrals)

Get the number of dihedral angles in the system.

Return
The status code
Parameters
  • topology -

    The topology

  • ndihedrals -

    After the call, contains the number of dihedral angles

int chfl_topology_bonds(const CHFL_TOPOLOGY * topology, size_t(*) data[2], size_t nbonds)

Get the list of bonds in the system.

Return
The status code
Parameters
  • topology -

    The topology

  • data -

    A nbonds x 2 array to be filled with the bonds in the system

  • nbonds -

    The size of the array. This should equal the value given by the chfl_topology_bonds_count function

int chfl_topology_angles(const CHFL_TOPOLOGY * topology, size_t(*) data[3], size_t nangles)

Get the list of angles in the system.

Return
The status code
Parameters
  • topology -

    The topology

  • data -

    A nangles x 3 array to be filled with the angles in the system

  • nangles -

    The size of the array. This should equal the value given by the chfl_topology_angles_count function

int chfl_topology_dihedrals(const CHFL_TOPOLOGY * topology, size_t(*) data[4], size_t ndihedrals)

Get the list of dihedral angles in the system.

Return
The status code
Parameters
  • topology -

    The topology

  • data -

    A ndihedrals x 4 array to be filled with the dihedral angles in the system

  • ndihedrals -

    The size of the array. This should equal the value given by the chfl_topology_dihedrals_count function

int chfl_topology_add_bond(CHFL_TOPOLOGY * topology, size_t i, size_t j)

Add a bond between the atoms i and j in the system.

Return
The status code
Parameters
  • topology -

    The topology

  • i -

    index of the first atom in the topology

  • j -

    index of the second atom in the topology

int chfl_topology_remove_bond(CHFL_TOPOLOGY * topology, size_t i, size_t j)

Remove any existing bond between the atoms i and j in the system.

Return
The status code
Parameters
  • topology -

    The topology

  • i -

    index of the first atom in the topology

  • j -

    index of the second atom in the topology

int chfl_topology_free(CHFL_TOPOLOGY * topology)

Destroy a topology, and free the associated memory.

Return
The status code
Parameters
  • topology -

    The topology to destroy

Function manipulating CHFL_ATOM

CHFL_ATOM * chfl_atom(const char * name)

Create an atom from an atomic name.

Return
A pointer to the corresponding atom
Parameters
  • name -

    The new atom name

CHFL_ATOM * chfl_atom_from_frame(const CHFL_FRAME * frame, size_t idx)

Get a specific atom from a frame.

Return
A pointer to the corresponding atom
Parameters
  • frame -

    The frame

  • idx -

    The atom index in the frame

CHFL_ATOM * chfl_atom_from_topology(const CHFL_TOPOLOGY * topology, size_t idx)

Get a specific atom from a topology.

Return
A pointer to the corresponding atom
Parameters
  • topology -

    The topology

  • idx -

    The atom index in the topology

int chfl_atom_mass(const CHFL_ATOM * atom, float * mass)

Get the mass of an atom, in atomic mass units.

Return
The status code
Parameters
  • atom -

    The atom

  • mass -

    The atom mass

int chfl_atom_set_mass(CHFL_ATOM * atom, float mass)

Set the mass of an atom, in atomic mass units.

Return
The status code
Parameters
  • atom -

    The atom

  • mass -

    The new atom mass

int chfl_atom_charge(const CHFL_ATOM * atom, float * charge)

Get the charge of an atom, in number of the electron charge e.

Return
The status code
Parameters
  • atom -

    The atom

  • charge -

    The atom charge

int chfl_atom_set_charge(CHFL_ATOM * atom, float charge)

Set the charge of an atom, in number of the electron charge e.

Return
The status code
Parameters
  • atom -

    The atom

  • charge -

    The new atom charge

int chfl_atom_name(const CHFL_ATOM * atom, char * name, size_t buffsize)

Get the name of an atom.

Return
The status code
Parameters
  • atom -

    The atom

  • name -

    A string buffer to be filled with the name

  • buffsize -

    The size of the string buffer

int chfl_atom_set_name(CHFL_ATOM * atom, const char * name)

Set the name of an atom.

Return
The status code
Parameters
  • atom -

    The atom

  • name -

    A null terminated string containing the new name

int chfl_atom_full_name(const CHFL_ATOM * atom, char * name, size_t buffsize)

Try to get the full name of an atom from the short name.

Return
The status code
Parameters
  • atom -

    The atom

  • name -

    A string buffer to be filled with the name

  • buffsize -

    The size of the string buffer

int chfl_atom_vdw_radius(const CHFL_ATOM * atom, double * radius)

Try to get the Van der Waals radius of an atom from the short name.

Return
The status code
Parameters
  • atom -

    The atom

  • radius -

    The Van der Waals radius of the atom or -1 if no value could be found.

int chfl_atom_covalent_radius(const CHFL_ATOM * atom, double * radius)

Try to get the covalent radius of an atom from the short name.

Return
The status code
Parameters
  • atom -

    The atom

  • radius -

    The covalent radius of the atom or -1 if no value could be found.

int chfl_atom_atomic_number(const CHFL_ATOM * atom, int * number)

Try to get the atomic number of an atom from the short name.

Return
The status code
Parameters
  • atom -

    The atom

  • number -

    The atomic number, or -1 if no value could be found.

CHFL_ATOM_TYPES enum

Available types of atoms.

Values:

  • CHFL_ATOM_ELEMENT = = 0 -

    Element from the periodic table of elements.

  • CHFL_ATOM_COARSE_GRAINED = = 1 -

    Coarse-grained atom are composed of more than one element: CH3 groups, amino-acids are coarse-grained atoms.

  • CHFL_ATOM_DUMMY = = 2 -

    Dummy site, with no physical reality.

  • CHFL_ATOM_UNDEFINED = = 3 -

    Undefined atom type.

int chfl_atom_type(const CHFL_ATOM * atom, chfl_atom_type_t * type)

Get the atom type.

Return
The status code
Parameters
  • atom -

    the atom to read

  • type -

    the type of the atom

int chfl_atom_set_type(CHFL_ATOM * atom, chfl_atom_type_t type)

Set the atom type.

Return
The status code
Parameters
  • atom -

    the atom to modify

  • type -

    the new type of the atom

int chfl_atom_free(CHFL_ATOM * atom)

Destroy an atom, and free the associated memory.

Return
The status code
Parameters
  • atom -

    The atom to destroy