Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
utilities.h File Reference
#include <core/output_struct.h>
#include <deal.II/base/conditional_ostream.h>
#include <deal.II/base/exceptions.h>
#include <deal.II/base/mpi_remote_point_evaluation.h>
#include <deal.II/base/parameter_handler.h>
#include <deal.II/base/patterns.h>
#include <deal.II/base/point.h>
#include <deal.II/base/table_handler.h>
#include <deal.II/base/tensor.h>
#include <deal.II/dofs/dof_handler.h>
#include <deal.II/fe/fe_values.h>
#include <deal.II/numerics/vector_tools.h>
#include <deal.II/particles/particle_iterator.h>
#include <boost/archive/text_iarchive.hpp>
#include <boost/archive/text_oarchive.hpp>
#include <magic_enum.hpp>
#include <algorithm>
#include <fstream>
#include <map>
#include <optional>
#include <string>
#include <string_view>
#include <tuple>
#include <type_traits>
#include <utility>
#include <vector>
Include dependency graph for utilities.h:

Go to the source code of this file.

Classes

class  statistics
struct  cell_comparison< dim >
struct  particle_comparison< dim >
struct  cut_cell_comparison< dim >
struct  cut_cell_hash< dim >

Typedefs

template<typename EnumType>
using DeprecatedEnumNames = std::vector<std::pair<std::string, EnumType>>

Functions

void add_statistics_to_table_handler (const std::string &variable, const statistics &stats, TableHandler &table)
template<typename T>
TableHandler make_table_scalars_vectors (const std::vector< T > &independent_values, const std::string &independent_column_name, const std::vector< std::vector< double > > &dependent_vector, const std::vector< std::string > &dependent_column_names, const unsigned int display_precision, const bool display_scientific_notation=false)
template<int dim, typename T>
TableHandler make_table_scalars_tensors (const std::vector< T > &independent_values, const std::string &independent_column_name, const std::vector< Tensor< 1, dim > > &dependent_vector, const std::vector< std::string > &dependent_column_names, const unsigned int display_precision, const bool display_scientific_notation=false)
template<int dim, typename T>
TableHandler make_table_scalars_tensors (const std::vector< T > &independent_values, const std::string &independent_column_name, const std::vector< std::vector< Tensor< 1, dim > > > &dependent_vector, const std::vector< std::string > &dependent_column_names, const unsigned int display_precision, const bool display_scientific_notation=false)
template<int dim>
TableHandler make_table_tensors_tensors (const std::vector< Tensor< 1, dim > > &independent_vector, const std::vector< std::string > &independent_column_names, const std::vector< Tensor< 1, dim > > &dependent_vector, const std::vector< std::string > &dependent_column_names, const unsigned int display_precision, const bool display_scientific_notation=false)
template<int dim>
TableHandler make_table_tensors_scalars (const std::vector< Tensor< 1, dim > > &independent_vector, const std::vector< std::string > &independent_column_names, const std::vector< double > &dependent_values, const std::string &dependent_column_name, const unsigned int display_precision, const bool display_scientific_notation=false)
double calculate_point_property (const double phase, const double property0, const double property1)
template<typename T>
constexpr int sgn (const T val) noexcept
template<typename T>
T clip (const T &n, const T &lower, const T &upper)
double calculate_point_property_cahn_hilliard (const double phase_cahn_hilliard, const double property0, const double property1)
void check_file_exists (const std::string &file_name, const std::string &file_description)
void fill_table_from_file (TableHandler &table, const std::string &file_name, const std::string &delimiter=" ")
void fill_vectors_from_file (std::map< std::string, std::vector< double > > &map, const std::string &file_name, const std::string &delimiter=" ")
void fill_string_vectors_from_file (std::map< std::string, std::vector< std::string > > &map, const std::string &file_name, const std::string &delimiter=" ")
void create_output_folder (const std::string &dirname)
void delete_output_folder (const std::string &dirname)
void announce_string (const ConditionalOStream &pcout, const std::string &expression, const char delimiter='-')
void announce_string (const ConditionalOStream &pcout, const std::string &expression, const unsigned int banner_size, const char delimiter='-')
void serialize_table (const TableHandler &table, const std::string &filename, const MPI_Comm &mpi_communicator, const bool serialize_on_rank_zero=true)
void deserialize_table (TableHandler &table, const std::string &filename, const MPI_Comm &mpi_communicator, const bool deserialize_on_rank_zero=true)
void serialize_tables_vector (const std::vector< OutputStructTableHandler > &table_output_structs, const MPI_Comm mpi_communicator)
void deserialize_tables_vector (std::vector< OutputStructTableHandler > &table_output_structs, const MPI_Comm mpi_communicator)
std::string get_last_value_of_parameter (const std::string &file_name, const std::string &parameter_name)
unsigned int get_dimension (const std::string &file_name)
int get_max_subsection_size (const std::string &file_name, const bool require_subsection_size=true)
template<typename EnumType>
requires std::is_enum_v<EnumType>
std::string enum_to_string (const EnumType value)
template<typename EnumType>
requires std::is_enum_v<EnumType>
EnumType string_to_enum (const std::string &name)
void warn_deprecated_parameter_value (const std::string &parameter_name, const std::string &deprecated_value, const std::string &new_value)
template<typename EnumType>
requires std::is_enum_v<EnumType>
std::string enum_to_selection (const DeprecatedEnumNames< EnumType > &deprecated_names={}, const std::vector< EnumType > &allowed_values={})
template<typename EnumType>
requires std::is_enum_v<EnumType>
std::string enum_to_choices (const std::vector< EnumType > &allowed_values={})
template<typename EnumType>
requires std::is_enum_v<EnumType>
void declare_enum_entry (ParameterHandler &prm, const std::string &entry_name, const EnumType default_value, const std::string &description, const DeprecatedEnumNames< EnumType > &deprecated_names={}, const std::vector< EnumType > &allowed_values={})
template<typename EnumType>
requires std::is_enum_v<EnumType>
EnumType string_to_enum (const std::string &name, const DeprecatedEnumNames< EnumType > &deprecated_names, const std::string &parameter_name)
template<int spacedim>
Tensor< 1, spacedim > value_string_to_tensor (const std::string &value_string)
template<int dim>
double compute_cell_diameter (const double cell_measure, const unsigned int fe_degree)
double compute_cell_measure_with_JxW (const std::vector< double > &JxW_values)
template<int dim>
double identify_minimum_cell_size (const Mapping< dim > &mapping, const DoFHandler< dim > &dof_handler, const Quadrature< dim > &cell_quadrature, const MPI_Comm &mpi_communicator)
double get_penalty_factor (const unsigned int fe_degree, const double cell_extent_here, const double cell_extent_there)
template<typename key, typename val>
std::vector< key > extract_keys_from_map (const std::map< key, val > &map)
template<typename key, typename val>
std::vector< val > extract_values_from_map (const std::map< key, val > &map)
std::string concatenate_strings (const int argc, char **argv)
void print_version_info (const ConditionalOStream &pcout)
std::tuple< std::map< std::string, bool >, std::vector< std::string > > parse_args (int argc, char **argv)
void print_parameters_to_output_file (const ConditionalOStream &pcout, const ParameterHandler &prm, const std::string &file_name)
void interpret_escape_sequences (std::string &s)
void print_comment_to_output_file (const ConditionalOStream &pcout, ParameterHandler &prm)
void delete_vtu_and_pvd_files (const std::string &output_path)
template<int dim>
double point_to_angle (const Point< dim > &point, const Point< dim > &center_of_rotation=Point< dim >(), const unsigned int rotation_axis_direction=2)
template<int dim>
Point< dim > radius_to_point (const double radius, const double angle_rad, const Point< dim > &center_of_rotation=Point< dim >(), const unsigned int rotation_axis_direction=2)
void create_random_number_container (std::vector< double > &random_container, const unsigned int number_of_elements, const double maximum_range, const unsigned int prn_seed)
template<typename T>
std::vector< T > convert_string_to_vector (const ParameterHandler &prm, const std::string &entry_string)
template<int dim, typename VectorType>
void evaluate_values_at_points (const Mapping< dim > &mapping, const DoFHandler< dim > &dof_handler, const VectorType &solution_field, const std::vector< Point< dim > > &evaluation_points, Utilities::MPI::RemotePointEvaluation< dim > &remote_point_evaluator, std::vector< double > &evaluated_scalar_values, const unsigned int first_selected_component=0)
template<int n_component, int dim, typename VectorType>
void evaluate_values_at_points (const Mapping< dim > &mapping, const DoFHandler< dim > &dof_handler, const VectorType &solution_field, const std::vector< Point< dim > > &evaluation_points, Utilities::MPI::RemotePointEvaluation< dim > &remote_point_evaluator, std::vector< Tensor< 1, dim, double > > &evaluated_vector_values, const unsigned int first_selected_component=0)
template<int dim>
bool points_are_in_domain (const std::vector< Point< dim > > &evaluation_points, const Utilities::MPI::RemotePointEvaluation< dim, dim > &remote_point_evaluator)

