include/lwpr_aux.h File Reference

LWPR auxiliary functions header file. More...

Data Structures
struct	LWPR_Workspace
	LWPR_Workspace is a structure that contains enough "working memory" for the LWPR computational routines. More...
struct	LWPR_ThreadData
	Data structure that is passed to each thread for updates or predictions. More...
Typedefs
typedef struct LWPR_Workspace	LWPR_Workspace
	LWPR_Workspace is a structure that contains enough "working memory" for the LWPR computational routines.
Functions
void	lwpr_aux_dist_derivatives (int nIn, int nInS, double dwdM, double dJ2dM, double ddwdMdM, double ddJ2dMdM, double w, double dwdq, double ddwdqdq, const double RF_D, const double RF_M, const double *dx, int diag_only, double penalty, int meta)
	Computes the derivates of the activation w and a penalty term with respect to M, Cholesky factors of the distance metric.
double	lwpr_aux_update_distance_metric (LWPR_ReceptiveField RF, double w, double dwdq, double ddwdqdq, double e_cv, double e, const double xn, LWPR_Workspace *ws)
	Performs an update of a receptive field's distance metric.
double	lwpr_aux_update_means (LWPR_ReceptiveField RF, const double x, double y, double w, double *xmz)
	Performs an update of the receptive field's statistics (weighted mean input and output).
void	lwpr_aux_compute_projection_r (int nIn, int nInS, int nReg, double s, double xres, const double x, const double U, const double *P)
	Computes the PLS projections and its residuals given regression axes U, projection axes P, and an input vector x.
void	lwpr_aux_compute_projection (int nIn, int nInS, int nReg, double s, const double x, const double U, const double P, LWPR_Workspace *ws)
	Computes the PLS projections given regression axes U, projection axes P, and an input vector x.
void	lwpr_aux_compute_projection_d (int nIn, int nInS, int nReg, double s, double dsdx, const double x, const double U, const double P, LWPR_Workspace ws)
	Computes the PLS projections and their derivatives given regression axes U, projection axes P, and an input vector x.
void	lwpr_aux_update_regression (LWPR_ReceptiveField RF, double yp, double e_cv, double e, const double x, double y, double w, LWPR_Workspace ws)
	Performs an update on the regression parameters of one receptive field.
LWPR_ReceptiveField *	lwpr_aux_add_rf (LWPR_SubModel *sub, int nReg)
	Adds a new receptive field to the specified LWPR_SubModel. Regression parameters etc. are not initialised.
int	lwpr_aux_check_add_projection (LWPR_ReceptiveField *RF)
	Check if a receptive field needs another PLS regression axis, and modify the relevant variables.
int	lwpr_aux_init_rf (LWPR_ReceptiveField RF, const LWPR_Model model, const LWPR_ReceptiveField RFT, const double xc, double y)
	Allocates and initialises the variables of a receptive field.
int	lwpr_aux_update_one (LWPR_Model model, int dim, const double xn, double yn, double y_pred, double max_w)
	Update the receptive fields specific to one output dimension of the LWPR model.
void *	lwpr_aux_update_one_T (void *ptr)
	Thread function for updating a subset of receptive fields.
int	lwpr_aux_update_one_add_prune (LWPR_Model model, LWPR_ThreadData TD, int dim, const double *xn, double yn)
	Update the receptive fields specific to one output dimension of the LWPR model.
double	lwpr_aux_predict_one (const LWPR_Model model, int dim, const double xn, double cutoff, double conf, double max_w)
	Computes the prediction of an LWPR model for a specific output dimension. Can also return confidence bounds and the maximal activation of all receptive fields.
void *	lwpr_aux_predict_one_T (void *ptr)
	Thread function for predicting the output for one SubModel.
void *	lwpr_aux_predict_conf_one_T (void *ptr)
	Computes the prediction of an LWPR model for a specific output dimension, together with its confidence bounds.
double	lwpr_aux_predict_one_J (const LWPR_Model model, int dim, const double xn, double cutoff, double *dydx)
	Computes the prediction of an LWPR model for a specific output dimension, and also the gradient of that prediction with respect to the input vector.
double	lwpr_aux_predict_one_JcJ (const LWPR_Model model, int dim, const double xn, double cutoff, double dydx, double conf, double *dcdx)
	Computes the prediction of an LWPR model for a specific output dimension, the confidence interval for the predictions, and also the gradients of both quantities with respect to the input vector.
double	lwpr_aux_predict_one_gH (const LWPR_Model model, int dim, const double xn, double cutoff, double dydx, double ddydxdx)
	Computes the prediction of an LWPR model for a specific output dimension, and also the gradient of that prediction with respect to the input vector.
void *	lwpr_aux_predict_one_J_T (void *ptr)
	Thread function for predicting output and gradient for one SubModel.
void *	lwpr_aux_predict_one_JcJ_T (void *ptr)
	Thread function for predicting output and gradient for one SubModel.
void *	lwpr_aux_predict_one_gH_T (void *ptr)
	Thread function for predicting output, gradient and Hessian for one SubModel.
void	lwpr_aux_update_model_stats (LWPR_Model model, const double x)
	Updates the global model statistics, i.e. the mean and variance of the input training data, and also the number of data points.

Detailed Description

LWPR auxiliary functions header file.

Typedef Documentation

typedef struct LWPR_Workspace LWPR_Workspace

LWPR_Workspace is a structure that contains enough "working memory" for the LWPR computational routines.

It is automatically allocated within lwpr_init_model, with one LWPR_Workspace structure per thread. You should not have to handle any of its elements yourself.

Function Documentation

LWPR_ReceptiveField* lwpr_aux_add_rf	(	LWPR_SubModel *	sub,
		int	nReg
	)

Adds a new receptive field to the specified LWPR_SubModel. Regression parameters etc. are not initialised.

Parameters:

`[in,out]`	sub	LWPR_SubModel specific to one output dimension
`[in]`	nReg	Number of PLS regression directions

Returns:: Pointer to the newly created receptive field (is also linked in sub->rf[...])

int lwpr_aux_check_add_projection ( LWPR_ReceptiveField * RF )

Check if a receptive field needs another PLS regression axis, and modify the relevant variables.

Parameters:

[in,out] RF Pointer to the receptive field

Returns:

0 if a new axis was not needed
1 if a new axis was added
-1 if a new axis was needed, but the necessary memory reallocation could not be done.

void lwpr_aux_compute_projection	(	int	nIn,
		int	nInS,
		int	nReg,
		double *	s,
		const double *	x,
		const double *	U,
		const double *	P,
		LWPR_Workspace *	ws
	)

Computes the PLS projections given regression axes U, projection axes P, and an input vector x.

Parameters:

`[in]`	nIn	Number of input dimensions
`[in]`	nInS	Storage length (stride) of matrices U, P and xres
`[in]`	nReg	Number of PLS regression directions
`[out]`	s	PLS projections (nReg)
`[in]`	x	Input vector (nIn)
`[in]`	U	PLS regression axes (nIn x nReg)
`[in]`	P	PLS projection axes (nIn x nReg)
`[in,out]`	ws	Pointer to workspace for intermediate results

void lwpr_aux_compute_projection_d	(	int	nIn,
		int	nInS,
		int	nReg,
		double *	s,
		double *	dsdx,
		const double *	x,
		const double *	U,
		const double *	P,
		LWPR_Workspace *	ws
	)

Computes the PLS projections and their derivatives given regression axes U, projection axes P, and an input vector x.

Parameters:

`[in]`	nIn	Number of input dimensions
`[in]`	nInS	Storage length (stride) of matrices U, P and xres
`[in]`	nReg	Number of PLS regression directions
`[out]`	s	PLS projections (nReg)
`[out]`	dsdx	Derivatives of s with respect to x in transposed form (nIn x nReg)
`[in]`	x	Input vector (nIn)
`[in]`	U	PLS regression axes (nIn x nReg)
`[in]`	P	PLS projection axes (nIn x nReg)
`[in,out]`	ws	Pointer to workspace for intermediate results

void lwpr_aux_compute_projection_r	(	int	nIn,
		int	nInS,
		int	nReg,
		double *	s,
		double *	xres,
		const double *	x,
		const double *	U,
		const double *	P
	)

Computes the PLS projections and its residuals given regression axes U, projection axes P, and an input vector x.

Parameters:

`[in]`	nIn	Number of input dimensions
`[in]`	nInS	Storage length (stride) of matrices U, P and xres
`[in]`	nReg	Number of PLS regression directions
`[out]`	s	PLS projections (nReg)
`[out]`	xres	Residuals of input vector after each projection step (nIn x nReg)
`[in]`	x	Input vector (nIn)
`[in]`	U	PLS regression axes (nIn x nReg)
`[in]`	P	PLS projection axes (nIn x nReg)

void lwpr_aux_dist_derivatives	(	int	nIn,
		int	nInS,
		double *	dwdM,
		double *	dJ2dM,
		double *	ddwdMdM,
		double *	ddJ2dMdM,
		double	w,
		double	dwdq,
		double	ddwdqdq,
		const double *	RF_D,
		const double *	RF_M,
		const double *	dx,
		int	diag_only,
		double	penalty,
		int	meta
	)

Computes the derivates of the activation w and a penalty term with respect to M, Cholesky factors of the distance metric.

Parameters:

`[in]`	nIn	Number of input dimensions
`[in]`	nInS	Offset between columns in matrices (stride)
`[out]`	dwdM	Derivative of w with respect to M (nIn x nIn)
`[out]`	dJ2dM	Derivative of penalty term J2 to M (nIn x nIn)
`[out]`	ddwdMdM	2nd derivative of w with respect to M (nIn x nIn)
`[out]`	ddJ2dMdM	2nd derivative of J2 with respect to M (nIn x nIn)
`[in]`	w	Activation of receptive field
`[in]`	dwdq	Derivative of w with respect to squared distance (~ outer derivate of the kernel)
`[in]`	ddwdqdq	2nd derivative of w with respect to squared distance
`[in]`	RF_D	The receptive field's distance metric (nIn x nIn)
`[in]`	RF_M	The Cholesky factorisation of RF_M (nIn x nIn)
`[in]`	dx	The difference between the normalised input x and the receptive fields centre c (nIn x 1)
`[in]`	diag_only	Flag that determines whether the distance metric is to be treated as diagonal
`[in]`	penalty	Pre-factor involved in computation of J2
`[in]`	meta	Flag that determines whether 2nd derivatives should be computed

int lwpr_aux_init_rf	(	LWPR_ReceptiveField *	RF,
		const LWPR_Model *	model,
		const LWPR_ReceptiveField *	RFT,
		const double *	xc,
		double	y
	)

Allocates and initialises the variables of a receptive field.

Parameters:

`[in,out]`	RF	Pointer to the receptive field to be initialised
`[in]`	model	Pointer to the LWPR model the RF belongs to
`[in]`	RFT	Pointer to a template receptive field (distance metric will be copied), may also be NULL
`[in]`	xc	Input vector (nIn), will be the receptive field's center
`[in]`	y	Output sample (submodel) specific), will be the receptive fields initial bias beta0

Returns:

0 if the necessary memory could not be allocated
1 in case of success

void* lwpr_aux_predict_conf_one_T ( void * ptr )

Computes the prediction of an LWPR model for a specific output dimension, together with its confidence bounds.

Parameters:

[in,out] ptr Pointer to an LWPR_ThreadData structure

Returns:: NULL

