Reference documentation for deal.II version 9.1.1
\(\newcommand{\dealcoloneq}{\mathrel{\vcenter{:}}=}\)
Namespaces | Classes | Functions
Utilities Namespace Reference

Namespaces

 CUDA
 
 LinearAlgebra
 
 MPI
 
 System
 
 Trilinos
 

Classes

struct  fixed_int_power
 
struct  fixed_int_power< a, 0 >
 

Functions

std::string dealii_version_string ()
 
template<int dim, typename Number >
std::vector< std::array< std::uint64_t, dim > > inverse_Hilbert_space_filling_curve (const std::vector< Point< dim, Number >> &points, const int bits_per_dim=64)
 
template<int dim>
std::vector< std::array< std::uint64_t, dim > > inverse_Hilbert_space_filling_curve (const std::vector< std::array< std::uint64_t, dim >> &points, const int bits_per_dim=64)
 
template<int dim>
std::uint64_t pack_integers (const std::array< std::uint64_t, dim > &index, const int bits_per_dim)
 
std::string int_to_string (const unsigned int value, const unsigned int digits=numbers::invalid_unsigned_int)
 
template<typename number >
std::string to_string (const number value, const unsigned int digits=numbers::invalid_unsigned_int)
 
unsigned int needed_digits (const unsigned int max_number)
 
int string_to_int (const std::string &s)
 
std::string dim_string (const int dim, const int spacedim)
 
std::vector< int > string_to_int (const std::vector< std::string > &s)
 
double string_to_double (const std::string &s)
 
std::vector< double > string_to_double (const std::vector< std::string > &s)
 
std::vector< std::string > split_string_list (const std::string &s, const std::string &delimiter=",")
 
std::vector< std::string > split_string_list (const std::string &s, const char delimiter)
 
std::vector< std::string > break_text_into_lines (const std::string &original_text, const unsigned int width, const char delimiter=' ')
 
bool match_at_string_start (const std::string &name, const std::string &pattern)
 
std::pair< int, unsigned int > get_integer_at_position (const std::string &name, const unsigned int position)
 
std::string replace_in_string (const std::string &input, const std::string &from, const std::string &to)
 
std::string trim (const std::string &input)
 
double generate_normal_random_number (const double a, const double sigma)
 
template<class T >
std::string type_to_string (const T &t)
 
template<int N, typename T >
fixed_power (const T t)
 
constexpr unsigned int pow (const unsigned int base, const int iexp)
 
template<typename Iterator , typename T >
Iterator lower_bound (Iterator first, Iterator last, const T &val)
 
template<typename Iterator , typename T , typename Comp >
Iterator lower_bound (Iterator first, Iterator last, const T &val, const Comp comp)
 
std::vector< unsigned int > reverse_permutation (const std::vector< unsigned int > &permutation)
 
std::vector< unsigned int > invert_permutation (const std::vector< unsigned int > &permutation)
 
std::vector< unsigned long long int > reverse_permutation (const std::vector< unsigned long long int > &permutation)
 
std::vector< unsigned long long int > invert_permutation (const std::vector< unsigned long long int > &permutation)
 
template<typename T >
size_t pack (const T &object, std::vector< char > &dest_buffer, const bool allow_compression=true)
 
template<typename T >
std::vector< char > pack (const T &object, const bool allow_compression=true)
 
template<typename T >
unpack (const std::vector< char > &buffer, const bool allow_compression=true)
 
template<typename T >
unpack (const std::vector< char >::const_iterator &cbegin, const std::vector< char >::const_iterator &cend, const bool allow_compression=true)
 
template<typename T , int N>
void unpack (const std::vector< char > &buffer, T(&unpacked_object)[N], const bool allow_compression=true)
 
template<typename T , int N>
void unpack (const std::vector< char >::const_iterator &cbegin, const std::vector< char >::const_iterator &cend, T(&unpacked_object)[N], const bool allow_compression=true)
 
template<typename To , typename From >
std::unique_ptr< To > dynamic_unique_cast (std::unique_ptr< From > &&p)
 
static ::ExceptionBaseExcInvalidNumber2StringConversersion (unsigned int arg1, unsigned int arg2)
 
static ::ExceptionBaseExcInvalidNumber (unsigned int arg1)
 
static ::ExceptionBaseExcCantConvertString (std::string arg1)
 

Detailed Description

A namespace for utility functions that are not particularly specific to finite element computing or numerical programs, but nevertheless are needed in various contexts when writing applications.

Author
Wolfgang Bangerth, 2005

Function Documentation

◆ dealii_version_string()

std::string Utilities::dealii_version_string ( )

Return a string of the form "deal.II version x.y.z" where "x.y.z" identifies the version of deal.II you are using. This information is also provided by the DEAL_II_PACKAGE_NAME and DEAL_II_PACKAGE_VERSION preprocessor variables.

Definition at line 88 of file utilities.cc.

◆ inverse_Hilbert_space_filling_curve() [1/2]

template<int dim, typename Number >
std::vector< std::array< std::uint64_t, dim > > Utilities::inverse_Hilbert_space_filling_curve ( const std::vector< Point< dim, Number >> &  points,
const int  bits_per_dim = 64 
)

Assign to each point in points an index using the Hilbert space filling curve. To that end, a bounding box for points will be determined, based on which their integer coordinates are calculated. The linear index is given as a dim-collection of bits, from high to low. This is done in order to keep the maximum resolution in terms of bit depth along each axis. Note that this dim-integer index can still be easily used for sorting and ordering, for example using the lexicographic ordering of tuples of integers.

The depth of the Hilbert curve (i.e. the number of bits per dimension) by default is equal to 64.

Note
This function can also handle degenerate cases, e.g. when the bounding box has zero size in one of the dimensions.

Definition at line 139 of file utilities.cc.

◆ inverse_Hilbert_space_filling_curve() [2/2]

template<int dim>
std::vector< std::array< std::uint64_t, dim > > Utilities::inverse_Hilbert_space_filling_curve ( const std::vector< std::array< std::uint64_t, dim >> &  points,
const int  bits_per_dim = 64 
)

Same as above, but for points in integer coordinates.

Definition at line 248 of file utilities.cc.

◆ pack_integers()

template<int dim>
std::uint64_t Utilities::pack_integers ( const std::array< std::uint64_t, dim > &  index,
const int  bits_per_dim 
)

Pack the least significant bits_per_dim bits from each element of index (starting from last) into a single unsigned integer. The last element of index will be used to set the first bits_per_dim bits in the resulting integer, the second to last element is used to set the next bits_per_dim bits, etc.. To fit all the data into the output, the following should hold bits_per_dim * dim <= 64.

The function is useful in debugging and visualization of indices returned by inverse_Hilbert_space_filling_curve().

Note
There is no need to use this function in order to compare indices returned by inverse_Hilbert_space_filling_curve(), as that can easily be done via std::lexicographical_compare().

Definition at line 360 of file utilities.cc.

◆ int_to_string()

std::string Utilities::int_to_string ( const unsigned int  value,
const unsigned int  digits = numbers::invalid_unsigned_int 
)

Convert a number value to a string, with as many digits as given to fill with leading zeros.

If the second parameter is left at its default value, the number is not padded with leading zeros. The result is then the same as if the standard C function itoa() had been called.

When calling this function signed integers are implicitly converted to unsigned integers and long integers might experience an overflow.

Note
The use of this function is discouraged and users should use Utilities::to_string() instead. In its current implementation the function simply calls to_string<unsigned int>().

Definition at line 383 of file utilities.cc.

◆ to_string()

template<typename number >
std::string Utilities::to_string ( const number  value,
const unsigned int  digits = numbers::invalid_unsigned_int 
)

Convert a number value to a string, with digits characters. The string is padded with leading zeros, after a possible minus sign. Therefore the total number of padding zeros is digits minus any signs, decimal points and digits of value.

If the second parameter is left at its default value, the number is not padded with leading zeros. The result is then the same as if the boost function lexical_cast<std::string>() had been called.

Definition at line 392 of file utilities.cc.

◆ needed_digits()

unsigned int Utilities::needed_digits ( const unsigned int  max_number)

Determine how many digits are needed to represent numbers at most as large as the given number.

Definition at line 467 of file utilities.cc.

◆ string_to_int() [1/2]

int Utilities::string_to_int ( const std::string &  s)

Given a string, convert it to an integer. Throw an assertion if that is not possible.

Definition at line 488 of file utilities.cc.

◆ dim_string()

std::string Utilities::dim_string ( const int  dim,
const int  spacedim 
)

Return a string describing the dimensions of the object. Often, functions in the deal.II library as well as in user codes need to define a string containing the template dimensions of some objects defined using two template parameters: dim (the topological dimension of the object) and spacedim (the dimension of the embedding Euclidean space). Since in all deal.II classes, by default spacedim is equal to dimension, the above string is usually contracted to "<dim>", instead of "<dim,spacedim>". This function returns a string containing "dim" if dim is equal to spacedim, otherwise it returns "dim,spacedim".

Definition at line 457 of file utilities.cc.

◆ string_to_int() [2/2]

std::vector< int > Utilities::string_to_int ( const std::vector< std::string > &  s)

Given a list of strings, convert it to a list of integers. Throw an assertion if that is not possible.

Definition at line 516 of file utilities.cc.

◆ string_to_double() [1/2]

double Utilities::string_to_double ( const std::string &  s)

Given a string, convert it to an double. Throw an assertion if that is not possible.

Definition at line 527 of file utilities.cc.

◆ string_to_double() [2/2]

std::vector< double > Utilities::string_to_double ( const std::vector< std::string > &  s)

Given a list of strings, convert it to a list of doubles. Throw an assertion if that is not possible.

Definition at line 555 of file utilities.cc.

◆ split_string_list() [1/2]

std::vector< std::string > Utilities::split_string_list ( const std::string &  s,
const std::string &  delimiter = "," 
)

Given a string that contains text separated by a delimiter, split it into its components; for each component, remove leading and trailing spaces. The default value of the delimiter is a comma, so that the function splits comma separated lists of strings.

To make data input from tables simpler, if the input string ends in a delimiter (possibly followed by an arbitrary amount of whitespace), then this last delimiter is ignored. For example,

Utilities::split_string_list("abc; def; ghi; ", ';');

yields the same 3-element list of output {"abc","def","ghi"} as you would get if the input had been

Utilities::split_string_list("abc; def; ghi", ';');

or

Utilities::split_string_list("abc; def; ghi;", ';');

As a consequence of this rule, a call like

yields a one-element list. Because of the trimming of whitespace, the single element is the empty string.

This function can digest the case that the delimiter is a space. In this case, it returns all words in the string. Combined with the rules above, this implies that

Utilities::split_string_list("abc def ghi ", ' ');

yields again the 3-element list of output {"abc","def","ghi"} from above despite the presence of space at the end of the string. Furthermore,

yields an empty list regardless of the number of spaces in the string.

Definition at line 566 of file utilities.cc.

◆ split_string_list() [2/2]

std::vector< std::string > Utilities::split_string_list ( const std::string &  s,
const char  delimiter 
)

Specialization of split_string_list() for the case where the delimiter is a single char.

Definition at line 611 of file utilities.cc.

◆ break_text_into_lines()

std::vector< std::string > Utilities::break_text_into_lines ( const std::string &  original_text,
const unsigned int  width,
const char  delimiter = ' ' 
)

Take a text, usually a documentation or something, and try to break it into individual lines of text at most width characters wide, by breaking at positions marked by delimiter in the text. If this is not possible, return the shortest lines that are longer than width. The default value of the delimiter is a space character. If original_text contains newline characters (
), the string is split at these locations, too.

Definition at line 620 of file utilities.cc.

◆ match_at_string_start()

bool Utilities::match_at_string_start ( const std::string &  name,
const std::string &  pattern 
)

Return true if the given pattern string appears in the first position of the string.

Definition at line 700 of file utilities.cc.

◆ get_integer_at_position()

std::pair< int, unsigned int > Utilities::get_integer_at_position ( const std::string &  name,
const unsigned int  position 
)

Read a (signed) integer starting at the position in name indicated by the second argument, and return this integer as a pair together with how many characters it takes up in the string.

If no integer can be read at the indicated position, return (-1,numbers::invalid_unsigned_int)