Typedef Documentation

◆ DeprecatedEnumNames

template<typename EnumType>
using DeprecatedEnumNames = std::vector<std::pair<std::string, EnumType>>

Deprecated strings of an enum parameter, each paired with the enumerator it stands for. These are the values that were accepted before the parameter strings were made identical to the enumerator identifiers (e.g. "extra verbose" for Verbosity::extra_verbose). They remain accepted, but using one of them raises a deprecation warning.

Template Parameters
EnumTypeEnumeration type.

Definition at line 765 of file utilities.h.

Function Documentation

◆ add_statistics_to_table_handler()

void add_statistics_to_table_handler ( const std::string & variable,
const statistics & stats,
TableHandler & table )
inline

Add statistical values to a TableHandler.

This function inserts a variable name and its associated statistics (minimum, maximum, total, average) into a given TableHandler.

Parameters
[in]variableThe name of the variable being recorded.
[in]statsThe statistics associated with the variable.
[in,out]tableReference to the TableHandler where the values will be added.

Definition at line 97 of file utilities.h.

References statistics::average, statistics::max, statistics::min, and statistics::total.

◆ announce_string() [1/2]

void announce_string ( const ConditionalOStream & pcout,
const std::string & expression,
const char delimiter = '-' )
inline

Prints a string and then adds a line above and below made with dashes containing as many dashes as the string has characters+1.

For example, if the string to be printed is "Tracer" the result will be:

-------
-------
Parameters
[in]pcoutthe parallel cout used to print the information
[in]expressionstring that will be printed
[in]delimiterthe character used to delimit the printing. Default value is "-"

Definition at line 500 of file utilities.h.

◆ announce_string() [2/2]

void announce_string ( const ConditionalOStream & pcout,
const std::string & expression,
const unsigned int banner_size,
const char delimiter = '-' )
inline

Prints an expression string surrounded from above and bottom with a lines of a specified delimiter character (by default, '-'). The length of the banner lines is the length of the string + 1 character.

Parameters
[in]pcoutParallel conditional output stream used to print the information
[in]expressionExpression string that will be printed
[in]banner_sizeLength of the decorative banner lines
[in]delimiterCharacters composing the decorative lines of the banner. By default, '-' is used.
Remarks
The overload of the function with banner_size is used for cases where the expression string is multiple lines long.

