# Python interface reference¶

The Python interface is exposed in the chemfiles module, and this page list all the classes and methods in this module.

## Error handling¶

Chemfiles uses exceptions for error handling, throwing ChemfilesError when an error occurs.

exception 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.

## Trajectory class¶

class 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.

## Frame class¶

class 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_bond(i, j)

Add a bond between the atoms at indexes i and j in this Frame’s topology.

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.

atom(i)

Get a copy of the Atom at index i in this Frame.

cell()

Get a copy of the UnitCell of this Frame.

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.

has_velocities()

Check if this Frame contains velocity.

natoms()

Get the current number of atoms in this Frame.

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.

set_cell(cell)

Set the UnitCell of this Frame to cell.

set_step(step)

Set this Frame step to step.

set_topology(topology)

Set the Topology of this Frame to topology.

step()

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

topology()

Get a copy of the Topology of this Frame.

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.

## UnitCell class¶

class 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;
class 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.

angles()

Get the three angles of this UnitCell, in degrees.

lengths()

Get the three lenghts of this UnitCell, in Angstroms.

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.

set_lengths(a, b, c)

Set the three lenghts of this UnitCell to a, b and c. These values should be in Angstroms.

set_shape(shape)

Set the shape of this UnitCell to shape.

shape()

Get the shape of this UnitCell.

volume()

Get the volume of this UnitCell.

wrap(vector)

Wrap a vector in this UnitCell, and return the wrapped vector.

## Topology class¶

class 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_atom(atom)

Add a copy of the Atom atom at the end of this Topology.

add_bond(i, j)

Add a bond between the atoms at indexes i and j in this 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.

angles()

Get the list of angles in this Topology.

angles_count()

Get the number of angles in this Topology.

atom(i)

Get a copy of the Atom at index i from this Topology.

bonds()

Get the list of bonds in this Topology.

bonds_count()

Get the number of bonds in this Topology.

dihedrals()

Get the list of dihedral angles in this Topology.

dihedrals_count()

Get the number of dihedral angles in this Topology.

impropers()

Get the list of improper angles in this Topology.

impropers_count()

Get the number of improper angles in this Topology.

natoms()

Get the number of atoms 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(i)

Get the Residue at index i from this Topology.

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_count()

Get the number of residues in this Topology.

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.

## Atom class¶

class chemfiles.Atom(name, type=None)

An Atom is a particle in the current Frame. It stores the following atomic properties:

• atom name;
• atom type;
• atom mass;
• atom charge.

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.

charge()

Get this Atom charge, in number of the electron charge e.

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.

mass()

Get this Atom mass, in atomic mass units.

name()

Get this Atom name.

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.

set_charge(charge)

Set this Atom charge, in number of the electron charge e.

set_mass(mass)

Set this Atom mass, in atomic mass units.

set_name(name)

Set this Atom name to name.

set_type(type)

Set this Atom type to type.

type()

Get this Atom type.

vdw_radius()

Try to get the Van der Waals radius of this Atom from its type. If the radius can not be found, returns 0.

## Residue class¶

class chemfiles.Residue(name, resid=None)

A Residue is a group of atoms belonging to the same logical unit. They can be small molecules, amino-acids in a protein, monomers in polymers, etc.

Create a new Residue from a name and optionally a residue id resid.

add_atom(atom)

Add the atom index atom in the Residue.

atoms()

Get the indexes of the atoms in this Residue.

contains(atom)

Check if the Residue contains the atom at index atom.

id()

Get the Residue index in the initial topology.

name()

Get the name of this Residue.

natoms()

Get the current number of atoms in the Residue.

## Selection class¶

class 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.

size()

Get the size of this Selection.

The size of a selection is the number of atoms we are selecting together. This value is 1 for the ‘atom’ context, 2 for the ‘pair’ and ‘bond’ context, 3 for the ‘three’ and ‘angles’ contextes and 4 for the ‘four’ and ‘dihedral’ contextes.

string()

Get the selection string used to create this Selection.