GSLUtility Provides top level interface to the GNU GSL. More...

#include <GSLUtility.h>

Collaboration diagram for Isis::GSL::GSLUtility:

Public Types
typedef TNT::Array1D< double >	GSLVector

typedef TNT::Array2D< double >	GSLMatrix

Public Member Functions
bool	success (int status) const
	Tests if status is success.

QString	status (int gsl_errno) const
	Returns GSL specific error text.

void	check (int gsl_status, const char *src=__FILE__, int line=__LINE__) const
	Performs a check on GSL library function return status.

size_t	Rows (const gsl_matrix *m) const
	Returns number of rows in a GSL matrix.

size_t	Columns (const gsl_matrix *m) const
	Returns the number of coulumns in a GSL matrix.

size_t	Rows (const GSLMatrix &m) const
	Returns the number of rows in TNT-based matrix

size_t	Columns (const GSLMatrix &m) const
	Returns the number of columns in TNT-based matrix.

size_t	size (const gsl_vector *v) const
	Returns the size of a GSL vector.

size_t	size (const gsl_matrix *m) const
	Returns the total number of elements in a GSL matrix.

gsl_vector *	vector (size_t n, bool zero=false) const
	Creates a GSL vector.

gsl_matrix *	matrix (size_t n1, size_t n2, bool zero=false) const
	Creates a GSL matrix.

gsl_matrix *	identity (size_t n1, size_t n2) const
	Returns a GSL identity matrix of the specified size.

void	setIdentity (gsl_matrix *m) const
	Initializes an existing GSL matrix to the identity matrix.

void	free (gsl_vector *v) const
	Frees a GSL vector.

void	free (gsl_matrix *m) const
	Frees a GSL matrix.

GSLVector	gslToGSL (const gsl_vector *v) const
	Converts a GSL vector to a TNT-based vector.

GSLMatrix	gslToGSL (const gsl_matrix *m) const
	Converts a GSL matrix to a TNT-based matrix.

gsl_vector *	GSLTogsl (const GSLVector &v, gsl_vector *gv=0) const
	Converts TNT-based vector to GSL vector.

gsl_matrix *	GSLTogsl (const GSLMatrix &m, gsl_matrix *gm=0) const
	Converts TNT-based matrix to GSL matrix.

Static Public Member Functions
static GSLUtility *	getInstance ()
	Return a reference to the GSL (singleton) object.

Private Member Functions
	GSLUtility ()
	Contructs a GSLUtility object with an error handler.

Static Private Member Functions
static void	handler (const char reason, const char file, int line, int gsl_errno)
	Special GSL errror handler.

Static Private Attributes
static GSLUtility *	_instance = 0
	Singleton self-reference pointer.

Detailed Description

GSLUtility Provides top level interface to the GNU GSL.

Provides GSL setup and interface utilities. This object is provided for convenience of GSL vector and matrix manipulation as well as better management of GSL error handling.

Without setting up GSL error handling, the GSL will abort when certain errors occur. This singleton object, an object where there is never more than one instance, an error handler is established that captures GSL errors and formats them into ISIS exceptions.

There are many convenience methods provided for manipulation of GSL vectors and matrixs. Motivation for this is to address element access and efficient parameter and copy mechanisms (provided by the TNT library).

There are some compile options on by default that help optimize the GSL. When the compile time DEBUG macro is set, range checking is turned on. Inline functions are also turned on by default unless the DEBUG macro is set. In addition, an additional compile time macro called SAFE_GSL is provided to emulate the DEBUG behavior, but does not invoke additional DEBUG behavior/side effects.

See http://www.gnu.org/software/gsl/ for additional details on the GNU Scientific Library.

Author: 2008-05-06 Kris Becker

History: 2009-08-20 Kris Becker Completed documentation

Definition at line 69 of file GSLUtility.h.

Member Typedef Documentation

◆ GSLMatrix

typedef TNT::Array2D<double> Isis::GSL::GSLUtility::GSLMatrix

Definition at line 72 of file GSLUtility.h.

◆ GSLVector

typedef TNT::Array1D<double> Isis::GSL::GSLUtility::GSLVector

Definition at line 71 of file GSLUtility.h.

Constructor & Destructor Documentation

◆ GSLUtility()

Isis::GSL::GSLUtility::GSLUtility ( )

private

Contructs a GSLUtility object with an error handler.

Sets an error handler for the GSL library so fatal GSL errors are intercepted and handled throught the ISIS exception utility.

See http://www.gnu.org/software/gsl/manual/html_node/Error-Handling.html for additional information.

Definition at line 35 of file GSLUtility.cpp.

References handler(), and vector().

Referenced by getInstance().

◆ ~GSLUtility()

Isis::GSL::GSLUtility::~GSLUtility ( )

inlineprivate

Definition at line 121 of file GSLUtility.h.

Member Function Documentation

◆ check()

void Isis::GSL::GSLUtility::check	(	int	gsl_status,
		const char *	src = __FILE__,
		int	line = __LINE__ ) const

Performs a check on GSL library function return status.

