ROL
Public Member Functions | Private Member Functions | Private Attributes | List of all members
ROL::KLDivergence< Real > Class Template Reference
Algorithmic Extensions » Stochastic Optimization » Risk Measures

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.
 KLDivergence (ROL::ParameterList &parlist)
 Constructor.
void initialize (const Vector< Real > &x)
void updateValue (Objective< Real > &obj, const Vector< Real > &x, const std::vector< Real > &xstat, Real &tol)
Real getValue (const Vector< Real > &x, const std::vector< Real > &xstat, SampleGenerator< Real > &sampler)
void updateGradient (Objective< Real > &obj, const Vector< Real > &x, const std::vector< Real > &xstat, Real &tol)
void getGradient (Vector< Real > &g, std::vector< Real > &gstat, const Vector< Real > &x, const std::vector< Real > &xstat, SampleGenerator< Real > &sampler)
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)
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)

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_

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 81 of file ROL_KLDivergence.hpp.

Constructor & Destructor Documentation

◆ KLDivergence() [1/2]

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

Constructor.

Parameters
[in]epsis the tolerance for the KL divergence constraint

Definition at line 118 of file ROL_KLDivergence.hpp.

References checkInputs(), eps_, and firstResetKLD_.

◆ KLDivergence() [2/2]

template<class Real>
ROL::KLDivergence< Real >::KLDivergence ( ROL::ParameterList & parlist)
inline

Constructor.

Parameters
[in]parlistis 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 131 of file ROL_KLDivergence.hpp.

References checkInputs(), eps_, and firstResetKLD_.

Member Function Documentation

◆ checkInputs()

template<class Real>
void ROL::KLDivergence< Real >::checkInputs ( void ) const
inlineprivate

Definition at line 107 of file ROL_KLDivergence.hpp.

References eps_, and zero.

Referenced by KLDivergence(), and KLDivergence().

◆ initialize()

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

Definition at line 139 of file ROL_KLDivergence.hpp.

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

◆ updateValue()

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

Definition at line 151 of file ROL_KLDivergence.hpp.

References eps_, and exponential().

◆ getValue()

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

Definition at line 160 of file ROL_KLDivergence.hpp.

References eps_, ROL::ROL_INF(), and ROL::SampleGenerator< Real >::sumAll().

◆ updateGradient()

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

Definition at line 171 of file ROL_KLDivergence.hpp.

References eps_, exponential(), and gval_.

◆ getGradient()

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 )
inline

Definition at line 183 of file ROL_KLDivergence.hpp.

References eps_, gval_, ROL::ROL_INF(), ROL::Vector< Real >::scale(), and ROL::SampleGenerator< Real >::sumAll().

◆ updateHessVec()

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 )
inline

Definition at line 206 of file ROL_KLDivergence.hpp.

References eps_, exponential(), gval_, gvval_, hval_, scaledGradient_, and scaledHessVec_.

◆ getHessVec()

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 )
inline

Definition at line 227 of file ROL_KLDivergence.hpp.

References ROL::Vector< Real >::axpy(), eps_, gval_, gvval_, hval_, ROL::ROL_INF(), ROL::Vector< Real >::scale(), scaledGradient_, scaledHessVec_, and ROL::SampleGenerator< Real >::sumAll().

◆ exponential() [1/2]

template<class Real>
Real ROL::KLDivergence< Real >::exponential ( const Real arg1,
const Real arg2 ) const
inlineprivate

Definition at line 271 of file ROL_KLDivergence.hpp.

References exponential(), and power().

Referenced by exponential(), updateGradient(), updateHessVec(), and updateValue().

◆ exponential() [2/2]

template<class Real>
Real ROL::KLDivergence< Real >::exponential ( const Real arg) const
inlineprivate

Definition at line 280 of file ROL_KLDivergence.hpp.

References ROL::ROL_INF().

◆ power()

template<class Real>
Real ROL::KLDivergence< Real >::power ( const Real arg,
const Real pow ) const
inlineprivate

Definition at line 289 of file ROL_KLDivergence.hpp.

References ROL::ROL_INF().

Referenced by exponential().

Member Data Documentation

◆ eps_

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

Definition at line 83 of file ROL_KLDivergence.hpp.

Referenced by checkInputs(), getGradient(), getHessVec(), getValue(), KLDivergence(), KLDivergence(), updateGradient(), updateHessVec(), and updateValue().

◆ gval_

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

Definition at line 85 of file ROL_KLDivergence.hpp.

Referenced by getGradient(), getHessVec(), initialize(), updateGradient(), and updateHessVec().

◆ gvval_

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

Definition at line 86 of file ROL_KLDivergence.hpp.

Referenced by getHessVec(), initialize(), and updateHessVec().

◆ hval_

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

Definition at line 87 of file ROL_KLDivergence.hpp.

Referenced by getHessVec(), initialize(), and updateHessVec().

◆ scaledGradient_

template<class Real>
ROL::Ptr<Vector<Real> > ROL::KLDivergence< Real >::scaledGradient_
private

Definition at line 88 of file ROL_KLDivergence.hpp.

Referenced by getHessVec(), initialize(), and updateHessVec().

◆ scaledHessVec_

template<class Real>
ROL::Ptr<Vector<Real> > ROL::KLDivergence< Real >::scaledHessVec_
private

Definition at line 89 of file ROL_KLDivergence.hpp.

Referenced by getHessVec(), initialize(), and updateHessVec().

◆ firstResetKLD_

template<class Real>
bool ROL::KLDivergence< Real >::firstResetKLD_
private

Definition at line 91 of file ROL_KLDivergence.hpp.

Referenced by initialize(), KLDivergence(), and KLDivergence().

The documentation for this class was generated from the following file:
Generated by doxygen 1.17.0