Data Types
type	line_search
	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...

Functions/Subroutines
pure integer(int32) function	ls_get_max_eval (this)
	Gets the maximum number of function evaluations allowed during a single line search.

subroutine	ls_set_max_eval (this, x)
	Sets the maximum number of function evaluations allowed during a single line search.

pure real(real64) function	ls_get_scale (this)
	Gets the scaling of the product of the gradient and direction vectors (ALPHA) 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.

subroutine	ls_set_scale (this, x)
	sets the scaling of the product of the gradient and direction vectors (ALPHA) 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.

pure real(real64) function	ls_get_dist (this)
	Gets a distance factor defining the minimum distance along the search direction vector is practical.

subroutine	ls_set_dist (this, x)
	Sets a distance factor defining the minimum distance along the search direction vector is practical.

subroutine	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.

subroutine	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.

pure real(real64) function	min_backtrack_search (mode, f0, f, f1, alam, alam1, slope)
	Minimizes either the quadratic or cubic representation for a backtracking-type line search.

subroutine, public	limit_search_vector (x, lim)
	Provides a means of scaling the length of the search direction vector.

Detailed Description

nonlin_linesearch

Purpose: To provide line search routines capable of minimizing nondesireable influences of the nonlinear equation solver model on the convergence of the iteration process.

Function/Subroutine Documentation

◆ limit_search_vector()

subroutine, public nonlin_linesearch::limit_search_vector	(	real(real64), dimension(:), intent(inout)	x,
		real(real64), intent(in)	lim )

Provides a means of scaling the length of the search direction vector.

Parameters

[in,out]	x	On input, the search direction vector. On output, the search direction vector limited in length to that specified by `lim`. If the vector is originally shorter than the limit length, no change is made.
[in]	lim	The length limit value.

Definition at line 678 of file nonlin_linesearch.f90.

◆ ls_get_dist()

pure real(real64) function nonlin_linesearch::ls_get_dist ( class(line_search), intent(in) this )

private

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 151 of file nonlin_linesearch.f90.

◆ ls_get_max_eval()

pure integer(int32) function nonlin_linesearch::ls_get_max_eval ( 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 98 of file nonlin_linesearch.f90.

◆ ls_get_scale()

pure real(real64) function nonlin_linesearch::ls_get_scale ( class(line_search), intent(in) this )

private

Gets the scaling of the product of the gradient and direction vectors (ALPHA) 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.

Parameters

[in] this The line_search object.

Returns: The scaling factor.

Definition at line 124 of file nonlin_linesearch.f90.

◆ ls_search_mimo()

subroutine nonlin_linesearch::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 )

private

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 213 of file nonlin_linesearch.f90.

◆ ls_search_miso()

subroutine nonlin_linesearch::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 )

private

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 431 of file nonlin_linesearch.f90.

◆ ls_set_dist()

subroutine nonlin_linesearch::ls_set_dist	(	class(line_search), intent(inout)	this,
		real(real64), intent(in)	x )

private

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 165 of file nonlin_linesearch.f90.

◆ ls_set_max_eval()

subroutine nonlin_linesearch::ls_set_max_eval	(	class(line_search), intent(inout)	this,
		integer(int32), intent(in)	x )

private

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 110 of file nonlin_linesearch.f90.

◆ ls_set_scale()

subroutine nonlin_linesearch::ls_set_scale	(	class(line_search), intent(inout)	this,
		real(real64), intent(in)	x )

private

sets the scaling of the product of the gradient and direction vectors (ALPHA) 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.

Parameters

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

Definition at line 138 of file nonlin_linesearch.f90.

◆ min_backtrack_search()

pure real(real64) function nonlin_linesearch::min_backtrack_search	(	integer(int32), intent(in)	mode,
		real(real64), intent(in)	f0,
		real(real64), intent(in)	f,
		real(real64), intent(in)	f1,
		real(real64), intent(in)	alam,
		real(real64), intent(in)	alam1,
		real(real64), intent(in)	slope )

private

Minimizes either the quadratic or cubic representation for a backtracking-type line search.

Parameters

[in]	mode	Set to 1 to apply the quadratic model; else, any other value will apply the cubic model.
[in]	f0	The previous function value.
[in]	f	The current function value.
[in]	f1	The predicted function value.
[in]	alam	The step length scaling factor at `f`.
[in]	alam1	The step length scaling factor at `f1`.
[in]	slope	The slope of the direction vector.

Returns: The new step length scaling factor.

Definition at line 626 of file nonlin_linesearch.f90.

Data Types

Functions/Subroutines

Detailed Description

Function/Subroutine Documentation

◆ limit_search_vector()

◆ ls_get_dist()

◆ ls_get_max_eval()

◆ ls_get_scale()

◆ ls_search_mimo()

◆ ls_search_miso()

◆ ls_set_dist()

◆ ls_set_max_eval()

◆ ls_set_scale()

◆ min_backtrack_search()