You must set the following fields of the LWPR_ThreadData structure that ptr points to:

model Must point to a valid LWPR_Model structure
dim Specific output dimension to handle
xn Input vector, must point to an array of model->nIn doubles
cutoff A threshold parameter. Receptive fields with activation below the cutoff are ignored

On return, you may read the following fields:

yn Prediction of the LWPR model along dimension dim (not yet normalised)
w_max Maximum activation per output dimension. May be NULL.
w_sec Confidence bounds for predicted output

double lwpr_aux_predict_one	(	const LWPR_Model *	model,
		int	dim,
		const double *	xn,
		double	cutoff,
		double *	conf,
		double *	max_w
	)

Computes the prediction of an LWPR model for a specific output dimension. Can also return confidence bounds and the maximal activation of all receptive fields.

Parameters:

`[in]`	model	Must point to a valid LWPR_Model structure
`[in]`	dim	Specific output dimension to handle
`[in]`	xn	Input vector, must point to an array of model->nIn doubles
`[in]`	cutoff	A threshold parameter. Receptive fields with activation below the cutoff are ignored
`[out]`	conf	Confidence bounds per output dimension. May be NULL.
`[out]`	max_w	Maximum activation per output dimension. May be NULL.

Returns:: The predicted output value

This function does not do any calculation itself. It just calls either lwpr_aux_predict_one_T or lwpr_aux_predict_conf_T, which are written with a less user-friendly, but thread-friendly interface.

double lwpr_aux_predict_one_gH	(	const LWPR_Model *	model,
		int	dim,
		const double *	xn,
		double	cutoff,
		double *	dydx,
		double *	ddydxdx
	)

Computes the prediction of an LWPR model for a specific output dimension, and also the gradient of that prediction with respect to the input vector.

Parameters:

`[in]`	model	Must point to a valid LWPR_Model structure
`[in]`	dim	Specific output dimension to handle
`[in]`	xn	Input vector, must point to an array of model->nIn doubles
`[in]`	cutoff	A threshold parameter. Receptive fields with activation below the cutoff are ignored
`[out]`	dydx	Gradient. Must point to an array of nIn doubles
`[out]`	ddydxdx	Hessian. Must point to an array of nIn x nIn doubles

Returns:: The predicted output value

This function does not perform any calculations itself, but just calls lwpr_aux_predict_one_gH_T()

See also:: lwpr_aux_predict_one

void* lwpr_aux_predict_one_gH_T ( void * ptr )

Thread function for predicting output, gradient and Hessian for one SubModel.

Parameters:

[in,out] ptr Pointer to an LWPR_ThreadData structure

Returns:: NULL

You must set the following fields of the LWPR_ThreadData structure that ptr points to:

model Must point to a valid LWPR_Model structure
dim Specific output dimension to handle
xn Input vector, must point to an array of model->nIn doubles
cutoff A threshold parameter. Receptive fields with activation below the cutoff are ignored

On return, you may read the following fields:

yn Prediction of the LWPR model along dimension dim (not yet normalised)
sum_dwdx (within LWPR_Workspace pointed to by LWPR_ThreadData) Gradient of yn w.r.t. xn
sum_ddwdxdx (within LWPR_Workspace pointed to by LWPR_ThreadData) Hessian of yn w.r.t. xn

double lwpr_aux_predict_one_J	(	const LWPR_Model *	model,
		int	dim,
		const double *	xn,
		double	cutoff,
		double *	dydx
	)

Computes the prediction of an LWPR model for a specific output dimension, and also the gradient of that prediction with respect to the input vector.

Parameters:

`[in]`	model	Must point to a valid LWPR_Model structure
`[in]`	dim	Specific output dimension to handle
`[in]`	xn	Input vector, must point to an array of model->nIn doubles
`[in]`	cutoff	A threshold parameter. Receptive fields with activation below the cutoff are ignored
`[out]`	dydx	Gradient. Must point to an array of nIn doubles

