Provides an interface for the mean plus upper semideviation of order 1. More...

#include <ROL_MeanSemiDeviation.hpp>

Inheritance diagram for ROL::MeanSemiDeviation< Real >:

Public Member Functions
	MeanSemiDeviation (const Real coeff, const Ptr< PlusFunction< Real > > &pf)
	Constructor. More...

	MeanSemiDeviation (ROL::ParameterList &parlist)
	Constructor. More...

void	setStorage (const Ptr< ScalarController< Real >> &value_storage, const Ptr< VectorController< Real >> &gradient_storage)

void	setHessVecStorage (const Ptr< ScalarController< Real >> &gradvec_storage, const Ptr< VectorController< Real >> &hessvec_storage)

void	initialize (const Vector< Real > &x)
	Initialize temporary variables. More...

void	updateValue (Objective< Real > &obj, const Vector< Real > &x, const std::vector< Real > &xstat, Real &tol)
	Update internal storage for value computation. More...

Real	getValue (const Vector< Real > &x, const std::vector< Real > &xstat, SampleGenerator< Real > &sampler)
	Return risk measure value. More...

void	updateGradient (Objective< Real > &obj, const Vector< Real > &x, const std::vector< Real > &xstat, Real &tol)
	Update internal risk measure storage for gradient computation. More...

void	getGradient (Vector< Real > &g, std::vector< Real > &gstat, const Vector< Real > &x, const std::vector< Real > &xstat, SampleGenerator< Real > &sampler)
	Return risk measure (sub)gradient. More...

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)
	Update internal risk measure storage for Hessian-time-a-vector computation. More...

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)
	Return risk measure Hessian-times-a-vector. More...

Public Member Functions inherited from ROL::RandVarFunctional< Real >
virtual	~RandVarFunctional ()

	RandVarFunctional (void)

	weight_ (0)

void	useStorage (bool storage)

void	useHessVecStorage (bool storage)

virtual void	resetStorage (bool flag=true)
	Reset internal storage. More...

virtual void	resetStorage (UpdateType type)

virtual void	setSample (const std::vector< Real > &point, const Real weight)

virtual Real	computeStatistic (const Ptr< const std::vector< Real >> &xstat) const
	Compute statistic. More...

Private Member Functions
void	initializeStorage (void)

void	clear (void)

void	checkInputs (void)

Private Attributes
Ptr< PlusFunction< Real > >	plusFunction_

Real	coeff_

Ptr< ScalarController< Real > >	values_

Ptr< ScalarController< Real > >	gradvecs_

Ptr< VectorController< Real > >	gradients_

Ptr< VectorController< Real > >	hessvecs_

Additional Inherited Members
Protected Member Functions inherited from ROL::RandVarFunctional< Real >
Real	computeValue (Objective< Real > &obj, const Vector< Real > &x, Real &tol)

void	computeGradient (Vector< Real > &g, Objective< Real > &obj, const Vector< Real > &x, Real &tol)

Real	computeGradVec (Vector< Real > &g, Objective< Real > &obj, const Vector< Real > &v, const Vector< Real > &x, Real &tol)

void	computeHessVec (Vector< Real > &hv, Objective< Real > &obj, const Vector< Real > &v, const Vector< Real > &x, Real &tol)

Protected Attributes inherited from ROL::RandVarFunctional< Real >
Real	val_

Real	gv_

Ptr< Vector< Real > >	g_

Ptr< Vector< Real > >	hv_

Ptr< Vector< Real > >	dualVector_

bool	firstReset_

std::vector< Real >	point_

Real	weight_

Detailed Description

template<class Real>
class ROL::MeanSemiDeviation< Real >

Provides an interface for the mean plus upper semideviation of order 1.

Provides an interface for the mean plus upper semideviation from target of order 1.

The mean plus upper semideviation of order 1 with constant \(0 < c < 1\) is

\[ \mathcal{R}(X) = \mathbb{E}[X] + c \mathbb{E}\left[(X-\mathbb{E}[X])_+\right] \right\} \]

where \((x)_+ = \max\{0,x\}\). \(\mathcal{R}\) is a law-invariant coherent risk measure.

When using derivative-based optimization, the user can provide a smooth approximation of \((\cdot)_+\) using the ROL::PlusFunction class.

The mean plus upper semideviation from target of order 1 with constant \(0 < c < 1\) and target \(t\in\mathbb{R}\) is

\[ \mathcal{R}(X) = \mathbb{E}[X] + c \mathbb{E}\left[(X-t)_+\right] \right\} \]

where \((x)_+ = \max\{0,x\}\). \(\mathcal{R}\) is a law-invariant risk measure.

When using derivative-based optimization, the user can provide a smooth approximation of \((\cdot)_+\) using the ROL::PlusFunction class.

Definition at line 38 of file ROL_MeanSemiDeviation.hpp.

Constructor & Destructor Documentation

template<class Real >

