Provides an interface for the Kullback-Leibler distributionally robust expectation. More...

#include <ROL_KLDivergence.hpp>

Inheritance diagram for ROL::KLDivergence< Real >:

Public Member Functions
	KLDivergence (const Real eps=1.e-2)
	Constructor. More...

	KLDivergence (ROL::ParameterList &parlist)
	Constructor. More...

void	initialize (const Vector< Real > &x)
	Initialize temporary variables. More...

void	updateValue (Objective< Real > &obj, const Vector< Real > &x, const std::vector< Real > &xstat, Real &tol)
	Update internal storage for value computation. More...

Real	getValue (const Vector< Real > &x, const std::vector< Real > &xstat, SampleGenerator< Real > &sampler)
	Return risk measure value. More...

void	updateGradient (Objective< Real > &obj, const Vector< Real > &x, const std::vector< Real > &xstat, Real &tol)
	Update internal risk measure storage for gradient computation. More...

void	getGradient (Vector< Real > &g, std::vector< Real > &gstat, const Vector< Real > &x, const std::vector< Real > &xstat, SampleGenerator< Real > &sampler)
	Return risk measure (sub)gradient. More...

void	updateHessVec (Objective< Real > &obj, const Vector< Real > &v, const std::vector< Real > &vstat, const Vector< Real > &x, const std::vector< Real > &xstat, Real &tol)
	Update internal risk measure storage for Hessian-time-a-vector computation. More...

void	getHessVec (Vector< Real > &hv, std::vector< Real > &hvstat, const Vector< Real > &v, const std::vector< Real > &vstat, const Vector< Real > &x, const std::vector< Real > &xstat, SampleGenerator< Real > &sampler)
	Return risk measure Hessian-times-a-vector. More...

Public Member Functions inherited from ROL::RandVarFunctional< Real >
virtual	~RandVarFunctional ()

	RandVarFunctional (void)

	weight_ (0)

void	useStorage (bool storage)

void	useHessVecStorage (bool storage)

virtual void	setStorage (const Ptr< ScalarController< Real >> &value_storage, const Ptr< VectorController< Real >> &gradient_storage)

virtual void	setHessVecStorage (const Ptr< ScalarController< Real >> &gradvec_storage, const Ptr< VectorController< Real >> &hessvec_storage)

virtual void	resetStorage (bool flag=true)
	Reset internal storage. More...

virtual void	resetStorage (UpdateType type)

virtual void	setSample (const std::vector< Real > &point, const Real weight)

virtual Real	computeStatistic (const Ptr< const std::vector< Real >> &xstat) const
	Compute statistic. More...

Private Member Functions
void	checkInputs (void) const

Real	exponential (const Real arg1, const Real arg2) const

Real	exponential (const Real arg) const

Real	power (const Real arg, const Real pow) const

Private Attributes
Real	eps_

Real	gval_

Real	gvval_

Real	hval_

ROL::Ptr< Vector< Real > >	scaledGradient_

ROL::Ptr< Vector< Real > >	scaledHessVec_

bool	firstResetKLD_

Additional Inherited Members
Protected Member Functions inherited from ROL::RandVarFunctional< Real >
Real	computeValue (Objective< Real > &obj, const Vector< Real > &x, Real &tol)

void	computeGradient (Vector< Real > &g, Objective< Real > &obj, const Vector< Real > &x, Real &tol)

Real	computeGradVec (Vector< Real > &g, Objective< Real > &obj, const Vector< Real > &v, const Vector< Real > &x, Real &tol)

void	computeHessVec (Vector< Real > &hv, Objective< Real > &obj, const Vector< Real > &v, const Vector< Real > &x, Real &tol)

Protected Attributes inherited from ROL::RandVarFunctional< Real >
Real	val_

Real	gv_

Ptr< Vector< Real > >	g_

Ptr< Vector< Real > >	hv_

Ptr< Vector< Real > >	dualVector_

bool	firstReset_

std::vector< Real >	point_

Real	weight_

Detailed Description

template<class Real>
class ROL::KLDivergence< Real >

Provides an interface for the Kullback-Leibler distributionally robust expectation.

This class defines a risk measure \(\mathcal{R}\) which arises in distributionally robust stochastic programming. \(\mathcal{R}\) is given by

\[ \mathcal{R}(X) = \sup_{\vartheta\in\mathfrak{A}} \mathbb{E}[\vartheta X] \]

where \(\mathfrak{A}\) is called the ambiguity (or uncertainty) set and is defined by a constraint on the Kullback-Leibler divergence, i.e.,

