Abstract class defining the problem-specific interface for the simplified solver interface to IterativeSolver. More...

#include <IterativeSolver.h>

Detailed Description

template<typename R, typename P = std::map<size_t, typename R::value_type>>
class molpro::linalg::itsolv::Problem< R, P >

Abstract class defining the problem-specific interface for the simplified solver interface to IterativeSolver.

Template Parameters

R	the type of container for solutions and residuals

Examples: ExampleProblem.h, and ExampleProblemDistrArray.h.

Public Types
using	container_t = R

using	p_container_t = P

using	value_t = typename R::value_type

Public Member Functions
	Problem ()=default

virtual	~Problem ()=default

virtual value_t	residual (const R &parameters, R &residual) const
	Calculate the residual vector. Used by non-linear solvers (NonLinearEquations, Optimize) only.

virtual void	action (const CVecRef< R > &parameters, const VecRef< R > &action) const
	Calculate the action of the kernel matrix on a set of parameters. Used by linear solvers, but not by the non-linear solvers (NonLinearEquations, Optimize).

virtual bool	diagonals (container_t &d) const
	Optionally provide the diagonal elements of the underlying kernel. If implemented and returning true, the provided diagonals will be used by IterativeSolver for preconditioning (and therefore the precondition() function does not need to be implemented), and, in the case of linear problems, for selection of the P space. Otherwise, preconditioning will be done with precondition(), and any P space has to be provided manually.

virtual void	precondition (const VecRef< R > &residual, const std::vector< value_t > &shift) const
	Apply preconditioning to a residual vector in order to predict a step towards the solution.

virtual void	precondition (const VecRef< R > &residual, const std::vector< value_t > &shift, const R &diagonals) const
	Apply preconditioning to a residual vector in order to predict a step towards the solution.

virtual void	precondition_with_metric (const VecRef< R > &residual, const std::vector< value_t > &shift, const R &diagonals, const R &metric_diagonals) const
	Apply preconditioning to a residual vector of a generalised eigenproblem. Used instead of precondition() when both diagonals() and metric_diagonals() are provided.

virtual MetricKind	metric_kind () const
	The kind of metric M of the problem. Anything other than MetricKind::Identity turns the eigenproblem A v = lambda v into the generalised eigenproblem A v = lambda M v, which requires metric_action() and solving with the IterativeSolver::solve() overload that takes buffers for the actions of the metric. Which kinds are supported depends on the solver (IterativeSolver::supports_metric()); solve() throws for the others.

virtual MetricStorage	metric_storage () const
	How IterativeSolver::solve() obtains the actions of the metric on its subspace vectors, see IterativeSolver::set_metric(). With MetricStorage::Stored (the default) it keeps the action of the metric on every subspace vector; with MetricStorage::OnTheFly it keeps none, and calls metric_action() on the solutions whenever it constructs residuals instead. OnTheFly saves the memory or disk space of one vector per subspace vector at the cost of applying the metric once more per root and iteration, which pays off where the metric is cheap to apply, e.g. diagonal or sparse.

virtual void	metric_action (const CVecRef< R > &parameters, const VecRef< R > &metric_actions) const
	Calculate the action of the metric on a set of parameters. Called only if metric_kind() is not MetricKind::Identity.

virtual void	action_with_metric (const CVecRef< R > &parameters, const VecRef< R > &actions, const VecRef< R > &metric_actions) const
	Calculate the actions of the kernel and of the metric on a set of parameters together. Used by IterativeSolver::solve() for problems with a metric; the default calls action() and metric_action(), and can be overridden where both are cheaper to calculate together.

virtual bool	metric_diagonals (R &d) const
	Provide the diagonal elements of the metric. For a problem with a metric that provides diagonals(), this is required too, so that the default preconditioner divides by diag(A) - lambda diag(M); IterativeSolver::solve() throws otherwise. Approximate values are fine. The diagonal elements of the kernel and of the metric are then passed to precondition_with_metric(), and an initial guess is generated from the lowest ratios of the diagonal elements of the kernel and the metric, which needs a container supported by precondition_default().

virtual bool	RHS (R &RHS, unsigned int instance) const
	Return the inhomogeneous part of a linear equation system.

