A collection of utilities used within ViennaSHE. More...

Namespaces
namespace	detail
	Namespace containing implementation details for functionality from viennashe::util. Typically not of interest for a library user.

Classes
struct	all_ok_checker
	A checker that never complains. Can be used instead of overly picky/erroneous checkers (just for debugging purposes, of course!) More...

struct	any_filter
	A trivial filter, all objects are accepted. More...

struct	arithmetic_averaging
	A functor which computes the arithmetic average of all entries in a container. More...

class	checker_with_exception
	A checker class that throws a user-provided exception rather than returning false on its functor interface. More...

class	contact_filter
	A simple filter to find cells and vertices which have potential boundary conditions. More...

struct	cpp03_static_assert

struct	cpp03_static_assert< true >

struct	device_from_array_generator
	A device generator to generate a device from C-Arrays (DOES NOT TAKE OWNERSHIP) More...

struct	device_from_flat_array_generator
	A device generator to generate a device from flat C-Arrays (DOES NOT TAKE OWNERSHIP) More...

class	device_generation_config
	Configuration class for the simple mesh generator. More...

class	filtered_functor
	A compound functor which applies the provided functor only to the argument if the supplied filter evaluates to true. More...

struct	geometric_averaging
	A functor which computes the geometric average of all entries in a container. More...

struct	inf_checker
	Checks for Inf. More...

class	invalid_range_bounds_exception
	Exception thrown if for a range(a,b) the check a < b fails. More...

class	invalid_value_exception
	Exception which is thrown if an invalid value is found. More...

struct	is_equal

struct	is_equal< T, T >

class	linear_solver_exception
	Exception for the case that a linear solver fails (typically with NaN due to zero inner product) More...

struct	log_generate_device
	Logging key for messages from the built-in ortho-grid generator. More...

struct	log_m_matrix_check
	Logging key for messages occurring during M-matrix check. More...

struct	logic_or_averaging
	A functor which returns the result of a logic-or chain consisting of all elements of the supplied container. More...

class	metal_filter
	A filter accepting metal cells only. More...

struct	nan_checker
	Checks for NaN. More...

class	no_contact_and_semiconductor_filter
	A filter used to filter cells, which are neither semiconductors (by material) nor contacts (by potential boundary condition) More...

class	no_contact_filter
	The inverse filter to the contact_filter. More...

struct	none_filter
	A trivial filter, no objects shall be accepted. More...

class	oxide_filter
	A filter accepting oxide cells only. More...

class	range_checker
	Checker for values inside a half-open interval [a, b), where 'a' is included, while 'b' is not. More...

class	semiconductor_filter
	A filter accepting semiconductor cells only. More...

class	spatial_quantity
	A functor-style wrapper for a spatial quantity which is externally prescribed by the user. More...

class	spatial_quantity_wrapper
	A functor-style wrapper for a spatial quantity (typically potential, electron density or hole density). Typically evaluated on each vertex only. More...

class	string_conversion_exception
	Exception that is thrown if a string cannot be converted to the respective target type. More...

class	timer
	A simple timer class. More...

class	value_holder_functor
	A functor which holds a single value. Used in most of the postprocessing routines. More...

class	vicinity_filter
	A filter returning true if any of the neighboring ncells of dimension 'dim' evaluate to true. More...

Functions
template<typename SystemMatrixType , typename BlockMatrixType , typename RowIndexIterator , typename ColumnIndexIterator >
void	add_block_matrix (SystemMatrixType &system_matrix, std::size_t row_index, std::size_t col_index, double prefactor, BlockMatrixType const &coupling_matrix, RowIndexIterator row_iter, ColumnIndexIterator const &col_iter_init, bool elastic_scattering_roundoff_error_prevention=false)
	Writes a sub-matrix of a block matrix 'coupling_matrix' into the global system matrix, scaled by 'prefactor'. More...

template<typename SystemMatrixType , typename BlockMatrixType , typename RowIndexIterator , typename ColumnIndexIterator , typename FoldVectorType >
void	add_folded_block_matrix (SystemMatrixType &system_matrix, long row_index, long col_index, double prefactor, BlockMatrixType const &coupling_matrix, RowIndexIterator row_iter, ColumnIndexIterator const &col_iter_init, FoldVectorType const &fold_vector, long fold_index_start)
	Writes a sub-matrix of a block matrix 'coupling_matrix' into the global system matrix, scaled by 'prefactor'. The columns are 'folded' (summed, i.e. a matrix-vector product) according to the vector provided. More...

