 |
Reference documentation for deal.II version 9.0.0
|
|
Reference documentation for deal.II version 9.0.0
|
#include <deal.II/base/table_handler.h>
Classes | |
| struct | Column |
Public Types | |
| enum | TextOutputFormat { table_with_headers, table_with_separate_column_description, simple_table_with_separate_column_description, org_mode_table } |
Public Member Functions | |
| TableHandler () | |
| void | declare_column (const std::string &key) |
| template<typename T > | |
| void | add_value (const std::string &key, const T value) |
| void | start_new_row () |
| void | set_auto_fill_mode (const bool state) |
| void | add_column_to_supercolumn (const std::string &key, const std::string &superkey) |
| void | set_column_order (const std::vector< std::string > &new_order) |
| void | set_precision (const std::string &key, const unsigned int precision) |
| void | set_scientific (const std::string &key, const bool scientific) |
| void | set_tex_caption (const std::string &key, const std::string &tex_caption) |
| void | set_tex_table_caption (const std::string &table_caption) |
| void | set_tex_table_label (const std::string &table_label) |
| void | set_tex_supercaption (const std::string &superkey, const std::string &tex_supercaption) |
| void | set_tex_format (const std::string &key, const std::string &format="c") |
| void | write_text (std::ostream &out, const TextOutputFormat format=table_with_headers) const |
| void | write_tex (std::ostream &file, const bool with_header=true) const |
| void | clear () |
| void | clear_current_row () |
| template<class Archive > | |
| void | serialize (Archive &ar, const unsigned int version) |
Static Public Member Functions | |
| static ::ExceptionBase & | ExcColumnNotExistent (std::string arg1) |
| static ::ExceptionBase & | ExcSuperColumnNotExistent (std::string arg1) |
| static ::ExceptionBase & | ExcColumnOrSuperColumnNotExistent (std::string arg1) |
| static ::ExceptionBase & | ExcWrongNumberOfDataEntries (std::string arg1, int arg2, std::string arg3, int arg4) |
| static ::ExceptionBase & | ExcUndefinedTexFormat (std::string arg1) |
Protected Member Functions | |
| void | get_selected_columns (std::vector< std::string > &sel_columns) const |
| unsigned int | n_rows () const |
Protected Attributes | |
| std::vector< std::string > | column_order |
| std::map< std::string, Column > | columns |
| std::map< std::string, std::vector< std::string > > | supercolumns |
| std::map< std::string, std::string > | tex_supercaptions |
| std::string | tex_table_caption |
| std::string | tex_table_label |
| bool | auto_fill_mode |
The TableHandler stores TableEntries of arbitrary value type and writes the table as text or in tex format to an output stream. The value type actually may vary from column to column and from row to row.
The most important function is the templatized function add_value(const std::string &key, const T value) that adds a column with the name key to the table if this column does not yet exist and adds the given value of type T (which must be one of int, unsigned int, double, std::string) to this column. After the table is complete there are different possibilities of output, e.g., into a latex file with write_tex() or as text with write_text().
Two (or more) columns may be merged into a "supercolumn" by twice (or multiple) calling add_column_to_supercolumn(), see there. Additionally there is a function to set for each column the precision of the output of numbers, and there are several functions to prescribe the format and the captions the columns are written with in tex mode.
A detailed explanation of this class is also given in the step-13 tutorial program.
This is a simple example demonstrating the usage of this class. The first column includes the numbers i=1..n, the second \(1^2\)... \(n^2\), the third \(sqrt(1)...sqrt(n)\), where the second and third columns are merged into one supercolumn with the superkey squares and roots. Additionally the first column is aligned to the right (the default was centered) and the precision of the square roots are set to be 6 (instead of 4 as default).
When generating output, TableHandler expects that all columns have the exact same number of elements in it so that the result is in fact a table. This assumes that in each of the iterations (time steps, nonlinear iterations, etc) you fill every single column. On the other hand, this may not always be what you want to do. For example, it could be that the function that computes the nonlinear residual is only called every few time steps; or, a function computing statistics of the mesh is only called whenever the mesh is in fact refined. In these cases, the add_value() function will be called less often for some columns and the column would therefore have fewer elements; furthermore, these elements would not be aligned with the rows that contain the other data elements that were produced during this iteration. An entirely different scenario is that the table is filled and at a later time we use the data in there to compute the elements of other rows; the ConvergenceTable class does something like this.
To support both scenarios, the TableHandler class has a property called auto-fill mode. By default, auto-fill mode is off, but it can be enabled by calling set_auto_fill_mode(). If auto-fill mode is enabled we use the following algorithm: - When calling add_value(key, value), we count the number of elements in the column corresponding to key. Let's call this number \(m\). - We also determine the maximal number of elements in the other columns; call it \(n\). - If \(m < n-1\) then we add \(n-m-1\) copies of the object T() to this column. Here, T is the data type of the given value. For example, if T is a numeric type, then T() is the number zero; if T is std::string, then T() is the empty string "". - Add the given value to this column.
Padding the column with default elements makes sure that after the addition the column has as many entries as the longest other column. In other words, if we have skipped previous invocations of add_value() for a given key, then the padding will enter default values into this column.
The algorithm as described will fail if you try to skip adding values for a key if adding an element for this key is the first thing you want to do for a given iteration or time step, since we would then pad to the length of the longest column of the previous iteration or time step. You may have to re-order adding to this column to a different spot in your program, after adding to a column that will always be added to; or, you may want to start every iteration by adding the number of the iteration to the table, for example in column 1.
In the case above, we have always padded columns above the element that is being added to a column. However, there is also a case where we have to pad below. Namely, if a previous row has been completely filled using TableHandler::add_value(), subsequent rows have been filled partially, and we then ask for output via write_text() or write_tex(). In that case, the last few rows that have been filled only partially need to be padded below the last element that has been added to them. As before, we do that by using default constructed objects of the same type as the last element of that column.
Definition at line 262 of file table_handler.h.
Set of options how a table should be formatted when output with the write_text() function. The following possibilities exist:
table_with_headers: The table is formatted in such a way that the contents are aligned under the key of each column, i.e. the key sits atop each column. This is suitable for tables with few columns where the entire table can be displayed on the screen. Output looks like this: table_with_separate_column_description: This is a better format when there are many columns and the table as a whole can not be displayed on the screen. Here, the column keys are first listed one-by- one on lines of their own, and are numbered for better readability. In addition, each of these description lines are prefixed by '#' to mark these lines as comments for programs that want to read the following table as data and should ignore these descriptive lines. GNUPLOT is one such program that will automatically ignore lines so prefixed. Output with this option looks like this: simple_table_with_separate_column_description: This format is very similar to table_with_separate_column_description, but it skips aligning the columns with additional white space. This increases the performance of write_text() for large tables. Example output: org_mode_table: Outputs to org-mode (http://orgmode.org/) table format. It is easy to convert org-mode tables to HTML/LaTeX/csv. Example output: Definition at line 323 of file table_handler.h.
| TableHandler::TableHandler | ( | ) |
Constructor.
Definition at line 189 of file table_handler.cc.
| void TableHandler::declare_column | ( | const std::string & | key | ) |
Declare the existence of a column in the table by giving it a name. As discussed in the documentation of the class, this is not usually necessary – just adding a value for a given column key via the add_value() function also declares the column. This function is therefore only necessary in cases where you want a column to also show up even if you never add an entry to any row in this column; or, more likely, if you want to prescribe the order in which columns are later printed by declaring columns in a particular order before entries are ever put into them.
(The latter objective can also be achieved by adding entries to the table in whatever order they are produced by a program, and later calling set_column_order(). However, this approach requires knowing – in one central place of your software – all of the columns keys that other parts of the software have written into, and how they should be sorted. This is easily possible for small programs, but may not be feasible for large code bases in which parts of the code base are only executed based on run-time parameters.)
Definition at line 196 of file table_handler.cc.
| void TableHandler::add_value | ( | const std::string & | key, |
| const T | value | ||
| ) |
Adds a column (if not yet existent) with the key key and adds the value of type T to the column. Values of type T must be convertible to one of int, unsigned int, double, std::string or a compiler error will result.
Definition at line 863 of file table_handler.h.
| void TableHandler::start_new_row | ( | ) |
If a row is only partially filled, then set all elements of that row for which no elements exist in a particular column to the empty string. This is akin to the 'auto_fill_mode' described in the introduction, but more general because it allows you to start writing into a column for a new row without having to know that that column had been written to in the previous row.
If all columns have been written into in the current row, then this function doesn't do anything at all. In other words, conceptually the function "completes" the current row, though its use case is to "start" a new row.
Definition at line 209 of file table_handler.cc.
| void TableHandler::set_auto_fill_mode | ( | const bool | state | ) |
Switch auto-fill mode on or off. See the general documentation of this class for a description of what auto-fill mode does.
Definition at line 233 of file table_handler.cc.
| void TableHandler::add_column_to_supercolumn | ( | const std::string & | key, |
| const std::string & | superkey | ||
| ) |
Creates a supercolumn (if not yet existent) and includes column to it. The keys of the column and the supercolumn are key and superkey, respectively. To merge two columns c1 and c2 to a supercolumn sc hence call add_column_to_supercolumn(c1,sc) and add_column_to_supercolumn(c2,sc).
Concerning the order of the columns, the supercolumn replaces the first column that is added to the supercolumn. Within the supercolumn the order of output follows the order the columns are added to the supercolumn.
Definition at line 239 of file table_handler.cc.
| void TableHandler::set_column_order | ( | const std::vector< std::string > & | new_order | ) |
Change the order of columns and supercolumns in the table.
new_order includes the keys and superkeys of the columns and supercolumns in the order the user would like them to be output. If a superkey is included the keys of the subcolumns need not be explicitly mentioned in this vector. The order of subcolumns within a supercolumn is not changeable and remains in the order in which the columns are added to the supercolumn.
This function may also be used to break big tables with too many columns into smaller ones. For example, you can call this function with the first five columns and then call one of the write_* functions, then call this function with the next five columns and again write_*, and so on.
Definition at line 285 of file table_handler.cc.
| void TableHandler::set_precision | ( | const std::string & | key, |
| const unsigned int | precision | ||
| ) |
Set the precision e.g. double or float variables are written with. precision is the same as in calling out<<setprecision(precision).
Definition at line 339 of file table_handler.cc.
| void TableHandler::set_scientific | ( | const std::string & | key, |
| const bool | scientific | ||
| ) |
Set the scientific_flag. True means scientific, false means fixed point notation.
Definition at line 351 of file table_handler.cc.
| void TableHandler::set_tex_caption | ( | const std::string & | key, |
| const std::string & | tex_caption | ||
| ) |
Set the caption of the column key for tex output. You may want to chose this different from key, if it contains formulas or similar constructs.
Definition at line 295 of file table_handler.cc.
| void TableHandler::set_tex_table_caption | ( | const std::string & | table_caption | ) |
Set the tex caption of the entire table for tex output.
Definition at line 304 of file table_handler.cc.
| void TableHandler::set_tex_table_label | ( | const std::string & | table_label | ) |
Set the label of this table for tex output.
Definition at line 311 of file table_handler.cc.
| void TableHandler::set_tex_supercaption | ( | const std::string & | superkey, |
| const std::string & | tex_supercaption | ||
| ) |
Set the caption the supercolumn superkey for tex output. You may want to chose this different from superkey, if it contains formulas or similar constructs.
Definition at line 318 of file table_handler.cc.
| void TableHandler::set_tex_format | ( | const std::string & | key, |
| const std::string & | format = "c" |
||
| ) |
Set the tex output format of a column, e.g. c, r, l, or p{3cm}. The default is c. Also if this function is not called for a column, the default is preset to be c.
Definition at line 328 of file table_handler.cc.
| void TableHandler::write_text | ( | std::ostream & | out, |
| const TextOutputFormat | format = table_with_headers |
||
| ) | const |
Write table as formatted text to the given stream. The text is formatted in such as way that it represents data as formatted columns of text. To avoid problems when reading these tables automatically, for example for postprocessing, if an entry in a cell of this table is empty (i.e. it has been created by calling the add_value() function with an empty string), then the entry of the table is printed as "".
The second argument indicates how column keys are to be displayed. See the description of TextOutputFormat for more information
Definition at line 363 of file table_handler.cc.
| void TableHandler::write_tex | ( | std::ostream & | file, |
| const bool | with_header = true |
||
| ) | const |
Write table as a tex file. If with_header is set to false, then no \documentclass{...}, \begin{document} and \end{document} are used. In this way the file can be included into an existing tex file using a command like \input{table_file}.
Definition at line 577 of file table_handler.cc.
| void TableHandler::clear | ( | ) |
Clear the rows of the table, i.e. calls clear() on all the underlying storage data structures.
Definition at line 712 of file table_handler.cc.
| void TableHandler::clear_current_row | ( | ) |
Remove all values added at the current row. This is useful when, for example, a time-step is rejected and all data recorded about it needs to be discarded.
Definition at line 776 of file table_handler.cc.
| void TableHandler::serialize | ( | Archive & | ar, |
| const unsigned int | version | ||
| ) |
Read or write the data of this object to or from a stream for the purpose of serialization.
Definition at line 926 of file table_handler.h.
|
protected |
Help function that gives a vector of the keys of all columns that are mentioned in column_order, where each supercolumn key is replaced by its subcolumn keys.
This function implicitly checks the consistency of the data. The result is returned in sel_columns.
Definition at line 745 of file table_handler.cc.
|
protected |
Builtin function, that gives the number of rows in the table and that checks if the number of rows is equal in every column. This function is e.g. called before writing output.
Definition at line 726 of file table_handler.cc.
|
protected |
A variable storing the column and supercolumn keys in the order desired by the user. By default this is the order of adding the columns. This order may be changed by set_column_order().
Definition at line 686 of file table_handler.h.
|
mutableprotected |
A map from the column keys to the columns (not supercolumns).
The field is declared mutable so that the write_text() and write_tex() functions can be const, even though they may pad columns below if auto_fill_mode is on.
Definition at line 695 of file table_handler.h.
|
protected |
A map from each supercolumn key to the keys of its subcolumns in the right order. It is allowed that a supercolumn has got the same key as a column.
Note that we do not use a multimap here since the order of column keys for each supercolumn key is relevant.
Definition at line 705 of file table_handler.h.
|
protected |
A map from the supercolumn keys to the captions of the supercolumns that are used in tex output.
By default these are just the supercolumn keys but they may be changed by set_tex_supercaptions(...).
Definition at line 714 of file table_handler.h.
|
protected |
The caption of the table itself.
Definition at line 719 of file table_handler.h.
|
protected |
The label of the table.
Definition at line 723 of file table_handler.h.
|
protected |
Flag indicating whether auto-fill mode should be used.
Definition at line 728 of file table_handler.h.
1.8.14