Basic class definition for the sparse arrays. More...

#include <DianaSparseArray.hpp>

Classes
struct	entry
	Type of the array entry. More...
Public Types
enum	tstate { uninitialized, unassembled, assembled, incr_initalize, incr_append, incr_assembled }
typedef Common::Types::CapeDouble	tvalue
	Type of the array value.
typedef Common::Types::CapeArrayLong	tindices
	Type of the array indices.
typedef std::vector< entry >	tentries
	Type of the entries internal container.
typedef std::vector < tentries::iterator >	pentries
	Type of the entries iterators container.
typedef refiterator < pentries::iterator >	iterator
	Type of the array iterator.
typedef refiterator < pentries::const_iterator >	const_iterator
	Type of the array constant iterator.
typedef entry &	reference
	Type of the array entry reference.
typedef const entry &	const_reference
	Type of the array entry constant reference.
typedef size_t	size_type
	Array size type.
typedef ptrdiff_t	difference_type
	Iterator difference type.
typedef unsigned int	crc_type
	CRC32 value type (for x86_64 int has 32 bits!)
Public Member Functions
	sparray (int _rank=0)
	Default constructor creates unassembled empty array.
	sparray (const tindices &_dims)
	Constructor creates array with predefined dimensions.
	sparray (int nrows, int ncols)
	Constructor creates two dimensional array.
	sparray (const sparray &ar)
	Array copy constructor.
sparray &	operator= (const sparray &ar)
	Array assignment operator.
virtual	~sparray ()
	Empty virtual dtor.
int	rank () const
	Returns number of dimensions.
tstate	state () const
	State of the array (see FSM figure).
bool	isassembled () const
size_type	size () const
	Returns the number of elements in the array.
const tindices &	dimensions () const
	Returns the dimensions of the array.
bool	isempty () const
	Returns true if the array is empty.
bool	iszero () const
crc_type	crc32 () const
	Returns CRC32 of the array structure.
iterator	begin ()
iterator	end ()
const_iterator	begin () const
const_iterator	end () const
reference	at (size_type __n)
	Provides access to the data contained in the array.
const_reference	at (size_type __n) const
	Provides access to the data contained in the array.
reference	operator[] (size_type __n)
	Subscript access to the data contained in the array.
const_reference	operator[] (size_type __n) const
	Subscript access to the data contained in the array.
reference	front ()
const_reference	front () const
reference	back ()
const_reference	back () const
int	find (const tindices &idx) const
iterator	begin_rm ()
iterator	end_rm ()
const_iterator	begin_rm () const
const_iterator	end_rm () const
iterator	begin_rm (int row)
iterator	end_rm (int row)
const_iterator	begin_rm (int row) const
const_iterator	end_rm (int row) const
reference	at_rm (size_type __n)
	Provides access to the data contained in the array.
const_reference	at_rm (size_type __n) const
	Provides access to the data contained in the array.
reference	front_rm ()
const_reference	front_rm () const
reference	back_rm ()
const_reference	back_rm () const
int	find_rm (const tindices &idx) const
iterator	begin_cm ()
iterator	end_cm ()
const_iterator	begin_cm () const
const_iterator	end_cm () const
iterator	begin_cm (int col)
iterator	end_cm (int col)
const_iterator	begin_cm (int col) const
const_iterator	end_cm (int col) const
reference	at_cm (size_type __n)
	Provides access to the data contained in the array.
const_reference	at_cm (size_type __n) const
	Provides access to the data contained in the array.
reference	front_cm ()
const_reference	front_cm () const
reference	back_cm ()
const_reference	back_cm () const
int	find_cm (const tindices &idx) const
void	clear ()
void	reset ()
void	assemble ()
void	append (const tindices &idx, tvalue value)
	Adds a value to array entry by its indices.
void	set_value (const tindices &idx, tvalue value)
	Assigns a value to array entry by its indices.
void	set_value (tvalue value)
	Assigns a value to the whole array.
void	add_value (const tindices &idx, tvalue value)
	Adds a value to array entry by its indices.
tvalue	get_value (const tindices &idx) const
	Returns a value of the array entry by its indices.
tvalue	get_value (...) const
	Returns a value of the array entry by its indices.
void	print_pattern (std::ostream &os) const
std::ostream &	print (std::ostream &ostr, int nentries=-1) const
	Prints array into output stream.
std::ostream &	print_matlab (std::ostream &ostr) const
	Prints array into output stream with Matlab syntax.
Private Member Functions
void	check_assembled (const char *func_name=NULL) const
	Checks status of the array.
