The Python interface is exposed in the chemfiles module, and this page
list all the classes and methods in this module.
Chemfiles uses exceptions for error handling, throwing
ChemfilesException when an
error occurs.
chemfiles.errors.ChemfilesException¶Exception class for errors in chemfiles
chemfiles.errors.set_warnings_callback(function)¶Call function on every warning event. The callback should take a string message and return nothing.
By default, warnings are send to python warnings module.
chemfiles.Trajectory(path, mode=’r’, format=”)¶A Trajectory is a chemistry file on the hard drive. It is the
main entry point of Chemfiles.
Open the Trajectory at the given path using the
given mode and optional specific file format.
Valid modes are 'r' for read, 'w' for write and 'a' for
append.
The specific file format 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 file extension.
close()¶Close the Trajectory and write any buffered content to the
hard drive.
nsteps()¶Get the number of steps (the number of frames) in a
Trajectory.
read(frame=None)¶Read the next step of the Trajectory and return the
corresponding Frame. If the frame parameter is given,
reuse the corresponding allocation.
read_step(step, frame=None)¶Read a specific step in the Trajectory and return the
corresponding Frame. If the frame parameter is given,
reuse the corresponding allocation.
set_cell(cell)¶Set the UnitCell associated with a Trajectory.
This UnitCell will be used when reading and writing the
files, replacing any UnitCell in the frames or files.
set_topology(topology, format=”)¶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.
If topology is a Topology instance, it is used
directly. If topology is a string, the first Frame of
the corresponding file is read, and the topology of this frame is used.
When reading from a file, if format is not the empty string, the
code uses this file format instead of guessing it from the file
extension.
write(frame)¶Write a Frame to the Trajectory.
chemfiles.Frame¶A Frame contains data from one simulation step: the current
unit cell, the topology, the positions, and the velocities of the particles
in the system. If some information is missing (topology or velocity or unit
cell), the corresponding data is filled with a default value.
Create an empty Frame that will be resized by the runtime
as needed.
add_atom(atom, position, velocity=None)¶Add a copy of the Atom atom and the corresponding
position and velocity to this Frame.
velocity can be None if no velocity is associated with the
atom.
add_velocities()¶Add velocity data to this Frame.
The velocities are initialized to zero. If the frame already contains velocities, this function does nothing.
guess_topology()¶Guess the bonds, angles and dihedrals in this Frame.
The bonds are guessed using a distance-based algorithm, and then angles and dihedrals are guessed from the bonds.
positions()¶Get a view into the positions of this Frame.
Positions are stored as a natoms x 3 array by thez runtime, this function gives direct access to the corresponding memory as a numpy array. Modifying the array will change the positions.
If the frame is resized (by writing to it, calling
Frame.resize(), Frame.add_atom(),
Frame.remove()), the array is invalidated. Accessing it can
cause a segfault.
remove(i)¶Remove the atom at index i in this Frame.
This modify all the atoms indexes after i, and invalidate any array
obtained using Frame.positions() or
Frame.velocities().
resize(natoms)¶Resize the positions, velocities and topology in this
Frame, to have space for natoms atoms.
This function may invalidate any array of the positions or the velocities if the new size is bigger than the old one. In all cases, previous data is conserved. This function conserve the presence or absence of velocities.
velocities()¶Get a view into the velocities of this Frame.
Velocities are stored as a natoms x 3 array by thez runtime, this function gives direct access to the corresponding memory as a numpy array. Modifying the array will change the velocities.
If the frame is resized (by writing to it, calling
Frame.resize(), Frame.add_atom(),
Frame.remove()), the array is invalidated. Accessing it can
cause a segfault.
chemfiles.CellShape¶Available cell shapes in Chemfiles:
CellType.Orthorhombic: for cells where the three angles are 90°;CellType.Triclinic: for cells where the three angles may not be 90°;CellType.Infinite: for cells without periodic boundary conditions;chemfiles.UnitCell(a, b, c, alpha=90.0, beta=90.0, gamma=90.0)¶An UnitCell represent the box containing the atoms, and its
periodicity.
An unit cell is fully represented by three lenghts (a, b, c); and three angles (alpha, beta, gamma). The angles are stored in degrees, and the lenghts in Angstroms. The cell angles are defined as follow: alpha is the angles between the cell vectors b and c; beta as the angle between a and c; and gamma as the angle between a and b.
A cell also has a matricial representation, by projecting the three base vector into an orthonormal base. We choose to represent such matrix as an upper triangular matrix:
| a_x b_x c_x |
| 0 b_y c_y |
| 0 0 c_z |
Create a new UnitCell with cell lenghts of a, b and
c, and cell angles alpha, beta and gamma.
If alpha, beta and gamma are equal to 90.0, the new unit cell shape is
CellShape.Orthorhombic. Else it is CellShape.Infinite.
matrix()¶Get this UnitCell matricial representation.
The matricial representation is obtained by aligning the a vector along the x axis and putting the b vector in the xy plane. This make the matrix an upper triangular matrix:
| a_x b_x c_x |
| 0 b_y c_y |
| 0 0 c_z |
set_angles(alpha, beta, gamma)¶Set the three angles of this UnitCell to alpha,
beta and gamma. These values should be in degrees. Setting
angles is only possible for CellShape.Triclinic cells.
chemfiles.Topology¶A Topology contains the definition of all the atoms in the
system, and the liaisons between the atoms (bonds, angles, dihedrals, …).
It will also contain all the residues information if it is available.
Create a new empty Topology.
add_residue(residue)¶Add the Residue residue to this Topology.
The residue id must not already be in the topology, and the residue
must contain only atoms that are not already in another residue.
isdihedral(i, j, k, m)¶Tell if the atoms at indexes i, j, k and m constitues a
dihedral angle in this Topology.
remove(i)¶Remove the Atom at index i from this
Topology.
This shifts all the atoms indexes after i by 1 (n becomes n-1).
remove_bond(i, j)¶Remove any existing bond between the atoms at indexes i and j
in this Topology.
This function does nothing if there is no bond between i and j.
residue_for_atom(i)¶Get the Residue containing the atom at index i from
this Topology. If the atom is not in a residue, this
function returns None.
residues_linked(first, second)¶Check if the two Residue first and second from this
Topology are linked together, i.e. if there is a bond
between one atom in the first residue and one atom in the second one.
resize(natoms)¶Resize this Topology to contain natoms atoms. If the
new number of atoms is bigger than the current number, new atoms will
be created with an empty name and type. If it is lower than the current
number of atoms, the last atoms will be removed, together with the
associated bonds, angles and dihedrals.
chemfiles.Atom(name, type=None)¶An Atom is a particle in the current Frame. It
stores the following atomic properties:
The atom name is usually an unique identifier ("H1", "C_a") while
the atom type will be shared between all particles of the same type:
"H", "Ow", "CH3".
Create a new Atom from a name, and set the atom type
to name.
atomic_number()¶Try to get the atomic number of this Atom from its type. If
the atomic number can not be found, returns -1.
covalent_radius()¶Try to get the covalent radius of this Atom from its type.
If the radius can not be found, returns -1.
chemfiles.Selection(selection)¶Select atoms in a Frame with a selection language.
The selection language is built by combining basic operations. Each basic
operation follows the <selector>[(<variable>)] <operator> <value>
structure, where <operator> is a comparison operator in
== != < <= > >=. Refer to the full documentation to know the allowed selectors and how to use them.
Create a new Selection from the given selection string.
evaluate(frame)¶Evaluate a Selection for a given Frame, and
return a list of matching atoms, either as a list of index or a list
of tuples of indexes.