Debian Codegraph @

include/deal.II/numerics/histogram.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 2023 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_histogram_h
16 #define dealii_histogram_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22
23 #include <deal.II/lac/vector.h>
24
25 #include <string>
26 #include <vector>
27
28 DEAL_II_NAMESPACE_OPEN
29
30
31 /**
32 * This class provides some facilities to generate 2d and 3d histograms. It is
33 * used by giving it one or several data sets and a rule how to break the
34 * range of values therein into intervals (e.g. linear spacing or logarithmic
35 * spacing of intervals). The values are then sorted into the different
36 * intervals and the number of values in each interval is stored for output
37 * later. In case only one data set was given, the resulting histogram will be
38 * a 2d one, while it will be a 3d one if more than one data set was given.
39 * For more than one data set, the same intervals are used for each of them
40 * anyway, to make comparison easier.
41 *
42 *
43 * <h3>Ways to generate the intervals</h3>
44 *
45 * At present, the following schemes for interval spacing are implemented:
46 * <ul>
47 * <li> Linear spacing: The intervals are distributed in constant steps
48 * between the minimum and maximum values of the data.
49 * <li> Logarithmic spacing: The intervals are distributed in constant steps
50 * between the minimum and maximum values of the logs of the values. This
51 * scheme is only useful if the data has only positive values. Negative and
52 * zero values are sorted into the leftmost interval.
53 * </ul>
54 *
55 * To keep programs extensible, you can use the two functions @p
56 * get_interval_spacing_names and @p parse_interval_spacing, which always give
57 * you a complete list of spacing formats presently supported and are able to
58 * generate the respective value of the @p enum. If you use them, you can
59 * write your program in a way such that it only needs to be recompiled to
60 * take effect of newly added formats, without changing your code.
61 *
62 *
63 * <h3>Output formats</h3>
64 *
65 * At present, only GNUPLOT output is supported.
66 *
67 *
68 * @ingroup textoutput
69 */
70 class Histogram
71 {
72 public:
73 /**
74 * Definition of several ways to arrange the spacing of intervals.
75 */
76 enum IntervalSpacing
77 {
78 /**
79 * Space intervals linearly.
80 */
81 linear,
82 /**
83 * Space intervals logarithmically.
84 */
85 logarithmic
86 };
87
88
89 /**
90 * Take several lists of values, each on to produce one histogram that will
91 * then be arrange one behind each other.
92 *
93 * Using several data sets at once allows to compare them more easily, since
94 * the intervals into which the data is sorted is the same for all data
95 * sets.
96 *
97 * The histograms will be arranged such that the computed intervals of the
98 * <tt>values[i][j]</tt> form the x-range, and the number of values in each
99 * interval will be the y-range (for 2d plots) or the z-range (for 3d
100 * plots). For 3d plots, the @p y_values parameter is used to assign each
101 * data set a value in the y direction, which is the depth coordinate in the
102 * resulting plot. For 2d plots, the @p y_values are ignored.
103 *
104 * If you give only one data set, i.e. <tt>values.size()==1</tt>, then the
105 * resulting histogram will be a 2d one.
106 *
107 * @p n_intervals denotes the number of intervals into which the data will
108 * be sorted; @p interval_spacing denotes the way the bounds of the
109 * intervals are computed. Refer to the general documentation for more
110 * information on this.
111 */
112 template <typename number>
113 void
114 evaluate(const std::vector<Vector<number>> &values,
115 const std::vector<double> &y_values,
116 const unsigned int n_intervals,
117 const IntervalSpacing interval_spacing = linear);
118
119 /**
120 * This function is only a wrapper to the above one in case you have only
121 * one data set.
122 */
123 template <typename number>
124 void
125 evaluate(const Vector<number> &values,
126 const unsigned int n_intervals,
127 const IntervalSpacing interval_spacing = linear);
128
129 /**
130 * Write the histogram computed by the @p evaluate function to a stream in a
131 * format suitable to the GNUPLOT program. The function generates 2d or 3d
132 * histograms.
133 */
134 void
135 write_gnuplot(std::ostream &out) const;
136
137 /**
138 * Return allowed names for the interval spacing as string. At present this
139 * is "linear|logarithmic".
140 */
141 static std::string
142 get_interval_spacing_names();
143
144 /**
145 * Get a string containing one of the names returned by the above function
146 * and return the respective value of @p IntervalSpacing. Throw an error if
147 * the string is no valid one.
148 */
149 static IntervalSpacing
150 parse_interval_spacing(const std::string &name);
151
152 /**
153 * Determine an estimate for the memory consumption (in bytes) of this
154 * object.
155 */
156 std::size_t
157 memory_consumption() const;
158
159 /**
160 * Exception.
161 */
162 DeclExceptionMsg(ExcEmptyData,
163 "Your input argument to this function does not appear to "
164 "have any data in it.");
165 /**
166 * Exception.
167 */
168 DeclException2(ExcIncompatibleArraySize,
169 int,
170 int,
171 << "The two array sizes " << arg1 << " and " << arg2
172 << " must match, but don't.");
173 /**
174 * Exception.
175 */
176 DeclException1(ExcInvalidName,
177 std::string,
178 << "The given name <" << arg1
179 << "> does not match any of the known formats.");
180
181 private:
182 /**
183 * Structure denoting one interval.
184 */
185 struct Interval
186 {
187 /**
188 * Constructor. Sets the bounds and sets the number of values in this
189 * interval to zero.
190 */
191 Interval(const double left_point, const double right_point);
192
193 /**
194 * Determine an estimate for the memory consumption (in bytes) of this
195 * object.
196 */
197 std::size_t
198 memory_consumption() const;
199
200 /**
201 * Left bound of the interval.
202 */
203 double left_point;
204
205 /**
206 * Right bound of the interval.
207 */
208 double right_point;
209
210 /**
211 * Number of values in this interval.
212 */
213 unsigned int content;
214 };
215
216 /**
217 * "Less-than" operation which finds the minimal positive value by sorting
218 * zero and negative value to be larger than the largest positive number.
219 * Used to find the lower bound of the leftmost interval in the logarithmic
220 * case interval spacing scheme.
221 *
222 * Return @p true, if (<tt>n1<n2</tt>, and (<tt>n1>0</tt> or
223 * <tt>n2<0</tt>)), or (n2<n1 and n1>0 and n2<=0). This in effect sorts all
224 * negative numbers to be larger than the largest positive number.
225 */
226 template <typename number>
227 static bool
228 logarithmic_less(const number n1, const number n2);
229
230 /**
231 * Vector holding one set of intervals for each data set given to the @p
232 * evaluate function.
233 */
234 std::vector<std::vector<Interval>> intervals;
235
236 /**
237 * Values for the depth axis of 3d histograms. Stored in the @p evaluate
238 * function.
239 */
240 std::vector<double> y_values;
241 };
242
243
244 DEAL_II_NAMESPACE_CLOSE
245
246 #endif