API reference

This page lists every public function exported by solvate, grouped by module.

Insertion and solvation

These are the functions for placing molecules in a target Universe. See User guide for guidance on which one to pick.

solvate.InsertPlanar(TargetUniverse, ProjectileUniverse, n=1, xmin=0, ymin=0, zmin=0, xmax=None, ymax=None, zmax=None, distance=1.25, tries=1000)

Insert n copies of a projectile into a rectangular region.

Each projectile is placed at a random position and orientation inside the axis-aligned box defined by (xmin, ymin, zmin) and (xmax, ymax, zmax). Up to tries placement attempts are made per projectile; a RuntimeError is raised if no overlap-free position is found.

Parameters:

• TargetUniverse (MDAnalysis.core.universe.Universe) – Universe to insert into. May be empty; TargetUniverse.dimensions then defines the simulation cell of the returned universe.

• ProjectileUniverse (MDAnalysis.core.universe.Universe) – Molecule that is inserted repeatedly.

• n (int, default 1) – Number of projectile copies to insert.

• xmin (float, default 0) – Lower bounds of the insertion box, in Å.

• ymin (float, default 0) – Lower bounds of the insertion box, in Å.

• zmin (float, default 0) – Lower bounds of the insertion box, in Å.

• xmax (float, optional) – Upper bounds of the insertion box, in Å. Each defaults to the corresponding component of TargetUniverse.dimensions.

• ymax (float, optional) – Upper bounds of the insertion box, in Å. Each defaults to the corresponding component of TargetUniverse.dimensions.

• zmax (float, optional) – Upper bounds of the insertion box, in Å. Each defaults to the corresponding component of TargetUniverse.dimensions.

• distance (float, default 1.25) – Minimum allowed distance (Å) between the inserted projectile and any existing atom in the target.

• tries (int, default 1000) – Maximum number of random placement attempts per projectile.

Returns:

New universe containing the target atoms followed by the inserted projectile copies.

Return type:

MDAnalysis.core.universe.Universe

Raises:

RuntimeError – If no overlap-free position is found within tries attempts for a given projectile.

See also

SolvatePlanar

Fast variant for many projectiles.

InsertCylinder, InsertSphere

solvate.InsertCylinder(TargetUniverse, ProjectileUniverse, n=1, pos=None, radius=None, min=0, max=None, dim=2, distance=1.25, tries=1000)

Insert n copies of a projectile into a cylindrical region.

Each projectile is placed at a random position and orientation inside the cylinder centred at pos with radius radius, extending from min to max along axis dim. Up to tries placement attempts are made per projectile; a RuntimeError is raised if no overlap-free position is found.

Parameters:

• TargetUniverse (MDAnalysis.core.universe.Universe) – Universe to insert into. May be empty.

• ProjectileUniverse (MDAnalysis.core.universe.Universe) – Molecule that is inserted repeatedly.

• n (int, default 1) – Number of projectile copies to insert.

• pos (array_like of shape (3,), optional) – Centre of the cylinder, in Å. Defaults to the centre of geometry of TargetUniverse (or the centre of its box if the target is empty). The component along dim is overridden by min.

• radius (float, optional) – Cylinder radius, in Å. Defaults to half of the smallest box edge of TargetUniverse.

• min (float, optional) – Lower and upper bound of the cylinder along axis dim, in Å. max defaults to TargetUniverse.dimensions[dim].

• max (float, optional) – Lower and upper bound of the cylinder along axis dim, in Å. max defaults to TargetUniverse.dimensions[dim].

• dim ({0, 1, 2}, default 2) – Index of the axis along which the cylinder extends (0 = x, 1 = y, 2 = z).

• distance (float, default 1.25) – Minimum allowed distance (Å) between the inserted projectile and any existing atom in the target.

• tries (int, default 1000) – Maximum number of random placement attempts per projectile.

Returns:

New universe containing the target atoms followed by the inserted projectile copies.

Return type:

MDAnalysis.core.universe.Universe

Raises:

RuntimeError – If no overlap-free position is found within tries attempts for a given projectile.

See also

SolvateCylinder

Fast variant for many projectiles.

InsertPlanar, InsertSphere

solvate.InsertSphere(TargetUniverse, ProjectileUniverse, n=1, pos=None, radius=None, distance=1.25, tries=1000)

Insert n copies of a projectile into a spherical region.

Each projectile is placed at a uniformly random position inside the sphere centred at pos with radius radius and a random orientation. Up to tries placement attempts are made per projectile; a RuntimeError is raised if no overlap-free position is found.

Parameters:

• TargetUniverse (MDAnalysis.core.universe.Universe) – Universe to insert into. May be empty.

• ProjectileUniverse (MDAnalysis.core.universe.Universe) – Molecule that is inserted repeatedly.

• n (int, default 1) – Number of projectile copies to insert.