ROL::MeanSemiDeviation< Real >::MeanSemiDeviation	(	const Real	coeff,
		const Ptr< PlusFunction< Real > > &	pf
	)

inline

Constructor.

Parameters

[in]	coeff	is the coefficient scaling the semideviation
[in]	pf	is the plus function or an approximation

Definition at line 93 of file ROL_MeanSemiDeviation.hpp.

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

template<class Real >

ROL::MeanSemiDeviation< Real >::MeanSemiDeviation ( ROL::ParameterList & parlist )

inline

Constructor.

Parameters

[in] parlist is a parameter list specifying inputs

parlist should contain sublists "SOL"->"Risk Measure"->"Mean Plus Semi-Deviation" and within the "Mean Plus Semi-Deviation" sublist should have the following parameters

"Coefficient" (between 0 and 1)
A sublist for plus function information.

Definition at line 107 of file ROL_MeanSemiDeviation.hpp.

References ROL::MeanSemiDeviation< Real >::checkInputs(), ROL::MeanSemiDeviation< Real >::coeff_, and ROL::MeanSemiDeviation< Real >::plusFunction_.

Member Function Documentation

template<class Real >

void ROL::MeanSemiDeviation< Real >::initializeStorage ( void )

inlineprivate

Definition at line 62 of file ROL_MeanSemiDeviation.hpp.

References ROL::MeanSemiDeviation< Real >::gradients_, ROL::MeanSemiDeviation< Real >::gradvecs_, ROL::MeanSemiDeviation< Real >::hessvecs_, ROL::RandVarFunctional< Real >::setHessVecStorage(), ROL::RandVarFunctional< Real >::setStorage(), and ROL::MeanSemiDeviation< Real >::values_.

Referenced by ROL::MeanSemiDeviation< Real >::checkInputs().

template<class Real >

void ROL::MeanSemiDeviation< Real >::clear ( void )

inlineprivate

Definition at line 72 of file ROL_MeanSemiDeviation.hpp.

References ROL::MeanSemiDeviation< Real >::gradvecs_, and ROL::MeanSemiDeviation< Real >::hessvecs_.

Referenced by ROL::MeanSemiDeviation< Real >::initialize().

template<class Real >

void ROL::MeanSemiDeviation< Real >::checkInputs ( void )

inlineprivate

Definition at line 77 of file ROL_MeanSemiDeviation.hpp.

References ROL::MeanSemiDeviation< Real >::coeff_, ROL::MeanSemiDeviation< Real >::initializeStorage(), ROL::MeanSemiDeviation< Real >::plusFunction_, and zero.

Referenced by ROL::MeanSemiDeviation< Real >::MeanSemiDeviation().

template<class Real >

void ROL::MeanSemiDeviation< Real >::setStorage	(	const Ptr< ScalarController< Real >> &	value_storage,
		const Ptr< VectorController< Real >> &	gradient_storage
	)

inlinevirtual

Reimplemented from ROL::RandVarFunctional< Real >.

Definition at line 119 of file ROL_MeanSemiDeviation.hpp.

References ROL::MeanSemiDeviation< Real >::gradients_, ROL::RandVarFunctional< Real >::setStorage(), and ROL::MeanSemiDeviation< Real >::values_.

template<class Real >

void ROL::MeanSemiDeviation< Real >::setHessVecStorage	(	const Ptr< ScalarController< Real >> &	gradvec_storage,
		const Ptr< VectorController< Real >> &	hessvec_storage
	)

inlinevirtual

Reimplemented from ROL::RandVarFunctional< Real >.

Definition at line 126 of file ROL_MeanSemiDeviation.hpp.

References ROL::MeanSemiDeviation< Real >::gradvecs_, ROL::MeanSemiDeviation< Real >::hessvecs_, and ROL::RandVarFunctional< Real >::setHessVecStorage().

template<class Real >

void ROL::MeanSemiDeviation< Real >::initialize ( const Vector< Real > & x )

inlinevirtual

Initialize temporary variables.

Parameters

[in] x is a vector used for initializing storage

Reimplemented from ROL::RandVarFunctional< Real >.

Definition at line 133 of file ROL_MeanSemiDeviation.hpp.

References ROL::MeanSemiDeviation< Real >::clear(), and ROL::RandVarFunctional< Real >::initialize().

template<class Real >

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

inlinevirtual

Update internal storage for value computation.

Parameters

[in]	val	is the value of the random variable objective function at the current sample point
[in]	weight	is the weight associated with the current sample point

Reimplemented from ROL::RandVarFunctional< Real >.

Definition at line 138 of file ROL_MeanSemiDeviation.hpp.

References ROL::RandVarFunctional< Real >::computeValue(), ROL::RandVarFunctional< Real >::val_, and ROL::RandVarFunctional< Real >::weight_.

template<class Real >

Real ROL::MeanSemiDeviation< Real >::getValue	(	const Vector< Real > &	x,
		const std::vector< Real > &	xstat,
		SampleGenerator< Real > &	sampler
	)

