mBuild

A hierarchical, component based molecule builder

With just a few lines of mBuild code, you can assemble reusable components into complex molecular systems for molecular simulations.

• mBuild is designed to minimize or even eliminate the need to explicitly translate and orient components when building systems: you simply tell it to connect two pieces!

• mBuild keeps track of the system’s topology so you don’t have to worry about manually defining bonds when constructing chemically bonded structures from smaller components.

Example system

Components in dashed boxes are drawn by hand using, e.g., Avogadro or generated elsewhere. Each component is wrapped as a simple python class with user defined attachment sites, or ports. That’s the hard part! Now mBuild can do the rest. Each component further down the hierarchy is, again, a simple python class that describes which piece should connect to which piece.

Ultimately, complex systems structures can be created with just a line or two of code. Additionally, this approach seamlessly exposes tunable parameters within the hierarchy so you can actually create whole families of structures simply by adjusting a variable:

pattern = Random2DPattern(20)  # A random arrangement of 20 pieces on a 2D surface.
brush_layer = BrushLayer(chain_lenth=20, pattern=pattern, tile_x=3, tile_y=2)

Various sub-portions of this library may be independently distributed under different licenses. See those files for their specific terms.

Installation

Install with conda

$ conda install -c conda-forge mbuild

Alternatively you can add all the required channels to your .condarc after which you can simply install without specifying the channels:

$ conda config --add channels conda-forge
$ conda install mbuild

Note

The order in which channels are added matters: conda-forge should be the highest priority as a result of being added last. In your .condarc file, it should be listed first.

Note

The MDTraj website makes a nice case for using Python and in particular the Anaconda scientific python distribution to manage your numerical and scientific Python packages.

Install an editable version from source

To make your life easier, we recommend that you use a pre-packaged Python distribution like Miniconda in order to get all of the dependencies:

$ git clone https://github.com/mosdef-hub/mbuild
$ cd mbuild
$ conda env create -f environment-dev.yml
$ conda activate mbuild-dev
$ pip install -e .

Note

The above installation is for OSX and Unix. If you are using Windows, use environment-win.yml instead of environment-dev.yml

Install pre-commit

We use [pre-commit](https://pre-commit.com/) to automatically handle our code formatting and this package is included in the dev environment. With the mbuild-dev conda environment active, pre-commit can be installed locally as a git hook by running:

$ pre-commit install

And (optional) all files can be checked by running:

$ pre-commit run --all-files

Supported Python Versions

Python 3.6, 3.7 and 3.8 are officially supported, including testing during development and packaging. Support for Python 2.7 has been dropped as of August 6, 2019. Other Python versions, such as 3.9 and 3.5 and older, may successfully build and function but no guarantee is made.

Testing your installation

mBuild uses py.test for unit testing. To run them simply run the following while in the base directory:

$ conda install pytest
$ py.test -v

Building the documentation

mBuild uses sphinx to build its documentation. To build the docs locally, run the following while in the docs directory:

$ pip install -r requirements.txt
$ make html

Using mBuild with Docker

Docker and other containerization technologies allow entire applications and their dependencies to be packaged and distributed as images. This simplifies the installation process for the user and substantially reduces platform dependence (e.g., different compiler versions, libraries, etc). This section is a how-to guide for using mBuild with docker.

Prerequisites

A docker installation on your machine. This Docker installation documentation has instructions to get docker running on your machine. If you are not familiar with docker, the Internet is full of good tutorials like these from Docker curriculum and YouTube.

Jupyter Quick Start

After you have a working docker installation, use the following command to start a Jupyter notebook with mBuild and all the required dependencies:

$ docker pull mosdef/mbuild:latest
$ docker run -it --name mbuild -p 8888:8888 mosdef/mbuild:latest

If no command is provided to the container (as above), the container starts a jupyter-notebook at the (container) location /home/anaconda/data. To access the notebook, paste the notebook URL into a web browser on your computer. When you are finished, you can use control-C to exit the notebook as usual. The docker container will exit upon notebook shutdown.

Warning

Containers by nature are ephemeral, so filesystem changes (e.g., adding a new notebook) only persists until the end of the container’s lifecycle. If the container is removed, any changes or code additions will not persist. See the section below for persistent data.

Note

The -it flags connect your keyboard to the terminal running in the container. You may run the prior command without those flags, but be aware that the container will not respond to any keyboard input. In that case, you would need to use the docker ps and docker kill commands to shut down the container.

Persisting User Volumes

If you are using mBuild from a docker container and need access to data on your local machine or you wish to save files generated in the container, you can mount user volumes in the container. User volumes will provide a way to persist filesystem changes made to a container regardless of the container lifecycle. For example, you might want to create a directory called mbuild-notebooks on your local system, which will store all of your mBuild notebooks/code. In order to make that accessible from within the container (where the notebooks will be created/edited), use the following steps:

$ mkdir mbuild-notebooks
$ cd mbuild-notebooks/
$ docker run -it --name mbuild --mount type=bind,source=$(pwd),target=/home/anaconda/data -p 8888:8888  mosdef/mbuild:latest

You can easily mount a different directory from your local machine by changing source=$(pwd) to source=/path/to/my/favorite/directory.

Note

The --mount flag mounts a volume into the docker container. Here we use a bind mount to bind the current directory on our local filesystem to the /home/anaconda/data location in the container. The files you see in the jupyter-notebook browser window are those that exist on your local machine.

Warning

If you are using the container with jupyter notebooks you should use the /home/anaconda/data location as the mount point inside the container; this is the default notebook directory.

Running Python scripts in the container

Jupyter notebooks are a great way to explore new software and prototype code. However, when it comes time for production science, it is often better to work with python scripts. In order to execute a python script (example.py) that exists in the current working directory of your local machine, run:

$ docker run --mount type=bind,source=$(pwd),target=/home/anaconda/data mosdef/mbuild:latest "python data/test.py"

Note that once again we are bind mounting the current working directory to /home/anaconda/data. The command we pass to the container is python data/test.py. Note the prefix data/ to the script; this is because we enter the container in the home folder (/home/anaconda), but our script is located under /home/anaconda/data.

Warning

Do not bind mount to target=/home/anaconda. This will cause errors.

If you don’t require a Jupyter notebook, but just want a Python interpreter, you can run:

$ docker run --mount type=bind,source=$(pwd),target=/home/anaconda/data mosdef/mbuild:latest python

If you don’t need access to any local data, you can of course drop the --mount command:

$ docker run mosdef/mbuild:latest python

Different mBuild versions

Instead of using latest, you can use the image mosdef/mbuild:stable for most recent stable release of mBuild.

Cleaning Up

You can remove the container by using the following command.

$ docker container rm mbuild

The image will still exist on your machine. See the tutorials at the top of this page for more information.

Warning

You will not be able to start a second container with the same name (e.g., mbuild), until the first container has been removed.

Note

You do not need to name the container mbuild as shown in the above examples (--name mbuild). Docker will give each container a name automatically. To see all the containers on your machine, run docker ps -a.

Tutorials

The following tutorials are available either as html or interactive jupyter notebooks.

Methane: Compounds and bonds

Note: mBuild expects all distance units to be in nanometers.

The primary building block in mBuild is a Compound. Anything you construct will inherit from this class. Let’s start with some basic imports and initialization:

import mbuild as mb

class Methane(mb.Compound):
    def __init__(self):
        super(Methane, self).__init__()

Any Compound can contain other Compounds which can be added using its add() method. Compounds at the bottom of such a hierarchy are referred to as Particles. Note however, that this is purely semantic in mBuild to help clearly designate the bottom of a hierarchy.

import mbuild as mb

class Methane(mb.Compound):
    def __init__(self):
        super(Methane, self).__init__()
        carbon = mb.Particle(name='C')
        self.add(carbon, label='C[$]')

        hydrogen = mb.Particle(name='H', pos=[0.11, 0, 0])
        self.add(hydrogen, label='HC[$]')

By default a created Compound/Particle will be placed at 0, 0, 0 as indicated by its pos attribute. The Particle objects contained in a Compound, the bottoms of the hierarchy, can be referenced via the particles method which returns a generator of all Particle objects contained below the Compound in the hierarchy.

Note: All positions in mBuild are stored in nanometers.

Any part added to a Compound can be given an optional, descriptive string label. If the label ends with the characters [$], a list will be created in the labels. Any subsequent parts added to the Compound with the same label prefix will be appended to the list. In the example above, we’ve labeled the hydrogen as HC[$]. So this first part, with the label prefix HC, is now referenceable via self['HC'][0]. The next part added with the label HC[$] will be referenceable via self['HC'][1].

Now let’s use these styles of referencing to connect the carbon to the hydrogen. Note that for typical use cases, you will almost never have to explicitly define a bond when using mBuild - this is just to show you what’s going on under the hood:

import mbuild as mb

class Methane(mb.Compound):
    def __init__(self):
        super(Methane, self).__init__()
        carbon = mb.Particle(name='C')
        self.add(carbon, label='C[$]')

        hydrogen = mb.Particle(name='H', pos=[0.11, 0, 0])
        self.add(hydrogen, label='HC[$]')

        self.add_bond((self[0], self['HC'][0]))

As you can see, the carbon is placed in the zero index of self. The hydrogen could be referenced via self[1] but since we gave it a fancy label, it’s also referenceable via self['HC'][0].

Alright now that we’ve got the basics, let’s finish building our Methane and take a look at it:

import mbuild as mb

class Methane(mb.Compound):
    def __init__(self):
        super(Methane, self).__init__()
        carbon = mb.Particle(name='C')
        self.add(carbon, label='C[$]')

        hydrogen = mb.Particle(name='H', pos=[0.1, 0, -0.07])
        self.add(hydrogen, label='HC[$]')

        self.add_bond((self[0], self['HC'][0]))

        self.add(mb.Particle(name='H', pos=[-0.1, 0, -0.07]), label='HC[$]')
        self.add(mb.Particle(name='H', pos=[0, 0.1, 0.07]), label='HC[$]')
        self.add(mb.Particle(name='H', pos=[0, -0.1, 0.07]), label='HC[$]')

        self.add_bond((self[0], self['HC'][1]))
        self.add_bond((self[0], self['HC'][2]))
        self.add_bond((self[0], self['HC'][3]))

methane = Methane()
methane.visualize()

# Save to .mol2
methane.save('methane.mol2',overwrite=True)

Ethane: Reading from files, Ports and coordinate transforms

Note: mBuild expects all distance units to be in nanometers.

In this example, we’ll cover reading molecular components from files, introduce the concept of Ports and start using some coordinate transforms.

First, we need to import the mbuild package:

import mbuild as mb

As you probably noticed while creating your methane molecule in the last tutorial, manually adding Particles and Bonds to a Compound is a bit cumbersome. The easiest way to create small, reusable components, such as methyls, amines or monomers, is to hand draw them using software like Avogadro and export them as either a .pdb or .mol2 file (the file should contain connectivity information).

Let’s start by reading a methyl group from a .pdb file:

import mbuild as mb

ch3 = mb.load('ch3.pdb')
ch3.visualize()

Now let’s use our first coordinate transform to center the methyl at its carbon atom:

import mbuild as mb

ch3 = mb.load('ch3.pdb')
mb.translate(ch3, -ch3[0].pos)  # Move carbon to origin.

Now we have a methyl group loaded up and centered. In order to connect Compounds in mBuild, we make use of a special type of Compound: the Port. A Port is a Compound with two sets of four “ghost” Particles. In addition Ports have an anchor attribute which typically points to a particle that the Port should be associated with. In our methyl group, the Port should be anchored to the carbon atom so that we can now form bonds to this carbon:

import mbuild as mb

ch3 = mb.load('ch3.pdb')
mb.translate(ch3, -ch3[0].pos)  # Move carbon to origin.

port = mb.Port(anchor=ch3[0])
ch3.add(port, label='up')

# Place the port at approximately half a C-C bond length.
mb.translate(ch3['up'], [0, -0.07, 0])

By default, Ports are never output from the mBuild structure. However, it can be useful to look at a molecule with the Ports to check your work as you go:

ch3.visualize(show_ports=True)

Now we wrap the methyl group into a python class, so that we can reuse it as a component to build more complex molecules later.

import mbuild as mb

class CH3(mb.Compound):
    def __init__(self):
        super(CH3, self).__init__()

        mb.load('ch3.pdb', compound=self)
        mb.translate(self, -self[0].pos)  # Move carbon to origin.

        port = mb.Port(anchor=self[0])
        self.add(port, label='up')
        # Place the port at approximately half a C-C bond length.
        mb.translate(self['up'], [0, -0.07, 0])

When two Ports are connected, they are forced to overlap in space and their parent Compounds are rotated and translated by the same amount.

Note: If we tried to connect two of our methyls right now using only one set of four ghost particles, not only would the Ports overlap perfectly, but the carbons and hydrogens would also perfectly overlap - the 4 ghost atoms in the Port are arranged identically with respect to the other atoms. For example, if a Port and its direction is indicated by “<-”, forcing the port in <-CH3 to overlap with <-CH3 would just look like <-CH3 (perfectly overlapping atoms).

To solve this problem, every port contains a second set of 4 ghost atoms pointing in the opposite direction. When two Compounds are connected, the port that places the anchor atoms the farthest away from each other is chosen automatically to prevent this overlap scenario.

When <->CH3 and <->CH3 are forced to overlap, the CH3<->CH3 is automatically chosen.

Now the fun part: stick ’em together to create an ethane:

ethane = mb.Compound()

ethane.add(CH3(), label="methyl_1")
ethane.add(CH3(), label="methyl_2")
mb.force_overlap(move_this=ethane['methyl_1'],
                         from_positions=ethane['methyl_1']['up'],
                         to_positions=ethane['methyl_2']['up'])

Above, the force_overlap() function takes a Compound and then rotates and translates it such that two other Compounds overlap. Typically, as in this case, those two other Compounds are Ports - in our case, methyl1['up'] and methyl2['up'].

ethane.visualize()

ethane.visualize(show_ports=True)

Similarly, if we want to make ethane a reusable component, we need to wrap it into a python class.

import mbuild as mb

class Ethane(mb.Compound):
    def __init__(self):
        super(Ethane, self).__init__()

        self.add(CH3(), label="methyl_1")
        self.add(CH3(), label="methyl_2")
        mb.force_overlap(move_this=self['methyl_1'],
                         from_positions=self['methyl_1']['up'],
                         to_positions=self['methyl_2']['up'])

ethane = Ethane()
ethane.visualize()

# Save to .mol2
ethane.save('ethane.mol2', overwrite=True)

Monolayer: Complex hierarchies, patterns, tiling and writing to files

Note: mBuild expects all distance units to be in nanometers.

In this example, we’ll cover assembling more complex hierarchies of components using patterns, tiling and how to output systems to files. To illustrate these concepts, let’s build an alkane monolayer on a crystalline substrate.

First, let’s build our monomers and functionalized them with a silane group which we can then attach to the substrate. The Alkane example uses the polymer tool to combine CH2 and CH3 repeat units. You also have the option to cap the front and back of the chain or to leave a CH2 group with a dangling port. The Silane compound is a Si(OH)2 group with two ports facing out from the central Si. Lastly, we combine alkane with silane and add a label to AlkylSilane which points to, silane['down']. This allows us to reference it later using AlkylSilane['down'] rather than AlkylSilane['silane']['down'].

Note: In Compounds with multiple Ports, by convention, we try to label every Port successively as ‘up’, ‘down’, ‘left’, ‘right’, ‘front’, ‘back’ which should roughly correspond to their relative orientations. This is a bit tricky to enforce because the system is so flexible so use your best judgement and try to be consistent! The more components we collect in our library with the same labeling conventions, the easier it becomes to build ever more complex structures.

import mbuild as mb

from mbuild.lib.recipes import Alkane
from mbuild.lib.moieties import Silane


class AlkylSilane(mb.Compound):
    """A silane functionalized alkane chain with one Port. """
    def __init__(self, chain_length):
        super(AlkylSilane, self).__init__()

        alkane = Alkane(chain_length, cap_end=False)
        self.add(alkane, 'alkane')
        silane = Silane()
        self.add(silane, 'silane')
        mb.force_overlap(self['alkane'], self['alkane']['down'], self['silane']['up'])

        # Hoist silane port to AlkylSilane level.
        self.add(silane['down'], 'down', containment=False)

AlkylSilane(5).visualize()

Now let’s create a substrate to which we can later attach our monomers:

import mbuild as mb
from mbuild.lib.surfaces import Betacristobalite

surface = Betacristobalite()
tiled_surface = mb.lib.recipes.TiledCompound(surface, n_tiles=(2, 1, 1))

Here we’ve imported a beta-cristobalite surface from our component library. The TiledCompound tool allows you replicate any Compound in the x-, y- and z-directions by any number of times - 2, 1 and 1 for our case.

Next, let’s create our monomer and a hydrogen atom that we’ll place on unoccupied surface sites:

from mbuild.lib.atoms import H
alkylsilane = AlkylSilane(chain_length=10)
hydrogen = H()

Then we need to tell mBuild how to arrange the chains on the surface. This is accomplished with the “pattern” tools. Every pattern is just a collection of points. There are all kinds of patterns like spherical, 2D, regular, irregular etc. When you use the apply_pattern command, you effectively superimpose the pattern onto the host compound, mBuild figures out what the closest ports are to the pattern points and then attaches copies of the guest onto the binding sites identified by the pattern:

pattern = mb.Grid2DPattern(8, 8)  # Evenly spaced, 2D grid of points.

# Attach chains to specified binding sites. Other sites get a hydrogen.
chains, hydrogens = pattern.apply_to_compound(host=tiled_surface, guest=alkylsilane, backfill=hydrogen)

Also note the backfill optional argument which allows you to place a different compound on any unused ports. In this case we want to backfill with hydrogen atoms on every port without a chain.

monolayer = mb.Compound([tiled_surface, chains, hydrogens])
monolayer.visualize() # Warning: may be slow in IPython notebooks

# Save as .mol2 file
monolayer.save('monolayer.mol2', overwrite=True)

lib.recipes.monolayer.py wraps many these functions into a simple, general class for generating the monolayers, as shown below:

from mbuild.lib.recipes import Monolayer

monolayer = Monolayer(fractions=[1.0], chains=alkylsilane, backfill=hydrogen,
                      pattern=mb.Grid2DPattern(n=8, m=8),
                      surface=surface, tile_x=2, tile_y=1)
monolayer.visualize()

Point Particles: Basic system initialization

Note: mBuild expects all distance units to be in nanometers.

This tutorial focuses on the usage of basic system initialization operations, as applied to simple point particle systems (i.e., generic Lennard-Jones particles rather than specific atoms).

The code below defines several point particles in a cubic arrangement. Note, the color and radius associated with a Particle name can be set and passed to the visualize command. Colors are passed in hex format (see http://www.color-hex.com/color/bfbfbf).

import mbuild as mb

class MonoLJ(mb.Compound):
    def __init__(self):
        super(MonoLJ, self).__init__()
        lj_particle1 = mb.Particle(name='LJ', pos=[0, 0, 0])
        self.add(lj_particle1)

        lj_particle2 = mb.Particle(name='LJ', pos=[1, 0, 0])
        self.add(lj_particle2)

        lj_particle3 = mb.Particle(name='LJ', pos=[0, 1, 0])
        self.add(lj_particle3)

        lj_particle4 = mb.Particle(name='LJ', pos=[0, 0, 1])
        self.add(lj_particle4)

        lj_particle5 = mb.Particle(name='LJ', pos=[1, 0, 1])
        self.add(lj_particle5)

        lj_particle6 = mb.Particle(name='LJ', pos=[1, 1, 0])
        self.add(lj_particle6)

        lj_particle7 = mb.Particle(name='LJ', pos=[0, 1, 1])
        self.add(lj_particle7)

        lj_particle8 = mb.Particle(name='LJ', pos=[1, 1, 1])
        self.add(lj_particle8)


monoLJ = MonoLJ()
monoLJ.visualize()

While this would work for defining a single molecule or very small system, this would not be efficient for large systems. Instead, the clone and translate operator can be used to facilitate automation. Below, we simply define a single prototype particle (lj_proto), which we then copy and translate about the system.

Note, mBuild provides two different translate operations, “translate” and “translate_to”. “translate” moves a particle by adding the vector the original position, whereas “translate_to” move a particle to the specified location in space. Note, “translate_to” maintains the internal spatial relationships of a collection of particles by first shifting the center of mass of the collection of particles to the origin, then translating to the specified location. Since the lj_proto particle in this example starts at the origin, these two commands produce identical behavior.

import mbuild as mb

class MonoLJ(mb.Compound):
    def __init__(self):
        super(MonoLJ, self).__init__()
        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])

        for i in range(0,2):
            for j in range(0,2):
                for k in range(0,2):
                    lj_particle = mb.clone(lj_proto)
                    pos = [i,j,k]
                    lj_particle.translate(pos)
                    self.add(lj_particle)