Definition at line 525 of file utilities.h.

◆ calculate_point_property()

double calculate_point_property ( const double phase,
const double property0,
const double property1 )
inline

Calculate the equivalent properties for a given phase. Method called in quadrature points loops in CLS simulations.

Parameters
phasePhase value for the given quadrature point
property0Property value for the fluid with index 0 (fluid for phase = 0)
property1Property value for the fluid with index 1 (fluid for phase = 1)

Definition at line 307 of file utilities.h.

References phase.

◆ calculate_point_property_cahn_hilliard()

double calculate_point_property_cahn_hilliard ( const double phase_cahn_hilliard,
const double property0,
const double property1 )
inlinenodiscard

Calculate the equivalent property for a given phase.

This method is called in quadrature point loops in Cahn-Hilliard simulations. It interpolates between two fluid properties based on the phase value.

Parameters
[in]phase_cahn_hilliardPhase value for the given quadrature point.
[in]property0Property value for the fluid with index 0 (fluid for phase = -1).
[in]property1Property value for the fluid with index 1 (fluid for phase = 1).
Returns
double Equivalent property for the given phase.

Definition at line 380 of file utilities.h.

References phase, phase_cahn_hilliard, and sgn().

◆ check_file_exists()

void check_file_exists ( const std::string & file_name,
const std::string & file_description )

Verify that a file that Lethe must read exists and can be opened, and raise an error stated in the user's terms otherwise.

This function is meant to be called right before a file whose path comes from the user, either from the command line or from the parameter file, is opened. It distinguishes a file name that was left empty, a file that does not exist and a file that exists but cannot be read, so that the user is told what to correct instead of facing the error that the reader of the file would raise further down.

Parameters
[in]file_namePath of the file, exactly as it was given by the user.
[in]file_descriptionRole of the file in the simulation. It is used to build the error message and should read naturally after "The", for example "parameter file given to the application" or "gmsh mesh file given by 'subsection mesh' - 'set file name'".

Definition at line 225 of file utilities.cc.

◆ clip()

template<typename T>
T clip ( const T & n,
const T & lower,
const T & upper )

Clip a property between a lower and a higher value.

Template Parameters
Targument's type
Parameters
[in,out]lowerLower admissible value
[in,out]upperUpper admissible value
[in,out]n
Returns
Clipped variable that is not below the lower limit and not above the upper limit

Definition at line 361 of file utilities.h.

◆ compute_cell_diameter()

template<int dim>
double compute_cell_diameter ( const double cell_measure,
const unsigned int fe_degree )
inline

Computes equivalent cell diameter by comparing the area to a disk (2D) or the volume to a sphere (3D).

Template Parameters
dimNumber of spatial dimensions (2D or 3D).
Parameters
[in]cell_measureArea (2D) or volume (3D) of the cell.
[in]fe_degreePolynomial degree of the shape function.
Returns
Cell diameter value.

Definition at line 989 of file utilities.h.

◆ compute_cell_measure_with_JxW()

double compute_cell_measure_with_JxW ( const std::vector< double > & JxW_values)
inline

Computes the area (2D) or volume (3D) of the cell by integrating 1 over the cell, by summing JxW values (quadrature weights) returned by the FEValues object.

Template Parameters
dimNumber of spatial dimensions (2D or 3D).
Parameters
[in]JxW_valuesVector of mapped quadrature weights.
Returns
Area (2D) volume (3D) of the cell.

Definition at line 1017 of file utilities.h.

◆ concatenate_strings()

std::string concatenate_strings ( const int argc,
char ** argv )

Concatenate words which are passed from the command line to a main function into a single string in which the words are seperated by space.

Parameters
[in]argcnumber of arguments in C style.
[in]argvarguments themselves in C style.

Concatenate words which are passed from the command line to a main function into a single string in which the words are seperated by space.

Parameters
[in]argcnumber of arguments in C style.
[in]argvarguments themselves in C style.

Definition at line 758 of file utilities.cc.

◆ convert_string_to_vector()

template<typename T>
std::vector< T > convert_string_to_vector ( const ParameterHandler & prm,
const std::string & entry_string )

Return the vector of size N of entry @entry_string. If the entry is specified in the .prm file, then the changed value is returned, otherwise the default value is returned. If the entry is not equivalent to a vector, an error will be thrown.

Template Parameters
TThe type of vector (int, unsigned int or double)
Parameters
[in]prmA parameter handler which is currently used to parse the simulation information.
[in]entry_stringA declare string in the parameter file.
Returns
A std::vector<double> corresponding to the entry_string in the prm file.

Definition at line 1330 of file utilities.h.

◆ create_output_folder()

void create_output_folder ( const std::string & dirname)

Creates the simulation output folder.

Parameters
[in]dirnameOutput directory name

Definition at line 401 of file utilities.cc.

◆ create_random_number_container()

void create_random_number_container ( std::vector< double > & random_container,
const unsigned int number_of_elements,
const double maximum_range,
const unsigned int prn_seed )
inline

Creates a vector of random doubles between 0 and a maximum value using a pseudo random seed.

Parameters
[in,out]random_containerContainer in which the doubles are stored.
[in]number_of_elementsNumber of random doubles to generate.
[in]maximum_rangeMaximum value that the random double can have.
[in]prn_seedPseudo random seed used to generate the random doubles.

Definition at line 1302 of file utilities.h.

◆ declare_enum_entry()

template<typename EnumType>
requires std::is_enum_v<EnumType>
void declare_enum_entry ( ParameterHandler & prm,
const std::string & entry_name,
const EnumType default_value,
const std::string & description,
const DeprecatedEnumNames< EnumType > & deprecated_names = {},
const std::vector< EnumType > & allowed_values = {} )
inline