• pos (array_like of shape (3,), optional) – Centre of the sphere, in Å. Defaults to the centre of geometry of TargetUniverse (or the centre of its box if the target is empty).

• radius (float, optional) – Sphere radius, in Å. Defaults to half of the smallest box edge of TargetUniverse.

• distance (float, default 1.25) – Minimum allowed distance (Å) between the inserted projectile and any existing atom in the target.

• tries (int, default 1000) – Maximum number of random placement attempts per projectile.

Returns:

New universe containing the target atoms followed by the inserted projectile copies.

Return type:

MDAnalysis.core.universe.Universe

Raises:

RuntimeError – If no overlap-free position is found within tries attempts for a given projectile.

See also

InsertPlanar, InsertCylinder

solvate.SolvatePlanar(TargetUniverse, ProjectileUniverse, n=1, density=None, xmin=0, ymin=0, zmin=0, xmax=None, ymax=None, zmax=None, distance=1.25, solvate_factor=100, fudge_factor=1.0, tries=1000)

Fill a rectangular region of a target with copies of a projectile.

Internally builds a small saturated patch of projectiles, tiles it across the insertion box, then prunes any copies that overlap atoms in TargetUniverse. This is orders of magnitude faster than InsertPlanar() for large solvent counts and is the recommended way to solvate a target with thousands of solvent molecules.

Parameters:

• TargetUniverse (MDAnalysis.core.universe.Universe) – Universe to solvate. May be empty; TargetUniverse.dimensions defines the simulation cell of the returned universe.

• ProjectileUniverse (MDAnalysis.core.universe.Universe) – Molecule that is inserted repeatedly.

• n (int, default 1) – Number of projectile copies to insert. Ignored when density is given.

• density (float, optional) – Target number density of projectiles, in molecules / ų. When set, n is computed from the volume of the insertion box and n is ignored.

• xmin (float, default 0) – Lower bounds of the insertion box, in Å.

• ymin (float, default 0) – Lower bounds of the insertion box, in Å.

• zmin (float, default 0) – Lower bounds of the insertion box, in Å.

• xmax (float, optional) – Upper bounds of the insertion box, in Å. Each defaults to the corresponding component of TargetUniverse.dimensions.

• ymax (float, optional) – Upper bounds of the insertion box, in Å. Each defaults to the corresponding component of TargetUniverse.dimensions.

• zmax (float, optional) – Upper bounds of the insertion box, in Å. Each defaults to the corresponding component of TargetUniverse.dimensions.

• distance (float, default 1.25) – Minimum allowed distance (Å) between an inserted projectile and any atom of the target. Tile copies closer than distance are removed after tiling.

• solvate_factor (int, default 100) – Target number of projectiles in each tiled sub-box. Larger values reduce the number of tiles and the cost of the per-tile saturation step; smaller values reduce peak memory.

• fudge_factor (float, default 1.0) – Multiplier on solvate_factor controlling how aggressively the seed patch is packed. Increased automatically and the function recurses when too few projectiles survive overlap pruning.

• tries (int, default 1000) – Base number of random placement attempts used when packing the seed patch (internally scaled by 1000).

Returns:

New universe containing the original target atoms followed by the inserted projectile copies.

Return type:

MDAnalysis.core.universe.Universe

See also

InsertPlanar

Slower per-molecule variant with full placement control.

SolvateCylinder

Equivalent for cylindrical regions.

solvate.SolvateCylinder(TargetUniverse, ProjectileUniverse, n=1, density=None, pos=None, radius=None, min=0, max=None, dim=2, distance=1.25, tries=1000, fudge_factor=1)

Fill a cylindrical region of a target with copies of a projectile.

Internally builds a small saturated patch of projectiles, tiles it across the cylinder’s bounding box, then prunes any copies that fall outside the cylinder or overlap atoms in TargetUniverse. For most use cases this is orders of magnitude faster than InsertCylinder().

Parameters:

• TargetUniverse (MDAnalysis.core.universe.Universe) – Universe to solvate. May be empty; in that case TargetUniverse.dimensions still defines the simulation cell of the returned universe.

• ProjectileUniverse (MDAnalysis.core.universe.Universe) – Molecule that is inserted repeatedly.

• n (int, default 1) – Number of projectile copies to insert. Ignored when density is given.

• density (float, optional) – Target number density of projectiles, in molecules / ų. When set, n is computed from the cylinder volume and n is ignored.

• pos (array_like of shape (3,), optional) – Centre of the cylinder, in Å. Defaults to the centre of geometry of TargetUniverse (or the centre of its box if the target is empty). The component along dim is overridden by min.

• radius (float, optional) – Cylinder radius, in Å. Defaults to half of the smallest box edge of TargetUniverse.

• min (float, optional) – Lower and upper bound of the cylinder along axis dim, in Å. max defaults to TargetUniverse.dimensions[dim].