\[ \mathfrak{A} = \{\vartheta\in\mathcal{X}^*\,:\, \mathbb{E}[\vartheta] = 1,\; \vartheta \ge 0,\;\text{and}\; \mathbb{E}[\vartheta\log(\vartheta)] \le \epsilon\}. \]

\(\mathcal{R}\) is a law-invariant, coherent risk measure. Moreover, by a duality argument, \(\mathcal{R}\) can be reformulated as

\[ \mathcal{R}(X) = \inf_{\lambda > 0}\left\{ \lambda \epsilon + \lambda\mathbb{E}\left[\exp\left( \frac{X}{\lambda}\right)\right]\right\}. \]

ROL implements this by augmenting the optimization vector \(x_0\) with the parameter \(\lambda\), then minimizes jointly for \((x_0,\lambda)\).

Definition at line 47 of file ROL_KLDivergence.hpp.

Constructor & Destructor Documentation

template<class Real >

ROL::KLDivergence< Real >::KLDivergence ( const Real eps = 1.e-2 )

inline

Constructor.

Parameters

[in] eps is the tolerance for the KL divergence constraint

Definition at line 84 of file ROL_KLDivergence.hpp.

References ROL::KLDivergence< Real >::checkInputs().

template<class Real >

ROL::KLDivergence< Real >::KLDivergence ( ROL::ParameterList & parlist )

inline

Constructor.

Parameters

[in] parlist is a parameter list specifying inputs

parlist should contain sublists "SOL"->"Risk Measure"->"KL Divergence" and within the "KL Divergence" sublist should have the following parameters

"Threshold" (greater than 0)

Definition at line 97 of file ROL_KLDivergence.hpp.

References ROL::KLDivergence< Real >::checkInputs(), and ROL::KLDivergence< Real >::eps_.

Member Function Documentation

template<class Real >

void ROL::KLDivergence< Real >::checkInputs ( void ) const

inlineprivate

Definition at line 73 of file ROL_KLDivergence.hpp.

References ROL::KLDivergence< Real >::eps_, and zero.

Referenced by ROL::KLDivergence< Real >::KLDivergence().

template<class Real >

void ROL::KLDivergence< Real >::initialize ( const Vector< Real > & x )

inlinevirtual

Initialize temporary variables.

Parameters

[in] x is a vector used for initializing storage

Reimplemented from ROL::RandVarFunctional< Real >.

Definition at line 105 of file ROL_KLDivergence.hpp.

References ROL::Vector< Real >::dual(), ROL::KLDivergence< Real >::firstResetKLD_, ROL::KLDivergence< Real >::gval_, ROL::KLDivergence< Real >::gvval_, ROL::KLDivergence< Real >::hval_, ROL::RandVarFunctional< Real >::initialize(), ROL::KLDivergence< Real >::scaledGradient_, ROL::KLDivergence< Real >::scaledHessVec_, and zero.

template<class Real >

void ROL::KLDivergence< Real >::updateValue	(	Objective< Real > &	obj,
		const Vector< Real > &	x,
		const std::vector< Real > &	xstat,
		Real &	tol
	)

inlinevirtual

Update internal storage for value computation.

Parameters

[in]	val	is the value of the random variable objective function at the current sample point
[in]	weight	is the weight associated with the current sample point

Reimplemented from ROL::RandVarFunctional< Real >.

Definition at line 117 of file ROL_KLDivergence.hpp.

References ROL::RandVarFunctional< Real >::computeValue(), ROL::KLDivergence< Real >::eps_, ROL::KLDivergence< Real >::exponential(), ROL::RandVarFunctional< Real >::val_, and ROL::RandVarFunctional< Real >::weight_.

template<class Real >

Real ROL::KLDivergence< Real >::getValue	(	const Vector< Real > &	x,
		const std::vector< Real > &	xstat,
		SampleGenerator< Real > &	sampler
	)

inlinevirtual

Return risk measure value.

Parameters

[in] sampler is the ROL::SampleGenerator used to sample the objective function

Upon return, getValue returns \(\mathcal{R}(f(x_0))\) where \(f(x_0)\) denotes the random variable objective function evaluated at \(x_0\).

Reimplemented from ROL::RandVarFunctional< Real >.

Definition at line 126 of file ROL_KLDivergence.hpp.

References ROL::KLDivergence< Real >::eps_, ROL::SampleGenerator< Real >::sumAll(), and ROL::RandVarFunctional< Real >::val_.

template<class Real >

void ROL::KLDivergence< Real >::updateGradient	(	Objective< Real > &	obj,
		const Vector< Real > &	x,
		const std::vector< Real > &	xstat,
		Real &	tol
	)

inlinevirtual

Update internal risk measure storage for gradient computation.

Parameters

[in]	val	is the value of the random variable objective function at the current sample point
[in]	g	is the gradient of the random variable objective function at the current sample point
[in]	weight	is the weight associated with the current sample point

Reimplemented from ROL::RandVarFunctional< Real >.

Definition at line 137 of file ROL_KLDivergence.hpp.

References ROL::RandVarFunctional< Real >::computeGradient(), ROL::RandVarFunctional< Real >::computeValue(), ROL::RandVarFunctional< Real >::dualVector_, ROL::KLDivergence< Real >::eps_, ROL::KLDivergence< Real >::exponential(), ROL::RandVarFunctional< Real >::g_, ROL::KLDivergence< Real >::gval_, ROL::RandVarFunctional< Real >::val_, and ROL::RandVarFunctional< Real >::weight_.

template<class Real >

void ROL::KLDivergence< Real >::getGradient	(	Vector< Real > &	g,
		std::vector< Real > &	gstat,
		const Vector< Real > &	x,
		const std::vector< Real > &	xstat,
		SampleGenerator< Real > &	sampler
	)

inlinevirtual

Return risk measure (sub)gradient.

Parameters

[out]	g	is the (sub)gradient of the risk measure
[in]	sampler	is the ROL::SampleGenerator used to sample the objective function

Upon return, getGradient returns \(\theta\in\partial\mathcal{R}(f(x_0))\) where \(f(x_0)\) denotes the random variable objective function evaluated at \(x_0\) and \(\partial\mathcal{R}(X)\) denotes the subdifferential of \(\mathcal{R}\) at \(X\).

Reimplemented from ROL::RandVarFunctional< Real >.

Definition at line 149 of file ROL_KLDivergence.hpp.

References ROL::KLDivergence< Real >::eps_, ROL::RandVarFunctional< Real >::g_, ROL::KLDivergence< Real >::gval_, ROL::Vector< Real >::scale(), ROL::SampleGenerator< Real >::sumAll(), and ROL::RandVarFunctional< Real >::val_.

template<class Real >

void ROL::KLDivergence< Real >::updateHessVec	(	Objective< Real > &	obj,
		const Vector< Real > &	v,
		const std::vector< Real > &	vstat,
		const Vector< Real > &	x,
		const std::vector< Real > &	xstat,
		Real &	tol
	)

inlinevirtual

Update internal risk measure storage for Hessian-time-a-vector computation.

Parameters

[in]	val	is the value of the random variable objective function at the current sample point
[in]	g	is the gradient of the random variable objective function at the current sample point
[in]	gv	is the gradient of the random variable objective function at the current sample point applied to the vector v0
[in]	hv	is the Hessian of the random variable objective function at the current sample point applied to the vector v0
[in]	weight	is the weight associated with the current sample point

Reimplemented from ROL::RandVarFunctional< Real >.

Definition at line 172 of file ROL_KLDivergence.hpp.

template<class Real >

void ROL::KLDivergence< Real >::getHessVec	(	Vector< Real > &	hv,
		std::vector< Real > &	hvstat,
		const Vector< Real > &	v,
		const std::vector< Real > &	vstat,
		const Vector< Real > &	x,
		const std::vector< Real > &	xstat,
		SampleGenerator< Real > &	sampler
	)

inlinevirtual

Return risk measure Hessian-times-a-vector.

Parameters

[out]	hv	is the Hessian-times-a-vector of the risk measure
[in]	sampler	is the ROL::SampleGenerator used to sample the objective function

Upon return, getHessVec returns \(\nabla^2 \mathcal{R}(f(x_0))v_0\) (if available) where \(f(x_0)\) denotes the random variable objective function evaluated at \(x_0\).

Reimplemented from ROL::RandVarFunctional< Real >.

Definition at line 193 of file ROL_KLDivergence.hpp.

References ROL::Vector< Real >::axpy(), ROL::RandVarFunctional< Real >::dualVector_, ROL::KLDivergence< Real >::eps_, ROL::RandVarFunctional< Real >::g_, ROL::RandVarFunctional< Real >::gv_, ROL::KLDivergence< Real >::gval_, ROL::KLDivergence< Real >::gvval_, ROL::RandVarFunctional< Real >::hv_, ROL::KLDivergence< Real >::hval_, ROL::Vector< Real >::scale(), ROL::KLDivergence< Real >::scaledGradient_, ROL::KLDivergence< Real >::scaledHessVec_, ROL::SampleGenerator< Real >::sumAll(), and ROL::RandVarFunctional< Real >::val_.