void	check_range (size_type __n, const char *func_name=NULL) const
	Checks index in the range of the array.
void	update_value (const tindices &idx, tvalue value, Common::Types::CapeBoolean addition)
	Updates a value of the array entry by its indices.
void	init_structure ()
crc_type	crc32calc (const tindices &buff, unsigned long crc)
Private Attributes
tstate	state_
	State of the array.
int	rank_
	Rank of the array.
crc_type	crc32_
	32 bit CRC of the array structure.
tentries	entries
	Array data internal container.
tentries	new_entries
	Array data internal container with new entries added by append or update_value.
tindices	dims
	Array dimensions.
pentries	entries_rm
	Vector with references onto entries in row major order.
std::vector< int >	entries_rm_comp
pentries	entries_cm
	Vector with references onto entries in column major order.
std::vector< int >	entries_cm_comp
std::vector< int >	incr_order
unsigned int	incr_counter
Friends
std::ostream &	operator<< (std::ostream &os, const sparray::entry &ent)
	Sparse array entry output operator.
std::ostream &	operator<< (std::ostream &os, const sparray &ar)
	Sparse array output operator.

Detailed Description

Basic class definition for the sparse arrays.

Behavior of the sparse array can be represented by the following finite state machine.

Nodes of the finite state machine have type sparray::tstate. Current FSM state in the array is private member sparray::state_, that can be accessed with method sparray::state(). Transitions are method calls of the sparse array. Transition set_value has additional tag "entry" or "no entry". The first one means that entry with indices specified in the set_value arguments has been already added to the sparse array structure, otherwise set_value will have tag "no entry".

Update: 03.09.2009 (L. Iakushyk): If the entries order is incorrect no exception is thrown and the entries order is reinialized. The reason that some models with event switching may change Jacobian structure.

Author:: Michael Krasnyk miha@mpi-magdeburg.mpg.de

Date:: 5 October 2005

Member Enumeration Documentation

enum tstate

Enumeration of states of the sparse array finite state machine.

Enumerator:

uninitialized	Array is uninitialized.
unassembled	Array is unassembled, but possibly has elements.
assembled	Array is assembled.
incr_initalize	"Append" array initialization.
incr_append	"Append" array update.
incr_assembled	Array is assembled.

Constructor & Destructor Documentation

sparray ( int _rank = 0 )

Default constructor creates unassembled empty array.

Parameters:

_rank Number of dimensions. Rank can not be changed during array object life time.

Dimensions sizes are elements of the indices array, so the first dimension is indices[0], the second is indices[1], the last is indices.back() and the rank of the array is the indices.size() (here term rank used in the sense of tensors).

sparray ( const tindices & _dims )

Constructor creates array with predefined dimensions.

Parameters:

indices Vector with dimensions sizes. Dimensions can not be changed during array object life time.

Final dimensions of the array may be more than specified _dims, so set_value or append methods can add value over dimensions boundaries. After array assembling dimensions array will be updated with new values.

sparray	(	int	nrows,
		int	ncols
	)

Constructor creates two dimensional array.

Parameters:

nrows	Number of rows.
ncols	Number of columns.

sparray ( const sparray & ar )

Array copy constructor.

Parameters:

ar	An array of identical elements.

Member Function Documentation

void add_value	(	const tindices &	idx,
		tvalue	value
	)

Adds a value to array entry by its indices.

Parameters:

idx	Entry indices.
value	Array entry increment.

void append	(	const tindices &	idx,
		tvalue	value
	)

Adds a value to array entry by its indices.

Parameters:

idx	Entry indices.
value	Array entry increment.

For this method entries order is fixed by the first initialization order.

Referenced by SingAnalyser::addDerivativeByParameter(), DianaContinuation::addDerivativeByParameter(), DianaContinuation::addLocalParameterisationJacRow(), DianaContinuation::addPseudoParameterisationJacRow(), SteadyStateContinuation::packModelJacobian(), HopfPointContinuation::packModelJacobian(), SingAnalyser::packModelJacobian(), and DianaContinuation::packModelJacobian().

void assemble ( )

Assembles array. This method initializes structure and moves array into assembled state.

reference at ( size_type __n ) [inline]

Provides access to the data contained in the array.

Parameters:

__n	The index of the element for which data should be accessed.

Returns:: Read/write reference to data.

Exceptions:

std::string If n is an invalid index.

This function provides for safer data access. The parameter is first checked that it is in the range of the vector. The function throws std::string if the check fails.

