ESPResSo
Extensible Simulation Package for Research on Soft Matter Systems
Loading...
Searching...
No Matches
LBWalberlaBase.hpp
Go to the documentation of this file.
1/*
2 * Copyright (C) 2019-2023 The ESPResSo project
3 *
4 * This file is part of ESPResSo.
5 *
6 * ESPResSo is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * ESPResSo is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20#pragma once
21
22/**
23 * @file
24 * @ref LBWalberlaBase provides the public interface of the LB
25 * waLBerla bridge. It relies on type erasure to hide the waLBerla
26 * implementation details from the ESPResSo core. It is implemented
27 * by @ref walberla::LBWalberlaImpl.
28 */
29
32
33#include <utils/Vector.hpp>
34
35#include <cstddef>
36#include <memory>
37#include <optional>
38#include <vector>
39
40/** @brief Interface of a lattice-based fluid model. */
42public:
43 ~LBWalberlaBase() override = default;
44
45 /**
46 * @brief Integrate LB for one time step.
47 * The ghost layer may be out-of-date after integration.
48 * Call @ref ghost_communication() to refresh them before
49 * calling any getter function that reads from the halo region.
50 */
51 virtual void integrate() = 0;
52
53 /** @brief Perform a full ghost communication. */
54 virtual void ghost_communication() = 0;
55
56 /** @brief Perform a ghost communication of the PDF field. */
57 virtual void ghost_communication_pdf() = 0;
58
59 /** @brief Perform a ghost communication of the velocity field. */
60 virtual void ghost_communication_vel() = 0;
61
62 /** @brief Number of discretized velocities in the PDF. */
63 virtual std::size_t stencil_size() const noexcept = 0;
64
65 /** @brief Whether kernels use double-precision floating point numbers. */
66 [[nodiscard]] virtual bool is_double_precision() const noexcept = 0;
67
68 /** @brief Get interpolated velocities at a position. */
69 virtual std::optional<Utils::Vector3d>
70 get_velocity_at_pos(Utils::Vector3d const &position,
71 bool consider_points_in_halo = false) const = 0;
72
73 /** @brief Get interpolated velocities at positions. */
74 virtual std::vector<Utils::Vector3d>
75 get_velocities_at_pos(std::vector<Utils::Vector3d> const &pos) = 0;
76
77 /** @brief Get interpolated densities at a position. */
78 virtual std::optional<double>
79 get_density_at_pos(Utils::Vector3d const &position,
80 bool consider_points_in_halo = false) const = 0;
81
82 /**
83 * @brief Interpolate a force to the stored forces to be applied on nodes
84 * in the next time step.
85 */
86 virtual bool add_force_at_pos(Utils::Vector3d const &position,
87 Utils::Vector3d const &force) = 0;
88
89 /**
90 * @brief Interpolate forces to the stored forces to be applied on nodes
91 * in the next time step.
92 */
93 virtual void
94 add_forces_at_pos(std::vector<Utils::Vector3d> const &positions,
95 std::vector<Utils::Vector3d> const &forces) = 0;
96
97 /** @brief Get stored force to be applied on node in the next time step. */
98 virtual std::optional<Utils::Vector3d>
99 get_node_force_to_be_applied(Utils::Vector3i const &node) const = 0;
100
101 /** @brief Get stored force that was applied on node in the last time step. */
102 virtual std::optional<Utils::Vector3d>
103 get_node_last_applied_force(Utils::Vector3i const &node,
104 bool consider_ghosts = false) const = 0;
105
106 /** @brief Set stored force that was applied on node in the last time step. */
107 virtual bool set_node_last_applied_force(Utils::Vector3i const &node,
108 Utils::Vector3d const &force) = 0;
109
110 /** @brief Get stored force that was applied on slice in the last time step.
111 */
112 virtual std::vector<double>
113 get_slice_last_applied_force(Utils::Vector3i const &lower_corner,
114 Utils::Vector3i const &upper_corner) const = 0;
115
116 /** @brief Set stored force that was applied on slice in the last time step.
117 */
118 virtual void
119 set_slice_last_applied_force(Utils::Vector3i const &lower_corner,
120 Utils::Vector3i const &upper_corner,
121 std::vector<double> const &force) = 0;
122
123 /** @brief Get node population. */
124 virtual std::optional<std::vector<double>>
125 get_node_population(Utils::Vector3i const &node,
126 bool consider_ghosts = false) const = 0;
127
128 /** @brief Set node population. */
129 virtual bool set_node_population(Utils::Vector3i const &node,
130 std::vector<double> const &population) = 0;
131
132 /** @brief Get slice population. */
133 virtual std::vector<double>
134 get_slice_population(Utils::Vector3i const &lower_corner,
135 Utils::Vector3i const &upper_corner) const = 0;
136
137 /** @brief Set slice population. */
138 virtual void set_slice_population(Utils::Vector3i const &lower_corner,
139 Utils::Vector3i const &upper_corner,
140 std::vector<double> const &population) = 0;
141
142 /** @brief Get node velocity. */
143 virtual std::optional<Utils::Vector3d>
144 get_node_velocity(Utils::Vector3i const &node,
145 bool consider_ghosts = false) const = 0;
146
147 /** @brief Set node velocity. */
148 virtual bool set_node_velocity(Utils::Vector3i const &node,
149 Utils::Vector3d const &v) = 0;
150
151 /** @brief Get slice velocity. */
152 virtual std::vector<double>
153 get_slice_velocity(Utils::Vector3i const &lower_corner,
154 Utils::Vector3i const &upper_corner) const = 0;
155
156 /** @brief Set slice velocity. */
157 virtual void set_slice_velocity(Utils::Vector3i const &lower_corner,
158 Utils::Vector3i const &upper_corner,
159 std::vector<double> const &velocity) = 0;
160
161 /** @brief Get node density. */
162 virtual std::optional<double>
163 get_node_density(Utils::Vector3i const &node,
164 bool consider_ghosts = false) const = 0;
165
166 /** @brief Set node density. */
167 virtual bool set_node_density(Utils::Vector3i const &node,
168 double density) = 0;
169
170 /** @brief Get slice density. */
171 virtual std::vector<double>
172 get_slice_density(Utils::Vector3i const &lower_corner,
173 Utils::Vector3i const &upper_corner) const = 0;
174
175 /** @brief Set slice density. */
176 virtual void set_slice_density(Utils::Vector3i const &lower_corner,
177 Utils::Vector3i const &upper_corner,
178 std::vector<double> const &density) = 0;
179
180 /** @brief Get node velocity boundary conditions. */
181 virtual std::optional<Utils::Vector3d>
183 bool consider_ghosts = false) const = 0;
184
185 /** @brief Set node velocity boundary conditions. */
186 virtual bool
188 Utils::Vector3d const &velocity) = 0;
189
190 /** @brief Get slice velocity boundary conditions. */
191 virtual std::vector<std::optional<Utils::Vector3d>>
192 get_slice_velocity_at_boundary(Utils::Vector3i const &lower_corner,
193 Utils::Vector3i const &upper_corner) const = 0;
194
195 /** @brief Set slice velocity boundary conditions. */
197 Utils::Vector3i const &lower_corner, Utils::Vector3i const &upper_corner,
198 std::vector<std::optional<Utils::Vector3d>> const &velocity) = 0;
199
200 /** @brief Get (stored) force applied on node due to boundary condition. */
201 virtual std::optional<Utils::Vector3d>
202 get_node_boundary_force(Utils::Vector3i const &node) const = 0;
203
204 /** @brief Remove a node from the boundaries. */
205 virtual bool remove_node_from_boundary(Utils::Vector3i const &node) = 0;
206
207 /** @brief Check if node has velocity boundary conditions. */
208 virtual std::optional<bool>
209 get_node_is_boundary(Utils::Vector3i const &node,
210 bool consider_ghosts = false) const = 0;
211
212 /** @brief Check if slice has velocity boundary conditions. */
213 virtual std::vector<bool>
214 get_slice_is_boundary(Utils::Vector3i const &lower_corner,
215 Utils::Vector3i const &upper_corner) const = 0;
216
217 /** @brief Rebuild the UBB field. This is an expensive operation. */
218 virtual void reallocate_ubb_field() = 0;
219
220 /** @brief Clear the boundary flag field and the UBB field. */
221 virtual void clear_boundaries() = 0;
222
223 /** @brief Update boundary conditions from a rasterized shape. */
224 virtual void update_boundary_from_shape(std::vector<int> const &,
225 std::vector<double> const &) = 0;
226
227 /** @brief Configure the default collision model. */
228 virtual void set_collision_model(double kT, unsigned int seed) = 0;
229
230 /** @brief Configure a thermalized collision model for Lees-Edwards. */
231 virtual void
232 set_collision_model(std::unique_ptr<LeesEdwardsPack> &&lees_edwards_pack) = 0;
233
234 /** @brief Check Lees-Edwards boundary conditions. */
235 virtual void check_lebc(unsigned int shear_direction,
236 unsigned int shear_plane_normal) const = 0;
237
238 /** @brief Get node pressure tensor. */
239 virtual std::optional<Utils::VectorXd<9>>
240 get_node_pressure_tensor(Utils::Vector3i const &node) const = 0;
241
242 /** @brief Get slice pressure tensor. */
243 virtual std::vector<double>
244 get_slice_pressure_tensor(Utils::Vector3i const &lower_corner,
245 Utils::Vector3i const &upper_corner) const = 0;
246
247 /** @brief Calculate average pressure tensor of the local domain. */
248 virtual Utils::VectorXd<9> get_pressure_tensor() const = 0;
249
250 /** @brief Calculate momentum of the local domain. */
251 virtual Utils::Vector3d get_momentum() const = 0;
252
253 /** @brief Set a global external force. */
254 virtual void set_external_force(Utils::Vector3d const &ext_force) = 0;
255
256 /** @brief Get the global external force. */
257 virtual Utils::Vector3d get_external_force() const noexcept = 0;
258
259 /** @brief Set the fluid viscosity. */
260 virtual void set_viscosity(double viscosity) = 0;
261
262 /** @brief Get the fluid viscosity. */
263 virtual double get_viscosity() const noexcept = 0;
264
265 /** @brief Get the fluid density. */
266 virtual double get_density() const noexcept = 0;
267
268 /** @brief Get the fluid temperature (if thermalized). */
269 virtual double get_kT() const noexcept = 0;
270
271 /** @brief Get the RNG seed (if thermalized). */
272 virtual unsigned int get_seed() const noexcept = 0;
273
274 /** @brief Set the RNG counter (if thermalized). */
275 [[nodiscard]] virtual std::optional<uint64_t> get_rng_state() const = 0;
276
277 /** @brief Set the RNG counter (if thermalized). */
278 virtual void set_rng_state(uint64_t counter) = 0;
279
280 /** @brief get the velocity field id */
281 [[nodiscard]] virtual std::size_t get_velocity_field_id() const noexcept = 0;
282
283 /** @brief get the force field id */
284 [[nodiscard]] virtual std::size_t get_force_field_id() const noexcept = 0;
285
286 [[nodiscard]] virtual bool is_gpu() const noexcept = 0;
287};
Vector implementation and trait types for boost qvm interoperability.
Interface of a lattice-based fluid model.
virtual bool remove_node_from_boundary(Utils::Vector3i const &node)=0
Remove a node from the boundaries.
virtual std::optional< Utils::Vector3d > get_node_velocity(Utils::Vector3i const &node, bool consider_ghosts=false) const =0
Get node velocity.
virtual bool set_node_last_applied_force(Utils::Vector3i const &node, Utils::Vector3d const &force)=0
Set stored force that was applied on node in the last time step.
virtual std::optional< Utils::Vector3d > get_node_velocity_at_boundary(Utils::Vector3i const &node, bool consider_ghosts=false) const =0
Get node velocity boundary conditions.
virtual bool add_force_at_pos(Utils::Vector3d const &position, Utils::Vector3d const &force)=0
Interpolate a force to the stored forces to be applied on nodes in the next time step.
virtual std::optional< Utils::Vector3d > get_node_last_applied_force(Utils::Vector3i const &node, bool consider_ghosts=false) const =0
Get stored force that was applied on node in the last time step.
virtual double get_density() const noexcept=0
Get the fluid density.
virtual std::optional< Utils::Vector3d > get_velocity_at_pos(Utils::Vector3d const &position, bool consider_points_in_halo=false) const =0
Get interpolated velocities at a position.
virtual Utils::VectorXd< 9 > get_pressure_tensor() const =0
Calculate average pressure tensor of the local domain.
virtual bool is_gpu() const noexcept=0
virtual std::optional< bool > get_node_is_boundary(Utils::Vector3i const &node, bool consider_ghosts=false) const =0
Check if node has velocity boundary conditions.
virtual std::optional< double > get_density_at_pos(Utils::Vector3d const &position, bool consider_points_in_halo=false) const =0
Get interpolated densities at a position.
virtual std::vector< double > get_slice_velocity(Utils::Vector3i const &lower_corner, Utils::Vector3i const &upper_corner) const =0
Get slice velocity.
virtual void set_slice_velocity_at_boundary(Utils::Vector3i const &lower_corner, Utils::Vector3i const &upper_corner, std::vector< std::optional< Utils::Vector3d > > const &velocity)=0
Set slice velocity boundary conditions.
virtual void clear_boundaries()=0
Clear the boundary flag field and the UBB field.
virtual std::optional< uint64_t > get_rng_state() const =0
Set the RNG counter (if thermalized).
virtual std::vector< double > get_slice_density(Utils::Vector3i const &lower_corner, Utils::Vector3i const &upper_corner) const =0
Get slice density.
virtual std::size_t stencil_size() const noexcept=0
Number of discretized velocities in the PDF.
virtual void set_collision_model(double kT, unsigned int seed)=0
Configure the default collision model.
virtual bool set_node_velocity_at_boundary(Utils::Vector3i const &node, Utils::Vector3d const &velocity)=0
Set node velocity boundary conditions.
virtual Utils::Vector3d get_momentum() const =0
Calculate momentum of the local domain.
virtual bool is_double_precision() const noexcept=0
Whether kernels use double-precision floating point numbers.
virtual std::optional< double > get_node_density(Utils::Vector3i const &node, bool consider_ghosts=false) const =0
Get node density.
virtual std::size_t get_velocity_field_id() const noexcept=0
get the velocity field id
virtual std::vector< double > get_slice_population(Utils::Vector3i const &lower_corner, Utils::Vector3i const &upper_corner) const =0
Get slice population.
virtual void add_forces_at_pos(std::vector< Utils::Vector3d > const &positions, std::vector< Utils::Vector3d > const &forces)=0
Interpolate forces to the stored forces to be applied on nodes in the next time step.
virtual std::vector< std::optional< Utils::Vector3d > > get_slice_velocity_at_boundary(Utils::Vector3i const &lower_corner, Utils::Vector3i const &upper_corner) const =0
Get slice velocity boundary conditions.
virtual std::optional< std::vector< double > > get_node_population(Utils::Vector3i const &node, bool consider_ghosts=false) const =0
Get node population.
virtual void reallocate_ubb_field()=0
Rebuild the UBB field.
virtual void set_slice_population(Utils::Vector3i const &lower_corner, Utils::Vector3i const &upper_corner, std::vector< double > const &population)=0
Set slice population.
virtual std::optional< Utils::Vector3d > get_node_force_to_be_applied(Utils::Vector3i const &node) const =0
Get stored force to be applied on node in the next time step.
virtual bool set_node_population(Utils::Vector3i const &node, std::vector< double > const &population)=0
Set node population.
virtual unsigned int get_seed() const noexcept=0
Get the RNG seed (if thermalized).
virtual double get_kT() const noexcept=0
Get the fluid temperature (if thermalized).
virtual void set_rng_state(uint64_t counter)=0
Set the RNG counter (if thermalized).
virtual std::size_t get_force_field_id() const noexcept=0
get the force field id
virtual Utils::Vector3d get_external_force() const noexcept=0
Get the global external force.
virtual void update_boundary_from_shape(std::vector< int > const &, std::vector< double > const &)=0
Update boundary conditions from a rasterized shape.
virtual std::vector< double > get_slice_pressure_tensor(Utils::Vector3i const &lower_corner, Utils::Vector3i const &upper_corner) const =0
Get slice pressure tensor.
virtual void set_slice_density(Utils::Vector3i const &lower_corner, Utils::Vector3i const &upper_corner, std::vector< double > const &density)=0
Set slice density.
virtual void integrate()=0
Integrate LB for one time step.
virtual void set_viscosity(double viscosity)=0
Set the fluid viscosity.
virtual bool set_node_density(Utils::Vector3i const &node, double density)=0
Set node density.
virtual void check_lebc(unsigned int shear_direction, unsigned int shear_plane_normal) const =0
Check Lees-Edwards boundary conditions.
virtual void ghost_communication()=0
Perform a full ghost communication.
virtual void set_external_force(Utils::Vector3d const &ext_force)=0
Set a global external force.
virtual void set_slice_velocity(Utils::Vector3i const &lower_corner, Utils::Vector3i const &upper_corner, std::vector< double > const &velocity)=0
Set slice velocity.
virtual std::optional< Utils::Vector3d > get_node_boundary_force(Utils::Vector3i const &node) const =0
Get (stored) force applied on node due to boundary condition.
virtual std::vector< bool > get_slice_is_boundary(Utils::Vector3i const &lower_corner, Utils::Vector3i const &upper_corner) const =0
Check if slice has velocity boundary conditions.
virtual bool set_node_velocity(Utils::Vector3i const &node, Utils::Vector3d const &v)=0
Set node velocity.
virtual double get_viscosity() const noexcept=0
Get the fluid viscosity.
virtual void set_slice_last_applied_force(Utils::Vector3i const &lower_corner, Utils::Vector3i const &upper_corner, std::vector< double > const &force)=0
Set stored force that was applied on slice in the last time step.
virtual void ghost_communication_pdf()=0
Perform a ghost communication of the PDF field.
virtual std::vector< Utils::Vector3d > get_velocities_at_pos(std::vector< Utils::Vector3d > const &pos)=0
Get interpolated velocities at positions.
virtual std::optional< Utils::VectorXd< 9 > > get_node_pressure_tensor(Utils::Vector3i const &node) const =0
Get node pressure tensor.
virtual void ghost_communication_vel()=0
Perform a ghost communication of the velocity field.
virtual std::vector< double > get_slice_last_applied_force(Utils::Vector3i const &lower_corner, Utils::Vector3i const &upper_corner) const =0
Get stored force that was applied on slice in the last time step.
~LBWalberlaBase() override=default
Abstract representation of a lattice-based model.
static Utils::Vector3d velocity(Particle const &p_ref, Particle const &p_vs)
Velocity of the virtual site.
Definition relative.cpp:64
Pack Lees-Edwards parameters for LB.