A templated (base) class for handling scalar functions. More...

#include <ScalarFunction.h>

Inheritance diagram for QUESO::BaseScalarFunction< V, M >:

Public Member Functions
void	setFiniteDifferenceStepSize (double fdStepSize)
	Sets the step size for finite differencing gradients. More...

void	setFiniteDifferenceStepSize (unsigned int i, double fdStepSize)

Constructor/Destructor methods.
	BaseScalarFunction (const char *prefix, const VectorSet< V, M > &domainSet)
	Default constructor. More...

virtual	~BaseScalarFunction ()
	Destructor. More...

Mathematical methods.
const VectorSet< V, M > &	domainSet () const
	Access to the protected attribute `m_domainSet:` domain set of the scalar function. More...

Evaluation methods
virtual double	lnValue (const V &domainVector, const V domainDirection, V gradVector, M hessianMatrix, V hessianEffect) const
	Logarithm of the value of the scalar function. Deprecated. More...

virtual double	lnValue (const V &domainVector) const
	Returns the logarithm of the function at `domainVector`. More...

virtual double	lnValue (const V &domainVector, V &gradVector) const
	Returns the logarithm of the function and its gradient at `domainVector`. More...

virtual double	lnValue (const V &domainVector, V &gradVector, const V &domainDirection, V &hessianEffect) const

virtual double	actualValue (const V &domainVector, const V domainDirection, V gradVector, M hessianMatrix, V hessianEffect) const =0
	Actual value of the scalar function. More...

Protected Attributes
const BaseEnvironment &	m_env

std::string	m_prefix

const VectorSet< V, M > &	m_domainSet
	Domain set of the scalar function. More...

Private Attributes
ScopedPtr < BoostInputOptionsParser > ::Type	m_parser
	Input parser. More...

std::vector< double >	m_fdStepSize
	Finite different step size. More...

Detailed Description

template<class V = GslVector, class M = GslMatrix>
class QUESO::BaseScalarFunction< V, M >

A templated (base) class for handling scalar functions.

This class allows the mathematical definition of a scalar function such as: \( f: B \subset R \rightarrow R \). A function of one or more variables has always one-dimensional range. PDFs (marginal, joint) and CDFs are examples of scalar functions.

Definition at line 52 of file ScalarFunction.h.

Constructor & Destructor Documentation

template<class V, class M>

QUESO::BaseScalarFunction< V, M >::BaseScalarFunction	(	const char *	prefix,
		const VectorSet< V, M > &	domainSet
	)

Default constructor.

Instantiates an object of the class, i.e. a scalar function, given a prefix and its domain.

Definition at line 46 of file ScalarFunction.C.

References dim, QUESO::BaseEnvironment::input(), QUESO::BaseScalarFunction< V, M >::m_domainSet, QUESO::BaseScalarFunction< V, M >::m_env, QUESO::BaseScalarFunction< V, M >::m_fdStepSize, QUESO::BaseScalarFunction< V, M >::m_parser, QUESO::BaseScalarFunction< V, M >::m_prefix, and QUESO::size.

   : m_env(domainSet.env()),
     m_prefix((std::string)(prefix) + "func_"),
     m_domainSet(domainSet),
 #ifndef QUESO_DISABLE_BOOST_PROGRAM_OPTIONS
     m_parser(new BoostInputOptionsParser(m_env.optionsInputFileName())),
 #endif
     m_fdStepSize(1, std::atof(QUESO_BASESCALARFN_FD_STEPSIZE_ODV))
 {
   unsigned int dim = m_domainSet.vectorSpace().dimLocal();
 
   // Snarf fd step size from input file.
 #ifndef QUESO_DISABLE_BOOST_PROGRAM_OPTIONS
   m_parser->registerOption<std::string>(m_prefix + "fdStepSize",
                                         QUESO_BASESCALARFN_FD_STEPSIZE_ODV,
                                         "step size for finite difference");
   m_parser->scanInputFile();
   m_parser->getOption<std::vector<double> >(m_prefix + "fdStepSize",
                                             m_fdStepSize);
 
   // Check size of finite difference vector the user provided.
   queso_require_msg((m_fdStepSize.size() == 1) || (m_fdStepSize.size() == dim),
                     "Finite difference vector is not the correct size");
 
   // If the user provided a scalar for a multi-dimensional function...
   if (dim > 1 && m_fdStepSize.size() == 1) {
     // ...get the only element
     double stepSize = m_fdStepSize[0];
 
     // and use it to fill a vector of length dim
     m_fdStepSize.resize(dim, stepSize);
   }
 #else
   unsigned int size = m_env.input().vector_variable_size(m_prefix + "fdStepSize");
 
   if (size == 0) {
     m_fdStepSize.resize(dim, std::atof(QUESO_BASESCALARFN_FD_STEPSIZE_ODV));
   }
   else if (size == 1) {
     double value = m_env.input()(m_prefix + "fdStepSize",
                                  std::atof(QUESO_BASESCALARFN_FD_STEPSIZE_ODV),
                                  0);
 
     m_fdStepSize.resize(dim, value);
   }
   else if (size == dim) {
     for (unsigned int i = 0; i < size; i++) {
       m_fdStepSize[i] = m_env.input()(m_prefix + "fdStepSize",
                                       std::atof(QUESO_BASESCALARFN_FD_STEPSIZE_ODV),
                                       i);
     }
   }
   else {
     // Either the user provides nothing, a scalar, or the whole vector.
     // Any other possiblities are not allowed so we error in this case.
     queso_error_msg("Finite difference vector must be a scalar or a vector of length parameter dimension");
   }
 #endif
 
   // Check all the elements of the finite difference vector are positive
   for (unsigned int i = 0; i < dim; i++) {
     queso_require_greater_msg(m_fdStepSize[i],
                               0.0,
                               "Finite difference step sizes must be positive");
   }
 }

template<class V , class M >

QUESO::BaseScalarFunction< V, M >::~BaseScalarFunction ( )

virtual

Destructor.

Definition at line 116 of file ScalarFunction.C.

117 {

118 }

Member Function Documentation

template<class V = GslVector, class M = GslMatrix>

virtual double QUESO::BaseScalarFunction< V, M >::actualValue	(	const V &	domainVector,
		const V *	domainDirection,
		V *	gradVector,
		M *	hessianMatrix,
		V *	hessianEffect
	)		const

pure virtual

Actual value of the scalar function.

template<class V , class M >

const VectorSet< V, M > & QUESO::BaseScalarFunction< V, M >::domainSet ( ) const

Access to the protected attribute m_domainSet: domain set of the scalar function.

Definition at line 122 of file ScalarFunction.C.

Referenced by QUESO::StatisticalInverseProblem< P_V, P_M >::StatisticalInverseProblem().

 {
   return m_domainSet;
 }

template<class V, class M>

double QUESO::BaseScalarFunction< V, M >::lnValue	(	const V &	domainVector,
		const V *	domainDirection,
		V *	gradVector,
		M *	hessianMatrix,
		V *	hessianEffect
	)		const

virtual

Logarithm of the value of the scalar function. Deprecated.

Pointers will be NULL if derivative information is not required by QUESO.

Default implementation throws an exception.

Definition at line 129 of file ScalarFunction.C.

Referenced by QUESO::LikelihoodBase< V, M >::actualValue().

 {
   std::string msg;
 
   msg += "Implementation of all lnValue methods is missing.  Please implement";
   msg += " at least lnValue(const V &).";
 
   queso_error_msg(msg);
 }

template<class V, class M>

double QUESO::BaseScalarFunction< V, M >::lnValue ( const V & domainVector ) const

virtual

Returns the logarithm of the function at domainVector.

Default implementation calls the deprecated method.

QUESO calls this method when it needs to evaluate the function but doesn't need derivative information about that function.

Reimplemented in QUESO::GaussianLikelihoodBlockDiagonalCovarianceRandomCoefficients< V, M >, QUESO::BayesianJointPdf< V, M >, QUESO::GaussianLikelihoodBlockDiagonalCovariance< V, M >, QUESO::GaussianLikelihoodFullCovarianceRandomCoefficient< V, M >, QUESO::GaussianLikelihoodFullCovariance< V, M >, QUESO::GaussianLikelihoodDiagonalCovariance< V, M >, and QUESO::GaussianLikelihoodScalarCovariance< V, M >.

Definition at line 145 of file ScalarFunction.C.

 {
   return this->lnValue(domainVector, NULL, NULL, NULL, NULL);
 }

template<class V, class M>

double QUESO::BaseScalarFunction< V, M >::lnValue	(	const V &	domainVector,
		V &	gradVector
	)		const

virtual

Returns the logarithm of the function and its gradient at domainVector.

Default implementation calls above method successively to fill up gradVector with a finite difference approximation.

Note, gradVector should be filled with the gradient of the logarithm of the function, not the gradient of the function.

QUESO calls this method when it needs to evaluate the function, needs first order derivative information, but doesn't need second order derivative information.

Reimplemented in QUESO::BayesianJointPdf< V, M >.

Definition at line 152 of file ScalarFunction.C.

 {
   double value = this->lnValue(domainVector);
 
   // Create perturbed version of domainVector to use in finite difference
   V perturbedVector(domainVector);
 
   // Fill up gradVector with a finite difference approximation
   for (unsigned int i = 0; i < domainVector.sizeLocal(); ++i) {
     // Store the old value of the perturbed element so we can undo it later
     double tmp = perturbedVector[i];
 
     perturbedVector[i] += m_fdStepSize[i];
     gradVector[i] = (this->lnValue(perturbedVector) - value) / m_fdStepSize[i];
 
     // Restore the old value of the perturbedVector element
     perturbedVector[i] = tmp;
   }
 
   return value;
 }

template<class V, class M>

double QUESO::BaseScalarFunction< V, M >::lnValue	(	const V &	domainVector,
		V &	gradVector,
		const V &	domainDirection,
		V &	hessianEffect
	)		const

virtual

Returns the logarithm of the function domainVector, the gradient of the logarithm at domainVector, and the effect of the hessian of the logarithm in the direction at domainDirection

Default implementation throws an exception because we don't expect the user to tolerate a finite difference approximation of the hessian.

Note, gradVector should be filled with the gradient of the logarithm of the function, not the gradient of the function.

The 'hessian' referred to here should be the hessian of the logarithm of the function at domainVector.

QUESO calls this method when it needs to evaluate the function, needs first order derivative information, and also needs second-order deriative information

Definition at line 176 of file ScalarFunction.C.

 {
   std::string msg;
 
   msg += "QUESO asked for Hessian information from an lnValue method, but the";
   msg += " implementation of is missing.  Please implement";
   msg += " lnValue(const V &, V &, const V &, V &).";
 
   queso_error_msg(msg);
 }

template<class V , class M >

void QUESO::BaseScalarFunction< V, M >::setFiniteDifferenceStepSize ( double fdStepSize )

Sets the step size for finite differencing gradients.

If the function is multi-dimensional then the same finite difference step size is used in every direction.

Definition at line 192 of file ScalarFunction.C.

 {
   queso_require_greater_msg(fdStepSize, 0.0,
                             "Must provide a finite difference step > 0");
 
   for (unsigned int i = 0; i < this->m_fdStepSize.size(); i++) {
     this->m_fdStepSize[i] = fdStepSize;
   }
 }

template<class V , class M >

void QUESO::BaseScalarFunction< V, M >::setFiniteDifferenceStepSize	(	unsigned int	i,
		double	fdStepSize
	)

Sets the step size for the i-th component of the finite differencing vector

i is a zero-based index.

If the function is one-dimensional, the only allowed value for i is 0.

Definition at line 204 of file ScalarFunction.C.

References QUESO::size.

 {
   queso_require_greater_msg(fdStepSize, 0.0,
                             "Must provide a finite difference step > 0");
 
   queso_require_greater_equal_msg(i, 0, "Must provide a nonnegative index");
 
   unsigned int size = this->m_fdStepSize.size();
   queso_require_less_msg(i, size, "Must provide an index less than size of parameter dimension");
 
   this->m_fdStepSize[i] = fdStepSize;
 }