Skip to content

Commit 96b8f35

Browse files
jngrad1234someshmebrito
committed
Rewrite collision detection feature
Co-authored-by: Somesh Kurahatti <[email protected]> Co-authored-by: Mariano Brito <[email protected]>
1 parent 1e3d4fb commit 96b8f35

40 files changed

+2054
-1112
lines changed

‎doc/sphinx/advanced_methods.rst

+160-116
Original file line numberDiff line numberDiff line change
@@ -19,123 +19,167 @@ automatically during the simulation, every time two particles collide.
1919
This is useful for simulations of chemical reactions and irreversible
2020
adhesion processes. Both, sliding and non-sliding contacts can be created.
2121

22-
The collision detection is controlled via the system
23-
:attr:`~espressomd.system.System.collision_detection` attribute,
22+
The collision detection is controlled via the
23+
:attr:`system.collision_detection
24+
<espressomd.system.System.collision_detection>` attribute,
2425
which is an instance of the class
2526
:class:`~espressomd.collision_detection.CollisionDetection`.
2627

27-
Several modes are available for different types of binding.
28-
29-
* ``"bind_centers"``: adds a pair-bond between two particles at their first collision.
30-
By making the bonded interaction *stiff* enough, the particles can be held together
31-
after the collision. Note that the particles can still slide on each others' surface,
32-
as the pair bond is not directional. This mode is set up as follows::
33-
34-
import espressomd
35-
import espressomd.interactions
36-
37-
system = espressomd.System(box_l=[1, 1, 1])
38-
bond_centers = espressomd.interactions.HarmonicBond(k=1000, r_0=1.5)
39-
system.bonded_inter.add(bond_centers)
40-
system.collision_detection.set_params(mode="bind_centers", distance=1.5,
41-
bond_centers=bond_centers)
42-
43-
The parameters are as follows:
44-
45-
* ``distance`` is the distance between two particles at which the binding is triggered.
46-
This cutoff distance, ``1.5`` in the example above, is typically chosen slightly larger
47-
than the particle diameter. It is also a good choice for the equilibrium length of the bond.
48-
* ``bond_centers`` is the bonded interaction to be created between the particles
49-
(an instance of :class:`~espressomd.interactions.HarmonicBond` in the example above).
50-
No guarantees are made regarding which of the two colliding particles gets the bond.
51-
Once there is a bond of this type on any of the colliding particles,
52-
no further binding occurs for this pair of particles.
53-
54-
* ``"bind_at_point_of_collision"``: this mode prevents sliding of the colliding particles at the contact.
55-
This is achieved by creating two virtual sites at the point of collision.
56-
They are rigidly connected to each of the colliding particles.
57-
A bond is then created between the virtual sites, or an angular bond between
58-
the two colliding particles and the virtual particles. In the latter case,
59-
the virtual particles are the centers of the angle potentials
60-
(particle 2 in the description of the angle potential, see :ref:`Bond-angle interactions`).
61-
Due to the rigid connection between each of the
62-
particles in the collision and its respective virtual site, a sliding
63-
at the contact point is no longer possible. See the documentation on
64-
:ref:`Rigid arrangements of particles` for details. In addition to the bond between the virtual
65-
sites, the bond between the colliding particles is also created, i.e.,
66-
the ``"bind_at_point_of_collision"`` mode implicitly includes the ``"bind_centers"`` mode.
67-
You can either use a real bonded interaction to prevent wobbling around
68-
the point of contact or you can use :class:`espressomd.interactions.Virtual` which acts as a marker, only.
69-
The method is setup as follows::
70-
71-
system.collision_detection.set_params(
72-
mode="bind_at_point_of_collision",
73-
distance=0.1,
74-
bond_centers=harmonic_bond1,
75-
bond_vs=harmonic_bond2,
76-
part_type_vs=1,
77-
vs_placement=0)
78-
79-
The parameters ``distance`` and ``bond_centers`` have the same meaning
80-
as in the ``"bind_centers"`` mode. The remaining parameters are as follows:
81-
82-
* ``bond_vs`` is the bond to be added between the two virtual sites created on collision.
83-
This is either a pair-bond with an equilibrium length matching the distance between
84-
the virtual sites, or an angle bond fully stretched in its equilibrium configuration.
85-
* ``part_type_vs`` is the particle type assigned to the virtual sites created on collision.
86-
In nearly all cases, no non-bonded interactions should be defined for this particle type.
87-
* ``vs_placement`` controls, where on the line connecting the centers of the colliding
88-
particles, the virtual sites are placed. A value of 0 means that the virtual sites are
89-
placed at the same position as the colliding particles on which they are based.
90-
A value of 0.5 will result in the virtual sites being placed at the mid-point between
91-
the two colliding particles. A value of 1 will result the virtual site associated
92-
to the first colliding particle to be placed at the position of the second colliding
93-
particle. In most cases, 0.5, is a good choice. Then, the bond connecting the virtual
94-
sites should have an equilibrium length of zero.
95-
96-
* ``"glue_to_surface"``: This mode is used to irreversibly attach small particles
97-
to the surface of a big particle. It is asymmetric in that several small particles
98-
can be bound to a big particle but not vice versa. The small particles can change type
99-
after collision to make them *inert*. On collision, a single virtual site is placed
100-
and related to the big particle. Then, a bond (``bond_centers``) connects the big
101-
and the small particle. A second bond (``bond_vs``) connects the virtual site and
102-
the small particle. Further required parameters are:
103-
104-
* ``part_type_to_attach_vs_to``: Type of the particle to which the virtual site is attached, i.e., the *big* particle.
105-
* ``part_type_to_be_glued``: Type of the particle bound to the virtual site (the *small* particle).
106-
* ``part_type_after_glueing``: The type assigned to the particle bound to the virtual site (*small* particle) after the collision.
107-
* ``part_type_vs``: Particle type assigned to the virtual site created during the collision.
108-
* ``distance_glued_particle_to_vs``: Distance of the virtual site to the particle being bound to it (*small* particle).
109-
110-
Note: When the type of a particle is changed on collision, this makes the
111-
particle inert with regards to further collision. Should a particle of
112-
type ``part_type_to_be_glued`` collide with two particles in a single
113-
time step, no guarantees are made with regards to which partner is selected.
114-
In particular, there is no guarantee that the choice is unbiased.
115-
116-
The method is used as follows::
117-
118-
system.collision_detection.set_params(
119-
mode="glue_to_surface",
120-
distance=0.1,
121-
distance_glued_particle_to_vs=0.02,
122-
bond_centers=harmonic_bond1,
123-
bond_vs=harmonic_bond2,
124-
part_type_vs=1,
125-
part_type_to_attach_vs_to=2,
126-
part_type_to_be_glued=3,
127-
part_type_after_glueing=4)
128-
129-
130-
The following limitations currently apply for the collision detection:
131-
132-
* No distinction is currently made between different particle types for the ``"bind_centers"`` method.
133-
134-
* The ``"bind_at_point_of_collision"`` and ``"glue_to_surface"`` approaches require
135-
the feature ``VIRTUAL_SITES_RELATIVE`` to be activated in :file:`myconfig.hpp`.
136-
137-
* The ``"bind_at_point_of_collision"`` approach cannot handle collisions
138-
between virtual sites
28+
Several protocols are available for different types of dynamic binding.
29+
The currently active collision mode can be removed by assigning ``None``
30+
or :class:`~espressomd.collision_detection.Off` to the
31+
:attr:`system.collision_detection.protocol
32+
<espressomd.collision_detection.CollisionDetection.protocol>` attribute.
33+
34+
.. _Bind centers:
35+
36+
Bind centers
37+
~~~~~~~~~~~~
38+
39+
Add a pair-bond between two particles at their first collision.
40+
By making the bonded interaction *stiff* enough, the particles can be held together
41+
after the collision. Note that the particles can still slide on each others' surface,
42+
as the pair bond is not directional. This protocol affects all particle types.
43+
This protocol is set up with :class:`~espressomd.collision_detection.BindCenters` as follows::
44+
45+
import espressomd
46+
import espressomd.interactions
47+
import espressomd.collision_detection
48+
system = espressomd.System(box_l=[1, 1, 1])
49+
bond_centers = espressomd.interactions.HarmonicBond(k=1000, r_0=0.1)
50+
system.bonded_inter.add(bond_centers)
51+
system.collision_detection.protocol = espressomd.collision_detection.BindCenters(
52+
distance=0.1, bond_centers=bond_centers)
53+
54+
The parameters are as follows:
55+
56+
* ``distance`` is the distance between two particles at which the binding is triggered.
57+
This cutoff distance, ``1.5`` in the example above, is typically chosen slightly larger
58+
than the particle diameter. It is also a good choice for the equilibrium length of the bond.
59+
* ``bond_centers`` is the bonded interaction to be created between the particles
60+
(an instance of :class:`~espressomd.interactions.HarmonicBond` in the example above).
61+
No guarantees are made regarding which of the two colliding particles gets the bond.
62+
Once there is a bond of this type on any of the colliding particles,
63+
no further binding occurs for this pair of particles.
64+
65+
.. note::
66+
67+
The following features are required:
68+
``COLLISION_DETECTION``.
69+
70+
.. _Bind at point of collision:
71+
72+
Bind at point of collision
73+
~~~~~~~~~~~~~~~~~~~~~~~~~~
74+
75+
Add two pair-bonds between two particles and two automatically generated virtual sites at their first collision.
76+
77+
This protocol prevents sliding of the colliding particles at the contact point.
78+
This is achieved by creating two virtual sites at the point of collision.
79+
They are rigidly connected to each of the colliding particles.
80+
Then, either a pair bond is added between the virtual sites, or an angular bond
81+
is added between the two colliding particles and the virtual particles.
82+
In the latter case, the virtual particles are the centers of the angle potentials
83+
(particle 2 in the description of the angle potential, see :ref:`Bond-angle interactions`).
84+
Due to the rigid connection between each of the colliding particles and their
85+
respective virtual sites, a sliding at the contact point is no longer possible.
86+
See :ref:`Rigid arrangements of particles` for details. This protocol affects all particle types.
87+
88+
In addition to the bond between the virtual sites, a bond between the colliding
89+
particles is also created. You can either use a real bonded interaction to prevent wobbling
90+
around the point of contact or you can use :class:`espressomd.interactions.Virtual`
91+
which acts as a marker, only.
92+
93+
This protocol is set up with :class:`~espressomd.collision_detection.BindAtPointOfCollision` as follows::
94+
95+
import espressomd
96+
import espressomd.interactions
97+
import espressomd.collision_detection
98+
system = espressomd.System(box_l=[1, 1, 1])
99+
bond_centers = espressomd.interactions.HarmonicBond(k=1000, r_0=0.1)
100+
bond_vs = espressomd.interactions.HarmonicBond(k=10000, r_0=0.02)
101+
system.bonded_inter.add(bond_centers)
102+
system.bonded_inter.add(bond_vs)
103+
system.collision_detection.protocol = espressomd.collision_detection.BindAtPointOfCollision(
104+
distance=0.1,
105+
bond_centers=bond_centers,
106+
bond_vs=bond_vs,
107+
part_type_vs=1,
108+
vs_placement=0.2)
109+
110+
The parameters ``distance`` and ``bond_centers`` have the same meaning
111+
as in the :ref:`Bind centers` protocol. The remaining parameters are as follows:
112+
113+
* ``bond_vs`` is the bond to be added between the two virtual sites created on collision.
114+
This is either a pair-bond with an equilibrium length matching the distance between
115+
the virtual sites, or an angle bond fully stretched in its equilibrium configuration.
116+
* ``part_type_vs`` is the particle type assigned to the virtual sites created on collision.
117+
In nearly all cases, no non-bonded interactions should be defined for this particle type.
118+
* ``vs_placement`` controls where the virtual sites are placed on the line connecting
119+
the colliding particles. A value of 0 means that the virtual sites are
120+
placed at the same position as the colliding particles on which they are based.
121+
A value of 0.5 will result in the virtual sites being placed at the mid-point between
122+
the two colliding particles. A value of 1 will result the virtual site associated
123+
to the first colliding particle to be placed at the position of the second colliding
124+
particle. In most cases, 0.5, is a good choice. Then, the bond connecting the virtual
125+
sites should have an equilibrium length of zero.
126+
127+
.. note::
128+
129+
The following features are required:
130+
``COLLISION_DETECTION``, ``VIRTUAL_SITES_RELATIVE``.
131+
132+
.. _Glue to surface:
133+
134+
Glue to surface
135+
~~~~~~~~~~~~~~~
136+
137+
Attach small particles to the surface of a large particle.
138+
139+
Several small particles can be bound to a large particle but not vice versa.
140+
The small particles can change type after collision to become *inert*.
141+
142+
This protocol is set up with :class:`~espressomd.collision_detection.GlueToSurface` as follows::
143+
144+
import espressomd
145+
import espressomd.interactions
146+
import espressomd.collision_detection
147+
system = espressomd.System(box_l=[1, 1, 1])
148+
bond_centers = espressomd.interactions.HarmonicBond(k=1000, r_0=0.1)
149+
bond_vs = espressomd.interactions.HarmonicBond(k=10000, r_0=0.02)
150+
system.bonded_inter.add(bond_centers)
151+
system.bonded_inter.add(bond_vs)
152+
system.collision_detection.protocol = espressomd.collision_detection.GlueToSurface(
153+
distance=0.1,
154+
distance_glued_particle_to_vs=0.02,
155+
bond_centers=bond_centers,
156+
bond_vs=bond_vs,
157+
part_type_vs=1,
158+
part_type_to_attach_vs_to=2,
159+
part_type_to_be_glued=3,
160+
part_type_after_glueing=4)
161+
162+
On collision, a single virtual site is placed and related to the large particle.
163+
Then a bond (``bond_centers``) connects the large and the small particle.
164+
A second bond (``bond_vs``) connects the virtual site and the small particle.
165+
Further required parameters are:
166+
167+
* ``part_type_to_attach_vs_to``: Type of the particle to which the virtual site is attached, i.e., the *large* particle.
168+
* ``part_type_to_be_glued``: Type of the particle bound to the virtual site (the *small* particle).
169+
* ``part_type_after_glueing``: The type assigned to the particle bound to the virtual site (*small* particle) after the collision.
170+
* ``part_type_vs``: Particle type assigned to the virtual site created during the collision.
171+
* ``distance_glued_particle_to_vs``: Distance of the virtual site to the particle being bound to it (*small* particle), as a fraction of the pair distance.
172+
173+
Note: When the type of a particle is changed on collision, this makes the
174+
particle inert with regards to further collisions. Should a particle of
175+
type ``part_type_to_be_glued`` collide with two particles in a single
176+
time step, no guarantees are made with regards to which partner is selected.
177+
In particular, there is no guarantee that the choice is unbiased.
178+
179+
.. note::
180+
181+
The following features are required:
182+
``COLLISION_DETECTION``, ``VIRTUAL_SITES_RELATIVE``.
139183

