Debian Codegraph @

include/deal.II/sundials/n_vector.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2021 - 2024 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15
16 #ifndef dealii_sundials_n_vector_h
17 #define dealii_sundials_n_vector_h
18
19 #include <deal.II/base/config.h>
20
21 #ifdef DEAL_II_WITH_SUNDIALS
22 # include <sundials/sundials_nvector.h>
23
24 # include <functional>
25 # include <memory>
26
27 DEAL_II_NAMESPACE_OPEN
28
29 # ifndef DOXYGEN
30 namespace SUNDIALS
31 {
32 namespace internal
33 {
34 template <typename VectorType>
35 class NVectorView;
36 }
37 } // namespace SUNDIALS
38 # endif
39
40 namespace SUNDIALS
41 {
42 namespace internal
43 {
44 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
45 /**
46 * Create a NVectorView of the given @p vector.
47 *
48 * This call is intended to be used as
49 *
50 * @code
51 * auto view = make_nvector_view(vector);
52 * @endcode
53 *
54 * The resulting object `view` must be kept around as long as any other
55 * object will use the internally viewed N_Vector.
56 *
57 * @tparam VectorType Type of the viewed vector. This parameter can be
58 * deduced automatically and will respect a potential const-qualifier.
59 * @param vector The vector to view.
60 * @param nvector_context A SUNDIALS context object to be used for the
61 * operations we want to do on this vector.
62 * @return A NVectorView of the @p vector.
63 *
64 * @related NVectorView
65 *
66 * @note Versions of this function prior to SUNDIALS 6.0 did not take a
67 * SUNContext argument.
68 */
69 template <typename VectorType>
70 NVectorView<VectorType>
71 make_nvector_view(VectorType &vector, SUNContext nvector_context);
72 # else
73 /**
74 * Create a NVectorView of the given @p vector.
75 *
76 * This call is intended to be used as
77 *
78 * @code
79 * auto view = make_nvector_view(vector);
80 * @endcode
81 *
82 * The resulting object `view` must be kept around as long as any other
83 * object will use the internally viewed N_Vector.
84 *
85 * @tparam VectorType Type of the viewed vector. This parameter can be
86 * deduced automatically and will respect a potential const-qualifier.
87 * @param vector The vector to view.
88 * @param nvector_context A SUNDIALS context object to be used for the
89 * operations we want to do on this vector.
90 * @return A NVectorView of the @p vector.
91 *
92 * @related NVectorView
93 *
94 * @note This version of make_nvector_view() is only for versions of
95 * SUNDIALS prior to 6.0 which did not need a SUNContext object to set up a
96 * vector.
97 */
98 template <typename VectorType>
99 NVectorView<VectorType>
100 make_nvector_view(VectorType &vector);
101 # endif
102
103 /**
104 * Retrieve the underlying vector attached to N_Vector @p v. This call will
105 * only succeed if the underlying vector is not const. Use
106 * unwrap_nvector_const() for this case.
107 *
108 * @note Users must ensure that they ask for the correct VectorType when
109 * calling this function and there are no type-safety checks in place.
110 *
111 * @tparam VectorType Type of the vector that is stored in @p v
112 * @param v Vector to unwrap
113 * @return The vector that is stored inside @p v
114 */
115 template <typename VectorType>
116 VectorType *
117 unwrap_nvector(N_Vector v);
118
119 /**
120 * Retrieve the underlying vector attached to N_Vector @p v as a constant
121 * pointer.
122 *
123 * @note Users must ensure that they ask for the correct VectorType when
124 * calling this function and there are no type-safety checks in place.
125 *
126 * @tparam VectorType Type of the vector that is stored in @p v
127 * @param v Vector to unwrap
128 * @return The vector that is stored inside @p v
129 */
130 template <typename VectorType>
131 const VectorType *
132 unwrap_nvector_const(N_Vector v);
133
134 /**
135 * A view to a vector which can be used whenever a N_Vector is required.
136 *
137 * Objects of this class should preferably be created by
138 * make_nvector_view() as
139 *
140 * @code
141 * auto view = make_nvector_view(vector);
142 * @endcode
143 *
144 * The resulting N_Vector is a view of the actual vector and not owning
145 * memory. Also, N_VDestroy() cannot be called on the resulting N_Vector
146 * since this would lead to a double delete in the destructor.
147 *
148 * @note SUNDIALS will never call N_VDestroy() on a vector it didn't create
149 * itself and thus the above constraint is not limiting the user.
150 *
151 * @tparam VectorType Type of the vector that is stored in @p v
152 */
153 template <typename VectorType>
154 class NVectorView
155 {
156 public:
157 /**
158 * Default constructor.
159 *
160 * The object is not actually viewing anything and needs to be assigned to
161 * with operator=(NVectorView &&).
162 */
163 NVectorView() = default;
164
165 # if DEAL_II_SUNDIALS_VERSION_GTE(6, 0, 0)
166 /**
167 * Constructor. Create view of @p vector.
168 *
169 * @note Versions of this function prior to SUNDIALS 6.0 did not take a
170 * SUNContext argument.
171 */
172 NVectorView(VectorType &vector, SUNContext nvector_context);
173 # else
174 /**
175 * Constructor. Create view of @p vector.
176 *
177 * @note This constructor is only for versions of SUNDIALS prior to 6.0
178 * which do not need a SUNContext object to set up a vector.
179 */
180 NVectorView(VectorType &vector);
181 # endif
182
183 /**
184 * Move assignment.
185 */
186 NVectorView(NVectorView &&) noexcept = default;
187
188 /**
189 * Move constructor.
190 */
191 NVectorView &
192 operator=(NVectorView &&) noexcept = default;
193
194 /**
195 * Explicitly delete copy ctor. This class is move-only.
196 */
197 NVectorView(const NVectorView &) = delete;
198
199 /**
200 * Explicitly delete copy assignment. This class is move-only.
201 */
202 NVectorView &
203 operator=(const NVectorView &) = delete;
204
205 /**
206 * Destructor.
207 *
208 * @note This will not destroy the viewed vector.
209 */
210 ~NVectorView() = default;
211
212 /**
213 * Implicit conversion to N_Vector. This operator makes the NVectorView
214 * look like an actual N_Vector and it can be used directly as an
215 * argument in many SUNDIALS functions.
216 */
217 operator N_Vector() const;
218
219 /**
220 * Access the N_Vector that is viewed by this object.
221 */
222 N_Vector
223 operator->() const;
224
225 private:
226 /**
227 * Actual pointer to a vector viewed by this class.
228 */
229 std::unique_ptr<_generic_N_Vector, std::function<void(N_Vector)>>
230 vector_ptr;
231 };
232 } // namespace internal
233 } // namespace SUNDIALS
234
235
236 DEAL_II_NAMESPACE_CLOSE
237
238 #else
239
240 // Make sure the scripts that create the C++20 module input files have
241 // something to latch on if the preprocessor #ifdef above would
242 // otherwise lead to an empty content of the file.
243 DEAL_II_NAMESPACE_OPEN
244 DEAL_II_NAMESPACE_CLOSE
245
246 #endif
247 #endif