Welcome to BCLS!

Go to the source code of this file.


Functions
static void *	xmalloc (int len, size_t size, char *who)
	Malloc wrapper. Private to this file.
BCLS *	bcls_create_prob (int mmax, int nmax)
	Create a BCLS problem instance.
void	bcls_init_prob (BCLS *ls)
	Initialize a BCLS problem.
int	bcls_free_prob (BCLS *ls)
	Free and reinitialize all resources in an existing BCLS problem.
void	bcls_set_print_hook (BCLS ls, void info, int(hook)(void info, char *msg))
	Install a print-hook routine.
void	bcls_set_fault_hook (BCLS ls, void info, int(hook)(void info, char *msg))
	Install a fault-hook routine.
void	bcls_set_anorm (BCLS *ls, double anorm[])
	Give BCLS access to set of column weights.
void	bcls_set_usolve (BCLS ls, int(Usolve)(int mode, int m, int n, int nix, int ix[], double v[], double w[], void *UsrWrk))
	Install a user-defined preconditioning routine.
int	bcls_compute_anorm (BCLS ls, int n, int m, int(Aprod)(int mode, int m, int n, int nix, int ix[], double x[], double y[], void UsrWrk), void UsrWrk, double anorm[])
	Compute the column norms of A.
void	bcls_set_problem_data (BCLS ls, int m, int n, int(Aprod)(int mode, int m, int n, int nix, int ix[], double x[], double y[], void UsrWrk), void UsrWrk, double damp, double x[], double b[], double c[], double bl[], double bu[])
	Load the problem into the BCLS data structure.
char *	bcls_exit_msg (int flag)
	Return an exit message.
int	bcls_solve_prob (BCLS *ls)
	Solve the current problem instance.

Detailed Description

Function Documentation

int bcls_compute_anorm	(	BCLS *	ls,
		int	n,
		int	m,
		int()(int mode, int m, int n, int nix, int ix[], double x[], double y[], void UsrWrk)	Aprod,
		void *	UsrWrk,
		double	anorm[]
	)

Compute the column norms of A.

Compute the columns norms of A. Each column of A is generated by multiplying A by a unit vector. The two-norm squared of each column is stored in aprod.

This routine must be called *after* bcls_create_prob. (As with any other BCLS routine.)

Parameters:

`[in]`	ls	BCLS problem context.
`[in]`	m	Number of rows in A.
`[in]`	n	Number of columns in A.
`[in]`	Aprod	User's matrix-product routine.
`[in,out]`	UsrWrk	Pointer to user's workspace (could be NULL).
`[out]`	anorm	Vector of column norms of A.

Returns:: Returns any error codes returned by the user's aprod routine.

Examples:: /examples/bcsol.c.

Definition at line 437 of file bcls.c.

References bcls_dload(), BCLS_MIN_COLUMN_NORM, cblas_dnrm2(), BCLS::ix, BCLS::wrk_u, and BCLS::wrk_v.

Here is the call graph for this function:

BCLS* bcls_create_prob	(	int	mmax,
		int	nmax
	)

Create a BCLS problem instance.

This routine create a BCLS problem. It *must* be called before any other BCLS routine. It will create and initialize a new BCLS problem with enough space to accomodate the specified problem. The problem is then initialized using bcls_init_prob.

In order to re-initialize the BCLS problem instance, but not deallocate memory that's already sufficient for an equal or smaller size problem, use bcls_init_prob.

Parameters:

`[in]`	mmax	Maximum number of rows in any A.
`[in]`	nmax	Maximum number of columns in any A.

Returns:: Return a pointer to a new BCLS problem. If the return is NULL, then the initialization failed.

Examples:: /examples/bcsol.c.

Definition at line 93 of file bcls.c.

References BCLS::aBreak, bcls_free_prob(), bcls_init_prob(), BCLS::dx, BCLS::dxFree, BCLS::g, BCLS::iBreak, imax(), BCLS::ix, BCLS::mmax, BCLS::nmax, BCLS::r, BCLS::wrk_u, BCLS::wrk_v, BCLS::wrk_w, and xmalloc().

Here is the call graph for this function:

char* bcls_exit_msg ( int flag )

Return an exit message.

Parameters:

[in] flag The code of the error.

Returns:: Error messsage.

Definition at line 536 of file bcls.c.

References BCLS_EXIT_APROD, BCLS_EXIT_CALLBK, BCLS_EXIT_CNVGD, BCLS_EXIT_INFEA, BCLS_EXIT_MAJOR, BCLS_EXIT_MINOR, BCLS_EXIT_UNBND, and BCLS_EXIT_USOLVE.

Referenced by bcls_solve_prob().

int bcls_free_prob ( BCLS * ls )

Free and reinitialize all resources in an existing BCLS problem.

Returns:

0: no errors
1: the BCLS problem is NULL (ie, does not exist).

Examples:: /examples/bcsol.c.

Definition at line 269 of file bcls.c.

References BCLS::aBreak, BCLS::dx, BCLS::dxFree, BCLS::g, BCLS::iBreak, BCLS::ix, BCLS::r, BCLS::wrk_u, BCLS::wrk_v, and BCLS::wrk_w.

Referenced by bcls_create_prob().

void bcls_init_prob ( BCLS * ls )

Initialize a BCLS problem.

Initialize a BCLS problem. You can call this routine to "reset" a BCLS problem, i.e., reset all parameter values. Note that it is automatically called by bcls_create_prob.

