Line data Source code
1 0 : // Distributed under the MIT License.
2 : // See LICENSE.txt for details.
3 :
4 : #pragma once
5 :
6 : #include <cstddef>
7 : #include <optional>
8 :
9 : #include "Utilities/Gsl.hpp"
10 :
11 : /// \cond
12 : class DataVector;
13 : class Matrix;
14 : template <size_t>
15 : class Mesh;
16 : template <typename TagsList>
17 : class Variables;
18 : /// \endcond
19 :
20 : namespace Spectral::filtering {
21 : /*!
22 : * \brief Filters the tensors stored within a `Variables` being represented by
23 : * ZernikeB2 basis functions, with an optional exponential roll-off and an
24 : * optional top-mode cutoff.
25 : *
26 : * \details Representing functions on a filled disk requires special basis
27 : * functions, namely ZernikeB2. These are inherently two-dimensional, meaning
28 : * the radial and angular spectral spaces are intertwined. This function goes
29 : * to that combined modal space, applies the filter, and transforms back.
30 : *
31 : * When `half_power` has a value, a smooth exponential roll-off (see
32 : * exponential_filter()) is applied to the combined radial-angular modes using
33 : * the coefficient `alpha`. When `num_modes_to_kill` is nonzero, the highest
34 : * `num_modes_to_kill` angular (Fourier \f$m\f$) modes are additionally set to
35 : * zero, with the \f$m=0\f$ mode always retained. If `half_power` is
36 : * `std::nullopt` and `num_modes_to_kill` is zero this function is a no-op.
37 : *
38 : * \see exponential_filter()
39 : */
40 : template <typename TagsList>
41 1 : void zernike_b2_disk_filter(gsl::not_null<Variables<TagsList>*> u,
42 : const Mesh<2>& mesh, double alpha,
43 : std::optional<unsigned> half_power,
44 : size_t num_modes_to_kill);
45 :
46 : /*!
47 : * \brief Filters the tensors stored within a `Variables` being represented by
48 : * ZernikeB2 basis functions, with an optional exponential roll-off and an
49 : * optional top-mode cutoff.
50 : *
51 : * \details Overload taking a caller-managed working buffer. Avoids heap
52 : * allocation when the filter is applied repeatedly (e.g. in
53 : * `Filters::FilledCylinder`).
54 : */
55 : template <typename TagsList>
56 1 : void zernike_b2_disk_filter(gsl::not_null<Variables<TagsList>*> u,
57 : gsl::not_null<DataVector*> buf, const Mesh<2>& mesh,
58 : double alpha, std::optional<unsigned> half_power,
59 : size_t num_modes_to_kill);
60 :
61 : /*!
62 : * \brief Filters the tensors stored within a `Variables` being represented by
63 : * ZernikeB2 basis functions.
64 : *
65 : * \details Equivalent to `zernike_b2_disk_filter()` with `half_power` set and
66 : * no top-mode cutoff. Kept for callers that only want the exponential filter.
67 : *
68 : * \see exponential_filter()
69 : */
70 : template <typename TagsList>
71 1 : void zernike_b2_disk_exponential_filter(gsl::not_null<Variables<TagsList>*> u,
72 : const Mesh<2>& mesh, double alpha,
73 : unsigned half_power);
74 :
75 : /*!
76 : * \brief Filters the tensors stored within a `Variables` being represented by
77 : * ZernikeB2 \f$\times\f$ Legendre basis functions, with optional independent
78 : * roll-offs for the combined radial-angular disk modes and the axial \f$z\f$
79 : * modes plus an optional angular top-mode cutoff.
80 : *
81 : * \details Representing functions on a filled cylinder requires special basis
82 : * functions, namely a filled disk with ZernikeB2 cross Legendre. This requires
83 : * inherently two-dimensional basis functions, meaning the radial and angular
84 : * spectral spaces are intertwined. This function goes to that combined modal
85 : * space, applies the disk filter, transforms back, and then filters the third
86 : * I1 dimension.
87 : *
88 : * The combined radial-angular (disk) modes are filtered with an exponential
89 : * roll-off when `radial_angular_half_power` has a value and with a top-mode
90 : * cutoff of the highest `num_modes_to_kill` angular (Fourier \f$m\f$) modes
91 : * when `num_modes_to_kill` is nonzero (the \f$m=0\f$ mode is always retained).
92 : * The axial \f$z\f$ direction is filtered with an independent exponential
93 : * roll-off when `z_half_power` has a value. The coefficient `alpha` is shared
94 : * by all exponential roll-offs. Any direction whose half-power is
95 : * `std::nullopt` (and, for the disk, with `num_modes_to_kill` zero) is left
96 : * untouched.
97 : *
98 : * While the radial-angular plane is fixed to ZernikeB2 \f$\times\f$ Fourier,
99 : * the axial \f$z\f$ filter is applied with exponential_filter() in whatever 1D
100 : * spectral basis the mesh uses in the \f$z\f$ direction, so both Legendre and
101 : * Chebyshev (with any quadrature) are supported there.
102 : *
103 : * \see exponential_filter()
104 : */
105 : template <typename TagsList>
106 1 : void zernike_b2_cylinder_filter(
107 : gsl::not_null<Variables<TagsList>*> u, const Mesh<3>& mesh, double alpha,
108 : std::optional<unsigned> radial_angular_half_power,
109 : std::optional<unsigned> z_half_power, size_t num_modes_to_kill);
110 :
111 : /*!
112 : * \brief Filters the tensors stored within a `Variables` being represented by
113 : * ZernikeB2 \f$\times\f$ Legendre basis functions, with optional independent
114 : * roll-offs for the combined radial-angular disk modes and the axial \f$z\f$
115 : * modes plus an optional angular top-mode cutoff.
116 : *
117 : * \details Overload taking a caller-managed working buffer. Avoids heap
118 : * allocation when the filter is applied repeatedly (e.g. in
119 : * `Filters::FilledCylinder`). One can optionally pass the exponential filter
120 : * to apply in the z direction, otherwise it will be computed.
121 : *
122 : */
123 : template <typename TagsList>
124 1 : void zernike_b2_cylinder_filter(
125 : gsl::not_null<Variables<TagsList>*> u, gsl::not_null<DataVector*> buf,
126 : const Mesh<3>& mesh, double alpha,
127 : std::optional<unsigned> radial_angular_half_power,
128 : std::optional<unsigned> z_half_power, size_t num_modes_to_kill,
129 : const std::optional<Matrix>& z_filter);
130 :
131 : /*!
132 : * \brief Filters the tensors stored within a `Variables` being represented by
133 : * ZernikeB2 \f$\times\f$ Legendre basis functions.
134 : *
135 : * \details Equivalent to `zernike_b2_cylinder_filter()` with both the disk and
136 : * axial half-powers set to `half_power` and no top-mode cutoff. Kept for
137 : * callers that only want a single exponential filter applied everywhere.
138 : *
139 : * \see exponential_filter()
140 : */
141 : template <typename TagsList>
142 1 : void zernike_b2_cylinder_exponential_filter(
143 : gsl::not_null<Variables<TagsList>*> u, const Mesh<3>& mesh, double alpha,
144 : unsigned half_power);
145 : } // namespace Spectral::filtering
|
