![]() |
Reference documentation for deal.II version 9.6.0
|
#include <deal.II/base/convergence_table.h>
Public Types | |
enum | RateMode { none , reduction_rate , reduction_rate_log2 } |
enum | TextOutputFormat { table_with_headers , table_with_separate_column_description , simple_table_with_separate_column_description , org_mode_table } |
Public Member Functions | |
ConvergenceTable ()=default | |
void | evaluate_convergence_rates (const std::string &data_column_key, const std::string &reference_column_key, const RateMode rate_mode, const unsigned int dim=2) |
void | evaluate_convergence_rates (const std::string &data_column_key, const RateMode rate_mode) |
void | omit_column_from_convergence_rate_evaluation (const std::string &key) |
void | evaluate_all_convergence_rates (const std::string &reference_column_key, const RateMode rate_mode) |
void | evaluate_all_convergence_rates (const RateMode rate_mode) |
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 & | ExcRateColumnAlreadyExists (std::string arg1) |
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 ConvergenceTable class is an application to the TableHandler class and stores some convergence data, such as residuals of the cg-method, or some evaluated L2-errors of discrete solutions, etc, and evaluates convergence rates or orders.
The already implemented RateMode's are reduction_rate, where the convergence rate is the quotient of two following rows, and reduction_rate_log2, that evaluates the order of convergence. These standard evaluations are useful for global refinement, for local refinement this may not be an appropriate method, as the convergence rates should be set in relation to the number of cells or the number of DoFs. The implementations of these non-standard methods is left to a user.
For example, the number of cells may be added to the table by calling add_value("n cells", n_cells)
. The number of DoFs may be added to the table by calling add_value("n dofs", n_dofs)
. Of course, one can also add more kinds of information by calling add_value() with other arguments. In any case, before the output of the table the functions evaluate_convergence_rates() and evaluate_all_convergence_rates() may be called.
There are two possibilities of how to evaluate the convergence rates of multiple columns in the same RateMode.
A detailed discussion of this class can also be found in the step-7 and step-13 example programs. It is also used in step-74.
Definition at line 63 of file convergence_table.h.
Rate in relation to the rows.
Enumerator | |
---|---|
none | Do not do anything. |
reduction_rate | Quotient of values in the previous row and in this row. |
reduction_rate_log2 | Logarithm of reduction_rate to the base 2 representing the order of convergence when halving the grid size, e.g. from h to h/2. |
Definition at line 74 of file convergence_table.h.
|
inherited |
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 353 of file table_handler.h.
|
default |
Constructor.
void ConvergenceTable::evaluate_convergence_rates | ( | const std::string & | data_column_key, |
const std::string & | reference_column_key, | ||
const RateMode | rate_mode, | ||
const unsigned int | dim = 2 ) |
Evaluate the convergence rates of the data column data_column_key
due to the RateMode in relation to the reference column reference_column_key
. Be sure that the value types of the table entries of the data column and the reference data column is a number, i.e. double, float, (unsigned) int, and so on.
As this class has no information on the space dimension upon which the reference column vs. the value column is based upon, it needs to be passed as last argument to this method. The default dimension for the reference column is 2, which is appropriate for the number of cells in 2d. If you work in 3d, set the number to 3. If the reference column is \(1/h\), remember to set the dimension to 1 also when working in 3d to get correct rates.
The new rate column and the data column will be merged to a supercolumn. The tex caption of the supercolumn will be (by default) the same as the one of the data column. This may be changed by using the set_tex_supercaption (...)
function of the base class TableHandler.
This method behaves in the following way:
If RateMode is reduction_rate, then the computed output is \( \frac{e_{n-1}/k_{n-1}}{e_n/k_n}, \) where \(k\) is the reference column (no dimension dependence!).
If RateMode is reduction_rate_log2, then the computed output is \( dim \frac{\log |e_{n-1}/e_{n}|}{\log |k_n/k_{n-1}|} \).
This is useful, for example, if we use as reference key the number of degrees of freedom or better, the number of cells. Assuming that the error is proportional to \( C (1/\sqrt{k})^r \) in 2d, then this method will produce the rate \(r\) as a result. For general dimension, as described by the last parameter of this function, the formula needs to be \( C (1/\sqrt[dim]{k})^r \).
Definition at line 22 of file convergence_table.cc.
void ConvergenceTable::evaluate_convergence_rates | ( | const std::string & | data_column_key, |
const RateMode | rate_mode ) |
Evaluate the convergence rates of the data column data_column_key
due to the RateMode. Be sure that the value types of the table entries of the data column is a number, i.e. double, float, (unsigned) int, and so on.
The new rate column and the data column will be merged to a supercolumn. The tex caption of the supercolumn will be (by default) the same as the one of the data column. This may be changed by using the set_tex_supercaption() function of the base class TableHandler.
Definition at line 127 of file convergence_table.cc.
void ConvergenceTable::omit_column_from_convergence_rate_evaluation | ( | const std::string & | key | ) |
Omit this column key
(not supercolumn!) from the evaluation of the convergence rates of ‘all’ columns (see the following two functions).
The Column::flag==1 is reserved for omitting the column from convergence rate evaluation.
Definition at line 219 of file convergence_table.cc.
void ConvergenceTable::evaluate_all_convergence_rates | ( | const std::string & | reference_column_key, |
const RateMode | rate_mode ) |
Evaluate convergence rates due to the rate_mode
in relation to the reference column reference_column_key
. This function evaluates the rates of ALL columns except of the columns that are to be omitted (see previous function) and except of the columns that are previously evaluated rate columns. This function allows to evaluate the convergence rate for almost all columns of a table without calling evaluate_convergence_rates() for each column separately.
Example: Columns like n cells
or n dofs
columns may be wanted to be omitted in the evaluation of the convergence rates. Hence they should omitted by calling the omit_column_from_convergence_rate_evaluation().
Definition at line 231 of file convergence_table.cc.
void ConvergenceTable::evaluate_all_convergence_rates | ( | const RateMode | rate_mode | ) |
Evaluate convergence rates due to the rate_mode
. This function evaluates the rates of ALL columns except of the columns that are to be omitted (see previous function) and except of the columns that are previously evaluated rate columns. This function allows to evaluate the convergence rate for almost all columns of a table without calling evaluate_convergence_rates() for each column separately.
Example: Columns like n cells
or n dofs
columns may be wanted to be omitted in the evaluation of the convergence rates. Hence they should omitted by calling the omit_column_from_convergence_rate_evaluation().
Definition at line 247 of file convergence_table.cc.
|
inherited |
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 192 of file table_handler.cc.
|
inherited |
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::uint64_t, std::string
or a compiler error will result.
Definition at line 945 of file table_handler.h.
|
inherited |
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 206 of file table_handler.cc.
|
inherited |
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 232 of file table_handler.cc.
|
inherited |
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.
|
inherited |
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 283 of file table_handler.cc.
|
inherited |
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 346 of file table_handler.cc.
|
inherited |
Set the scientific_flag
. True means scientific, false means fixed point notation.
Definition at line 359 of file table_handler.cc.
|
inherited |
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 297 of file table_handler.cc.
|
inherited |
Set the tex caption of the entire table
for tex output.
Definition at line 307 of file table_handler.cc.
|
inherited |
Set the label of this table
for tex output.
Definition at line 315 of file table_handler.cc.
|
inherited |
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 323 of file table_handler.cc.
|
inherited |
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 334 of file table_handler.cc.
|
inherited |
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 371 of file table_handler.cc.
|
inherited |
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 587 of file table_handler.cc.
|
inherited |
Clear the rows of the table, i.e. calls clear() on all the underlying storage data structures.
Definition at line 730 of file table_handler.cc.
|
inherited |
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 795 of file table_handler.cc.
|
inherited |
Read or write the data of this object to or from a stream for the purpose of serialization using the BOOST serialization library.
Definition at line 1004 of file table_handler.h.
|
protectedinherited |
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 764 of file table_handler.cc.
|
protectedinherited |
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 743 of file table_handler.cc.
|
protectedinherited |
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 760 of file table_handler.h.
|
mutableprotectedinherited |
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 769 of file table_handler.h.
|
protectedinherited |
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 779 of file table_handler.h.
|
protectedinherited |
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 788 of file table_handler.h.
|
protectedinherited |
The caption of the table itself.
Definition at line 793 of file table_handler.h.
|
protectedinherited |
The label of the table.
Definition at line 797 of file table_handler.h.
|
protectedinherited |
Flag indicating whether auto-fill mode should be used.
Definition at line 802 of file table_handler.h.