• max (float, optional) – Lower and upper bound of the cylinder along axis dim, in Å. max defaults to TargetUniverse.dimensions[dim].

• dim ({0, 1, 2}, default 2) – Index of the axis along which the cylinder extends (0 = x, 1 = y, 2 = z).

• distance (float, default 1.25) – Minimum allowed distance (Å) between an inserted projectile and any atom of the target.

• tries (int, default 1000) – Maximum number of random placement attempts used when building the seed patch.

• fudge_factor (float, default 1.0) – Multiplier on the number of projectiles packed into the seed patch. Increased automatically and the function recurses when too few projectiles survive overlap pruning.

Returns:

New universe containing the original target atoms followed by the inserted projectile copies.

Return type:

MDAnalysis.core.universe.Universe

See also

InsertCylinder

Slower per-molecule variant with full placement control.

SolvatePlanar

Equivalent for rectangular regions.

Water and small-molecule models

Pre-built and parametric models, all returning a fresh MDAnalysis Universe.

solvate.models.empty(dimensions)

Create an empty Universe.

Useful as a target for the Insert* and Solvate* functions when building a system from scratch.

Parameters:

dimensions (array_like of shape (6,)) – Simulation cell as [a, b, c, alpha, beta, gamma] with lengths in Å and angles in degrees.

Returns:

An empty universe with no atoms and the given simulation cell.

Return type:

MDAnalysis.core.universe.Universe

solvate.models.spce()

Return a single SPC/E water molecule.

Uses an O–H bond length of 1.0 Å, an H–O–H angle of 109.47°, and the hydrogen partial charge q_H = 0.4238 e.

Returns:

Single-residue universe with three atoms representing SPC/E water.

Return type:

MDAnalysis.core.universe.Universe

See also

tip3p, tip4p_epsilon

solvate.models.tip3p()

Return a single TIP3P water molecule.

Uses an O–H bond length of 0.9572 Å, an H–O–H angle of 104.52°, and a hydrogen partial charge of q_H = 0.417 e.

Returns:

Single-residue universe with three atoms representing TIP3P water.

Return type:

MDAnalysis.core.universe.Universe

See also

spce, tip4p_epsilon

solvate.models.tip4p_epsilon()

Return a single TIP4P/ε water molecule.

Uses an O–H bond length of 0.9572 Å, an O–M distance of 0.105 Å, an H–O–H angle of 104.52°, and a hydrogen partial charge of q_H = 0.527 e (the negative charge sits on the M site).

Returns:

Single-residue universe with four atoms representing TIP4P/ε water.

Return type:

MDAnalysis.core.universe.Universe

See also

spce, tip3p

solvate.models.type_a(l_1, q_O, q_H, theta, mass_O=15.999, mass_H=1.00784)

Build a single 3-site water molecule (type a).

The oxygen sits at the origin; the two hydrogens lie in the xy plane at distance l_1 from the oxygen and at an angle theta to each other. Topology, masses, and partial charges are populated so the resulting universe is ready to be replicated by an Insert* or Solvate* call.

Parameters:

• l_1 (float) – O–H bond length, in Å.

• q_O (float) – Partial charge on the oxygen, in units of the elementary charge.

• q_H (float) – Partial charge on each hydrogen, in units of the elementary charge.

• theta (float) – H–O–H angle, in radians. Must lie in (0, pi].

• mass_O (float, default 15.999) – Oxygen mass, in u.

• mass_H (float, default 1.00784) – Hydrogen mass, in u.

Returns:

A single-residue universe with three atoms (OW, HW1, HW2) and the appropriate bond and angle topology.

Return type:

MDAnalysis.core.universe.Universe

See also

spce, tip3p

type_c

4-site variant with an additional M site.

solvate.models.type_c(l_1, l_2, q_M, q_H, theta, mass_O=15.999, mass_H=1.00784)

Build a single 4-site water molecule (type c).

Like type_a() but with an additional massless M site placed on the H–O–H angle bisector at distance l_2 from the oxygen. The negative charge sits on the M site rather than the oxygen.

Parameters:

• l_1 (float) – O–H bond length, in Å.

• l_2 (float) – O–M distance along the H–O–H bisector, in Å.

• q_M (float) – Partial charge on the M site, in units of the elementary charge.

• q_H (float) – Partial charge on each hydrogen, in units of the elementary charge.

• theta (float) – H–O–H angle, in radians. Must lie in (0, pi].

• mass_O (float, default 15.999) – Oxygen mass, in u.

• mass_H (float, default 1.00784) – Hydrogen mass, in u.

Returns:

A single-residue universe with four atoms (OW, HW1, HW2, MW), bonds, and angle topology.

Return type:

MDAnalysis.core.universe.Universe

See also

tip4p_epsilon

Pre-parameterised 4-site water model.

type_a

3-site variant.