virtual std::vector< value_t >	pp_action_matrix (const std::vector< P > &pparams) const
	Calculate the kernel matrix in the P space.

virtual void	p_action (const std::vector< std::vector< value_t > > &p_coefficients, const CVecRef< P > &pparams, const VecRef< container_t > &actions) const
	Calculate the action of the kernel matrix on a set of vectors in the P space.

virtual std::vector< value_t >	pp_metric_matrix (const std::vector< P > &pparams) const
	Calculate the metric matrix in the P space, for a problem with a metric (metric_kind())

virtual void	p_metric_action (const std::vector< std::vector< value_t > > &p_coefficients, const CVecRef< P > &pparams, const VecRef< container_t > &metric_actions) const
	Calculate the action of the metric on a set of vectors in the P space, for a problem with a metric (metric_kind()). Not used if the metric is applied on the fly (metric_storage()).

virtual bool	test_parameters (unsigned int instance, R &parameters) const
	Provide values of R vectors for testing the problem class. For use in a non-linear solver, the first vector (instance=0) should be a reference point, and the remainder (instance>0) should be close to it, such that meaningful numerical differentation can be done to test the residual function.

Member Typedef Documentation

◆ container_t

template<typename R , typename P = std::map<size_t, typename R::value_type>>

using molpro::linalg::itsolv::Problem< R, P >::container_t = R

◆ p_container_t

template<typename R , typename P = std::map<size_t, typename R::value_type>>

using molpro::linalg::itsolv::Problem< R, P >::p_container_t = P

◆ value_t

template<typename R , typename P = std::map<size_t, typename R::value_type>>

using molpro::linalg::itsolv::Problem< R, P >::value_t = typename R::value_type

Constructor & Destructor Documentation

◆ Problem()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

molpro::linalg::itsolv::Problem< R, P >::Problem ( )

default

◆ ~Problem()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual molpro::linalg::itsolv::Problem< R, P >::~Problem ( )

virtualdefault

Member Function Documentation

◆ action()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual void molpro::linalg::itsolv::Problem< R, P >::action	(	const CVecRef< R > &	parameters,
		const VecRef< R > &	action
	)		const

inlinevirtual

Calculate the action of the kernel matrix on a set of parameters. Used by linear solvers, but not by the non-linear solvers (NonLinearEquations, Optimize).

Parameters

parameters	The trial solutions for which the action is to be calculated
action	The action vectors

Examples: ExampleProblem.h, and ExampleProblemDistrArray.h.

◆ action_with_metric()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual void molpro::linalg::itsolv::Problem< R, P >::action_with_metric	(	const CVecRef< R > &	parameters,
		const VecRef< R > &	actions,
		const VecRef< R > &	metric_actions
	)		const

inlinevirtual

Calculate the actions of the kernel and of the metric on a set of parameters together. Used by IterativeSolver::solve() for problems with a metric; the default calls action() and metric_action(), and can be overridden where both are cheaper to calculate together.

Parameters

parameters	The trial solutions for which the actions are to be calculated
actions	The action vectors of the kernel
metric_actions	The action vectors of the metric

◆ diagonals()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual bool molpro::linalg::itsolv::Problem< R, P >::diagonals ( container_t & d ) const

inlinevirtual

Optionally provide the diagonal elements of the underlying kernel. If implemented and returning true, the provided diagonals will be used by IterativeSolver for preconditioning (and therefore the precondition() function does not need to be implemented), and, in the case of linear problems, for selection of the P space. Otherwise, preconditioning will be done with precondition(), and any P space has to be provided manually.

Parameters

d	On exit, contains the diagonal elements

Returns: Whether diagonals have been provided.

Examples: ExampleProblem.h, and ExampleProblemDistrArray.h.

◆ metric_action()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual void molpro::linalg::itsolv::Problem< R, P >::metric_action	(	const CVecRef< R > &	parameters,
		const VecRef< R > &	metric_actions
	)		const

inlinevirtual

Calculate the action of the metric on a set of parameters. Called only if metric_kind() is not MetricKind::Identity.

Parameters

parameters	The trial solutions for which the action is to be calculated
metric_actions	The action vectors of the metric

◆ metric_diagonals()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual bool molpro::linalg::itsolv::Problem< R, P >::metric_diagonals ( R & d ) const

inlinevirtual

Provide the diagonal elements of the metric. For a problem with a metric that provides diagonals(), this is required too, so that the default preconditioner divides by diag(A) - lambda diag(M); IterativeSolver::solve() throws otherwise. Approximate values are fine. The diagonal elements of the kernel and of the metric are then passed to precondition_with_metric(), and an initial guess is generated from the lowest ratios of the diagonal elements of the kernel and the metric, which needs a container supported by precondition_default().

Parameters

d	On exit, contains the diagonal elements of the metric

Returns: Whether the diagonal elements of the metric have been provided.

◆ metric_kind()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual MetricKind molpro::linalg::itsolv::Problem< R, P >::metric_kind ( ) const

inlinevirtual

The kind of metric M of the problem. Anything other than MetricKind::Identity turns the eigenproblem A v = lambda v into the generalised eigenproblem A v = lambda M v, which requires metric_action() and solving with the IterativeSolver::solve() overload that takes buffers for the actions of the metric. Which kinds are supported depends on the solver (IterativeSolver::supports_metric()); solve() throws for the others.

◆ metric_storage()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual MetricStorage molpro::linalg::itsolv::Problem< R, P >::metric_storage ( ) const

inlinevirtual

How IterativeSolver::solve() obtains the actions of the metric on its subspace vectors, see IterativeSolver::set_metric(). With MetricStorage::Stored (the default) it keeps the action of the metric on every subspace vector; with MetricStorage::OnTheFly it keeps none, and calls metric_action() on the solutions whenever it constructs residuals instead. OnTheFly saves the memory or disk space of one vector per subspace vector at the cost of applying the metric once more per root and iteration, which pays off where the metric is cheap to apply, e.g. diagonal or sparse.

◆ p_action()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual void molpro::linalg::itsolv::Problem< R, P >::p_action	(	const std::vector< std::vector< value_t > > &	p_coefficients,
		const CVecRef< P > &	pparams,
		const VecRef< container_t > &	actions
	)		const

inlinevirtual

Calculate the action of the kernel matrix on a set of vectors in the P space.

Parameters

p_coefficients	The projection of the vectors onto to the P space
pparams	Specification of the P space
actions	On exit, the computed action has been added to the original contents

Examples: ExampleProblemDistrArray.h.

◆ p_metric_action()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual void molpro::linalg::itsolv::Problem< R, P >::p_metric_action	(	const std::vector< std::vector< value_t > > &	p_coefficients,
		const CVecRef< P > &	pparams,
		const VecRef< container_t > &	metric_actions
	)		const

inlinevirtual

Calculate the action of the metric on a set of vectors in the P space, for a problem with a metric (metric_kind()). Not used if the metric is applied on the fly (metric_storage()).

Parameters

p_coefficients	The projection of the vectors onto to the P space
pparams	Specification of the P space
metric_actions	On exit, the computed action of the metric has been added to the original contents

IterativeSolver::solve() calls it once with no vectors (empty p_coefficients and metric_actions) before it changes the solver, to make sure that it is available.

◆ pp_action_matrix()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual std::vector< value_t > molpro::linalg::itsolv::Problem< R, P >::pp_action_matrix ( const std::vector< P > & pparams ) const

inlinevirtual

Calculate the kernel matrix in the P space.

Parameters

pparams Specification of the P space

Returns

Examples: ExampleProblemDistrArray.h.

◆ pp_metric_matrix()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual std::vector< value_t > molpro::linalg::itsolv::Problem< R, P >::pp_metric_matrix ( const std::vector< P > & pparams ) const

inlinevirtual

Calculate the metric matrix in the P space, for a problem with a metric (metric_kind())

Parameters

pparams Specification of the P space

Returns: the matrix <p_i|M p_j>, with j running fastest

◆ precondition() [1/2]

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual void molpro::linalg::itsolv::Problem< R, P >::precondition	(	const VecRef< R > &	residual,
		const std::vector< value_t > &	shift
	)		const

inlinevirtual

Apply preconditioning to a residual vector in order to predict a step towards the solution.

Parameters

residual	On entry, assumed to be the residual. On exit, the negative of the predicted step.
shift	When called from LinearEigensystem, contains the corresponding current eigenvalue estimates for each of the parameter vectors in the set. All other solvers pass a vector of zeroes.

Used if diagonals() is not provided. For a generalised eigenproblem A v = lambda M v, the preconditioner should approximate the inverse of A - shift M.

◆ precondition() [2/2]

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual void molpro::linalg::itsolv::Problem< R, P >::precondition	(	const VecRef< R > &	residual,
		const std::vector< value_t > &	shift,
		const R &	diagonals
	)		const

inlinevirtual

Apply preconditioning to a residual vector in order to predict a step towards the solution.

Parameters

residual	On entry, assumed to be the residual. On exit, the negative of the predicted step.
shift	When called from LinearEigensystem, contains the corresponding current eigenvalue estimates for each of the parameter vectors in the set. All other solvers pass a vector of zeroes.
diagonals	The diagonal elements of the underlying kernel

◆ precondition_with_metric()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual void molpro::linalg::itsolv::Problem< R, P >::precondition_with_metric	(	const VecRef< R > &	residual,
		const std::vector< value_t > &	shift,
		const R &	diagonals,
		const R &	metric_diagonals
	)		const

inlinevirtual

Apply preconditioning to a residual vector of a generalised eigenproblem. Used instead of precondition() when both diagonals() and metric_diagonals() are provided.

Parameters

residual	On entry, assumed to be the residual. On exit, the negative of the predicted step.
shift	Contains the current eigenvalue estimates for each of the parameter vectors in the set.
diagonals	The diagonal elements of the underlying kernel
metric_diagonals	The diagonal elements of the metric

◆ residual()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual value_t molpro::linalg::itsolv::Problem< R, P >::residual	(	const R &	parameters,
		R &	residual
	)		const

inlinevirtual

Calculate the residual vector. Used by non-linear solvers (NonLinearEquations, Optimize) only.

Parameters

parameters	The trial solution for which the residual is to be calculated
residual	The residual vector

Returns: In the case where the residual is an exact differential, the corresponding function value. Used by Optimize but not NonLinearEquations.

Reimplemented in molpro::linalg::itsolv::interpolate_detail::Morse_problem< value_type >.

Examples: ExampleProblem.h, and ExampleProblemDistrArray.h.

◆ RHS()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual bool molpro::linalg::itsolv::Problem< R, P >::RHS	(	R &	RHS,
		unsigned int	instance
	)		const

inlinevirtual

Return the inhomogeneous part of a linear equation system.

Parameters

RHS	On return, will contain the requested right-hand-side of equations if available.
instance	Which RHS is required. If there are N sets of equations to solve, then 0,1,...N-1 number the instances. The solver will call this function repeatedly with instance=0,1,2,... until it receives a negative response.

Returns: whether the requested RHS is available and has been provided

Examples: ExampleProblem.h.

◆ test_parameters()

template<typename R , typename P = std::map<size_t, typename R::value_type>>

virtual bool molpro::linalg::itsolv::Problem< R, P >::test_parameters	(	unsigned int	instance,
		R &	parameters
	)		const

inlinevirtual

Provide values of R vectors for testing the problem class. For use in a non-linear solver, the first vector (instance=0) should be a reference point, and the remainder (instance>0) should be close to it, such that meaningful numerical differentation can be done to test the residual function.

Parameters

instance
parameters

Returns: true if a vector has been provided

Detailed Description

Public Types

Public Member Functions

Member Typedef Documentation

◆ container_t

◆ p_container_t

◆ value_t

Constructor & Destructor Documentation

◆ Problem()

◆ ~Problem()

Member Function Documentation

◆ action()

◆ action_with_metric()

◆ diagonals()

◆ metric_action()

◆ metric_diagonals()

◆ metric_kind()

◆ metric_storage()

◆ p_action()

◆ p_metric_action()

◆ pp_action_matrix()

◆ pp_metric_matrix()

◆ precondition() [1/2]

◆ precondition() [2/2]

◆ precondition_with_metric()

◆ residual()

◆ RHS()

◆ test_parameters()