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.
chfl_version
(void)Get the version of the chemfiles library.
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_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.
chfl_loglevel
(chfl_log_level_t * level)Get the current maximal logging level.
level
- The logging level
chfl_set_loglevel
(chfl_log_level_t level)Set the current maximal 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.
The return values for this status code correspond to the following macros:
Status code for success.
Memory error: out of memory, wrong size for arrays parameters, ...
File error: file do not exist, you do not have rights to open it, ...
Error in file formating.
Any other error from Chemfiles.
Error in the C++ standard library.
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_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.
frame
- The frame
natoms
- The new number of atoms.
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.
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
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.
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
chfl_frame_has_velocities
(const CHFL_FRAME * frame, bool * has_velocities)Ask wether this frame contains velocity data or not.
frame
- The frame
has_velocities
- A boolean, will be true if the frame have velocities, false otherwise.
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.
frame
- The frame
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_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.
matched
to (matched + natoms)
is a valid adress range.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.
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.
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_from_frame
(const 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
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_set_lengths
(CHFL_CELL * cell, double a, double b, double c)Set the unit cell lenghts.
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)
chfl_cell_angles
(const CHFL_CELL * cell, double * alpha, double * beta, double * gamma)Get the cell angles, in degrees.
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)
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
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)
chfl_cell_matrix
(const CHFL_CELL * cell, double matrix[3][3])Get the unit cell matricial representation.
cell
- the unit cell to use
matrix
- 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_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
(const CHFL_FRAME * frame)Get a copy of the topology of 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
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
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
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
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
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
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
i
- index of the first atom in the topology
j
- index of the second atom in the topology
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
i
- index of the first atom in the topology
j
- index of the second atom in the topology
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_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.
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