monoLJ = MonoLJ()
monoLJ.visualize()

To simplify this process, mBuild provides several build-in patterning tools, where for example, Grid3DPattern can be used to perform this same operation. Grid3DPattern generates a set of points, from 0 to 1, which get stored in the variable “pattern”. We need only loop over the points in pattern, cloning, translating, and adding to the system. Note, because Grid3DPattern defines points between 0 and 1, they must be scaled based on the desired system size, i.e., pattern.scale(2).

import mbuild as mb

class MonoLJ(mb.Compound):
    def __init__(self):
        super(MonoLJ, self).__init__()
        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])

        pattern = mb.Grid3DPattern(2, 2, 2)
        pattern.scale(2)

        for pos in pattern:
            lj_particle = mb.clone(lj_proto)
            lj_particle.translate(pos)
            self.add(lj_particle)

monoLJ = MonoLJ()
monoLJ.visualize()

Larger systems can therefore be easily generated by toggling the values given to Grid3DPattern. Other patterns can also be generated using the same basic code, such as a 2D grid pattern:

import mbuild as mb

class MonoLJ(mb.Compound):
    def __init__(self):
        super(MonoLJ, self).__init__()
        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])

        pattern = mb.Grid2DPattern(5, 5)
        pattern.scale(5)

        for pos in pattern:
            lj_particle = mb.clone(lj_proto)
            lj_particle.translate(pos)
            self.add(lj_particle)

monoLJ = MonoLJ()
monoLJ.visualize()

Points on a sphere can be generated using SpherePattern. Points on a disk using DisKPattern, etc.

Note to show both simultaneously, we shift the x-coordinate of Particles in the sphere by -1 (i.e., pos[0]-=1.0) and +1 for the disk (i.e, pos[0]+=1.0).

import mbuild as mb

class MonoLJ(mb.Compound):
    def __init__(self):
        super(MonoLJ, self).__init__()
        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])

        pattern_sphere = mb.SpherePattern(200)
        pattern_sphere.scale(0.5)

        for pos in pattern_sphere:
            lj_particle = mb.clone(lj_proto)
            pos[0]-=1.0
            lj_particle.translate(pos)
            self.add(lj_particle)

        pattern_disk = mb.DiskPattern(200)
        pattern_disk.scale(0.5)
        for pos in pattern_disk:
            lj_particle = mb.clone(lj_proto)
            pos[0]+=1.0
            lj_particle.translate(pos)
            self.add(lj_particle)

monoLJ = MonoLJ()
monoLJ.visualize()

We can also take advantage of the hierachical nature of mBuild to accomplish the same task more cleanly. Below we create a component that corresponds to the sphere (class SphereLJ), and one that corresponds to the disk (class DiskLJ), and then instantiate and shift each of these individually in the MonoLJ component.

import mbuild as mb

class SphereLJ(mb.Compound):
    def __init__(self):
        super(SphereLJ, self).__init__()
        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])

        pattern_sphere = mb.SpherePattern(200)
        pattern_sphere.scale(0.5)

        for pos in pattern_sphere:
            lj_particle = mb.clone(lj_proto)
            lj_particle.translate(pos)
            self.add(lj_particle)

class DiskLJ(mb.Compound):
    def __init__(self):
        super(DiskLJ, self).__init__()
        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])

        pattern_disk = mb.DiskPattern(200)
        pattern_disk.scale(0.5)
        for pos in pattern_disk:
            lj_particle = mb.clone(lj_proto)
            lj_particle.translate(pos)
            self.add(lj_particle)


class MonoLJ(mb.Compound):
    def __init__(self):
        super(MonoLJ, self).__init__()

        sphere = SphereLJ();
        pos=[-1, 0, 0]
        sphere.translate(pos)
        self.add(sphere)

        disk = DiskLJ();
        pos=[1, 0, 0]
        disk.translate(pos)
        self.add(disk)


monoLJ = MonoLJ()
monoLJ.visualize()

Again, since mBuild is hierarchical, the pattern functions can be used to generate large systems of any arbitary component. For example, we can replicate the SphereLJ component on a regular array.

import mbuild as mb

class SphereLJ(mb.Compound):
    def __init__(self):
        super(SphereLJ, self).__init__()
        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])

        pattern_sphere = mb.SpherePattern(13)
        pattern_sphere.scale(0.1)

        for pos in pattern_sphere:
            lj_particle = mb.clone(lj_proto)
            lj_particle.translate(pos)
            self.add(lj_particle)
class MonoLJ(mb.Compound):
    def __init__(self):
        super(MonoLJ, self).__init__()
        sphere = SphereLJ();

        pattern = mb.Grid3DPattern(3, 3, 3)
        pattern.scale(2)

        for pos in pattern:
            lj_sphere = mb.clone(sphere)
            lj_sphere.translate_to(pos)
            #shift the particle so the center of mass
            #of the system is at the origin
            lj_sphere.translate([-5,-5,-5])

            self.add(lj_sphere)

monoLJ = MonoLJ()
monoLJ.visualize()

Several functions exist for rotating compounds. For example, the spin command allows a compound to be rotated, in place, about a specific axis (i.e., it considers the origin for the rotation to lie at the compound’s center of mass).

import mbuild as mb
import random
from numpy import pi


class CubeLJ(mb.Compound):
    def __init__(self):
        super(CubeLJ, self).__init__()
        lj_proto = mb.Particle(name='LJ', pos=[0, 0, 0])

        pattern = mb.Grid3DPattern(2, 2, 2)
        pattern.scale(0.2)

        for pos in pattern:
            lj_particle = mb.clone(lj_proto)
            lj_particle.translate(pos)
            self.add(lj_particle)

class MonoLJ(mb.Compound):
    def __init__(self):
        super(MonoLJ, self).__init__()
        cube_proto = CubeLJ();

        pattern = mb.Grid3DPattern(3, 3, 3)
        pattern.scale(2)
        rnd = random.Random()
        rnd.seed(123)

        for pos in pattern:
            lj_cube = mb.clone(cube_proto)
            lj_cube.translate_to(pos)
            #shift the particle so the center of mass
            #of the system is at the origin
            lj_cube.translate([-5,-5,-5])
            lj_cube.spin( rnd.uniform(0, 2 * pi), [1, 0, 0])
            lj_cube.spin(rnd.uniform(0, 2 * pi), [0, 1, 0])
            lj_cube.spin(rnd.uniform(0, 2 * pi), [0, 0, 1])

            self.add(lj_cube)

monoLJ = MonoLJ()
monoLJ.visualize()

Configurations can be dumped to file using the save command; this takes advantage of MDTraj and supports a range of file formats (see http://MDTraj.org).

#save as xyz file
monoLJ.save('output.xyz')
#save as mol2
monoLJ.save('output.mol2')

Building a Simple Alkane

The purpose of this tutorial is to demonstrate the construction of an alkane polymer and provide familiarity with many of the underlying functions in mBuild. Note that a robust polymer construction recipe already exists in mBuild, which will also be demonstrated at the end of the tutorial.

Setting up the monomer

The first step is to construct the basic repeat unit for the alkane, i.e., a \(CH_2\) group, similar to the construction of the \(CH_3\) monomer in the prior methane tutorial. Rather than importing the coordinates from a pdb file, as in the previous example, we will instead explicitly define them in the class. Recall that distance units are nm in mBuild.

import mbuild as mb

class CH2(mb.Compound):
    def __init__(self):
        super(CH2, self).__init__()
        # Add carbon
        self.add(mb.Particle(name='C', pos=[0,0,0]), label='C[$]')

        # Add hydrogens
        self.add(mb.Particle(name='H', pos=[-0.109, 0, 0.0]), label='HC[$]')
        self.add(mb.Particle(name='H', pos=[0.109, 0, 0.0]), label='HC[$]')

        # Add bonds between the atoms
        self.add_bond((self['C'][0], self['HC'][0]))
        self.add_bond((self['C'][0], self['HC'][1]))

        # Add ports anchored to the carbon
        self.add(mb.Port(anchor=self[0]), label='up')
        self.add(mb.Port(anchor=self[0]), label='down')

        # Move the ports approximately half a C-C bond length away from the carbon
        self['up'].translate([0, -0.154/2, 0])
        self['down'].translate([0, 0.154/2, 0])

monomer = CH2()
monomer.visualize(show_ports=True)

This configuration of the monomer is not a particularly realistic conformation. One could use this monomer to construct a polymer and then apply an energy minimization scheme, or, as we will demonstrate here, we can use mBuild’s rotation commands to provide a more realistic starting point.

Below, we use the same basic script, but now apply a rotation to the hydrogen atoms. Since the hydrogens start 180° apart and we know they should be ~109.5° apart, each should be rotated half of the difference closer to each other around the y-axis. Note that the rotation angle is given in radians. Similarly, the ports should be rotated around the x-axis by the same amount so that atoms can be added in a realistic orientation.

import numpy as np
import mbuild as mb

class CH2(mb.Compound):
    def __init__(self):
        super(CH2, self).__init__()
        # Add carbon
        self.add(mb.Particle(name='C', pos=[0,0,0]), label='C[$]')

        # Add hydrogens
        self.add(mb.Particle(name='H', pos=[-0.109, 0, 0.0]), label='HC[$]')
        self.add(mb.Particle(name='H', pos=[0.109, 0, 0.0]), label='HC[$]')

        # Rotate the hydrogens
        theta = 0.5 * (180 - 109.5) * np.pi / 180
        #mb.rotate(self['HC'][0], theta, around=[0, 1, 0])
        #mb.rotate(self['HC'][1], -theta, around=[0, 1, 0])
        self['HC'][0].rotate( theta, around=[0, 1, 0])
        self['HC'][1].rotate(-theta, around=[0, 1, 0])

        # Add bonds between the atoms
        self.add_bond((self['C'][0], self['HC'][0]))
        self.add_bond((self['C'][0], self['HC'][1]))

        # Add the ports and appropriately rotate them
        self.add(mb.Port(anchor=self[0]), label='up')
        self['up'].translate([0, -0.154/2, 0])
        self['up'].rotate(theta, around=[1, 0, 0])

        self.add(mb.Port(anchor=self[0]), label='down')
        self['down'].translate([0, 0.154/2, 0])
        self['down'].rotate(-theta, around=[1, 0, 0])

monomer = CH2()
monomer.visualize(show_ports=True)

Defining the polymerization class

With a basic monomer construct, we can now construct a polymer by connecting the ports together. Here, we first instantiate one instance of the CH2 class as 1ast_monomer, then use the clone function to make a copy. The force_overlap() function is used to connect the 'up' port from current_monomer to the 'down' port of last_mononer.

class AlkanePolymer(mb.Compound):
    def __init__(self):
        super(AlkanePolymer, self).__init__()
        last_monomer = CH2()
        self.add(last_monomer)
        for i in range(3):
            current_monomer = CH2()
            mb.force_overlap(move_this=current_monomer,
                             from_positions=current_monomer['up'],
                             to_positions=last_monomer['down'])
            self.add(current_monomer)
            last_monomer = current_monomer

polymer = AlkanePolymer()
polymer.visualize(show_ports=True)

Visualization of this structure demonstrates a problem; the polymer curls up on itself. This is a result of the fact that ports not only define the location in space, but also an orientation. This can be trivially fixed, by rotating the down port 180° around the y-axis.

We can also add a variable chain_length both to the for loop and init that will allow the length of the polymer to be adjusted when the class is instantiated.

import numpy as np
import mbuild as mb

class CH2(mb.Compound):
    def __init__(self):
        super(CH2, self).__init__()
         # Add carbons and hydrogens
        self.add(mb.Particle(name='C', pos=[0,0,0]), label='C[$]')
        self.add(mb.Particle(name='H', pos=[-0.109, 0, 0.0]), label='HC[$]')
        self.add(mb.Particle(name='H', pos=[0.109, 0, 0.0]), label='HC[$]')

        # rotate hydrogens
        theta = 0.5 * (180 - 109.5) * np.pi / 180
        self['HC'][0].rotate(theta, around=[0, 1, 0])
        self['HC'][1].rotate(-theta, around=[0, 1, 0])

        # Add bonds between the atoms
        self.add_bond((self['C'][0], self['HC'][0]))
        self.add_bond((self['C'][0], self['HC'][1]))

        # Add ports
        self.add(mb.Port(anchor=self[0]), label='up')
        self['up'].translate([0, -0.154/2, 0])
        self['up'].rotate(theta, around=[1, 0, 0])

        self.add(mb.Port(anchor=self[0]), label='down')
        self['down'].translate([0, 0.154/2, 0])
        self['down'].rotate(np.pi, [0, 1, 0])
        self['down'].rotate(-theta, around=[1, 0, 0])


class AlkanePolymer(mb.Compound):
    def __init__(self, chain_length=1):
        super(AlkanePolymer, self).__init__()
        last_monomer = CH2()
        self.add(last_monomer)
        for i in range (chain_length-1):
            current_monomer = CH2()

            mb.force_overlap(move_this=current_monomer,
                             from_positions=current_monomer['up'],
                             to_positions=last_monomer['down'])
            self.add(current_monomer)
            last_monomer=current_monomer

polymer = AlkanePolymer(chain_length=10)
polymer.visualize(show_ports=True)

Using mBuild’s Polymer Class

mBuild provides a prebuilt class to perform this basic functionality. Since it is designed to be more general, it takes as an argument not just the chain length, but also the monomer and the port labels (e.g., ‘up’ and ‘down’, since these labels are user defined).

polymer = mb.lib.recipes.Polymer(CH2(), 10, port_labels=('up', 'down'))
polymer.visualize()

Building a System of Alkanes

A system of alkanes can be constructed by simply cloning the polymer constructed above and translating and/or rotating the alkanes in space. mBuild provides many routines that can be used to create different patterns, to which the polymers can be shifted.

# create the polymer
polymer = mb.lib.recipes.Polymer(CH2(), 10, port_labels=('up', 'down'))

# the pattern we generate puts points in the xy-plane, so we'll rotate the polymer
# so that it is oriented normal to the xy-plane
polymer.rotate(np.pi/2, [1, 0, 0])

# define a compound to hold all the polymers
system = mb.Compound()

# create a pattern of points to fill a disk
# patterns are generated between 0 and 1,
# and thus need to be scaled to provide appropriate spacing
pattern_disk = mb.DiskPattern(50)
pattern_disk.scale(5)

# now clone the polymer and move it to the points in the pattern
for pos in pattern_disk:
    current_polymer = mb.clone(polymer)
    current_polymer.translate(pos)
    system.add(current_polymer)

system.visualize()

Other patterns can be used, e.g., the Grid3DPattern. We can also use the rotation commands to randomize the orientation.

import random

polymer = mb.lib.recipes.Polymer(CH2(), 10, port_labels=('up', 'down'))
system = mb.Compound()
polymer.rotate(np.pi/2, [1, 0, 0])

pattern_disk = mb.Grid3DPattern(5, 5, 5)
pattern_disk.scale(8.0)

for pos in pattern_disk:
    current_polymer = mb.clone(polymer)
    for around in [(1, 0, 0), (0, 1, 0), (0, 0, 1)]:  # rotate around x, y, and z
        current_polymer.rotate(random.uniform(0, np.pi), around)
    current_polymer.translate(pos)
    system.add(current_polymer)

system.visualize()

mBuild also provides an interface to PACKMOL, allowing the creation of a randomized configuration.

polymer = mb.lib.recipes.Polymer(CH2(), 5, port_labels=('up', 'down'))
system = mb.fill_box(polymer, n_compounds=100, overlap=1.5, box=[10,10,10])
system.visualize()

Variations

Rather than a linear chain, the Polymer class we wrote can be easily changed such that small perturbations are given to each port. To avoid accumulation of deviations from the equilibrium angle, we will clone an unperturbed monomer each time (i.e., monomer_proto) before applying a random variation.

We also define a variable delta, which will control the maximum amount of perturbation. Note that large values of delta may result in the chain overlapping itself, as mBuild does not currently include routines to exclude such overlaps.

import mbuild as mb

import random

class AlkanePolymer(mb.Compound):
    def __init__(self, chain_length=1, delta=0):
        super(AlkanePolymer, self).__init__()
        monomer_proto = CH2()
        last_monomer = CH2()
        last_monomer['down'].rotate(random.uniform(-delta,delta), [1, 0, 0])
        last_monomer['down'].rotate(random.uniform(-delta,delta), [0, 1, 0])
        self.add(last_monomer)
        for i in range(chain_length-1):
            current_monomer = mb.clone(monomer_proto)
            current_monomer['down'].rotate(random.uniform(-delta,delta), [1, 0, 0])
            current_monomer['down'].rotate(random.uniform(-delta,delta), [0, 1, 0])
            mb.force_overlap(move_this=current_monomer,
                             from_positions=current_monomer['up'],
                             to_positions=last_monomer['down'])
            self.add(current_monomer)
            last_monomer=current_monomer

polymer = AlkanePolymer(chain_length = 200, delta=0.4)
polymer.visualize()

Data Structures

The primary building blocks in an mBuild hierarchy inherit from the mbuild.Compound class. Compounds maintain an ordered set of children which are other Compounds. In addition, an independent, ordered dictionary of labels is maintained through which users can reference any other Compound in the hierarchy via descriptive strings. Every Compound knows its parent Compound, one step up in the hierarchy, and knows which Compounds reference it in their labels. mbuild.Port is a special type of Compound which are used internally to connect different Compounds using the equivalence transformations described below.

Compounds at the bottom of an mBuild hierarchy, the leaves of the tree, are referred to as Particles and can be instantiated as foo = mbuild.Particle(name='bar'). Note however, that this merely serves to illustrate that this Compound is at the bottom of the hierarchy; Particle is simply an alias for Compound which can be used to clarify the intended role of an object you are creating. The method mbuild.Compound.particles() traverses the hierarchy to the bottom and yields those Compounds. mbuild.Compound.root() returns the compound at the top of the hierarchy.

Compound

class mbuild.Compound(subcompounds=None, name=None, pos=None, charge=0.0, periodicity=None, box=None, element=None, port_particle=False)

A building block in the mBuild hierarchy.

Compound is the superclass of all composite building blocks in the mBuild hierarchy. That is, all composite building blocks must inherit from compound, either directly or indirectly. The design of Compound follows the Composite design pattern:

@book{DesignPatterns,
    author = "Gamma, Erich and Helm, Richard and Johnson, Ralph and
    Vlissides, John M.",
    title = "Design Patterns",
    subtitle = "Elements of Reusable Object-Oriented Software",
    year = "1995",
    publisher = "Addison-Wesley",
    note = "p. 395",
    ISBN = "0-201-63361-2",
}

with Compound being the composite, and Particle playing the role of the primitive (leaf) part, where Particle is in fact simply an alias to the Compound class.

Compound maintains a list of children (other Compounds contained within), and provides a means to tag the children with labels, so that the compounds can be easily looked up later. Labels may also point to objects outside the Compound’s containment hierarchy. Compound has built-in support for copying and deepcopying Compound hierarchies, enumerating particles or bonds in the hierarchy, proximity based searches, visualization, I/O operations, and a number of other convenience methods.

Parameters

subcompoundsmb.Compound or list of mb.Compound, optional, default=None

One or more compounds to be added to self.

namestr, optional, default=self.__class__.__name__

The type of Compound.

posnp.ndarray, shape=(3,), dtype=float, optional, default=[0, 0, 0]

The position of the Compound in Cartestian space

chargefloat, optional, default=0.0

Currently not used. Likely removed in next release.

periodicitytuple of bools, length=3, optional, default=None

Whether the Compound is periodic in the x, y, and z directions. If None is provided, the periodicity is set to (False, False, False) which is non-periodic in all directions.

port_particlebool, optional, default=False

Whether or not this Compound is part of a Port

boxmb.Box, optional

The simulation box containing the compound. Also accounts for the periodicity. Defaults to None which is treated as non-periodic.

element: str, optional, default=None

The one or two character element symbol

Attributes

bond_graphmb.BondGraph

Graph-like object that stores bond information for this Compound

childrenOrderedSet

Contains all children (other Compounds).

labelsOrderedDict

Labels to Compound/Atom mappings. These do not necessarily need not be in self.children.

parentmb.Compound

The parent Compound that contains this part. Can be None if this compound is the root of the containment hierarchy.

referrersset

Other compounds that reference this part with labels.

rigid_idint, default=None

Get the rigid_id of the Compound.

boundingboxmb.Box

The bounds (xmin, xmax, ymin, ymax, zmin, zmax) of particles in Compound

center

Get the cartesian center of the Compound based on its Particles.

contains_rigid

Return True if the Compound contains rigid bodies.

max_rigid_id

Return the maximum rigid body ID contained in the Compound.

n_particles

Return the number of Particles in the Compound.

n_bonds

Return the number of bonds in the Compound.

root

Get the Compound at the top of self’s hierarchy.

xyz

Return all particle coordinates in this compound.

xyz_with_ports

Return all particle coordinates in this compound including ports.

add(new_child, label=None, containment=True, replace=False, inherit_periodicity=None, inherit_box=False, reset_rigid_ids=True)

Add a part to the Compound.

Note:

This does not necessarily add the part to self.children but may instead be used to add a reference to the part to self.labels. See ‘containment’ argument.

Parameters

new_childmb.Compound or list-like of mb.Compound

The object(s) to be added to this Compound.

labelstr, optional, default None

A descriptive string for the part.

containmentbool, optional, default=True

Add the part to self.children.

replacebool, optional, default=True

Replace the label if it already exists.

inherit_periodicitybool, optional, default=True

Replace the periodicity of self with the periodicity of the Compound being added

inherit_box: bool, optional, default=False

Replace the box of self with the box of the Compound being added

reset_rigid_idsbool, optional, default=True

If the Compound to be added contains rigid bodies, reset the rigid_ids such that values remain distinct from rigid_ids already present in self. Can be set to False if attempting to add Compounds to an existing rigid body.

add_bond(particle_pair)

Add a bond between two Particles.

Parameters

particle_pairindexable object, length=2, dtype=mb.Compound

The pair of Particles to add a bond between

all_ports()

Return all Ports referenced by this Compound and its successors.

Returns

list of mb.Compound

A list of all Ports referenced by this Compound and its successors

ancestors()

Generate all ancestors of the Compound recursively.

Yields

mb.Compound

The next Compound above self in the hierarchy

available_ports()

Return all unoccupied Ports referenced by this Compound.

Returns

list of mb.Compound

A list of all unoccupied ports referenced by the Compound

bonds()

Return all bonds in the Compound and sub-Compounds.

Yields

tuple of mb.Compound

The next bond in the Compound

See also

bond_graph.edges_iter

Iterates over all edges in a BondGraph

property box

Get the box of the Compound.

Ports cannot have a box.

property center

Get the cartesian center of the Compound based on its Particles.

Returns

np.ndarray, shape=(3,), dtype=float

The cartesian center of the Compound based on its Particles

property charge

Get the charge of the Compound.

property contains_rigid

Return True if the Compound contains rigid bodies.

If the Compound contains any particle with a rigid_id != None then contains_rigid will return True. If the Compound has no children (i.e. the Compound resides at the bottom of the containment hierarchy) then contains_rigid will return False.

Returns

bool,

True if the Compound contains any particle with a rigid_id != None

Notes

The private variable ‘_check_if_contains_rigid_bodies’ is used to help cache the status of ‘contains_rigid’. If ‘_check_if_contains_rigid_bodies’ is False, then the rigid body containment of the Compound has not changed, and the particle tree is not traversed, boosting performance.

property element

Get the element of the Compound.

energy_minimize(forcefield='UFF', steps=1000, **kwargs)

Perform an energy minimization on a Compound.

Default behavior utilizes Open Babel to perform an energy minimization/geometry optimization on a Compound by applying a generic force field

Can also utilize OpenMM to energy minimize after atomtyping a Compound using Foyer to apply a forcefield XML file that contains valid SMARTS strings.

This function is primarily intended to be used on smaller components, with sizes on the order of 10’s to 100’s of particles, as the energy minimization scales poorly with the number of particles.

Parameters

stepsint, optional, default=1000

The number of optimization iterations

forcefieldstr, optional, default=’UFF’

The generic force field to apply to the Compound for minimization. Valid options are ‘MMFF94’, ‘MMFF94s’, ‘’UFF’, ‘GAFF’, ‘Ghemical’. Please refer to the Open Babel documentation when considering your choice of force field. Utilizing OpenMM for energy minimization requires a forcefield XML file with valid SMARTS strings. Please refer to OpenMM docs for more information.

Other Parameters

algorithmstr, optional, default=’cg’

The energy minimization algorithm. Valid options are ‘steep’, ‘cg’, and ‘md’, corresponding to steepest descent, conjugate gradient, and equilibrium molecular dynamics respectively. For _energy_minimize_openbabel

scale_bondsfloat, optional, default=1

Scales the bond force constant (1 is completely on). For _energy_minimize_openmm

scale_anglesfloat, optional, default=1

Scales the angle force constant (1 is completely on) For _energy_minimize_openmm

scale_torsionsfloat, optional, default=1

Scales the torsional force constants (1 is completely on) For _energy_minimize_openmm Note: Only Ryckaert-Bellemans style torsions are currently supported

scale_nonbondedfloat, optional, default=1

Scales epsilon (1 is completely on) For _energy_minimize_openmm

References

If using _energy_minimize_openmm(), please cite:

Eastman2013

P. Eastman, M. S. Friedrichs, J. D. Chodera, R. J. Radmer, C. M. Bruns, J. P. Ku, K. A. Beauchamp, T. J. Lane, L.-P. Wang, D. Shukla, T. Tye, M. Houston, T. Stich, C. Klein, M. R. Shirts, and V. S. Pande. “OpenMM 4: A Reusable, Extensible, Hardware Independent Library for High Performance Molecular Simulation.” J. Chem. Theor. Comput. 9(1): 461-469. (2013).

If using _energy_minimize_openbabel(), please cite:

OBoyle2011

O’Boyle, N.M.; Banck, M.; James, C.A.; Morley, C.; Vandermeersch, T.; Hutchison, G.R. “Open Babel: An open chemical toolbox.” (2011) J. Cheminf. 3, 33

OpenBabel

Open Babel, version X.X.X http://openbabel.org, (installed Month Year)

If using the ‘MMFF94’ force field please also cite the following:

Halgren1996a

T.A. Halgren, “Merck molecular force field. I. Basis, form, scope, parameterization, and performance of MMFF94.” (1996) J. Comput. Chem. 17, 490-519

Halgren1996b

T.A. Halgren, “Merck molecular force field. II. MMFF94 van der Waals and electrostatic parameters for intermolecular interactions.” (1996) J. Comput. Chem. 17, 520-552

Halgren1996c

T.A. Halgren, “Merck molecular force field. III. Molecular geometries and vibrational frequencies for MMFF94.” (1996) J. Comput. Chem. 17, 553-586

Halgren1996d

T.A. Halgren and R.B. Nachbar, “Merck molecular force field. IV. Conformational energies and geometries for MMFF94.” (1996) J. Comput. Chem. 17, 587-615

Halgren1996e

T.A. Halgren, “Merck molecular force field. V. Extension of MMFF94 using experimental data, additional computational data, and empirical rules.” (1996) J. Comput. Chem. 17, 616-641

If using the ‘MMFF94s’ force field please cite the above along with:

Halgren1999

T.A. Halgren, “MMFF VI. MMFF94s option for energy minimization studies.” (1999) J. Comput. Chem. 20, 720-729

If using the ‘UFF’ force field please cite the following:

Rappe1992

Rappe, A.K., Casewit, C.J., Colwell, K.S., Goddard, W.A. III, Skiff, W.M. “UFF, a full periodic table force field for molecular mechanics and molecular dynamics simulations.” (1992) J. Am. Chem. Soc. 114, 10024-10039

If using the ‘GAFF’ force field please cite the following:

Wang2004

Wang, J., Wolf, R.M., Caldwell, J.W., Kollman, P.A., Case, D.A. “Development and testing of a general AMBER force field” (2004) J. Comput. Chem. 25, 1157-1174

If using the ‘Ghemical’ force field please cite the following:

Hassinen2001

T. Hassinen and M. Perakyla, “New energy terms for reduced protein models implemented in an off-lattice force field” (2001) J. Comput. Chem. 22, 1229-1242

from_parmed(structure, coords_only=False, infer_hierarchy=True)

Extract atoms and bonds from a pmd.Structure.

Will create sub-compounds for every chain if there is more than one and sub-sub-compounds for every residue.

Parameters

structurepmd.Structure

The structure to load.

coords_onlybool

Set preexisting atoms in compound to coordinates given by structure.

infer_hierarchybool, optional, default=True

If true, infer compound hierarchy from chains and residues

from_pybel(pybel_mol, use_element=True, coords_only=False, infer_hierarchy=True, ignore_box_warn=False)

Create a Compound from a Pybel.Molecule.

Parameters

pybel_mol: pybel.Molecule

use_elementbool, default True

If True, construct mb Particles based on the pybel Atom’s element. If False, construcs mb Particles based on the pybel Atom’s type

coords_onlybool, default False

Set preexisting atoms in compound to coordinates given by structure. Note: Not yet implemented, included only for parity with other conversion functions

infer_hierarchybool, optional, default=True

If True, infer hierarchy from residues

ignore_box_warnbool, optional, default=False

If True, ignore warning if no box is present.

See also

mbuild.conversion.from_pybel

from_trajectory(traj, frame=- 1, coords_only=False, infer_hierarchy=True)

Extract atoms and bonds from a md.Trajectory.

Will create sub-compounds for every chain if there is more than one and sub-sub-compounds for every residue.

Parameters

trajmdtraj.Trajectory

The trajectory to load.

frameint, optional, default=-1 (last)

The frame to take coordinates from.

coords_onlybool, optional, default=False

Only read coordinate information

infer_hierarchybool, optional, default=True

If True, infer compound hierarchy from chains and residues

See also

mbuild.conversion.from_trajectory

generate_bonds(name_a, name_b, dmin, dmax)

Add Bonds between all pairs of types a/b within [dmin, dmax].

Parameters

name_astr

The name of one of the Particles to be in each bond

name_bstr

The name of the other Particle to be in each bond

dminfloat

The minimum distance between Particles for considering a bond

dmaxfloat

The maximum distance between Particles for considering a bond

get_boundingbox()

Compute the bounding box of the compound.

Compute and store the rectangular bounding box of the Compound.

Returns

mb.Box

The bounding box for this Compound.

Notes

Triclinic bounding boxes are supported, but only for Compounds that are generated from mb.Lattice’s and the resulting mb.Lattice.populate method

get_smiles()

Get SMILES string for compound.

Bond order is guessed with pybel and may lead to incorrect SMILES strings.

Returns

smiles_string: str

label_rigid_bodies(discrete_bodies=None, rigid_particles=None)

Designate which Compounds should be treated as rigid bodies.

If no arguments are provided, this function will treat the compound as a single rigid body by providing all particles in self with the same rigid_id. If discrete_bodies is not None, each instance of a Compound with a name found in discrete_bodies will be treated as a unique rigid body. If rigid_particles is not None, only Particles (Compounds at the bottom of the containment hierarchy) matching this name will be considered part of the rigid body.

Parameters

discrete_bodiesstr or list of str, optional, default=None

Name(s) of Compound instances to be treated as unique rigid bodies. Compound instances matching this (these) name(s) will be provided with unique rigid_ids

rigid_particlesstr or list of str, optional, default=None

Name(s) of Compound instances at the bottom of the containment hierarchy (Particles) to be included in rigid bodies. Only Particles matching this (these) name(s) will have their rigid_ids altered to match the rigid body number.

Examples

Creating a rigid benzene

>>> import mbuild as mb
>>> from mbuild.utils.io import get_fn
>>> benzene = mb.load(get_fn('benzene.mol2'))
>>> benzene.label_rigid_bodies()

Creating a semi-rigid benzene, where only the carbons are treated as a rigid body

>>> import mbuild as mb
>>> from mbuild.utils.io import get_fn
>>> benzene = mb.load(get_fn('benzene.mol2'))
>>> benzene.label_rigid_bodies(rigid_particles='C')

Create a box of rigid benzenes, where each benzene has a unique rigid body ID.

>>> import mbuild as mb
>>> from mbuild.utils.io import get_fn
>>> benzene = mb.load(get_fn('benzene.mol2'))
>>> benzene.name = 'Benzene'
>>> filled = mb.fill_box(benzene,
...                      n_compounds=10,
...                      box=[0, 0, 0, 4, 4, 4])
>>> filled.label_rigid_bodies(distinct_bodies='Benzene')

Create a box of semi-rigid benzenes, where each benzene has a unique rigid body ID and only the carbon portion is treated as rigid.

>>> import mbuild as mb
>>> from mbuild.utils.io import get_fn
>>> benzene = mb.load(get_fn('benzene.mol2'))
>>> benzene.name = 'Benzene'
>>> filled = mb.fill_box(benzene,
...                      n_compounds=10,
...                      box=[0, 0, 0, 4, 4, 4])
>>> filled.label_rigid_bodies(distinct_bodies='Benzene',
...                           rigid_particles='C')

property max_rigid_id

Return the maximum rigid body ID contained in the Compound.

This is usually used by compound.root to determine the maximum rigid_id in the containment hierarchy.

Returns

int or None

The maximum rigid body ID contained in the Compound. If no rigid body IDs are found, None is returned

property maxs

Return the maximum x, y, z coordinate of any particle in this compound.

min_periodic_distance(xyz0, xyz1)

Vectorized distance calculation considering minimum image.

Only implemented for orthorhombic simulation boxes.

Parameters

xyz0np.ndarray, shape=(3,), dtype=float

Coordinates of first point

xyz1np.ndarray, shape=(3,), dtype=float

Coordinates of second point

Returns

float

Vectorized distance between the two points following minimum image convention

property mins

Return the mimimum x, y, z coordinate of any particle in this compound.

property n_bonds

Return the number of bonds in the Compound.

Returns

int

The number of bonds in the Compound

property n_particles

Return the number of Particles in the Compound.

Returns

int,

The number of Particles in the Compound

particles(include_ports=False)

Return all Particles of the Compound.

Parameters

include_portsbool, optional, default=False

Include port particles

Yields

mb.Compound

The next Particle in the Compound

particles_by_element(element)

Return all Particles of the Compound with a specific element.

Parameters

namestr or ele.Element

element abbreviation or element

Yields

mb.Compound

The next Particle in the Compound with the user-specified element

particles_by_name(name)

Return all Particles of the Compound with a specific name.

Parameters

namestr

Only particles with this name are returned

Yields

mb.Compound

The next Particle in the Compound with the user-specified name

particles_in_range(compound, dmax, max_particles=20, particle_kdtree=None, particle_array=None)

Find particles within a specified range of another particle.

Parameters

compoundmb.Compound

Reference particle to find other particles in range of

dmaxfloat

Maximum distance from ‘compound’ to look for Particles

max_particlesint, optional, default=20

Maximum number of Particles to return

particle_kdtreemb.PeriodicCKDTree, optional

KD-tree for looking up nearest neighbors. If not provided, a KD- tree will be generated from all Particles in self

particle_arraynp.ndarray, shape=(n,), dtype=mb.Compound, optional

Array of possible particles to consider for return. If not provided, this defaults to all Particles in self

Returns

np.ndarray, shape=(n,), dtype=mb.Compound

Particles in range of compound according to user-defined limits

See also

periodic_kdtree.PerioidicCKDTree

mBuild implementation of kd-trees

scipy.spatial.ckdtree

Further details on kd-trees

property periodicity

Get the periodicity of the Compound.

property pos

Get the position of the Compound.

If the Compound contains children, returns the center.

The position of a Compound containing children can’t be set.

referenced_ports()

Return all Ports referenced by this Compound.

Returns

list of mb.Compound

A list of all ports referenced by the Compound

remove(objs_to_remove)

Remove children from the Compound cleanly.

Parameters

objs_to_removemb.Compound or list of mb.Compound

The Compound(s) to be removed from self

remove_bond(particle_pair)

Delete a bond between a pair of Particles.

Parameters

particle_pairindexable object, length=2, dtype=mb.Compound

The pair of Particles to remove the bond between

property rigid_id

Get the rigid_id of the Compound.

rigid_particles(rigid_id=None)

Generate all particles in rigid bodies.

If a rigid_id is specified, then this function will only yield particles with a matching rigid_id.

Parameters

rigid_idint, optional

Include only particles with this rigid body ID

Yields

mb.Compound

The next particle with a rigid_id that is not None, or the next particle with a matching rigid_id if specified

property root

Get the Compound at the top of self’s hierarchy.

Returns

mb.Compound

The Compound at the top of self’s hierarchy

rotate(theta, around)

Rotate Compound around an arbitrary vector.

Parameters

thetafloat

The angle by which to rotate the Compound, in radians.

aroundnp.ndarray, shape=(3,), dtype=float

The vector about which to rotate the Compound.

save(filename, show_ports=False, forcefield_name=None, forcefield_files=None, forcefield_debug=False, box=None, overwrite=False, residues=None, combining_rule='lorentz', foyer_kwargs=None, **kwargs)

Save the Compound to a file.

Parameters

filenamestr

Filesystem path in which to save the trajectory. The extension or prefix will be parsed and control the format. Supported extensions: ‘hoomdxml’, ‘gsd’, ‘gro’, ‘top’, ‘lammps’, ‘lmp’, ‘mcf’

show_portsbool, optional, default=False

Save ports contained within the compound.

forcefield_filesstr, optional, default=None

Apply a forcefield to the output file using a forcefield provided by the foyer package.

forcefield_namestr, optional, default=None

Apply a named forcefield to the output file using the foyer package, e.g. ‘oplsaa’. Foyer forcefields

forcefield_debugbool, optional, default=False

Choose verbosity level when applying a forcefield through foyer. Specifically, when missing atom types in the forcefield xml file, determine if the warning is condensed or verbose.

boxmb.Box, optional, default=self.boundingbox (with buffer)

Box information to be written to the output file. If ‘None’, a bounding box is used with 0.25nm buffers at each face to avoid overlapping atoms.

overwritebool, optional, default=False

Overwrite if the filename already exists

residuesstr of list of str

Labels of residues in the Compound. Residues are assigned by checking against Compound.name.

combining_rulestr, optional, default=’lorentz’

Specify the combining rule for nonbonded interactions. Only relevant when the foyer package is used to apply a forcefield. Valid options are ‘lorentz’ and ‘geometric’, specifying Lorentz-Berthelot and geometric combining rules respectively.

foyer_kwargsdict, optional, default=None

Keyword arguments to provide to foyer.Forcefield.apply. Depending on the file extension these will be passed to either write_gsd, write_hoomdxml, write_lammpsdata, write_mcf, or parmed.Structure.save. See parmed structure documentation

Other Parameters

ref_distancefloat, optional, default=1.0

Normalization factor used when saving to .gsd and .hoomdxml formats for converting distance values to reduced units.

ref_energyfloat, optional, default=1.0

Normalization factor used when saving to .gsd and .hoomdxml formats for converting energy values to reduced units.

ref_massfloat, optional, default=1.0

Normalization factor used when saving to .gsd and .hoomdxml formats for converting mass values to reduced units.

atom_style: str, default=’full’

Defines the style of atoms to be saved in a LAMMPS data file. The following atom styles are currently supported: ‘full’, ‘atomic’, ‘charge’, ‘molecular’ See LAMMPS atom style documentation for more information.

unit_style: str, default=’real’

Defines to unit style to be save in a LAMMPS data file. Defaults to ‘real’ units. Current styles are supported: ‘real’, ‘lj’. See LAMMPS unit style documentation_ for more information.

See also

conversion.save

Main saver logic

formats.gsdwrite.write_gsd

Write to GSD format

formats.hoomdxml.write_hoomdxml

Write to Hoomd XML format

formats.xyzwriter.write_xyz

Write to XYZ format

formats.lammpsdata.write_lammpsdata

Write to LAMMPS data format

formats.cassandramcf.write_mcf

Write to Cassandra MCF format

formats.json_formats.compound_to_json

Write to a json file

Notes

When saving the compound as a json, only the following arguments are used: * filename * show_ports

spin(theta, around)

Rotate Compound in place around an arbitrary vector.

Parameters

thetafloat

The angle by which to rotate the Compound, in radians.

aroundnp.ndarray, shape=(3,), dtype=float

The axis about which to spin the Compound.

successors()

Yield Compounds below self in the hierarchy.

Yields

mb.Compound

The next Particle below self in the hierarchy

to_intermol(molecule_types=None)

Create an InterMol system from a Compound.

Parameters

molecule_typeslist or tuple of subclasses of Compound

Returns

intermol_systemintermol.system.System

See also

mbuild.conversion.to_intermol

to_networkx(names_only=False)

Create a NetworkX graph representing the hierarchy of a Compound.

Parameters

names_onlybool, optional, default=False

Store only the names of the compounds in the graph, appended with their IDs, for distinction even if they have the same name. When set to False, the default behavior, the nodes are the compounds themselves.

Returns

Gnetworkx.DiGraph

See also

mbuild.conversion.to_networkx

mbuild.bond_graph

Notes

This digraph is not the bondgraph of the compound.

to_parmed(box=None, title='', residues=None, show_ports=False, infer_residues=False)

Create a ParmEd Structure from a Compound.

Parameters

boxmb.Box, optional, default=self.boundingbox (with buffer)

Box information to be used when converting to a Structure. If ‘None’, self.box is used. If self.box is None, a bounding box is used with 0.5 nm buffer in each dimension to avoid overlapping atoms.

titlestr, optional, default=self.name

Title/name of the ParmEd Structure

residuesstr of list of str

Labels of residues in the Compound. Residues are assigned by checking against Compound.name.

show_portsboolean, optional, default=False

Include all port atoms when converting to a Structure.

infer_residuesbool, optional, default=False

Attempt to assign residues based on names of children.

Returns

parmed.structure.Structure

ParmEd Structure object converted from self

See also

mbuild.conversion.to_parmed

parmed.structure.Structure

Details on the ParmEd Structure object

to_pybel(box=None, title='', residues=None, show_ports=False, infer_residues=False)

Create a pybel.Molecule from a Compound.

Parameters

boxmb.Box, def None

titlestr, optional, default=self.name

Title/name of the ParmEd Structure

residuesstr of list of str

Labels of residues in the Compound. Residues are assigned by checking against Compound.name.

show_portsboolean, optional, default=False

Include all port atoms when converting to a Structure.

infer_residuesbool, optional, default=False

Attempt to assign residues based on names of children

Returns

pybel.Molecule

See also

mbuild.conversion.to_pybel

Notes

Most of the mb.Compound is first converted to openbabel.OBMol And then pybel creates a pybel.Molecule from the OBMol Bond orders are assumed to be 1 OBMol atom indexing starts at 1, with spatial dimension Angstrom

to_trajectory(show_ports=False, chains=None, residues=None, box=None)

Convert to an md.Trajectory and flatten the compound.

Parameters

show_portsbool, optional, default=False

Include all port atoms when converting to trajectory.

chainsmb.Compound or list of mb.Compound

Chain types to add to the topology

residuesstr of list of str

Labels of residues in the Compound. Residues are assigned by checking against Compound.name.

boxmb.Box, optional, default=self.boundingbox (with buffer)

Box information to be used when converting to a Trajectory. If ‘None’, self.box is used. If self.box is None, a bounding box is used with a 0.5 nm buffer in each dimension to avoid overlapping atoms.

Returns

trajectorymd.Trajectory

See also

_to_topology

translate(by)

Translate the Compound by a vector.

Parameters

bynp.ndarray, shape=(3,), dtype=float

translate_to(pos)

Translate the Compound to a specific position.

Parameters

posnp.ndarray, shape=3(,), dtype=float

unlabel_rigid_bodies()

Remove all rigid body labels from the Compound.

update_coordinates(filename, update_port_locations=True)

Update the coordinates of this Compound from a file.

Parameters

filenamestr

Name of file from which to load coordinates. Supported file types are the same as those supported by load()

update_port_locationsbool, optional, default=True

Update the locations of Ports so that they are shifted along with their anchor particles. Note: This conserves the location of Ports with respect to the anchor Particle, but does not conserve the orientation of Ports with respect to the molecule as a whole.

See also

load

Load coordinates from a file

visualize(show_ports=False, backend='py3dmol', color_scheme={})

Visualize the Compound using py3dmol (default) or nglview.

Allows for visualization of a Compound within a Jupyter Notebook.

Parameters

show_portsbool, optional, default=False

Visualize Ports in addition to Particles

backendstr, optional, default=’py3dmol’

Specify the backend package to visualize compounds Currently supported: py3dmol, nglview

color_schemedict, optional

Specify coloring for non-elemental particles keys are strings of the particle names values are strings of the colors i.e. {‘_CGBEAD’: ‘blue’}

property xyz

Return all particle coordinates in this compound.

Returns

posnp.ndarray, shape=(n, 3), dtype=float

Array with the positions of all particles.

property xyz_with_ports

Return all particle coordinates in this compound including ports.

Returns

posnp.ndarray, shape=(n, 3), dtype=float

Array with the positions of all particles and ports.

Port

class mbuild.Port(anchor=None, orientation=None, separation=0)

A set of four ghost Particles used to connect parts.

Parameters

anchormb.Particle, optional, default=None

A Particle associated with the port. Used to form bonds.

orientationarray-like, shape=(3,), optional, default=[0, 1, 0]

Vector along which to orient the port

separationfloat, optional, default=0

Distance to shift port along the orientation vector from the anchor particle position. If no anchor is provided, the port will be shifted from the origin.

Attributes

anchormb.Particle, optional, default=None

A Particle associated with the port. Used to form bonds.

upmb.Compound

Collection of 4 ghost particles used to perform equivalence transforms. Faces the opposite direction as self[‘down’].

downmb.Compound

Collection of 4 ghost particles used to perform equivalence transforms. Faces the opposite direction as self[‘up’].

usedbool

Status of whether a port has been occupied following an equivalence transform.

property access_labels

List labels used to access the Port.

Returns

list of str

Strings that can be used to access this Port relative to self.root

property center

Get the cartesian center of the Port.

property direction

Get the unit vector pointing in the ‘direction’ of the Port.

property separation

Get the distance between a port and its anchor particle.

If the port has no anchor particle, returns None.

update_orientation(orientation)

Change the direction between a port and its anchor particle.

orientationarray-like, shape=(3,), required

Vector along which to orient the port

update_separation(separation)

Change the distance between a port and its anchor particle.

separationfloat, required

Distance to shift port along the orientation vector from the anchor particle position. If no anchor is provided, the port will be shifted from the origin.

Box

class mbuild.Box(lengths, angles=None, precision=None)

A box representing the bounds of the system.

Parameters

lengthslist-like, shape=(3,), dtype=float

Lengths of the edges of the box.

angleslist-like, shape=(3,), dtype=float, default=None

Angles (in degrees) that define the tilt of the edges of the box. If None is given, angles are assumed to be [90.0, 90.0, 90.0]. These are also known as alpha, beta, gamma in the crystallography community.

precisionint, optional, default=None

Control the precision of the floating point representation of box attributes. If none provided, the default is 6 decimals.

Notes

Box vectors are expected to be provided in row-major format.

Attributes

vectorsnp.ndarray, shape=(3,3), dtype=float

Box representation as a 3x3 matrix.

lengthstuple, shape=(3,), dtype=float

Lengths of the box.

anglestuple, shape=(3,), dtype=float

Angles defining the tilt of the box (alpha, beta, gamma).

Lxfloat

Length in the x direction.

Lyfloat

Length in the y direction.

Lzfloat

Length in the z direction.

xyfloat

Tilt factor xy of the box.

xzfloat

Tilt factor xz of the box.

yzfloat

Tilt factor yz of the box.

precisionint

Amount of decimals to represent floating point values.

property Lx

Length in the x direction.

property Ly

Length in the y direction.

property Lz

Length in the z direction.

property angles

Angles defining the tilt of the box (alpha, beta, gamma).

property box_parameters

Lengths and tilt factors of the box.

property bravais_parameters

Return the Box representation as Bravais lattice parameters.

Based on the box vectors, return the parameters to describe the box in terms of the Bravais lattice parameters:

a,b,c = the edges of the Box alpha, beta, gamma = angles(tilt) of the parallelepiped, in degrees

Returns

parameterstuple of floats,

(a, b, c, alpha, beta, gamma)

classmethod from_lengths_angles(lengths, angles, precision=None)

Generate a box from lengths and angles.

classmethod from_lengths_tilt_factors(lengths, tilt_factors=None, precision=None)

Generate a box from box lengths and tilt factors.

classmethod from_lo_hi_tilt_factors(lo, hi, tilt_factors, precision=None)

Generate a box from a lo, hi convention and tilt factors.

classmethod from_mins_maxs_angles(mins, maxs, angles, precision=None)

Generate a box from min/max distance calculations and angles.

classmethod from_uvec_lengths(uvec, lengths, precision=None)

Generate a box from unit vectors and lengths.

classmethod from_vectors(vectors, precision=None)

Generate a box from box vectors.

property lengths

Lengths of the box.

property precision

Amount of decimals to represent floating point values.

property tilt_factors

Return the 3 tilt_factors (xy, xz, yz) of the box.

property vectors

Box representation as a 3x3 matrix.

property xy

Tilt factor xy of the box.

property xz

Tilt factor xz of the box.

property yz

Tilt factor yz of the box.

Lattice

class mbuild.Lattice(lattice_spacing=None, lattice_vectors=None, lattice_points=None, angles=None)

Develop crystal structure from user defined inputs.

Lattice, the abstract building block of a crystal cell. Once defined by the user, the lattice can then be populated with Compounds and replicated as many cell lengths desired in 3D space.

A Lattice is defined through the Bravais lattice definitions. With edge vectors a1, a2, a3; lattice spacing a,b,c; and lattice points at unique fractional positions between 0-1 in 3 dimensions. This encapsulates distance, area, volume, depending on the parameters defined.

Parameters

lattice_spacingarray-like, shape=(3,), required, dtype=float

Array of lattice spacings a,b,c for the cell.

lattice_vectorsarray-like, shape=(3, 3), optional, default=None,

Vectors that encase the unit cell corresponding to dimension. Will only default to these values if no angles were defined as well. If None is given, assumes an identity matrix [[1,0,0], [0,1,0], [0,0,1]]

lattice_pointsdictionary, shape={‘id’: [[nested list of positions]]

optional, default={‘default’: [[0.,0.,0.]]} Locations of all lattice points in cell using fractional coordinates.

anglesarray-like, shape=(3,), optional, dtype=float

Array of inter-planar Bravais angles in degrees.

Examples

Generating a triclinic lattice for cholesterol.

>>> import mbuild as mb
>>> from mbuild.utils.io import get_fn
>>> # reading in the lattice parameters for crystalline cholesterol
>>> angle_values = [94.64, 90.67, 96.32]
>>> spacing = [1.4172, 3.4209, 1.0481]
>>> basis = {'cholesterol':[[0., 0., 0.]]}
>>> cholesterol_lattice = mb.Lattice(spacing,
...                                  angles=angle_values,
...                                  lattice_points=basis)
>>>
>>> # The lattice based on the bravais lattice parameters of crystalline
>>> # cholesterol was generated.
>>>
>>> # Replicating the triclinic unit cell out 3 replications
>>> # in x,y,z directions.
>>>
>>> cholesterol_unit = mb.Compound()
>>> cholesterol_unit = mb.load(get_fn('cholesterol.pdb'))
>>> # associate basis vector with id 'cholesterol' to cholesterol Compound
>>> basis_dictionary = {'cholesterol' : cholesterol_unit}
>>> expanded_cell = cholesterol_lattice.populate(x=3, y=3, z=3,
...                              compound_dict=basis_dictionary)

The unit cell of cholesterol was associated with a Compound that contains the connectivity data and spatial arrangements of a cholesterol molecule. The unit cell was then expanded out in x,y,z directions and cholesterol Compounds were populated.

Generating BCC CsCl crystal structure

>>> import mbuild as mb
>>> chlorine = mb.Compound(name='Cl')
>>> # angles not needed, when not provided, defaults to 90,90,90
>>> cesium = mb.Compound(name='Cs')
>>> spacing = [.4123, .4123, .4123]
>>> basis = {'Cl' : [[0., 0., 0.]], 'Cs' : [[.5, .5, .5]]}
>>> cscl_lattice = mb.Lattice(spacing, lattice_points=basis)
>>>
>>> # Now associate id with Compounds for lattice points and replicate 3x
>>>
>>> cscl_dict = {'Cl' : chlorine, 'Cs' : cesium}
>>> cscl_compound = cscl_lattice.populate(x=3, y=3, z=3,
...                                       compound_dict=cscl_dict)

A multi-Compound basis was created and replicated. For each unique basis atom position, a separate entry must be completed for the basis_atom input.

Generating FCC Copper cell with lattice_vectors instead of angles

>>> import mbuild as mb
>>> copper = mb.Compound(name='Cu')
>>> lattice_vector = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
>>> spacing = [.36149, .36149, .36149]
>>> copper_locations = [[0., 0., 0.], [.5, .5, 0.],
...                     [.5, 0., .5], [0., .5, .5]]
>>> basis = {'Cu' : copper_locations}
>>> copper_lattice = mb.Lattice(lattice_spacing = spacing,
...                             lattice_vectors=lattice_vector,
...                             lattice_points=basis)
>>> copper_dict = {'Cu' : copper}
>>> copper_pillar = copper_lattice.populate(x=3, y=3, z=20,
...                                       compound_dict=copper_dict)

Generating the 2d Structure Graphene carbon backbone

>>> import mbuild as mb
>>> carbon = mb.Compound(name='C')
>>> angles = [90, 90, 120]
>>> carbon_locations = [[0, 0, 0], [2/3, 1/3, 0]]
>>> basis = {'C' : carbon_locations}
>>> graphene = mb.Lattice(lattice_spacing=[.2456, .2456, 0],
...                        angles=angles, lattice_points=basis)
>>> carbon_dict = {'C' : carbon}
>>> graphene_cell = graphene.populate(compound_dict=carbon_dict,
...                                   x=3, y=3, z=1)

Attributes

dimensionint, 3

Default dimensionality within mBuild. If choosing a lower dimension, pad the relevant arrays with zeroes.

lattice_spacingnumpy array, shape=(3,), required, dtype=float

Array of lattice spacings a,b,c for the cell.

lattice_vectorsnumpy array, shape=(3, 3), optional

default=[[1,0,0], [0,1,0], [0,0,1]] Vectors that encase the unit cell corresponding to dimension. Will only default to these values if no angles were defined as well.

lattice_pointsdictionary, shape={‘id’: [[nested list of positions]]

optional, default={‘default’: [[0.,0.,0.]]} Locations of all lattice points in cell using fractional coordinates.

anglesnumpy array, shape=(3,), optional, dtype=float

Array of inter-planar Bravais angles

populate(compound_dict=None, x=1, y=1, z=1)

Expand lattice and create compound from lattice.

Expands lattice based on user input. The user must also pass in a dictionary that contains the keys that exist in the basis_dict. The corresponding Compound will be the full lattice returned to the user.

If no dictionary is passed to the user, Dummy Compounds will be used.

Parameters

xint, optional, default=1

How many iterations in the x direction.

yint, optional, default=1

How many iterations in the y direction.

zint, optional, default=1

How many iterations in the z direction.

compound_dictdictionary, optional, default=None

Link between basis_dict and Compounds.

Raises

ValueError

incorrect x,y, or z values.

TypeError

incorrect type for basis vector

Notes

Called after constructor by user.

Units

mBuild automatically performs unit conversions in its reader and writer functions. When working with an mbuild.Compound, mBuild uses the following units:

Quantity	Units
distance	nm
angle	radians*

* mbuild.Lattice and mbuild.Box use degrees.

See also foyer unit documentation and ele documentation.

Coordinate transformations

The following utility functions provide mechanisms for spatial transformations for mbuild compounds:

mbuild.coordinate_transform.force_overlap(move_this, from_positions, to_positions, add_bond=True)

Move a Compound such that a position overlaps with another.

Computes an affine transformation that maps the from_positions to the respective to_positions, and applies this transformation to the compound.

Parameters

move_thismb.Compound

The Compound to be moved.

from_positionsnp.ndarray, shape=(n, 3), dtype=float

Original positions.

to_positionsnp.ndarray, shape=(n, 3), dtype=float

New positions.

add_bondbool, optional, default=True

If from_positions and to_positions are Ports, create a bond between the two anchor atoms.

mbuild.coordinate_transform.translate(compound, pos)

Translate a compound by a vector.

Parameters

compoundmb.Compound

The compound being translated.

posnp.ndarray, shape=(3,), dtype=float

The vector to translate the compound by.

mbuild.coordinate_transform.translate_to(compound, pos)

Translate a compound to a coordinate.

Parameters

compoundmb.Compound

The compound being translated.

posnp.ndarray, shape=(3,), dtype=float

The coordinate to translate the compound to.

mbuild.coordinate_transform.rotate(compound, theta, around)

Rotate a compound around an arbitrary vector.

Parameters

compoundmb.Compound

The compound being rotated.

thetafloat

The angle by which to rotate the compound, in radians.

aroundnp.ndarray, shape=(3,), dtype=float

The vector about which to rotate the compound.

mbuild.coordinate_transform.spin(compound, theta, around)

Rotate a compound in place around an arbitrary vector.

Parameters

compoundmb.Compound

The compound being rotated.

thetafloat

The angle by which to rotate the compound, in radians.

aroundnp.ndarray, shape=(3,), dtype=float

The axis about which to spin the compound.

mbuild.coordinate_transform.x_axis_transform(compound, new_origin=None, point_on_x_axis=None, point_on_xy_plane=None)

Move a compound such that the x-axis lies on specified points.

Parameters

compoundmb.Compound

The compound to move.

new_originmb.Compound or list-like of size 3, default=[0.0, 0.0, 0.0]

Where to place the new origin of the coordinate system.

point_on_x_axismb.Compound or list-like of size 3, default=[1, 0, 0]

A point on the new x-axis.

point_on_xy_planemb.Compound or list-like of size 3, default=[1, 0, 0]

A point on the new xy-plane.

mbuild.coordinate_transform.y_axis_transform(compound, new_origin=None, point_on_y_axis=None, point_on_xy_plane=None)

Move a compound such that the y-axis lies on specified points.

Parameters

compoundmb.Compound

The compound to move.

new_originmb.Compound or like-like of size 3, default=[0, 0, 0]

Where to place the new origin of the coordinate system.

point_on_y_axismb.Compound or list-like of size 3, default=[0, 1, 0]

A point on the new y-axis.

point_on_xy_planemb.Compound or list-like of size 3, default=[0, 1, 0]

A point on the new xy-plane.

mbuild.coordinate_transform.z_axis_transform(compound, new_origin=None, point_on_z_axis=None, point_on_zx_plane=None)

Move a compound such that the z-axis lies on specified points.

Parameters

compoundmb.Compound

The compound to move.

new_originmb.Compound or list-like of size 3, default=[0, 0, 0]

Where to place the new origin of the coordinate system.

point_on_z_axismb.Compound or list-like of size 3, default=[0, 0, 1]

A point on the new z-axis.

point_on_zx_planemb.Compound or list-like of size 3, default=[0, 0, 1]

A point on the new xz-plane.

Recipes

Monolayer

class mbuild.lib.recipes.monolayer.Monolayer(surface, chains, fractions=None, backfill=None, pattern=None, tile_x=1, tile_y=1, **kwargs)

A general monolayer recipe.

Parameters

surfacemb.Compound

Surface on which the monolayer will be built.

chainslist of mb.Compounds

The chains to be replicated and attached to the surface.

fractionslist of floats

The fractions of the pattern to be allocated to each chain.

backfilllist of mb.Compound, optional, default=None

If there are fewer chains than there are ports on the surface, copies of backfill will be used to fill the remaining ports.

patternmb.Pattern, optional, default=mb.Random2DPattern

An array of planar binding locations. If not provided, the entire surface will be filled with chain.

tile_xint, optional, default=1

Number of times to replicate substrate in x-direction.

tile_yint, optional, default=1

Number of times to replicate substrate in y-direction.

Polymer

class mbuild.lib.recipes.polymer.Polymer(monomers=None, end_groups=None)

Connect one or more components in a specified sequence.

Notes

There are two different approaches to using the Polymer class to create polymers

1) Pass in already created Compound instances to the monomers and end_groups parameters when creating a Polymer instance:

You can then call the Polymer.build() method to create a polymer. This approach can be used if the compounds being passed into the Polymer instance already have the ports created, and correct atomic structure to allow for the monomer-monomer and monomer-end group bonds. These compounds are used as-is when creating the polymer chain.

Attributes

monomerslist of mbuild.Compounds

Get the monomers.

end_groupslist of mbuild.Compounds

Get the end groups.

Methods

add_monomer(monomer, indices, separation, port_labels, orientation, replace)	Use to add a monomer compound to Polymer.monomers
add_end_groups(compound, index, separation, orientation, replace)	Use to add an end group compound to Polymer.end_groups
build(n, sequence)	Use to create a single polymer compound. This method uses the compounds created by calling the add_monomer and add_end_group methods.

add_end_groups(compound, index, separation=None, orientation=None, replace=True, label='head', duplicate=True)

Add an mBuild compound to self.end_groups.

End groups will be used to cap the polymer. Call this function for each unique end group compound to be used in the polymer, or call it once with duplicate=True if the head and tail end groups are the same.

Parameters

compoundmbuild.Compound

A compound of the end group structure

indexint

The particle index in compound that represents the bonding site between the end group and polymer. You can specify the index of a particle that will be replaced by the polymer bond or that acts as the bonding site. See the replace parameter notes.

separationfloat

The bond length (units nm) desired between monomer and end-group.

orientationarray-like, shape=(3,), default None

Vector along which to orient the port If replace=True and orientation=None, the orientation of the bond between the particle being removed and the anchor particle is used. Recommended behavior is to leave orientation set to None if you are using replace=True.

replaceBool, default True

If True, then the particle identified by index will be removed and ports are added to the particle it was initially bonded to. Only use replace=True in the case that index points to a hydrogen atom bonded to the desired bonding site particle. If False, then the particle identified by index will have a port added and no particle is removed from the end group compound.

labelstr, default ‘head’

Whether to add the end group to the ‘head or ‘tail’ of the polymer. If duplicate=True, label is ignored.

duplicateBool, default True

If True, then compound is duplicated and added to Polymer.end_groups twice. Set to True if you want the same end group compound at the head and tail of the polymer. If that’s the case, you only need to call add_end_groups() once. If False, compound is not duplicated and only one instance of the end group structure is added to Polymer.end_groups. You can call add_end_groups() a second time to add another end group.

Notes

Refer to the docstring notes of the add_monomer() function for an explanation of the correct way to use the replace and index parameters.

add_monomer(compound, indices, separation=None, orientation=[None, None], replace=True)

Add a Compound to self.monomers.

The monomers will be used to build the polymer. Call this function for each unique monomer to be used in the polymer.

Parameters

compoundmbuild.Compound

A compound of the individual monomer

indiceslist of int of length 2

The particle indicies of compound that represent the polymer bonding sites. You can specify the indices of particles that will be replaced by the polymer bond, or indices of particles that act as the bonding sites. See the ‘replace’ parameter notes.

separationfloat, units nm

The bond length desired at the monomer-monomer bonding site. (separation / 2) is used to set the length of each port

orientationlist of array-like, shape=(3,) of length 2,

default=[None, None] Vector along which to orient the port If replace = True, and orientation = None, the orientation of the bond between the particle being removed and the anchor particle is used. Recommended behavior is to leave orientation set to None if you are using replace=True.

replaceBool, required, default=True

If True, then the particles identified by bonding_indices will be removed and ports are added to the particles they were initially bonded to. Only use replace=True in the case that bonding_indices point to hydrogen atoms bonded to the desired monomer-monomer bonding site particles. If False, then the particles identified by bonding_indices will have ports added, and no particles are removed from the monomer compound.

Notes

Using the ‘replace’ and ‘indices’ parameters:

The atoms in an mbuild compound can be identified by their index numbers. For example, an ethane compound with the index number next to each atom:

       H(4)    H(7)
        |      |
H(3) - C(0) - C(1) - H(6)
        |      |
       H(2)   H(5)

If replace=True, then this fucntion removes the hydrogen atoms that are occupying where the C-C bond should occur between monomers. It is required that you specify which atoms should be removed which is achieved by the indices parameter.

In this example, you would remove H(2) and H(7) by indicating indices [2, 7]. The resulting structure of the polymer can vary wildly depending on your choice for indices, so you will have to test out different combinations to find the two that result in the desired structure.

build(n, sequence='A', add_hydrogens=True)

Connect one or more components in a specified sequence.

Uses the compounds that are stored in Polymer.monomers and Polymer.end_groups.

Parameters

nint

The number of times to replicate the sequence.

sequencestr, optional, default ‘A’

A string of characters where each unique character represents one repetition of a monomer. Characters in sequence are assigned to monomers in the order they appear in Polymer.monomers. The characters in sequence are assigned to the compounds in the in the order that they appear in the Polymer.monomers list. For example, ‘AB’ where ‘A’corresponds to the first compound added to Polymer.monomers and ‘B’ to the second compound.

add_hydrogensbool, default True

If True and an end group compound is None, then the head or tail of the polymer will be capped off with hydrogen atoms. If end group compounds exist, then they will be used. If False and an end group compound is None, then the head or tail port will be exposed in the polymer.

property end_groups

Get the end groups.

end_groups cannot be set. Use add_end_group method instead.

property monomers

Get the monomers.

monomers cannot be set. Use add_monomer method instead.

Tiled Compound

class mbuild.lib.recipes.tiled_compound.TiledCompound(tile, n_tiles, name=None)

Replicates a Compound in any cartesian direction(s).

Correctly updates connectivity while respecting periodic boundary conditions.

Parameters

tilemb.Compound

The Compound to be replicated.

n_tilesarray-like, shape=(3,), dtype=int, optional, default=(1, 1, 1)

Number of times to replicate tile in the x, y and z-directions.

namestr, optional, default=tile.name

Descriptive string for the compound.

Silica Interface

class mbuild.lib.recipes.silica_interface.SilicaInterface(bulk_silica, tile_x=1, tile_y=1, thickness=1.0, seed=12345)

A recipe for creating an interface from bulk silica.

Carves silica interface from bulk, adjusts to a reactive surface site density of 5.0 sites/nm^2 (agreeing with experimental results, see Zhuravlev 2000) by creating Si-O-Si bridges, and yields a 2:1 Si:O ratio (excluding the reactive surface sites).

Parameters

bulk_silicaCompound

Bulk silica from which to cleave an interface

tile_xint, optional, default=1

Number of times to replicate bulk silica in x-direction

tile_yint, optional, default=1

Number of times to replicate bulk silica in y-direction

thicknessfloat, optional, default=1.0

Thickness of the slab to carve from the silica bulk. (in nm; not including oxygen layers on the top and bottom of the surface)

References

1

Hartkamp, R., Siboulet, B., Dufreche, J.-F., Boasne, B. “Ion-specific adsorption and electroosmosis in charged amorphous porous silica.” (2015) Phys. Chem. Chem. Phys. 17, 24683-24695

2

L.T. Zhuravlev, “The surface chemistry of amorphous silica. Zhuravlev model.” (2000) Colloids Surf., A. 10, 1-38

Packing

mBuild packing module: a wrapper for PACKMOL.

http://leandro.iqm.unicamp.br/m3g/packmol/home.shtml

mbuild.packing.fill_box(compound, n_compounds=None, box=None, density=None, overlap=0.2, seed=12345, sidemax=100.0, edge=0.2, compound_ratio=None, aspect_ratio=None, fix_orientation=False, temp_file=None, update_port_locations=False)

Fill a box with an mbuild.compound or Compound s using PACKMOL.

fill_box takes a single Compound or a list of Compound s and returns a Compound that has been filled to specification by PACKMOL.

When filling a system, two arguments of n_compounds , box , and density must be specified.

If n_compounds and box are not None, the specified number of compounds will be inserted into a box of the specified size.

If n_compounds and density are not None, the corresponding box size will be calculated internally. In this case, n_compounds must be an int and not a list of int.

If box and density are not None, the corresponding number of compounds will be calculated internally.

For the cases in which box is not specified but generated internally, the default behavior is to calculate a cubic box. Optionally, aspect_ratio can be passed to generate a non-cubic box.

Parameters

compoundmb.Compound or list of mb.Compound

Compound or list of compounds to fill in box.

n_compoundsint or list of int

Number of compounds to be filled in box.

boxmb.Box

Box to be filled by compounds.

densityfloat, units \(kg/m^3\) , default=None

Target density for the system in macroscale units. If not None, one of n_compounds or box , but not both, must be specified.

overlapfloat, units nm, default=0.2

Minimum separation between atoms of different molecules.

seedint, default=12345

Random seed to be passed to PACKMOL.

sidemaxfloat, optional, default=100.0

Needed to build an initial approximation of the molecule distribution in PACKMOL. All system coordinates must fit with in +/- sidemax, so increase sidemax accordingly to your final box size.

edgefloat, units nm, default=0.2

Buffer at the edge of the box to not place molecules. This is necessary in some systems because PACKMOL does not account for periodic boundary conditions in its optimization.

compound_ratiolist, default=None

Ratio of number of each compound to be put in box. Only used in the case of density and box having been specified, n_compounds not specified, and more than one compound .

aspect_ratiolist of float

If a non-cubic box is desired, the ratio of box lengths in the x, y, and z directions.

fix_orientationbool or list of bools

Specify that compounds should not be rotated when filling the box, default=False.

temp_filestr, default=None

File name to write PACKMOL raw output to.

update_port_locationsbool, default=False

After packing, port locations can be updated, but since compounds can be rotated, port orientation may be incorrect.

Returns

filledmb.Compound

mbuild.packing.fill_region(compound, n_compounds, region, overlap=0.2, bounds=None, seed=12345, sidemax=100.0, edge=0.2, fix_orientation=False, temp_file=None, update_port_locations=False)

Fill a region of a box with mbuild.Compound (s) using PACKMOL.

Parameters

compoundmb.Compound or list of mb.Compound

Compound or list of compounds to fill in region.

n_compoundsint or list of ints

Number of compounds to be put in region.

regionmb.Box or list of mb.Box

Region to be filled by compounds.

overlapfloat, units nm, default=0.2

Minimum separation between atoms of different molecules.

seedint, default=12345

Random seed to be passed to PACKMOL.

sidemaxfloat, optional, default=100.0

Needed to build an initial approximation of the molecule distribution in PACKMOL. All system coordinates must fit with in +/- sidemax, so increase sidemax accordingly to your final box size.

edgefloat, units nm, default=0.2

Buffer at the edge of the region to not place molecules. This is necessary in some systems because PACKMOL does not account for periodic boundary conditions in its optimization.

fix_orientationbool or list of bools

Specify that compounds should not be rotated when filling the box, default=False.

boundslist-like of floats [minx, miny, minz, maxx, maxy, maxz], units nm, default=None

Bounding within box to pack compounds, if you want to pack within a bounding area that is not the full extent of the region, bounds are required.

temp_filestr, default=None

File name to write PACKMOL raw output to.

update_port_locationsbool, default=False

After packing, port locations can be updated, but since compounds can be rotated, port orientation may be incorrect.

Returns

filledmb.Compound

If using mulitple regions and compounds, the nth value in each list are used

in order.

For example, the third compound will be put in the third region using the

third value in n_compounds.

mbuild.packing.fill_sphere(compound, sphere, n_compounds=None, density=None, overlap=0.2, seed=12345, sidemax=100.0, edge=0.2, compound_ratio=None, fix_orientation=False, temp_file=None, update_port_locations=False)

Fill a sphere with a compound using PACKMOL.

One argument of n_compounds and density must be specified.

If n_compounds is not None, the specified number of n_compounds will be inserted into a sphere of the specified size.

If density is not None, the corresponding number of compounds will be calculated internally.

Parameters

compoundmb.Compound or list of mb.Compound

Compound or list of compounds to be put in box.

spherelist, units nm

Sphere coordinates in the form [x_center, y_center, z_center, radius]

n_compoundsint or list of int

Number of compounds to be put in box.

densityfloat, units \(kg/m^3\), default=None

Target density for the sphere in macroscale units.

overlapfloat, units nm, default=0.2

Minimum separation between atoms of different molecules.

seedint, default=12345

Random seed to be passed to PACKMOL.

sidemaxfloat, optional, default=100.0

Needed to build an initial approximation of the molecule distribution in PACKMOL. All system coordinates must fit with in +/- sidemax, so increase sidemax accordingly to your final sphere size

edgefloat, units nm, default=0.2

Buffer at the edge of the sphere to not place molecules. This is necessary in some systems because PACKMOL does not account for periodic boundary conditions in its optimization.

compound_ratiolist, default=None

Ratio of number of each compound to be put in sphere. Only used in the case of density having been specified, n_compounds not specified, and more than one compound.

fix_orientationbool or list of bools

Specify that compounds should not be rotated when filling the sphere, default=False.

temp_filestr, default=None

File name to write PACKMOL raw output to.

update_port_locationsbool, default=False

After packing, port locations can be updated, but since compounds can be rotated, port orientation may be incorrect.

Returns

filledmb.Compound

mbuild.packing.solvate(solute, solvent, n_solvent, box, overlap=0.2, seed=12345, sidemax=100.0, edge=0.2, fix_orientation=False, temp_file=None, update_port_locations=False)

Solvate a compound in a box of solvent using PACKMOL.

Parameters

solutemb.Compound

Compound to be placed in a box and solvated.

solventmb.Compound

Compound to solvate the box.

n_solventint

Number of solvents to be put in box.

boxmb.Box

Box to be filled by compounds.

overlapfloat, units nm, default=0.2

Minimum separation between atoms of different molecules.

seedint, default=12345

Random seed to be passed to PACKMOL.

sidemaxfloat, optional, default=100.0

Needed to build an initial approximation of the molecule distribution in PACKMOL. All system coordinates must fit with in +/- sidemax, so increase sidemax accordingly to your final box size

edgefloat, units nm, default=0.2

Buffer at the edge of the box to not place molecules. This is necessary in some systems because PACKMOL does not account for periodic boundary conditions in its optimization.

fix_orientationbool

Specify if solvent should not be rotated when filling box, default=False.

temp_filestr, default=None

File name to write PACKMOL raw output to.

update_port_locationsbool, default=False

After packing, port locations can be updated, but since compounds can be rotated, port orientation may be incorrect.

Returns

solvatedmb.Compound

Pattern

mBuild pattern module.

class mbuild.pattern.DiskPattern(n, **kwargs)

Generate N evenly distributed points on the unit circle along z = 0.

Disk is centered at the origin. Algorithm based on Vogel’s method.

Code by Alexandre Devert: http://blog.marmakoide.org/?p=1

class mbuild.pattern.Grid2DPattern(n, m, **kwargs)

Generate a 2D grid (n x m) of points along z = 0.

Notes

Points span [0,1) along x and y axes

Attributes

nint

Number of grid rows

mint

Number of grid columns

class mbuild.pattern.Grid3DPattern(n, m, l, **kwargs)

Generate a 3D grid (n x m x l) of points.

Notes

Points span [0,1) along x, y, and z axes

Attributes

nint

Number of grid rows

mint

Number of grid columns

lint

Number of grid aisles

class mbuild.pattern.Pattern(points, orientations=None, scale=None, **kwargs)

A superclass for molecules spatial Patterns.

Patterns refer to how molecules are arranged either in a box (volume) or 2-D surface. This class could serve as a superclass for different molecules patterns

Attributes

pointsarray or np.array

Positions of molecules in surface or space

orientationsdict, optional, default=None

Orientations of ports

scalefloat, optional, default=None

Scale the points in the Pattern.

apply(compound, orientation='', compound_port='')

Arrange copies of a Compound as specified by the Pattern.

Parameters

compoundmb.Compound

mb.Compound to be applied new pattern

orientationdict, optional, default=’’

New orientations for ports in compound

compound_portlist, optional, default=None

Ports to be applied new orientations

Returns

compoundmb.Compound

mb.Compound with applied pattern

apply_to_compound(guest, guest_port_name='down', host=None, backfill=None, backfill_port_name='up', scale=True)

Attach copies of a guest Compound to Ports on a host Compound.

Parameters

guestmb.Compound

The Compound prototype to be applied to the host Compound

guest_port_namestr, optional, default=’down’

The name of the port located on guest to attach to the host

hostmb.Compound, optional, default=None

A Compound with available ports to add copies of guest to

backfillmb.Compound, optional, default=None

A Compound to add to the remaining available ports on host after clones of guest have been added for each point in the pattern

backfill_port_namestr, optional, default=’up’

The name of the port located on backfill to attach to the host

scalebool, optional, default=True

Scale the points in the pattern to the lengths of the host’s boundingbox and shift them by the hosts mins

Returns

guestslist of mb.Compound

List of inserted guest compounds on host compound

backfillslist of mb.Compound

List of inserted backfill compounds on host compound

scale(by)

Scale the points in the Pattern.

Parameters

byfloat or np.ndarray, shape=(3,)

The factor to scale by. If a scalar, scale all directions isotropically. If np.ndarray, scale each direction independently

class mbuild.pattern.Random2DPattern(n, seed=None, **kwargs)

Generate n random points on a 2D grid along z = 0.

Attributes

nint

Number of points to generate

seedint

Seed for random number generation

class mbuild.pattern.Random3DPattern(n, seed=None, **kwargs)

Generate n random points on a 3D grid.

Attributes

nint

Number of points to generate

seedint

Seed for random number generation

class mbuild.pattern.SpherePattern(n, **kwargs)

Generate N evenly distributed points on the unit sphere.

Sphere is centered at the origin. Alrgorithm based on the ‘Golden Spiral’.

Code by Chris Colbert from the numpy-discussion list: http://mail.scipy.org/pipermail/numpy-discussion/2009-July/043811.html

Citing mBuild

If you use mBuild for your research, please cite our paper:

ACS

Klein, C.; Sallai, J.; Jones, T. J.; Iacovella, C. R.; McCabe, C.; Cummings, P. T. A Hierarchical, Component Based Approach to Screening Properties of Soft Matter. In Foundations of Molecular Modeling and Simulation. Molecular Modeling and Simulation (Applications and Perspectives); Snurr, R. Q., Adjiman, C. S., Kofke, D. A., Eds.; Springer, Singapore, 2016; pp 79-92.

BibTeX

@Inbook{Klein2016mBuild,
    author      = "Klein, Christoph and Sallai, János and Jones, Trevor J. and Iacovella, Christopher R. and McCabe, Clare and Cummings, Peter T.",
    editor      = "Snurr, Randall Q and Adjiman, Claire S. and Kofke, David A.",
    title       = "A Hierarchical, Component Based Approach to Screening Properties of Soft Matter",
    bookTitle   = "Foundations of Molecular Modeling and Simulation: Select Papers from FOMMS 2015",
    year        = "2016",
    publisher   = "Springer Singapore",
    address     = "Singapore",
    pages       = "79--92",
    isbn        = "978-981-10-1128-3",
    doi         = "10.1007/978-981-10-1128-3_5",
    url         = "https://doi.org/10.1007/978-981-10-1128-3_5"
}

Download as BibTeX or RIS

Older Documentation

Up until mBuild Version 0.10.4, the documentation is available as pdf files. Please use the following links to download the documentation as a pdf manual:

• Mbuild Version 0.10.4: Download Here

• Mbuild Version 0.10.3: Download Here

• Mbuild Version 0.10.1: Download Here

• Mbuild Version 0.9.3: Download Here