molpro::linalg::array::ArrayHandler< AL, AR > Class Template Reference

Enhances various operations between pairs of arrays and allows dynamic code injection with uniform interface. More...

#include <ArrayHandler.h>

Detailed Description

template<class AL, class AR = AL>
class molpro::linalg::array::ArrayHandler< AL, AR >

Enhances various operations between pairs of arrays and allows dynamic code injection with uniform interface.

The handler is directional, there is a left and a right array.

Template Parameters

AL
AR

Operations between pairs of arrays can often be improved with some hindsight, e.g. lazy evaluation and loop fusing, or might require dynamic information, e.g. file name info for copy constructor of disk array. This class is not meant to beautify the code, but to allow dynamic code injection without a bloated interface.

Use cases

Copy constructor

AL slow;
AR fast;
ArrayHandler<AL, AR> handler;
AL copy_of_fast = handler.copy(fast);

Lazy evaluation of axpy

std::vector<AL> a1;
std::vector<AR> a2;
Matrix alpha;
// ... Assume initialization was done
auto h = handle.lazy_handle();
for (auto i = 0; i < a1.size(); ++i)
  for (auto j = 0; j < a2.size(); ++j)
    h.axpy(alpha[i,j], a2[i], a1[j]);
h.eval(); // or let destructor handle it

Lazy evaluation of dot

std::vector<AL> a1;
std::vector<AR> a2;
Matrix overlap;
// ... Assume initialization was done
auto h = handle.lazy_handle();
for (auto i = 0; i < a1.size(); ++i)
  for (auto j = 0; j < a2.size(); ++j)
    h.dot(a1[i], a2[j], overlap[i,j]);
h.eval(); // or let the destructor handle it

Classes
struct	Counter
class	LazyHandle
	Registers operations for lazy evaluation. Evaluation is triggered by calling eval() or on destruction. More...
class	ProxyHandle
	A convenience wrapper around a pointer to the LazyHandle. More...

Public Types
using	value_type_L = typename array::mapped_or_value_type_t< AL >
using	value_type_R = typename array::mapped_or_value_type_t< AR >
using	value_type = decltype(value_type_L{} *value_type_R{})
using	value_type_abs = decltype(check_abs< value_type >())

Public Member Functions
virtual AL	copy (const AR &source)=0
virtual void	copy (AL &x, const AR &y)=0
	Copy content of y into x. More...
virtual void	scal (value_type alpha, AL &x)=0
virtual void	fill (value_type alpha, AL &x)=0
virtual void	axpy (value_type alpha, const AR &x, AL &y)=0
virtual value_type	dot (const AL &x, const AR &y)=0
virtual void	gemm_outer (const Matrix< value_type > alphas, const CVecRef< AR > &xx, const VecRef< AL > &yy)=0
virtual Matrix< value_type >	gemm_inner (const CVecRef< AL > &xx, const CVecRef< AR > &yy)=0
virtual std::map< size_t, value_type_abs >	select_max_dot (size_t n, const AL &x, const AR &y)=0
	Select n indices with largest by absolute value contributions to the dot product. More...
virtual std::map< size_t, value_type >	select (size_t n, const AL &x, bool max=false, bool ignore_sign=false)=0
	Select n indices with largest (or smallest) actual (or absolute) value. More...
const Counter &	counter () const
std::string	counter_to_string (std::string L, std::string R)
void	clear_counter ()
virtual	~ArrayHandler ()
	Destroys ArrayHandler instance and invalidates any LazyHandler it created. Invalidated handler will not evaluate. More...
virtual ProxyHandle	lazy_handle ()=0
	Returns a lazy handle. Most implementations simply need to call the overload: return lazy_handle(*this);. More...

Protected Member Functions
	ArrayHandler ()
	ArrayHandler (const ArrayHandler &)=default
virtual void	error (const std::string &message)
	Throws an error. More...
