hoomd.hpmc.external.user¶
Overview
Define an external potential energy field imposed on all particles in the system. |
Details
User-defined external fields for HPMC simulations.
Set \(U_{\mathrm{external},i}\) evaluated in
hoomd.hpmc.integrate.HPMCIntegrator
to a user-defined expression.
See also
Features explains the compile time options needed for user defined external potentials.
- class hoomd.hpmc.external.user.CPPExternalPotential(code, param_array=[])¶
Bases:
ExternalField
Define an external potential energy field imposed on all particles in the system.
- Parameters:
Potentials added using
CPPExternalPotential
are added to the total energy calculation inhoomd.hpmc.integrate.HPMCIntegrator
.CPPExternalPotential
takes C++ code, compiles it at runtime, and executes the code natively in the MC loop with full performance. It enables researchers to quickly and easily implement custom energetic field intractions without the need to modify and recompile HOOMD.Adjust parameters within the code with the
param_array
attribute without requiring a recompile. These arrays are read-only during function evaluation.C++ code
Supply C++ code to the code argument and
CPPExternalPotential
will compile the code and call it to evaluate the energy. The text provided in code is the body of a function with the following signature:float eval(const BoxDim& box, unsigned int type_i, const vec3<Scalar>& r_i, const quat<Scalar>& q_i Scalar diameter, Scalar charge )
box is the system box.
type_i is the (integer) particle type.
r_i is the particle position
q_i the quaternion representing the particle orientation.
diameter the particle diameter.
charge the particle charge.
Note
vec3
andquat
are defined in the file VectorMath.h in the HOOMD-blue source code, andBoxDim
is defined in he file BoxDim.h in the HOOMD-blue source code.Note
Your code must return a value.
Example:
gravity_code = ''' float gravity_constant = param_array[0]; return gravity_constant * (r_i.z + box.getL().z/2); ''' cpp_external_potential = hoomd.hpmc.external.user.CPPExternalPotential( code=gravity_code, param_array=[9.8]) hpmc_integrator.external_potential = cpp_external_potential
Note
CPPExternalPotential
does not support execution on GPUs.Warning
CPPExternalPotential
is experimental and subject to change in future minor releases.- code¶
The code of the body of the external field energy function. After running zero or more steps, this property cannot be modified.
Example
code = cpp_external_potential.code
- Type:
- param_array¶
Numpy array containing dynamically adjustable elements in the potential energy function as defined by the user. After running zero or more steps, the array cannot be set, although individual values can still be changed.
Example
cpp_external_potential.param_array[0] = 10.0
- Type:
(N, )
numpy.ndarray
offloat
- property energy¶
Total field energy of the system in the current state.
\[U = \sum_{i=0}^\mathrm{N_particles-1} U_{\mathrm{external},i}\]Example:
logger.add(cpp_external_potential, quantities=['energy'])
Returns
None
when the patch object and integrator are not attached.(
Loggable
: category=”scalar”)- Type: