md.external

Overview

md.external.periodic One-dimension periodic potential.
md.external.e_field Electric field.

Details

External forces.

Apply an external force to all particles in the simulation. This module organizes all external forces. As an example, a force derived from a periodic potential can be used to induce a concentration modulation in the system.

class hoomd.md.external.coeff

Defines external potential coefficients.

The coefficients for all external forces are specified using this class. Coefficients are specified per particle type.

Example:

my_external_force.force_coeff.set('A', A=1.0, i=1, w=0.02, p=3)
my_external_force.force_coeff.set('B', A=-1.0, i=1, w=0.02, p=3)
set(type, **coeffs)

Sets parameters for particle types.

Parameters:
  • type (str) – Type of particle (or list of types)
  • coeff – Named coefficients (see below for examples)

Calling set() results in one or more parameters being set for a particle type. Types are identified by name, and parameters are also added by name. Which parameters you need to specify depends on the external force you are setting these coefficients for, see the corresponding documentation.

All possible particle types as defined in the simulation box must be specified before executing run(). You will receive an error if you fail to do so. It is not an error, however, to specify coefficients for particle types that do not exist in the simulation. This can be useful in defining a force field for many different types of particles even when some simulations only include a subset.

To set the same coefficients between many particle types, provide a list of type names instead of a single one. All types in the list will be set to the same parameters. A convenient wildcard that lists all types of particles in the simulation can be gotten from a saved system from the init command.

Examples:

coeff.set('A', A=1.0, i=1, w=0.02, p=3)
coeff.set('B', A=-1.0, i=1, w=0.02, p=3)
coeff.set(['A','B'], i=1, w=0.02, p=3)

Note

Single parameters can be updated. For example, executing coeff.set('A', A=1.0) will update the value of A and leave the other parameters as they were previously set.

class hoomd.md.external.e_field(field, name='')

Electric field.

e_field specifies that an external force should be added to every particle in the simulation that results from an electric field.

The external potential \(V(\vec{r})\) is implemented using the following formula:

\[V(\vec{r}) = - q_i \vec{E} \cdot \vec{r}\]

where \(q_i\) is the particle charge and \(\vec{E}\) is the field vector

Example:

# Apply an electric field in the x-direction
e_field = external.e_field((1,0,0))
disable(log=False)

Disable the force.

Parameters:log (bool) – Set to True if you plan to continue logging the potential energy associated with this force.

Examples:

force.disable()
force.disable(log=True)

Executing the disable command will remove the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable().

By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

enable()

Enable the force.

Examples:

force.enable()

See disable().

get_energy(group)

Get the energy of a particle group.

Parameters:group (hoomd.group) – The particle group to query the energy for.
Returns:The last computed energy for the members in the group.

Examples:

g = group.all()
energy = force.get_energy(g)
get_net_force(group)

Get the force of a particle group.

Parameters:group (hoomd.group) – The particle group to query the force for.
Returns:The last computed force for the members in the group.

Examples

g = group.all() force = force.get_net_force(g)

get_net_virial(group)

Get the virial of a particle group.

Parameters:group (hoomd.group) – The particle group to query the virial for.
Returns:The last computed virial for the members in the group.

Examples

g = group.all() virial = force.get_net_virial(g)

class hoomd.md.external.periodic(name='')

One-dimension periodic potential.

periodic specifies that an external force should be added to every particle in the simulation to induce a periodic modulation in the particle concentration. The force parameters can be set on a per particle type basis. The potential can e.g. be used to induce an ordered phase in a block-copolymer melt.

The external potential \(V(\vec{r})\) is implemented using the following formula:

\[V(\vec{r}) = A * \tanh\left[\frac{1}{2 \pi p w} \cos\left(p \vec{b}_i\cdot\vec{r}\right)\right]\]

where \(A\) is the ordering parameter, \(\vec{b}_i\) is the reciprocal lattice vector direction \(i=0..2\), \(p\) the periodicity and \(w\) the interface width (relative to the distance \(2\pi/|\mathbf{b_i}|\) between planes in the \(i\)-direction). The modulation is one-dimensional. It extends along the lattice vector \(\mathbf{a}_i\) of the simulation cell.

Examples:

# Apply a periodic composition modulation along the first lattice vector
periodic = external.periodic()
periodic.force_coeff.set('A', A=1.0, i=0, w=0.02, p=3)
periodic.force_coeff.set('B', A=-1.0, i=0, w=0.02, p=3)
disable(log=False)

Disable the force.

Parameters:log (bool) – Set to True if you plan to continue logging the potential energy associated with this force.

Examples:

force.disable()
force.disable(log=True)

Executing the disable command will remove the force from the simulation. Any hoomd.run() command executed after disabling a force will not calculate or use the force during the simulation. A disabled force can be re-enabled with enable().

By setting log to True, the values of the force can be logged even though the forces are not applied in the simulation. For forces that use cutoff radii, setting log=True will cause the correct r_cut values to be used throughout the simulation, and therefore possibly drive the neighbor list size larger than it otherwise would be. If log is left False, the potential energy associated with this force will not be available for logging.

enable()

Enable the force.

Examples:

force.enable()

See disable().

get_energy(group)

Get the energy of a particle group.

Parameters:group (hoomd.group) – The particle group to query the energy for.
Returns:The last computed energy for the members in the group.

Examples:

g = group.all()
energy = force.get_energy(g)
get_net_force(group)

Get the force of a particle group.

Parameters:group (hoomd.group) – The particle group to query the force for.
Returns:The last computed force for the members in the group.

Examples

g = group.all() force = force.get_net_force(g)

get_net_virial(group)

Get the virial of a particle group.

Parameters:group (hoomd.group) – The particle group to query the virial for.
Returns:The last computed virial for the members in the group.

Examples

g = group.all() virial = force.get_net_virial(g)