Welcome to chemlab’s documentation!¶

Version 0.4¶

chemlab.mviewer:

• Added a full-fledged molecular viewer. But it will be gone in favor of the notebook based chemview.

chemlab.io:

• Added cclib integration

chemlab.notebook:

• New module with functions for the IPython notebook. Requires chemview.

chemlab.qc:

• Example module for quantum chemistry calculation. Please file an issue on GitHub if you want to maintain it.

Version 0.3¶

chemlab.core:

• New bond handling with the Molecule.bonds and System.bonds attributes
• Possibility to add charges

chemlab.graphics:

• Post Processing Effects:

  • FXAA – Fast Approximate Antialiasing
  • Gamma Correction
  • Glow
  • Outline
  • SSAO – Screen Space Ambient Occlusion

• Renderers:

  • Implemented toon shading for different shapes.
  • CylinderImpostorRenderer – a really fast way to draw cylinders

• Offline Rendering at any resolution supported by the video card.

• Started some work on user interaction for a full molecular viewer.

chemlab.db:

• New Databases:

  • RCSB for protein structures
  • ToxNetDB for properties
  • ChemspiderDB

Version 0.2¶

chemlab.core:

• Serialization through json with from_json and tojson for Atom, System and Molecule;
• Removing atoms and molecules from System. System.remove_atoms, System.remove_molecules;
• Experimental support for customized Atom/Molecule/System types.
• Some indexing routines: System.atom_to_molecules_indices and System.mol_to_atom_indices;
• Custom sorting of systems throught System.reorder_molecules;
• Support for bonds in molecules and experimental support for bonds in Systems throught Molecule.bonds and System.get_bonds_array
• System.merge_systems has a better overlap handling.
• Removed boxsize attribute, now you have to always specify box_vectors.
• Implemented random_lattice_box to do random solvent boxes.

chemlab.graphics:

• New Renderers: - BallAndStickRenderer - BondRenderer - WireframeRenderer
• Implemented Camera.autozoom for autoscaling
• Reimplemented BondRenderer in cython.

chemlab.io:

• New Handlers:

  • MDL molfile (.mol extension)
  • Chemical Markup Language (.cml extension)

chemlab.db:

• New package to handle databases
• CirDB to retrieve molecules from chemical identifier resolver
• ChemlabDB to retrieve built-in data
• LocalDB to make personal databases

chemlab.ipython:

• Preliminary ipython notebook integration. It can display Molecule and System instances by using out-of-screen rendering.

chemlab.utils:

• Implemented some (periodic/non-periodic) distance finding routines.

Development¶

After installing the dependencies, grab the chemlab source from git:

$ git clone --recursive https://github.com/chemlab/chemlab.git

Complile the included extensions:

$ python setup.py build_ext --inplace

Just add the chemlab directory to the PYTHONPATH in your .bashrc:

export PYTHONPATH=$PYTHONPATH:/path/to/chemlab

Manipulating Molecules¶

Molecules are easily and efficiently manipulated through the use of numpy arrays. One of the most useful arrays contained in Molecule is the array of coordinates Molecule.r_array. The array of coordinates is a numpy array of shape (NA,3) where NA is the number of atoms in the molecule. According to the numpy broadcasting rules, if you sum two arrays with shapes (NA,3) and (3,), each row of the first array gets summed with the second array. Let’s say we have a water molecule and we want to displace it randomly in a box, this is easily accomplished by initializing a Molecule at the origin and summing its coordinates with a random displacement:

import numpy as np

wat = Molecule([Atom("H", [0.0, 0.0, 0.0]),
                Atom("H", [0.0, 1.0, 0.0]),
                Atom("O", [0.0, 0.0, 1.0])], bonds=[[2, 0], [2, 1]])

# Shapes (NA, 3) and (3,)
wat.r_array += np.random.rand(3)

Using the same principles, you can also apply other kinds of transformations such as matrices. You can for example rotate the molecule by 90 degrees around the z-axis:

from chemlab.graphics.transformations import rotation_matrix

# The transformation module returns 4x4 matrices
M = rotation_matrix(np.pi/2, np.array([0.0, 0.0, 1.0]))[:3,:3]

# slow, readable way
for i,r in enumerate(wat.r_array):
    wat.r_array[i] = np.dot(M,r)

# numpy efficient way to do the same:
# wat.r_array = np.dot(wat.r_array, M.T)

The array-based API provides a massive increase in performance and a more straightforward integration with C libraries thanks to the numpy arrays. This feature comes at a cost: the data is copied between atoms and molecules, in other words the changes in the costituents atoms are not reflected in the Molecule and vice-versa. Even if it may look a bit unnatural, this approach limits side effects and makes the code more predictable and easy to follow.

Bonds between atoms can be set or retrieved by using the bonds attribute. It’s an array of integers of dimensions (nbonds, 2) where the integer value corresponds to the atomic indices:

>>> from chemlab.db import ChemlabDB
>>> water = ChemlabDB().get('molecule', 'example.water')
>>> water.bonds
array([[0, 1],
       [0, 2]])

By using the numpy.take function it’s very easy to extract properties relative to the bonds. numpy.take lets you index an array using another array as a source of indices, for example, we can extract the bonds extrema in this way:

>>> import numpy as np
>>> np.take(water.type_array, n.bonds)
array([['O', 'H'],
       ['O', 'H']], dtype=object)

If the array is not flat (like r_array), you can also specify the indexing axis; the following snippet can be used to retrieve the bond distances:

# With water.bonds[:, 0] we take an array with the indices of the
# first element of the bond. And we use numpy.take to use this array
# to index r_array. We index along the axis 0, along this axis
# the elements are 3D vectors.
>>> bond_starts = np.take(water.r_array, water.bonds[:, 0], axis=0)
>>> bond_ends = np.take(water.r_array, water.bonds[:, 1], axis=0)
>>> bond_vectors = bond_ends - bond_starts

# We sum the squares along the axis 1, this is equivalent of doint
# x**2 + y**2 + z**2 for each row of the bond_vectors array
>>> distances = np.sqrt((bond_vectors**2).sum(axis=1))
>>> print(distances)
[ 0.1         0.09999803]

Sometimes you don’t want to manually input the bonds, but want to have them automatically generated. In this case you may use the chemlab.core.Molecule.guess_bonds() method.

Systems¶

In context such as molecular simulations it is customary to introduce a new data structure called System. A System represents a collection of molecules, and optionally (but recommended) you can pass also periodic box information:

>>> from chemlab.core import System
# molecule = a list of Molecule instances
>>> s = System(molecules, boxsize=2.0)

A System does not directly take Atom instances as its constituents, therefore if you need to simulate a system made of single atoms (say, a box of liquid Ar) you need to wrap the atoms into a Molecule:

>>> ar = Atom('Ar', [0.0, 0.0, 0.0])
>>> mol = Molecule([ar])

System, similarly to Molecule, can expose data by using arrays and it inherits atomic data from the constituent molecules. For instance, you can easily and efficiently access all the atomic coordinates by using the attribute System.r_array. To understand the relation between Atom.r, Molecule.r_array and System.r_array you can refer to the picture below:

You can preallocate a System by using the classmethod System.empty (pretty much like you can preallocate numpy arrays with np.empty or np.zeros) and then add the molecules one by one:

import numpy as np
from chemlab.core import Atom, Molecule, System
from chemlab.graphics import display_system

# Template molecule
wat = Molecule([Atom('O', [0.00, 0.00, 0.01]),
                Atom('H', [0.00, 0.08,-0.05]),
                Atom('H', [0.00,-0.08,-0.05])])

# Initialize a system with four water molecules.
s = System.empty(4, 12) # 4 molecules, 12 atoms

for i in range(4):
    wat.move_to(np.random.rand(3)) # randomly displace the water molecule
    s.add(wat) # data gets copied each time