Declare a parameter entry whose value is an enumerator. The default value, the accepted values and the choices listed in the description are all derived from the enumeration, so that they cannot differ from one another.

The entry is declared with enum_to_string() of default_value as default value, a Patterns::Selection built with enum_to_selection() as pattern and description followed by enum_to_choices() as documentation.

Template Parameters
EnumTypeEnumeration type.
Parameters
[in,out]prmParameter handler in which the entry is declared.
[in]entry_nameName of the parameter in the parameter file.
[in]default_valueDefault enumerator of the parameter.
[in]descriptionDescription of the parameter, without the list of its choices, which is appended to it. It should end with a period.
[in]deprecated_namesDeprecated strings which remain accepted.
[in]allowed_valuesEnumerators accepted by the parameter. If empty, all the enumerators of EnumType are accepted (see enum_to_selection()).

Definition at line 888 of file utilities.h.

◆ delete_output_folder()

void delete_output_folder ( const std::string & dirname)

Delete the output folder and its content.

Parameters
[in]dirnameOutput directory name.

Definition at line 407 of file utilities.cc.

◆ delete_vtu_and_pvd_files()

void delete_vtu_and_pvd_files ( const std::string & output_path)

Delete vtu and pvd files.

Definition at line 917 of file utilities.cc.

◆ deserialize_table()

void deserialize_table ( TableHandler & table,
const std::string & filename,
const MPI_Comm & mpi_communicator,
const bool deserialize_on_rank_zero = true )
inline

Loads a TableHandler from a file using Boost serialization.

The filename should include the desired extension.

Parameters
[in,out]tableThe table to be deserialized (will be overwritten).
[in]filenamePath to the file (including extension) to read the table from.
[in]mpi_communicatorThe MPI communicator
[in]deserialize_on_rank_zeroBoolean indicating if the table should only be deserialized on rank 0 only. By default, it is set to true.

Definition at line 576 of file utilities.h.

◆ deserialize_tables_vector()

void deserialize_tables_vector ( std::vector< OutputStructTableHandler > & table_output_structs,
const MPI_Comm mpi_communicator )
inline

Deserializes all the TableHandler objects in table_output_structs.

Parameters
[in,out]table_output_structsVector of structures containing references to TableHandler objects that needs to be serialized/deserialized for a given solver, and their corresponding file names.
[in]mpi_communicatorThe MPI communicator

Definition at line 624 of file utilities.h.

References deserialize_table().

◆ enum_to_choices()

template<typename EnumType>
requires std::is_enum_v<EnumType>
std::string enum_to_choices ( const std::vector< EnumType > & allowed_values = {})
inline

Return the sentence listing the choices of an enum parameter (e.g. "Choices are <quiet|verbose|extra_verbose>."), to be used in the description of the parameter entry. The choices are the enumerator identifiers, in the order of the enumeration. The deprecated strings which are still accepted are deliberately not listed.

Template Parameters
EnumTypeEnumeration type.
Parameters
[in]allowed_valuesEnumerators accepted by the parameter. If empty, all the enumerators of EnumType are accepted (see enum_to_selection()).
Returns
The sentence listing the choices, separated by "|".

Definition at line 854 of file utilities.h.

◆ enum_to_selection()

template<typename EnumType>
requires std::is_enum_v<EnumType>
std::string enum_to_selection ( const DeprecatedEnumNames< EnumType > & deprecated_names = {},
const std::vector< EnumType > & allowed_values = {} )
inline

Return the selection string (e.g. "quiet|verbose|extra_verbose") of an enum parameter, to be given to Patterns::Selection. The choices returned in the selection string are the enumerator identifiers (meaning, the names in the enum converted into strings) followed by the deprecated strings which are still accepted.

Template Parameters
EnumTypeEnumeration type.
Parameters
[in]deprecated_namesDeprecated strings which remain accepted.
[in]allowed_valuesEnumerators (e.g. the enum values, for example quiet, verbose and extra_verbose) accepted by the parameter. If empty, all the enumerators (meaning all possible values) of EnumType are accepted. This is necessary because some enums contain internal enumerators which are not user choices (for example, the periodic_neighbor value of the boundary condition types, which the parser assigns to the boundary matching a periodic boundary).
Returns
The choices separated by "|".

Definition at line 807 of file utilities.h.

◆ enum_to_string()

template<typename EnumType>
requires std::is_enum_v<EnumType>
std::string enum_to_string ( const EnumType value)
inline

Return the name of an enumerator, e.g. to derive the default value string of a parameter entry from the in-class default of its enum member.

This is only valid for parameters whose accepted strings are exactly the enumerator identifiers (e.g. "bdf1" for TimeSteppingMethod::bdf1).

Note
Patterns::Tools::Convert<EnumType> is not used, because it treats enums as bit-flag sets: for a non-zero value, it also returns the name of the zero-valued enumerator (e.g. "pspg_supg| gls" for gls).
Template Parameters
EnumTypeEnumeration type.
Parameters
[in]valueEnumerator whose name is returned.
Returns
The identifier of value.

Definition at line 705 of file utilities.h.

◆ evaluate_values_at_points() [1/2]

template<int dim, typename VectorType>
void evaluate_values_at_points ( const Mapping< dim > & mapping,
const DoFHandler< dim > & dof_handler,
const VectorType & solution_field,
const std::vector< Point< dim > > & evaluation_points,
Utilities::MPI::RemotePointEvaluation< dim > & remote_point_evaluator,
std::vector< double > & evaluated_scalar_values,
const unsigned int first_selected_component = 0 )

Evaluates the values of a scalar field at remote points of the domain from the mapping, the DoF handler and the solution field.

Template Parameters
dimDenotes the number of spatial dimensions.
VectorTypeVector type of the solution vector.
Parameters
[in]mappingMapping of the domain.
[in]dof_handlerDoF handler associated to the solution field.
[in]solution_fieldVector containing the solution field. For distributed meshes, ghost elements must be updated.
[in]evaluation_pointsVector of points where the values of the solution field are to be evaluated.
[in,out]remote_point_evaluatorUtilities::MPI::RemotePointEvaluation object used to evaluate values of the variable of interest at given points of the domain.
[in,out]evaluated_scalar_valuesVector of evaluated scalar values.
[in]first_selected_componentFirst component of the solution to select if the solution field is a vector field. This is used to extract the correct field when the solution vector contains multiple fields (e.g., velocity and pressure are stored in a same solution vector).
Remarks
If a given evaluation point is not within the simulated domain, an exception is thrown.

Definition at line 930 of file utilities.cc.

References points_are_in_domain().

◆ evaluate_values_at_points() [2/2]

template<int n_component, int dim, typename VectorType>
void evaluate_values_at_points ( const Mapping< dim > & mapping,
const DoFHandler< dim > & dof_handler,
const VectorType & solution_field,
const std::vector< Point< dim > > & evaluation_points,
Utilities::MPI::RemotePointEvaluation< dim > & remote_point_evaluator,
std::vector< Tensor< 1, dim, double > > & evaluated_vector_values,
const unsigned int first_selected_component = 0 )

Evaluates the values of a vector field at remote points of the domain from the mapping, the DoF handler and the solution field.

Template Parameters
n_componentNumber of components of the evaluated vector solution.
dimDenotes the number of spatial dimensions.
VectorTypeVector type of the solution vector.
Parameters
[in]mappingMapping of the domain.
[in]dof_handlerDoF handler associated to the solution field.
[in]solution_fieldVector containing the vector solution field.
[in]evaluation_pointsVector of points where the values of the solution field are to be evaluated.
[in,out]remote_point_evaluatorUtilities::MPI::RemotePointEvaluation object used to evaluate values of the variable of interest at given points of the domain.
[in,out]evaluated_vector_valuesVector of evaluated vector values.
[in]first_selected_componentFirst component of the solution to select. This is used to extract the correct fields when the solution vector contains multiple fields (e.g., velocity and pressure are stored in a same solution vector).
Remarks
If a given evaluation point is not within the simulated domain, an exception is thrown.

Definition at line 1027 of file utilities.cc.

References points_are_in_domain().

◆ extract_keys_from_map()

template<typename key, typename val>
std::vector< key > extract_keys_from_map ( const std::map< key, val > & map)

Extract the keys from map object.

Template Parameters
keyKey of the map
valValue of the map. This template parameter is not used.
Parameters
[in]mapMap object from which the keys are extracted
Returns
keys Vector of keys from the map

Definition at line 1118 of file utilities.h.

◆ extract_values_from_map()

template<typename key, typename val>
std::vector< val > extract_values_from_map ( const std::map< key, val > & map)

Extract the values from map object.

Template Parameters
keyKey of the map. This template parameter is not used.
valValue of the map.
Parameters
[in]mapMap object from which the keys are extracted
Returns
values Vector of values from the map

Definition at line 1138 of file utilities.h.

◆ fill_string_vectors_from_file()

void fill_string_vectors_from_file ( std::map< std::string, std::vector< std::string > > & map,
const std::string & file_name,
const std::string & delimiter = " " )

Function that read a file that was build from a dealii table and create a map with the key being the column name and the variable the vectors of data.

Parameters
[in,out]mapA map used to store the data based on column names.
[in]file_namePath to the file to read the table from.
[in]delimiterDelimiter used in the file to separate values. Default is a space (" ").

Definition at line 352 of file utilities.cc.

References check_file_exists().

◆ fill_table_from_file()

void fill_table_from_file ( TableHandler & table,
const std::string & file_name,
const std::string & delimiter = " " )

Reads a file generated by a deal.II TableHandler and fills a TableHandler with its data.

This function reads a table from a file and populates the given TableHandler. Warning: If the table already contains data, it will be erased.

Parameters
[in,out]tableThe table to be filled. Existing content will be overwritten.
[in]file_namePath to the file to read the table from.
[in]delimiterDelimiter used in the file to separate values. Default is a space (" ").

Definition at line 253 of file utilities.cc.

References check_file_exists().

◆ fill_vectors_from_file()

void fill_vectors_from_file ( std::map< std::string, std::vector< double > > & map,
const std::string & file_name,
const std::string & delimiter = " " )

function that read a file that was build from a dealii table and fill 2 vectors. The first vector contains all the columns names and the second one contained all the column data.

Parameters
[in,out]mapA map used to store the data based on column names.
[in]file_namePath to the file to read the table from.
[in]delimiterDelimiter used in the file to separate values. Default is a space (" ").

Definition at line 299 of file utilities.cc.

References check_file_exists().

◆ get_dimension()

unsigned int get_dimension ( const std::string & file_name)

Extract the dimension in which to run Lethe from the contents of the parameter file. This is something that we need to do before processing the parameter file since we need to know whether to use the dim=2 or dim=3 instantiation of the main classes.

Parameters
file_name[in]The file name from which dimension is read

Definition at line 670 of file utilities.cc.

References get_last_value_of_parameter().

◆ get_last_value_of_parameter()

std::string get_last_value_of_parameter ( const std::string & file_name,
const std::string & parameter_name )

Retrieves the value of a specific parameter from an input file. Returns an empty string if the parameter is not found. This function is adapted from ASPECT and is mainly used to parse the dimension of the problem before creating the full parameter parser.