virtual void	fused_axpy (const std::vector< std::tuple< size_t, size_t, size_t > > &reg, const std::vector< value_type > &alphas, const std::vector< std::reference_wrapper< const AR > > &xx, std::vector< std::reference_wrapper< AL > > &yy)
	Default implementation of fused_axpy without any simplification. More...
virtual void	fused_dot (const std::vector< std::tuple< size_t, size_t, size_t > > &reg, const std::vector< std::reference_wrapper< const AL > > &xx, const std::vector< std::reference_wrapper< const AR > > &yy, std::vector< std::reference_wrapper< value_type > > &out)
	Default implementation of fused_dot without any simplification. More...
void	save_handle (const std::shared_ptr< LazyHandle > &handle)
	Save weak ptr to a lazy handle. More...
ProxyHandle	lazy_handle (ArrayHandler< AL, AR > &handler)

Protected Attributes
std::unique_ptr< Counter >	m_counter
std::vector< std::weak_ptr< LazyHandle > >	m_lazy_handles
	keeps track of all created lazy handles More...

Member Typedef Documentation

value_type

template<class AL , class AR = AL>

using molpro::linalg::array::ArrayHandler< AL, AR >::value_type = decltype(value_type_L{} * value_type_R{})

value_type_abs

template<class AL , class AR = AL>

using molpro::linalg::array::ArrayHandler< AL, AR >::value_type_abs = decltype(check_abs<value_type>())

value_type_L

template<class AL , class AR = AL>

using molpro::linalg::array::ArrayHandler< AL, AR >::value_type_L = typename array::mapped_or_value_type_t<AL>

value_type_R

template<class AL , class AR = AL>

using molpro::linalg::array::ArrayHandler< AL, AR >::value_type_R = typename array::mapped_or_value_type_t<AR>

Constructor & Destructor Documentation

ArrayHandler() [1/2]

template<class AL , class AR = AL>

molpro::linalg::array::ArrayHandler< AL, AR >::ArrayHandler ( )

inlineprotected

ArrayHandler() [2/2]

template<class AL , class AR = AL>

molpro::linalg::array::ArrayHandler< AL, AR >::ArrayHandler ( const ArrayHandler< AL, AR > &  )

protecteddefault

~ArrayHandler()

template<class AL , class AR = AL>

virtual molpro::linalg::array::ArrayHandler< AL, AR >::~ArrayHandler ( )

inlinevirtual

Destroys ArrayHandler instance and invalidates any LazyHandler it created. Invalidated handler will not evaluate.

Member Function Documentation

axpy()

template<class AL , class AR = AL>

virtual void molpro::linalg::array::ArrayHandler< AL, AR >::axpy ( value_type  alpha, const AR &  x, AL &  y  )

pure virtual

Implemented in molpro::linalg::array::ArrayHandlerDDiskSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerDistrSparse< AL, AR, true >, and molpro::linalg::array::ArrayHandlerIterableSparse< AL, AR, true >.

clear_counter()

template<class AL , class AR = AL>

void molpro::linalg::array::ArrayHandler< AL, AR >::clear_counter ( )

inline

copy() [1/2]

template<class AL , class AR = AL>

virtual void molpro::linalg::array::ArrayHandler< AL, AR >::copy ( AL &  x, const AR &  y  )

pure virtual

Copy content of y into x.

Implemented in molpro::linalg::array::ArrayHandlerDDiskSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerDistrSparse< AL, AR, true >, and molpro::linalg::array::ArrayHandlerIterableSparse< AL, AR, true >.

copy() [2/2]

template<class AL , class AR = AL>

virtual AL molpro::linalg::array::ArrayHandler< AL, AR >::copy ( const AR &  source )

pure virtual

Implemented in molpro::linalg::array::ArrayHandlerDDiskSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerDistrSparse< AL, AR, true >, and molpro::linalg::array::ArrayHandlerIterableSparse< AL, AR, true >.

counter()

template<class AL , class AR = AL>

const Counter & molpro::linalg::array::ArrayHandler< AL, AR >::counter ( ) const

inline

counter_to_string()

template<class AL , class AR = AL>

std::string molpro::linalg::array::ArrayHandler< AL, AR >::counter_to_string ( std::string  L, std::string  R  )

inline

dot()

template<class AL , class AR = AL>

virtual value_type molpro::linalg::array::ArrayHandler< AL, AR >::dot ( const AL &  x, const AR &  y  )

pure virtual

Implemented in molpro::linalg::array::ArrayHandlerDDiskSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerDistrSparse< AL, AR, true >, and molpro::linalg::array::ArrayHandlerIterableSparse< AL, AR, true >.

error()

template<class AL , class AR = AL>

virtual void molpro::linalg::array::ArrayHandler< AL, AR >::error ( const std::string &  message )

inlineprotectedvirtual

Throws an error.

Parameters

message

error message

fill()

template<class AL , class AR = AL>

virtual void molpro::linalg::array::ArrayHandler< AL, AR >::fill ( value_type  alpha, AL &  x  )

pure virtual

Implemented in molpro::linalg::array::ArrayHandlerDDisk< AL, AR >, molpro::linalg::array::ArrayHandlerDDiskDistr< AL, AR >, molpro::linalg::array::ArrayHandlerDDiskSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerDefault< AL, AR >, molpro::linalg::array::ArrayHandlerDistr< AL, AR >, molpro::linalg::array::ArrayHandlerDistrDDisk< AL, AR >, molpro::linalg::array::ArrayHandlerDistrSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerIterable< AL, AR >, molpro::linalg::array::ArrayHandlerIterableSparse< AL, AR, true >, and molpro::linalg::array::ArrayHandlerSparse< AL, AR >.

fused_axpy()

template<class AL , class AR = AL>

virtual void molpro::linalg::array::ArrayHandler< AL, AR >::fused_axpy ( const std::vector< std::tuple< size_t, size_t, size_t > > &  reg, const std::vector< value_type > &  alphas, const std::vector< std::reference_wrapper< const AR > > &  xx, std::vector< std::reference_wrapper< AL > > &  yy  )

inlineprotectedvirtual

Default implementation of fused_axpy without any simplification.

fused_dot()

template<class AL , class AR = AL>

virtual void molpro::linalg::array::ArrayHandler< AL, AR >::fused_dot ( const std::vector< std::tuple< size_t, size_t, size_t > > &  reg, const std::vector< std::reference_wrapper< const AL > > &  xx, const std::vector< std::reference_wrapper< const AR > > &  yy, std::vector< std::reference_wrapper< value_type > > &  out  )

inlineprotectedvirtual

Default implementation of fused_dot without any simplification.

gemm_inner()

template<class AL , class AR = AL>

virtual Matrix< value_type > molpro::linalg::array::ArrayHandler< AL, AR >::gemm_inner ( const CVecRef< AL > &  xx, const CVecRef< AR > &  yy  )

pure virtual

Perform dot() on multiple pairs of containers in an efficient manner

Implemented in molpro::linalg::array::ArrayHandlerDDiskSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerDistrSparse< AL, AR, true >, and molpro::linalg::array::ArrayHandlerIterableSparse< AL, AR, true >.

gemm_outer()

template<class AL , class AR = AL>

virtual void molpro::linalg::array::ArrayHandler< AL, AR >::gemm_outer ( const Matrix< value_type >  alphas, const CVecRef< AR > &  xx, const VecRef< AL > &  yy  )

pure virtual

Perform axpy() on multiple pairs of containers in an efficient manner

lazy_handle() [1/2]

template<class AL , class AR = AL>

virtual ProxyHandle molpro::linalg::array::ArrayHandler< AL, AR >::lazy_handle ( )

pure virtual

Returns a lazy handle. Most implementations simply need to call the overload: return lazy_handle(*this);.

Implemented in molpro::linalg::array::ArrayHandlerDDisk< AL, AR >, molpro::linalg::array::ArrayHandlerDDiskDistr< AL, AR >, molpro::linalg::array::ArrayHandlerDDiskSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerDefault< AL, AR >, molpro::linalg::array::ArrayHandlerDistr< AL, AR >, molpro::linalg::array::ArrayHandlerDistrDDisk< AL, AR >, molpro::linalg::array::ArrayHandlerDistrSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerIterable< AL, AR >, molpro::linalg::array::ArrayHandlerIterableSparse< AL, AR, true >, and molpro::linalg::array::ArrayHandlerSparse< AL, AR >.

lazy_handle() [2/2]

template<class AL , class AR = AL>

ProxyHandle molpro::linalg::array::ArrayHandler< AL, AR >::lazy_handle ( ArrayHandler< AL, AR > &  handler )

inlineprotected

save_handle()

template<class AL , class AR = AL>

void molpro::linalg::array::ArrayHandler< AL, AR >::save_handle ( const std::shared_ptr< LazyHandle > &  handle )

inlineprotected

Save weak ptr to a lazy handle.

scal()

template<class AL , class AR = AL>

virtual void molpro::linalg::array::ArrayHandler< AL, AR >::scal ( value_type  alpha, AL &  x  )

pure virtual

Implemented in molpro::linalg::array::ArrayHandlerDDisk< AL, AR >, molpro::linalg::array::ArrayHandlerDDiskDistr< AL, AR >, molpro::linalg::array::ArrayHandlerDDiskSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerDefault< AL, AR >, molpro::linalg::array::ArrayHandlerDistr< AL, AR >, molpro::linalg::array::ArrayHandlerDistrDDisk< AL, AR >, molpro::linalg::array::ArrayHandlerDistrSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerIterable< AL, AR >, molpro::linalg::array::ArrayHandlerIterableSparse< AL, AR, true >, and molpro::linalg::array::ArrayHandlerSparse< AL, AR >.

select()

template<class AL , class AR = AL>

virtual std::map< size_t, value_type > molpro::linalg::array::ArrayHandler< AL, AR >::select ( size_t  n, const AL &  x, bool  max = false, bool  ignore_sign = false  )

pure virtual

Select n indices with largest (or smallest) actual (or absolute) value.

Parameters

n	number of indices to select
x	array to examine
max	If true, select largest values, otherwise smallest
ignore_sign	If true, consider std::abs() of elements

Returns

map of indices and corresponding values

Implemented in molpro::linalg::array::ArrayHandlerDDisk< AL, AR >, molpro::linalg::array::ArrayHandlerDDiskDistr< AL, AR >, molpro::linalg::array::ArrayHandlerDDiskSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerDefault< AL, AR >, molpro::linalg::array::ArrayHandlerDistr< AL, AR >, molpro::linalg::array::ArrayHandlerDistrDDisk< AL, AR >, molpro::linalg::array::ArrayHandlerDistrSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerIterable< AL, AR >, molpro::linalg::array::ArrayHandlerIterableSparse< AL, AR, true >, and molpro::linalg::array::ArrayHandlerSparse< AL, AR >.

select_max_dot()

template<class AL , class AR = AL>

virtual std::map< size_t, value_type_abs > molpro::linalg::array::ArrayHandler< AL, AR >::select_max_dot ( size_t  n, const AL &  x, const AR &  y  )

pure virtual

Select n indices with largest by absolute value contributions to the dot product.

This is necessary for perturbation theory.

Parameters

n	number of indices to select
x	left array
y	right array

Returns

map of indices and corresponding x,y product

Implemented in molpro::linalg::array::ArrayHandlerDDiskSparse< AL, AR, true >, molpro::linalg::array::ArrayHandlerDistrSparse< AL, AR, true >, and molpro::linalg::array::ArrayHandlerIterableSparse< AL, AR, true >.

Member Data Documentation

m_counter

template<class AL , class AR = AL>

std::unique_ptr<Counter> molpro::linalg::array::ArrayHandler< AL, AR >::m_counter

protected

m_lazy_handles

template<class AL , class AR = AL>

std::vector<std::weak_ptr<LazyHandle> > molpro::linalg::array::ArrayHandler< AL, AR >::m_lazy_handles

protected

keeps track of all created lazy handles