140184
.. _Deleting bonds when particles are pulled apart:
141185

@@ -209,10 +253,10 @@ features can be combined to model reversible bonds.
209253
Two combinations are possible:
210254

211255
* ``"delete_bond"`` mode for breakable bonds together with
212-
``"bind_centers"`` mode for collision detection:
256+
the :ref:`Bind centers` protocol of collision detection:
213257
used to create or delete a bond between two real particles
214258
* ``"revert_bind_at_point_of_collision"`` mode for breakable bonds together
215-
with ``"bind_at_point_of_collision"`` mode for collision detection:
259+
with the :ref:`Bind at point of collision` protocol of collision detection:
216260
used to create or delete virtual sites (the implicitly created
217261
bond between the real particles isn't affected)
218262

‎src/core/CMakeLists.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@ add_library(
2323
espresso_core SHARED
2424
bond_error.cpp
2525
cells.cpp
26-
collision.cpp
2726
communication.cpp
2827
dpd.cpp
2928
energy.cpp
@@ -102,6 +101,7 @@ add_subdirectory(bond_breakage)
102101
add_subdirectory(bonded_interactions)
103102
add_subdirectory(cell_system)
104103
add_subdirectory(cluster_analysis)
104+
add_subdirectory(collision_detection)
105105
add_subdirectory(constraints)
106106
add_subdirectory(ek)
107107
add_subdirectory(electrostatics)

0 commit comments

Comments
 (0)