Parameters
[in]file_nameFile from which we retrieve the parameter.
[in]parameter_nameName of the parameter to retrieve.
Returns
std::string Value of the parameter, or an empty string if not found.

Definition at line 585 of file utilities.cc.

References check_file_exists().

◆ get_max_subsection_size()

int get_max_subsection_size ( const std::string & file_name,
const bool require_subsection_size = true )

Extract the maximum value between the number of boundary conditions and the number of manifolds from the file. This value is linked to the "number" string defined in the simulation parameter file. It provides an estimate for the amount of parameters or manifolds and is used to determine the size of the vectors that will store boundary conditions and manifold data. This feature will need to be monitored extensively in the future.

Parameters
[in]file_nameThe file name from which the number of boundary conditions is read
[in]require_subsection_sizeIf true, the file must contain at least one "number" entry and an exception is raised otherwise. Solvers for which no variable size subsection is mandatory, such as the DEM solvers whose boundary conditions are declared with a "number of boundary conditions" entry, set this to false. A file without any "number" entry then yields a size of zero.
Returns
The maximum number of boundary conditions or manifolds.

Definition at line 736 of file utilities.cc.

References get_max_value_of_parameter().

◆ get_penalty_factor()

double get_penalty_factor ( const unsigned int fe_degree,
const double cell_extent_here,
const double cell_extent_there )
inline

Calculate the penalty factor for the SIPG method for the case when two cells are of different sizes. A harmonic mean is used to calculate an average cell extent.

Parameters
[in]fe_degreeFinite element degree.
[in]cell_extent_hereDistance of the here cell. The ratio between the volume of the cell and the area of the face is generally used as a metric for this distance.
[in]cell_extent_thereDistance of the there cell. The ratio between the volume of the cell and the area of the face is generally used as a metric for this distance.
Returns
double

Definition at line 1099 of file utilities.h.

◆ identify_minimum_cell_size()

template<int dim>
double identify_minimum_cell_size ( const Mapping< dim > & mapping,
const DoFHandler< dim > & dof_handler,
const Quadrature< dim > & cell_quadrature,
const MPI_Comm & mpi_communicator )
inline

Identify minimum cell size. The cell size corresponds to the diameter of a disk (2D) or sphere (3D) of equivalent area (2D) or volume (3D).

Template Parameters
dimNumber of spatial dimensions (2D or 3D).
Parameters
[in]mappingInterface for transformation from the reference (unit) cell to the real cell.
[in]dof_handlerDescribes the layout of DoFs and the type of FE.
[in]cell_quadratureLocal cell quadrature information.
[in]mpi_communicatorAllows communication between cores.
Returns
Smallest cell size value.

Definition at line 1044 of file utilities.h.

References compute_cell_diameter(), and compute_cell_measure_with_JxW().

◆ interpret_escape_sequences()

void interpret_escape_sequences ( std::string & s)

Identify escape sequences listed below and apply them to the string.

  • "\n": Newline
  • "\t": Horizontal tab
  • "\r": Carriage return
  • "\b": Backspace
  • "\v": Vertical tab
Parameters
[in,out]sString to be modified if escape sequences are specified.

Definition at line 892 of file utilities.cc.

◆ make_table_scalars_tensors() [1/2]

template<int dim, typename T>
TableHandler make_table_scalars_tensors ( const std::vector< T > & independent_values,
const std::string & independent_column_name,
const std::vector< std::vector< Tensor< 1, dim > > > & dependent_vector,
const std::vector< std::string > & dependent_column_names,
const unsigned int display_precision,
const bool display_scientific_notation = false )

Generate a table from a vector of scalar (independent variable) and a vector of vectors of Tensor<1,dim> (dependent variables).

Template Parameters
TScalar type of independent variables.
dimInteger that denotes the number of spatial dimensions.
Parameters
[in]independent_valuesVector of scalar values that serve as the independent variable (e.g., time).
[in]independent_column_nameLabel of the independent variable.
[in]dependent_vectorVector of vectors of Tensor<1,dim> containing dependent variables values (e.g., force).
[in]dependent_column_namesVector of strings representing the labels of dependent variables.
[in]display_precisionInteger indicating the precision at which the table is written.
[in]display_scientific_notationBoolean indicating if the values should be displayed in scientific notation (true) or not (false).
Returns
Table with the independent variable values followed by the dependent variables values.

Definition at line 98 of file utilities.cc.

◆ make_table_scalars_tensors() [2/2]

template<int dim, typename T>
TableHandler make_table_scalars_tensors ( const std::vector< T > & independent_values,
const std::string & independent_column_name,
const std::vector< Tensor< 1, dim > > & dependent_vector,
const std::vector< std::string > & dependent_column_names,
const unsigned int display_precision,
const bool display_scientific_notation = false )

Generate a table from a vector of scalars (independent variable) and a vector of Tensor<1,dim> (dependent variables).

Template Parameters
TScalar type of independent variables.
dimInteger that denotes the number of spatial dimensions.
Parameters
[in]independent_valuesVector of scalar values that serve as the independent variable (e.g., time).
[in]independent_column_nameLabel of the independent variable.
[in]dependent_vectorVector of Tensor<1,dim> containing dependent variables values (e.g., force).
[in]dependent_column_namesVector of strings representing the labels of dependent variables.
[in]display_precisionInteger indicating the precision at which the table is written.
[in]display_scientific_notationBoolean indicating if the values should be displayed in scientific notation (true) or not (false).
Returns
Table with the independent variable values followed by the dependent variables values.

Definition at line 59 of file utilities.cc.

◆ make_table_scalars_vectors()

