LWPR library (the low level C implementation)

Data Structures

struct  LWPR_ReceptiveField
 This structure completely describes a "receptive field" (a local linear model). More...
struct  LWPR_SubModel
 The structure LWPR_SubModel holds all the receptive fields (LWPR_ReceptiveField) that contribute to a particular output dimension of the complete LWPR_Model. More...
struct  LWPR_Model
 Main data structure for describing an LWPR model. More...

Files

file  lwpr.h
 

Main header file of the LWPR library.


file  lwpr_aux.h
 

LWPR auxiliary functions header file.


file  lwpr_binio.h
 

Prototypes for binary-IO related LWPR subroutines.


file  lwpr_math.h
 

Prototypes for some rather simple vector and matrix operations.


file  lwpr_mem.h
 

Prototypes for auxiliary LWPR routines that handle memory allocation and disposition.


file  lwpr_xml.h
 

Prototypes for XML related LWPR subroutines.


Defines

#define HAVE_LIBEXPAT   0
#define NUM_THREADS   1

Typedefs

typedef struct LWPR_Model LWPR_Model
 Main data structure for describing an LWPR model.

Enumerations

enum  LWPR_Kernel { LWPR_GAUSSIAN_KERNEL, LWPR_BISQUARE_KERNEL }

Functions

void lwpr_predict (const LWPR_Model *model, const double *x, double cutoff, double *y, double *conf, double *max_w)
 Computes the prediction of an LWPR model given an input vector x. Can also return confidence bounds and the maximal activation of all receptive fields.
void lwpr_predict_J (const LWPR_Model *model, const double *x, double cutoff, double *y, double *J)
 Computes the prediction and its derivatives (Jacobian) of an LWPR model given an input vector x.
void lwpr_predict_JcJ (const LWPR_Model *model, const double *x, double cutoff, double *y, double *J, double *conf, double *Jconf)
 Computes the predictions, the confidence intervals and the first derivatives of all the quantities.
void lwpr_predict_JH (const LWPR_Model *model, const double *x, double cutoff, double *y, double *J, double *H)
 Computes the prediction and its first and second derivatives of an LWPR model given an input vector x.
int lwpr_update (LWPR_Model *model, const double *x, const double *y, double *yp, double *max_w)
 Updates an LWPR model with a given input/output pair (x,y). Optionally returns the model's prediction for y and the maximal activation of all receptive fields.
int lwpr_init_model (LWPR_Model *model, int nIn, int nOut, const char *name)
 Initialises an LWPR model and allocates internally used storage for submodels etc.
void lwpr_free_model (LWPR_Model *model)
 Cleans up the LWPR_Model structure by disposing all internally allocated memory. Make sure you always call this function if you do not need the model anymore.
int lwpr_set_init_alpha (LWPR_Model *model, double alpha)
 Set the initial learning rate for 2nd order distance metric updates.
int lwpr_set_init_D_spherical (LWPR_Model *model, double sigma)
 Set a spherical initial distance metric for creating new receptive fields.
int lwpr_set_init_D_diagonal (LWPR_Model *model, const double *d)
 Set a diagonal initial distance metric for creating new receptive fields.
int lwpr_set_init_D (LWPR_Model *model, const double *D, int stride)
 Set initial distance metric for creating new receptive fields.
int lwpr_duplicate_model (LWPR_Model *dest, const LWPR_Model *src)
 Creates a duplicate (deep copy) of an LWPR model structure.
int lwpr_write_binary (const LWPR_Model *model, const char *filename)
 Writes an LWPR model to a file.
int lwpr_read_binary (LWPR_Model *model, const char *filename)
 Reads an LWPR model from a binary file.
int lwpr_write_binary_fp (const LWPR_Model *model, FILE *fp)
 Writes an LWPR model to a file.
int lwpr_read_binary_fp (LWPR_Model *model, FILE *fp)
 Reads an LWPR model from a binary file.
int lwpr_write_xml (const LWPR_Model *model, const char *filename)
 Writes an LWPR model to an XML file.
void lwpr_write_xml_fp (const LWPR_Model *model, FILE *fp)
 Writes an LWPR model to an XML file.
int lwpr_read_xml (LWPR_Model *model, const char *filename, int *numWarnings)
 Parse an LWPR model from an XML file.

Detailed Description

Define Documentation

#define HAVE_LIBEXPAT   0

Set HAVE_LIBEXPAT to 1 if you have the EXPAT library installed, and you need support for reading LWPR models from XML files. On Linux/UNIX, the configure script will take care of this automatically. On Windows, you need to set this variable yourself, and you also need to make sure that the compiler finds EXPAT's library and include files.

#define NUM_THREADS   1

Using this directive you can enable multi-threading at compile time. Set this to the desired number of threads. The number of cores in your machine is a good starting point, but how much speed improvement you get really depends on the machine, its configuration, and the learning task at hand.

Typedef Documentation

typedef struct LWPR_Model LWPR_Model

Main data structure for describing an LWPR model.

This structure contains flags and initial values that determine the behaviour of the LWPR algorithm, and also provides some statistics about the model.

It should always be initialised with lwpr_init_model, and destroyed with lwpr_free_model. Note that both functions do not allocate/free the space for the LWPR_Model itself.

Enumeration Type Documentation

enum LWPR_Kernel

Enumeration of locality kernels that the LWPR library toolbox provides. This determines how an activation (or weight) w is computed from a given input vector x and the centre c and distance metric D of a receptive field.

Enumerator:
LWPR_GAUSSIAN_KERNEL 

Receptive field activations will be computed using the Gaussian kernel

\[ w = \exp\left(-\frac{1}{2} (\mathbf{x-c})^T \mathbf{D(x-c)}\right)\]

This is the default setting after a call to lwpr_init_model().

LWPR_BISQUARE_KERNEL 

Receptive field activations will be computed using the Bisquare kernel

\[ w = \left\{\begin{array}{ll} \left(1 -\frac{1}{2} q\right)^2 & q < 2 \\ 0 & q\geq 2 \end{array}\right.,\quad\textnormal{where~} q = (\mathbf{x-c})^T \mathbf{D(x-c)}\]

Function Documentation

int lwpr_duplicate_model ( LWPR_Model *  dest,
const LWPR_Model *  src 
)

Creates a duplicate (deep copy) of an LWPR model structure.

Parameters:
[out] dest Pointer to an (uninitialised) LWPR_Model
[in] src Pointer to the LWPR_Model that should be duplicated
Returns:
  • 0 in case of failure (insufficient memory)
  • 1 in case of success

Referenced by LWPR_Object::LWPR_Object().

void lwpr_free_model ( LWPR_Model *  model  ) 

Cleans up the LWPR_Model structure by disposing all internally allocated memory. Make sure you always call this function if you do not need the model anymore.

Parameters:
[in] model The LWPR model structure whose contents should be disposed.

Note that this function does NOT free the memory of the LWPR_Model structure itself. Therefore, you should either use static or local variables like 

   LWPR_Model model;
   if (!lwpr_init_model(&model,10,2,"Just a demo")) { 
      error(...);
   }
   ...
   lwpr_free_model(&model);

or you have to do the malloc() and free() calls yourself, e.g. 

   LWPR_Model *pModel;
   pModel = malloc(sizeof(LWPR_Model));
   if (pModel == NULL || !lwpr_init_model(pModel,10,2,"2nd Demo")) { 
      error(...);
   }
   ... 
   lwpr_free_model(pModel);
   free(pModel);
See also:
lwpr_init_model

Referenced by LWPR_Object::~LWPR_Object().

int lwpr_init_model ( LWPR_Model *  model,
int  nIn,
int  nOut,
const char *  name 
)

Initialises an LWPR model and allocates internally used storage for submodels etc.

Parameters:
[in,out] model Must point to an LWPR_Model structure
[in] nIn Number of input dimensions
[in] nOut Number of output dimensions
[in] name Optional descriptive title. This string (if not NULL) is copied to internally managed memory.
Returns:
  • 1 in case of succes
  • 0 in case of failure (e.g. memory could not be allocated).

Note that "model" must already point to an LWPR_Model structure (e.g. a local variable),

See also:
lwpr_free_model

Referenced by LWPR_Object::LWPR_Object().

void lwpr_predict ( const LWPR_Model *  model,
const double *  x,
double  cutoff,
double *  y,
double *  conf,
double *  max_w 
)

Computes the prediction of an LWPR model given an input vector x. 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] x Input vector, must point to an array of nIn doubles
[in] cutoff A threshold parameter. Receptive fields with activation below the cutoff are ignored
[out] y Output vector, must point to an array of nOut doubles
[out] conf Confidence bounds per output dimension. Must be NULL or point to an array of nOut doubles
[out] max_w Maximum activation per output dimension. Must be NULL or point to an array of nOut doubles

