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

Provides a general interface for risk measures generated through the expectation risk quadrangle. More...

#include <ROL_ExpectationQuad.hpp>

+ Inheritance diagram for ROL::ExpectationQuad< Real >:

Public Member Functions

 ExpectationQuad (void)
 
virtual Real regret (Real x, int deriv=0)=0
 Evaluate the scalar regret function at x. More...
 
virtual void checkRegret (void)
 Run default derivative tests for the scalar regret function. 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...
 
void update (const Real val, const Vector< Real > &g, const Real weight)
 Update internal risk measure storage for gradient computation. 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...
 
Real getValue (SampleGenerator< Real > &sampler)
 Return risk measure value. More...
 
void getGradient (Vector< Real > &g, SampleGenerator< Real > &sampler)
 Return risk measure (sub)gradient. 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 Attributes

Teuchos::RCP< Vector< Real > > dualVector_
 
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::ExpectationQuad< Real >

Provides a general interface for risk measures generated through the expectation risk quadrangle.

The expectation risk quadrangle is a specialization of the general risk quadrangle that provides a rigorous connection between risk-averse optimization and statistical estimation. The risk quadrangle provides fundamental relationships between measures of risk, regret, error and deviation. An expectation risk quadrangle is defined through scalar regret and error functions. The scalar regret function, \(v:\mathbb{R}\to(-\infty,\infty]\), must be proper, closed, convex and satisfy \(v(0)=0\) and \(v(x) > x\) for all \(x\neq 0\). Similarly, the scalar error function, \(e:\mathbb{R}\to[0,\infty]\), must be proper, closed, convex and satisfy \(e(0)=0\) and \(e(x) > 0\) for all \(x\neq 0\). \(v\) and \(e\) are obtained from one another through the relations

\[ v(x) = e(x) + x \quad\text{and}\quad e(x) = v(x) - x. \]

Given \(v\) (or equivalently \(e\)), the associated risk measure is

\[ \mathcal{R}(X) = \inf_{t\in\mathbb{R}} \left\{ t + \mathbb{E}\left[v(X-t)\right] \right\}. \]

In general, \(\mathcal{R}\) is convex and translation equivariant. Moreover, \(\mathcal{R}\) is monotonic if \(v\) is increasing and \(\mathcal{R}\) is positive homogeneous if \(v\) is. ROL implements this by augmenting the optimization vector \(x_0\) with the parameter \(t\), then minimizes jointly for \((x_0,t)\).

Definition at line 89 of file ROL_ExpectationQuad.hpp.

Constructor & Destructor Documentation

◆ ExpectationQuad()

template<class Real >
ROL::ExpectationQuad< Real >::ExpectationQuad ( void  )
inline

Definition at line 100 of file ROL_ExpectationQuad.hpp.

Member Function Documentation

◆ regret()

template<class Real >
virtual Real ROL::ExpectationQuad< Real >::regret ( Real  x,
int  deriv = 0 
)
pure virtual

Evaluate the scalar regret function at x.

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

This function returns \(v(x)\) or a derivative of \(v(x)\).

Implemented in ROL::QuantileQuadrangle< Real >, ROL::MoreauYosidaCVaR< Real >, ROL::LogQuantileQuadrangle< Real >, ROL::SmoothedWorstCaseQuadrangle< Real >, ROL::LogExponentialQuadrangle< Real >, ROL::MeanVarianceQuadrangle< Real >, and ROL::TruncatedMeanQuadrangle< Real >.

Referenced by ROL::ExpectationQuad< Real >::checkRegret(), and ROL::ExpectationQuad< Real >::update().

◆ checkRegret()

template<class Real >
virtual void ROL::ExpectationQuad< Real >::checkRegret ( void  )
inlinevirtual

◆ reset() [1/2]

template<class Real >
void ROL::ExpectationQuad< 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 222 of file ROL_ExpectationQuad.hpp.

References ROL::ExpectationQuad< Real >::dualVector_, ROL::ExpectationQuad< Real >::firstReset_, ROL::RiskVector< Real >::getStatistic(), ROL::RiskMeasure< Real >::reset(), and ROL::ExpectationQuad< Real >::xstat_.

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

◆ reset() [2/2]

template<class Real >
void ROL::ExpectationQuad< 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 233 of file ROL_ExpectationQuad.hpp.

References ROL::RiskVector< Real >::getStatistic(), ROL::RiskVector< Real >::getVector(), ROL::ExpectationQuad< Real >::reset(), and ROL::ExpectationQuad< Real >::vstat_.

◆ update() [1/3]

template<class Real >
void ROL::ExpectationQuad< 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 242 of file ROL_ExpectationQuad.hpp.

References ROL::ExpectationQuad< Real >::regret(), and ROL::ExpectationQuad< Real >::xstat_.

◆ update() [2/3]

template<class Real >
void ROL::ExpectationQuad< 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 247 of file ROL_ExpectationQuad.hpp.

References ROL::ExpectationQuad< Real >::regret(), and ROL::ExpectationQuad< Real >::xstat_.

◆ update() [3/3]

template<class Real >
void ROL::ExpectationQuad< 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 253 of file ROL_ExpectationQuad.hpp.

References ROL::ExpectationQuad< Real >::regret(), ROL::ExpectationQuad< Real >::vstat_, and ROL::ExpectationQuad< Real >::xstat_.

◆ getValue()

template<class Real >
Real ROL::ExpectationQuad< 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 262 of file ROL_ExpectationQuad.hpp.

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

◆ getGradient()

template<class Real >
void ROL::ExpectationQuad< 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 269 of file ROL_ExpectationQuad.hpp.

References ROL::ExpectationQuad< Real >::dualVector_, ROL::RiskVector< Real >::setStatistic(), ROL::RiskVector< Real >::setVector(), and ROL::SampleGenerator< Real >::sumAll().

◆ getHessVec()

template<class Real >
void ROL::ExpectationQuad< 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 280 of file ROL_ExpectationQuad.hpp.

References ROL::ExpectationQuad< Real >::dualVector_, ROL::RiskVector< Real >::setStatistic(), ROL::RiskVector< Real >::setVector(), and ROL::SampleGenerator< Real >::sumAll().

Member Data Documentation

◆ dualVector_

template<class Real >
Teuchos::RCP<Vector<Real> > ROL::ExpectationQuad< Real >::dualVector_
private

◆ xstat_

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

◆ vstat_

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

◆ firstReset_

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

Definition at line 97 of file ROL_ExpectationQuad.hpp.

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


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