Debian Codegraph @

include/deal.II/base/polynomials_piecewise.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2013 - 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 #ifndef dealii_polynomials_piecewise_h
16 #define dealii_polynomials_piecewise_h
17
18
19
20 #include <deal.II/base/config.h>
21
22 #include <deal.II/base/enable_observer_pointer.h>
23 #include <deal.II/base/exceptions.h>
24 #include <deal.II/base/point.h>
25 #include <deal.II/base/polynomial.h>
26
27 #include <vector>
28
29 DEAL_II_NAMESPACE_OPEN
30
31 /**
32 * @addtogroup Polynomials
33 * @{
34 */
35
36 /**
37 * A namespace in which classes relating to the description of 1d polynomial
38 * spaces are declared.
39 */
40 namespace Polynomials
41 {
42 /**
43 * Definition of piecewise 1d polynomials for the unit interval. This space
44 * allows the description of interpolating polynomials on parts of the unit
45 * interval, similarly to the definition of finite element basis functions
46 * on subdivided elements. The primary purpose of this class is to
47 * allow constructing the shape functions of the FE_Q_iso_Q1 class that has
48 * a number of interpolation points in each coordinate direction, but instead
49 * of using them for higher-order polynomials just chooses piecewise linear
50 * shape functions -- in effect, it is a $Q_1$ element defined on a
51 * subdivision of the reference cell, and replicated on each of these
52 * sub-cells.
53 *
54 * This class is not derived from the ScalarPolynomialsBase base class
55 * because it is not actually a polynomial -- it is a piecewise polynomial.
56 * However, it is interface-compatible with the Polynomials::Polynomial
57 * class, and consequently can be used as template argument for
58 * TensorProductPolynomials.
59 *
60 * @ingroup Polynomials
61 */
62 template <typename number>
63 class PiecewisePolynomial : public EnableObserverPointer
64 {
65 public:
66 /**
67 * Constructor for Lagrange polynomial on an interval that is a subset of
68 * the unit interval. It uses a polynomial description that is scaled to
69 * the size of the subinterval compared to the unit interval, the total
70 * number of intervals (subdivisions), the current index of the interval
71 * as well as if the polynomial spans onto the next interval (e.g., if it
72 * lives on two neighboring intervals).
73 *
74 * If the number of intervals is one, the piecewise polynomial behaves
75 * exactly like a usual polynomial.
76 */
77 PiecewisePolynomial(const Polynomial<number> &coefficients_on_interval,
78 const unsigned int n_intervals,
79 const unsigned int interval,
80 const bool spans_next_interval);
81
82 /**
83 * Constructor for linear Lagrange polynomial on an interval that is a
84 * subset of the unit interval. It uses a polynomial description that is
85 * scaled to the size of the subinterval compared to the unit interval.
86 * The subintervals are bounded by the adjacent points in @p points.
87 */
88 PiecewisePolynomial(const std::vector<Point<1, number>> &points,
89 const unsigned int index);
90
91 /**
92 * Return the value of this polynomial at the given point, evaluating the
93 * underlying polynomial. The polynomial evaluates to zero when outside of
94 * the given interval (and possible the next one to the right when it
95 * spans over that range).
96 */
97 number
98 value(const number x) const;
99
100 /**
101 * Return the values and the derivatives of the Polynomial at point
102 * <tt>x</tt>. <tt>values[i], i=0,...,values.size()-1</tt> includes the
103 * <tt>i</tt>th derivative. The number of derivatives to be computed is
104 * thus determined by the size of the vector passed.
105 *
106 * Note that all the derivatives evaluate to zero at the border between
107 * intervals (assuming exact arithmetic) in the interior of the unit
108 * interval, as there is no unique gradient value in that case for a
109 * piecewise polynomial. This is not always desired (e.g., when evaluating
110 * jumps of gradients on the element boundary), but it is the user's
111 * responsibility to avoid evaluation at these points when it does not
112 * make sense.
113 */
114 void
115 value(const number x, std::vector<number> &values) const;
116
117 /**
118 * Return the values and the derivatives of the Polynomial at point
119 * <tt>x</tt>. <tt>values[i], i=0,...,n_derivatives</tt> includes the
120 * <tt>i</tt>th derivative.The number of derivatives to be computed is
121 * determined by @p n_derivatives and @p values has to provide sufficient
122 * space for @p n_derivatives + 1 values.
123 *
124 * Note that all the derivatives evaluate to zero at the border between
125 * intervals (assuming exact arithmetic) in the interior of the unit
126 * interval, as there is no unique gradient value in that case for a
127 * piecewise polynomial. This is not always desired (e.g., when evaluating
128 * jumps of gradients on the element boundary), but it is the user's
129 * responsibility to avoid evaluation at these points when it does not
130 * make sense.
131 */
132 void
133 value(const number x,
134 const unsigned int n_derivatives,
135 number *values) const;
136
137 /**
138 * Degree of the polynomial. This is the degree of the underlying base
139 * polynomial.
140 */
141 unsigned int
142 degree() const;
143
144 /**
145 * Write or read the data of this object to or from a stream for the
146 * purpose of serialization using the [BOOST serialization
147 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
148 */
149 template <class Archive>
150 void
151 serialize(Archive &ar, const unsigned int version);
152
153 /**
154 * Return an estimate (in bytes) for the memory consumption of this object.
155 */
156 virtual std::size_t
157 memory_consumption() const;
158
159 protected:
160 /**
161 * Underlying polynomial object that is scaled to a subinterval and
162 * concatenated accordingly.
163 */
164 Polynomial<number> polynomial;
165
166 /**
167 * A variable storing the number of intervals that the unit interval is
168 * divided into.
169 */
170 unsigned int n_intervals;
171
172 /**
173 * A variable storing the index of the current polynomial in the range of
174 * intervals.
175 */
176 unsigned int interval;
177
178 /**
179 * Store if the polynomial spans over two adjacent intervals, i.e., the
180 * one given in subinterval and the next one.
181 */
182 bool spans_two_intervals;
183
184 /**
185 * Points bounding the subintervals in the case that piecewise linear
186 * polynomial on varying subintervals is requested.
187 */
188 std::vector<number> points;
189
190 /**
191 * Precomputed inverses of the lengths of the subintervals, i.e.,
192 * `one_over_lengths[i] = 1.0 / (points[i + 1] - points[i]`.
193 */
194 std::vector<number> one_over_lengths;
195
196 /**
197 * A variable storing the index of the current polynomial in the case that
198 * piecewise linear polynomial on varying subintervals is requested.
199 */
200 unsigned int index;
201 };
202
203
204
205 /**
206 * Generates a complete Lagrange basis on a subdivision of the unit interval
207 * in smaller intervals for a given degree on the subintervals and number of
208 * intervals.
209 */
210 std::vector<PiecewisePolynomial<double>>
211 generate_complete_Lagrange_basis_on_subdivisions(
212 const unsigned int n_subdivisions,
213 const unsigned int base_degree);
214
215 /**
216 * Generates a complete linear basis on a subdivision of the unit interval
217 * in smaller intervals for a given vector of points.
218 */
219 std::vector<PiecewisePolynomial<double>>
220 generate_complete_linear_basis_on_subdivisions(
221 const std::vector<Point<1>> &points);
222
223 } // namespace Polynomials
224
225
226 /** @} */
227
228 /* -------------------------- inline functions --------------------- */
229
230 namespace Polynomials
231 {
232 template <typename number>
233 inline unsigned int
234 PiecewisePolynomial<number>::degree() const
235 {
236 if (points.size() > 0)
237 return 1;
238 return polynomial.degree();
239 }
240
241
242
243 template <typename number>
244 inline number
245 PiecewisePolynomial<number>::value(const number x) const
246 {
247 if (points.size() > 0)
248 {
249 if (x > points[index])
250 return std::max<number>(0.0,
251 1.0 - (x - points[index]) *
252 one_over_lengths[index]);
253 else if (x < points[index])
254 return std::max<number>(0.0,
255 0.0 + (x - points[index - 1]) *
256 one_over_lengths[index - 1]);
257 else
258 return 1.0;
259 }
260
261 AssertIndexRange(interval, n_intervals);
262 number y = x;
263 // shift polynomial if necessary
264 if (n_intervals > 1)
265 {
266 const number step = 1. / n_intervals;
267
268 // polynomial spans over two intervals
269 if (spans_two_intervals == true)
270 {
271 const number offset = step * interval;
272 if (x < offset)
273 return 0;
274 else if (x > offset + step + step)
275 return 0;
276 else if (x < offset + step)
277 y = x - offset;
278 else
279 y = offset + step + step - x;
280 }
281 else
282 {
283 const number offset = step * interval;
284 if (x < offset || x > offset + step)
285 return 0;
286 else
287 y = x - offset;
288 }
289
290 return polynomial.value(y);
291 }
292 else
293 return polynomial.value(x);
294 }
295
296
297
298 template <typename number>
299 template <class Archive>
300 inline void
301 PiecewisePolynomial<number>::serialize(Archive &ar, const unsigned int)
302 {
303 // forward to serialization function in the base class.
304 ar &static_cast<EnableObserverPointer &>(*this);
305 ar &polynomial;
306 ar &n_intervals;
307 ar &interval;
308 ar &spans_two_intervals;
309 ar &points;
310 ar &one_over_lengths;
311 ar &index;
312 }
313 } // namespace Polynomials
314
315 DEAL_II_NAMESPACE_CLOSE
316
317 #endif