Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
velocity_verlet_integrator.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2020-2026 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
4#ifndef lethe_velocity_verlet_integrator_h
5#define lethe_velocity_verlet_integrator_h
6
8#include <dem/integrator.h>
9
10using namespace dealii;
11
12/**
13 * @brief Implementation of a classical velocity verlet scheme for the
14 * integration of the particle motion. Note that reinitialization of force and
15 * torque is also integrated into integration class.
16 *
17 * Velocity Verlet is a second-order integration scheme. It is implemented in
18 * its staggered (leapfrog) form: the velocities are stored at the half steps
19 * and the positions at the integer steps. Consequently, carrying out n time
20 * steps requires n + 1 integration operations.
21 *
22 * Calculation procedure:
23 *
24 * Opening half step (integrate_start), carried
25 * out once at the first time step
26 * v(1/2) = v(0) + 1/2 * a(0) * dt
27 * x(1) = x(0) + v(1/2) * dt
28 *
29 * Regular steps (integrate), carried out at every subsequent time step
30 * a(n) = F(n) / m
31 * v(n+1/2) = v(n-1/2) + a(n) * dt
32 * x(n+1) = x(n) + v(n+1/2) * dt
33 *
34 * Closing half step (integrate_end), carried out once the final
35 * position is reached to synchronize the velocities with the positions
36 * a(n) = F(n) / m
37 * v(n) = v(n-1/2) + 1/2 * a(n) * dt
38 *
39 * @tparam dim An integer that denotes the number of spatial dimensions.
40 * @tparam PropertiesIndex Index of the properties used within the ParticleHandler.
41 *
42 */
43template <int dim, typename PropertiesIndex>
44class VelocityVerletIntegrator : public Integrator<dim, PropertiesIndex>
45{
46public:
48
49 /**
50 * @brief Integrate the opening half step of the Velocity Verlet scheme, which
51 * starts the staggering. The velocities are advanced by half a time step,
52 * from v(0) to v(1/2), whereas the positions are advanced by a full time
53 * step, from x(0) to x(1). No time is therefore lost by the opening step: it
54 * consumes a full time step of the simulation, only the velocity is lagging
55 * by dt/2.
56 *
57 * @param particle_handler The particle handler whose particle motion we wish
58 * to integrate
59 * @param body_force A constant volumetric body force applied to all particles
60 * @param time_step The value of the time step used for the integration
61 * @param torque Torque acting on particles. It is reset to zero at the end of
62 * the integration
63 * @param force Force acting on particles. It is reset to zero at the end of
64 * the integration
65 * @param MOI A container of moment of inertia of particles
66 */
67 virtual void
68 integrate_start(Particles::ParticleHandler<dim> &particle_handler,
69 const Tensor<1, 3> &body_force,
70 const double time_step,
71 std::vector<Tensor<1, 3>> &torque,
72 std::vector<Tensor<1, 3>> &force,
73 const std::vector<double> &MOI) override;
74
75 /**
76 * @brief Integrate the closing half step of the Velocity Verlet scheme. The
77 * velocities are advanced by half a time step to synchronize them with the
78 * positions. The positions are left untouched.
79 *
80 * @param particle_handler The particle handler whose particle motion we wish
81 * to integrate
82 * @param body_force A constant volumetric body force applied to all particles
83 * @param time_step The value of the time step used for the integration
84 * @param torque Torque acting on particles. It is reset to zero at the end of
85 * the integration
86 * @param force Force acting on particles. It is reset to zero at the end of
87 * the integration
88 * @param MOI A container of moment of inertia of particles
89 */
90 virtual void
91 integrate_end(Particles::ParticleHandler<dim> &particle_handler,
92 const Tensor<1, 3> &body_force,
93 const double time_step,
94 std::vector<Tensor<1, 3>> &torque,
95 std::vector<Tensor<1, 3>> &force,
96 const std::vector<double> &MOI) override;
97
98 /**
99 * @brief Integrate the closing half step of the Velocity Verlet scheme when the
100 * adaptive sparse contacts are enabled. Only the particles located in mobile
101 * cells have their velocities advanced, the other ones only have their force
102 * and torque reset.
103 *
104 * @param particle_handler The particle handler whose particle motion we wish
105 * to integrate
106 * @param body_force A constant volumetric body force applied to all particles
107 * @param time_step The value of the time step used for the integration
108 * @param torque Torque acting on particles. It is reset to zero at the end of
109 * the integration
110 * @param force Force acting on particles. It is reset to zero at the end of
111 * the integration
112 * @param MOI A container of moment of inertia of particles
113 * @param triangulation The triangulation of the background mesh
114 * @param sparse_contacts_object The object that stores the mobility status of
115 * the cells
116 */
117 virtual void
118 integrate_end(Particles::ParticleHandler<dim> &particle_handler,
119 const Tensor<1, 3> &body_force,
120 const double time_step,
121 std::vector<Tensor<1, 3>> &torque,
122 std::vector<Tensor<1, 3>> &force,
123 const std::vector<double> &MOI,
124 const parallel::distributed::Triangulation<dim> &triangulation,
126 &sparse_contacts_object) override;
127
128 /**
129 * @brief Carry out a regular step of the Velocity Verlet scheme, that is, a full
130 * velocity step followed by a full position step.
131 *
132 * This function is called at every time step but the first one, which is
133 * handled by integrate_start(). It assumes that the velocities are already
134 * staggered, that is, that they are known at t(n-1/2) whereas the positions
135 * are known at t(n), and it preserves that staggering:
136 *
137 * a(n) = g + F(n) / m
138 * v(n+1/2) = v(n-1/2) + a(n) * dt
139 * x(n+1) = x(n) + v(n+1/2) * dt
140 *
141 * The velocity is advanced before the position and the updated velocity is
142 * the one used to advance the position, which is what makes the scheme
143 * second order and symplectic. Note that the acceleration is evaluated from
144 * the force accumulated by the contact force objects since the previous step,
145 * hence the force and the torque containers are reset to zero once they have
146 * been consumed. The angular velocity is advanced in the same manner from the
147 * torque and the moment of inertia.
148 *
149 * All three components of the velocity and of the angular velocity are
150 * advanced, even in 2D, since the third component of the angular velocity is
151 * the one that carries the rotation in 2D. Only the first @p dim components
152 * of the position are advanced.
153 *
154 * @param particle_handler The particle handler whose particle motion we wish
155 * to integrate
156 * @param body_force A constant volumetric body force applied to all particles
157 * @param time_step The value of the time step used for the integration
158 * @param torque Torque acting on particles. It is reset to zero at the end of
159 * the integration
160 * @param force Force acting on particles. It is reset to zero at the end of
161 * the integration
162 * @param MOI A container of moment of inertia of particles
163 */
164 virtual void
165 integrate(Particles::ParticleHandler<dim> &particle_handler,
166 const Tensor<1, 3> &body_force,
167 const double time_step,
168 std::vector<Tensor<1, 3>> &torque,
169 std::vector<Tensor<1, 3>> &force,
170 const std::vector<double> &MOI) override;
171
172 /**
173 * @brief Carry out a regular step of the Velocity Verlet scheme when the adaptive
174 * sparse contacts are enabled.
175 *
176 * The integration is identical to the one described above, but it is only
177 * carried out for the particles that belong to mobile cells. The particles of
178 * the active and inactive cells only have their force and torque reset, so
179 * that they remain at rest. The particles of the advected cells are displaced
180 * with the average velocity and acceleration of their cell, which is handled
181 * by integrate_with_advected_particles(). When the sparse contacts are
182 * disabled, or on the iteration at which the mobility status is reset, this
183 * function simply falls back to the regular integration.
184 *
185 * @param particle_handler The particle handler whose particle motion we wish
186 * to integrate
187 * @param body_force A constant volumetric body force applied to all particles
188 * @param time_step The value of the time step used for the integration
189 * @param torque Torque acting on particles. It is reset to zero at the end of
190 * the integration
191 * @param force Force acting on particles. It is reset to zero at the end of
192 * the integration
193 * @param MOI A container of moment of inertia of particles
194 * @param triangulation The triangulation of the background mesh
195 * @param sparse_contacts_object The object that stores the mobility status of
196 * the cells
197 */
198 virtual void
199 integrate(Particles::ParticleHandler<dim> &particle_handler,
200 const Tensor<1, 3> &body_force,
201 const double time_step,
202 std::vector<Tensor<1, 3>> &torque,
203 std::vector<Tensor<1, 3>> &force,
204 const std::vector<double> &MOI,
205 const parallel::distributed::Triangulation<dim> &triangulation,
207 &sparse_contacts_object) override;
208
209 void
211 Particles::ParticleHandler<dim> &particle_handler,
212 const Tensor<1, 3> &body_force,
213 const double time_step,
214 std::vector<Tensor<1, 3>> &torque,
215 std::vector<Tensor<1, 3>> &force,
216 const std::vector<double> &MOI,
217 const parallel::distributed::Triangulation<dim> &triangulation,
218 AdaptiveSparseContacts<dim, PropertiesIndex> &sparse_contacts_object);
219};
220
221#endif
Mechanism that disables contacts computation through mobility status of cells based on granular tempe...
Integrator()=default
The constructor to the integrator class is currently blank Eventually it might be a good idea to have...
void integrate_with_advected_particles(Particles::ParticleHandler< dim > &particle_handler, const Tensor< 1, 3 > &body_force, const double time_step, std::vector< Tensor< 1, 3 > > &torque, std::vector< Tensor< 1, 3 > > &force, const std::vector< double > &MOI, const parallel::distributed::Triangulation< dim > &triangulation, AdaptiveSparseContacts< dim, PropertiesIndex > &sparse_contacts_object)
virtual void integrate_start(Particles::ParticleHandler< dim > &particle_handler, const Tensor< 1, 3 > &body_force, const double time_step, std::vector< Tensor< 1, 3 > > &torque, std::vector< Tensor< 1, 3 > > &force, const std::vector< double > &MOI) override
Integrate the opening half step of the Velocity Verlet scheme, which starts the staggering....
virtual void integrate_end(Particles::ParticleHandler< dim > &particle_handler, const Tensor< 1, 3 > &body_force, const double time_step, std::vector< Tensor< 1, 3 > > &torque, std::vector< Tensor< 1, 3 > > &force, const std::vector< double > &MOI) override
Integrate the closing half step of the Velocity Verlet scheme. The velocities are advanced by half a ...
virtual void integrate(Particles::ParticleHandler< dim > &particle_handler, const Tensor< 1, 3 > &body_force, const double time_step, std::vector< Tensor< 1, 3 > > &torque, std::vector< Tensor< 1, 3 > > &force, const std::vector< double > &MOI) override
Carry out a regular step of the Velocity Verlet scheme, that is, a full velocity step followed by a f...
VelocityVerletIntegrator()=default