Definition at line 715 of file utilities.cc.

◆ replace_in_string()

std::string Utilities::replace_in_string ( const std::string &  input,
const std::string &  from,
const std::string &  to 
)

Return a string with all occurrences of from in input replaced by to.

Definition at line 411 of file utilities.cc.

◆ trim()

std::string Utilities::trim ( const std::string &  input)

Return a string with all standard whitespace characters (including '\t', '\n', and '\r') at the beginning and end of input removed.

Definition at line 430 of file utilities.cc.

◆ generate_normal_random_number()

double Utilities::generate_normal_random_number ( const double  a,
const double  sigma 
)

Generate a random number from a normalized Gaussian probability distribution centered around a and with standard deviation sigma. The returned number will be different every time the function is called.

This function is reentrant, i.e., it can safely be called from multiple threads at the same time. In addition, each thread will get the same sequence of numbers every time. On the other hand, if you run Threads::Task objects via the Threading Building Blocks, then tasks will be assigned to mostly random threads, and may get a different sequence of random numbers in different runs of the program, since a previous task may already have consumed the first few random numbers generated for the thread you're on. If this is a problem, you need to create your own random number generator objects every time you want to start from a defined point.

Note
Like the system function rand(), this function produces the same sequence of random numbers every time a program is started. This is an important property for debugging codes, but it makes it impossible to really verify statistical properties of a code. For rand(), you can call srand() to "seed" the random number generator to get different sequences of random numbers every time a program is called. However, this function does not allow seeding the random number generator. If you need this, as above, use one of the C++ or BOOST facilities.

Definition at line 757 of file utilities.cc.

◆ type_to_string()

template<class T >
std::string Utilities::type_to_string ( const T &  t)
inline

Return a string description of the type of the variable t.

In general, C++ uses mangled names to identify types. This function uses boost::core::demangle to return a human readable string describing the type of the variable passed as argument.

Author
Luca Heltai, 2019.

Definition at line 1058 of file utilities.h.

◆ fixed_power()

template<int N, typename T >
T Utilities::fixed_power ( const T  t)
inline

Calculate a fixed power, provided as a template argument, of a number.

This function provides an efficient way to calculate things like t^N where N is a known number at compile time.

Use this function as in fixed_power<dim> (n).

Definition at line 1031 of file utilities.h.

◆ pow()

constexpr unsigned int Utilities::pow ( const unsigned int  base,
const int  iexp 
)

A replacement for std::pow that allows compile-time calculations for constant expression arguments. The exponent iexp must not be negative.

Definition at line 428 of file utilities.h.

◆ lower_bound() [1/2]

template<typename Iterator , typename T >
Iterator Utilities::lower_bound ( Iterator  first,
Iterator  last,
const T &  val 
)
inline

Optimized replacement for std::lower_bound for searching within the range of column indices. Slashes execution time by approximately one half for the present application, partly because the binary search is replaced by a linear search for small loop lengths.

Another reason for this function is rather obscure: when using the GCC libstdc++ function std::lower_bound, complexity is O(log(N)) as required. However, when using the debug version of the GCC libstdc++ as we do when running the testsuite, then std::lower_bound tests whether the sequence is in fact partitioned with respect to the pivot 'value' (i.e. in essence that the sequence is sorted as required for binary search to work). However, verifying this means that the complexity of std::lower_bound jumps to O(N); we call this function O(N) times below, making the overall complexity O(N**2). The consequence is that a few tests with big meshes completely run off the wall time limit for tests and fail with the libstdc++ debug mode

This function simply makes the assumption that the sequence is sorted, and we simply don't do the additional check.

Definition at line 1067 of file utilities.h.

◆ lower_bound() [2/2]

template<typename Iterator , typename T , typename Comp >
Iterator Utilities::lower_bound ( Iterator  first,
Iterator  last,
const T &  val,
const Comp  comp 
)
inline

The same function as above, but taking an argument that is used to compare individual elements of the sequence of objects pointed to by the iterators.

Definition at line 1076 of file utilities.h.

◆ reverse_permutation() [1/2]

std::vector< unsigned int > Utilities::reverse_permutation ( const std::vector< unsigned int > &  permutation)

Given a permutation vector (i.e. a vector \(p_0\ldots p_{N-1}\) where each \(p_i\in [0,N)\) and \(p_i\neq p_j\) for \(i\neq j\)), produce the reverse permutation \(q_i=N-1-p_i\).

Definition at line 776 of file utilities.cc.

◆ invert_permutation() [1/2]

std::vector< unsigned int > Utilities::invert_permutation ( const std::vector< unsigned int > &  permutation)

Given a permutation vector (i.e. a vector \(p_0\ldots p_{N-1}\) where each \(p_i\in [0,N)\) and \(p_i\neq p_j\) for \(i\neq j\)), produce the inverse permutation \(q_0\ldots q_{N-1}\) so that \(q_{p_i}=p_{q_i}=i\).

Definition at line 790 of file utilities.cc.

◆ reverse_permutation() [2/2]

std::vector< unsigned long long int > Utilities::reverse_permutation ( const std::vector< unsigned long long int > &  permutation)

Given a permutation vector (i.e. a vector \(p_0\ldots p_{N-1}\) where each \(p_i\in [0,N)\) and \(p_i\neq p_j\) for \(i\neq j\)), produce the reverse permutation \(q_i=N-1-p_i\).

Definition at line 812 of file utilities.cc.

◆ invert_permutation() [2/2]

std::vector< unsigned long long int > Utilities::invert_permutation ( const std::vector< unsigned long long int > &  permutation)

Given a permutation vector (i.e. a vector \(p_0\ldots p_{N-1}\) where each \(p_i\in [0,N)\) and \(p_i\neq p_j\) for \(i\neq j\)), produce the inverse permutation \(q_0\ldots q_{N-1}\) so that \(q_{p_i}=p_{q_i}=i\).

Definition at line 826 of file utilities.cc.

◆ pack() [1/2]

template<typename T >
size_t Utilities::pack ( const T &  object,
std::vector< char > &  dest_buffer,
const bool  allow_compression = true 
)

Given an arbitrary object of type T, use boost::serialization utilities to pack the object into a vector of characters and append it to the given buffer. The number of elements that have been added to the buffer will be returned. The object can be unpacked using the Utilities::unpack function below.

If the library has been compiled with ZLIB enabled, then the output buffer can be compressed. This can be triggered with the parameter allow_compression, and is only of effect if ZLIB is enabled.

If many consecutive calls with the same buffer are considered, it is recommended for reasons of performance to ensure that its capacity is sufficient.

Author
Timo Heister, Wolfgang Bangerth, 2017.

Definition at line 1174 of file utilities.h.

◆ pack() [2/2]

template<typename T >
std::vector< char > Utilities::pack ( const T &  object,
const bool  allow_compression = true 
)

Creates and returns a buffer solely for the given object, using the above mentioned pack function.

If the library has been compiled with ZLIB enabled, then the output buffer can be compressed. This can be triggered with the parameter allow_compression, and is only of effect if ZLIB is enabled.

Author
Timo Heister, Wolfgang Bangerth, 2017.

Definition at line 1246 of file utilities.h.

◆ unpack() [1/4]

template<typename T >
T Utilities::unpack ( const std::vector< char > &  buffer,
const bool  allow_compression = true 
)

Given a vector of characters, obtained through a call to the function Utilities::pack, restore its content in an object of type T.

This function uses boost::serialization utilities to unpack the object from a vector of characters, and it is the inverse of the function Utilities::pack().

The allow_compression parameter denotes if the buffer to read from could have been previously compressed with ZLIB, and is only of effect if ZLIB is enabled.

Note
Since no arguments to this function depend on the template type T, you must manually specify the template argument when calling this function.
If you want to pack() or unpack() arrays of objects, then the following works:
double array[3] = {1,2,3};
std::vector<char> buffer = Utilities::pack(array);
However, the converse does not:
array = Utilities::unpack<double[3]>(buffer);
This is because C++ does not allow functions to return arrays. Consequently, there is a separate unpack() function for arrays, see below.
Author
Timo Heister, Wolfgang Bangerth, 2017.

Definition at line 1318 of file utilities.h.

◆ unpack() [2/4]

