| 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 |