template<typename T>
TableHandler make_table_scalars_vectors ( const std::vector< T > & independent_values,
const std::string & independent_column_name,
const std::vector< std::vector< double > > & dependent_vector,
const std::vector< std::string > & dependent_column_names,
const unsigned int display_precision,
const bool display_scientific_notation = false )

Generate a table from a vector of scalars (independent variable) and a vector of vectors of scalars (dependent variables).

Template Parameters
TScalar type of independent variables.
Parameters
[in]independent_valuesVector of scalar values that serve as the independent variable (e.g., time).
[in]independent_column_nameLabel of the independent variable.
[in]dependent_vectorVector of vectors of scalar values containing dependant variables values.
[in]dependent_column_namesVector of strings representing the labels of dependent variables.
[in]display_precisionInteger indicating the precision at which the table is written.
[in]display_scientific_notationBoolean indicating if the values should be displayed in scientific notation (true) or not (false).
Returns
Table with the independent variable values followed by the dependent variables values.

Definition at line 24 of file utilities.cc.

◆ make_table_tensors_scalars()

template<int dim>
TableHandler make_table_tensors_scalars ( const std::vector< Tensor< 1, dim > > & independent_vector,
const std::vector< std::string > & independent_column_names,
const std::vector< double > & dependent_values,
const std::string & dependent_column_name,
const unsigned int display_precision,
const bool display_scientific_notation = false )

Generate a table from a vector of Tensor<1,dim> (independent variables) and a vector of scalars (dependent variable).

Template Parameters
dimInteger that denotes the number of spatial dimensions.
Parameters
[in]independent_vectorVector of Tensor<1,dim> that serves as the independent variable (e.g., position).
[in]independent_column_namesVector of strings representing labels of the independent tensor.
[in]dependent_valuesVector of doubles containing dependent variables values (e.g., force).
[in]dependent_column_nameLabel of the dependent variable.
[in]display_precisionInteger indicating the precision at which the table is written.
[in]display_scientific_notationBoolean indicating if the values should be displayed in scientific notation (true) or not (false).
Returns
Table with the independent variables values followed by the dependent variable values.

Definition at line 189 of file utilities.cc.

◆ make_table_tensors_tensors()

template<int dim>
TableHandler make_table_tensors_tensors ( const std::vector< Tensor< 1, dim > > & independent_vector,
const std::vector< std::string > & independent_column_names,
const std::vector< Tensor< 1, dim > > & dependent_vector,
const std::vector< std::string > & dependent_column_names,
const unsigned int display_precision,
const bool display_scientific_notation = false )

Generate a table from a vector of Tensor<1,dim> (independent variables) and a vector of Tensor<1,dim> (dependent variables).

Template Parameters
dimInteger that denotes the number of spatial dimensions.
Parameters
[in]independent_vectorVector of Tensor<1,dim> that serves as the independent variable (e.g., position).
[in]independent_column_namesVector of strings representing labels of the independent tensor.
[in]dependent_vectorVector of vectors of Tensor<1,dim> containing dependent variables values (e.g., force).
[in]dependent_column_namesVector of strings representing the labels of dependent variables.
[in]display_precisionInteger indicating the precision at which the table is written.
[in]display_scientific_notationBoolean indicating if the values should be displayed in scientific notation (true) or not (false).
Returns
Table with the independent variables values followed by the dependent variables values.

Definition at line 147 of file utilities.cc.

◆ parse_args()

std::tuple< std::map< std::string, bool >, std::vector< std::string > > parse_args ( int argc,
char ** argv )

Parse the arguments given to the application.

Parameters
[in]argcNumber of arguments
[in]argvArray of strings representing the arguments
Returns
Tuple containing a map with the command line flags and a boolean set to 1 for the specific flag; and a vector of strings with the rest of the arguments that are not flags; in Lethe, this corresponds to the parameter file given to the application.

Definition at line 800 of file utilities.cc.

◆ point_to_angle()

template<int dim>
double point_to_angle ( const Point< dim > & point,
const Point< dim > & center_of_rotation = Point<dim>(),
const unsigned int rotation_axis_direction = 2 )
inline

Converts point to angle (in radians) based on rotation axis.

Parameters
[in]pointPoint in cartesian coordinates
[in]center_of_rotationCenter of rotation
[in]rotation_axis_directionDirection of rotation axis (x=0, y=1, z=2)
Returns
Angle in the plane perpendicular to the rotation axis

Definition at line 1234 of file utilities.h.

◆ points_are_in_domain()

template<int dim>
bool points_are_in_domain ( const std::vector< Point< dim > > & evaluation_points,
const Utilities::MPI::RemotePointEvaluation< dim, dim > & remote_point_evaluator )
inline

Checks that the evaluation points are within the simulated domain and returns true if all points are within the domain.

Template Parameters
dimDenotes the number of spatial dimensions.
Parameters
[in]evaluation_pointsVector of points where the values of the solution field are to be evaluated.
[in]remote_point_evaluatorRemotePointEvaluation object used to evaluate values.
Returns
true if all points are within the simulated domain.

Definition at line 1527 of file utilities.h.

◆ print_comment_to_output_file()

void print_comment_to_output_file ( const ConditionalOStream & pcout,
ParameterHandler & prm )

Print a user comment at the beginning of the simulation on the console output.

Parameters
[in]pcoutParallel console output stream.
[in,out]prmParameterHandler. specified.

Definition at line 902 of file utilities.cc.

References interpret_escape_sequences().

◆ print_parameters_to_output_file()

void print_parameters_to_output_file ( const ConditionalOStream & pcout,
const ParameterHandler & prm,
const std::string & file_name )

Print the parameters given by the parameter file of the application.

