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 47 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 84 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 97 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 73 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 105 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 117 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 126 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 137 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 149 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 172 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 193 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 237 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 246 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 255 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 49 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 51 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 52 of file ROL_KLDivergence.hpp.

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

◆ hval_

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

Definition at line 53 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 54 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 55 of file ROL_KLDivergence.hpp.

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

◆ firstResetKLD_

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

Definition at line 57 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.15.0