| 1 |
// ------------------------------------------------------------------------ |
| 2 |
// |
| 3 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 4 |
// Copyright (C) 1999 - 2025 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_table_handler_h |
| 16 |
#define dealii_table_handler_h |
| 17 |
|
| 18 |
|
| 19 |
#include <deal.II/base/config.h> |
| 20 |
|
| 21 |
#include <deal.II/base/exceptions.h> |
| 22 |
|
| 23 |
#include <boost/serialization/map.hpp> |
| 24 |
#include <boost/serialization/split_member.hpp> |
| 25 |
#include <boost/serialization/string.hpp> |
| 26 |
#include <boost/serialization/vector.hpp> |
| 27 |
|
| 28 |
#include <cstdint> |
| 29 |
#include <map> |
| 30 |
#include <ostream> |
| 31 |
#include <string> |
| 32 |
#include <variant> |
| 33 |
#include <vector> |
| 34 |
|
| 35 |
|
| 36 |
DEAL_II_NAMESPACE_OPEN |
| 37 |
|
| 38 |
// Forward declaration |
| 39 |
#ifndef DOXYGEN |
| 40 |
class TableHandler; |
| 41 |
#endif |
| 42 |
|
| 43 |
namespace internal |
| 44 |
{ |
| 45 |
/** |
| 46 |
* A <tt>TableEntry</tt> stores the value of a table entry. It can either be |
| 47 |
* of type int, unsigned int, std::uint64_t, double or std::string. In |
| 48 |
* essence, this structure is the same as `std::variant<int,unsigned |
| 49 |
* int,std::uint64_t,double,std::string>` but we wrap this object in a |
| 50 |
* structure for which we can write a function that can serialize it. This is |
| 51 |
* also why the function is not in fact of type std::any. |
| 52 |
*/ |
| 53 |
struct TableEntry |
| 54 |
{ |
| 55 |
public: |
| 56 |
/** |
| 57 |
* Default constructor. |
| 58 |
*/ |
| 59 |
TableEntry() = default; |
| 60 |
|
| 61 |
/** |
| 62 |
* Constructor. Initialize this table element with the value |
| 63 |
* <code>t</code>. |
| 64 |
*/ |
| 65 |
template <typename T> |
| 66 |
explicit TableEntry(const T &t); |
| 67 |
|
| 68 |
/** |
| 69 |
* Return the value stored by this object. The template type T must be one |
| 70 |
* of <code>int,unsigned int,std::uint64_t,double,std::string</code> and it |
| 71 |
* must match the data type of the object originally stored in this |
| 72 |
* TableEntry object. |
| 73 |
*/ |
| 74 |
template <typename T> |
| 75 |
T |
| 76 |
get() const; |
| 77 |
|
| 78 |
/** |
| 79 |
* Return the numeric value of this object if data has been stored in it |
| 80 |
* either as an integer, an unsigned integer,std::uint64_t, or a double. |
| 81 |
* |
| 82 |
* @return double |
| 83 |
*/ |
| 84 |
double |
| 85 |
get_numeric_value() const; |
| 86 |
|
| 87 |
/** |
| 88 |
* Cache the contained value with the given formatting and return it. The |
| 89 |
* given parameters from the column definition are used for the |
| 90 |
* formatting. The value is cached as a string internally in cached_value. |
| 91 |
* The cache needs to be invalidated with this routine if the formatting |
| 92 |
* of the column changes. |
| 93 |
*/ |
| 94 |
void |
| 95 |
cache_string(bool scientific, unsigned int precision) const; |
| 96 |
|
| 97 |
/** |
| 98 |
* Return the value cached using cache_string(). This is just a wrapper |
| 99 |
* around cached_value. |
| 100 |
*/ |
| 101 |
const std::string & |
| 102 |
get_cached_string() const; |
| 103 |
|
| 104 |
|
| 105 |
/** |
| 106 |
* Return a TableEntry object that has the same data type of the stored |
| 107 |
* value but with a value that is default constructed for this data type. |
| 108 |
* This is used to pad columns below previously set ones. |
| 109 |
*/ |
| 110 |
TableEntry |
| 111 |
get_default_constructed_copy() const; |
| 112 |
|
| 113 |
/** |
| 114 |
* Write the data of this object to a stream for the purpose of |
| 115 |
* serialization using the [BOOST serialization |
| 116 |
* library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html). |
| 117 |
*/ |
| 118 |
template <class Archive> |
| 119 |
void |
| 120 |
save(Archive &ar, const unsigned int version) const; |
| 121 |
|
| 122 |
/** |
| 123 |
* Read the data of this object from a stream for the purpose of |
| 124 |
* serialization using the [BOOST serialization |
| 125 |
* library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html). |
| 126 |
*/ |
| 127 |
template <class Archive> |
| 128 |
void |
| 129 |
load(Archive &ar, const unsigned int version); |
| 130 |
|
| 131 |
#ifdef DOXYGEN |
| 132 |
/** |
| 133 |
* Write and read the data of this object from a stream for the purpose |
| 134 |
* of serialization using the [BOOST serialization |
| 135 |
* library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html). |
| 136 |
*/ |
| 137 |
template <class Archive> |
| 138 |
void |
| 139 |
serialize(Archive &archive, const unsigned int version); |
| 140 |
#else |
| 141 |
// This macro defines the serialize() method that is compatible with |
| 142 |
// the templated save() and load() method that have been implemented. |
| 143 |
BOOST_SERIALIZATION_SPLIT_MEMBER() |
| 144 |
#endif |
| 145 |
|
| 146 |
private: |
| 147 |
/** |
| 148 |
* Abbreviation for the data type stored by this object. |
| 149 |
*/ |
| 150 |
using value_type = |
| 151 |
std::variant<int, unsigned int, std::uint64_t, double, std::string>; |
| 152 |
|
| 153 |
/** |
| 154 |
* Stored value. |
| 155 |
*/ |
| 156 |
value_type value; |
| 157 |
|
| 158 |
/** |
| 159 |
* Cache the current value as a string. |
| 160 |
*/ |
| 161 |
mutable std::string cached_value; |
| 162 |
|
| 163 |
friend class dealii::TableHandler; |
| 164 |
}; |
| 165 |
} // namespace internal |
| 166 |
|
| 167 |
|
| 168 |
/** |
| 169 |
* The TableHandler stores TableEntries of arbitrary value type and writes the |
| 170 |
* table as text or in tex format to an output stream. The value type actually |
| 171 |
* may vary from column to column and from row to row. |
| 172 |
* |
| 173 |
* <h3>Usage</h3> |
| 174 |
* |
| 175 |
* The most important function is the templatized function |
| 176 |
* <code>add_value(const std::string &key, const T value)</code> that adds a |
| 177 |
* column with the name <tt>key</tt> to the table if this column does not yet |
| 178 |
* exist and adds the given value of type <tt>T</tt> (which must be one of |
| 179 |
* <tt>int</tt>, <tt>unsigned int</tt>, <tt>double</tt>, <tt>std::string</tt>) |
| 180 |
* to this column. After the table is complete there are different |
| 181 |
* possibilities of output, e.g., into a latex file with write_tex() or as |
| 182 |
* text with write_text(). |
| 183 |
* |
| 184 |
* Two (or more) columns may be merged into a "supercolumn" by twice (or |
| 185 |
* multiple) calling add_column_to_supercolumn(), see there. Additionally |
| 186 |
* there is a function to set for each column the precision of the output of |
| 187 |
* numbers, and there are several functions to prescribe the format and the |
| 188 |
* captions the columns are written with in tex mode. |
| 189 |
* |
| 190 |
* A detailed explanation of this class is also given in the step-13 tutorial |
| 191 |
* program. |
| 192 |
* |
| 193 |
* |
| 194 |
* <h3>Example</h3> |
| 195 |
* |
| 196 |
* This is a simple example demonstrating the usage of this class. The first |
| 197 |
* column includes the numbers $i=1 \dots n$, the second $1^2 \dots n^2$, the |
| 198 |
* third $\sqrt{1}\dots\sqrt{n}$, where the second and third columns are merged |
| 199 |
* into one supercolumn with the superkey <tt>squares and roots</tt>. |
| 200 |
* Additionally the first column is aligned to the right (the default was |
| 201 |
* <tt>centered</tt>) and the precision of the square roots are set to be 6 |
| 202 |
* (instead of 4 as default). |
| 203 |
* |
| 204 |
* @code |
| 205 |
* TableHandler table; |
| 206 |
* for (unsigned int i = 1; i <= n; ++i) |
| 207 |
* { |
| 208 |
* table.add_value("numbers", i); |
| 209 |
* table.add_value("squares", i * i); |
| 210 |
* table.add_value("square roots", std::sqrt(i)); |
| 211 |
* } |
| 212 |
* // merge the second and third column |
| 213 |
* table.add_column_to_supercolumn("squares", "squares and roots"); |
| 214 |
* table.add_column_to_supercolumn("square roots", "squares and roots"); |
| 215 |
* |
| 216 |
* // additional settings |
| 217 |
* table.set_tex_format("numbers", "r"); |
| 218 |
* table.set_precision("square roots", 6); |
| 219 |
* |
| 220 |
* // output |
| 221 |
* std::ofstream out_file("number_table.tex"); |
| 222 |
* table.write_tex(out_file); |
| 223 |
* out_file.close(); |
| 224 |
* @endcode |
| 225 |
* |
| 226 |
* |
| 227 |
* <h3>Dealing with sparse data: auto-fill mode</h3> |
| 228 |
* |
| 229 |
* When generating output, TableHandler expects that all columns have the |
| 230 |
* exact same number of elements in it so that the result is in fact a table. |
| 231 |
* This assumes that in each of the iterations (time steps, nonlinear |
| 232 |
* iterations, etc) you fill every single column. On the other hand, this may |
| 233 |
* not always be what you want to do. For example, it could be that the |
| 234 |
* function that computes the nonlinear residual is only called every few time |
| 235 |
* steps; or, a function computing statistics of the mesh is only called |
| 236 |
* whenever the mesh is in fact refined. In these cases, the add_value() |
| 237 |
* function will be called less often for some columns and the column would |
| 238 |
* therefore have fewer elements; furthermore, these elements would not be |
| 239 |
* aligned with the rows that contain the other data elements that were |
| 240 |
* produced during this iteration. An entirely different scenario is that the |
| 241 |
* table is filled and at a later time we use the data in there to compute the |
| 242 |
* elements of other rows; the ConvergenceTable class does something like |
| 243 |
* this. |
| 244 |
* |
| 245 |
* To support both scenarios, the TableHandler class has a property called <i |
| 246 |
* >auto-fill mode</i>. By default, auto-fill mode is off, but it can be |
| 247 |
* enabled by calling set_auto_fill_mode(). If auto-fill mode is enabled we |
| 248 |
* use the following algorithm: |
| 249 |
* |
| 250 |
* - When calling <code>add_value(key, value)</code>, we count the number of |
| 251 |
* elements in the column corresponding to <code>key</code>. Let's call this |
| 252 |
* number $m$. |
| 253 |
* |
| 254 |
* - We also determine the maximal number of elements in the other columns; |
| 255 |
* call it $n$. |
| 256 |
* |
| 257 |
* - If $m < n-1$ then we add $n-m-1$ copies of the object <code>T()</code> to |
| 258 |
* this column. Here, <code>T</code> is the data type of the given |
| 259 |
* <code>value</code>. For example, if <code>T</code> is a numeric type, then |
| 260 |
* <code>T()</code> is the number zero; if <code>T</code> is |
| 261 |
* <code>std::string</code>, then <code>T()</code> is the empty string |
| 262 |
* <code>""</code>. |
| 263 |
* |
| 264 |
* - Add the given value to this column. |
| 265 |
* |
| 266 |
* Padding the column with default elements makes sure that after the addition |
| 267 |
* the column has as many entries as the longest other column. In other words, |
| 268 |
* if we have skipped previous invocations of add_value() for a given key, |
| 269 |
* then the padding will enter default values into this column. |
| 270 |
* |
| 271 |
* The algorithm as described will fail if you try to skip adding values for a |
| 272 |
* key if adding an element for this key is the first thing you want to do for |
| 273 |
* a given iteration or time step, since we would then pad to the length of |
| 274 |
* the longest column of the <i>previous</i> iteration or time step. You may |
| 275 |
* have to re-order adding to this column to a different spot in your program, |
| 276 |
* after adding to a column that will always be added to; or, you may want to |
| 277 |
* start every iteration by adding the number of the iteration to the table, |
| 278 |
* for example in column 1. |
| 279 |
* |
| 280 |
* In the case above, we have always padded columns <b>above</b> the element |
| 281 |
* that is being added to a column. However, there is also a case where we |
| 282 |
* have to pad <b>below</b>. Namely, if a previous row has been completely |
| 283 |
* filled using TableHandler::add_value(), subsequent rows have been filled |
| 284 |
* partially, and we then ask for output via write_text() or write_tex(). In |
| 285 |
* that case, the last few rows that have been filled only partially need to |
| 286 |
* be padded below the last element that has been added to them. As before, we |
| 287 |
* do that by using default constructed objects of the same type as the last |
| 288 |
* element of that column. |
| 289 |
* |
| 290 |
* @ingroup textoutput |
| 291 |
*/ |
| 292 |
class TableHandler |
| 293 |
{ |
| 294 |
public: |
| 295 |
/** |
| 296 |
* Set of options how a table should be formatted when output with the |
| 297 |
* write_text() function. The following possibilities exist: |
| 298 |
* |
| 299 |
* - <code>table_with_headers</code>: The table is formatted in such a way |
| 300 |
* that the contents are aligned under the key of each column, i.e. the key |
| 301 |
* sits atop each column. This is suitable for tables with few columns where |
| 302 |
* the entire table can be displayed on the screen. Output looks like this: |
| 303 |
* @code |
| 304 |
* key1 key2 key3 |
| 305 |
* 0 0 "" |
| 306 |
* 1 0 "" |
| 307 |
* 2 13 a |
| 308 |
* 1 0 "" |
| 309 |
* @endcode |
| 310 |
* - <code>table_with_separate_column_description</code>: This is a better |
| 311 |
* format when there are many columns and the table as a whole can not be |
| 312 |
* displayed on the screen. Here, the column keys are first listed |
| 313 |
* one-by-one on lines of their own, and are numbered for better readability. |
| 314 |
* In addition, each of these description lines are prefixed by '#' to mark |
| 315 |
* these lines as comments for programs that want to read the following |
| 316 |
* table as data and should ignore these descriptive lines. GNUPLOT is one |
| 317 |
* such program that will automatically ignore lines so prefixed. Output |
| 318 |
* with this option looks like this: |
| 319 |
* @code |
| 320 |
* # 1: key1 |
| 321 |
* # 2: key2 |
| 322 |
* # 3: key3 |
| 323 |
* 0 0 "" |
| 324 |
* 1 0 "" |
| 325 |
* 2 13 a |
| 326 |
* 1 0 "" |
| 327 |
* @endcode |
| 328 |
* - <code>simple_table_with_separate_column_description</code>: This format |
| 329 |
* is very similar to <code>table_with_separate_column_description</code>, |
| 330 |
* but it skips aligning the columns with additional white space. This |
| 331 |
* increases the performance of write_text() for large tables. Example |
| 332 |
* output: |
| 333 |
* @code |
| 334 |
* # 1: key1 |
| 335 |
* # 2: key2 |
| 336 |
* # 3: key3 |
| 337 |
* 0 0 "" |
| 338 |
* 1 0 "" |
| 339 |
* 2 13 a |
| 340 |
* 1 0 "" |
| 341 |
* @endcode |
| 342 |
* - <code>org_mode_table</code>: Outputs to org-mode (http://orgmode.org/) |
| 343 |
* table format. It is easy to convert org-mode tables to HTML/LaTeX/csv. |
| 344 |
* Example output: |
| 345 |
* @code |
| 346 |
* | key1 | key2 | key3 | |
| 347 |
* | 0 | 0 | "" | |
| 348 |
* | 1 | 0 | "" | |
| 349 |
* | 2 | 13 | a | |
| 350 |
* | 1 | 0 | "" | |
| 351 |
* @endcode |
| 352 |
*/ |
| 353 |
enum TextOutputFormat |
| 354 |
{ |
| 355 |
/** |
| 356 |
* Print the table with headers. |
| 357 |
*/ |
| 358 |
table_with_headers, |
| 359 |
/** |
| 360 |
* Print the table with separate lines for each column label. |
| 361 |
*/ |
| 362 |
table_with_separate_column_description, |
| 363 |
/** |
| 364 |
* Like table_with_separate_column_description, but without aligning the |
| 365 |
* column containing the column labels. |
| 366 |
*/ |
| 367 |
simple_table_with_separate_column_description, |
| 368 |
/** |
| 369 |
* Print the table in org mode format. |
| 370 |
*/ |
| 371 |
org_mode_table |
| 372 |
}; |
| 373 |
|
| 374 |
/** |
| 375 |
* Constructor. |
| 376 |
*/ |
| 377 |
TableHandler(); |
| 378 |
|
| 379 |
|
| 380 |
/** |
| 381 |
* Declare the existence of a column in the table by giving it a name. |
| 382 |
* As discussed in the documentation of the class, this is not usually |
| 383 |
* necessary -- just adding a value for a given column key via the |
| 384 |
* add_value() function also declares the column. This function is |
| 385 |
* therefore only necessary in cases where you want a column to |
| 386 |
* also show up even if you never add an entry to any row in this column; |
| 387 |
* or, more likely, if you want to prescribe the order in which columns |
| 388 |
* are later printed by declaring columns in a particular order before |
| 389 |
* entries are ever put into them. |
| 390 |
* |
| 391 |
* (The latter objective can also be achieved by adding entries to |
| 392 |
* the table in whatever order they are produced by a program, |
| 393 |
* and later calling set_column_order(). However, this approach |
| 394 |
* requires knowing -- in one central place of your software -- |
| 395 |
* all of the columns keys that other parts of the software have |
| 396 |
* written into, and how they should be sorted. This is easily |
| 397 |
* possible for small programs, but may not be feasible for |
| 398 |
* large code bases in which parts of the code base are only |
| 399 |
* executed based on run-time parameters.) |
| 400 |
*/ |
| 401 |
void |
| 402 |
declare_column(const std::string &key); |
| 403 |
|
| 404 |
/** |
| 405 |
* Adds a column (if not yet existent) with the key <tt>key</tt> and adds |
| 406 |
* the value of type <tt>T</tt> to the column. Values of type <tt>T</tt> |
| 407 |
* must be convertible to one of <code>int, unsigned int, double, |
| 408 |
* std::uint64_t, std::string</code> or a compiler error will result. |
| 409 |
*/ |
| 410 |
template <typename T> |
| 411 |
void |
| 412 |
add_value(const std::string &key, const T value); |
| 413 |
|
| 414 |
/** |
| 415 |
* If a row is only partially filled, then set all elements of that |
| 416 |
* row for which no elements exist in a particular column to the |
| 417 |
* empty string. This is akin to the 'auto_fill_mode' described in |
| 418 |
* the introduction, but more general because it allows you to start |
| 419 |
* writing into a column for a new row without having to know that |
| 420 |
* that column had been written to in the previous row. |
| 421 |
* |
| 422 |
* If all columns have been written into in the current row, then |
| 423 |
* this function doesn't do anything at all. In other words, |
| 424 |
* conceptually the function "completes" the current row, though its |
| 425 |
* use case is to "start" a new row. |
| 426 |
*/ |
| 427 |
void |
| 428 |
start_new_row(); |
| 429 |
|
| 430 |
/** |
| 431 |
* Switch auto-fill mode on or off. See the general documentation of this |
| 432 |
* class for a description of what auto-fill mode does. |
| 433 |
*/ |
| 434 |
void |
| 435 |
set_auto_fill_mode(const bool state); |
| 436 |
|
| 437 |
/** |
| 438 |
* Creates a supercolumn (if not yet existent) and includes column to it. |
| 439 |
* The keys of the column and the supercolumn are <tt>key</tt> and |
| 440 |
* <tt>superkey</tt>, respectively. To merge two columns <tt>c1</tt> and |
| 441 |
* <tt>c2</tt> to a supercolumn <tt>sc</tt> hence call |
| 442 |
* <tt>add_column_to_supercolumn(c1,sc)</tt> and |
| 443 |
* <tt>add_column_to_supercolumn(c2,sc)</tt>. |
| 444 |
* |
| 445 |
* Concerning the order of the columns, the supercolumn replaces the first |
| 446 |
* column that is added to the supercolumn. Within the supercolumn the order |
| 447 |
* of output follows the order the columns are added to the supercolumn. |
| 448 |
*/ |
| 449 |
void |
| 450 |
add_column_to_supercolumn(const std::string &key, |
| 451 |
const std::string &superkey); |
| 452 |
|
| 453 |
/** |
| 454 |
* Change the order of columns and supercolumns in the table. |
| 455 |
* |
| 456 |
* <tt>new_order</tt> includes the keys and superkeys of the columns and |
| 457 |
* supercolumns in the order the user would like them to be output. If a |
| 458 |
* superkey is included the keys of the subcolumns need not be explicitly |
| 459 |
* mentioned in this vector. The order of subcolumns within a supercolumn |
| 460 |
* is not changeable and remains in the order in which the columns are added |
| 461 |
* to the supercolumn. |
| 462 |
* |
| 463 |
* This function may also be used to break big tables with too many columns |
| 464 |
* into smaller ones. For example, you can call this function with the first |
| 465 |
* five columns and then call one of the <tt>write_*</tt> functions, then |
| 466 |
* call this function with the next five columns and again <tt>write_*</tt>, |
| 467 |
* and so on. |
| 468 |
*/ |
| 469 |
void |
| 470 |
set_column_order(const std::vector<std::string> &new_order); |
| 471 |
|
| 472 |
/** |
| 473 |
* Set the <tt>precision</tt> e.g. double or float variables are written |
| 474 |
* with. <tt>precision</tt> is the same as in calling |
| 475 |
* <tt>out<<setprecision(precision)</tt>. |
| 476 |
*/ |
| 477 |
void |
| 478 |
set_precision(const std::string &key, const unsigned int precision); |
| 479 |
|
| 480 |
/** |
| 481 |
* Set the <tt>scientific_flag</tt>. True means scientific, false means |
| 482 |
* fixed point notation. |
| 483 |
*/ |
| 484 |
void |
| 485 |
set_scientific(const std::string &key, const bool scientific); |
| 486 |
|
| 487 |
/** |
| 488 |
* Set the caption of the column <tt>key</tt> for tex output. You may want |
| 489 |
* to chose this different from <tt>key</tt>, if it contains formulas or |
| 490 |
* similar constructs. |
| 491 |
*/ |
| 492 |
void |
| 493 |
set_tex_caption(const std::string &key, const std::string &tex_caption); |
| 494 |
|
| 495 |
/** |
| 496 |
* Set the tex caption of the entire <tt>table</tt> for tex output. |
| 497 |
*/ |
| 498 |
void |
| 499 |
set_tex_table_caption(const std::string &table_caption); |
| 500 |
|
| 501 |
/** |
| 502 |
* Set the label of this <tt>table</tt> for tex output. |
| 503 |
*/ |
| 504 |
void |
| 505 |
set_tex_table_label(const std::string &table_label); |
| 506 |
|
| 507 |
/** |
| 508 |
* Set the caption the supercolumn <tt>superkey</tt> for tex output. |
| 509 |
* You may want to chose this different from <tt>superkey</tt>, if it |
| 510 |
* contains formulas or similar constructs. |
| 511 |
*/ |
| 512 |
void |
| 513 |
set_tex_supercaption(const std::string &superkey, |
| 514 |
const std::string &tex_supercaption); |
| 515 |
|
| 516 |
/** |
| 517 |
* Set the tex output format of a column, e.g. <tt>c</tt>, <tt>r</tt>, |
| 518 |
* <tt>l</tt>, or <tt>p{3cm}</tt>. The default is <tt>c</tt>. Also if this |
| 519 |
* function is not called for a column, the default is preset to be |
| 520 |
* <tt>c</tt>. |
| 521 |
*/ |
| 522 |
void |
| 523 |
set_tex_format(const std::string &key, const std::string &format = "c"); |
| 524 |
|
| 525 |
/** |
| 526 |
* Write table as formatted text to the given stream. The text is formatted |
| 527 |
* in such as way that it represents data as formatted columns of text. To |
| 528 |
* avoid problems when reading these tables automatically, for example for |
| 529 |
* postprocessing, if an entry in a cell of this table is empty (i.e. it has |
| 530 |
* been created by calling the add_value() function with an empty string), |
| 531 |
* then the entry of the table is printed as <code>""</code>. |
| 532 |
* |
| 533 |
* The second argument indicates how column keys are to be displayed. See |
| 534 |
* the description of TextOutputFormat for more information. |
| 535 |
*/ |
| 536 |
void |
| 537 |
write_text(std::ostream &out, |
| 538 |
const TextOutputFormat format = table_with_headers) const; |
| 539 |
|
| 540 |
/** |
| 541 |
* Write table as a tex file. If @p with_header is set to false, then no |
| 542 |
* <code>\\documentclass{...}</code>, <code>\\begin{document}</code> and |
| 543 |
* <code>\\end{document}</code> are used. In this way the file can be |
| 544 |
* included into an existing tex file using a command like |
| 545 |
* <code>\\input{table_file}</code>. |
| 546 |
*/ |
| 547 |
void |
| 548 |
write_tex(std::ostream &file, const bool with_header = true) const; |
| 549 |
|
| 550 |
/** |
| 551 |
* Clear the rows of the table, i.e. calls clear() on all the underlying |
| 552 |
* storage data structures. |
| 553 |
*/ |
| 554 |
void |
| 555 |
clear(); |
| 556 |
|
| 557 |
/** |
| 558 |
* Remove all values added at the current row. This is useful when, for |
| 559 |
* example, a time-step is rejected and all data recorded about it needs to |
| 560 |
* be discarded. |
| 561 |
*/ |
| 562 |
void |
| 563 |
clear_current_row(); |
| 564 |
|
| 565 |
/** |
| 566 |
* Read or write the data of this object to or from a stream for the purpose |
| 567 |
* of serialization using the [BOOST serialization |
| 568 |
* library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html). |
| 569 |
*/ |
| 570 |
template <class Archive> |
| 571 |
void |
| 572 |
serialize(Archive &ar, const unsigned int version); |
| 573 |
|
| 574 |
/** |
| 575 |
* @addtogroup Exceptions |
| 576 |
* @{ |
| 577 |
*/ |
| 578 |
|
| 579 |
/** |
| 580 |
* Exception |
| 581 |
*/ |
| 582 |
DeclException1(ExcColumnNotExistent, |
| 583 |
std::string, |
| 584 |
<< "Column <" << arg1 << "> does not exist."); |
| 585 |
|
| 586 |
/** |
| 587 |
* Exception |
| 588 |
*/ |
| 589 |
DeclException1(ExcSuperColumnNotExistent, |
| 590 |
std::string, |
| 591 |
<< "Supercolumn <" << arg1 << "> does not exist."); |
| 592 |
|
| 593 |
/** |
| 594 |
* Exception |
| 595 |
*/ |
| 596 |
DeclException1(ExcColumnOrSuperColumnNotExistent, |
| 597 |
std::string, |
| 598 |
<< "Column or supercolumn <" << arg1 << "> does not exist."); |
| 599 |
|
| 600 |
/** |
| 601 |
* Exception |
| 602 |
*/ |
| 603 |
DeclException4(ExcWrongNumberOfDataEntries, |
| 604 |
std::string, |
| 605 |
int, |
| 606 |
std::string, |
| 607 |
int, |
| 608 |
<< "Column <" << arg1 << "> has " << arg2 |
| 609 |
<< " rows, but Column <" << arg3 << "> has " << arg4 |
| 610 |
<< " rows."); |
| 611 |
|
| 612 |
/** |
| 613 |
* Exception |
| 614 |
*/ |
| 615 |
DeclException1(ExcUndefinedTexFormat, |
| 616 |
std::string, |
| 617 |
<< '<' << arg1 << "> is not a tex column format. Use " |
| 618 |
<< "'l', 'c', or 'r' to indicate left, centered, or " |
| 619 |
<< "right aligned text."); |
| 620 |
/** @} */ |
| 621 |
protected: |
| 622 |
/** |
| 623 |
* Structure encapsulating all the data that is needed to describe one |
| 624 |
* column of a table. |
| 625 |
*/ |
| 626 |
struct Column |
| 627 |
{ |
| 628 |
/** |
| 629 |
* Constructor needed by <tt>std::map</tt>. |
| 630 |
*/ |
| 631 |
Column(); |
| 632 |
|
| 633 |
/** |
| 634 |
* Constructor. |
| 635 |
*/ |
| 636 |
explicit Column(const std::string &tex_caption); |
| 637 |
|
| 638 |
/** |
| 639 |
* Pad this column with default constructed elements to the number of rows |
| 640 |
* given by the argument. |
| 641 |
*/ |
| 642 |
void |
| 643 |
pad_column_below(const unsigned int length); |
| 644 |
|
| 645 |
/** |
| 646 |
* Write the data of this object to a stream for the purpose of |
| 647 |
* serialization using the [BOOST serialization |
| 648 |
* library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html). |
| 649 |
*/ |
| 650 |
template <class Archive> |
| 651 |
void |
| 652 |
save(Archive &ar, const unsigned int version) const; |
| 653 |
|
| 654 |
/** |
| 655 |
* Read the data of this object from a stream for the purpose of |
| 656 |
* serialization using the [BOOST serialization |
| 657 |
* library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html). |
| 658 |
*/ |
| 659 |
template <class Archive> |
| 660 |
void |
| 661 |
load(Archive &ar, const unsigned int version); |
| 662 |
|
| 663 |
#ifdef DOXYGEN |
| 664 |
/** |
| 665 |
* Write and read the data of this object from a stream for the purpose |
| 666 |
* of serialization using the [BOOST serialization |
| 667 |
* library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html). |
| 668 |
*/ |
| 669 |
template <class Archive> |
| 670 |
void |
| 671 |
serialize(Archive &archive, const unsigned int version); |
| 672 |
#else |
| 673 |
// This macro defines the serialize() method that is compatible with |
| 674 |
// the templated save() and load() method that have been implemented. |
| 675 |
BOOST_SERIALIZATION_SPLIT_MEMBER() |
| 676 |
#endif |
| 677 |
|
| 678 |
|
| 679 |
/** |
| 680 |
* Invalidates the string cache of all the entries and recomputes the |
| 681 |
* maximum length max_length. |
| 682 |
*/ |
| 683 |
void |
| 684 |
invalidate_cache(); |
| 685 |
|
| 686 |
/** |
| 687 |
* List of entries within this column. Values are always immediately |
| 688 |
* converted to strings to provide a uniform method of lookup. |
| 689 |
*/ |
| 690 |
std::vector<internal::TableEntry> entries; |
| 691 |
|
| 692 |
/** |
| 693 |
* The caption of the column in tex output. By default, this is the key |
| 694 |
* string that is given to the <tt>TableHandler</tt> by |
| 695 |
* <tt>TableHandler::add_value(...)</tt>. This may be changed by calling |
| 696 |
* <tt>TableHandler::set_tex_caption(...)</tt>. |
| 697 |
*/ |
| 698 |
std::string tex_caption; |
| 699 |
|
| 700 |
/** |
| 701 |
* The column format in tex output. By default, this is <tt>"c"</tt>, |
| 702 |
* meaning `centered'. This may be changed by calling |
| 703 |
* <tt>TableHandler::set_tex_format(...)</tt> with <tt>"c", "r", "l"</tt> |
| 704 |
* for centered, right or left. |
| 705 |
*/ |
| 706 |
|
| 707 |
std::string tex_format; |
| 708 |
|
| 709 |
/** |
| 710 |
* Double or float entries are written with this precision (set by the |
| 711 |
* user). The default is 4. |
| 712 |
*/ |
| 713 |
unsigned int precision; |
| 714 |
|
| 715 |
/** |
| 716 |
* <tt>scientific</tt>=false means fixed point notation. |
| 717 |
*/ |
| 718 |
bool scientific; |
| 719 |
|
| 720 |
/** |
| 721 |
* Flag that may be used by derived classes for arbitrary purposes. |
| 722 |
* |
| 723 |
* In particular, the ConvergenceTable class uses the flag to denote |
| 724 |
* columns for which convergence information has already been computed, or |
| 725 |
* should not be computed at all. |
| 726 |
*/ |
| 727 |
unsigned int flag; |
| 728 |
|
| 729 |
/** |
| 730 |
* This entry caches the maximum length in characters for all entries in |
| 731 |
* this table. |
| 732 |
*/ |
| 733 |
unsigned int max_length; |
| 734 |
}; |
| 735 |
|
| 736 |
/** |
| 737 |
* Help function that gives a vector of the keys of all columns that are |
| 738 |
* mentioned in <tt>column_order</tt>, where each supercolumn key is |
| 739 |
* replaced by its subcolumn keys. |
| 740 |
* |
| 741 |
* This function implicitly checks the consistency of the data. The result |
| 742 |
* is returned in <tt>sel_columns</tt>. |
| 743 |
*/ |
| 744 |
void |
| 745 |
get_selected_columns(std::vector<std::string> &sel_columns) const; |
| 746 |
|
| 747 |
/** |
| 748 |
* Builtin function, that gives the number of rows in the table and that |
| 749 |
* checks if the number of rows is equal in every column. This function is |
| 750 |
* e.g. called before writing output. |
| 751 |
*/ |
| 752 |
unsigned int |
| 753 |
n_rows() const; |
| 754 |
|
| 755 |
/** |
| 756 |
* A variable storing the column and supercolumn keys in the order desired by |
| 757 |
* the user. By default this is the order of adding the columns. This order |
| 758 |
* may be changed by set_column_order(). |
| 759 |
*/ |
| 760 |
std::vector<std::string> column_order; |
| 761 |
|
| 762 |
/** |
| 763 |
* A map from the column keys to the columns (not supercolumns). |
| 764 |
* |
| 765 |
* The field is declared mutable so that the write_text() and write_tex() |
| 766 |
* functions can be const, even though they may pad columns below if |
| 767 |
* 'auto_fill_mode' is on. |
| 768 |
*/ |
| 769 |
mutable std::map<std::string, Column> columns; |
| 770 |
|
| 771 |
/** |
| 772 |
* A map from each supercolumn key to the keys of its subcolumns in the right |
| 773 |
* order. It is allowed that a supercolumn has got the same key as a |
| 774 |
* column. |
| 775 |
* |
| 776 |
* Note that we do not use a <tt>multimap</tt> here since the order of |
| 777 |
* column keys for each supercolumn key is relevant. |
| 778 |
*/ |
| 779 |
std::map<std::string, std::vector<std::string>> supercolumns; |
| 780 |
|
| 781 |
/** |
| 782 |
* A map from the supercolumn keys to the captions of the supercolumns that |
| 783 |
* are used in tex output. |
| 784 |
* |
| 785 |
* By default these are just the supercolumn keys but they may be changed by |
| 786 |
* <tt>set_tex_supercaptions(...)</tt>. |
| 787 |
*/ |
| 788 |
std::map<std::string, std::string> tex_supercaptions; |
| 789 |
|
| 790 |
/** |
| 791 |
* The caption of the table itself. |
| 792 |
*/ |
| 793 |
std::string tex_table_caption; |
| 794 |
/** |
| 795 |
* The label of the table. |
| 796 |
*/ |
| 797 |
std::string tex_table_label; |
| 798 |
|
| 799 |
/** |
| 800 |
* Flag indicating whether auto-fill mode should be used. |
| 801 |
*/ |
| 802 |
bool auto_fill_mode; |
| 803 |
}; |
| 804 |
|
| 805 |
|
| 806 |
namespace internal |
| 807 |
{ |
| 808 |
template <typename T> |
| 809 |
TableEntry::TableEntry(const T &t) |
| 810 |
: value(t) |
| 811 |
{} |
| 812 |
|
| 813 |
|
| 814 |
template <typename T> |
| 815 |
T |
| 816 |
TableEntry::get() const |
| 817 |
{ |
| 818 |
// we don't quite know the data type in 'value', but |
| 819 |
// it must be one of the ones in the type list of the |
| 820 |
// std::variant. so if T is not in the list, or if |
| 821 |
// the data stored in the TableEntry is not of type |
| 822 |
// T, then we will get an exception that we can |
| 823 |
// catch and produce an error message |
| 824 |
try |
| 825 |
{ |
| 826 |
return std::get<T>(value); |
| 827 |
} |
| 828 |
catch (...) |
| 829 |
{ |
| 830 |
Assert(false, |
| 831 |
ExcMessage( |
| 832 |
"This TableEntry object does not store a datum of type T")); |
| 833 |
throw; |
| 834 |
} |
| 835 |
} |
| 836 |
|
| 837 |
|
| 838 |
|
| 839 |
template <class Archive> |
| 840 |
void |
| 841 |
TableEntry::save(Archive &ar, const unsigned int) const |
| 842 |
{ |
| 843 |
// write first an identifier for the kind |
| 844 |
// of data stored and then the actual |
| 845 |
// data, in its correct data type |
| 846 |
if (std::holds_alternative<int>(value)) |
| 847 |
{ |
| 848 |
const int p = std::get<int>(value); |
| 849 |
char c = 'i'; |
| 850 |
ar &c &p; |
| 851 |
} |
| 852 |
else if (std::holds_alternative<unsigned int>(value)) |
| 853 |
{ |
| 854 |
const unsigned int p = std::get<unsigned int>(value); |
| 855 |
char c = 'u'; |
| 856 |
ar &c &p; |
| 857 |
} |
| 858 |
else if (std::holds_alternative<double>(value)) |
| 859 |
{ |
| 860 |
const double p = std::get<double>(value); |
| 861 |
char c = 'd'; |
| 862 |
ar &c &p; |
| 863 |
} |
| 864 |
else if (std::holds_alternative<std::string>(value)) |
| 865 |
{ |
| 866 |
const std::string p = std::get<std::string>(value); |
| 867 |
char c = 's'; |
| 868 |
ar &c &p; |
| 869 |
} |
| 870 |
else if (std::holds_alternative<std::uint64_t>(value)) |
| 871 |
{ |
| 872 |
const std::uint64_t p = std::get<std::uint64_t>(value); |
| 873 |
char c = 'l'; |
| 874 |
ar &c &p; |
| 875 |
} |
| 876 |
else |
| 877 |
DEAL_II_ASSERT_UNREACHABLE(); |
| 878 |
} |
| 879 |
|
| 880 |
|
| 881 |
|
| 882 |
template <class Archive> |
| 883 |
void |
| 884 |
TableEntry::load(Archive &ar, const unsigned int) |
| 885 |
{ |
| 886 |
// following what we do in the save() |
| 887 |
// function, first read in the data type |
| 888 |
// as a one-character id, and then read |
| 889 |
// the data |
| 890 |
char c; |
| 891 |
ar &c; |
| 892 |
|
| 893 |
switch (c) |
| 894 |
{ |
| 895 |
case 'i': |
| 896 |
{ |
| 897 |
int val; |
| 898 |
ar &val; |
| 899 |
value = val; |
| 900 |
break; |
| 901 |
} |
| 902 |
|
| 903 |
case 'u': |
| 904 |
{ |
| 905 |
unsigned int val; |
| 906 |
ar &val; |
| 907 |
value = val; |
| 908 |
break; |
| 909 |
} |
| 910 |
|
| 911 |
case 'd': |
| 912 |
{ |
| 913 |
double val; |
| 914 |
ar &val; |
| 915 |
value = val; |
| 916 |
break; |
| 917 |
} |
| 918 |
|
| 919 |
case 's': |
| 920 |
{ |
| 921 |
std::string val; |
| 922 |
ar &val; |
| 923 |
value = val; |
| 924 |
break; |
| 925 |
} |
| 926 |
|
| 927 |
case 'l': |
| 928 |
{ |
| 929 |
std::uint64_t val; |
| 930 |
ar &val; |
| 931 |
value = val; |
| 932 |
break; |
| 933 |
} |
| 934 |
|
| 935 |
default: |
| 936 |
DEAL_II_ASSERT_UNREACHABLE(); |
| 937 |
} |
| 938 |
} |
| 939 |
} // namespace internal |
| 940 |
|
| 941 |
|
| 942 |
|
| 943 |
template <typename T> |
| 944 |
void |
| 945 |
TableHandler::add_value(const std::string &key, const T value) |
| 946 |
{ |
| 947 |
// see if the column already exists |
| 948 |
if (columns.find(key) == columns.end()) |
| 949 |
declare_column(key); |
| 950 |
|
| 951 |
if (auto_fill_mode == true) |
| 952 |
{ |
| 953 |
// follow the algorithm given in the introduction to this class |
| 954 |
// of padding columns as necessary |
| 955 |
unsigned int max_col_length = 0; |
| 956 |
for (const auto &column : columns) |
| 957 |
max_col_length = |
| 958 |
std::max(max_col_length, |
| 959 |
static_cast<unsigned int>(column.second.entries.size())); |
| 960 |
|
| 961 |
while (columns[key].entries.size() + 1 < max_col_length) |
| 962 |
{ |
| 963 |
columns[key].entries.push_back(internal::TableEntry(T())); |
| 964 |
const internal::TableEntry &entry = columns[key].entries.back(); |
| 965 |
entry.cache_string(columns[key].scientific, columns[key].precision); |
| 966 |
columns[key].max_length = |
| 967 |
std::max(columns[key].max_length, |
| 968 |
static_cast<unsigned int>( |
| 969 |
entry.get_cached_string().size())); |
| 970 |
} |
| 971 |
} |
| 972 |
|
| 973 |
// now push the value given to this function |
| 974 |
columns[key].entries.push_back(internal::TableEntry(value)); |
| 975 |
const internal::TableEntry &entry = columns[key].entries.back(); |
| 976 |
entry.cache_string(columns[key].scientific, columns[key].precision); |
| 977 |
columns[key].max_length = |
| 978 |
std::max(columns[key].max_length, |
| 979 |
static_cast<unsigned int>(entry.get_cached_string().size())); |
| 980 |
} |
| 981 |
|
| 982 |
|
| 983 |
|
| 984 |
template <class Archive> |
| 985 |
void |
| 986 |
TableHandler::Column::save(Archive &ar, const unsigned int /*version*/) const |
| 987 |
{ |
| 988 |
ar &entries &tex_caption &tex_format &precision &scientific &flag &max_length; |
| 989 |
} |
| 990 |
|
| 991 |
|
| 992 |
|
| 993 |
template <class Archive> |
| 994 |
void |
| 995 |
TableHandler::Column::load(Archive &ar, const unsigned int /*version*/) |
| 996 |
{ |
| 997 |
ar &entries &tex_caption &tex_format &precision &scientific &flag &max_length; |
| 998 |
invalidate_cache(); |
| 999 |
} |
| 1000 |
|
| 1001 |
|
| 1002 |
template <class Archive> |
| 1003 |
void |
| 1004 |
TableHandler::serialize(Archive &ar, const unsigned int) |
| 1005 |
{ |
| 1006 |
ar &column_order &columns &supercolumns &tex_supercaptions &tex_table_caption |
| 1007 |
&tex_table_label &auto_fill_mode; |
| 1008 |
} |
| 1009 |
|
| 1010 |
|
| 1011 |
DEAL_II_NAMESPACE_CLOSE |
| 1012 |
|
| 1013 |
#endif |