Parameters
[in]pcoutParallel output stream
[in]prmObject containing the parameters parsed from the parameter file.
[in]file_nameFile name where the parameters will be written.
[in]pcoutParallel output stream
[in]prmObject containing the parameters parsed from the parameter file

Definition at line 865 of file utilities.cc.

References get_last_value_of_parameter().

◆ print_version_info()

void print_version_info ( const ConditionalOStream & pcout)

Print the information of the deal.II and Lethe branches used to run an application in the "git describe" format.

Parameters
[in]pcoutParallel output stream

Definition at line 775 of file utilities.cc.

◆ radius_to_point()

template<int dim>
Point< dim > radius_to_point ( const double radius,
const double angle_rad,
const Point< dim > & center_of_rotation = Point<dim>(),
const unsigned int rotation_axis_direction = 2 )
inline

Converts radius to point in cartesian coordinates based on rotation axis.

Parameters
[in]radiusRadial distance
[in]angle_radAngle (in radians)
[in]center_of_rotationCenter of rotation
[in]rotation_axis_directionDirection of rotation axis (x=0, y=1, z=2)
Returns
point Point in cartesian coordinates

Definition at line 1266 of file utilities.h.

◆ serialize_table()

void serialize_table ( const TableHandler & table,
const std::string & filename,
const MPI_Comm & mpi_communicator,
const bool serialize_on_rank_zero = true )
inline

Serializes a TableHandler to a file using Boost serialization.

The filename should include the desired extension.

Parameters
[in]tableThe table to be serialized.
[in]filenamePath to the file (including extension) where the table will be saved.
[in]mpi_communicatorThe MPI communicator
[in]serialize_on_rank_zeroBoolean indicating if the table should only be serialized on rank 0 only. By default, it is set to true.

Definition at line 547 of file utilities.h.

◆ serialize_tables_vector()

void serialize_tables_vector ( const std::vector< OutputStructTableHandler > & table_output_structs,
const MPI_Comm mpi_communicator )
inline

Serializes all the TableHandler objects in table_output_structs.

Parameters
[in]table_output_structsVector of structures containing references to TableHandler objects that need to be serialized/deserialized for a given solver, and their corresponding file names.
[in]mpi_communicatorThe MPI communicator

Definition at line 602 of file utilities.h.

References serialize_table().

◆ sgn()

template<typename T>
int sgn ( const T val)
nodiscardconstexprnoexcept

Retrieve the sign of a value.

Used in calculate_point_property_cahn_hilliard to determine the sign of the phase parameter.

Template Parameters
TThe argument's type (must support comparison with zero).
Parameters
[in]valValue of the variable for which the sign is evaluated.
Return values
-1if the value is negative.
+1if the value is positive.
0if the value is zero.

Definition at line 344 of file utilities.h.

◆ string_to_enum() [1/2]

template<typename EnumType>
requires std::is_enum_v<EnumType>
EnumType string_to_enum ( const std::string & name)
inline

Return the enumerator whose identifier is name, e.g. to parse the value of a parameter entry into its enum member. This is the inverse of enum_to_string().

This is only valid for parameters whose accepted strings are exactly the enumerator identifiers (e.g. "bdf1" for TimeSteppingMethod::bdf1). The comparison is case-sensitive.

Note
Patterns::Tools::Convert<EnumType> is not used, because it treats enums as bit-flag sets (see enum_to_string()).
Template Parameters
EnumTypeEnumeration type.
Parameters
[in]nameIdentifier of the enumerator.
Returns
The enumerator of EnumType named name. An exception is thrown if EnumType has no enumerator named name.

Definition at line 734 of file utilities.h.

◆ string_to_enum() [2/2]

template<typename EnumType>
requires std::is_enum_v<EnumType>
EnumType string_to_enum ( const std::string & name,
const DeprecatedEnumNames< EnumType > & deprecated_names,
const std::string & parameter_name )
inline

Return the enumerator designated by name, which is either the identifier of the enumerator or one of the deprecated strings of the parameter. In the latter case, a deprecation warning is printed.

Template Parameters
EnumTypeEnumeration type.
Parameters
[in]parameter_valueValue of the parameter.
[in]deprecated_namesDeprecated strings which remain accepted.
[in]parameter_nameName of the parameter in the parameter file, used in the deprecation warning.
Returns
The enumerator of EnumType designated by name. An exception is thrown if name is neither an enumerator nor a deprecated string.

Definition at line 923 of file utilities.h.

References enum_to_string(), string_to_enum(), and warn_deprecated_parameter_value().

◆ value_string_to_tensor()

template<int spacedim>
Tensor< 1, spacedim > value_string_to_tensor ( const std::string & value_string)
inline

Return the tensor corresponding to the value_string. If the dimension correspondence of the value_string is not equivalent to spacedim (either 2 or 3), an exception will be thrown. The delimiter separating the elements of the value_string is a comma (",").

Remarks
The function is used to construct Point<spacedim> objects.
Template Parameters
spacedimNumber of spatial dimensions (2D or 3D).
Parameters
[in]value_stringA string in the parameter file corresponding to a given tensor.
Returns
A Tensor<1,spacedim> corresponding to the value_string in the parameter file.

Definition at line 956 of file utilities.h.

◆ warn_deprecated_parameter_value()

void warn_deprecated_parameter_value ( const std::string & parameter_name,
const std::string & deprecated_value,
const std::string & new_value )

Print a warning stating that a deprecated value was given to a parameter, along with the value which replaces it. The warning is only printed by the first MPI process.

Parameters
[in]parameter_nameName of the parameter in the parameter file.
[in]deprecated_valueDeprecated value which was given.
[in]new_valueValue which replaces deprecated_value.

Definition at line 839 of file utilities.cc.