This covenience method performs a validity check on the return status of a GSL function. It will throw an ISIS exception should the status be anything other than GSL_SUCCESS.

Parameters

gsl_status	Return value of GSL function
src	Name of the source file where the function was called.
line	Line number in the source where the call/error occurs

Definition at line 307 of file GSLUtility.cpp.

References Isis::IException::Programmer, and vector().

◆ Columns() [1/2]

size_t Isis::GSL::GSLUtility::Columns ( const gsl_matrix * m ) const

Returns the number of coulumns in a GSL matrix.

Definition at line 272 of file GSLUtility.cpp.

Referenced by gslToGSL(), GSLTogsl(), and size().

◆ Columns() [2/2]

size_t Isis::GSL::GSLUtility::Columns ( const GSLMatrix & m ) const

Returns the number of columns in TNT-based matrix.

Definition at line 277 of file GSLUtility.cpp.

◆ free() [1/2]

void Isis::GSL::GSLUtility::free ( gsl_matrix * m ) const

Frees a GSL matrix.

Frees the memory allocated to a GSL matrix. As with any free operation, the matrix cannot be used thereafter.

It is up to the user to manage all GSL allocated elements. It is not done automatically.

Parameters

m	GSL matrix to free

Definition at line 157 of file GSLUtility.cpp.

References vector().

◆ free() [2/2]

void Isis::GSL::GSLUtility::free ( gsl_vector * v ) const

Frees a GSL vector.

Frees the memory allocated to a GSL vector. As with any free operation, the vector cannot be used thereafter.

It is up to the user to manage all GSL allocated elements. It is not done automatically.

Parameters

v	GSL vector to free

Definition at line 141 of file GSLUtility.cpp.

References vector().

◆ getInstance()

GSLUtility * Isis::GSL::GSLUtility::getInstance ( )

static

Return a reference to the GSL (singleton) object.

This method returns a pointer reference to the GSL utility object. If it is not yet created, one is constructed and lives until the application terminates.

Returns: GSLUtility::GSLUtility* Pointer reference to GSLUtility singleton

Definition at line 49 of file GSLUtility.cpp.

References _instance, and GSLUtility().

Referenced by Isis::SmtkMatcher::randomNumberSetup().

◆ gslToGSL() [1/2]

GSLUtility::GSLMatrix Isis::GSL::GSLUtility::gslToGSL ( const gsl_matrix * m ) const

Converts a GSL matrix to a TNT-based matrix.

Convenience method to convert to GSLMatrix type

Parameters

m	GSL matrix to convert

Returns: GSLUtility::GSLMatrix TNT-based matrix

Definition at line 189 of file GSLUtility.cpp.

References Columns(), Rows(), and vector().

◆ gslToGSL() [2/2]

GSLUtility::GSLVector Isis::GSL::GSLUtility::gslToGSL ( const gsl_vector * v ) const

Converts a GSL vector to a TNT-based vector.

Convenience method to convert to GSLVector type

Parameters

v	GSL vector to convert

Returns: GSLUtility::GSLVector TNT-based vector

Definition at line 171 of file GSLUtility.cpp.

References size(), and vector().

◆ GSLTogsl() [1/2]

gsl_matrix * Isis::GSL::GSLUtility::GSLTogsl	(	const GSLMatrix &	m,
		gsl_matrix *	gm = 0 ) const

Converts TNT-based matrix to GSL matrix.

Convenience method to convert TNT-based matrix to a GSL matrix.

Parameters

m	TNT-based matrix to convert
gm	Optional GSL matrix of same size to copy data to

Returns: gsl_matrix* Pointer to GSL matrix copy

Definition at line 242 of file GSLUtility.cpp.

References Columns(), Isis::IException::Programmer, Rows(), and vector().

◆ GSLTogsl() [2/2]

gsl_vector * Isis::GSL::GSLUtility::GSLTogsl	(	const GSLVector &	v,
		gsl_vector *	gv = 0 ) const

Converts TNT-based vector to GSL vector.

Convenience method to convert TNT-based vector to a GSL vector.

Parameters

v	TNT-based vector to convert
gv	Optional GSL vector of same size to copy data to

Returns: gsl_vector* Pointer to GSL vector copy

Definition at line 212 of file GSLUtility.cpp.

References Isis::IException::Programmer, size(), and vector().

◆ handler()

void Isis::GSL::GSLUtility::handler	(	const char *	reason,
		const char *	file,
		int	line,
		int	gsl_errno )

staticprivate

Special GSL errror handler.

This method is the designated ISIS error handler for errors that occur within the GSL library. It will be called by the GSL library when errors occur to handle failures. It is designed to override GSL default behavior which is to issue an error and abort the application.

This method traps the error and throws an ISIS exception indicating the error.

Parameters

reason	GSL description of the error
file	Source file where the error originates
line	Line if source file where error occurred
gsl_errno	Actual GSL error encountered

Definition at line 331 of file GSLUtility.cpp.

References Isis::IException::Programmer, and vector().

Referenced by GSLUtility().

◆ identity()

