ROL
Public Member Functions | Private Member Functions | Private Attributes | List of all members
ROL::KLDivergence< Real > Class Template Reference

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 (Teuchos::ParameterList &parlist)
 Constructor. More...
 
void reset (Teuchos::RCP< Vector< Real > > &x0, const Vector< Real > &x)
 Reset internal risk measure storage. Called for value and gradient computation. More...
 
void reset (Teuchos::RCP< Vector< Real > > &x0, const Vector< Real > &x, Teuchos::RCP< Vector< Real > > &v0, const Vector< Real > &v)
 Reset internal risk measure storage. Called for Hessian-times-a-vector computation. More...
 
void update (const Real val, const Real weight)
 Update internal risk measure storage for value computation. More...
 
Real getValue (SampleGenerator< Real > &sampler)
 Return risk measure value. More...
 
void update (const Real val, const Vector< Real > &g, const Real weight)
 Update internal risk measure storage for gradient computation. More...
 
void getGradient (Vector< Real > &g, SampleGenerator< Real > &sampler)
 Return risk measure (sub)gradient. More...
 
void update (const Real val, const Vector< Real > &g, const Real gv, const Vector< Real > &hv, const Real weight)
 Update internal risk measure storage for Hessian-time-a-vector computation. More...
 
void getHessVec (Vector< Real > &hv, SampleGenerator< Real > &sampler)
 Return risk measure Hessian-times-a-vector. More...
 
- Public Member Functions inherited from ROL::RiskMeasure< Real >
virtual ~RiskMeasure ()
 
 RiskMeasure (void)
 

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_
 
Teuchos::RCP< Vector< Real > > scaledGradient_
 
Teuchos::RCP< Vector< Real > > scaledHessVec_
 
Teuchos::RCP< Vector< Real > > dualVector1_
 
Teuchos::RCP< Vector< Real > > dualVector2_
 
Real xstat_
 
Real vstat_
 
bool firstReset_
 

Additional Inherited Members

- Protected Attributes inherited from ROL::RiskMeasure< Real >
Real val_
 
Real gv_
 
Teuchos::RCP< Vector< Real > > g_
 
Teuchos::RCP< Vector< Real > > hv_
 
Teuchos::RCP< Vector< Real > > dualVector_
 
bool firstReset_
 

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

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

◆ KLDivergence() [2/2]

