Skip to content

[pull] develop from lammps:develop #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pull merged 7 commits into from
Mar 2, 2026
Merged

[pull] develop from lammps:develop #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
4387c5a
implement "within" and "exclude" keywords for dynamic groups
akohlmey Feb 27, 2026
1020e7b
update graphics hbond example
akohlmey Feb 27, 2026
b3c81c2
avoid use after free
akohlmey Feb 27, 2026
b1029e0
documentation clarifications
akohlmey Feb 27, 2026
ce80937
add unit tests for added keywords
akohlmey Feb 27, 2026
a9ef455
Fix typo
akohlmey Feb 27, 2026
fbd7c51
Merge pull request #4902 from akohlmey/dynamic-group-add-within-exclude
akohlmey Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 11 additions & 17 deletions doc/src/Howto_viz.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -995,7 +995,7 @@ input file:

group ogroup type 1
group hgroup type 2
compute hb all hbond/local 3.3 30.0 ogroup ogroup hgroup
compute hb all hbond/local 3.5 30.0 ogroup ogroup hgroup

dump viz all image 100 water-*.png element type size 600 600 zoom 1.331 view 70 20 &
shiny 0.2 ssao yes 348276 0.6 fsaa yes box yes 0.025 &
Expand All @@ -1017,25 +1017,19 @@ and the surrounding water molecules in both directions.

.. code-block:: LAMMPS

# define ellipsoid region around peptide for hbond analysis and visualization
group peptide type <= 12
variable comx equal xcm(peptide,x)
variable comy equal xcm(peptide,y)
variable comz equal xcm(peptide,z)
region shell ellipsoid v_comx v_comy v_comz 7.0 8.0 16.0
group viz dynamic all region shell include molecule

# define groups of donor and acceptor atoms for peptide and water
group pdonor type 5
group wdonor type 13
group pacceptor type 3 5 9 12
group wacceptor type 13
group hydrogen type 10 14
# select atoms for visualization: peptide and water molecules within 3.5 angstrom
group viz dynamic peptide within 3.5 include molecule every 100

# define groups of donor, acceptor, and hydrogen atoms for peptide and water
group pdonor type 5 9 # peptide donors : nitrogens and phenol oxygen
group woxygen type 13 # water oxygens are donor and acceptor
group pacceptor type 3 5 9 12 # peptide acceptors: oxygens, nitrogens, and sulfur
group hydrogen type 4 10 14 # hydrogens bonded to oxygens and nitrogens

# peptide-water hydrogen bonds where the peptide is the donor
compute hb1 all hbond/local 3.3 30.0 pdonor wacceptor hydrogen
compute hb1 all hbond/local 3.5 30.0 pdonor woxygen hydrogen
# peptide-water hydrogen bonds where the peptide is the acceptor
compute hb2 all hbond/local 3.7 30.0 wdonor pacceptor hydrogen
compute hb2 all hbond/local 3.7 30.0 woxygen pacceptor hydrogen

# create donor/acceptor hydrogen bond info text
fix label all graphics/labels 100 text "Hydrogen bonds donated: $(c_hb1:%02.0f)" 207 72 0.0 &
Expand Down
103 changes: 67 additions & 36 deletions doc/src/group.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,15 @@ Syntax
*intersect* args = two or more group IDs
*dynamic* args = parent-ID keyword value ...
one or more keyword/value pairs may be appended
keyword = *region* or *var* or *property* or *every*
keyword = *region* or *var* or *property* or *every* or *exclude* or *include* or *within*
*region* value = region-ID
*var* value = name of variable
*property* value = name of custom integer or floating point vector
*every* value = N = update group every this many timesteps
*exclude* value = group-ID = exclude atoms in this group from dynamic group
*include* args = molecule
molecule = add atoms to group with same molecule ID as atoms already in group
molecule = add atoms to the dynamic group with same molecule ID as atoms already selected for the dynamic group
*within* value = cutoff = add atoms to the dynamic group that are within the given cutoff distance of the atoms already selected for the dynamic group
*static* = no args

Examples
Expand All @@ -67,6 +69,7 @@ Examples
group boundary intersect upper flow
group boundary delete
group mine dynamic all region myRegion every 100
group solvation dynamic peptide within 3.5 include molecule every 100 exclude peptide

Description
"""""""""""
Expand Down Expand Up @@ -227,10 +230,12 @@ added to the specified group.
The *dynamic* style flags an existing or new group as dynamic. This
means atoms will be (re)assigned to the group periodically as a
simulation runs. This is in contrast to static groups where atoms are
permanently assigned to the group. The way the assignment occurs is
as follows. Only atoms in the group specified as the parent group via
the parent-ID are assigned to the dynamic group before the following
conditions are applied.
permanently assigned to the group. The way the assignment occurs is as
follows. Only atoms in the group specified as the parent group via the
parent-ID are initially assigned to the dynamic group before the
following selection conditions are applied. The *include* and *within*
keywords can then trigger including additional atoms which may be
outside the parent group.

If the *region* keyword is used, atoms not in the specified region are
removed from the dynamic group.
Expand All @@ -243,43 +248,69 @@ If the *property* keyword is used, the name refers to a custom integer
or floating point per-atom vector defined via the :doc:`fix
property/atom <fix_property_atom>` command. This means the values in
the vector can be read as part of a data file with the :doc:`read_data
<read_data>` command or specified with the :doc:`set <set>` command.
Or accessed and changed via the :doc:`library interface to LAMMPS
<read_data>` command or specified with the :doc:`set <set>` command. Or
accessed and changed via the :doc:`library interface to LAMMPS
<Howto_library>`, or by styles you add to LAMMPS (pair, fix, compute,
etc) which access the custom vector and modify its values. Which
means the values can be modified between or during simulations. Atoms
whose values in the custom vector are zero are removed from the
dynamic group. Note that the name of the custom per-atom vector is
specified just as *name*, not as *i_name* or *d_name* as it is for
other commands that use different kinds of custom atom vectors or
arrays as arguments.
etc) which access the custom vector and modify its values. Which means
the values can be modified between or during simulations. Atoms whose
values in the custom vector are zero are removed from the dynamic group.
Note that the name of the custom per-atom vector is specified just as
*name*, not as *i_name* or *d_name* as it is for other commands that use
different kinds of custom atom vectors or arrays as arguments.

The assignment of atoms to a dynamic group is done at the beginning of
each run and on every timestep that is a multiple of *N*\ , which is
the argument for the *every* keyword (:math:`N = 1` is the default). For an
each run and on every timestep that is a multiple of *N*\ , which is the
argument for the *every* keyword (:math:`N = 1` is the default). For an
energy minimization, via the :doc:`minimize <minimize>` command, an
assignment is made at the beginning of the minimization, but not
during the iterations of the minimizer.

The optional *include* keyword with its arg *molecule* adds atoms to a
dynamic group that have the same molecule ID as atoms already in the
group. The molecule ID = 0 is ignored in this operation, since it is
assumed to flag isolated atoms that are not part of molecules. An
example of where this operation is useful is if the dynamic group is
defined using a *region*. If molecules straddle the region boundary,
then atoms outside the region that are part of molecules with atoms
inside the region will be added to the group (see above).

The point in the timestep at which atoms are assigned to a dynamic
group is after interatomic forces have been computed, but before any
assignment is made at the beginning of the minimization, but not during
the iterations of the minimizer.

.. versionadded:: TBD

The optional *exclude* keyword has a group ID as argument and after all
other atom selections for the dynamic group have been performed, it
removes selected atoms that are in the specified group from the dynamic
group. This can for example be used to first select additional solvent
atoms up to a given distance from a group using the *within* keyword
(see below), but then exclude the non-solvent atoms.

.. versionadded:: 11Feb2026

The optional *include* keyword with its argument *molecule* adds atoms
to a dynamic group that have the same molecule ID as atoms already in
the group. Atoms with the molecule ID = 0 are ignored in this
operation, since that ID is generally assumed to flag isolated atoms
that are not part of molecules. An example of where this operation is
useful is if the dynamic group is defined using a *region*. If
molecules straddle the region boundary, then atoms outside the region
that are part of molecules with atoms inside the region will be added to
the group (see above).

.. versionadded:: TBD

The optional *within* keyword with its *cutoff* argument adds atoms to a
dynamic group that are within the given cutoff distance from any of the
atoms selected for the dynamic group. Since this requires processing a
neighbor list and computing distances for potentially many pairs of
atoms plus and additional forward communication step, this can be an
expensive operation that should be used in combination with the *every*
option and a value of (e.g. 10 or larger) to reduce the overhead for
updating the selection. Outside of flow simulations and similar, atoms
will mostly oscillate around their positions and diffuse on a much
larger timescale, so infrequent group updates will not be a problem.
Also when selecting atoms for output to a :doc:`dump file <dump>` it is
not necessary to update the selection more often than the dump interval.

The point in the timestep at which atoms are assigned to a dynamic group
is **after** interatomic forces have been computed, but **before** any
fixes which alter forces or otherwise update the system have been
invoked. This means that atom positions have been updated, neighbor
lists and ghost atoms are current, and both intermolecular and
intramolecular forces have been calculated based on the new
coordinates. Thus the region criterion, if applied, should be
accurate. Also, any computes invoked by an atom-style variable should
use updated information for that timestep (e.g., potential energy/atom
or coordination number/atom). Similarly, fixes or computes which are
intramolecular forces have been calculated based on the new coordinates.
Thus the region criterion, if applied, should be accurate. Also, any
computes invoked by an atom-style variable should use updated
information for that timestep (e.g., potential energy/atom or
coordination number/atom). Similarly, fixes or computes which are
invoked after that point in the timestep, should operate on the new
group of atoms.

Expand Down
60 changes: 39 additions & 21 deletions examples/GRAPHICS/in.peptide-hbonds
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,9 @@
# Solvated 5-mer peptide
# Visualize 5-mer peptide with solvation shell and hydrogen bonds

# output dump image every this many steps
variable vizsteps index 100
# run for this many steps
variable runsteps index 20000

units real
atom_style full
Expand All @@ -23,40 +28,53 @@ thermo 1000
fix 1 all nvt temp 275.0 275.0 100.0 tchain 1
fix 2 all shake 0.0001 10 1000 b 4 6 8 10 12 14 18 a 31

# define region around peptide for hbond analysis and visualization
group peptide type <= 12

# compute center of mass of peptide and center of box and displace atoms so they will match
variable comx equal xcm(peptide,x)
variable comy equal xcm(peptide,y)
variable comz equal xcm(peptide,z)
region water ellipsoid v_comx v_comy v_comz 7.0 8.0 16.0
group viz dynamic all region water include molecule
variable midx equal 0.5*(xhi+xlo)
variable midy equal 0.5*(yhi+ylo)
variable midz equal 0.5*(zhi+zlo)
variable xshift equal -v_comx+v_midx
variable yshift equal -v_comy+v_midy
variable zshift equal -v_comz+v_midz
displace_atoms all move v_xshift v_yshift v_zshift

# select atoms for visualization: peptide and water molecules within 3.5 angstrom
group viz dynamic peptide within 3.5 include molecule every ${vizsteps}

# define groups of donor and acceptor atoms for peptide and water
group pdonor type 5 9
group wdonor type 13
group pacceptor type 3 5 9 12
group wacceptor type 13
group hydrogen type 10 14
group pdonor type 5 9 # peptide donors : nitrogens and phenol oxygen
group woxygen type 13 # water oxygens are donor and acceptor
group pacceptor type 3 5 9 12 # peptide acceptors: oxygens, nitrogens, and sulfur
group hydrogen type 4 10 14 # hydrogens bonded to oxygens and nitrogens

# peptide-water hydrogen bonds where the peptide is the donor
compute hb1 all hbond/local 3.3 30.0 pdonor wacceptor hydrogen
compute hb1 all hbond/local 3.5 30.0 pdonor woxygen hydrogen
# peptide-water hydrogen bonds where the peptide is the acceptor
compute hb2 all hbond/local 3.7 30.0 wdonor pacceptor hydrogen
compute hb2 all hbond/local 3.7 30.0 woxygen pacceptor hydrogen

# create donor/acceptor hydrogen bonds info text
fix label all graphics/labels 100 text " Hydrogen bonds donated: $(c_hb1:%02.0f)" 207 72 0.0 &
size 24 backcolor darkgray &
text "Hydrogen bonds accepted: $(c_hb2:%02.0f)" 210 30 0.0 &
size 24 backcolor darkgray
fix label all graphics/labels ${vizsteps} text " Hydrogen bonds donated: $(c_hb1:%02.0f)" 207 72 0.0 &
size 24 backcolor darkgray &
text "Hydrogen bonds accepted: $(c_hb2:%02.0f)" 210 30 0.0 &
size 24 backcolor darkgray
# create colored arrows to go with text labels
fix obj all graphics/objects 100 arrow 5 80.0 61.0 39 80.0 67.0 39 0.3 0.2 &
arrow 6 80.0 61.0 37.2 80.0 67.0 37.2 0.3 0.2
fix obj all graphics/objects ${vizsteps} arrow 5 80.0 57.1 27.5 80.0 65.0 27.5 0.35 0.2 &
arrow 6 80.0 57.1 25.7 80.0 65.0 25.7 0.35 0.2
# add progress bar
variable prog equal step/${runsteps}
fix graphics all graphics/objects ${vizsteps} progbar 10 13 z $(xhi) $(ylo-0.5) $(zlo+0.5*(zhi-zlo)) $(lz-3.0) 0.5 v_prog 10

# combine the graphics into visualization
dump viz viz image 100 hbonds-*.png element element size 600 600 zoom 2.1 view 80 0 bond atom 0.3 &
fsaa yes ssao yes 12384 0.6 shiny 0.1 box no 0.1 center s 0.5 0.52 0.52 &
compute hb1 const -0.4 0.3 compute hb2 const -0.4 0.3 fix label const 1 0 fix obj type 0.0 0.0
dump viz viz image ${vizsteps} hbonds-*.png element element size 800 800 zoom 1.7 view 90 0 &
fsaa yes ssao yes 12384 0.6 shiny 0.1 box no 0.1 bond atom 0.3 &
center s 0.5 0.5 0.4 axes no 0.5 0.1 &
compute hb1 const -0.4 0.4 compute hb2 const -0.4 0.4 &
fix label const 1 0 fix obj type 0.0 0.0 fix graphics element 1 0.1
dump_modify viz pad 5 boxcolor white backcolor darkgray backcolor2 silver &
element C C O H N C C C O H H S O H ccolor hb1 cyan ccolor hb2 magenta

run 20000
run ${runsteps}
Loading