References sparray::at_rm().

const_reference at ( size_type __n ) const [inline]

Provides access to the data contained in the array.

Parameters:

__n	The index of the element for which data should be accessed.

Returns:: Read-only (constant) reference to data.

Exceptions:

std::string If n is an invalid index.

This function provides for safer data access. The parameter is first checked that it is in the range of the vector. The function throws std::string if the check fails.

References sparray::at_rm().

reference at_cm ( size_type __n ) [inline]

Provides access to the data contained in the array.

Parameters:

__n	The column major index of the element for which data should be accessed.

Returns:: Read/write reference to data.

Exceptions:

std::string If n is an invalid index.

This function provides for safer data access. The parameter is first checked that it is in the range of the vector. The function throws std::string if the check fails.

References sparray::check_range(), and sparray::entries_cm.

const_reference at_cm ( size_type __n ) const [inline]

Provides access to the data contained in the array.

Parameters:

__n	The column major index of the element for which data should be accessed.

Returns:: Read-only (constant) reference to data.

Exceptions:

std::string If n is an invalid index.

This function provides for safer data access. The parameter is first checked that it is in the range of the vector. The function throws std::string if the check fails.

References sparray::check_range(), and sparray::entries_cm.

reference at_rm ( size_type __n ) [inline]

Provides access to the data contained in the array.

Parameters:

__n	The row major index of the element for which data should be accessed.

Returns:: Read/write reference to data.

Exceptions:

std::string If n is an invalid index.

This function provides for safer data access. The parameter is first checked that it is in the range of the vector. The function throws std::string if the check fails.

References sparray::check_range(), and sparray::entries_rm.

Referenced by sparray::at().

const_reference at_rm ( size_type __n ) const [inline]

Provides access to the data contained in the array.

Parameters:

__n	The row major index of the element for which data should be accessed.

Returns:: Read-only (constant) reference to data.

Exceptions:

std::string If n is an invalid index.

This function provides for safer data access. The parameter is first checked that it is in the range of the vector. The function throws std::string if the check fails.

References sparray::check_range(), and sparray::entries_rm.

reference back ( ) [inline]

Returns a read/write reference to the data at the last element of the array.

References sparray::back_rm().

const_reference back ( ) const [inline]

Returns a read-only (constant) reference to the data at the last element of the array.

References sparray::back_rm().

reference back_cm ( ) [inline]

Returns a read/write reference to the data at the last element of the column major ordered array.

References sparray::check_assembled(), and sparray::end_cm().

const_reference back_cm ( ) const [inline]

Returns a read-only (constant) reference to the data at the first element of the column major ordered array.

References sparray::check_assembled(), and sparray::end_cm().

reference back_rm ( ) [inline]

Returns a read/write reference to the data at the last element of the row major ordered array.

References sparray::check_assembled(), and sparray::end_rm().

Referenced by sparray::back().

const_reference back_rm ( ) const [inline]

Returns a read-only (constant) reference to the data at the first element of the row major ordered array.

References sparray::check_assembled(), and sparray::end_rm().

iterator begin ( ) [inline]

Returns a read/write iterator that points to the first element in the array. Iteration is done in default element order.

References sparray::begin_rm().

Referenced by sparray::isempty().

const_iterator begin ( ) const [inline]

Returns a read-only (constant) iterator that points to the first element in the array. Iteration is done in default element order.

References sparray::begin_rm().

iterator begin_cm ( ) [inline]

Returns a read/write iterator that points to the first element in the array. Iteration is done in the column major element order.

References sparray::check_assembled(), and sparray::entries_cm.

Referenced by SingAnalyser::addDerivativeByParameter(), and sparray::front_cm().

const_iterator begin_cm ( ) const [inline]

Returns a read-only (constant) iterator that points to the first element in the array. Iteration is done in the column major element order.

References sparray::check_assembled(), and sparray::entries_cm.

iterator begin_cm ( int col )

Returns a read/write iterator that points to the first element in the specified column of the array. Iteration is done in the column major element order.

const_iterator begin_cm ( int col ) const

Returns a read-only (constant) iterator that points to the first element in the specified column of the array. Iteration is done in the column major element order.

iterator begin_rm ( ) [inline]

Returns a read/write iterator that points to the first element in the array. Iteration is done in the row major element order.

References sparray::check_assembled(), and sparray::entries_rm.

Referenced by sparray::begin(), and sparray::front_rm().

const_iterator begin_rm ( ) const [inline]

Returns a read-only (constant) iterator that points to the first element in the array. Iteration is done in the row major element order.

