Python interface reference¶

The Python interface is built on top of the C interface, using the ctypes standard module.

This interface is contained in the chemfiles module, and this page list all the classes and methods in this module.

Logging functions¶

All logging in chemfiles uses a global maximal logging level, of type LogLevel, which can be manipulated using log_level and set_log_level. The logging output is by default redirected to the standard error stream, but this can be changed by using the log_to_stderr; log_to_stdout; log_to_file; log_callback and silent functions.

class chemfiles.logging.LogLevel¶

Available log levels:

ERROR: Only log errors
WARNING: Log errors and warnings
INFO: Log errors, warnings and informations
DEBUG: Log everything, from errors to debug informations

chemfiles.logging.log_callback(callback)¶

Use a callback for logging, instead of the built-in logging system.

The callback function must have the following signature:

def callback(level, message):
    ...
    return None

where level is a LogLevel, and message a string containing the log message.

chemfiles.logging.log_level()¶: Get current logging level

chemfiles.logging.log_to_file(path)¶: Write logs to the file at path, creating it if needed.

chemfiles.logging.log_to_stderr()¶: Write logs to the standard error stream. This is the default.

chemfiles.logging.log_to_stdout()¶: Write logs to the standard output stream.

chemfiles.logging.set_log_level(level)¶: Set the logging level to level

chemfiles.logging.silent()¶: Remove all logging output

Error classes¶

Chemfiles uses exceptions for error handling, and will only throw one of these exceptions. The ChemfilesException base class can be used to catch all chemfiles related errors.

exception chemfiles.errors.ArgumentError¶: Error in argument type

exception chemfiles.errors.CPPException(status)¶: Error in C++ runtime

exception chemfiles.errors.ChemfilesException¶: Base class for all Chemfiles exceptions

exception chemfiles.errors.NullPointerError¶: Got a NULL pointer from C!

chemfiles.errors.clear_errors()¶: Clear any error message saved in the library

chemfiles.errors.last_error()¶: Get the last error from the library

Trajectory class¶

class chemfiles.Trajectory(path, mode='r', fformat='')¶

A Trajectory is a chemistry file on the hard drive. It is the main entry point of Chemfiles.

nsteps()¶: Get the number of steps (the number of frames) in a Trajectory.

read()¶: Read the next step of the Trajectory and return the corresponding Frame

read_step(step)¶: Read a specific step in the Trajectory and return the corresponding Frame.

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)¶: 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.

set_topology_file(filename)¶: Set the Topology associated with a Trajectory by reading the first Frame of filename; and extracting the Topology of this Frame.

sync()¶: Synchronize any buffered content to the hard drive.

write(frame)¶: Write a Frame to the Trajectory

Frame class¶

class chemfiles.Frame(natoms=0)¶

A Frame holds data from one step of a simulation: the current Topology, the positions, and maybe the velocities of the particles in the system.

add_velocities()¶: Add velocity information to this Frame

atom(index)¶: Get a specific Atom from a frame, given its index in the frame

cell()¶: Get the UnitCell from the Frame

guess_topology(bonds=True)¶: 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.

has_velocities()¶: Check if the Frame has velocity information.

natoms()¶: Get the current number of atoms in the Frame.

positions()¶: Get a view into the positions of the Frame.

resize(size)¶: Get the positions from the Frame.

set_cell(cell)¶: Set the UnitCell of the Frame

set_step(step)¶: Set the Frame step

set_topology(topology)¶: Set the Topology of the Frame

step()¶: Get the Frame step, i.e. the frame number in the trajectory

topology()¶: Get the Topology from the Frame

velocities()¶: Get a view into the velocities of the Frame.

UnitCell class¶

class chemfiles.CellType¶

Available cell types in Chemfiles:

CellType.Orthorhombic: The three angles are 90°
CellType.Triclinic: The three angles may not be 90°
CellType.Infinite: Cell type when there is no 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 in the system, and its periodicity.

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

An unit cell also have a cell type, represented by the CellType class.

angles()¶: Get the three angles of an UnitCell, in degrees.

lengths()¶: Get the three lenghts of an UnitCell, in Angstroms.

matrix()¶: Get the unit cell matricial representation.

set_angles(alpha, beta, gamma)¶: Set the three angles of an UnitCell, in degrees. This is only possible for CellType.Triclinic cells.

set_lengths(a, b, c)¶: Set the three lenghts of an UnitCell, in Angstroms.

set_type(celltype)¶: Set the type of the unit cell

type()¶: Get the type of the unit cell

volume()¶: Get the volume of the unit cell

Topology class¶

class chemfiles.Topology¶

A Topology contains the definition of all the particles in the system, and the liaisons between the particles (bonds, angles, dihedrals, ...).

Only the atoms and the bonds are stored, the angles and the dihedrals are computed automaticaly.

add_bond(i, j)¶: Add a bond between the atoms at indexes i and j in the system

angles()¶: Get the list of angles in the system

angles_count()¶: Get the number of angles in the system

append(atom)¶: Add an Atom at the end of the Topology

atom(index)¶: Get the Atom at index from a topology.

bonds()¶: Get the list of bonds in the system

bonds_count()¶: Get the number of bonds in the system

dihedrals()¶: Get the list of dihedral angles in the system

dihedrals_count()¶: Get the number of dihedral angles in the system

isangle(i, j, k)¶: Tell if the atoms at indexes i, j and k constitues an angle

isbond(i, j)¶: Tell if the atoms at indexes i and j are bonded together

isdihedral(i, j, k, m)¶: Tell if the atoms at indexes i, j, k and m constitues a dihedral angle

natoms()¶: Get the current number of atoms in the Topology.

remove(index)¶: Remove an Atom from the Topology by index. This can modify all the other atoms indexes.

remove_bond(i, j)¶: Remove any existing bond between the atoms at indexes i and j in the system

Atom class¶

class chemfiles.AtomType¶

Available types of atoms:

AtomType.Element: Element from the periodic table of elements
AtomType.CorseGrain: Corse-grained atom are composed of more than one

element: CH3 groups, amino-acids are corse-grained atoms.
AtomType.Dummy: Dummy site, with no physical reality
AtomType.Undefined: Undefined atom type

class chemfiles.Atom(name)¶

An Atom is a particle in the current Frame. It can be used to store and retrieve informations about a particle, such as mass, name, atomic number, etc.

atomic_number()¶: Try to get the atomic number of the Atom. If the number can not be found, returns -1.

charge()¶: Get the Atom charge, in number of the electron charge e

covalent_radius()¶: Try to get the covalent radius of the Atom. If the radius can not be found, returns -1.

full_name()¶: Try to get the full name of the Atom. The full name of “He” is “Helium”, and so on. If the name can not be found, returns the empty string.

mass()¶: Get the Atom mass, in atomic mass units

name()¶: Get the Atom name

set_charge(charge)¶: Set the Atom charge, in number of the electron charge e

set_mass(mass)¶: Set the Atom mass, in atomic mass units

set_name(name)¶: Set the Atom name

set_type(atomtype)¶: Set the type of the atom

type()¶: Get the type of the atom

vdw_radius()¶: Try to get the Van der Waals radius of the Atom. If the radius can not be found, returns -1.

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.

evaluate(frame)¶: Evaluate a Selection for a given Frame, and return a list of matching atoms, either a a list of index or a list of tuples of indexes.

size()¶

Get the size of the Selection, i.e. 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.