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
monomers
list of mbuild.CompoundsGet the monomers.
end_groups
list of mbuild.CompoundsGet 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)[source]
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)[source]
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)[source]
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, **kwargs)[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
scale
float, optional, default=NoneScale 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
- 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