template<typename T >
T Utilities::unpack ( const std::vector< char >::const_iterator &  cbegin,
const std::vector< char >::const_iterator &  cend,
const bool  allow_compression = true 
)

Same unpack function as above, but takes constant iterators on (a fraction of) a given packed buffer of type std::vector<char> instead.

The allow_compression parameter denotes if the buffer to read from could have been previously compressed with ZLIB, and is only of effect if ZLIB is enabled.

Author
Timo Heister, Wolfgang Bangerth, 2017.

Definition at line 1256 of file utilities.h.

◆ unpack() [3/4]

template<typename T , int N>
void Utilities::unpack ( const std::vector< char > &  buffer,
T(&)  unpacked_object[N],
const bool  allow_compression = true 
)

Given a vector of characters, obtained through a call to the function Utilities::pack, restore its content in an array of type T.

This function uses boost::serialization utilities to unpack the object from a vector of characters, and it is the inverse of the function Utilities::pack().

The allow_compression parameter denotes if the buffer to read from could have been previously compressed with ZLIB, and is only of effect if ZLIB is enabled.

Note
This function exists due to a quirk of C++. Specifically, if you want to pack() or unpack() arrays of objects, then the following works:
double array[3] = {1,2,3};
std::vector<char> buffer = Utilities::pack(array);
However, the converse does not:
array = Utilities::unpack<double[3]>(buffer);
This is because C++ does not allow functions to return arrays. The current function therefore allows to write
Utilities::unpack(buffer, array);
Note that unlike the other unpack() function, it is not necessary to explicitly specify the template arguments since they can be deduced from the second argument.
Author
Timo Heister, Wolfgang Bangerth, 2017.

Definition at line 1382 of file utilities.h.

◆ unpack() [4/4]

template<typename T , int N>
void Utilities::unpack ( const std::vector< char >::const_iterator &  cbegin,
const std::vector< char >::const_iterator &  cend,
T(&)  unpacked_object[N],
const bool  allow_compression = true 
)

Same unpack function as above, but takes constant iterators on (a fraction of) a given packed buffer of type std::vector<char> instead.

The allow_compression parameter denotes if the buffer to read from could have been previously compressed with ZLIB, and is only of effect if ZLIB is enabled.

Author
Timo Heister, Wolfgang Bangerth, 2017.

Definition at line 1326 of file utilities.h.

◆ dynamic_unique_cast()

template<typename To , typename From >
std::unique_ptr<To> Utilities::dynamic_unique_cast ( std::unique_ptr< From > &&  p)

Convert an object of type std::unique_ptr<From> to an object of type std::unique_ptr<To>, where it is assumed that we can cast the pointer to From to a pointer to To using a dynamic_cast – in other words, we assume that From and To are connected through a class hierarchy, and that the object pointed to is in fact of a type that contains both a From and a To. An example is if either To is derived from From or the other way around.

The function throws an exception of type std::bad_cast if the dynamic_cast does not succeed. This is the same exception you would get if a regular dynamic_cast between object types (but not pointer types) does not succeed.

An example of how this function works is as follows:

// A base class. Assume that it has virtual
// functions so that dynamic_cast can work.
class B
{
...
};
// A derived class
class D : public B
{
...
};
// A factory function
std::unique_ptr<B> create_object (...)
{
...
}
void foo (...)
{
std::unique_ptr<B> b = create_object (...);
// Assume that we know for some reason that the object above must
// have created a D object but returned it as a std::unique_ptr<B>.
// In order to access the D functionality, we need to cast the
// pointer. Use the equivalent to dynamic_cast:
std::unique_ptr<D> d = dynamic_unique_cast<D>(std::move(b));
// If the object really was a D, then 'd' now points to it. Note
// also that in accordance with the semantics of std::unique_ptr,
// it was necessary to std::move the 'b' object, and indeed 'b'
// now no longer points to anything -- ownership has been
// transferred to 'd'!
Note
This function does not try to convert the Deleter objects stored by std::unique_ptr objects. The function therefore only works if the deleter objects are at their defaults, i.e., if they are of type std::default_delete<To> and std::default_delete<From>.

Definition at line 738 of file utilities.h.