template<class Real >
ROL::KLDivergence< Real >::KLDivergence ( Teuchos::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 122 of file ROL_KLDivergence.hpp.

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

Member Function Documentation

◆ checkInputs()

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

◆ reset() [1/2]

template<class Real >
void ROL::KLDivergence< Real >::reset ( Teuchos::RCP< Vector< Real > > &  x0,
const Vector< Real > &  x 
)
inlinevirtual

Reset internal risk measure storage. Called for value and gradient computation.

Parameters
[out]x0is a user-provided optimization vector
[in]xis a (potentially) augmented risk vector
   On input, \form#56 carries \form#323 and any statistics (scalars)
   associated with the risk measure. 

Reimplemented from ROL::RiskMeasure< Real >.

Definition at line 130 of file ROL_KLDivergence.hpp.

References ROL::KLDivergence< Real >::dualVector1_, ROL::KLDivergence< Real >::dualVector2_, ROL::KLDivergence< Real >::firstReset_, ROL::KLDivergence< Real >::gval_, ROL::KLDivergence< Real >::gvval_, ROL::KLDivergence< Real >::hval_, ROL::RiskMeasure< Real >::reset(), ROL::KLDivergence< Real >::scaledGradient_, ROL::KLDivergence< Real >::scaledHessVec_, and ROL::KLDivergence< Real >::xstat_.

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

◆ reset() [2/2]

template<class Real >
void ROL::KLDivergence< Real >::reset ( Teuchos::RCP< Vector< Real > > &  x0,
const Vector< Real > &  x,
Teuchos::RCP< Vector< Real > > &  v0,
const Vector< Real > &  v 
)
inlinevirtual

Reset internal risk measure storage. Called for Hessian-times-a-vector computation.

Parameters
[out]x0is a user-provided optimization vector
[in]xis a (potentially) augmented risk vector
[out]v0is a user-provided direction vector
[in]vis a (potentially) augmented risk vector
   On input, \form#56 carries \form#323 and any statistics (scalars)
   associated with the risk measure.  Similarly, \form#37 carries
\(v_0\) and any statistics (scalars) associated with the risk measure.

Reimplemented from ROL::RiskMeasure< Real >.

Definition at line 146 of file ROL_KLDivergence.hpp.

References ROL::KLDivergence< Real >::reset(), and ROL::KLDivergence< Real >::vstat_.

◆ update() [1/3]

template<class Real >
void ROL::KLDivergence< Real >::update ( const Real  val,
const Real  weight 
)
inlinevirtual

Update internal risk measure storage for value computation.

Parameters
[in]valis the value of the random variable objective function at the current sample point
[in]weightis the weight associated with the current sample point

Reimplemented from ROL::RiskMeasure< Real >.

Definition at line 153 of file ROL_KLDivergence.hpp.

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

◆ getValue()

template<class Real >
Real ROL::KLDivergence< Real >::getValue ( SampleGenerator< Real > &  sampler)
inlinevirtual

Return risk measure value.

Parameters
[in]sampleris 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::RiskMeasure< Real >.

Definition at line 158 of file ROL_KLDivergence.hpp.

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

◆ update() [2/3]

template<class Real >
void ROL::KLDivergence< Real >::update ( const Real  val,
const Vector< Real > &  g,
const Real  weight 
)
inlinevirtual

Update internal risk measure storage for gradient computation.

Parameters
[in]valis the value of the random variable objective function at the current sample point
[in]gis the gradient of the random variable objective function at the current sample point
[in]weightis the weight associated with the current sample point

Reimplemented from ROL::RiskMeasure< Real >.

Definition at line 167 of file ROL_KLDivergence.hpp.

References ROL::KLDivergence< Real >::eps_, ROL::KLDivergence< Real >::exponential(), ROL::KLDivergence< Real >::gval_, and ROL::KLDivergence< Real >::xstat_.

◆ getGradient()

template<class Real >
void ROL::KLDivergence< Real >::getGradient ( Vector< Real > &  g,
SampleGenerator< Real > &  sampler 
)
inlinevirtual

Return risk measure (sub)gradient.

Parameters
[out]gis the (sub)gradient of the risk measure
[in]sampleris 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::RiskMeasure< Real >.

Definition at line 174 of file ROL_KLDivergence.hpp.

References ROL::KLDivergence< Real >::dualVector1_, ROL::KLDivergence< Real >::eps_, ROL::KLDivergence< Real >::gval_, ROL::SampleGenerator< Real >::sumAll(), and ROL::KLDivergence< Real >::xstat_.

◆ update() [3/3]

template<class Real >
void ROL::KLDivergence< Real >::update ( const Real  val,
const Vector< Real > &  g,
const Real  gv,
const Vector< Real > &  hv,
const Real  weight 
)
inlinevirtual

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

Parameters
[in]valis the value of the random variable objective function at the current sample point
[in]gis the gradient of the random variable objective function at the current sample point
[in]gvis the gradient of the random variable objective function at the current sample point applied to the vector v0
[in]hvis the Hessian of the random variable objective function at the current sample point applied to the vector v0
[in]weightis the weight associated with the current sample point

Reimplemented from ROL::RiskMeasure< Real >.

Definition at line 196 of file ROL_KLDivergence.hpp.

References ROL::KLDivergence< Real >::eps_, ROL::KLDivergence< Real >::exponential(), ROL::KLDivergence< Real >::gval_, ROL::KLDivergence< Real >::gvval_, ROL::KLDivergence< Real >::hval_, ROL::KLDivergence< Real >::scaledGradient_, ROL::KLDivergence< Real >::scaledHessVec_, and ROL::KLDivergence< Real >::xstat_.

◆ getHessVec()

template<class Real >
void ROL::KLDivergence< Real >::getHessVec ( Vector< Real > &  hv,
SampleGenerator< Real > &  sampler 
)
inlinevirtual

Return risk measure Hessian-times-a-vector.

Parameters
[out]hvis the Hessian-times-a-vector of the risk measure
[in]sampleris 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::RiskMeasure< Real >.

Definition at line 210 of file ROL_KLDivergence.hpp.

References ROL::KLDivergence< Real >::dualVector1_, ROL::KLDivergence< Real >::dualVector2_, ROL::KLDivergence< Real >::eps_, ROL::KLDivergence< Real >::gval_, ROL::KLDivergence< Real >::gvval_, ROL::KLDivergence< Real >::hval_, ROL::KLDivergence< Real >::scaledGradient_, ROL::KLDivergence< Real >::scaledHessVec_, ROL::SampleGenerator< Real >::sumAll(), ROL::KLDivergence< Real >::vstat_, and ROL::KLDivergence< Real >::xstat_.

◆ exponential() [1/2]

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

◆ exponential() [2/2]

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

Definition at line 261 of file ROL_KLDivergence.hpp.

◆ power()

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

Definition at line 270 of file ROL_KLDivergence.hpp.

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

Member Data Documentation

◆ eps_

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

◆ gval_

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

◆ gvval_

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

◆ hval_

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

◆ scaledGradient_

template<class Real >
Teuchos::RCP<Vector<Real> > ROL::KLDivergence< Real >::scaledGradient_
private

◆ scaledHessVec_

template<class Real >
Teuchos::RCP<Vector<Real> > ROL::KLDivergence< Real >::scaledHessVec_
private

◆ dualVector1_

template<class Real >
Teuchos::RCP<Vector<Real> > ROL::KLDivergence< Real >::dualVector1_
private

◆ dualVector2_

template<class Real >
Teuchos::RCP<Vector<Real> > ROL::KLDivergence< Real >::dualVector2_
private

◆ xstat_

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

◆ vstat_

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

◆ firstReset_

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

Definition at line 96 of file ROL_KLDivergence.hpp.

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


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