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.
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.
chfl_strerror(int status)Get the error message corresponding to an error code.
status - The error code
chfl_last_error()Get the last error message.
Available logging level.
Values:
CHFL_LOG_NONE = = 0 - Do not log anything.
CHFL_LOG_ERROR = = 1 - Only log on errors.
CHFL_LOG_WARNING = = 2 - Log warnings and erors.
CHFL_LOG_INFO = = 3 - Log infos, warnings and errors.
CHFL_LOG_DEBUG = = 4 - Log everything.
chfl_loglevel(chfl_log_level_t * level)Get the current logging level.
level - The logging level
chfl_set_loglevel(chfl_log_level_t level)Set the current logging level to level.
level - The new logging level
chfl_logfile(const char * file)Redirect the logs to file, overwriting the file if it exists.
file - The filename for the new log file.
chfl_log_stderr()Redirect the logs to the standard error output. This is enabled by default.
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_open(const char * filename, const char * mode)Open a trajectory file.
filename - The path to the trajectory file
mode - The opening mode: “r” for read, “w” for write and “a” for append.
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.
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
chfl_trajectory_read(CHFL_TRAJECTORY * file, CHFL_FRAME * frame)Read the next step of the trajectory into a frame.
file - A pointer to the trajectory
frame - A frame to fill with the data
chfl_trajectory_read_step(CHFL_TRAJECTORY * file, size_t step, CHFL_FRAME * frame)Read a specific step of the trajectory in a frame.
file - A pointer to the trajectory
step - The step to read
frame - A frame to fill with the data
chfl_trajectory_write(CHFL_TRAJECTORY * file, const CHFL_FRAME * frame)Write a frame to the trajectory.
file - The trajectory to write
frame - the frame which will be writen to the file
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.
file - A pointer to the trajectory
topology - The new topology to use
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.
file - A pointer to the trajectory
filename - The file to read in order to get the new topology
chfl_trajectory_nsteps(CHFL_TRAJECTORY * file, size_t * nsteps)Get the number of steps (the number of frames) in a trajectory.
file - A pointer to the trajectory
nsteps - This will contain the number of steps
chfl_trajectory_close(CHFL_TRAJECTORY * file)Close a trajectory file, and free the associated memory.
file - A pointer to the file
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.
natoms - the size of the wanted frame
chfl_frame_atoms_count(const CHFL_FRAME * frame, size_t * natoms)Get the current number of atoms in the frame.
frame - The frame to analyse
natoms - the number of atoms in the frame
chfl_frame_positions(const CHFL_FRAME * frame, float(*) data[3], size_t size)Get the positions from a frame.
frame - The frame
data - A Nx3 float array to be filled with the data
size - The array size (N).
chfl_frame_set_positions(CHFL_FRAME * frame, float const (*) data[3], size_t size)Set the positions of a frame.
frame - The frame
data - A Nx3 float array containing the positions in row-major order.
size - The array size (N).
chfl_frame_has_velocities(const CHFL_FRAME * frame, bool * has_vel)Check if a frame has velocity information.
frame - The frame
has_vel - true if the frame has velocities, false otherwise.
chfl_frame_velocities(const CHFL_FRAME * frame, float(*) data[3], size_t size)Get the velocities from a frame, if they exists.
frame - The frame
data - A Nx3 float array to be filled with the data
size - The array size (N).
chfl_frame_set_velocities(CHFL_FRAME * frame, float const (*) data[3], size_t size)Set the velocities of a frame.
frame - The frame
data - A Nx3 float array containing the velocities in row-major order.
size - The array size (N).
chfl_frame_set_cell(CHFL_FRAME * frame, const CHFL_CELL * cell)Set the UnitCell of a Frame.
frame - The frame
cell - The new cell
chfl_frame_set_topology(CHFL_FRAME * frame, const CHFL_TOPOLOGY * topology)Set the Topology of a Frame.
frame - The frame
topology - The new topology
chfl_frame_step(const CHFL_FRAME * frame, size_t * step)Get the Frame step, i.e. the frame number in the trajectory.
frame - The frame
step - This will contains the step number
chfl_frame_set_step(CHFL_FRAME * frame, size_t step)Set the Frame step.
frame - The frame
step - The new frame step
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.
frame - The Frame to analyse
bonds - Should we recompute the bonds from the positions or not ?
chfl_frame_free(CHFL_FRAME * frame)Destroy a frame, and free the associated memory.
frame - The frame to destroy
CHFL_CELL¶chfl_cell(double a, double b, double c)Create an ORTHOROMBIC UnitCell from the three lenghts.
abc - the three lenghts of the cell
chfl_cell_from_frame(CHFL_FRAME * frame)Get the UnitCell from a frame.
frame - the frame
chfl_cell_lengths(const CHFL_CELL * cell, double * a, double * b, double * c)Get the cell lenghts.
cell - the unit cell to read
abc - the three cell lenghts
chfl_cell_set_lengths(CHFL_CELL * cell, double a, double b, double c)Set the unit cell lenghts.
cell - the unit cell to modify
abc - the cell lenghts
chfl_cell_angles(const CHFL_CELL * cell, double * alpha, double * beta, double * gamma)Get the cell angles, in degrees.
cell - the cell to read
alphabetagamma - the three cell angles
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.
cell - the unit cell to modify
alphabetagamma - the new angles values, in degrees
chfl_cell_matrix(const CHFL_CELL * cell, double mat[3][3])Get the unit cell matricial representation.
cell - the unit cell to use
mat - the matrix to fill. It should be a 3x3 matrix.
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.
chfl_cell_type(const CHFL_CELL * cell, chfl_cell_type_t * type)Get the cell type.
cell - the unit cell to read
type - the type of the cell
chfl_cell_set_type(CHFL_CELL * cell, chfl_cell_type_t type)Set the cell type.
cell - the cell to modify
type - the new type of the cell
chfl_cell_periodicity(const CHFL_CELL * cell, bool * x, bool * y, bool * z)Get the cell periodic boundary conditions along the three axis.
cell - the cell to read
xyz - the periodicity of the cell along the three axis.
chfl_cell_set_periodicity(CHFL_CELL * cell, bool x, bool y, bool z)Set the cell periodic boundary conditions along the three axis.
cell - the cell to modify
xyz - the new periodicity of the cell along the three axis.
chfl_cell_free(CHFL_CELL * cell)Destroy an unit cell, and free the associated memory.
cell - The cell to destroy
CHFL_TOPOLOGY¶chfl_topology()Create a new empty topology.
chfl_topology_from_frame(CHFL_FRAME * frame)Extract the topology from a frame.
frame - The frame
chfl_topology_atoms_count(const CHFL_TOPOLOGY * topology, size_t * natoms)Get the current number of atoms in the topology.
topology - The topology to analyse
natoms - Will contain the number of atoms in the frame
chfl_topology_append(CHFL_TOPOLOGY * topology, const CHFL_ATOM * atom)Add an atom at the end of a topology.
topology - The topology
atom - The atom to be added
chfl_topology_remove(CHFL_TOPOLOGY * topology, size_t i)Remove an atom from a topology by index. This modify all the other atoms indexes.
topology - The topology
i - The atomic index
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.
topology - The topology
ij - The atomic indexes
result - true if the atoms are bonded, false otherwise
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.
topology - The topology
ijk - The atomic indexes
result - true if the atoms constitues an angle, false otherwise
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.
topology - The topology
ijkm - The atomic indexes
result - true if the atoms constitues a dihedral angle, false otherwise
chfl_topology_bonds_count(const CHFL_TOPOLOGY * topology, size_t * nbonds)Get the number of bonds in the system.
topology - The topology
nbonds - After the call, contains the number of bond
chfl_topology_angles_count(const CHFL_TOPOLOGY * topology, size_t * nangles)Get the number of angles in the system.
topology - The topology
nangles - After the call, contains the number of angles
chfl_topology_dihedrals_count(const CHFL_TOPOLOGY * topology, size_t * ndihedrals)Get the number of dihedral angles in the system.
topology - The topology
ndihedrals - After the call, contains the number of dihedral angles
chfl_topology_bonds(const CHFL_TOPOLOGY * topology, size_t(*) data[2], size_t nbonds)Get the list of bonds in the system.
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
chfl_topology_angles(const CHFL_TOPOLOGY * topology, size_t(*) data[3], size_t nangles)Get the list of angles in the system.
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
chfl_topology_dihedrals(const CHFL_TOPOLOGY * topology, size_t(*) data[4], size_t ndihedrals)Get the list of dihedral angles in the system.
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
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.
topology - The topology
ij - The atomic indexes
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.
topology - The topology
ij - The atomic indexes
chfl_topology_free(CHFL_TOPOLOGY * topology)Destroy a topology, and free the associated memory.
topology - The topology to destroy
CHFL_ATOM¶chfl_atom(const char * name)Create an atom from an atomic name.
name - The new atom name
chfl_atom_from_frame(const CHFL_FRAME * frame, size_t idx)Get a specific atom from a frame.
frame - The frame
idx - The atom index in the frame
chfl_atom_from_topology(const CHFL_TOPOLOGY * topology, size_t idx)Get a specific atom from a topology.
topology - The topology
idx - The atom index in the topology
chfl_atom_mass(const CHFL_ATOM * atom, float * mass)Get the mass of an atom, in atomic mass units.
atom - The atom
mass - The atom mass
chfl_atom_set_mass(CHFL_ATOM * atom, float mass)Set the mass of an atom, in atomic mass units.
atom - The atom
mass - The new atom mass
chfl_atom_charge(const CHFL_ATOM * atom, float * charge)Get the charge of an atom, in number of the electron charge e.
atom - The atom
charge - The atom charge
chfl_atom_set_charge(CHFL_ATOM * atom, float charge)Set the charge of an atom, in number of the electron charge e.
atom - The atom
charge - The new atom charge
chfl_atom_name(const CHFL_ATOM * atom, char * name, size_t buffsize)Get the name of an atom.
atom - The atom
name - A string buffer to be filled with the name
buffsize - The size of the string buffer
chfl_atom_set_name(CHFL_ATOM * atom, const char * name)Set the name of an atom.
atom - The atom
name - A null terminated string containing the new name
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.
atom - The atom
name - A string buffer to be filled with the name
buffsize - The size of the string buffer
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.
atom - The atom
radius - The Van der Waals radius of the atom or -1 if no value could be found.
chfl_atom_covalent_radius(const CHFL_ATOM * atom, double * radius)Try to get the covalent radius of an atom from the short name.
atom - The atom
radius - The covalent radius of the atom or -1 if no value could be found.
chfl_atom_atomic_number(const CHFL_ATOM * atom, int * number)Try to get the atomic number of an atom from the short name.
atom - The atom
number - The atomic number, or -1 if no value could be found.
Available types of atoms.
Values:
CHFL_ATOM_ELEMENT = = 0 - Element from the periodic table of elements.
CHFL_ATOM_CORSE_GRAIN = = 1 - Corse-grained atom are composed of more than one element: CH3 groups, amino-acids are corse-grained atoms.
CHFL_ATOM_DUMMY = = 2 - Dummy site, with no physical reality.
CHFL_ATOM_UNDEFINED = = 3 - Undefined atom type.
chfl_atom_type(const CHFL_ATOM * atom, chfl_atom_type_t * type)Get the atom type.
atom - the atom to read
type - the type of the atom
chfl_atom_set_type(CHFL_ATOM * atom, chfl_atom_type_t type)Set the atom type.
atom - the atom to modify
type - the new type of the atom
chfl_atom_free(CHFL_ATOM * atom)Destroy an atom, and free the associated memory.
atom - The atom to destroy