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
ChemfilesError
when an
error occurs.
chemfiles.utils.
ChemfilesError
¶Exception class for errors in chemfiles
chemfiles.utils.
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.utils.
add_configuration
(path)¶Read configuration data from the file at path
.
By default, chemfiles reads configuration from any file name .chemfilesrc in the current directory or any parent directory. This function can be used to add data from another configuration file.
This function will fail if there is no file at path
, or if the file is
incorectly formatted. Data from the new configuration file will overwrite
any existing data.
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_residue
(residue)¶Add the Residue
residue
to this Frame
’s
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.
add_velocities
()¶Add velocity data to this Frame
.
The velocities are initialized to zero. If the frame already contains velocities, this function does nothing.
angle
(i, j, k)¶Get the angle formed by the atoms at indexes i
, j
and k
in
this Frame
, accounting for periodic boundary conditions.
The result is expressed in radians.
dihedral
(i, j, k, m)¶Get the dihedral angle formed by the atoms at indexes i
, j
,
k
and m
in this Frame
, accounting for periodic
boundary conditions. The result is expressed in radians.
distance
(i, j)¶Get the distance between the atoms at indexes i
and j
in this
Frame
, accounting for periodic boundary conditions. The
result is expressed in angstroms.
get
(name)¶Get a property of this frame with the given name
, or raise an error
if the property does not exists.
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.
out_of_plane
(i, j, k, m)¶Get the out of plane distance formed by the atoms at indexes i
,
j
, k
and m
in this Frame
, accounting for
periodic boundary conditions. The result is expressed in angstroms.
This is the distance betweent the atom j and the ikm plane. The j atom is the center of the improper dihedral angle formed by i, j, k and m.
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()
.
remove_bond
(i, j)¶Remove any existing bond between the atoms at indexes i
and j
in this Frame
’s topology.
This function does nothing if there is no bond between i
and j
.
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.
set
(name, value)¶Set a property of this frame, with the given name
and value
.
The new value overwrite any pre-existing property with the same name.
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.
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 0.
covalent_radius
()¶Try to get the covalent radius of this Atom
from its type.
If the radius can not be found, returns 0.
full_name
()¶Try to get the full name of this Atom
from its type. For
example, the full name of “He” is “Helium”. If the name can not be
found, returns the empty string.
get
(name)¶Get a property of this atom with the given name
, or raise an error
if the property does not exists.
set
(name, value)¶Set a property of this atom, with the given name
and value
.
The new value overwrite any pre-existing property with the same name.
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.