gsl_matrix * Isis::GSL::GSLUtility::identity	(	size_t	n1,
		size_t	n2 ) const

Returns a GSL identity matrix of the specified size.

This method allocates a square or rectanglar matrix and initilizes it to the identity matrix. The diagonal elements are all set to 1.0, all other elements are set to 0.

Parameters

n1	Number rows to allocate
n2	Number columns to allocate

Returns: gsl_matrix* Returns pointer to identity matrix

Definition at line 114 of file GSLUtility.cpp.

References vector().

◆ matrix()

gsl_matrix * Isis::GSL::GSLUtility::matrix	(	size_t	n1,
		size_t	n2,
		bool	zero = false ) const

Creates a GSL matrix.

This convenience method creates a GSL matrix for use within applications. The memory is dynamically allocated and must be managed (i.e., freed) by the caller. See the free() method for this provision.

Parameters

n1	Size of rows in the GSL matrix to create
n2	Size of columns in the GSL matrix to create
zero	Set to true if you want GSL to assign 0 to the allocated matrix otherwise, false will not initilize the memory.

Returns: gsl_matrix* Returns an allocated GSL matrix

Definition at line 93 of file GSLUtility.cpp.

References vector().

◆ Rows() [1/2]

size_t Isis::GSL::GSLUtility::Rows ( const gsl_matrix * m ) const

Returns number of rows in a GSL matrix.

Definition at line 267 of file GSLUtility.cpp.

Referenced by gslToGSL(), GSLTogsl(), and size().

◆ Rows() [2/2]

size_t Isis::GSL::GSLUtility::Rows ( const GSLMatrix & m ) const

Returns the number of rows in TNT-based matrix

Definition at line 282 of file GSLUtility.cpp.

◆ setIdentity()

void Isis::GSL::GSLUtility::setIdentity ( gsl_matrix * m ) const

Initializes an existing GSL matrix to the identity matrix.

Parameters

m	Pointer to matrix to set to identity

Definition at line 125 of file GSLUtility.cpp.

References vector().

◆ size() [1/2]

size_t Isis::GSL::GSLUtility::size ( const gsl_matrix * m ) const

Returns the total number of elements in a GSL matrix.

Definition at line 292 of file GSLUtility.cpp.

References Columns(), and Rows().

◆ size() [2/2]

size_t Isis::GSL::GSLUtility::size ( const gsl_vector * v ) const

Returns the size of a GSL vector.

Definition at line 287 of file GSLUtility.cpp.

Referenced by gslToGSL(), and GSLTogsl().

◆ status()

QString Isis::GSL::GSLUtility::status ( int gsl_errno ) const

inline

Returns GSL specific error text.

Parameters

gsl_errno GSL error number

Returns: QString Textual context of GSL error

Definition at line 87 of file GSLUtility.h.

References vector().

Referenced by success().

◆ success()

bool Isis::GSL::GSLUtility::success ( int status ) const

inline

Tests if status is success.

Definition at line 77 of file GSLUtility.h.

References status().

◆ vector()

gsl_vector * Isis::GSL::GSLUtility::vector	(	size_t	n,
		bool	zero = false ) const

Creates a GSL vector.

This convenience method creates a GSL vector for use within applications. The memory is dynamically allocated and must be managed (i.e., freed) by the caller. See the free() method for this provision.

Parameters

n	Size of GSL vector to create
zero	Set to true if you want GSL to assign 0 to the allocated vector otherwise, false will not initilize the memory.

Returns: gsl_vector* Returns an allocated GSL vector

Definition at line 70 of file GSLUtility.cpp.

References vector().

Referenced by check(), free(), free(), gslToGSL(), gslToGSL(), GSLTogsl(), GSLTogsl(), GSLUtility(), handler(), identity(), matrix(), setIdentity(), status(), and vector().

Member Data Documentation

◆ _instance

GSLUtility * Isis::GSL::GSLUtility::_instance = 0

staticprivate

Singleton self-reference pointer.

! Initialization of object reference

Definition at line 123 of file GSLUtility.h.

Referenced by getInstance().

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

src/base/objs/GSLUtility/GSLUtility.h
src/base/objs/GSLUtility/GSLUtility.cpp

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Static Private Attributes

Detailed Description

Member Typedef Documentation

◆ GSLMatrix

◆ GSLVector

Constructor & Destructor Documentation

◆ GSLUtility()

◆ ~GSLUtility()

Member Function Documentation

◆ check()

◆ Columns() [1/2]

◆ Columns() [2/2]

◆ free() [1/2]

◆ free() [2/2]

◆ getInstance()

◆ gslToGSL() [1/2]

◆ gslToGSL() [2/2]

◆ GSLTogsl() [1/2]

◆ GSLTogsl() [2/2]

◆ handler()

◆ identity()

◆ matrix()

◆ Rows() [1/2]

◆ Rows() [2/2]

◆ setIdentity()

◆ size() [1/2]

◆ size() [2/2]

◆ status()

◆ success()

◆ vector()

Member Data Documentation

◆ _instance