Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
fluid_dynamics_vans.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_fluid_dynamics_vans_h
5#define lethe_fluid_dynamics_vans_h
6
7#include <core/parameters.h>
8
11
12#include <dem/dem.h>
16
17#include <deal.II/fe/mapping_q.h>
18
19#include <deal.II/particles/particle_handler.h>
20#include <deal.II/particles/property_pool.h>
21
22using namespace dealii;
23
24/**
25 * @brief Solver class for Volume-Averaged Navier-Stokes (VANS) equations with GLS stabilization.
26 *
27 * This class implements a computational fluid dynamics solver for the VANS
28 * equations, which are used to model fluid flow in porous media or multiphase
29 * systems where the presence of solid particles affects the fluid motion. The
30 * solver uses Galerkin Least Squares (GLS) stabilization techniques including
31 * SUPG (Streamline Upwind Petrov-Galerkin) and PSPG (Pressure Stabilizing
32 * Petrov-Galerkin) methods.
33 *
34 * The VANS equations account for the volume fraction of the fluid phase (void
35 * fraction) and incorporate particle-fluid interactions through appropriate
36 * source terms. This solver forms the foundation for CFD-DEM simulations where
37 * particle dynamics are coupled with fluid flow.
38 *
39 * @tparam dim Spatial dimension of the simulation (2 or 3)
40 *
41 * @ingroup solvers
42 */
43
44template <int dim, typename PropertiesIndex>
46{
47public:
48 /**
49 * @brief Constructor for the VANS solver.
50 *
51 * @param[in] nsparam CFD-DEM simulation parameters containing all
52 * configuration options for the coupled fluid-particle simulation
53 */
55
56 /**
57 * @brief Destructor for the VANS solver.
58 */
60
61 /**
62 * @brief Main solver loop for the VANS equations.
63 *
64 * Executes the complete solution procedure for the VANS equations including
65 * time stepping, matrix assembly, linear system solution, and convergence
66 * checking.
67 */
68 virtual void
69 solve() override;
70
71private:
72 /**
73 * @brief Assemble the diagonal mass matrix for the VANS system.
74 *
75 * Constructs the diagonal mass matrix used in time-dependent VANS
76 * calculations, incorporating void fraction effects.
77 *
78 * @param[out] mass_matrix Sparse matrix to store the assembled mass matrix
79 */
80 void
81 assemble_mass_matrix_diagonal(TrilinosWrappers::SparseMatrix &mass_matrix);
82
83 /**
84 * @brief Update solution vectors and constraint objects.
85 *
86 * Updates the solution vectors and applies constraints after each
87 * iteration or time step in the VANS solution process.
88 */
89 void
91
92 /**
93 * @brief Read DEM data for particle-fluid coupling.
94 *
95 * Loads particle information from DEM simulation for use in computing
96 * void fraction and particle-fluid interaction terms.
97 */
98 virtual void
99 read_dem();
100
101protected:
102 /**
103 * @brief Set up degrees of freedom and initialize void fraction field.
104 *
105 * Associates degrees of freedom to each vertex of the finite elements
106 * and initializes the void fraction field that represents the local
107 * volume fraction available to the fluid phase.
108 */
109 virtual void
110 setup_dofs() override;
111
112 /**
113 * @brief Execute a single VANS iteration.
114 *
115 * Performs one iteration of the VANS solution procedure including
116 * assembly, solution of the linear system, and solution update.
117 */
118 virtual void
119 iterate() override;
120
121 /**
122 * @brief Calculate void fraction field based on particle positions.
123 *
124 * Computes the local void fraction (porosity) at each point in the
125 * computational domain based on the current particle configuration.
126 *
127 * @param[in] time Current simulation time for time-dependent calculations
128 */
129 void
130 calculate_void_fraction(const double time);
131
132 /**
133 * @brief Create mapping between vertices and cells.
134 *
135 * Establishes the relationship between mesh vertices and the cells
136 * that contain them, which is needed for efficient void fraction
137 * and particle-fluid coupling calculations.
138 */
139 void
141
142 /**
143 * @brief Monitor mass conservation in the VANS system.
144 *
145 * Calculates and reports mass conservation metrics for the VANS
146 * solution, taking into account the void fraction field.
147 */
148 virtual void
150
151 /**
152 * @brief Complete operations at the end of a time step.
153 *
154 * Performs final operations required at the completion of each time
155 * step including post-processing and time advancement for fluid dynamics.
156 */
157 virtual void
159
160 /**
161 * @brief Assemble the global system matrix for the VANS equations.
162 *
163 * Constructs the global system matrix by assembling contributions from
164 * all cells, including fluid dynamics terms modified by void fraction
165 * and particle-fluid interaction terms.
166 */
167 void
168 assemble_system_matrix() override;
169
170 /**
171 * @brief Assemble the global right-hand side vector for the VANS equations.
172 *
173 * Constructs the global right-hand side vector including all source terms,
174 * boundary conditions, and particle-fluid coupling contributions.
175 */
176 void
177 assemble_system_rhs() override;
178
179 /**
180 * @brief Assemble the local system matrix for a given cell.
181 *
182 * Computes the local contributions to the global system matrix for a
183 * single cell, including VANS-specific terms with void fraction effects
184 * and GLS stabilization terms. This function is used by WorkStream
185 * for thread-safe parallel assembly.
186 *
187 * @param[in] cell Iterator pointing to the current active cell
188 * @param[in,out] scratch_data Scratch data containing finite element
189 * information at quadrature points for efficient assembly
190 * @param[out] copy_data Copy data structure for storing local assembly
191 * results before copying to global structures
192 */
193 void
195 const typename DoFHandler<dim>::active_cell_iterator &cell,
196 NavierStokesScratchData<dim> &scratch_data,
197 StabilizedMethodsTensorCopyData<dim> &copy_data) override;
198
199 /**
200 * @brief Assemble the local right-hand side vector for a given cell.
201 *
202 * Computes the local contributions to the global right-hand side vector
203 * for a single cell, including source terms, boundary conditions, and
204 * particle-fluid interaction terms modified by void fraction.
205 *
206 * @param[in] cell Iterator pointing to the current active cell
207 * @param[in,out] scratch_data Scratch data containing finite element
208 * information at quadrature points for efficient assembly
209 * @param[out] copy_data Copy data structure for storing local assembly
210 * results before copying to global structures
211 */
212 void
214 const typename DoFHandler<dim>::active_cell_iterator &cell,
215 NavierStokesScratchData<dim> &scratch_data,
216 StabilizedMethodsTensorCopyData<dim> &copy_data) override;
217
218 /**
219 * @brief Set up the vector of assembler functions for VANS equations.
220 *
221 * Initializes the assembler objects responsible for computing different
222 * terms in the VANS equations, including particle-fluid interaction
223 * assemblers and void fraction-dependent terms.
224 */
225 void
226 setup_assemblers() override;
227
228 /**
229 * @brief Copy local matrix contributions to the global system matrix.
230 *
231 * Transfers the locally assembled matrix contributions from a single
232 * cell to the appropriate locations in the global system matrix,
233 * handling constraint applications and matrix sparsity patterns.
234 *
235 * @param[in] copy_data Local assembly data containing matrix contributions
236 * and associated degree of freedom indices
237 */
238 void
240 const StabilizedMethodsTensorCopyData<dim> &copy_data) override;
241
242 /**
243 * @brief Copy local right-hand side contributions to the global vector.
244 *
245 * Transfers the locally assembled right-hand side contributions from
246 * a single cell to the appropriate locations in the global right-hand
247 * side vector, handling constraint applications.
248 *
249 * @param[in] copy_data Local assembly data containing right-hand side
250 * contributions and associated degree of freedom indices
251 */
252 void
254 const StabilizedMethodsTensorCopyData<dim> &copy_data) override;
255
256 /**
257 * @brief Gather additional output fields for visualization.
258 *
259 * Adds void fraction and particle velocity fields to the standard
260 * fluid dynamics output for comprehensive visualization of the
261 * coupled CFD-DEM system.
262 *
263 * @return Vector of OutputStruct objects containing additional fields
264 * for VTU output file generation
265 */
266 virtual std::vector<OutputStruct<dim, GlobalVectorType>>
267 gather_output_hook() override;
268
269
270 /**
271 * @brief Member Variables
272 */
273
274 /// CFD-DEM simulation parameters containing all configuration options
276
277 /// Mapping object for particle position calculations and projections
278 MappingQGeneric<dim> particle_mapping;
279
280 /// Vector of assembler objects for particle-fluid interaction terms
281 std::vector<std::shared_ptr<ParticleFluidAssemblerBase<dim, PropertiesIndex>>>
283
284 /// Flag enabling Pressure Stabilizing Petrov-Galerkin (PSPG) stabilization
285 const bool PSPG = true;
286
287 /// Flag enabling Streamline Upwind Petrov-Galerkin (SUPG) stabilization
288 const bool SUPG = true;
289
290 /// Scaling factor for GLS velocity stabilization terms
291 const double GLS_u_scale = 1;
292
293 /// Pressure drop across the computational domain
295
296 /// Mapping from vertex indices to sets of cells containing each vertex
297 std::map<unsigned int,
298 std::set<typename DoFHandler<dim>::active_cell_iterator>>
300
301 /// Mapping from vertex indices to sets of periodic cells containing each
302 /// vertex
303 std::map<unsigned int,
304 std::set<typename DoFHandler<dim>::active_cell_iterator>>
306
307 /// Particle handler for managing particle data and operations
308 Particles::ParticleHandler<dim, dim> particle_handler;
309
310 /// Particle projector for calculating void fraction and particle effects
312
313 /// Flag indicating whether the domain has periodic boundary conditions
315
316 /// Map of offset vectors for periodic boundary condition calculations
317 std::map<types::boundary_id, Tensor<1, dim>> cfd_periodic_offsets;
318
319 /// Map of direction indices for periodic boundary conditions
320 std::map<types::boundary_id, unsigned int> cfd_periodic_directions;
321};
322
323#endif
FluidDynamicsMatrixBased(SimulationParameters< dim > &nsparam, const FluidDynamicsFormulation fluid_dynamics_formulation=FluidDynamicsFormulation::standard)
Construct the matrix-based Navier-Stokes solver.
CFDDEMSimulationParameters< dim > cfd_dem_simulation_parameters
Member Variables.
void vertices_cell_mapping()
Create mapping between vertices and cells.
std::map< types::boundary_id, Tensor< 1, dim > > cfd_periodic_offsets
Map of offset vectors for periodic boundary condition calculations.
ParticleProjector< dim, PropertiesIndex > particle_projector
Particle projector for calculating void fraction and particle effects.
virtual void finish_time_step_fd()
Complete operations at the end of a time step.
std::vector< std::shared_ptr< ParticleFluidAssemblerBase< dim, PropertiesIndex > > > particle_fluid_assemblers
Vector of assembler objects for particle-fluid interaction terms.
double pressure_drop
Pressure drop across the computational domain.
std::map< unsigned int, std::set< typename DoFHandler< dim >::active_cell_iterator > > vertices_to_periodic_cell
virtual void iterate() override
Execute a single VANS iteration.
void assemble_local_system_rhs(const typename DoFHandler< dim >::active_cell_iterator &cell, NavierStokesScratchData< dim > &scratch_data, StabilizedMethodsTensorCopyData< dim > &copy_data) override
Assemble the local right-hand side vector for a given cell.
virtual void read_dem()
Read DEM data for particle-fluid coupling.
void assemble_mass_matrix_diagonal(TrilinosWrappers::SparseMatrix &mass_matrix)
Assemble the diagonal mass matrix for the VANS system.
void assemble_system_matrix() override
Assemble the global system matrix for the VANS equations.
std::map< unsigned int, std::set< typename DoFHandler< dim >::active_cell_iterator > > vertices_to_cell
Mapping from vertex indices to sets of cells containing each vertex.
void assemble_local_system_matrix(const typename DoFHandler< dim >::active_cell_iterator &cell, NavierStokesScratchData< dim > &scratch_data, StabilizedMethodsTensorCopyData< dim > &copy_data) override
Assemble the local system matrix for a given cell.
FluidDynamicsVANS(CFDDEMSimulationParameters< dim > &nsparam)
Constructor for the VANS solver.
virtual void setup_dofs() override
Set up degrees of freedom and initialize void fraction field.
virtual std::vector< OutputStruct< dim, GlobalVectorType > > gather_output_hook() override
Gather additional output fields for visualization.
const bool SUPG
Flag enabling Streamline Upwind Petrov-Galerkin (SUPG) stabilization.
void copy_local_rhs_to_global_rhs(const StabilizedMethodsTensorCopyData< dim > &copy_data) override
Copy local right-hand side contributions to the global vector.
std::map< types::boundary_id, unsigned int > cfd_periodic_directions
Map of direction indices for periodic boundary conditions.
MappingQGeneric< dim > particle_mapping
Mapping object for particle position calculations and projections.
Particles::ParticleHandler< dim, dim > particle_handler
Particle handler for managing particle data and operations.
const double GLS_u_scale
Scaling factor for GLS velocity stabilization terms.
~FluidDynamicsVANS()
Destructor for the VANS solver.
virtual void monitor_mass_conservation()
Monitor mass conservation in the VANS system.
void copy_local_matrix_to_global_matrix(const StabilizedMethodsTensorCopyData< dim > &copy_data) override
Copy local matrix contributions to the global system matrix.
void setup_assemblers() override
Set up the vector of assembler functions for VANS equations.
void update_solution_and_constraints()
Update solution vectors and constraint objects.
bool has_periodic_boundaries
Flag indicating whether the domain has periodic boundary conditions.
void assemble_system_rhs() override
Assemble the global right-hand side vector for the VANS equations.
void calculate_void_fraction(const double time)
Calculate void fraction field based on particle positions.
const bool PSPG
Flag enabling Pressure Stabilizing Petrov-Galerkin (PSPG) stabilization.
virtual void solve() override
Main solver loop for the VANS equations.
Class that stores the information required by the assembly procedure for a Navier-Stokes equation....
Particle information projection. This class manages the calculation of the projection of the particle...
Class responsible for storing the information calculated using the assembly of stabilized Tensor<1,...
Definition copy_data.h:166
Assemblers for the Volume-Averaged Navier-Stokes (VANS) equations.