inlinevirtual

Return risk measure value.

Parameters

[in] sampler is 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::RandVarFunctional< Real >.

Definition at line 146 of file ROL_MeanSemiDeviation.hpp.

References ROL::MeanSemiDeviation< Real >::coeff_, ROL::SampleGenerator< Real >::getMyPoint(), ROL::SampleGenerator< Real >::getMyWeight(), ROL::SampleGenerator< Real >::numMySamples(), ROL::MeanSemiDeviation< Real >::plusFunction_, ROL::SampleGenerator< Real >::start(), ROL::SampleGenerator< Real >::sumAll(), ROL::RandVarFunctional< Real >::val_, and ROL::MeanSemiDeviation< Real >::values_.

template<class Real >

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

inlinevirtual

Update internal risk measure storage for gradient computation.

Parameters

[in]	val	is the value of the random variable objective function at the current sample point
[in]	g	is the gradient of the random variable objective function at the current sample point
[in]	weight	is the weight associated with the current sample point

Reimplemented from ROL::RandVarFunctional< Real >.

Definition at line 165 of file ROL_MeanSemiDeviation.hpp.

References ROL::RandVarFunctional< Real >::computeGradient(), ROL::RandVarFunctional< Real >::computeValue(), ROL::RandVarFunctional< Real >::dualVector_, ROL::RandVarFunctional< Real >::val_, and ROL::RandVarFunctional< Real >::weight_.

template<class Real >

void ROL::MeanSemiDeviation< Real >::getGradient	(	Vector< Real > &	g,
		std::vector< Real > &	gstat,
		const Vector< Real > &	x,
		const std::vector< Real > &	xstat,
		SampleGenerator< Real > &	sampler
	)

inlinevirtual

Return risk measure (sub)gradient.

Parameters

[out]	g	is the (sub)gradient of the risk measure
[in]	sampler	is 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::RandVarFunctional< Real >.

Definition at line 174 of file ROL_MeanSemiDeviation.hpp.

References ROL::MeanSemiDeviation< Real >::coeff_, ROL::RandVarFunctional< Real >::dualVector_, ROL::RandVarFunctional< Real >::g_, ROL::SampleGenerator< Real >::getMyPoint(), ROL::SampleGenerator< Real >::getMyWeight(), ROL::MeanSemiDeviation< Real >::gradients_, ROL::SampleGenerator< Real >::numMySamples(), ROL::MeanSemiDeviation< Real >::plusFunction_, ROL::SampleGenerator< Real >::start(), ROL::SampleGenerator< Real >::sumAll(), ROL::RandVarFunctional< Real >::val_, and ROL::MeanSemiDeviation< Real >::values_.

template<class Real >

void ROL::MeanSemiDeviation< 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
	)

inlinevirtual

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

Parameters

[in]	val	is the value of the random variable objective function at the current sample point
[in]	g	is the gradient of the random variable objective function at the current sample point
[in]	gv	is the gradient of the random variable objective function at the current sample point applied to the vector v0
[in]	hv	is the Hessian of the random variable objective function at the current sample point applied to the vector v0
[in]	weight	is the weight associated with the current sample point

Reimplemented from ROL::RandVarFunctional< Real >.

Definition at line 205 of file ROL_MeanSemiDeviation.hpp.

References ROL::RandVarFunctional< Real >::computeGradVec(), ROL::RandVarFunctional< Real >::computeHessVec(), ROL::RandVarFunctional< Real >::computeValue(), ROL::RandVarFunctional< Real >::dualVector_, ROL::RandVarFunctional< Real >::gv_, ROL::RandVarFunctional< Real >::val_, and ROL::RandVarFunctional< Real >::weight_.

template<class Real >

void ROL::MeanSemiDeviation< 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
	)

inlinevirtual

Return risk measure Hessian-times-a-vector.

Parameters

[out]	hv	is the Hessian-times-a-vector of the risk measure
[in]	sampler	is 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::RandVarFunctional< Real >.

Definition at line 218 of file ROL_MeanSemiDeviation.hpp.

References ROL::MeanSemiDeviation< Real >::coeff_, ROL::RandVarFunctional< Real >::dualVector_, ROL::SampleGenerator< Real >::getMyPoint(), ROL::SampleGenerator< Real >::getMyWeight(), ROL::MeanSemiDeviation< Real >::gradients_, ROL::MeanSemiDeviation< Real >::gradvecs_, ROL::RandVarFunctional< Real >::gv_, ROL::MeanSemiDeviation< Real >::hessvecs_, ROL::RandVarFunctional< Real >::hv_, ROL::SampleGenerator< Real >::numMySamples(), ROL::MeanSemiDeviation< Real >::plusFunction_, ROL::SampleGenerator< Real >::start(), ROL::SampleGenerator< Real >::sumAll(), ROL::RandVarFunctional< Real >::val_, and ROL::MeanSemiDeviation< Real >::values_.