References sparray::check_assembled(), and sparray::entries_rm.

iterator begin_rm ( int row )

Returns a read/write iterator that points to the first element in the specified row of the array. Iteration is done in the row major element order.

const_iterator begin_rm ( int row ) const

Returns a read-only (constant) iterator that points to the first element in the specified row of the array. Iteration is done in the row major element order.

void check_assembled ( const char * func_name = NULL ) const [private]

Checks status of the array.

Parameters:

func_name Name of the testing function.

Exceptions:

std::string If array is unassembled.

Referenced by sparray::back_cm(), sparray::back_rm(), sparray::begin_cm(), sparray::begin_rm(), sparray::dimensions(), sparray::end_cm(), sparray::end_rm(), sparray::front_cm(), sparray::front_rm(), sparray::isempty(), sparray::operator[](), and sparray::size().

void check_range	(	size_type	__n,
		const char *	func_name = `NULL`
	)		const `[private]`

Checks index in the range of the array.

Parameters:

func_name	Name of the testing function.
__n	The row major index of the element.

Exceptions:

std::string If __n is an invalid index or array is unassembled.

Referenced by sparray::at_cm(), and sparray::at_rm().

void clear ( )

Clears array and moves array into uninitialized state.

Referenced by DianaContinuation::packModelJacobian().

crc_type crc32 ( ) const [inline]

Returns CRC32 of the array structure.

Array performs CRC32 evaluation in the method init_structure. Structure it's array of sparse indices. First row of this array is dimensions of the array. Next size() rows are indices in the row major order.

References sparray::crc32_.

crc_type crc32calc	(	const tindices &	buff,
		unsigned long	crc
	)		`[private]`

Calculates CRC32 of the indices.

Parameters:

buff	Data container (big endian CapeLong).
crc	CRC algorithm initializer.

Returns:: Evaluated CRC of the consequent data.

iterator end ( ) [inline]

Returns a read/write iterator that points one past the last element in the array. Iteration is done in default element order.

References sparray::end_rm().

Referenced by sparray::isempty().

const_iterator end ( ) const [inline]

Returns a read-only (constant) iterator that points one past the last element in the array. Iteration is done in default element order.

References sparray::end_rm().

iterator end_cm ( ) [inline]

Returns a read/write iterator that points one past the last element in the array. Iteration is done in the column major element order.

References sparray::check_assembled(), and sparray::entries_cm.

Referenced by SingAnalyser::addDerivativeByParameter(), and sparray::back_cm().

const_iterator end_cm ( ) const [inline]

Returns a read-only (constant) iterator that points one past the last element in the array. Iteration is done in the column major element order.

References sparray::check_assembled(), and sparray::entries_cm.

iterator end_cm ( int col )

Returns a read/write iterator that points one past the last element in the specified column of the array. Iteration is done in the column major element order.

const_iterator end_cm ( int col ) const

Returns a read-only (constant) iterator that points one past the last element in the specified column of the array. Iteration is done in the column major element order.

iterator end_rm ( ) [inline]

Returns a read/write iterator that points one past the last element in the array. Iteration is done in the row major element order.

References sparray::check_assembled(), and sparray::entries_rm.

Referenced by sparray::back_rm(), and sparray::end().

const_iterator end_rm ( ) const [inline]

Returns a read-only (constant) iterator that points one past the last element in the array. Iteration is done in the row major element order.

References sparray::check_assembled(), and sparray::entries_rm.

iterator end_rm ( int row )

Returns a read/write iterator that points one past the last element in the specified row of the array. Iteration is done in the row major element order.

const_iterator end_rm ( int row ) const

Returns a read-only (constant) iterator that points one past the last element in the specified row of the array. Iteration is done in the row major element order.

int find ( const tindices & idx ) const [inline]

Returns a position of the entry specified by the indices.

Parameters:

idx	Indices vector.

Returns:: Entry position in the array or -1 if the entry was not found.

References sparray::find_rm().

int find_cm ( const tindices & idx ) const

Returns a position of the entry specified by the indices.

Parameters:

idx	Indices vector.

Returns:: Entry position in the column major ordered array or -1 if the entry was not found.

int find_rm ( const tindices & idx ) const

Returns a position of the entry specified by the indices.

Parameters:

idx	Indices vector.

Returns:: Entry position in the row major ordered array or -1 if the entry was not found.

Referenced by sparray::find().

reference front ( ) [inline]

Returns a read/write reference to the data at the first element of the array.

