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

Provides a general interface for the F-divergence distributionally robust expectation. More...

#include <ROL_FDivergence.hpp>

Inheritance diagram for ROL::FDivergence< Real >:

Public Member Functions

 FDivergence (const Real thresh)
 Constructor.
 FDivergence (ROL::ParameterList &parlist)
 Constructor.
virtual Real Fprimal (Real x, int deriv=0) const =0
 Implementation of the scalar primal F function.
virtual Real Fdual (Real x, int deriv=0) const =0
 Implementation of the scalar dual F function.
bool check (std::ostream &outStream=std::cout) const
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

Private Attributes

Real thresh_
Real valLam_
Real valLam2_
Real valMu_
Real valMu2_

Detailed Description

template<class Real>
class ROL::FDivergence< Real >

Provides a general interface for the F-divergence 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 F-divergence, i.e.,

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

where \(F:\mathbb{R}\to[0,\infty]\) convex, lower semicontinuous and satisfies \(F(1) = 1\) and \(F(x) = \infty\) for \(x < 0\). \(\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,\,\mu}\left\{ \lambda \epsilon + \mu + \mathbb{E}\left[ (\lambda F)^*(X-\mu)\right]\right\}. \]

Here, \((\lambda F)^*\) denotes the Legendre-Fenchel transformation of \((\lambda F)\). ROL implements this by augmenting the optimization vector \(x_0\) with the parameter \((\lambda,\mu)\), then minimizes jointly for \((x_0,\lambda,\mu)\).

Definition at line 53 of file ROL_FDivergence.hpp.

Constructor & Destructor Documentation

◆ FDivergence() [1/2]

template<class Real>
ROL::FDivergence< Real >::FDivergence ( const Real thresh)
inline

Constructor.

Parameters
[in]epsis the tolerance for the F-divergence constraint

Definition at line 87 of file ROL_FDivergence.hpp.

References checkInputs(), thresh_, valLam2_, valLam_, valMu2_, and valMu_.

Referenced by ROL::Chi2Divergence< Real >::Chi2Divergence(), and ROL::Chi2Divergence< Real >::Chi2Divergence().

◆ FDivergence() [2/2]

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

Constructor.

Parameters
[in]parlistis a parameter list specifying inputs

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

  • "Threshold" (greater than 0)

Definition at line 100 of file ROL_FDivergence.hpp.

References checkInputs(), thresh_, valLam2_, valLam_, valMu2_, and valMu_.

Member Function Documentation

◆ checkInputs()

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

Definition at line 76 of file ROL_FDivergence.hpp.

References thresh_, and zero.

Referenced by FDivergence(), and FDivergence().

◆ Fprimal()

template<class Real>
virtual Real ROL::FDivergence< Real >::Fprimal ( Real x,
int deriv = 0 ) const
pure virtual

Implementation of the scalar primal F function.

Parameters
[in]xis a scalar input
[in]derivis the derivative order

Upon return, Fprimal returns \(F(x)\) or a derivative of \(F(x)\).

Implemented in ROL::Chi2Divergence< Real >.

Referenced by check().

◆ Fdual()

template<class Real>
virtual Real ROL::FDivergence< Real >::Fdual ( Real x,
int deriv = 0 ) const
pure virtual

Implementation of the scalar dual F function.

Parameters
[in]xis a scalar input
[in]derivis the derivative order

Upon return, Fdual returns \(F^*(x)\) or a derivative of \(F^*(x)\). Here, \(F^*\) denotes the Legendre-Fenchel transformation of \(F\), i.e.,

\[ F^*(y) = \sup_{x\in\mathbb{R}}\{xy - F(x)\}. \]

Implemented in ROL::Chi2Divergence< Real >.

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

◆ check()

template<class Real>
bool ROL::FDivergence< Real >::check ( std::ostream & outStream = std::cout) const
inline

Definition at line 131 of file ROL_FDivergence.hpp.

References Fdual(), Fprimal(), and ROL::ROL_EPSILON().

◆ initialize()

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

Definition at line 174 of file ROL_FDivergence.hpp.

References valLam2_, valLam_, valMu2_, and valMu_.

◆ updateValue()

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

Definition at line 180 of file ROL_FDivergence.hpp.

References Fdual().

◆ getValue()

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

Definition at line 191 of file ROL_FDivergence.hpp.

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

◆ updateGradient()

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

Definition at line 202 of file ROL_FDivergence.hpp.

References Fdual(), ROL::ROL_EPSILON(), valLam_, and valMu_.

◆ getGradient()

template<class Real>
void ROL::FDivergence< 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 223 of file ROL_FDivergence.hpp.

References ROL::SampleGenerator< Real >::sumAll(), thresh_, valLam_, and valMu_.

◆ updateHessVec()

template<class Real>
void ROL::FDivergence< 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 240 of file ROL_FDivergence.hpp.

References Fdual(), ROL::ROL_EPSILON(), valLam2_, valLam_, valMu2_, and valMu_.

◆ getHessVec()

template<class Real>
void ROL::FDivergence< 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 268 of file ROL_FDivergence.hpp.

References ROL::SampleGenerator< Real >::sumAll(), valLam2_, valLam_, valMu2_, and valMu_.

Member Data Documentation

◆ thresh_

template<class Real>
Real ROL::FDivergence< Real >::thresh_
private

Definition at line 55 of file ROL_FDivergence.hpp.

Referenced by checkInputs(), FDivergence(), FDivergence(), getGradient(), and getValue().

◆ valLam_

template<class Real>
Real ROL::FDivergence< Real >::valLam_
private

Definition at line 57 of file ROL_FDivergence.hpp.

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

◆ valLam2_

template<class Real>
Real ROL::FDivergence< Real >::valLam2_
private

Definition at line 58 of file ROL_FDivergence.hpp.

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

◆ valMu_

template<class Real>
Real ROL::FDivergence< Real >::valMu_
private

Definition at line 59 of file ROL_FDivergence.hpp.

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

◆ valMu2_

template<class Real>
Real ROL::FDivergence< Real >::valMu2_
private

Definition at line 60 of file ROL_FDivergence.hpp.

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

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