display_system(s)

Since the data is copied, the wat molecule acts as a template so you can move it around and keep adding it to the System.

Preallocating and adding molecules is a pretty fast way to build a System, but the fastest way (in terms of processing time) is to build the system by passing ready-made arrays, this is done by using chemlab.core.System.from_arrays().

Most of the chemlab.core.Molecule array attributes are still present in chemlab.core.System, including System.bonds; bonds between molecules are currently not supported and setting them will result in an unexpected behaviour. There is also a chemlab.core.System.guess_bonds() method to automatically set the intramolecular bonds.

from chemlab.db import ChemlabDB
from chemlab.core import random_lattice_box

# Example water molecule
water = ChemlabDB().get('molecule', 'example.water')

s = random_lattice_box([water], [1000], [4.0, 4.0, 4.0])

from chemlab.core import Atom, Molecule, crystal
from chemlab.graphics import display_system

# Molecule templates
na = Molecule([Atom('Na', [0.0, 0.0, 0.0])])
cl = Molecule([Atom('Cl', [0.0, 0.0, 0.0])])

s = crystal([[0.0, 0.0, 0.0], [0.5, 0.5, 0.5]], # Fractional Positions
            [na, cl], # Molecules
            225, # Space Group
            cellpar = [.54, .54, .54, 90, 90, 90], # unit cell parameters
            repetitions = [5, 5, 5]) # unit cell repetitions in each direction

display_system(s)

Manipulating Systems¶

Selections¶

You can manipulate systems by using some simple but flexible functions. It is really easy to generate a system by selecting a part from a bigger system, this is implemented in the functions chemlab.core.subsystem_from_atoms() and chemlab.core.subsystem_from_molecules().

Those two functions take as the first argument the original System, and as the second argument a selection. A selection is either a boolean array that is True when we want to select that element and False otherwise, or an integer array containing the elements that we want to select. By using those two functions we can create a subsystem by building those selections.

The following example shows an easy way to take the molecules that contain atoms in the region of space x > 0.5 by employing subsystem_from_atoms():

import numpy as np
from chemlab.core import crystal, Molecule, Atom, subsystem_from_atoms
from chemlab.graphics import display_system

# Template molecule
wat = Molecule([Atom('O', [0.00, 0.00, 0.01]),
              Atom('H', [0.00, 0.08,-0.05]),
              Atom('H', [0.00,-0.08,-0.05])])

s = crystal([[0.0, 0.0, 0.0]], [wat], 225,
     cellpar = [.54, .54, .54, 90, 90, 90], # unit cell parameters
     repetitions = [5, 5, 5]) # unit cell repetitions in each direction

selection = s.r_array[:, 0] > 0.5
sub_s = subsystem_from_atoms(s, selection)

display_system(sub_s)

It is also possible to select a subsystem by selecting specific molecules; in the following example we select the first 10 water molecules by using subsystem_from_molecules():

from chemlab.core import subsystem_from_molecules

selection = np.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
sub_s = subsystem_from_molecules(s, selection)

Note

chemlab will provide other selection utilities in the future, if you have a specific request, file an issue on github

Merging systems¶

You can also create a system by merging two different systems. In the following example we will see how to make a NaCl/H2O interface by using chemlab.core.merge_systems():

import numpy as np
from chemlab.core import Atom, Molecule, crystal
from chemlab.core import subsystem_from_atoms, merge_systems
from chemlab.graphics import display_system

# Make water crystal
wat = Molecule([Atom('O', [0.00, 0.00, 0.01]),
      Atom('H', [0.00, 0.08,-0.05]),
      Atom('H', [0.00,-0.08,-0.05])])

water_crystal = crystal([[0.0, 0.0, 0.0]], [wat], 225,
     cellpar = [.54, .54, .54, 90, 90, 90], # unit cell parameters
     repetitions = [5, 5, 5]) # unit cell repetitions in each direction

# Make nacl crystal
na = Molecule([Atom('Na', [0.0, 0.0, 0.0])])
cl = Molecule([Atom('Cl', [0.0, 0.0, 0.0])])

nacl_crystal = crystal([[0.0, 0.0, 0.0], [0.5, 0.5, 0.5]], [na, cl], 225,
      cellpar = [.54, .54, .54, 90, 90, 90],
      repetitions = [5, 5, 5])

water_half = subsystem_from_atoms(water_crystal,
                water_crystal.r_array[:,0] > 1.2)
nacl_half = subsystem_from_atoms(nacl_crystal,
                nacl_crystal.r_array[:,0] < 1.2)

interface = merge_systems(water_half, nacl_half)
display_system(interface)

At the present time, the merging will avoid overlapping by creating a bounding box around the two systems and removing the molecules of the first system that are inside the second system bounding box. In the future there will be more clever ways to handle this overlaps.

Removing¶

There are two methods used to remove specific atoms and molecules from a system. chemlab.core.System.remove_molecules() and chemlab.core.System.remove_atoms(). Taking from the previous NaCl example, you may need to remove some excess ions to meet the electroneutrality condition:

# n_na and n_cl are the number of Na and Cl molecules
toremove = 'Na' if n_na > n_cl else 'Cl'
nremove = abs(n_na - n_cl) # Number of indices to be removed

remove_indices = (s.type_array == toremove).nonzero()[0][:nremove]

s.remove_atoms(rem_indices)

Sorting and reordering¶

It is possible to reorder the molecules in a System by using the method chemlab.core.System.reorder_molecules() that takes the new order as the first argument. Reordering can be useful for example to sort the molecules against a certain key.

If you use chemlab in conjunction with GROMACS, you may use the chemlab.core.System.sort() to sort the molecules according to their molecular formulas before exporting. The topology file expect to have a file with the same molecule type ordererd.

Extending the base types¶

Differents applications of chemistry may require additional data attached to each atom, molecule or system. For example you may need the velocity of the system, atomic charges or number of electrons. Chemlab should be able to provide a way to simply attach this data while retaining the selection and sorting functionalities.

The management of the atomic and molecular properties within a System is done through specific handlers. Those handlers are called attributes and fields. In the following example we may see how it’s possible to add a new field “v” to the Atom class, and transmit this field as a “v_array” in the Molecule and System class. In those cases they basically take as their argument the attribute/field name, the type, and a function that return the default value for the field/attribute:

from chemlab.core.attributes import MArrayAttr, NDArrayAttr
from chemlab.core.fields import AtomicField

class MyAtom(Atom):
    fields = Atom.fields + [AtomicField("v",
                                        default=lambda at: np.zeros(3, np.float))]

class MyMolecule(Molecule):
    attributes = Molecule.attributes + [MArrayAttr("v_array", "v", np.float,
                                                    default=lambda mol: np.zeros((mol.n_atoms, 3), np.float))]

class MySystem(System):
    attributes = System.attributes + [NDArrayAttr("v_array", "v_array", np.float, 3)]

Those class are ready to use. You may want to create new instances with the Atom.from_fields, Molecule.from_arrays and System.from_arrays.

Once you’ve done your field-specific job with MyAtom/MyMolecule/MySystem you can convert back to a chemlab default class class by using the astype methods:

at = myat.astype(Atom)
mol = mymol.astype(Molecule)
sys = mysys.astype(System)

The jungle of file formats¶

There are a lot of file formats used and produced by chemistry applications. Each program has his way to store geometries, trajectories, energies and properties etc. chemlab tries to encompass all of those different properties by using a lightweight way to handle such differences.

Reading and writing data¶

The classes responsible for the I/O are subclasses of chemlab.io.handlers.IOHandler. These handlers take a file-like object as the first argument and they work all in the same way, here is an example of GroHandler:

from chemlab.io.handlers import GromacsIO

fd = open('waterbox.gro', 'rb')
infile = GromacsIO(fd)
system = infile.read('system')

# Modify system as you wish...
fd = open('waterbox_out.gro', 'w')
outfile = GromacsIO(fd)
outfile.write('system', system)

You first create the handler instance for a certain format and then you can read a certain feature provided by the handler. In this example we read and write the system feature.

Some file formats may have some extra data for each atom, molecule or system. For example the ”.gro” file formats have his own way to call the atoms in a water molecule: OW, HW1, HW2. To handle such issues, you can write this information in the export arrays contained in the data structures, such as Atom.export, Molecule.export, and their array-based counterparts Molecule.atom_export_array, System.mol_export and System.atom_export_array.

Those attributes are especially important where you write in some data format, since you may have to provide those attribute when you initialize your Atom, Molecule and System.

You can easily open a data file without even having to search his format handler by using the utility function chemlab.io.datafile() this is the recommended way for automatically opening a file:

from chemlab.io import datafile

# For reading
sys = datafile('waterbox.gro').read('system')
t, coords = datafile('traj.xtc').read('trajectory')

# For writing
datafile("output.gro", "w").write("system", sys)

Implementing your own IOHandler¶

Implementing or improving an existing IOHandler is a great way to participate in chemlab development. Fortunately, it’s extremely easy to set one up.

It boils down to a few steps:

1. Subclass IOHandler;
2. Define the class attributes can_read and can_write;
3. Implement the write and read methods for the features that you added in can_read and can_write;
4. Write the documentation for each feature.

Here is an example of the xyz handler:

import numpy as np
from chemlab.io.handlers import IOHandler
from chemlab.core import Molecule

class XyzIO(IOHandler):
    '''The XYZ format is described in this wikipedia article
    http://en.wikipedia.org/wiki/XYZ_file_format.

    **Features**

    .. method:: read("molecule")

       Read the coordinates in a :py:class:`~chemlab.core.Molecule` instance.

    .. method:: write("molecule", mol)

       Writes a :py:class:`~chemlab.core.Molecule` instance in the XYZ format.
    '''

    can_read = ['molecule']
    can_write = ['molecule']

    def read(self, feature):
        self.check_feature(feature, "read")
        lines = self.fd.readlines()

        num = int(lines[0])
        title = lines[1]

        if feature == 'title':
            return title

        if feature == 'molecule':
            type_array = []
            r_array = []
            for l in lines[2:]:
                type, x, y, z = l.split()
                r_array.append([float(x),float(y),float(z)])
                type_array.append(type)

            r_array = np.array(r_array)/10 # To nm
            type_array = np.array(type_array)

            return Molecule.from_arrays(r_array=r_array, type_array=type_array)


    def write(self, feature, mol):
        self.check_feature(feature, "write")
        lines = []
        if feature == 'molecule':
            lines.append(str(mol.n_atoms))

            lines.append('Generated by chemlab')
            for t, (x, y, z) in zip(mol.type_array, mol.r_array):
                lines.append('    %s       %.6f      %.6f      %.6f' %
                             (t, x*10, y*10, z*10))

            self.fd.write('\n'.join(lines))

A few remarks:

• It is recommended to use the method

  check_feature() before performing read/write. This will check that the feature is present in the can_read/can_write list;

• If you want to squeeze out performance you should use

  Molecule.from_arrays() and System.from_arrays();

• You can read whatever data you wish, for example the

  EdrIO handler does not read Molecule or System at all;

• You can definitely take inspiration from the handlers included in chemlab, Supported File Formats.

Intro¶

The chemlab.graphics package is one of the most interesting aspects of chemlab, that sets him apart from similar programs.

The purpose of the package is to provide a solid library to develop 3D applications to display chemical data in an flexible way. For example it’s extremely easy to build a molecular viewer and add a bunch of custom features to it.

The typical approach when developing a graphics application is to create a QtViewer instance and add 3D features to it:

>>> from chemlab.graphics import QtViewer
>>> v = QtViewer()

now let’s define a molecule. We can use the chemlab.db module to get a water template.

>>> from chemlab.graphics.renderers import AtomRenderer
>>> from chemlab.db  import ChemlabDB
>>> water = ChemlabDB().get('molecule', 'example.water')
>>> ar = v.add_renderer(AtomRenderer, water.r_array, water.type_array)
>>> v.run()

In this way you should be able to visualize a molecule where each atom is represented as a sphere. There are also a set of viewing controls:

• Mouse Drag (Left Click) or Left/Right/Up/Down: Rotate the molecule
• Mouse Drag (Right Click): Pan the view
• Mouse Wheel or +/-: Zoom in/out

In a similar fashion it is possible to display other features, such as boxes, cylinders, lines, etc. It is useful to notice that with Viewer.add_renderer we are not passing an instance of the renderer, but we’re passing the renderer class and its respective constructor arguments. The method Viewer.add_renderer returns the actual instance.

It is possible as well to overlay 2D elements to a scene in a similar fashion, this will display a string at the screen position 300, 300:

from chemlab.graphics.uis import TextUI
tui = v.add_ui(TextUI, 300, 300, "Hello, World!")

Anyway, I encourage you to use the powerful Qt framework to provide interaction and widgets to your application.

Renderers¶

Renderers are simply classes used to draw 3D objects. They are tecnically required to provide just one method, draw and they must take an instance of QChemlabWidget as their first argument (check out the AbstractRenderer class). In this way they provide the maximum flexibility required to build efficient opengl routines. Renderers may be subclass other renderers as well as use other renderers.

A very useful renderer is TriangleRenderer, used to render efficiently a list of triangles, it constitutes a basis for writing other renderers. TriangleRenderer works like this: you pass the vertices, normals and colors of the triangles and it will display a set of triangles in the world:

from chemlab.graphics import QtViewer
from chemlab.graphics.renderers import TriangleRenderer
from chemlab.graphics.colors import green
import numpy as np

vertices = np.array([[0.0, 0.0, 0.0], [0.0, 1.0, 0.0], [1.0, 0.0, 0.0]])
normals = np.array([[0.0, 0.0, 1.0], [0.0, 0.0, 1.0], [0.0, 0.0, 1.0]])
colors = np.array([green, green, green])

v = QtViewer()
v.add_renderer(TriangleRenderer, vertices, normals, colors)
v.run()

If you pass 6 vertices/normals/colors, it will display 2 triangles and so on. As a sidenote, it is very efficient and in fact chemlab.graphics.renderers.TriangleRenderer is used as a backend for a lot of other renderers such as SphereRenderer and CylinderRenderer. If you can reduce a shape in triangles, you can easily write a renderer for it.

In addition to that, TriangleRenderer provides also a method to update vertices, normals and colors. We can demonstrate that from the last example by defining an update function that rotates our triangle:

from chemlab.graphics.transformations import rotation_matrix

def update():
    y_axis = np.array([0.0, 1.0, 0.0])

    # We take the [:3,:3] part because rotation_matrix can be used to
    # rotate homogeneous (4D) coordinates.
    rot = rotation_matrix(3.14/32, y_axis)[:3, :3]

    # This is the numpy-efficient way of applying rot to each coordinate
    vertices[:] = np.dot(vertices, rot.T)
    normals[:] = np.dot(vertices, rot.T)

    tr.update_vertices(vertices)
    tr.update_normals(normals)
    v.widget.update()

v.schedule(update, 10)
v.run()

Post Processing Effects¶

Post processing effects are a great way to increase the visual quality of your representations. Those effects are applied after the scene is rendered and they can be applied one after each other to achieve a combination of effects.

Applying a post processing effect is extremely easy. Let’s see we are viewing a big molecule with lots of pockets, such as a protein. Grab the protein 3ZJE , load it into chemlab and display it using a simple Van der Waals representation:

from chemlab.graphics import QtViewer
from chemlab.graphics.renderers import AtomRenderer
from chemlab.io import datafile

protein = datafile("3ZJE.pdb").read("molecule")
v = QtViewer()
v.add_renderer(AtomRenderer, protein.r_array, protein.type_array)
v.run()

You’ll get a representation like this:

This representation doesn’t really show the molecule surface features, plus it looks dull and plasticky. We can add the screen space ambient occlusion effect to improve its visual quality.

Screen space ambient occlusion (SSAO) is a very powerful technique used by numerous videogames to make the illumination much more realistic, by darkening the more occluded areas of the objects, such as pockets and surface features.

Chemlab implements this effect in the SSAOEffect class. To apply it to the scene it’s sufficient to add this simple line:

from chemlab.graphics.postprocessing import SSAOEffect

v.add_post_processing(SSAOEffect)
v.run()

What you’ll get is this, with a much-improved visual quality:

Post processing effects can be customized with arguments. The SSAO effect may have a dirty look, you can fix that by changing the parameter kernel_size, which default to 32, with a max value of 128:

v.add_post_processing(SSAOEffect, kernel_size=128)

This will improve the visual quality at the cost of decreased performance. To see all the options available take look at the api documentation List of Post Processing Effects.

Post processing effects can also be stacked on top of each other. If your computer is powerful enough, you can load your scene with a stack of effects that will be applied in turn:

from chemlab.graphics.postprocessing import SSAOEffect
from chemlab.graphics.postprocessing import OutlineEffect
from chemlab.graphics.postprocessing import FXAAEffect
from chemlab.graphics.postprocessing import GammaCorrectionEffect

v.add_post_processing(SSAOEffect) # better illumination
v.add_post_processing(OutlineEffect) # black outlines
v.add_post_processing(FXAAEffect) # fast antialiasing
v.add_post_processing(GammaCorrectionEffect) # color correction

v.run()

Unfortunately on ATI cards with open source drivers can’t apply multiple post processing effects. I’m investigating the issue, but this can be potentially due to a bug in the drivers.

Offline Rendering¶

With chemlab you can produce renderings programmatically without having to display anything or tinkering with the user interface. This feature comes pretty useful when generating reports with a lot of pictures.

Let’s say you want to make a showcase of different chemical compounds, such as the first four alkanes. First of all we’ll take a sample molecule to adjust the looks and then we’ll adapt the code to render all of the alkanes in a sequence.

As an example we’ll tweak our rendering on the norbornene molecule contained in the chemlab database:

from chemlab.db import ChemlabDB
cdb = ChemlabDB()

norb = cdb.get("molecule", "example.norbornene")

We want to do the rendering of this molecule using a space fill representation, this can be achieved by using the AtomRenderer, which will render each atom as a sphere with its Van Der Waals radius:

from chemlab.graphics import QtViewer
from chemlab.graphics.renderers import AtomRenderer

v = QtViewer()
atom_rend = v.add_renderer(AtomRenderer, norb.r_array, norb.type_array)

After we’ve got the renderer in place we can programmatically manipulate the camera to adjust at the right zoom level. You can, for instance, use the chemlab.graphics.camera.Camera.autozoom() method to automatically adjust the scene, but you are free to use any other method present in the Camera class:

v.widget.camera.autozoom(norb.r_array)

v.run()

At this point, you are free experiment with different effects and combinations. In our case we’ll add SSAO and anti aliasing to add more depth and smoothness to the rendering:

from chemlab.graphics.postprocessing import SSAOEffect, FXAAEffect

v.add_post_processing(SSAOEffect, kernel_size=128, kernel_radius=1.0)
v.add_post_processing(FXAAEffect)

v.run()

To actually save the image you can now use the chemlab.graphics.QChemlabWidget.toimage() method and select a resolution of 800x800 pixels. This will return a PIL image, that has a save method to store it as a png:

img = v.widget.toimage(800, 800)
img.save("norb.png")

Once we’ve got the sample molecule up and running it’s very easy to automatize the process to produce images of different molecules. In the following code we prepare the QtViewer with the effects, we call v.widget.initializeGL() in place of v.show() and for each molecule we add an AtomRenderer and adjust the camera:

from chemlab.db import CirDB
from chemlab.graphics import QtViewer
from chemlab.graphics.renderers import AtomRenderer
from chemlab.graphics.postprocessing import FXAAEffect, SSAOEffect

# A series of compounds to display
compounds = ["methane", "ethane", "propane", "butane"]

db = CirDB()

# Prepare the viewer
v = QtViewer()
v.widget.initalizeGL() # Needed if you don't call show()
v.add_post_processing(SSAOEffect, kernel_size=128, kernel_radius=1.0)
v.add_post_processing(FXAAEffect)

for compound in compounds:
    mol = db.get("molecule", compound)
    rend = v.add_renderer(AtomRenderer, mol.r_array, mol.type_array)

    v.widget.camera.autozoom(mol.r_array)
    # Give some extra zoom
    v.widget.camera.mouse_zoom(1.0)

    v.widget.toimage(300, 300).save(compound + '.png')

    # Cleanup
    v.remove_renderer(rend)

This example is stored in the chemlab/examples/offline_rendering.py file.

Tutorial: TetrahedronRenderer¶

In this section, we’ll see how to write a renderer that will display several tetrahedrons. We will write our TetrahedronRenderer based on TriangleRenderer. To do that we first need to understand how a tetrahedron is made, and how can we define the vertices that make the tetrahedron.

First of all, we need to have the 4 coordinates that represents a tetrahedron. Without even trying to visualize it, just pick the values straight from Wikipedia:

import numpy as np
v1 = np.array([1.0, 0.0, -1.0/np.sqrt(2)])
v2 = np.array([-1.0, 0.0, -1.0/np.sqrt(2)])
v3 = np.array([0.0, 1.0, 1.0/np.sqrt(2)])
v4 = np.array([0.0, -1.0, 1.0/np.sqrt(2)])

We can quickly verify if this is correcty by using a PointRenderer:

from chemlab.graphics import QtViewer
from chemlab.graphics.renderers import PointRenderer
from chemlab.graphics.colors import black, green, blue, red

colors = [black, green, blue, red]
v = QtViewer()
v.add_renderer(PointRenderer, np.array([v1, v2, v3, v4]), colors)
v.run()

We’ve got 4 boring points that look like they’re at the vertices of a tetrahedron. Most importantly we learned that we can use PointRenderer to quickly test shapes.

Now let’s define the four triangles (12 vertices) that represent a solid tetrahedron. It is good practice to put the triangle vertices in a certain order to estabilish which face is pointing outside and which one is pointing inside for optimization reasons. The convention is that if we specify 3 triangle vertices in clockwise order this means that the face points outwards from the solid:

We can therefore write our vertices and colors:

vertices = np.array([
    v1, v4, v3,
    v3, v4, v2,
    v1, v3, v2,
    v2, v4, v1
])

colors = [green] * 12

All is left to do is write the normals to the surface at each vertex. This is easily done by calculating the cross product of the vectors constituting two sides of a triangle (remember that the normals should point outward) and normalize the result:

n1 = -np.cross(v4 - v1, v3 - v1)
n1 /= np.linalg.norm(n1)

n2 = -np.cross(v4 - v3, v2 - v3)
n2 = np.linalg.norm(n2)

n3 = -np.cross(v3 - v1, v2 - v1)
n3 /= np.linalg.norm(n3)

n4 = -np.cross(v4 - v2, v1 - v2)
n4 /= np.linalg.norm(n4)

normals = [n1, n1, n1,
           n2, n2, n2,
           n3, n3, n3,
           n4, n4, n4]

from chemlab.graphics.renderers import TriangleRenderer

v.add_renderer(TriangleRenderer, vertices, normals, colors)
v.run()

Now that we’ve got the basic shape in place we can code the actual Renderer class to be used directly with the viewer. We will make a renderer that, given a set of coordinates will display many tetrahedra.

We can start by defining a Renderer class, inheriting from AbstractRenderer, the main thing you should notice is that you need an additional argument widget that will be passed when you use the method QtViewer.add_renderer:

from chemlab.graphics.renderers import AbstractRenderer

class TetrahedraRenderer(AbstractRenderer):
    def __init__(self, widget, positions):
        super(TetrahedraRenderer, self).__init__(widget)
        ...

The strategy to implement a multiple-tetrahedron renderer will be like this:

• store the triangle vertices, and normals of a single tetrahedra.
• for each position that we pass, translate the vertices of the single tetrahedra and accumulate the obtained vertices in a big array.
• repeat the normals of a single tetrahedra for the number of tetrahedra we’re going to render.
• generate the per-vertex colors (green for simplicity)
• create a TriangleRenderer as an attribute and initialize him with the accumulated vertices, normals, and colors
• reimplement the draw method by calling the draw method of our trianglerenderer.

You can see the code in this snippet:

class TetrahedraRenderer(AbstractRenderer):
    def __init__(self, widget, positions):
        super(TetrahedraRenderer, self).__init__(widget)

        v1 = np.array([1.0, 0.0, -1.0/np.sqrt(2)])
        v2 = np.array([-1.0, 0.0, -1.0/np.sqrt(2)])
        v3 = np.array([0.0, 1.0, 1.0/np.sqrt(2)])
        v4 = np.array([0.0, -1.0, 1.0/np.sqrt(2)])

        positions = np.array(positions)

        # Vertices of a single tetrahedra
        self._th_vertices = np.array([
            v1, v4, v3,
            v3, v4, v2,
            v1, v3, v2,
            v2, v4, v1
        ])

        self._th_normals = np.array([
            n1, n1, n1,
            n2, n2, n2,
            n3, n3, n3,
            n4, n4, n4])

        self.n_tetra = len(positions)

        tot_vertices = []
        for pos in positions:
            tot_vertices.extend(self._th_vertices + pos)

        # Refer to numpy.tile, this simply repeats the elements
        # of the array in an efficient manner.
        tot_normals = np.tile(self._th_normals, (self.n_tetra, 1))
        tot_colors = [green] * self.n_tetra * 12

        # !NOTICE! that we have to pass widget as the first argument
        self.tr = TriangleRenderer(widget, tot_vertices,
                                  tot_normals, tot_colors)

    def draw(self):
        self.tr.draw()

To demostrate let’s draw a grid of 125 tetrahedra:

positions = []

for x in range(5):
    for y in range(5):
        for z in range(5):
            positions.append([float(x)*2, float(y)*2, float(z)*2])

v.add_renderer(TetrahedraRenderer, positions)
v.widget.camera.position = np.array([0.0, 0.0, 20.0])
v.run()

If you had any problem with the tutorial or you want to implement other kind of renderers don’t exitate to contact me. The full code of this tutorial is in chemlab/examples/tetrahedra_tutorial.py.

Having your own molecular database¶

It may happen that you have your most-frequently used collection of molecules and systems. Chemlab provides a serialization system that let you easily dump your objects in a directory and retrieve them by using a local database.

This is achieved by the class chemlab.db.LocalDB:

from chemlab.db import LocalDB

ldb = LocalDB('/path/to/yourdb')
# Generate/retrieve some molecule

ldb.store('molecule', 'examplemol',  mol)
ldb.store('system', 'examplesys',  sys)

The method chemlab.db.LocalDB.store() takes a first argument that can be ither molecule or system, as a second argument the key used to store/retrieve the entry and finally the object to store.

You can, at a later time retrieve the entries in this way:

from chemlab.db import LocalDB

ldb = LocalDB('/path/to/yourdb')
mol = ldb.get('molecule', 'examplemol')
s = ldb.get('system', 'examplesys')

The molecules files are serialized using the json format and stored in a very simple directory structure. For the previous example, the database directory would look like this:

/path/to/yourdb/
        - molecule/
          - examplemol.json
        - system/
          - examplesys.json

The reason for such a simple structure is that in the future it will be easy to define custom-made remote database, for example you could have a community mantained github repo with commonly used molecules and data, that can be directly accessed by chemlab (everybody is welcome to develop such an extension). On top of that, you can copy-paste json molecule files without having to do any migration.

Quick Start¶

You can start the chemlab molecular viewer by typing:

chemlab view

This will load the user interface consisting of the viewer, and an IPython shell.

You can start typinc commands in the IPython shell and changes will appear immediately in the viewer. Downloading a molecule from the web is really easy with the command chemlab.mviewer.api.download_molecule():

download_molecule('aspirine')

You can select atoms by clicking on them. The selection effect is a white glow.

The molecular viewer can be used to perform some simple tasks programmatically.

Changing the Appeareance¶

Chemlab can make seriously good-looking pictures.

The general way the appeareance-related function work is that they apply on selections. Say, you want the change all the Carbon atom colors to black.

This is really easy to do:

select_atom_type('C')
change_color('black')

The colors available as string are the standard HTML colors, written in underscore.

You can also pass rgba tuples in the range 0-255. Please, leave the alpha value to 255:

select_atom_type('C')
change_color((0, 0, 0, 255))

Similarly you can change the radius of certain atoms or scale them:

select_all()
scale_atoms(2.0) # Scale Factor
change_radius(0.15) # Exact value in nm

Perhaps the most interesting feature are the post processing effects, the most interesting is called ‘ssao’ or Screen Space Ambient Occlusion. It enhances the picture by giving nice shadows in the more occluded areas, take a look at the picture generated by this code:

download_molecule('testosterone')

select_all()
scale_atoms(2.0)

# We make the colors brighter, ssao works best on light colors.

select_atom_type('C')
change_color((210, 210, 210, 0)) # That's a very light gray

select_atom_type('O')
change_color((255, 163, 163, 255))

change_background('white')

pp_id = add_post_processing('ssao')

# For max quality
# add_post_processing('ssao', kernel_size=128)

There is a good amount of shadows, you can also setup other effects such as anti aliasing and gamma correction:

add_post_processing('fxaa')
add_post_processing('gamma')

The function add_post_processing() returns a string id that you can use to remove the effect or to change its options. To list all the available post processing effects, use the function list_post_processing():

list_post_processing()
# ['ssao1', 'fxaa2', 'gamma3']
change_post_processing_options('ssao1', kernel_size=128)
remove_post_processing('fxaa2')
clear_post_processing()

Loading Data¶

The Chemlab molecular viewer provides quite handy function to load some data into it:

load_system("file.gro")
load_molecule("file.cml")

You can also download the molecule from a web database by its common name:

download_molecule('aspirine')

Or you can also download and open a file from a remote location using directly its URL:

load_remote_system('https://raw.github.com/chemlab/chemlab-testdata/master/naclwater.gro')
load_remote_molecule('https://raw.github.com/chemlab/chemlab-testdata/master/benzene.mol')

load_system('water.gro')
load_trajectory("traj.xtc")

load_remote_system('https://raw.github.com/chemlab/chemlab-testdata/master/water.gro')
load_remote_trajectory('https://github.com/chemlab/chemlab-testdata/raw/master/trajout.xtc')

Selections¶

In Chemlab you select and operate on atoms and bonds.

You can use the built-in functions to select according to various types:

select_atoms([0, 1, 2])
select_atom_type('Na')
select_molecules('H2O')
select_all()
select_within([0, 1], 0.2)

You can also act on the selection in different ways:

invert_selection()
clear_selection()

Each selection routine returns a Selection object, that contains information on the selection state, so you can use it later:

select_atoms([0, 1, 2])
Selection([0, 1, 2], tot=6)

The Selection() Selection objects have an API to be combined. For example if you want to select Na and Cl atoms you can do in this way, using the function select_selection():

na_at = select_atoms('Na')
cl_at = select_atoms('Cl')
select_selection({'atoms' : na_at.add(cl_at)})

You can retrieve the currently selected atoms and bonds indices in the following way:

selected_atoms()
selected_bonds()

Hiding and Showing¶

Sometimes you want to hide certain objects from the current view to remove clutter. For example if you want to select all the water molecules and hide them:

select_molecules('H2O')
hide()

There’s also a conveniency function to do this:

hide_water()

You can also select hidden objects and show them:

select_hidden()
show()

Writing your own commands¶

The built-in commands provide a quick and easy way to operate on your molecules and they provide basic functionality. The true power of chemlab relies in the possibility to write and load your commands using the power and simplicity of Python.

For example we can write a command that calculates automatically the distance between two selected atoms. We can open a file utils.py and put the following code in it:

import numpy as np

def distance():
   sel = selected_atoms()
   if len(sel) != 2:
       print("Only two atoms must be selected")
       return
   else:
       # Here we use numpy fancy indexing
       a, b = current_system().r_array[sel]
       return np.linalg.norm(b - a)

How can we access this function from a chemlab session?

The chemlab shell is just a regular Python shell, so one solution will be to simply add the directory to your PYTHONPATH and import it manually.

However, chemlab provides an init file that lets you write some code that will be called at initialization time.

The file is stored in the path .chemlab/scripts/__init__.py. To automatically load the command distance we have to first put the file utils.py in the directory .chemlab/scripts/ and add the following line to the __init__ file

from .utils import distance

You can easily write and hook in a lot of extensions. Please write something useful (You will!) and attach your code on the chemlab github page https://github.com/chemlab/chemlab/issues?labels=extension&milestone=&state=open

def select_within(radius):
    pass

for each atom:
    find the neighbours atoms
    select them

from chemlab.mviewer.toolboxes.selection import selected_atoms

def select_within(radius):
  neighbours = []

  for i_central in selected_atoms():
    r_central = current_system().r_array[i_central]

    for r in current_system().r_array:
       dist = np.linalg.norm(r - r_central)
       if dist < radius:
            neighbours.append(i)

  select_atoms(np.unique(neighbours))

from .myutils import select_within

current_system()

selected_atoms()
# array([ 0,  1])

select_atoms([0, 1])

selected = selected_atoms()
s = current_system()
a, b = s.r_array[selected]
import numpy as np
distance = np.linalg.norm(a - b)

Installing GROMACS¶

This depends on the system you’re using but I believe that GROMACS is already packaged for most linux distributions and also for other operating systems.

In Ubuntu:

$ sudo apt-get install gromacs

What GROMACS needs¶

In order to run a minimum simulation GROMACS requires to know some basic properties of the system we intend to simulate. This boils down to basically 3 ingredients:

1. The starting composition and configuration of our system. This is provided by a ”.gro” file that contains the atom and molecule types, and their position in space.
2. Information about the connectivity and interactions between our particles. This is called topology file and it is provided by writing a ”.top” file.
3. Simulation method. This will require us to give parameters on how we want to make the system evolve. This is provided by an ”.mdp” file.

chemlab can help us to build any system that we want and we’ll use it to write a ”.gro” file. Then we will use chemlab to visualize and analyze the result of the GROMACS simulation.

Crafting a box of water¶

There are many ways to generate a box of water, in our example we will place 512 water molecules in a cubic grid. The advantages of doing that is the simplicity of the approach and the fact that we are naturally avoid any overlap between adiacent molecules.

To generate such a box we will:

1. Create a template water Molecule;
2. Translate this molecule on the grid points
3. Add the molecule to a preinitialized System.

import numpy as np
from chemlab.core import Atom, Molecule, System
from chemlab.graphics import display_system

# Spacing between two grid points
spacing = 0.3

# an 8x8x8 grid, for a total of 512 points
grid_size = (8, 8, 8)

# Preallocate the system
# 512 molecules, and 512*3 atoms
s = System.empty(512, 512*3)

# Water template, it contains export informations for gromacs
# more about export later...
water_tmp = Molecule([Atom('O', [0.0, 0.0, 0.0], export={'grotype': 'OW'}),
                      Atom('H', [0.1, 0.0, 0.0], export={'grotype': 'HW1'}),
                      Atom('H', [-0.03333, 0.09428, 0.0], export={'grotype':'HW2'})],
                     export={'groname': 'SOL'})

for a in range(grid_size[0]):
    for b in range(grid_size[1]):
        for c in range(grid_size[2]):
            grid_point = np.array([a,b,c]) * spacing # array operation
            water_tmp.move_to(grid_point)
            s.add(water_tmp)

# Adjust boxsize for periodic boundary conditions
s.box_vectors = np.eye(3) * (8 * spacing)

# Visualize to verify that the system was setup correctly
display_system(s)

If you run this, it will display the following window:

Awesome! Now we can write the ”.gro” file. Notice that when we defined our water molecule we had to pass an export dictionary to the atoms and molecules. The export mechanism is the way used by chemlab to handle all the variety of different file formats.

In this specific case, gromacs defines its own atom and molecule names in the ”.top” file and then matches those to the ”.gro” file to infer the bonds and interactions.

TODO Add picture of the export dictionary

How do we write the .gro file? Since we’ve already setup our export information, this is an one-liner:

from chemlab.io import datafile

datafile("start.gro", "w").write("system", s)

.top and .mdp files¶

I’ll give you directly the gromacs input files to do an NPT simulation of water, just create those files in your working directory:

topol.top

; We simply import ready-made definitions for the molecule type
; SOL and the atom types OW, HW1 and HW2
#include "ffoplsaa.itp"
#include "spce.itp"

[ system ]
Simple box of water

[ molecules ]
SOL 512

run.mdp

integrator = md
dt = 0.001
nsteps = 200000
nstxtcout = 100

rlist = 0.9
coulombtype = pme
rcoulomb = 0.9
rvdw = 0.9
dispcorr = enerpres

tcoupl = v-rescale
tc-grps = System
ref_t = 300
tau_t = 0.1

pcoupl = berendsen
compressibility = 4.5e-5
ref_p = 1.0

gen_vel = yes
gen_temp = 300
constraints = all-bonds

Running the simulation¶

To run the simulation with gromacs we have to do two steps:

1. Generate a parameter input, this will check that our input make sense before running the simulation:

   grompp_d -f run.mdp -c start.gro -p topol.top
   

   This will generate a bunch of files in your working directory.

2. Now we run the simulation, in the meantime, go grab coffee:

   mdrun_d -v
   

   This will take a while depending on your machine. If you are not a coffee drinker, don’t worry, you can stop the simulation by pressing Ctrl-C. The good news is that chemlab can read files from partial runs!

Viewing the results, the command-line way¶

To quickly preview trajectories and system energies you can use the script chemlab included in the distribution in scripts/chemlab.

GROMACS can store the trajectory (in the form of atomic coordinates) in the .xtc file. To play the trajectory you can use the command:

$ chemlab view start.gro --traj traj.xtc

You may also be interested to look at some other properties, such as the potential energy, pressure, temperature and density. This information is written by GROMACS in the ”.edr” file. You can use the chemlab script to view that:

$ chemlab gromacs energy ener.edr -e Pressure
$ chemlab gromacs energy ener.edr -e Temperature
$ chemlab gromacs energy ener.edr -e Potential
$ chemlab gromacs energy ener.edr -e Density

It is also possible to view and get the results by directly reading the files and have direct access to the xtc coordinates and the energy stored in the edr files. Take a look at the reference for chemlab.io.handlers.XtcIO and chemlab.io.handlers.EdrIO.

The tutorial is over, if you have any problem or want to know more, just drop an email on the mailing list python-chemlab@googlegroups.com or file an issue on github https://github.com/chemlab/chemlab/issues

The Atom class¶

class chemlab.core.Atom(type, r, export=None)¶

Create an Atom instance. Atom is a generic container for particle data.

See also

Atoms, Molecules and Systems

Parameters

type: str

Atomic symbol

r: {np.ndarray [3], list [3]}

Atomic coordinates in nm

export: dict, optional

Additional export information.

Example

>>> Atom('H', [0.0, 0.0, 0.0])

In this example we’re attaching additional data to the Atom instance. The chemlab.io.GroIO can use this information when exporting in the gro format.

>>> Atom('H', [0.0, 0.0, 0.0], {'groname': 'HW1'})

type¶

Type:	str

The atomic symbol e.g. Ar, H, O.

r¶

Type:	np.ndarray(3) of floats

Atomic position in nm.

mass¶

Type:	float

Mass in atomic mass units.

charge¶

Type:	float

Charge in electron charge units.

export¶

Type:	dict

Dictionary containing additional information when importing data from various formats.

See also

chemlab.io.gro.GroIO

fields¶

Type:	tuple

This is a class attribute. The list of attributes that constitute the Atom. This is used to iterate over the Atom attributes at runtime.

copy()¶

Return a copy of the original Atom.

classmethod from_fields(**kwargs)¶

Create an Atom instance from a set of fields. This is a slightly faster way to initialize an Atom.

Example

>>> Atom.from_fields(type='Ar',
                     r_array=np.array([0.0, 0.0, 0.0]),
                     mass=39.948,
                     export={})

The Molecule class¶

class chemlab.core.Molecule(atoms, bonds=None, export=None)¶

Molecule is a data container for a set of N Atoms.

See also

Atoms, Molecules and Systems

Parameters

atoms: list of Atom instances

Atoms that constitute the Molecule. Beware that the data gets copied and subsequend changes in the Atom instances will not reflect in the Molecule.

export: dict, optional

Export information for the Molecule

r_array¶

Type:	np.ndarray((N,3), dtype=float)
Derived from:	Atom

An array with the coordinates of each Atom.

type_array {numpy.array[N] of str}

Type:	np.ndarray(N, dtype=str)
Derived from:	Atom

An array containing the chemical symbols of the constituent atoms.

m_array¶

Type:	np.ndarray(N, dtype=float)
Derived from:	Atom

Array of masses.

charge_array¶

Type:	np.ndarray(N, dtype=float)
Derived from:	Atom

Array of the charges present on the atoms.

atom_export_array¶

Type:	np.ndarray(N, dtype=object) array of dicts
Derived from:	Atom

Array of Atom.export dicts.

n_atoms¶

Type:	int

Number of atoms present in the molecule.

export¶

Type:	dict

Export information for the whole Molecule.

bonds¶

Type:	np.ndarray((NBONDS,2), dtype=int)

A list containing the indices of the atoms connected by a bond. Example: [[0 1] [0 2] [3 4]]

mass¶

Type:	float

Mass of the whole molecule in amu.

center_of_mass¶

Type:	float

geometric_center¶

Type:	float

formula¶

Type:	str

The brute formula of the Molecule. i.e. "H2O"

copy()¶

Return a copy of the molecule instance

classmethod from_arrays(**kwargs)¶

Create a Molecule from a set of Atom-derived arrays. Please refer to the Molecule Atom Derived Attributes. Only r_array and type_array are absolutely required, the others are optional.

>>> Molecule.from_arrays(r_array=np.array([[0.0, 0.0, 0.0],
                                           [1.0, 0.0, 0.0],
                                           [0.0, 1.0, 0.0]]),
                         type_array=np.array(['O', 'H', 'H']))
molecule(H2O)

Initializing a molecule in this way can be much faster than the default initialization method.

guess_bonds()¶

Guess the molecular bonds by using covalent radii information.

move_to(r)¶

Translate the molecule to a new position r.

tojson()¶

Return a json string representing the Molecule. This is useful for serialization.

The System class¶

class chemlab.core.System(molecules, box_vectors=None)¶

A data structure containing information of a set of N Molecules and NA Atoms.

Parameters

molecules: list of molecules

Molecules that constitute the System. The data gets copied to the System, subsequent changes to the Molecule are not reflected in the System.

box_vectors: np.ndarray((3,3), dtype=float), optional

You can specify a periodic box of another shape by giving 3 box vectors.

The System class has attributes derived both from the Molecule and the Atom class.

r_array¶

Type:	np.ndarray((NA, 3), dtype=float)
Derived from:	Atom

Atomic coordinates.

m_array¶

Type:	np.ndarray(NA, dtype=float)
Derived from:	Atom

Atomic masses.

type_array¶

Type:	np.ndarray(NA, dtype=object) array of str
Derived from:	Atom

Array of all the atomic symbols. It can be used to select certain atoms in a system.

charge_array¶

Type:	np.ndarray(N, dtype=float)
Derived from:	Atom

Array of the charges present on the atoms.

Example

Suppose you have a box of water defined by the System s, to select all oxygen atoms you can use the numpy selection rules:

>>> oxygens = s.type_array == 'O'
# oxygens is an array of booleans of length NA where
# each True corresponds to an oxygen atom i.e:
# [True, False, False, True, False, False]

You can use the oxygen array to access other properties:

>>> o_coordinates = s.r_array[oxygens]
>>> o_indices = np.arange(s.n_atoms)[oxygens]

bonds¶

Type:	np.ndarray((NBONDS, 2), dtype=int)
Derived from:	Molecule

An array of 2d indices that specify the index of the bonded atoms.

atom_export_array¶

Type:	np.ndarray(NA, dtype=object) array of dict
Derived from:	Atom

mol_export¶

Type:	np.ndarray(N, dtype=object) array of dict
Derived from:	Molecule

Export information relative to the molecule.

box_vectors¶

Type:	np.ndarray((3,3), dtype=float) or None

Those are the three vectors that define of the periodic box of the system.

Example

To define an orthorombic box of size 3, 4, 5 nm:

>>> np.array([[3.0, 0.0, 0.0],  # Vector a
              [0.0, 4.0, 0.0],  # Vector b
              [0.0, 0.0, 5.0]]) # Vector c

n_mol¶

Type:	int

Number of molecules.

n_atoms¶

Type:	int

Number of atoms.

mol_indices¶

Type:	np.ndarray(N, dtype=int)

Gives the starting index for each molecule in the atomic arrays. For example, in a System comprised of 3 water molecules:

>>> s.mol_indices
[0, 3, 6]
>>> s.type_array[0:3]
['O', 'H', 'H']

This array is used internally to retrieve all the Molecule derived data. Do not modify unless you know what you’re doing.

mol_n_atoms¶

Type:	np.ndarray(N, dtype=int)

Contains the number of atoms present in each molecule

add(mol)¶

Add the molecule mol to a System initialized through System.empty.

atom_to_molecule_indices(selection)¶

Given the indices over atoms, return the indices over molecules. If an atom is selected, all the containing molecule is selected too.

Parameters

selection: np.ndarray((N,), dtype=int) | np.ndarray((NATOMS,), dtype=book)

Either an index array or a boolean selection array over the atoms

Returns

np.ndarray((N,), dtype=int) an array of molecular indices.

copy()¶

Return a copy of the current system.

classmethod empty(n_mol, n_atoms, box_vectors=None)¶

Initialize an empty System containing n_mol Molecules and n_atoms Atoms. The molecules can be added by using the method add().

Example

How to initialize a system of 3 water molecules:

s = System.empty(3, 9)
for i in range(3):
    s.add(water)

classmethod from_arrays(**kwargs)¶

Initialize a System from its constituent arrays. It is the fastest way to initialize a System, well suited for reading one or more big System from data files.

Parameters

The following parameters are required:

• r_array
• type_array
• mol_indices

To further speed up the initialization process you optionally pass the other derived arrays:

• m_array
• mol_n_atoms
• atom_export_array
• mol_export