References sparray::front_rm().

const_reference front ( ) const [inline]

Returns a read-only (constant) reference to the data at the first element of the array.

References sparray::front_rm().

reference front_cm ( ) [inline]

Returns a read/write reference to the data at the first element of the column major ordered array.

References sparray::begin_cm(), and sparray::check_assembled().

const_reference front_cm ( ) const [inline]

Returns a read-only (constant) reference to the data at the first element of the column major ordered array.

References sparray::begin_cm(), and sparray::check_assembled().

reference front_rm ( ) [inline]

Returns a read/write reference to the data at the first element of the row major ordered array.

References sparray::begin_rm(), and sparray::check_assembled().

Referenced by sparray::front().

const_reference front_rm ( ) const [inline]

Returns a read-only (constant) reference to the data at the first element of the row major ordered array.

References sparray::begin_rm(), and sparray::check_assembled().

tvalue get_value ( const tindices & idx ) const

Returns a value of the array entry by its indices.

Parameters:

idx	Entry indices.

tvalue get_value ( ... ) const

Returns a value of the array entry by its indices.

Number of arguments should be equal to the rank of the array. Type of arguments is int. This method is experimental, so it should be used very carefully.

void init_structure ( ) [private]

Initializes structure.

bool isempty ( ) const [inline]

Returns true if the array is empty.

For the current realization this method will return only false (see assemble() method description).

References sparray::begin(), sparray::check_assembled(), and sparray::end().

bool iszero ( ) const

Returns true if matrix is zero.

sparray& operator= ( const sparray & ar )

Array assignment operator.

Parameters:

ar	An array of identical elements.

reference operator[] ( size_type __n ) [inline]

Subscript access to the data contained in the array.

Parameters:

__n	The index of the element for which data should be accessed.

Returns:: Read/write reference to data.

This operator allows for easy, array-style, data access. (For checked lookups see at().)

References sparray::check_assembled(), and sparray::entries_rm.

const_reference operator[] ( size_type __n ) const [inline]

Subscript access to the data contained in the array.

Parameters:

__n	The index of the element for which data should be accessed.

Returns:: Read-only (constant) reference to data.

This operator allows for easy, array-style, data access. (For checked lookups see at().)

References sparray::check_assembled(), and sparray::entries_rm.

std::ostream& print	(	std::ostream &	ostr,
		int	nentries = `-1`
	)		const

Prints array into output stream.

Parameters:

ostr	Output stream.
nentries	Number of printed elements of the array. The whole array will be printed if nentries less than zero.

Returns:: Output stream.

std::ostream& print_matlab ( std::ostream & ostr ) const

Prints array into output stream with Matlab syntax.

Parameters:

ostr	Output stream.

Returns:: Output stream.

int rank ( ) const [inline]

Returns number of dimensions.

Here term rank is used in the sense of tensors and it is not a rank of the linear operator.

References sparray::rank_.

Referenced by SteadyStateContinuation::packModelJacobian(), HopfPointContinuation::packModelJacobian(), and SingAnalyser::packModelJacobian().

void reset ( )

Clears array and moves array into uninitialized state as in clear, and additionally clears dimensions, only rank now is specified at the constructor time!

Referenced by DianaContinuation::initSystemVariables().

void set_value	(	const tindices &	idx,
		tvalue	value
	)

Assigns a value to array entry by its indices.

Parameters:

idx	Entry indices.
value	New element value.

void set_value ( tvalue value )

Assigns a value to the whole array.

Parameters:

value New array value.

void update_value	(	const tindices &	idx,
		tvalue	value,
		Common::Types::CapeBoolean	addition
	)		`[private]`

Updates a value of the array entry by its indices.

Parameters:

idx	Entry indices.
value	Update value.
addition	Type of the update. For addition is true update will be addition, otherwise update will be assignment.

Member Data Documentation

std::vector<int> entries_cm_comp [private]

Vector with references onto first elements of columns. The first element is entries_cm.front() and the last element is entries_cm.back(). Vector has size dims.back()+1.

std::vector<int> entries_rm_comp [private]

Vector with references onto first elements of rows. The first element is entries_rm.front() and the last element is entries_rm.back(). Vector has size dims.front()+1.

unsigned int incr_counter [private]

Internal counter of the append method calls. This vector used only "append" cycle of the array FSM.

std::vector<int> incr_order [private]

Initial order of entries, which were added by append method. This vector used only "append" cycle of the array FSM.

The documentation for this class was generated from the following file:

DianaSparseArray.hpp

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation