The ParsedConvergenceTable class. More...

#include <deal.II/base/parsed_convergence_table.h>

Public Member Functions
	ParsedConvergenceTable (const std::vector< std::string > &component_names={"u"}, const std::vector< std::set< VectorTools::NormType > > &list_of_error_norms={ {VectorTools::H1_norm, VectorTools::L2_norm, VectorTools::Linfty_norm}})

	ParsedConvergenceTable (const std::vector< std::string > &component_names, const std::vector< std::set< VectorTools::NormType > > &list_of_error_norms, const double exponent, const std::set< std::string > &extra_columns, const std::string &rate_key, const std::string &rate_mode, const std::string &error_file_name, const unsigned int precision, const bool compute_error)

void	add_parameters (ParameterHandler &prm)

template<int dim, int spacedim, typename VectorType >
void	error_from_exact (const DoFHandler< dim, spacedim > &vspace, const VectorType &solution, const Function< spacedim > &exact, const Function< spacedim > *weight=nullptr)

template<int dim, int spacedim, typename VectorType >
void	error_from_exact (const Mapping< dim, spacedim > &mapping, const DoFHandler< dim, spacedim > &vspace, const VectorType &solution, const Function< spacedim > &exact, const Function< spacedim > *weight=nullptr)

void	add_extra_column (const std::string &column_name, const std::function< double()> &custom_function, const bool compute_rate=true)

template<int dim, int spacedim, typename VectorType >
void	difference (const DoFHandler< dim, spacedim > &, const VectorType &, const VectorType &, const Function< spacedim > *weight=nullptr)

template<int dim, int spacedim, typename VectorType >
void	difference (const Mapping< dim, spacedim > &mapping, const DoFHandler< dim, spacedim > &, const VectorType &, const VectorType &, const Function< spacedim > *weight=nullptr)

void	output_table (std::ostream &out)

void	output_table ()

Private Member Functions
void	prepare_table_for_output ()

Private Attributes
const std::vector< std::string >	component_names

const std::vector< std::string >	unique_component_names

const std::vector< ComponentMask >	unique_component_masks

std::map< std::string, std::pair< std::function< double()>, bool > >	extra_column_functions

std::vector< std::set< VectorTools::NormType > >	norms_per_unique_component

double	exponent

ConvergenceTable	table

std::set< std::string >	extra_columns

std::string	rate_key

std::string	rate_mode

unsigned int	precision

std::string	error_file_name

bool	compute_error

Detailed Description

The ParsedConvergenceTable class.

This class simplifies the construction of convergence tables, reading the options for the generation of the table from a parameter file. It provides a series of methods that can be used to compute the error given a reference exact solution, or the difference between two numerical solutions, or any other custom computation of the error, given via std::function objects.

An example usage of this class is given by

ParsedConvergenceTable table;
 
ParameterHandler prm;
table.add_parameters(prm);
 
for (unsigned int i = 0; i < n_cycles; ++i)
  {
    ... // do some computations
    table.error_from_exact(dof_handler, solution, exact_solution);
  }
table.output_table(std::cout);

The above code constructs a ParsedConvergenceTable that works for scalar problems, and will produce an error table with H1_norm, L2_norm, and Linfty_norm norms of the error.

Whenever a call to the methods error_from_exact() or difference() is made, the instance of this class inspects its parameters, computes all norms specified by the parameter given at construction time, possibly modified via a parameter file, computes all extra column entries specified using the method add_extra_column(), and writes one row of the convergence table.

Once you have finished with the computations, a call to output_table() will generate a formatted convergence table on the provided stream, and to the file (if any) specified in the parameter file.

With a small modification, the same code can be used to estimate the errors of mixed or multi-physics problems, e.g.:

using namespace VectorTools;
ParsedConvergenceTable table({"u,u,p"},{{H1_norm, L2_norm}, {L2_norm}});
 
ParameterHandler prm;
table.add_parameters(prm);
 
for (unsigned int i = 0; i < n_cycles; ++i)
  {
    ... // do some computations
    table.error_from_exact(dof_handler, solution, exact_solution);
  }
table.output_table(std::cout);

The above code assumes that you are solving a Stokes problem with three components. Two components for the vector velocity field u, and one component for the pressure field p, and will produce an error table with H1 and L2 norm of the error in the velocity field (first two, components) and L2 error in the pressure field.

You may also call table.output_table() without arguments, to write the table only to the file specified in the parameter file.

By calling the method add_parameters() passing a ParameterHandler object, the following options will be defined in the given ParameterHandler object (in the current level of the ParameterHandler object, i.e., whatever level you have entered with the ParameterHandler::enter_subsection() method), and can be modified at run time through a parameter file :

set Enable computation of the errors = true
set Error file name                  =
set Error precision                  = 3
set Exponent for p-norms             = 2
set Extra columns                    = dofs, cells
set List of error norms to compute   = Linfty_norm, L2_norm, H1_norm
set Rate key                         = dofs
set Rate mode                        = reduction_rate_log2

When using this class, please cite

@article{SartoriGiulianiBardelloni-2018-a,
 Author = {Sartori, Alberto and Giuliani, Nicola and
           Bardelloni, Mauro and Heltai, Luca},
 Journal = {SoftwareX},
 Pages = {318--327},
 Title = {{deal2lkit: A toolkit library for high performance
           programming in deal.II}},
 Doi = {10.1016/j.softx.2018.09.004},
 Volume = {7},
 Year = {2018}}

Definition at line 136 of file parsed_convergence_table.h.

Constructor & Destructor Documentation

◆ ParsedConvergenceTable() [1/2]

ParsedConvergenceTable::ParsedConvergenceTable	(	const std::vector< std::string > &	component_names = `{"u"}`,
		const std::vector< std::set< VectorTools::NormType > > &	list_of_error_norms = `{ {VectorTools::H1_norm, VectorTools::L2_norm, VectorTools::Linfty_norm}}`
	)

Minimal constructor for ParsedConvergenceTable objects.

The number of components must match the number of components of the finite element space that is used to compute the errors. If a component name is repeated, than it is interpreted as a vector field, and the errors of the repeated components are grouped together.

The size of the vector list_of_error_norms must match the number of unique component names, and may contain zero or more comma separated identifiers for the norm to compute for each component (see the documentation of VectorTools::NormType for the available options).

For example, the following constructor

using namespace VectorTools;
ParsedConvergenceTable table({"u", "v", "v"},
                             {{Linfty_norm}, {L2_norm, H1_norm}});

would produce (if the parameter file is left untouched) a table similar to

cells dofs u_Linfty_norm    v_L2_norm      v_H1_norm
   9    1.183e-01 -    5.156e-02 -    2.615e-01 -
  25   3.291e-02 2.50 1.333e-02 2.65 1.272e-01 1.41
  81   8.449e-03 2.31 3.360e-03 2.34 6.313e-02 1.19
 289  2.126e-03 2.17 8.418e-04 2.18 3.150e-02 1.09
1089 5.325e-04 2.09 2.106e-04 2.09 1.574e-02 1.05

See the other constructor for a documentation of all the parameters you can change.

Parameters

component_names	Specify the names of the components;
list_of_error_norms	Specify what error norms to compute for each unique component name.

Definition at line 63 of file parsed_convergence_table.cc.

◆ ParsedConvergenceTable() [2/2]

ParsedConvergenceTable::ParsedConvergenceTable	(	const std::vector< std::string > &	component_names,
		const std::vector< std::set< VectorTools::NormType > > &	list_of_error_norms,
		const double	exponent,
		const std::set< std::string > &	extra_columns,
		const std::string &	rate_key,
		const std::string &	rate_mode,
		const std::string &	error_file_name,
		const unsigned int	precision,
		const bool	compute_error
	)

Full constructor for ParsedConvergenceTable.

Parameters

component_names	Names of the components. Repeated consecutive names are interpreted as components of a vector valued field;
list_of_error_norms	Specify what error norms to compute for each unique component name;
exponent	The exponent to use in p-norms;
extra_columns	Extra columns to add. These may be "cells" or "dofs";
rate_key	Specify the extra column by which we will compute the error rates. This key can either be one of "cells" or "dofs", or, if you add extra columns to the table via the method add_extra_column(), it may be one of the extra columns you added;
rate_mode	Specify the rate mode to use when computing error rates. This maybe either "reduction_rate", "reduction_rate_log2", or "none". See the documentation of ConvergenceTable::RateMode for an explanation of how each of this mode behaves;
error_file_name	Name of error output file (with extension txt, gpl, tex, or org). If different from the empty string, than output_table() also writes in this file in the format deduced from its extension;
precision	How many digits to use when writing the error;
compute_error	Control whether the filling of the table is enabled or not. This flag may be used to disable at run time any error computation;

The parameters you specify with this constructor can be written to a ParameterHandler object by calling the add_parameters() method. Once you call the add_parameters() method, the following options will be defined in the given ParameterHandler object, and the parameters of the instance of this class will follow the modification you make to the ParameterHandler object at run time:

# Listing of Parameters
# ---------------------
# When set to false, no computations are performed.
set Enable computation of the errors = true
 
# Set this to a filename with extension .txt, .gpl, .org, or .tex to enable
# writing the convergence table to a file.
set Error file name                  =
 
# Number of digits to use when printing the error.
set Error precision                  = 3
 
# Extra columns to add to the table. Available options are dofs and cells.
set Extra columns                    = dofs, cells
 
# The exponent to use when computing p-norms.
set Exponent for p-norms             = 2
 
# Each component is separated by a semicolon and each norm by a comma. See
# the documentation of VectorTools::NormType for a list of implemented
# norms. If you want to skip a component, leave its entry empty.
set List of error norms to compute   = Linfty_norm, L2_norm, H1_norm
 
# Key to use when computing convergence rates. If this is set to a
# column that is not present, or to none, then no error rates are computed.
set Rate key                         = dofs
 
# What type of error rate to compute. Available options are
# reduction_rate_log2, reduction_rate, and none.
set Rate mode                        = reduction_rate_log2

Definition at line 79 of file parsed_convergence_table.cc.

Member Function Documentation

◆ add_parameters()

void ParsedConvergenceTable::add_parameters ( ParameterHandler & prm )

Attach all the parameters in this class to entries of the parameter handler prm. Whenever the content of prm changes, the parameters of this class will be updated.

Definition at line 108 of file parsed_convergence_table.cc.

◆ error_from_exact() [1/2]

template<int dim, int spacedim, typename VectorType >

void ParsedConvergenceTable::error_from_exact	(	const DoFHandler< dim, spacedim > &	vspace,
		const VectorType &	solution,
		const Function< spacedim > &	exact,
		const Function< spacedim > *	weight = `nullptr`
	)

Add a row to the error table, containing the error between solution and the exact function, in the norm(s) specified in the parameter file.

If you specify a weight function during this call, then this is used to compute weighted errors. The weight function can be either a scalar function (which will be used for all components), or a vector function. When it is a vector function, an assertion is triggered if the number of components does not coincide with the number of components of the underlying finite element space.

◆ error_from_exact() [2/2]

template<int dim, int spacedim, typename VectorType >

void ParsedConvergenceTable::error_from_exact	(	const Mapping< dim, spacedim > &	mapping,
		const DoFHandler< dim, spacedim > &	vspace,
		const VectorType &	solution,
		const Function< spacedim > &	exact,
		const Function< spacedim > *	weight = `nullptr`
	)

Same as above, with a different mapping.

◆ add_extra_column()

void ParsedConvergenceTable::add_extra_column	(	const std::string &	column_name,
		const std::function< double()> &	custom_function,
		const bool	compute_rate = `true`
	)

Add an additional column (with name column_name) to the table, by invoking the function custom_function, when calling error_from_exact() or difference().

You can call this method as many times as you want. If column_name was already used in a previous call, then calling this method with the same name will overwrite whatever function you had previously specified. If you use a lambda function for this call, make sure that the variables used internally in the lambda function remain valid until the call to error_from_exact() or difference().

Make sure you add all extra columns before the first call to error_from_exact() or difference(). Adding additional columns to the convergence table after you already started filling the table will trigger an exception.

This method may be used, for example, to compute the error w.r.t. to time step increments in time, for example:

using namespace VectorTools;
ParsedConvergenceTable table({"u"}, {{L2_norm}});
 
double dt = .5;
auto dt_function = [&]() {
       return dt;
};
 
table.add_extra_column("dt", dt_function, false);
 
for (unsigned int i = 0; i < n_cycles; ++i)
  {
    // ... compute solution at the current dt
 
    table.error_from_exact(dof_handler, solution, exact_solution);
    dt /= 2.0;
  }
table.output_table(std::cout);

will produce a table similar to

   dt        u_L2_norm
000e-1    5.156e-02 -
500e-2    1.333e-02 2.65
250e-2    3.360e-03 2.34
250e-3    8.418e-04 2.18

provided that you use the following parameter file (only non default entries are shown here):

set Extra columns                  =
set List of error norms to compute = L2_norm
set Rate key                       = dt

Parameters

column_name	Name of the column to add;
custom_function	Function that will be called to fill the given entry. You need to make sure that the scope of this function is valid up to the call to error_from_exact() or difference();
compute_rate	If set to true, then this column will be included in the list of columns for which error rates are computed. You may want to set this to false if you want to compute error rates with respect to this column. In this case, you should also specify `column_name` as the rate key in the parameter file.

Definition at line 263 of file parsed_convergence_table.cc.

◆ difference() [1/2]

template<int dim, int spacedim, typename VectorType >

void ParsedConvergenceTable::difference	(	const DoFHandler< dim, spacedim > &	,
		const VectorType &	,
		const VectorType &	,
		const Function< spacedim > *	weight = `nullptr`
	)

Difference between two solutions in the same vector space.

◆ difference() [2/2]

template<int dim, int spacedim, typename VectorType >

void ParsedConvergenceTable::difference	(	const Mapping< dim, spacedim > &	mapping,
		const DoFHandler< dim, spacedim > &	,
		const VectorType &	,
		const VectorType &	,
		const Function< spacedim > *	weight = `nullptr`
	)

Same as above, with a non default mapping.

◆ output_table() [1/2]

void ParsedConvergenceTable::output_table ( std::ostream & out )

Write the error table to the out stream (in text format), and (possibly) to the file stream specified in the parameters (with the format deduced from the file name extension).

Definition at line 216 of file parsed_convergence_table.cc.