Example

Our classic example of 3 water molecules:

r_array = np.random.random((3, 9))
type_array = ['O', 'H', 'H', 'O', 'H', 'H', 'O', 'H', 'H']
mol_indices = [0, 3, 6]
System.from_arrays(r_array=r_array, type_array=type_array,
                   mol_indices=mol_indices)

classmethod from_json(string)¶

Create a System instance from a json string. Such strings are produced from the method chemlab.core.System.tojson()

get_molecule(index)¶

Get the Molecule instance corresponding to the molecule at index.

This method is useful to use Molecule properties that are generated each time, such as Molecule.formula and Molecule.center_of_mass

guess_bonds()¶

Guess the bonds between the molecules constituent of the system.

mol_to_atom_indices(indices)¶

Given the indices over molecules, return the indices over atoms.

Parameters

indices: np.ndarray((N,), dtype=int)

Array of integers between 0 and System.n_mol

Returns

np.ndarray((N,), dtype=int) the indices of all the atoms belonging to the selected molecules.

remove_atoms(indices)¶

Remove the atoms positioned at indices. The molecule containing the atom is removed as well.

If you have a system of 10 water molecules (and 30 atoms), if you remove the atoms at indices 0, 1 and 29 you will remove the first and last water molecules.

Parameters

indices: np.ndarray((N,), dtype=int)

Array of integers between 0 and System.n_atoms

remove_molecules(indices)¶

Remove the molecules positioned at indices.

For example, if you have a system comprised of 10 water molecules you can remove the first, fifth and nineth by using:

system.remove_molecules([0, 4, 8])

Parameters

indices: np.ndarray((N,), dtype=int)

Array of integers between 0 and System.n_mol

reorder_molecules(new_order)¶

Reorder the molecules in the system according to new_order.

Parameters

new_order: np.ndarray((NMOL,), dtype=int)

An array of integers containing the new order of the system.

sort()¶

Sort the molecules in the system according to their brute formula.

tojson()¶

Serialize a System instance using json.

See also

chemlab.core.System.from_json()

Routines to manipulate Systems¶

chemlab.core.subsystem_from_molecules(orig, selection)¶

Create a system from the orig system by picking the molecules specified in selection.

Parameters

orig: System

The system from where to extract the subsystem

selection: np.ndarray of int or np.ndarray(N) of bool

selection can be either a list of molecular indices to select or a boolean array whose elements are True in correspondence of the molecules to select (it is usually the result of a numpy comparison operation).

Example

In this example we can see how to select the molecules whose center of mass that is in the region of space x > 0.1:

s = System(...) # It is a set of 10 water molecules

select = []
for i range(s.n_mol):
   if s.get_molecule(i).center_of_mass[0] > 0.1:
       select.append(i)

subs = subsystem_from_molecules(s, np.ndarray(select)) 

Note

The API for operating on molecules is not yet fully developed. In the future there will be smarter ways to filter molecule attributes instead of looping and using System.get_molecule.

chemlab.core.subsystem_from_atoms(orig, selection)¶

Generate a subsystem containing the atoms specified by selection. If an atom belongs to a molecule, the whole molecule is selected.

Example

This function can be useful when selecting a part of a system based on positions. For example, in this snippet you can see how to select the part of the system (a set of molecules) whose x coordinates is bigger than 1.0 nm:

s = System(...)
subs = subsystem_from_atoms(s.r_array[0,:] > 1.0)

Parameters

orig: System

Original system.

selection: np.ndarray of int or np.ndarray(NA) of bool

A boolean array that is True when the ith atom has to be selected or a set of atomic indices to be included.

Returns:

A new System instance.

chemlab.core.merge_systems(sysa, sysb, bounding=0.2)¶

Generate a system by merging sysa and sysb.

Overlapping molecules are removed by cutting the molecules of sysa that have atoms near the atoms of sysb. The cutoff distance is defined by the bounding parameter.

Parameters

sysa: System

First system

sysb: System

Second system

bounding: float or False

Extra space used when cutting molecules in sysa to make space for sysb. If it is False, no overlap handling will be performed.

Routines to create Systems¶

chemlab.core.crystal(positions, molecules, group, cellpar=[1.0, 1.0, 1.0, 90, 90, 90], repetitions=[1, 1, 1])¶

Build a crystal from atomic positions, space group and cell parameters.

Parameters

positions: list of coordinates

A list of the atomic positions

molecules: list of Molecule

The molecules corresponding to the positions, the molecule will be translated in all the equivalent positions.

group: int | str

Space group given either as its number in International Tables or as its Hermann-Mauguin symbol.

repetitions:

Repetition of the unit cell in each direction

cellpar:

Unit cell parameters

This function was taken and adapted from the spacegroup module found in ASE.

The module spacegroup module was originally developed by Jesper Frills.

chemlab.core.random_lattice_box(mol_list, mol_number, size, spacing=<Mock object>)¶

Make a box by placing the molecules specified in mol_list on random points of an evenly spaced lattice.

Using a lattice automatically ensures that no two molecules are overlapping.

Parameters

mol_list: list of Molecule instances

A list of each kind of molecules to add to the system.

mol_number: list of int

The number of molecules to place for each kind.

size: np.ndarray((3,), float)

The box size in nm

spacing: np.ndarray((3,), float), [0.3 0.3 0.3]

The lattice spacing in nm.

Returns

A System instance.

Example

Typical box with 1000 water molecules randomly placed in a box of size [2.0 2.0 2.0]:

from chemlab.db import ChemlabDB

# Example water molecule
water = ChemlabDB().get('molecule', 'example.water')

s = random_water_box([water], [1000], [2.0, 2.0, 2.0])

The class IOHandler¶

class chemlab.io.handlers.IOHandler(fd)¶

Generic base class for file readers and writers.

The initialization function takes a file-like object fd, as an argument.

Subclasses can extend the methods __init__, read and write to implement their reading and writing routines.

Attributes

fd¶

can_read¶

Type:	list of str

A list of features that the handler can read.

can_write¶

Type:	list of str

A list of features that IOHandler can write.

check_feature(feature, readwrite)¶

Check if the feature is supported in the handler and raise an exception otherwise.

Parameters

feature: str

Identifier for a certain feature.

readwrite: “read” or “write”

Check if the feature is available for reading or writing.

read(feature, *args, **kwargs)¶

Read and return the feature feature. It should raise an ValueError if the feature is not present in the handler can_read attribute, use the method IOHandler.check_feature() to provide this behaviour.

Certain features may require additional arguments, and it is possible to pass those as well.

Example

Subclasses can reimplement this method to add functionality:

class XyzIO(IOHandler):
    can_read = ['molecule']

    def read(self, feature, *args, **kwargs):
        self.check_feature(feature, "read")
        if feature == 'molecule':
           # Do stuff
           return geom

write(feature, value, *args, **kwargs)¶

Same as read(). You have to pass also a value to write and you may pass any additional arguments.

Example

class XyzIO(IOHandler):
    can_write = ['molecule']

    def write(self, feature, value, *args, **kwargs):
        self.check_feature(feature, "write")
        if feature == 'molecule':
           # Do stuff
           return geom

Ready to use functions¶

The two following functions are a convenient way to quickly display and animate a System in chemlab.

chemlab.graphics.display_system(sys, style='vdw')¶

Display the system sys with the default viewer.

chemlab.graphics.display_trajectory(sys, times, coords_list, box_vectors=None, style='spheres')¶

Display the the system sys and instrument the trajectory viewer with frames information.

Parameters

sys: System

The system to be displayed

times: np.ndarray(NFRAMES, dtype=float)

The time corresponding to each frame. This is used only for feedback reasons.

coords_list: list of np.ndarray((NFRAMES, 3), dtype=float)

Atomic coordinates at each frame.

Builtin 3D viewers¶

Renderers and UIs¶