template<typename VectorType , typename BlockMatrixType , typename RowIndexIterator , typename ColumnIndexIterator >
void	subtract_folded_block_vector (VectorType &residual, std::size_t row_index, double prefactor, BlockMatrixType const &coupling_matrix, RowIndexIterator row_iter, ColumnIndexIterator const &col_iter_init, double const *fold_vector)
	Writes a sub-matrix of a block matrix 'coupling_matrix' to the residual vector. The columns are 'folded' (summed, i.e. a matrix-vector product) according to the vector provided. More...

template<typename ValueType >
bool	is_NaN (const ValueType &val)
	Checks if a value of type ValueType is NaN using value != value. More...

template<typename ValueType >
bool	is_Inf (const ValueType &val)
	Checks if a value of type ValueType is Inf using (value - value) != 0. More...

template<typename ValueType >
bool	is_negative (const ValueType &val)
	Checks if a value of type ValueType is negative using value < 0. More...

template<typename VectorType >
void	check_vector_for_valid_entries (VectorType const &vec, std::string message="Location not specified")
	Checks a vector for valid entries (i.e. no NaN). More...

template<typename CheckerType , typename ExceptionType >
checker_with_exception< CheckerType, ExceptionType >	make_checker_with_exception (CheckerType const &checker, ExceptionType const &ex)
	Convenience creator routine for creating a checker with exception from checker returning a bool only. More...

template<typename MatrixType >
void	m_matrix_check (MatrixType const &A)
	Checks a matrix for being an M matrix. More...

template<typename MatrixType >
long	matrix_consistency_check (MatrixType const &matrix)
	Checks a matrix for empty rows. More...

template<typename NumericT >
long	matrix_consistency_check (viennashe::math::sparse_matrix< NumericT > const &matrix)
	Checks a matrix for empty rows. More...

template<typename MatrixType >
void	check_vanishing_column_sums (MatrixType const &matrix, std::size_t num_cols)
	Checks that the first 'num_cols' column sums of the provided matrix vanish (up to round-off) or a column is not populated with any entries at all. More...

template<typename CellTagT , typename FacetTagT , typename WrappedConfigT >
viennagrid::result_of::point< viennagrid::element< CellTagT, WrappedConfigT > >::type	outer_cell_normal_at_facet (viennagrid::element< CellTagT, WrappedConfigT > const &cell, viennagrid::element< FacetTagT, WrappedConfigT > const &facet)
	Returns the unit outer normal of a facet with respect to the provided cell. More...

template<typename DeviceT , typename CellT , typename FacetContainerT , typename CellSetterT , typename FacetAccessorT >
void	dual_box_flux_to_cell (DeviceT const &device, CellT const &cell, FacetContainerT const &facets, CellSetterT &cell_setter, FacetAccessorT const &facet_access)
	Interpolates normal components of the flux defined on each facet to cells. Mostly used for visualization purposes. More...

template<typename DeviceType , typename CellSetter , typename FacetAccessor >
void	dual_box_flux_to_cell (DeviceType const &device, CellSetter &cell_setter, FacetAccessor const &facet_accessor)
	Interpolates normal components of the flux defined on each facet to all cells in the mesh (or segment). More...

template<typename DeviceT , typename IndexT >
void	dump_mesh (DeviceT const &device, double vertices, IndexT &num_vertices, IndexT cells, IndexT &num_cells)

template<typename MeshT , typename SegmentationT >
void	generate_device (MeshT &mesh, SegmentationT &seg, device_generation_config const &conf)
	Public interface for mesh generation of simple one- or two-dimensional meshes. Device must be rectangular for the two-dimensional case. More...

template<typename FilterType , typename FunctorType >
filtered_functor< FilterType, FunctorType >	make_filtered_functor (FilterType const &filter, FunctorType &fun)
	Convenience routine for creating a filtered functor out of the provided filter- and action-functor. Also see class filtered_functor. More...

template<typename MeshT , typename FacetT , typename CellT >
CellT const *	get_other_cell_of_facet (MeshT const &mesh, FacetT const &facet, CellT const &cell)
	Helper function returning a const-pointer to the 'second cell' of a facet, or NULL if there is no second facet. The 'first' cell is passed to the function. More...