Parameters:

[in,out] ls BCLS problem context.

Definition at line 186 of file bcls.c.

References BCLS::anorm, BCLS::Aprod, BCLS::backtrack, BCLS::backtrack_limit, BCLS_EXIT_UNDEF, BCLS_INFINITY, BCLS_NEWTON_STEP_LSQR, BCLS_PROJ_SEARCH_EXACT, BCLS_SOLN_UNDEF, bcls_timer(), BCLS_TIMER_APROD, BCLS_TIMER_INIT, BCLS_TIMER_LSQR, BCLS_TIMER_TOTAL, BCLS_TIMER_USOLVE, BCLS::BigNum, BCLS::CallBack, BCLS::conlim, BCLS::damp, BCLS::damp_min, BCLS::eps, BCLS::eps2, BCLS::eps3, BCLS::epsfixed, BCLS::epsx, BCLS::exit, BCLS::fault_hook, BCLS::fault_info, BCLS::itnMaj, BCLS::itnMajLim, BCLS::itnMin, BCLS::itnMinLim, BCLS::m, BCLS::minor_file, BCLS::mmax, BCLS::mu, BCLS::n, BCLS_timer::name, BCLS::nAprod1, BCLS::nAprodF, BCLS::nAprodT, BCLS::newton_step, BCLS::nmax, BCLS::nUsolve, BCLS::optTol, BCLS::print_hook, BCLS::print_info, BCLS::print_level, BCLS::proj_search, BCLS::soln_dInf, BCLS::soln_jInf, BCLS::soln_rNorm, BCLS::soln_stat, BCLS::stopwatch, BCLS::unconstrained, BCLS::Usolve, and BCLS::UsrWrk.

Referenced by bcls_create_prob().

Here is the call graph for this function:

void bcls_set_anorm	(	BCLS *	ls,
		double	anorm[]
	)

Give BCLS access to set of column weights.

Define a set of column weights. BCLS will use these to scale the steepest-descent steps.

Parameters:

`[in,out]`	ls	BCLS problem context.
`[in]`	anorm	Array of columns norms of A.

Examples:: /examples/bcsol.c.

Definition at line 374 of file bcls.c.

References BCLS::anorm.

void bcls_set_fault_hook	(	BCLS *	ls,
		void *	info,
		int()(void info, char *msg)	hook
	)

Install a fault-hook routine.

This routine installs a user-defined fault-hook routine.

The parameter info is a transit pointer passed to the hook routine.

The parameter "hook" is an entry point to the user-defined fault-hook routine. This routine is called by the routine "bcls_fault" every time an error message should be output. The routine "bcls_fault" passes to the hook routine the transit pointer info and the character string msg, which contains the message. If the hook routine returns zero, the routine print prints the message in an usual way. Otherwise, if the hook routine returns non-zero, the message is not printed.

In order to uninstall the hook routine the parameter hook should be specified as NULL (in this case the parameter info is ignored).

Parameters:

`[in,out]`	ls	BCLS problem context.
`[in]`	info	Transit pointer passed to the hook routine.
`[in]`	hook	Pointer to the fault-hook routine.

Definition at line 353 of file bcls.c.

References BCLS::fault_hook, and BCLS::fault_info.

void bcls_set_print_hook	(	BCLS *	ls,
		void *	info,
		int()(void info, char *msg)	hook
	)

Install a print-hook routine.

This routine installs a user-defined print-hook routine.

The parameter info is a transit pointer passed to the hook routine.

The parameter hook is an entry point to the user-defined print-hook routine. This routine is called by the routine "print" every time an informative message should be output. The routine "print" passes to the hook routine the transit pointer info and the character string msg, which contains the message. If the hook routine returns zero, the routine print prints the message in an usual way. Otherwise, if the hook routine returns non-zero, the message is not printed.

In order to uninstall the hook routine the parameter hook should be specified as NULL (in this case the parameter info is ignored).

Parameters:

`[in,out]`	ls	BCLS problem context.
`[in]`	info	Transit pointer passed to the hook routine.
`[in]`	hook	Pointer to the print-hook routine.

Examples:: /examples/bcsol.c.

Definition at line 318 of file bcls.c.

References BCLS::print_hook, and BCLS::print_info.

void bcls_set_problem_data	(	BCLS *	ls,
		int	m,
		int	n,
		int()(int mode, int m, int n, int nix, int ix[], double x[], double y[], void UsrWrk)	Aprod,
		void *	UsrWrk,
		double	damp,
		double	x[],
		double	b[],
		double	c[],
		double	bl[],
		double	bu[]
	)

Load the problem into the BCLS data structure.

The routiens loads the complete problem description into a BCLS problem instance. No work is really being done: only the various structure elements are being set to point to the right places.

Parameters:

`[in,out]`	ls	BCLS problem context.
`[in]`	m	Number of rows in A. Note: m <= mmax.
`[in]`	n	Number of columns in A. Note: n <= nmax.
`[in]`	Aprod	Hook to user's matrix-vector product routine.
`[in,out]`	UsrWrk	Transit pointer passed directly to Aprod/Usolve.
`[in]`	damp	Regularization parameter.
`[in,out]`	x	The starting point.
`[in]`	b	The RHS vector.
`[in]`	c	Defines a linear term (set to NULL if one doesn't exist).
`[in]`	bl	Lower bounds on x.
`[in]`	bu	Upper bounds on x.