Recipes

Monolayer

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

A general monolayer recipe.

Parameters:
surface : mb.Compound

Surface on which the monolayer will be built.

chains : list of mb.Compounds

The chains to be replicated and attached to the surface.

fractions : list of floats

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

backfill : list 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.

pattern : mb.Pattern, optional, default=mb.Random2DPattern

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

tile_x : int, optional, default=1

Number of times to replicate substrate in x-direction.

tile_y : int, optional, default=1

Number of times to replicate substrate in y-direction.

Polymer

class mbuild.lib.recipes.polymer.Polymer(monomers, n, sequence='A', port_labels=('up', 'down'))[source]

Connect one or more components in a specified sequence.

Parameters:
monomers : mb.Compound or list of mb.Compound

The compound(s) to replicate.

n : int

The number of times to replicate the sequence.

sequence : str, 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 assigned by the built-in sorted().

port_labels : 2-tuple of strs, optional, default=(‘up’, ‘down’)

The names of the two ports to use to connect copies of proto.

Tiled Compound

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

Replicates a Compound in any cartesian direction(s).

Correctly updates connectivity while respecting periodic boundary conditions.

Parameters:
tile : mb.Compound

The Compound to be replicated.

n_tiles : array-like, shape=(3,), dtype=int, optional, default=(1, 1, 1)

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

name : str, 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)[source]

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_silica : mb.Compound

Bulk silica from which to cleave an interface

tile_x : int, optional, default=1

Number of times to replicate bulk silica in x-direction

tile_y : int, optional, default=1

Number of times to replicate bulk silica in y-direction

thickness : float, 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

Lattice

class mbuild.lattice.Lattice(lattice_spacing=None, lattice_vectors=None, lattice_points=None, angles=None)[source]

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_spacing : array-like, shape=(3,), required, dtype=float

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

lattice_vectors : array-like, 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_points : dictionary, shape={‘id’: [[nested list of positions]]

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

angles : array-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:
dimension : int, 3

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

lattice_spacing : numpy array, shape=(3,), required, dtype=float

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

lattice_vectors : numpy 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_points : dictionary, shape={‘id’: [[nested list of positions]]

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

angles : numpy array, shape=(3,), optional, dtype=float

Array of inter-planar Bravais angles

get_populated_box(self, x=1, y=1, z=1)[source]

Return a mbuild.Box representing the periodic boundaries of a populated mbuild.Lattice. This is meant to be called in parallel with, and using the same arguments of, a call to mb.Lattice.populate().

Parameters:
x : int, optional, default=1

How many iterations in the x direction.

y : int, optional, default=1

How many iterations in the y direction.

z : int, optional, default=1

How many iterations in the z direction.

populate(self, compound_dict=None, x=1, y=1, z=1)[source]

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:
x : int, optional, default=1

How many iterations in the x direction.

y : int, optional, default=1

How many iterations in the y direction.

z : int, optional, default=1

How many iterations in the z direction.

compound_dict : dictionary, optional, default=None

Link between basis_dict and Compounds.

Packing

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

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

fill_box takes a single mbuild.Compound or a list of mbuild.Compound’s and return an mbuild.Compound that has been filled to the user’s specifications to the best of PACKMOL’s ability.

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 n_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:
compound : mb.Compound or list of mb.Compound

Compound or list of compounds to fill in box.

n_compounds : int or list of int

Number of compounds to be filled in box.

box : mb.Box

Box to be filled by compounds.

density : float, 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.

overlap : float, units nm, default=0.2

Minimum separation between atoms of different molecules.

seed : int, default=12345

Random seed to be passed to PACKMOL.

edge : float, 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_ratio : list, 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_ratio : list of float

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

fix_orientation : bool or list of bools

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

temp_file : str, default=None

File name to write PACKMOL’s raw output to.

update_port_locations : bool, default=False

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

Returns:
filled : mb.Compound
mbuild.packing.fill_region(compound, n_compounds, region, overlap=0.2, seed=12345, edge=0.2, fix_orientation=False, temp_file=None, update_port_locations=False)[source]

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

Parameters:
compound : mb.Compound or list of mb.Compound

Compound or list of compounds to fill in region.

n_compounds : int or list of ints

Number of compounds to be put in region.

region : mb.Box or list of mb.Box

Region to be filled by compounds.

overlap : float, units nm, default=0.2

Minimum separation between atoms of different molecules.

seed : int, default=12345

Random seed to be passed to PACKMOL.

edge : float, 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_orientation : bool or list of bools

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

temp_file : str, default=None

File name to write PACKMOL’s raw output to.

update_port_locations : bool, default=False

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

Returns:
filled : mb.Compound
If using mulitple regions and compounds, the nth value in each
list are used in order.
For example, if 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, edge=0.2, compound_ratio=None, fix_orientation=False, temp_file=None, update_port_locations=False)[source]

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:
compound : mb.Compound or list of mb.Compound

Compound or list of compounds to be put in box.

sphere : list, units nm

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

n_compounds : int or list of int

Number of compounds to be put in box.

density : float, units kg/m^3, default=None

Target density for the sphere in macroscale units.

overlap : float, units nm, default=0.2

Minimum separation between atoms of different molecules.

seed : int, default=12345

Random seed to be passed to PACKMOL.

edge : float, 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_ratio : list, 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_orientation : bool or list of bools

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

temp_file : str, default=None

File name to write PACKMOL’s raw output to.

update_port_locations : bool, default=False

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

Returns:
filled : mb.Compound
mbuild.packing.solvate(solute, solvent, n_solvent, box, overlap=0.2, seed=12345, edge=0.2, fix_orientation=False, temp_file=None, update_port_locations=False)[source]

Solvate a compound in a box of solvent using packmol.

Parameters:
solute : mb.Compound

Compound to be placed in a box and solvated.

solvent : mb.Compound

Compound to solvate the box.

n_solvent : int

Number of solvents to be put in box.

box : mb.Box

Box to be filled by compounds.

overlap : float, units nm, default=0.2

Minimum separation between atoms of different molecules.

seed : int, default=12345

Random seed to be passed to PACKMOL.

edge : float, 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_orientation : bool

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

temp_file : str, default=None

File name to write PACKMOL’s raw output to.

update_port_locations : bool, default=False

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

Returns:
solvated : mb.Compound

Pattern

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

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:
points : array or np.array

Positions of molecules in surface or space

orientations : dict, optional, default=None

Orientations of ports

scale : float, optional, default=None

Scale the points in the Pattern.

apply(self, compound, orientation='', compound_port='')[source]

Arrange copies of a Compound as specified by the Pattern.

Parameters:
compound : mb.Compound

mb.Compound to be applied new pattern

orientation : dict, optional, default=’‘

New orientations for ports in compound

compound_port : list, optional, default=None

Ports to be applied new orientations

Returns:
compound : mb.Compound

mb.Compound with applied pattern

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

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

Parameters:
guest : mb.Compound

The Compound prototype to be applied to the host Compound

guest_port_name : str, optional, default=’down’

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

host : mb.Compound, optional, default=None

A Compound with available ports to add copies of guest to

backfill : mb.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_name : str, optional, default=’up’

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

scale : bool, optional, default=True

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

Returns:
guests : list of mb.Compound

List of inserted guest compounds on host compound

backfills : list of mb.Compound

List of inserted backfill compounds on host compound

scale(self, by)[source]

Scale the points in the Pattern.

Parameters:
by : float 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.DiskPattern(n, **kwargs)[source]

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.SpherePattern(n, **kwargs)[source]

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

class mbuild.pattern.Random2DPattern(n, seed=None, **kwargs)[source]
class mbuild.pattern.Random3DPattern(n, seed=None, **kwargs)[source]

Generate n random points on a 3D grid

Attributes:
n : int

Number of points to generate

seed : int

Seed for random number generation

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

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

Notes

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

n : int
Number of grid rows
m : int
Number of grid columns
class mbuild.pattern.Grid3DPattern(n, m, l, **kwargs)[source]

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

Notes

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

n : int
Number of grid rows
m : int
Number of grid columns
l : int
Number of grid aisles