template<typename DeviceT , typename CellT >
CellT const *	get_connected_semiconductor_cell (DeviceT const &device, CellT const &cell)
	Helper function returning a const-pointer to the 'second cell' of a facet, or NULL if there is no second facet. The 'first' cell is passed to the function. More...

template<typename T >
std::string	format_number_to_width (T number, int width)
	Returns the formatted number as string with the given length, where spaces are used as padding character. More...

template<typename VectorType >
VectorType::value_type	norm_inf (VectorType const &v, std::size_t index_start, std::size_t index_stop)
	Computes the infimum norm of a subvector. More...

Detailed Description

A collection of utilities used within ViennaSHE.

Function Documentation

◆ add_block_matrix()

template<typename SystemMatrixType , typename BlockMatrixType , typename RowIndexIterator , typename ColumnIndexIterator >

void viennashe::util::add_block_matrix	(	SystemMatrixType &	system_matrix,
		std::size_t	row_index,
		std::size_t	col_index,
		double	prefactor,
		BlockMatrixType const &	coupling_matrix,
		RowIndexIterator	row_iter,
		ColumnIndexIterator const &	col_iter_init,
		bool	elastic_scattering_roundoff_error_prevention = `false`
	)

Writes a sub-matrix of a block matrix 'coupling_matrix' into the global system matrix, scaled by 'prefactor'.

Parameters

system_matrix	System matrix, to which the entries are written
row_index	Starting row index in system matrix
col_index	Starting column index in system matrix
prefactor	The block matrix 'coupling_matrix' is multiplied by prefactor before the write operation is carried out
coupling_matrix	The block matrix
row_iter	Iterator over row indices of 'coupling matrix'
col_iter_init	Iterator over column indices of 'coupling matrix'
elastic_scattering_roundoff_error_prevention	Flag which specifies whether the first element in the coupling matrix should be forced to zero to avoid round-off errors

Definition at line 48 of file block_matrix_writer.hpp.

◆ add_folded_block_matrix()

template<typename SystemMatrixType , typename BlockMatrixType , typename RowIndexIterator , typename ColumnIndexIterator , typename FoldVectorType >

void viennashe::util::add_folded_block_matrix	(	SystemMatrixType &	system_matrix,
		long	row_index,
		long	col_index,
		double	prefactor,
		BlockMatrixType const &	coupling_matrix,
		RowIndexIterator	row_iter,
		ColumnIndexIterator const &	col_iter_init,
		FoldVectorType const &	fold_vector,
		long	fold_index_start
	)

Writes a sub-matrix of a block matrix 'coupling_matrix' into the global system matrix, scaled by 'prefactor'. The columns are 'folded' (summed, i.e. a matrix-vector product) according to the vector provided.

Parameters

system_matrix	System matrix, to which the entries are written
row_index	Starting row index in system matrix
col_index	Starting column index in system matrix
prefactor	The block matrix 'coupling_matrix' is multiplied by prefactor before the write operation is carried out
coupling_matrix	The block matrix
row_iter	Iterator over row indices of 'coupling matrix'
col_iter_init	Iterator over column indices of 'coupling matrix'
fold_vector	The vector with which the fold-operation (matrix-vector product on the columns selected by the column-iterator) is carried out.
fold_index_start	Start (offset) index within the fold_vector

Definition at line 101 of file block_matrix_writer.hpp.

◆ check_vanishing_column_sums()

template<typename MatrixType >

void viennashe::util::check_vanishing_column_sums	(	MatrixType const &	matrix,
		std::size_t	num_cols
	)

Checks that the first 'num_cols' column sums of the provided matrix vanish (up to round-off) or a column is not populated with any entries at all.

Definition at line 315 of file checks.hpp.

◆ check_vector_for_valid_entries()

template<typename VectorType >

void viennashe::util::check_vector_for_valid_entries	(	VectorType const &	vec,
		std::string	message = `"Location not specified"`
	)

Checks a vector for valid entries (i.e. no NaN).

Definition at line 111 of file checks.hpp.

◆ dual_box_flux_to_cell() [1/2]

template<typename DeviceT , typename CellT , typename FacetContainerT , typename CellSetterT , typename FacetAccessorT >

