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

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