Referenced by LWPR_Object::predict().

void lwpr_predict_J ( const LWPR_Model *  model,
const double *  x,
double  cutoff,
double *  y,
double *  J 
)

Computes the prediction and its derivatives (Jacobian) of an LWPR model given an input vector x.

Parameters:
[in] model Must point to a valid LWPR_Model structure
[in] x Input vector, must point to an array of nIn doubles
[in] cutoff A threshold parameter. Receptive fields with activation below the cutoff are ignored
[out] y Output vector, must point to an array of nOut doubles
[out] J Jacobian matrix, i.e. derivatives of output vector with respect to input vector. Must point to an array of nOut*nIn doubles. The matrix is stored in column-major order, that is, for a 3-D input x and 2-D output y the Jacobian

\[\mathbf{J} = \frac{\partial\mathbf{y}}{\partial\mathbf{x}} = \left(\begin{array}{ccc} \frac{\partial y_1}{\partial x_1} & \frac{\partial y_1}{\partial x_2} & \frac{\partial y_1}{\partial x_3}\medskip\\ \frac{\partial y_2}{\partial x_1} & \frac{\partial y_2}{\partial x_2} & \frac{\partial y_2}{\partial x_3} \\ \end{array}\right) = \left(\begin{array}{ccc} j_{11} & j_{12} & j_{13}\\ j_{21} & j_{22} & j_{23}\\ \end{array}\right) \]

is thus stored as 

   double J[6] = {j11,j21,j12,j22,j13,j23};
void lwpr_predict_JcJ ( const LWPR_Model *  model,
const double *  x,
double  cutoff,
double *  y,
double *  J,
double *  conf,
double *  Jconf 
)

Computes the predictions, the confidence intervals and the first derivatives of all the quantities.

Parameters:
[in] model Must point to a valid LWPR_Model structure
[in] x Input vector, must point to an array of nIn doubles
[in] cutoff A threshold parameter. Receptive fields with activation below the cutoff are ignored
[out] y Output vector, must point to an array of nOut doubles
[out] J Jacobian matrix, i.e. derivatives of output vector with respect to input vector. Must point to an array of nOut*nIn doubles.
[out] conf Confidence intervals, must point to an array of nOut doubles
[out] Jconf Jacobian of the confidences, must point to an array of nOut*nIn doubles.
void lwpr_predict_JH ( const LWPR_Model *  model,
const double *  x,
double  cutoff,
double *  y,
double *  J,
double *  H 
)

Computes the prediction and its first and second derivatives of an LWPR model given an input vector x.

Parameters:
[in] model Must point to a valid LWPR_Model structure
[in] x Input vector, must point to an array of nIn doubles
[in] cutoff A threshold parameter. Receptive fields with activation below the cutoff are ignored
[out] y Output vector, must point to an array of nOut doubles
[out] J Jacobian matrix, i.e. derivatives of output vector with respect to input vector. Must point to an array of nOut*nIn doubles.
[out] H Hessian matrices, i.e. 2nd derivatives of output vector with respect to input vector. Must point to an array of nIn*nIn*nOut doubles. The Hessians for each output dimension are stored one after another.
int lwpr_read_binary ( LWPR_Model *  model,
const char *  filename 
)

Reads an LWPR model from a binary file.

Parameters:
[in,out] model Pointer to a valid LWPR model structure
[in] filename Name of the file to read the model from
Returns:
  • 0 if errors have occured
  • 1 on success

Referenced by LWPR_Object::LWPR_Object().

int lwpr_read_binary_fp ( LWPR_Model *  model,
FILE *  fp 
)

Reads an LWPR model from a binary file.

Parameters:
[in,out] model Pointer to a valid LWPR model structure
[in] fp Descriptor of an already opened file (see stdio.h)
Returns:
  • 0 if errors have occured
  • 1 on success
int lwpr_read_xml ( LWPR_Model *  model,
const char *  filename,
int *  numWarnings 
)

Parse an LWPR model from an XML file.

Parameters:
[in] model Pointer to a valid LWPR model structure
[in] filename Name of the XML file
[out] numWarnings Number of warnings encountered during parsing
Returns:
The number of errors encountered during parsing, which is >= 10000 if the XML structure itself is invalid (as detected by EXPAT). An example of other errors (each counted as 1) is an invalid number of elements in vectors and matrices. If the file could not be opened for reading, the function returns -1.

If the library has been compiled without EXPAT support, this function is just a dummy and returns -2.

Referenced by LWPR_Object::LWPR_Object().

int lwpr_set_init_alpha ( LWPR_Model *  model,
double  alpha 
)

Set the initial learning rate for 2nd order distance metric updates.

Parameters:
[in,out] model Pointer to a valid LWPR_Model
[in] alpha Scalar learning rate (the same for all elements of the distance metric)
Returns:
  • 0 in case of failure (alpha <= 0)
  • 1 in case of success

Referenced by LWPR_Object::setInitAlpha().

int lwpr_set_init_D ( LWPR_Model *  model,
const double *  D,
int  stride 
)

Set initial distance metric for creating new receptive fields.

Parameters:
[in,out] model Pointer to a valid LWPR_Model
[in] D Symmetric, positive definite distance metric. Must point to an array of at least nIn*stride doubles.
[in] stride Offset between the first element of different columns of D. Pass nIn if the matrix is stored densely, that is, without any space between adjacent columns.
Returns:
  • 0 in case of failure (D not positive definite)
  • 1 in case of success

Referenced by LWPR_Object::setInitD().

int lwpr_set_init_D_diagonal ( LWPR_Model *  model,
const double *  d 
)

Set a diagonal initial distance metric for creating new receptive fields.

Parameters:
[in,out] model Pointer to a valid LWPR_Model
[in] d Diagonal elements of the distance metric (must be >= 0). d must point to an array of nIn doubles
Returns:
  • 0 in case of failure (any d[i] <= 0)
  • 1 in case of success

Referenced by LWPR_Object::setInitD().

int lwpr_set_init_D_spherical ( LWPR_Model *  model,
double  sigma 
)

Set a spherical initial distance metric for creating new receptive fields.

Parameters:
[in,out] model Pointer to a valid LWPR_Model
[in] sigma Scale parameter of the distance metric, larger values imply narrower kernels
Returns:
  • 0 in case of failure (sigma <= 0)
  • 1 in case of success

Referenced by LWPR_Object::setInitD().

int lwpr_update ( LWPR_Model *  model,
const double *  x,
const double *  y,
double *  yp,
double *  max_w 
)

Updates an LWPR model with a given input/output pair (x,y). Optionally returns the model's prediction for y and the maximal activation of all receptive fields.

Parameters:
[in,out] model Must point to a valid LWPR_Model structure
[in] x Input vector, must point to an array of nIn doubles
[in] y Output vector, must point to an array of nOut doubles
[out] yp Current prediction given x. Must be NULL or point to an array of nOut doubles
[out] max_w Maximum activation per output dimension. Must be NULL or point to an array of nOut doubles
Returns:
  • 1 if the update was succesful
  • 0 if a receptive field would have to be added, but the necessary memory could not be allocated.

Referenced by LWPR_Object::update().

int lwpr_write_binary ( const LWPR_Model *  model,
const char *  filename 
)

Writes an LWPR model to a file.

Parameters:
[in] model Pointer to a valid LWPR model structure
[in] filename The name of the file
Returns:
  • 0 if errors have occured
  • 1 on success

Referenced by LWPR_Object::writeBinary().

int lwpr_write_binary_fp ( const LWPR_Model *  model,
FILE *  fp 
)

Writes an LWPR model to a file.

Parameters:
[in] model Pointer to a valid LWPR model structure
[in] fp Descriptor of an already opened file (see stdio.h)
Returns:
  • 0 if errors have occured
  • 1 on success
int lwpr_write_xml ( const LWPR_Model *  model,
const char *  filename 
)

Writes an LWPR model to an XML file.

Parameters:
[in] model Pointer to a valid LWPR model structure
[in] filename Name of the XML file to write the model to
Returns:
  • 0 in case of failure (e.g. file could not be opened for writing)
  • 1 in case of success

Referenced by LWPR_Object::writeXML().

void lwpr_write_xml_fp ( const LWPR_Model *  model,
FILE *  fp 
)

Writes an LWPR model to an XML file.

Parameters:
[in] model Pointer to a valid LWPR model structure
[in] fp Descriptor of an already opened file (see stdio.h)
Generated on Thu Feb 9 08:18:35 2012 for LWPR Library by  doxygen 1.6.3