md.force

Overview

md.force.active Active force.
md.force.constant Constant force.
md.force.dipole Treat particles as dipoles in an electric field.

Details

Apply forces to particles.

class hoomd.md.force.active(seed, group, f_lst=None, t_lst=None, orientation_link=True, orientation_reverse_link=False, rotation_diff=0, constraint=None)

Active force.

Parameters:
  • seed (int) – required user-specified seed number for random number generator.
  • f_list (list) – An array of (x,y,z) tuples for the active force vector for each individual particle.
  • t_list (list) – An array of (x,y,z) tuples that indicate active torque vectors for each particle
  • group (hoomd.group) – Group for which the force will be set
  • orientation_link (bool) – if True then forces and torques are applied in the particle’s reference frame. If false, then the box reference frame is used. Only relevant for non-point-like anisotropic particles.
  • orientation_reverse_link (bool) – When True, the particle’s orientation is set to match the active force vector. Useful for for using a particle’s orientation to log the active force vector. Not recommended for anisotropic particles. Quaternion rotation assumes base vector of (0,0,1).
  • rotation_diff (float) – rotational diffusion constant, \(D_r\), for all particles in the group.
  • constraint (hoomd.md.update.constraint_ellipsoid) – such as update.constraint_ellipsoid.

active specifies that an active force should be added to all particles. Obeys \(\delta {\bf r}_i = \delta t v_0 \hat{p}_i\), where \(v_0\) is the active velocity. In 2D \(\hat{p}_i = (\cos \theta_i, \sin \theta_i)\) is the active force vector for particle \(i\); and the diffusion of the active force vector follows \(\delta \theta / \delta t = \sqrt{2 D_r / \delta t} \Gamma\), where \(D_r\) is the rotational diffusion constant, and the gamma function is a unit-variance random variable, whose components are uncorrelated in time, space, and between particles. In 3D, \(\hat{p}_i\) is a unit vector in 3D space, and diffusion follows \(\delta \hat{p}_i / \delta t = \sqrt{2 D_r / \delta t} \Gamma (\hat{p}_i (\cos \theta - 1) + \hat{p}_r \sin \theta)\), where \(\hat{p}_r\) is an uncorrelated random unit vector. The persistence length of an active particle’s path is \(v_0 / D_r\).

Attention

active() does not support MPI execution.

Examples:

force.active( seed=13, f_list=[tuple(3,0,0) for i in range(N)])

ellipsoid = update.constraint_ellipsoid(group=groupA, P=(0,0,0), rx=3, ry=4, rz=5)
force.active( seed=7, f_list=[tuple(1,2,3) for i in range(N)], orientation_link=False, rotation_diff=100, constraint=ellipsoid)
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.force.constant(fx=None, fy=None, fz=None, fvec=None, tvec=None, group=None, callback=None)

Constant force.

Parameters:
  • fvec (tuple) – force vector (in force units)
  • tvec (tuple) – torque vector (in torque units)
  • fx (float) – x component of force, retained for backwards compatibility
  • fy (float) – y component of force, retained for backwards compatibility
  • fz (float) – z component of force, retained for backwards compatibility
  • group (hoomd.group) – Group for which the force will be set.
  • callback (callable) – A python callback invoked every time the forces are computed

constant specifies that a constant force should be added to every particle in the simulation or optionally to all particles in a group.

Note

Forces are kept constant during the simulation. If a callback should re-compute particle forces every time step, it needs to overwrite the old forces of all particles with new values.

Note

Per-particle forces take precedence over a particle group, which takes precedence over constant forces for all particles.

Examples:

force.constant(fx=1.0, fy=0.5, fz=0.25)
const = force.constant(fvec=(0.4,1.0,0.5))
const = force.constant(fvec=(0.4,1.0,0.5),group=fluid)
const = force.constant(fvec=(0.4,1.0,0.5), tvec=(0,0,1) ,group=fluid)

def update_forces(timestep):
    global const
    const.set_force(tag=1, fvec=(1.0*timestep,2.0*timestep,3.0*timestep))
const = force.constant(callback=update_forces)
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.force.dipole(field_x, field_y, field_z, p)

Treat particles as dipoles in an electric field.

Parameters:
  • field_x (float) – x-component of the field (units?)
  • field_y (float) – y-component of the field (units?)
  • field_z (float) – z-component of the field (units?)
  • p (float) – magnitude of the particles’ dipole moment in the local z direction

Examples:

force.external_field_dipole(field_x=0.0, field_y=1.0 ,field_z=0.5, p=1.0)
const_ext_f_dipole = force.external_field_dipole(field_x=0.0, field_y=1.0 ,field_z=0.5, p=1.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)

set_params(field_y, field_z, p)

Change the constant field and dipole moment.

Parameters:
  • field_x (float) – x-component of the field (units?)
  • field_y (float) – y-component of the field (units?)
  • field_z (float) – z-component of the field (units?)
  • p (float) – magnitude of the particles’ dipole moment in the local z direction

Examples:

const_ext_f_dipole = force.external_field_dipole(field_x=0.0, field_y=1.0 ,field_z=0.5, p=1.0)
const_ext_f_dipole.setParams(field_x=0.1, field_y=0.1, field_z=0.0, p=1.0))