Debian Codegraph @

include/deal.II/base/function_restriction.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 #ifndef dealii_function_restriction_h
16 #define dealii_function_restriction_h
17
18 #include <deal.II/base/function.h>
19 #include <deal.II/base/observer_pointer.h>
20 #include <deal.II/base/point.h>
21 #include <deal.II/base/tensor.h>
22
23 DEAL_II_NAMESPACE_OPEN
24
25 namespace Functions
26 {
27 /**
28 * This class takes a function in `dim + 1` dimensions and creates a new
29 * function in one dimension lower by restricting one of the coordinates to a
30 * given value. Mathematically this corresponds to taking a function
31 * $f = f(x, y, z)$,
32 * a fixed value, $Z$, and defining a new function (the restriction)
33 * $g = g(x, y) = f(x, y, Z)$.
34 * Using this class, this translates to
35 * @code
36 * Function<3> & function = ...
37 * double z = ...
38 * unsigned int restricted_direction = 2;
39 * CoordinateRestriction<2> restriction(function, restricted_direction, z);
40 * @endcode
41 *
42 * The `dim`-dimensional coordinates on the restriction are ordered starting
43 * from the restricted (`dim + 1`)-coordinate. In particular, this means that
44 * if the $y$-coordinate is locked to $Y$ in 3d, the coordinates are ordered
45 * as $(z, x)$ on the restriction:
46 * $g = g(z, x) = f(x, Y, z)$.
47 * This is the same convention as in BoundingBox::cross_section.
48 */
49 template <int dim>
50 class CoordinateRestriction : public Function<dim>
51 {
52 public:
53 /**
54 * Constructor, takes the (`dim + 1`)-coordinate direction and the value
55 * that the incoming function should be restricted to.
56 *
57 * A pointer to the incoming function is stored internally, so the function
58 * must have a longer lifetime than the created restriction.
59 */
60 CoordinateRestriction(const Function<dim + 1> &function,
61 const unsigned int direction,
62 const double coordinate_value);
63
64 double
65 value(const Point<dim> &point, const unsigned int component) const override;
66
67 Tensor<1, dim>
68 gradient(const Point<dim> &point,
69 const unsigned int component) const override;
70
71 SymmetricTensor<2, dim>
72 hessian(const Point<dim> &point,
73 const unsigned int component) const override;
74
75 private:
76 // The higher-dimensional function that has been restricted.
77 const ObserverPointer<const Function<dim + 1>> function;
78
79 // The (`dim + 1`)-coordinate direction that has been restricted.
80 const unsigned int restricted_direction;
81
82 // Value of the restricted coordinate.
83 const double coordinate_value;
84 };
85
86
87
88 /**
89 * This class creates a 1-dimensional function from a `dim + 1` dimensional
90 * function by restricting `dim` of the coordinate values to a given point.
91 * Mathematically this corresponds to taking a function, $f = f(x, y, z)$, and
92 * a point $(Y, Z)$, and defining a new function $g = g(x) = f(x, Y, Z)$.
93 * Using this class, this translates to
94 * @code
95 * Function<3> & function = ...
96 * Point<2> point(y, z);
97 * unsigned int open_direction = 0;
98 * PointRestriction<2> restriction(function, open_direction, point);
99 * @endcode
100 *
101 * The coordinates of the point will be expanded in the higher-dimensional
102 * functions coordinates starting from the open-direction (and wrapping
103 * around). In particular, if we restrict to a point $(Z, X)$ and choose to
104 * keep the y-direction open, the restriction that is created is the function
105 * $g(y) = f(X, y, Z)$.
106 * This is consistent with the convention in BoundingBox::cross_section.
107 */
108 template <int dim>
109 class PointRestriction : public Function<1>
110 {
111 public:
112 /**
113 * Constructor, takes the point that the incoming function should be
114 * restricted to and which (`dim + 1`)-dimensional coordinate direction
115 * should be kept "open".
116 *
117 * A pointer to the incoming function is stored internally, so the function
118 * must have a longer lifetime than the created restriction.
119 */
120 PointRestriction(const Function<dim + 1> &function,
121 const unsigned int open_direction,
122 const Point<dim> &point);
123
124 double
125 value(const Point<1> &point, const unsigned int component) const override;
126
127 Tensor<1, 1>
128 gradient(const Point<1> &point,
129 const unsigned int component) const override;
130
131 SymmetricTensor<2, 1>
132 hessian(const Point<1> &point, const unsigned int component) const override;
133
134 private:
135 // The higher-dimensional function that has been restricted.
136 const ObserverPointer<const Function<dim + 1>> function;
137
138 // The (`dim + 1`)-coordinate direction that is kept "open"
139 const unsigned int open_direction;
140
141 // The point that we have restricted the above function to.
142 const Point<dim> point;
143 };
144
145 } // namespace Functions
146
147
148 namespace internal
149 {
150 /**
151 * Creates a (`dim + 1`)-dimensional point by copying over the coordinates of
152 * the incoming `dim`-dimensional point and setting the "missing"
153 * (`dim + 1`)-dimensional component to the incoming coordinate value.
154 *
155 * For example, given the input
156 * $\{(x, y), 2, z \}$ this function creates the point $(x, y, z)$.
157 *
158 * The coordinates of the `dim`-dimensional point are written to the
159 * coordinates of the (`dim + 1`)-dimensional point in the order of the
160 * convention given by the function coordinate_to_one_dim_higher. Thus, the
161 * order of coordinates on the lower-dimensional point are not preserved:
162 * $\{(z, x), 1, y \}$ creates the point $(x, y, z)$.
163 */
164 template <int dim>
165 Point<dim + 1>
166 create_higher_dim_point(const Point<dim> &point,
167 const unsigned int component_in_dim_plus_1,
168 const double coordinate_value);
169 } // namespace internal
170
171 DEAL_II_NAMESPACE_CLOSE
172
173 #endif /* dealii_function_restriction_h */