void viennashe::util::dual_box_flux_to_cell	(	DeviceT const &	device,
		CellT const &	cell,
		FacetContainerT const &	facets,
		CellSetterT &	cell_setter,
		FacetAccessorT const &	facet_access
	)

Interpolates normal components of the flux defined on each facet to cells. Mostly used for visualization purposes.

Parameters

device	The device object (needed because it holds the Voronoi data)
cell	The cell to be interpolated to
facets	The set of facets to be considered (facets need to be the facets of the given cell!)
cell_setter	Functor for storing the interpolated flux vector
facet_access	Functor for accessing the normal components of the flux

Definition at line 150 of file dual_box_flux.hpp.

◆ dual_box_flux_to_cell() [2/2]

template<typename DeviceType , typename CellSetter , typename FacetAccessor >

void viennashe::util::dual_box_flux_to_cell	(	DeviceType const &	device,
		CellSetter &	cell_setter,
		FacetAccessor const &	facet_accessor
	)

Interpolates normal components of the flux defined on each facet to all cells in the mesh (or segment).

Parameters

device	The ViennaSHE device on which to interpolate.
cell_setter	Functor for storing the interpolated flux vector
facet_accessor	Functor for accessing the normal components of the flux

Definition at line 212 of file dual_box_flux.hpp.

◆ dump_mesh()

template<typename DeviceT , typename IndexT >

void viennashe::util::dump_mesh	(	DeviceT const &	device,
		double **	vertices,
		IndexT &	num_vertices,
		IndexT **	cells,
		IndexT &	num_cells
	)

Definition at line 28 of file dump_device_mesh.hpp.

◆ format_number_to_width()

template<typename T >

std::string viennashe::util::format_number_to_width	(	T	number,
		int	width
	)

Returns the formatted number as string with the given length, where spaces are used as padding character.

Parameters

number	The number to be formatted
width	Non negative number

Returns: Formatted number as string

Definition at line 372 of file misc.hpp.

◆ generate_device()

template<typename MeshT , typename SegmentationT >

void viennashe::util::generate_device	(	MeshT &	mesh,
		SegmentationT &	seg,
		device_generation_config const &	conf
	)

Public interface for mesh generation of simple one- or two-dimensional meshes. Device must be rectangular for the two-dimensional case.

Parameters

mesh	An empty ViennaGrid mesh
seg	An empty ViennaGrid segementation
conf	The mesh generation configuration object

Definition at line 469 of file generate_device.hpp.

◆ get_connected_semiconductor_cell()

template<typename DeviceT , typename CellT >

CellT const * viennashe::util::get_connected_semiconductor_cell	(	DeviceT const &	device,
		CellT const &	cell
	)

Helper function returning a const-pointer to the 'second cell' of a facet, or NULL if there is no second facet. The 'first' cell is passed to the function.

Definition at line 216 of file misc.hpp.

◆ get_other_cell_of_facet()

template<typename MeshT , typename FacetT , typename CellT >

CellT const * viennashe::util::get_other_cell_of_facet	(	MeshT const &	mesh,
		FacetT const &	facet,
		CellT const &	cell
	)

Helper function returning a const-pointer to the 'second cell' of a facet, or NULL if there is no second facet. The 'first' cell is passed to the function.

Definition at line 196 of file misc.hpp.

◆ is_Inf()

template<typename ValueType >

bool viennashe::util::is_Inf ( const ValueType & val )

Checks if a value of type ValueType is Inf using (value - value) != 0.

Definition at line 101 of file checks.hpp.

◆ is_NaN()

template<typename ValueType >

bool viennashe::util::is_NaN ( const ValueType & val )

Checks if a value of type ValueType is NaN using value != value.

Definition at line 97 of file checks.hpp.

◆ is_negative()

template<typename ValueType >

bool viennashe::util::is_negative ( const ValueType & val )

Checks if a value of type ValueType is negative using value < 0.

Definition at line 105 of file checks.hpp.

◆ m_matrix_check()

template<typename MatrixType >

void viennashe::util::m_matrix_check ( MatrixType const & A )

Checks a matrix for being an M matrix.

To be an M-matrix, in each row the diagonal entry is the only positive entry. Moreover, the modulus of the sum of the off-diagonal entries has to be smaller or equal (in at least one row strictly smaller) than the off-diagonal entry.

Parameters

A	The matrix to be checked for being an M-matrix

Definition at line 174 of file checks.hpp.

◆ make_checker_with_exception()