Returns:: The predicted output value

This function does not perform any calculations itself, but just calls lwpr_aux_predict_conf_one_J_T()

See also:: lwpr_aux_predict_one

void* lwpr_aux_predict_one_J_T ( void * ptr )

Thread function for predicting output and gradient for one SubModel.

Parameters:

[in,out] ptr Pointer to an LWPR_ThreadData structure

Returns:: NULL

You must set the following fields of the LWPR_ThreadData structure that ptr points to:

model Must point to a valid LWPR_Model structure
dim Specific output dimension to handle
xn Input vector, must point to an array of model->nIn doubles
cutoff A threshold parameter. Receptive fields with activation below the cutoff are ignored

On return, you may read the following fields:

yn Prediction of the LWPR model along dimension dim (not yet normalised)
sum_dwdx (within LWPR_Workspace pointed to by LWPR_ThreadData) Gradient of yn w.r.t. xn

double lwpr_aux_predict_one_JcJ	(	const LWPR_Model *	model,
		int	dim,
		const double *	xn,
		double	cutoff,
		double *	dydx,
		double *	conf,
		double *	dcdx
	)

Computes the prediction of an LWPR model for a specific output dimension, the confidence interval for the predictions, and also the gradients of both quantities with respect to the input vector.

Parameters:

`[in]`	model	Must point to a valid LWPR_Model structure
`[in]`	dim	Specific output dimension to handle
`[in]`	xn	Input vector, must point to an array of model->nIn doubles
`[in]`	cutoff	A threshold parameter. Receptive fields with activation below the cutoff are ignored
`[out]`	dydx	Gradient of the prediction. Must point to an array of nIn doubles
`[out]`	conf	Confidence interval. Must point to a double
`[out]`	dcdx	Gradient of the confidence interval. Must point to an array of nIn doubles.

Returns:: The predicted output value y

This function does not perform any calculations itself, but just calls lwpr_aux_predict_conf_one_J_T()

See also:: lwpr_aux_predict_one

void* lwpr_aux_predict_one_JcJ_T ( void * ptr )

Thread function for predicting output and gradient for one SubModel.

Parameters:

[in,out] ptr Pointer to an LWPR_ThreadData structure

Returns:: NULL

You must set the following fields of the LWPR_ThreadData structure that ptr points to:

model Must point to a valid LWPR_Model structure
dim Specific output dimension to handle
xn Input vector, must point to an array of model->nIn doubles
cutoff A threshold parameter. Receptive fields with activation below the cutoff are ignored

On return, you may read the following fields (within LWPR_Workspace pointed to by LWPR_ThreadData)

yn Prediction of the LWPR model along dimension dim (not yet normalised)
sum_ydwdx_wdydx Gradient of yn w.r.t. xn
w_sec Confidence interval
sum_ddRdxdx Gradient of w_sec w.r.t. xn

void* lwpr_aux_predict_one_T ( void * ptr )

Thread function for predicting the output for one SubModel.

Parameters:

[in,out] ptr Pointer to an LWPR_ThreadData structure

Returns:: NULL

You must set the following fields of the LWPR_ThreadData structure that ptr points to:

model Must point to a valid LWPR_Model structure
dim Specific output dimension to handle
xn Input vector, must point to an array of model->nIn doubles
cutoff A threshold parameter. Receptive fields with activation below the cutoff are ignored

On return, you may read the following fields:

yn Prediction of the LWPR model along dimension dim (not yet normalised)
w_max Maximum activation per output dimension. May be NULL.

double lwpr_aux_update_distance_metric	(	LWPR_ReceptiveField *	RF,
		double	w,
		double	dwdq,
		double	ddwdqdq,
		double	e_cv,
		double	e,
		const double *	xn,
		LWPR_Workspace *	ws
	)

Performs an update of a receptive field's distance metric.

Parameters:

`[in,out]`	RF	Pointer to the receptive field
`[in]`	w	Activation of receptive field
`[in]`	dwdq	Derivative of w with respect to squared distance (~ outer derivate of the kernel)
`[in]`	ddwdqdq	2nd derivative of w with respect to squared distance
`[in]`	e_cv	Current cross-validation error of the RF
`[in]`	e	Current (non-CV) error
`[in]`	xn	Normalised input vector (nIn x 1)
`[in]`	ws	Pointer to working memory that may be used

Returns:: The "transient multiplier" used to dampen the distance metric updates

double lwpr_aux_update_means	(	LWPR_ReceptiveField *	RF,
		const double *	x,
		double	y,
		double	w,
		double *	xmz
	)

Performs an update of the receptive field's statistics (weighted mean input and output).

Parameters:

`[in,out]`	RF	Pointer to the receptive field
`[in]`	x	Normalised input vector (nIn)
`[in]`	y	Normalised output (specific to current output dimension)
`[in]`	w	Activation of receptive field
`[out]`	xmz	Distance between x and updated weighted mean (nIn)

Returns:: Difference between y and updated weighted mean output

void lwpr_aux_update_model_stats	(	LWPR_Model *	model,
		const double *	x
	)

Updates the global model statistics, i.e. the mean and variance of the input training data, and also the number of data points.

Parameters:

`[in,out]`	model	Pointer to an LWPR model structure
`[in]`	x	Input vector x (nIn, not normalised)

int lwpr_aux_update_one	(	LWPR_Model *	model,
		int	dim,
		const double *	xn,
		double	yn,
		double *	y_pred,
		double *	max_w
	)

Update the receptive fields specific to one output dimension of the LWPR model.

Parameters:

`[in,out]`	model	Pointer to the LWPR model
`[in]`	dim	Output dimension to handle [0 ; nOut-1]
`[in]`	xn	Normalised input vector (nIn)
`[in]`	yn	Normalised input sample (specific to output dimension "dim")
`[out]`	y_pred	Prediction for yn after update
`[out]`	max_w	Maximum activation over all receptive fields

Returns:

1 in case of success
0 if a receptive field would have to be added, but memory allocation failed

int lwpr_aux_update_one_add_prune	(	LWPR_Model *	model,
		LWPR_ThreadData *	TD,
		int	dim,
		const double *	xn,
		double	yn
	)

Update the receptive fields specific to one output dimension of the LWPR model.

Parameters:

`[in,out]`	model	Pointer to the LWPR model
`[in]`	TD	Pointer to an LWPR_ThreadData structure
`[in]`	dim	Specific output dimension to handle
`[in]`	xn	Normalised input vector (nIn)
`[in]`	yn	Normalised input sample (specific to output dimension "dim")

Returns:

1 in case of success
0 if a receptive field would have to be added, but memory allocation failed

void* lwpr_aux_update_one_T ( void * ptr )

Thread function for updating a subset of receptive fields.

Parameters:

[in] ptr Pointer to an LWPR_ThreadData structure

Returns:: NULL

void lwpr_aux_update_regression	(	LWPR_ReceptiveField *	RF,
		double *	yp,
		double *	e_cv,
		double *	e,
		const double *	x,
		double	y,
		double	w,
		LWPR_Workspace *	ws
	)

Performs an update on the regression parameters of one receptive field.

Parameters:

`[in,out]`	RF	Pointer to the receptive field
`[out]`	yp	Predicted output of the receptive field AFTER the update
`[out]`	e_cv	cross-validation error (prediction before update) (nReg)
`[out]`	e	Prediction error (after the update)
`[in]`	x	Input vector sample (nIn)
`[in]`	y	Output/target sample (specific for one output dimension)
`[in]`	w	Activation of the receptive field given x
`[in,out]`	ws	Pointer to workspace for intermediate results

include/lwpr_aux.h File Reference

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation