Defines a type capable of performing an inexact, backtracking line search to find a point as far along the specified direction vector that is usable for unconstrained minimization problems. More...

Public Member Functions
procedure, public	get_max_fcn_evals (this)
	Gets the maximum number of function evaluations allowed during a single line search.

procedure, public	set_max_fcn_evals (this, x)
	Sets the maximum number of function evaluations allowed during a single line search.

procedure, public	get_scaling_factor (this)
	Gets the scaling of the product of the gradient and direction vectors.

procedure, public	set_scaling_factor (this, x)
	Sets the scaling of the product of the gradient and direction vectors.

procedure, public	get_distance_factor (this)
	Gets a distance factor defining the minimum distance along the search direction vector is practical.

procedure, public	set_distance_factor (this, x)
	Sets a distance factor defining the minimum distance along the search direction vector is practical.

generic, public	search (this, fcn, xold, grad, dir, x, fvec, fold, fx, ib, err)
	Utilizes an inexact, backtracking line search based on the Armijo-Goldstein condition to find a point as far along the specified direction vector that is usable for unconstrained minimization problems.

generic, public	search (this, fcn, xold, grad, dir, x, fold, fx, ib, err)
	Utilizes an inexact, backtracking line search based on the Armijo-Goldstein condition to find a point as far along the specified direction vector that is usable for unconstrained minimization problems.

procedure	ls_search_mimo (this, fcn, xold, grad, dir, x, fvec, fold, fx, ib, err)
	Utilizes an inexact, backtracking line search to find a point as far along the specified direction vector that is usable for unconstrained minimization problems.

procedure	ls_search_miso (this, fcn, xold, grad, dir, x, fold, fx, ib, err)
	Utilizes an inexact, backtracking line search to find a point as far along the specified direction vector that is usable for unconstrained minimization problems.

Public Attributes
real(real64)	m_alpha = 1.0d-4
	Defines the scaling of the product of the gradient and direction vectors such that F(X + LAMBDA * P) <= F(X) + LAMBDA * ALPHA * P*T G, where P is the search direction vector, G is the gradient vector, and LAMBDA is the scaling factor. The parameter must exist on the set (0, 1). A value of 1e-4 is typically a good starting point.

real(real64)	m_factor = 0.1d0
	Defines a minimum factor X used to determine a minimum value LAMBDA such that MIN(LAMBDA) = X * LAMBDA, where LAMBDA defines the distance along the line search direction assuming a value of one means the full length of the direction vector is traversed. As such, the value must exist on the set (0, 1); however, for practical considerations, the minimum value should be limited to 0.1 such that the value must exist on the set [0.1, 1).

Private Attributes
integer(int32)	m_maxeval = 100
	The maximum number of function evaluations allowed during a single line search.

Detailed Description

Defines a type capable of performing an inexact, backtracking line search to find a point as far along the specified direction vector that is usable for unconstrained minimization problems.

See Also

Wikipedia
[Oxfford Lecture Notes] (https://people.maths.ox.ac.uk/hauser/hauser_lecture2.pdf)
[Northwestern University - Line Search] (https://optimization.mccormick.northwestern.edu/index.php/Line_search_methods)
[Northwestern University - Trust Region Methods] (https://optimization.mccormick.northwestern.edu/index.php/Trust-region_methods)
Wolfram
Numerical Recipes

Definition at line 40 of file nonlin_linesearch.f90.

Member Function/Subroutine Documentation

◆ get_distance_factor()

procedure, public nonlin_linesearch::line_search::get_distance_factor ( class(line_search), intent(in) this )

Gets a distance factor defining the minimum distance along the search direction vector is practical.

Parameters

[in] this The line_search object.

Returns: The distance factor. A value of 1 indicates the full length of the vector.

Definition at line 75 of file nonlin_linesearch.f90.

◆ get_max_fcn_evals()

procedure, public nonlin_linesearch::line_search::get_max_fcn_evals ( class(line_search), intent(in) this )

Gets the maximum number of function evaluations allowed during a single line search.

Parameters

[in] this The line_search object.

Returns: The maximum number of function evaluations.

Definition at line 63 of file nonlin_linesearch.f90.

◆ get_scaling_factor()

procedure, public nonlin_linesearch::line_search::get_scaling_factor ( class(line_search), intent(in) this )

Gets the scaling of the product of the gradient and direction vectors.

Parameters

[in] this The line_search object.

Returns: The scaling factor.

Definition at line 69 of file nonlin_linesearch.f90.

◆ ls_search_mimo()

procedure nonlin_linesearch::line_search::ls_search_mimo	(	class(line_search), intent(in)	this,
		class(vecfcn_helper), intent(in)	fcn,
		real(real64), dimension(:), intent(in)	xold,
		real(real64), dimension(:), intent(in)	grad,
		real(real64), dimension(:), intent(in)	dir,
		real(real64), dimension(:), intent(out)	x,
		real(real64), dimension(:), intent(out)	fvec,
		real(real64), intent(in), optional	fold,
		real(real64), intent(out), optional	fx,
		type(iteration_behavior), optional	ib,
		class(errors), intent(inout), optional, target	err )

Utilizes an inexact, backtracking line search to find a point as far along the specified direction vector that is usable for unconstrained minimization problems.

Parameters

[in]	this	The line_search object.
[in]	fcn	A vecfcn_helper object containing the system of equations.
[in]	xold	An N-element array defining the initial point, where N is the number of variables.
[in]	grad	An N-element array defining the gradient of `fcn` evaluated at `xold`.
[in]	dir	An N-element array defining the search direction.
[out]	x	An N-element array where the updated solution point will be written.
[out]	fvec	An M-element array containing the M equation values evaluated at `x`, where M is the number of equations.
[in]	fold	An optional input that provides the value resulting from: 1/2 * dot_product(fcn(xold), fcn(xold)). If not provided, `fcn` is evalauted at `xold`, and the aforementioned relationship is computed.
[out]	fx	The result of the operation: (1/2) * dot_product(`fvec`, `fvec`). Remember `fvec` is evaluated at `x`.
[out]	ib	An optional output, that if provided, allows the caller to obtain iteration performance statistics.
[out]	err	An optional errors-based object that if provided can be used to retrieve information relating to any errors encountered during execution. If not provided, a default implementation of the errors class is used internally to provide error handling. Possible errors and warning messages that may be encountered are as follows. NL_INVALID_OPERATION_ERROR: Occurs if no equations have been defined. NL_ARRAY_SIZE_ERROR: Occurs if any of the input arrays are not sized correctly. NL_DIVERGENT_BEHAVIOR_ERROR: Occurs if the direction vector is pointing in an apparent uphill direction. NL_CONVERGENCE_ERROR: Occurs if the line search cannot converge within the allowed number of iterations.

Definition at line 85 of file nonlin_linesearch.f90.

◆ ls_search_miso()

procedure nonlin_linesearch::line_search::ls_search_miso	(	class(line_search), intent(in)	this,
		class(fcnnvar_helper), intent(in)	fcn,
		real(real64), dimension(:), intent(in)	xold,
		real(real64), dimension(:), intent(in)	grad,
		real(real64), dimension(:), intent(in)	dir,
		real(real64), dimension(:), intent(out)	x,
		real(real64), intent(in), optional	fold,
		real(real64), intent(out), optional	fx,
		type(iteration_behavior), optional	ib,
		class(errors), intent(inout), optional, target	err )

Utilizes an inexact, backtracking line search to find a point as far along the specified direction vector that is usable for unconstrained minimization problems.

Parameters

[in]	this	The line_search object.
[in]	fcn	A fcnnvar_helper object containing the system of equations.
[in]	xold	An N-element array defining the initial point, where N is the number of variables.
[in]	grad	An N-element array defining the gradient of `fcn` evaluated at `xold`.
[in]	dir	An N-element array defining the search direction.
[out]	x	An N-element array where the updated solution point will be written.
[in]	fold	An optional input that provides the function value at `xold`. If not provided, `fcn` is evalauted at `xold`.
[out]	fx	The value of the function as evaluated at `x`.
[out]	ib	An optional output, that if provided, allows the caller to obtain iteration performance statistics.
[out]	err	An optional errors-based object that if provided can be used to retrieve information relating to any errors encountered during execution. If not provided, a default implementation of the errors class is used internally to provide error handling. Possible errors and warning messages that may be encountered are as follows. NL_INVALID_OPERATION_ERROR: Occurs if no equations have been defined. NL_ARRAY_SIZE_ERROR: Occurs if any of the input arrays are not sized correctly. NL_DIVERGENT_BEHAVIOR_ERROR: Occurs if the direction vector is pointing in an apparent uphill direction. NL_CONVERGENCE_ERROR: Occurs if the line search cannot converge within the allowed number of iterations.

Definition at line 86 of file nonlin_linesearch.f90.

◆ search() [1/2]

generic, public nonlin_linesearch::line_search::search	(	class(line_search), intent(in)	this,
		class(fcnnvar_helper), intent(in)	fcn,
		real(real64), dimension(:), intent(in)	xold,
		real(real64), dimension(:), intent(in)	grad,
		real(real64), dimension(:), intent(in)	dir,
		real(real64), dimension(:), intent(out)	x,
		real(real64), intent(in), optional	fold,
		real(real64), intent(out), optional	fx,
		type(iteration_behavior), optional	ib,
		class(errors), intent(inout), optional, target	err )

Utilizes an inexact, backtracking line search based on the Armijo-Goldstein condition to find a point as far along the specified direction vector that is usable for unconstrained minimization problems.

Parameters

[in]	this	The line_search object.
[in]	fcn	A fcnnvar_helper object containing the system of equations.
[in]	xold	An N-element array defining the initial point, where N is the number of variables.
[in]	grad	An N-element array defining the gradient of `fcn` evaluated at `xold`.
[in]	dir	An N-element array defining the search direction.
[out]	x	An N-element array where the updated solution point will be written.
[in]	fold	An optional input that provides the function value at `xold`. If not provided, `fcn` is evalauted at `xold`.
[out]	fx	The value of the function as evaluated at `x`.
[out]	ib	An optional output, that if provided, allows the caller to obtain iteration performance statistics.
[out]	err	An optional errors-based object that if provided can be used to retrieve information relating to any errors encountered during execution. If not provided, a default implementation of the errors class is used internally to provide error handling. Possible errors and warning messages that may be encountered are as follows. NL_INVALID_OPERATION_ERROR: Occurs if no equations have been defined. NL_ARRAY_SIZE_ERROR: Occurs if any of the input arrays are not sized correctly. NL_DIVERGENT_BEHAVIOR_ERROR: Occurs if the direction vector is pointing in an apparent uphill direction. NL_CONVERGENCE_ERROR: Occurs if the line search cannot converge within the allowed number of iterations.

Definition at line 83 of file nonlin_linesearch.f90.

◆ search() [2/2]

generic, public nonlin_linesearch::line_search::search	(	class(line_search), intent(in)	this,
		class(vecfcn_helper), intent(in)	fcn,
		real(real64), dimension(:), intent(in)	xold,
		real(real64), dimension(:), intent(in)	grad,
		real(real64), dimension(:), intent(in)	dir,
		real(real64), dimension(:), intent(out)	x,
		real(real64), dimension(:), intent(out)	fvec,
		real(real64), intent(in), optional	fold,
		real(real64), intent(out), optional	fx,
		type(iteration_behavior), optional	ib,
		class(errors), intent(inout), optional, target	err )

Utilizes an inexact, backtracking line search based on the Armijo-Goldstein condition to find a point as far along the specified direction vector that is usable for unconstrained minimization problems.

Parameters

[in]	this	The line_search object.
[in]	fcn	A vecfcn_helper object containing the system of equations.
[in]	xold	An N-element array defining the initial point, where N is the number of variables.
[in]	grad	An N-element array defining the gradient of `fcn` evaluated at `xold`.
[in]	dir	An N-element array defining the search direction.
[out]	x	An N-element array where the updated solution point will be written.
[out]	fvec	An M-element array containing the M equation values evaluated at `x`, where M is the number of equations.
[in]	fold	An optional input that provides the value resulting from: 1/2 * dot_product(fcn(xold), fcn(xold)). If not provided, `fcn` is evalauted at `xold`, and the aforementioned relationship is computed.
[out]	fx	The result of the operation: (1/2) * dot_product(`fvec`, `fvec`). Remember `fvec` is evaluated at `x`.
[out]	ib	An optional output, that if provided, allows the caller to obtain iteration performance statistics.
[out]	err	An optional errors-based object that if provided can be used to retrieve information relating to any errors encountered during execution. If not provided, a default implementation of the errors class is used internally to provide error handling. Possible errors and warning messages that may be encountered are as follows. NL_INVALID_OPERATION_ERROR: Occurs if no equations have been defined. NL_ARRAY_SIZE_ERROR: Occurs if any of the input arrays are not sized correctly. NL_DIVERGENT_BEHAVIOR_ERROR: Occurs if the direction vector is pointing in an apparent uphill direction. NL_CONVERGENCE_ERROR: Occurs if the line search cannot converge within the allowed number of iterations.

Definition at line 83 of file nonlin_linesearch.f90.

◆ set_distance_factor()

procedure, public nonlin_linesearch::line_search::set_distance_factor	(	class(line_search), intent(inout)	this,
		real(real64), intent(in)	x )

Sets a distance factor defining the minimum distance along the search direction vector is practical.

Parameters

[in,out]	this	The line_search object.
[in]	x	The distance factor. A value of 1 indicates the full length of the vector. Notice, this value is restricted to lie in the set [0.1, 1.0)

Definition at line 78 of file nonlin_linesearch.f90.

◆ set_max_fcn_evals()

procedure, public nonlin_linesearch::line_search::set_max_fcn_evals	(	class(line_search), intent(inout)	this,
		integer(int32), intent(in)	x )

Sets the maximum number of function evaluations allowed during a single line search.

Parameters

[in,out]	this	The line_search object.
[in]	x	The maximum number of function evaluations.

Definition at line 66 of file nonlin_linesearch.f90.

◆ set_scaling_factor()

procedure, public nonlin_linesearch::line_search::set_scaling_factor	(	class(line_search), intent(inout)	this,
		real(real64), intent(in)	x )

Sets the scaling of the product of the gradient and direction vectors.

Parameters

[in,out]	this	The line_search object.
[in]	x	The scaling factor.

Definition at line 72 of file nonlin_linesearch.f90.

Member Data Documentation

◆ m_alpha

real(real64) nonlin_linesearch::line_search::m_alpha = 1.0d-4

Defines the scaling of the product of the gradient and direction vectors such that F(X + LAMBDA * P) <= F(X) + LAMBDA * ALPHA * P**T * G, where P is the search direction vector, G is the gradient vector, and LAMBDA is the scaling factor. The parameter must exist on the set (0, 1). A value of 1e-4 is typically a good starting point.

Definition at line 51 of file nonlin_linesearch.f90.

◆ m_factor

real(real64) nonlin_linesearch::line_search::m_factor = 0.1d0

Defines a minimum factor X used to determine a minimum value LAMBDA such that MIN(LAMBDA) = X * LAMBDA, where LAMBDA defines the distance along the line search direction assuming a value of one means the full length of the direction vector is traversed. As such, the value must exist on the set (0, 1); however, for practical considerations, the minimum value should be limited to 0.1 such that the value must exist on the set [0.1, 1).

Definition at line 59 of file nonlin_linesearch.f90.

◆ m_maxeval

integer(int32) nonlin_linesearch::line_search::m_maxeval = 100

private

The maximum number of function evaluations allowed during a single line search.

Definition at line 44 of file nonlin_linesearch.f90.

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

D:/Code/nonlin/src/nonlin_linesearch.f90

Public Member Functions

Public Attributes

Private Attributes

Detailed Description

Member Function/Subroutine Documentation

◆ get_distance_factor()

◆ get_max_fcn_evals()

◆ get_scaling_factor()

◆ ls_search_mimo()

◆ ls_search_miso()

◆ search() [1/2]

◆ search() [2/2]

◆ set_distance_factor()

◆ set_max_fcn_evals()

◆ set_scaling_factor()

Member Data Documentation

◆ m_alpha

◆ m_factor

◆ m_maxeval