template<typename CheckerType , typename ExceptionType >

checker_with_exception< CheckerType, ExceptionType > viennashe::util::make_checker_with_exception	(	CheckerType const &	checker,
		ExceptionType const &	ex
	)

Convenience creator routine for creating a checker with exception from checker returning a bool only.

Definition at line 161 of file checks.hpp.

◆ make_filtered_functor()

template<typename FilterType , typename FunctorType >

filtered_functor< FilterType, FunctorType > viennashe::util::make_filtered_functor	(	FilterType const &	filter,
		FunctorType &	fun
	)

Convenience routine for creating a filtered functor out of the provided filter- and action-functor. Also see class filtered_functor.

Definition at line 175 of file misc.hpp.

◆ matrix_consistency_check() [1/2]

template<typename MatrixType >

long viennashe::util::matrix_consistency_check ( MatrixType const & matrix )

Checks a matrix for empty rows.

Returns: -1 if everything is okay, otherwise index of first empty row

Definition at line 246 of file checks.hpp.

◆ matrix_consistency_check() [2/2]

template<typename NumericT >

long viennashe::util::matrix_consistency_check ( viennashe::math::sparse_matrix< NumericT > const & matrix )

Checks a matrix for empty rows.

Returns: -1 if everything is okay, otherwise index of first empty row

Definition at line 283 of file checks.hpp.

◆ norm_inf()

template<typename VectorType >

VectorType::value_type viennashe::util::norm_inf	(	VectorType const &	v,
		std::size_t	index_start,
		std::size_t	index_stop
	)

Computes the infimum norm of a subvector.

Parameters

v	The vector
index_start	The start index (inclusive)
index_stop	The stop index (exclusive)

Definition at line 386 of file misc.hpp.

◆ outer_cell_normal_at_facet()

template<typename CellTagT , typename FacetTagT , typename WrappedConfigT >

viennagrid::result_of::point< viennagrid::element< CellTagT, WrappedConfigT > >::type viennashe::util::outer_cell_normal_at_facet	(	viennagrid::element< CellTagT, WrappedConfigT > const &	cell,
		viennagrid::element< FacetTagT, WrappedConfigT > const &	facet
	)

Returns the unit outer normal of a facet with respect to the provided cell.

Definition at line 132 of file dual_box_flux.hpp.

◆ subtract_folded_block_vector()

template<typename VectorType , typename BlockMatrixType , typename RowIndexIterator , typename ColumnIndexIterator >

void viennashe::util::subtract_folded_block_vector	(	VectorType &	residual,
		std::size_t	row_index,
		double	prefactor,
		BlockMatrixType const &	coupling_matrix,
		RowIndexIterator	row_iter,
		ColumnIndexIterator const &	col_iter_init,
		double const *	fold_vector
	)

Writes a sub-matrix of a block matrix 'coupling_matrix' to the residual vector. The columns are 'folded' (summed, i.e. a matrix-vector product) according to the vector provided.

Parameters

residual	Residual vector to which the entries are written
row_index	Starting row index in system matrix
prefactor	The block matrix 'coupling_matrix' is multiplied by prefactor before the write operation is carried out
coupling_matrix	The block matrix
row_iter	Iterator over row indices of 'coupling matrix'
col_iter_init	Iterator over column indices of 'coupling matrix'
fold_vector	The vector with which the fold-operation (matrix-vector product on the columns selected by the column-iterator) is carried out.

Definition at line 153 of file block_matrix_writer.hpp.

Namespaces

Classes

Functions

Detailed Description

Function Documentation

◆ add_block_matrix()

◆ add_folded_block_matrix()

◆ check_vanishing_column_sums()

◆ check_vector_for_valid_entries()

◆ dual_box_flux_to_cell() [1/2]

◆ dual_box_flux_to_cell() [2/2]

◆ dump_mesh()

◆ format_number_to_width()

◆ generate_device()

◆ get_connected_semiconductor_cell()

◆ get_other_cell_of_facet()

◆ is_Inf()

◆ is_NaN()

◆ is_negative()

◆ m_matrix_check()

◆ make_checker_with_exception()

◆ make_filtered_functor()

◆ matrix_consistency_check() [1/2]

◆ matrix_consistency_check() [2/2]

◆ norm_inf()

◆ outer_cell_normal_at_facet()

◆ subtract_folded_block_vector()