diff --git a/hoomd/md/angle.py b/hoomd/md/angle.py index bf7ab7bbca..f49cb340d7 100644 --- a/hoomd/md/angle.py +++ b/hoomd/md/angle.py @@ -83,11 +83,13 @@ class Harmonic(Angle): U(\theta) = \frac{1}{2} k \left( \theta - \theta_0 \right)^2 - Examples:: + .. rubric:: Example: - harmonic = angle.Harmonic() - harmonic.params["A-A-A"] = dict(k=3.0, t0=0.7851) - harmonic.params["A-B-A"] = dict(k=100.0, t0=1.0) + .. code-block:: python + + harmonic = angle.Harmonic() + harmonic.params["A-A-A"] = dict(k=3.0, t0=0.7851) + harmonic.params["A-B-A"] = dict(k=100.0, t0=1.0) {inherited} @@ -132,11 +134,13 @@ class CosineSquared(Angle): `CosineSquared` is used in the gromos96 and MARTINI force fields. - Examples:: + .. rubric:: Example: + + .. code-block:: python - cosinesq = angle.CosineSquared() - cosinesq.params["A-A-A"] = dict(k=3.0, t0=0.7851) - cosinesq.params["A-B-A"] = dict(k=100.0, t0=1.0) + cosinesq = angle.CosineSquared() + cosinesq.params["A-A-A"] = dict(k=3.0, t0=0.7851) + cosinesq.params["A-B-A"] = dict(k=100.0, t0=1.0) {inherited} diff --git a/hoomd/md/bond.py b/hoomd/md/bond.py index d0157ed1da..d8fd626cb8 100644 --- a/hoomd/md/bond.py +++ b/hoomd/md/bond.py @@ -80,11 +80,13 @@ class Harmonic(Bond): U(r) = \frac{1}{2} k \left( r - r_0 \right)^2 - Examples:: + .. rubric:: Example: - harmonic = bond.Harmonic() - harmonic.params["A-A"] = dict(k=3.0, r0=2.38) - harmonic.params["A-B"] = dict(k=10.0, r0=1.0) + .. code-block:: python + + harmonic = bond.Harmonic() + harmonic.params["A-A"] = dict(k=3.0, r0=2.38) + harmonic.params["A-B"] = dict(k=10.0, r0=1.0) {inherited} @@ -143,13 +145,15 @@ class FENEWCA(Bond): bond, :math:`\varepsilon` is the repulsive interaction energy, and :math:`\sigma` is the repulsive interaction width. - Examples:: + .. rubric:: Example: + + .. code-block:: python - fenewca = bond.FENEWCA() - fenewca.params['A-A'] = dict(k=3.0, r0=2.38, epsilon=1.0, sigma=1.0, - delta=0.0) - fenewca.params['A-B'] = dict(k=10.0, r0=1.0, epsilon=0.8, sigma=1.2, - delta=0.0) + fenewca = bond.FENEWCA() + fenewca.params['A-A'] = dict(k=3.0, r0=2.38, epsilon=1.0, sigma=1.0, + delta=0.0) + fenewca.params['A-B'] = dict(k=10.0, r0=1.0, epsilon=0.8, sigma=1.2, + delta=0.0) {inherited} @@ -342,11 +346,13 @@ class Tether(Bond): .. math:: l_{min} < l_{c1} < l_{c0} < l_{max} - Examples:: + .. rubric:: Example: + + .. code-block:: python - bond_potential = bond.Tether() - bond_potential.params['A-A'] = dict(k_b=10.0, l_min=0.9, l_c1=1.2, - l_c0=1.8, l_max=2.1) + bond_potential = bond.Tether() + bond_potential.params['A-A'] = dict(k_b=10.0, l_min=0.9, l_c1=1.2, + l_c0=1.8, l_max=2.1) {inherited} diff --git a/hoomd/md/compute.py b/hoomd/md/compute.py index c5a92ab7e8..3dbb17d79c 100644 --- a/hoomd/md/compute.py +++ b/hoomd/md/compute.py @@ -33,10 +33,12 @@ class ThermodynamicQuantities(Compute): rigid body centers - ignoring constituent particles to avoid double counting. - Examples:: + .. rubric:: Example: - f = filter.Type("A") - compute.ThermodynamicQuantities(filter=f) + .. code-block:: python + + f = filter.Type("A") + compute.ThermodynamicQuantities(filter=f) {inherited} @@ -342,11 +344,13 @@ class HarmonicAveragedThermodynamicQuantities(Compute): by molecular simulation". Phys. Rev. E 92, 043303 doi:10.1103/PhysRevE.92.043303 - Examples:: + .. rubric:: Example: - hma = hoomd.compute.HarmonicAveragedThermodynamicQuantities( - filter=hoomd.filter.Type("A"), kT=1.0 - ) + .. code-block:: python + + hma = hoomd.compute.HarmonicAveragedThermodynamicQuantities( + filter=hoomd.filter.Type("A"), kT=1.0 + ) {inherited} diff --git a/hoomd/md/dihedral.py b/hoomd/md/dihedral.py index eb7099b2f9..e120fedd4c 100644 --- a/hoomd/md/dihedral.py +++ b/hoomd/md/dihedral.py @@ -93,11 +93,13 @@ class Periodic(Dihedral): U(\phi) = \frac{1}{2}k \left( 1 + d \cos\left(n \phi - \phi_0 \right) \right) - Examples:: + .. rubric:: Example: - harmonic = dihedral.Periodic() - harmonic.params["A-A-A-A"] = dict(k=3.0, d=-1, n=3, phi0=0) - harmonic.params["A-B-C-D"] = dict(k=100.0, d=1, n=4, phi0=math.pi / 2) + .. code-block:: python + + harmonic = dihedral.Periodic() + harmonic.params["A-A-A-A"] = dict(k=3.0, d=-1, n=3, phi0=0) + harmonic.params["A-B-C-D"] = dict(k=100.0, d=1, n=4, phi0=math.pi / 2) {inherited} @@ -226,10 +228,12 @@ class OPLS(Dihedral): :math:`k_n` are the force coefficients in the Fourier series. - Examples:: + .. rubric:: Example: + + .. code-block:: python - opls = dihedral.OPLS() - opls.params["A-A-A-A"] = dict(k1=1.0, k2=1.0, k3=1.0, k4=1.0) + opls = dihedral.OPLS() + opls.params["A-A-A-A"] = dict(k1=1.0, k2=1.0, k3=1.0, k4=1.0) {inherited} diff --git a/hoomd/md/force.py b/hoomd/md/force.py index 305de16b93..4add15bd08 100644 --- a/hoomd/md/force.py +++ b/hoomd/md/force.py @@ -242,13 +242,14 @@ def cpu_local_force_arrays(self): The local arrays are read only for built-in forces. Use `Custom` to implement custom forces. - Examples:: + .. rubric:: Example: - with self.cpu_local_force_arrays as arrays: - arrays.force[:] = ... - arrays.potential_energy[:] = ... - arrays.torque[:] = ... - arrays.virial[:] = ... + .. code-block:: python + with self.cpu_local_force_arrays as arrays: + arrays.force[:] = ... + arrays.potential_energy[:] = ... + arrays.torque[:] = ... + arrays.virial[:] = ... """ if self._in_context_manager: raise RuntimeError( @@ -275,13 +276,15 @@ def gpu_local_force_arrays(self): The local arrays are read only for built-in forces. Use `Custom` to implement custom forces. - Examples:: + .. rubric:: Example: + + .. code-block:: python - with self.gpu_local_force_arrays as arrays: - arrays.force[:] = ... - arrays.potential_energy[:] = ... - arrays.torque[:] = ... - arrays.virial[:] = ... + with self.gpu_local_force_arrays as arrays: + arrays.force[:] = ... + arrays.potential_energy[:] = ... + arrays.torque[:] = ... + arrays.virial[:] = ... Note: GPU local force data is not available if the chosen device for the @@ -427,17 +430,19 @@ class Active(Force): `hoomd.md.update.ActiveRotationalDiffusion` - Examples:: + .. rubric:: Example: - all = hoomd.filter.All() - active = hoomd.md.force.Active( - filter=hoomd.filter.All() - ) - active.active_force['A','B'] = (1,0,0) - active.active_torque['A','B'] = (0,0,0) - rotational_diffusion_updater = active.create_diffusion_updater( - trigger=10) - sim.operations += rotational_diffusion_updater + .. code-block:: python + + all = hoomd.filter.All() + active = hoomd.md.force.Active( + filter=hoomd.filter.All() + ) + active.active_force['A','B'] = (1,0,0) + active.active_torque['A','B'] = (0,0,0) + rotational_diffusion_updater = active.create_diffusion_updater( + trigger=10) + sim.operations += rotational_diffusion_updater Note: The energy and virial associated with the active force are 0. @@ -559,17 +564,19 @@ class ActiveOnManifold(Active): `hoomd.md.update.ActiveRotationalDiffusion` - Examples:: + .. rubric:: Example: - all = filter.All() - sphere = hoomd.md.manifold.Sphere(r=10) - active = hoomd.md.force.ActiveOnManifold( - filter=hoomd.filter.All(), - rotation_diff=0.01, - manifold_constraint=sphere, - ) - active.active_force["A", "B"] = (1, 0, 0) - active.active_torque["A", "B"] = (0, 0, 0) + .. code-block:: python + + all = filter.All() + sphere = hoomd.md.manifold.Sphere(r=10) + active = hoomd.md.force.ActiveOnManifold( + filter=hoomd.filter.All(), + rotation_diff=0.01, + manifold_constraint=sphere, + ) + active.active_force["A", "B"] = (1, 0, 0) + active.active_torque["A", "B"] = (0, 0, 0) {inherited} @@ -648,11 +655,13 @@ class Constant(Force): particles selected by the filter. `Constant` sets the force and torque to ``(0,0,0)`` for particles not selected by the filter. - Examples:: + .. rubric:: Example: + + .. code-block:: python - constant = hoomd.md.force.Constant(filter=hoomd.filter.All()) - constant.constant_force["A"] = (1, 0, 0) - constant.constant_torque["A"] = (0, 0, 0) + constant = hoomd.md.force.Constant(filter=hoomd.filter.All()) + constant.constant_force["A"] = (1, 0, 0) + constant.constant_torque["A"] = (0, 0, 0) Note: The energy and virial associated with the constant force are 0. diff --git a/hoomd/md/integrate.py b/hoomd/md/integrate.py index 640b5c5377..489376905e 100644 --- a/hoomd/md/integrate.py +++ b/hoomd/md/integrate.py @@ -239,15 +239,23 @@ class Integrator(_DynamicIntegrator): - `hoomd.md.constrain` - Examples:: - - nlist = hoomd.md.nlist.Cell() - lj = hoomd.md.pair.LJ(nlist=nlist) - lj.params.default = dict(epsilon=1.0, sigma=1.0) - lj.r_cut[('A', 'A')] = 2**(1/6) - nve = hoomd.md.methods.NVE(filter=hoomd.filter.All()) - integrator = hoomd.md.Integrator(dt=0.001, methods=[nve], forces=[lj]) - sim.operations.integrator = integrator + .. rubric:: Example: + + .. code-block:: python + + cell = hoomd.md.nlist.Cell(buffer=0.4) + lj = hoomd.md.pair.LJ(nlist=cell) + lj.params[('A', 'A')] = dict(epsilon=1.0, sigma=1.0) + lj.r_cut[('A', 'A')] = 2.5 + nve = hoomd.md.methods.ConstantVolume( + filter=hoomd.filter.All(), + thermostat=None, + ) + integrator = hoomd.md.Integrator(dt=0.005, + methods=[nve], + forces=[lj], + ) + {inherited} diff --git a/hoomd/md/nlist.py b/hoomd/md/nlist.py index e99b916300..dd0effc18f 100644 --- a/hoomd/md/nlist.py +++ b/hoomd/md/nlist.py @@ -255,14 +255,16 @@ def cpu_local_nlist_arrays(self): Note: The local arrays are read only. - Examples:: - - with self.cpu_local_nlist_arrays as arrays: - nlist_iter = zip(arrays.head_list, arrays.n_neigh) - for i, (head, nn) in enumerate(nlist_iter): - for j_idx in range(head, head + nn): - j = arrays.nlist[j_idx] - # i and j are "neighbor" indices + .. rubric:: Example: + + .. code-block:: python + + with self.cpu_local_nlist_arrays as arrays: + nlist_iter = zip(arrays.head_list, arrays.n_neigh) + for i, (head, nn) in enumerate(nlist_iter): + for j_idx in range(head, head + nn): + j = arrays.nlist[j_idx] + # i and j are "neighbor" indices """ if not self._attached: raise hoomd.error.DataAccessError("cpu_local_nlist_arrays") @@ -293,65 +295,67 @@ def gpu_local_nlist_arrays(self): See Also: `cpu_local_nlist_arrays` - Examples:: - - get_local_pairs = cupy.RawKernel(r''' - extern "C" __global__ - void get_local_pairs( - const unsigned int N, - const unsigned long* heads, - const unsigned int* nns, - const unsigned int* nlist, - const unsigned int* tags, - const unsigned long* offsets, - unsigned long* pairs) { - unsigned int i = (unsigned int) - (blockDim.x * blockIdx.x + threadIdx.x); - if (i >= N) - return; - uint2* pair = (uint2*)pairs; - unsigned long head = heads[i]; - unsigned int nn = nns[i]; - unsigned long offset = offsets[i]; - unsigned int tag_i = tags[i]; - for (unsigned int idx = 0; idx < nn; idx++) { - unsigned int j = nlist[head + idx]; - pair[offset + idx] = make_uint2(tag_i, tags[j]); + .. rubric:: Example: + + .. code-block:: python + + get_local_pairs = cupy.RawKernel(r''' + extern "C" __global__ + void get_local_pairs( + const unsigned int N, + const unsigned long* heads, + const unsigned int* nns, + const unsigned int* nlist, + const unsigned int* tags, + const unsigned long* offsets, + unsigned long* pairs) { + unsigned int i = (unsigned int) + (blockDim.x * blockIdx.x + threadIdx.x); + if (i >= N) + return; + uint2* pair = (uint2*)pairs; + unsigned long head = heads[i]; + unsigned int nn = nns[i]; + unsigned long offset = offsets[i]; + unsigned int tag_i = tags[i]; + for (unsigned int idx = 0; idx < nn; idx++) { + unsigned int j = nlist[head + idx]; + pair[offset + idx] = make_uint2(tag_i, tags[j]); + } } - } - ''', 'get_local_pairs') - - with nlist.gpu_local_nlist_arrays as data: - with sim.state.gpu_local_snapshot as snap_data: - tags = snap_data.particles.tag_with_ghost - tags = tags._coerce_to_ndarray() - - head_list = data.head_list._coerce_to_ndarray() - n_neigh = data.n_neigh._coerce_to_ndarray() - raw_nlist = data.nlist._coerce_to_ndarray() - - N = int(head_list.size) - n_pairs = int(cupy.sum(n_neigh)) - offsets = cupy.cumsum(n_neigh.astype(cupy.uint64) - offsets -= n_neigh[0] - device_local_pairs = cupy.zeros( - (n_pairs, 2), - dtype=cupy.uint32) - - block = 256 - n_grid = (N + 255) // 256 - get_local_pairs( - (n_grid,), - (block,), - ( - N, - head_list, - n_neigh, - raw_nlist, - tags, - offsets, - device_local_pairs - )) + ''', 'get_local_pairs') + + with nlist.gpu_local_nlist_arrays as data: + with sim.state.gpu_local_snapshot as snap_data: + tags = snap_data.particles.tag_with_ghost + tags = tags._coerce_to_ndarray() + + head_list = data.head_list._coerce_to_ndarray() + n_neigh = data.n_neigh._coerce_to_ndarray() + raw_nlist = data.nlist._coerce_to_ndarray() + + N = int(head_list.size) + n_pairs = int(cupy.sum(n_neigh)) + offsets = cupy.cumsum(n_neigh.astype(cupy.uint64) + offsets -= n_neigh[0] + device_local_pairs = cupy.zeros( + (n_pairs, 2), + dtype=cupy.uint32) + + block = 256 + n_grid = (N + 255) // 256 + get_local_pairs( + (n_grid,), + (block,), + ( + N, + head_list, + n_neigh, + raw_nlist, + tags, + offsets, + device_local_pairs + )) Note: GPU local nlist data is not available if the chosen device for the @@ -456,9 +460,11 @@ class Cell(NeighborList): number of cells in the system. In these cases, consider using `Stencil` or `Tree`, which can use less memory. - Examples:: + .. rubric:: Example: - cell = nlist.Cell() + .. code-block:: python + + cell = nlist.Cell() {inherited} @@ -566,9 +572,11 @@ class Stencil(NeighborList): *cell_width*, and when the *cell_width* covers the simulation box with a roughly integer number of cells. - Examples:: + .. rubric:: Example: + + .. code-block:: python - nl_s = nlist.Stencil(cell_width=1.5) + nl_s = nlist.Stencil(cell_width=1.5) Important: `M.P. Howard et al. 2016 `_ @@ -664,9 +672,11 @@ class Tree(NeighborList): improved algorithm that is currently implemented. Cite both if you utilize this neighbor list style in your work. - Examples:: + .. rubric:: Example: + + .. code-block:: python - nl_t = nlist.Tree(check_dist=False) + nl_t = nlist.Tree(check_dist=False) """ __doc__ = ( diff --git a/hoomd/md/special_pair.py b/hoomd/md/special_pair.py index e4e67a6724..8f5a8e72cb 100644 --- a/hoomd/md/special_pair.py +++ b/hoomd/md/special_pair.py @@ -97,11 +97,13 @@ class LJ(SpecialPair): fields, such as the scaled 1-4 interactions in OPLS where both the 1-4 `LJ` and `Coulomb` interactions are scaled by 0.5. - Examples:: + .. rubric:: Example: - lj = special_pair.LJ() - lj.params['cluster'] = dict(epsilon=3, sigma=0.5) - lj.r_cut['cluster'] = 5 + .. code-block:: python + + lj = special_pair.LJ() + lj.params['cluster'] = dict(epsilon=3, sigma=0.5) + lj.r_cut['cluster'] = 5 {inherited} @@ -164,11 +166,13 @@ class Coulomb(SpecialPair): fields, such as the scaled 1-4 interactions in OPLS where both the 1-4 `LJ` and `Coulomb` interactions are scaled by 0.5. - Examples:: + .. rubric:: Example: + + .. code-block:: python - coulomb = special_pair.Coulomb() - coulomb.params['cluster'] = dict(alpha=1.0) - coulomb.r_cut['cluster'] = 2 + coulomb = special_pair.Coulomb() + coulomb.params['cluster'] = dict(alpha=1.0) + coulomb.r_cut['cluster'] = 2 {inherited} diff --git a/hoomd/md/update.py b/hoomd/md/update.py index e4b0a2c006..85779030bb 100644 --- a/hoomd/md/update.py +++ b/hoomd/md/update.py @@ -40,11 +40,13 @@ class ZeroMomentum(Updater): Note: `ZeroMomentum` executes on the CPU even when using a GPU device. - Examples:: + .. rubric:: Example: - zero_momentum = hoomd.md.update.ZeroMomentum( - hoomd.trigger.Periodic(100) - ) + .. code-block:: python + + zero_momentum = hoomd.md.update.ZeroMomentum( + hoomd.trigger.Periodic(100) + ) """ __doc__ = ( @@ -117,18 +119,20 @@ class ReversePerturbationFlow(Updater): The attributes of this updater are immutable once the updater is attached to a simulation. - Examples:: - - # const integrated flow with 0.1 slope for max 1e8 timesteps - ramp = hoomd.variant.Ramp(0.0, 0.1e8, 0, int(1e8)) - # velocity gradient in z direction and shear flow in x direction. - mpf = hoomd.md.update.ReversePerturbationFlow( - filter=hoomd.filter.All(), - flow_target=ramp, - slab_direction="Z", - flow_direction="X", - n_slabs=20, - ) + .. rubric:: Example: + + .. code-block:: python + + # const integrated flow with 0.1 slope for max 1e8 timesteps + ramp = hoomd.variant.Ramp(0.0, 0.1e8, 0, int(1e8)) + # velocity gradient in z direction and shear flow in x direction. + mpf = hoomd.md.update.ReversePerturbationFlow( + filter=hoomd.filter.All(), + flow_target=ramp, + slab_direction="Z", + flow_direction="X", + n_slabs=20, + ) {inherited}