# 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
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)[source]

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

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)[source]

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.

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.

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.

property monomers

Get the monomers.

## 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
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)[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_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)[source]

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)[source]

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)[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
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)[source]

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)[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.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

Attributes
nint

Number of grid rows

mint

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

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)[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
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='')[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[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