Main Page | Modules | Class List | File List | Class Members | File Members

Pseudo-Inverse of a General Size Matrix
[General Size Matrices]


Classes

struct  Gan_PseudoInverseStruct
struct  Gan_PseudoInverseStruct_f

Defines

#define gel(M, i, j)   gan_mat_get_el(M,i,j)
#define sel(M, i, j, v)   gan_mat_set_el(M,i,j,v)
#define sgel(M, i, j)   gan_squmat_get_el(M,i,j)
#define ssel(M, i, j, v)   gan_squmat_set_el(M,i,j,v)
#define vgel(M, i)   gan_vec_get_el(M,i)
#define vsel(M, i, v)   gan_vec_set_el(M,i,v)
#define gel(M, i, j)   gan_matf_get_el(M,i,j)
#define sel(M, i, j, v)   gan_matf_set_el(M,i,j,v)
#define sgel(M, i, j)   gan_squmatf_get_el(M,i,j)
#define ssel(M, i, j, v)   gan_squmatf_set_el(M,i,j,v)
#define vgel(M, i)   gan_vecf_get_el(M,i)
#define vsel(M, i, v)   gan_vecf_set_el(M,i,v)

Functions

Gan_PseudoInverseStructgan_pseudoinv_form (Gan_PseudoInverseStruct *pis, long max_asize, long max_bsize)
 Forms a pseudo-inverse equation solving structure.
void gan_pseudoinv_free (Gan_PseudoInverseStruct *pis)
 Frees a pseudo-inverse equation solving structure.
Gan_Bool gan_pseudoinv_reset (Gan_PseudoInverseStruct *pis, long asize, long bsize)
 Initialises a pseudo-inverse equation solver to zero.
Gan_Bool gan_pseudoinv_increment (Gan_PseudoInverseStruct *pis, double scale,...)
 Decrements a pseudo-inverse equation solver.
Gan_Bool gan_pseudoinv_decrement (Gan_PseudoInverseStruct *pis, double scale,...)
 Decrements a pseudo-inverse equation solver.
Gan_Bool gan_pseudoinv_set_constraint (Gan_PseudoInverseStruct *pis, Gan_Matrix *C, Gan_Matrix *D)
 Build a constraint into a system of linear equations.
Gan_Bool gan_pseudoinv_set_null_space (Gan_PseudoInverseStruct *pis, int null_space)
 Sets the size of the null space in a system of linear equations.
Gan_Bool gan_pseudoinv_set_ratio_thres (Gan_PseudoInverseStruct *pis, double ratio_thres)
 Sets the threshold on singular value ratios.
Gan_Bool gan_pseudoinv_set_low_values_allowed (Gan_PseudoInverseStruct *pis, int low_values_allowed)
 Sets the number of allowed low singular values.
Gan_Bool gan_pseudoinv_solve (Gan_PseudoInverseStruct *pis, int *error_code)
 Solve an accumulated system of linear equations.
Gan_Matrixgan_pseudoinv_get_solution (Gan_PseudoInverseStruct *pis)
 Return solution of an accumulated system of linear equations.
Gan_Vectorgan_pseudoinv_get_null_vector (Gan_PseudoInverseStruct *pis)
 Return a null vector from the solution space.
Gan_PseudoInverseStructgan_pseudoinv_alloc (long max_asize, long max_bsize)
 Macro: Allocates a pseudo-inverse equation solving structure.
Gan_PseudoInverseStruct_fgan_pseudoinvf_form (Gan_PseudoInverseStruct_f *pis, long max_asize, long max_bsize)
 Forms a pseudo-inverse equation solving structure.
void gan_pseudoinvf_free (Gan_PseudoInverseStruct_f *pis)
 Frees a pseudo-inverse equation solving structure.
Gan_Bool gan_pseudoinvf_reset (Gan_PseudoInverseStruct_f *pis, long asize, long bsize)
 Initialises a pseudo-inverse equation solver to zero.
Gan_Bool gan_pseudoinvf_increment (Gan_PseudoInverseStruct_f *pis, float scale,...)
 Decrements a pseudo-inverse equation solver.
Gan_Bool gan_pseudoinvf_decrement (Gan_PseudoInverseStruct_f *pis, float scale,...)
 Decrements a pseudo-inverse equation solver.
Gan_Bool gan_pseudoinvf_set_constraint (Gan_PseudoInverseStruct_f *pis, Gan_Matrix_f *C, Gan_Matrix_f *D)
 Build a constraint into a system of linear equations.
Gan_Bool gan_pseudoinvf_set_null_space (Gan_PseudoInverseStruct_f *pis, int null_space)
 Sets the size of the null space in a system of linear equations.
Gan_Bool gan_pseudoinvf_set_ratio_thres (Gan_PseudoInverseStruct_f *pis, float ratio_thres)
 Sets the threshold on singular value ratios.
Gan_Bool gan_pseudoinvf_set_low_values_allowed (Gan_PseudoInverseStruct_f *pis, int low_values_allowed)
 Sets the number of allowed low singular values.
Gan_Bool gan_pseudoinvf_solve (Gan_PseudoInverseStruct_f *pis, int *error_code)
 Solve an accumulated system of linear equations.
Gan_Matrix_fgan_pseudoinvf_get_solution (Gan_PseudoInverseStruct_f *pis)
 Return solution of an accumulated system of linear equations.
Gan_Vector_fgan_pseudoinvf_get_null_vector (Gan_PseudoInverseStruct_f *pis)
 Return a null vector from the solution space.
Gan_PseudoInverseStruct_fgan_pseudoinvf_alloc (long max_asize, long max_bsize)
 Macro: Allocates a pseudo-inverse equation solving structure.

Function Documentation

Gan_PseudoInverseStruct* gan_pseudoinv_alloc long  max_asize,
long  max_bsize
 

Macro: Allocates a pseudo-inverse equation solving structure.

Parameters:
max_asize The envisaged largest size of the matrix
max_bsize The envisaged largest number of solution vectors
Returns:
Pointer to the allocated structure, or NULL on failure.
Allocates/fills a structure with initial values to compute the pseudo-inverse solution of a system of linear equations.

Macro call to gan_pseudoinv_form().

See also:
gan_pseudoinv_form().

Gan_Bool gan_pseudoinv_decrement Gan_PseudoInverseStruct pis,
double  scale,
  ...
 

Decrements a pseudo-inverse equation solver.

Parameters:
pis A pointer to a structure
scale A scaling for the equations
... A variable argument list of vector components
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Decrements a system of linear equations

\[ A\:X = B \]

to be solved by pseudo-inverse:

\[ X = (A^{\top} A)^{-1} A^{\top} B \]

This function takes the variable argument list of elements of a vectors a and b, of sizes equal to the asize and bsize arguments to the most recent call to gan_pseudoinv_reset() on the pis structure. The matrix $ (A^{\top} A) $ is decremented by $ s\:a\:a^{\top} $, where $ s $ is the value scale, and $ (A^{\top} B) $ is decremented by $ s\:a\:b^{\top} $. This function is used to remove data added using gan_pseudoinv_increment().

See also:
gan_pseudoinv_alloc().

Gan_PseudoInverseStruct * gan_pseudoinv_form Gan_PseudoInverseStruct psi,
long  max_asize,
long  max_bsize
 

Forms a pseudo-inverse equation solving structure.

Parameters:
pis A pointer to a structure or NULL
max_asize The envisaged largest size of the matrix
max_bsize The envisaged largest number of solution vectors
Returns:
Pointer to structure, or NULL on failure.
Allocates/fills a structure with initial values to compute the pseudo-inverse solution of a system of linear equations.

See also:
gan_pseudoinv_alloc().

void gan_pseudoinv_free Gan_PseudoInverseStruct pis  ) 
 

Frees a pseudo-inverse equation solving structure.

Parameters:
pis A pointer to a structure
Returns:
No value.
Frees a structure created to compute the pseudo-inverse solution of a system of linear equations.

See also:
gan_pseudoinv_alloc().

Gan_Vector * gan_pseudoinv_get_null_vector Gan_PseudoInverseStruct pis  ) 
 

Return a null vector from the solution space.

Parameters:
pis A pointer to the structure containing the equations
Returns:
The null-space vector, or NULL on failure.
Returns a null vector from the solution space of the given system of linear equations, on which The returned matrix is returned directly from the pis structure, so should not be freed by the calling program.

See also:
gan_pseudoinv_solve().

Gan_Matrix * gan_pseudoinv_get_solution Gan_PseudoInverseStruct pis  ) 
 

Return solution of an accumulated system of linear equations.

Parameters:
pis A pointer to the structure containing the equations
Returns:
Pointer to the solution matrix, or NULL on failure.
Returns the solution computed by gan_pseudoinv_solve(). The returned matrix is returned directly from the pis structure, so should not be freed by the calling program.

See also:
gan_pseudoinv_solve().

Gan_Bool gan_pseudoinv_increment Gan_PseudoInverseStruct pis,
double  scale,
  ...
 

Decrements a pseudo-inverse equation solver.

Parameters:
pis A pointer to a structure
scale A scaling for the equations
... A variable argument list of vector components
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Increments a system of linear equations

\[ A X = B \]

to be solved by pseudo-inverse:

\[ X = (A^{\top} A)^{-1} A^{\top} B \]

This function takes the variable argument list of elements of a vectors a and b, of sizes equal to the asize and bsize arguments to the most recent call to gan_pseudoinv_reset() on the pis structure. The matrix $ A^{\top} A $ is incremented by $ s\:a\:a^{\top} $, where $ s $ is the scale value, and $ A^{\top} B $ is incremented by $ s\:a\:b^{\top} $.

See also:
gan_pseudoinv_alloc().

Gan_Bool gan_pseudoinv_reset Gan_PseudoInverseStruct pis,
long  asize,
long  bsize
 

Initialises a pseudo-inverse equation solver to zero.

Parameters:
pis A pointer to a structure
asize The size of the matrix (number of solution elements)
bsize The number of solution vectors
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Initialises a structure to compute the pseudo-inverse solution of a system of linear equations. The size of the matrix and the number of solutions is also set.

See also:
gan_pseudoinv_alloc().

Gan_Bool gan_pseudoinv_set_constraint Gan_PseudoInverseStruct pis,
Gan_Matrix C,
Gan_Matrix D
 

Build a constraint into a system of linear equations.

Parameters:
pis A pointer to the structure containing the equations
C a pointer to a LHS constraint matrix
D a pointer to an RHS constraint matrix
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Applies the constraint

\[ C\:X = D \]

to any subsequently computed slution of the equations being built in the pis structure.

See also:
gan_pseudoinv_solve().

Gan_Bool gan_pseudoinv_set_low_values_allowed Gan_PseudoInverseStruct pis,
int  low_values_allowed
 

Sets the number of allowed low singular values.

Parameters:
pis A pointer to the structure containing the equations
low_values_allowed The number of low singular values allowed
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Sets the number of small singular values allowed when solving for the pseudo-inverse solution of a set of equations, where "small" is in the sense of the singular value ratio threshold between the tested value and the largest singular value, compared with the value set by gan_pseudoinv_set_ratio_thres(). Values within the allowed number threshold defined here are set to zero on inverting the system matrix.

The default value for this parameter is zero, effectively nullifying its effect. If it is set to a non-zero value then gan_pseudoinv_set_ratio_thres() should also be used to set the singular value ratio threshold.

See also:
gan_pseudoinv_set_ratio_thres().

Gan_Bool gan_pseudoinv_set_null_space Gan_PseudoInverseStruct pis,
int  null_space
 

Sets the size of the null space in a system of linear equations.

Parameters:
pis A pointer to the structure containing the equations
null_space The dimension of the null space
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Indicates that the solution of an accumulated system of linear equations has a null-space with the given dimension.

See also:
gan_pseudoinv_solve().

Gan_Bool gan_pseudoinv_set_ratio_thres Gan_PseudoInverseStruct pis,
double  ratio_thres
 

Sets the threshold on singular value ratios.

Parameters:
pis A pointer to the structure containing the equations
ratio_thres The threshold
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Sets a threshold so that when the Moore-Penrose pseudo-inverse is calculated, the singular values are compared with the highest singular values. If they are less than ratio_thres times the highest singular value, the low singular values are effectively set to infinity for the purpose of inverse.

The default value for ratio_thres is zero, eliminating its effect.

See also:
gan_pseudoinv_solve().

Gan_Bool gan_pseudoinv_solve Gan_PseudoInverseStruct pis,
int *  error_code
 

Solve an accumulated system of linear equations.

Parameters:
pis A pointer to the structure containing the equations
error_code A pointer to be filled with an error code or NULL
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Solves the set of equations

\[ A\:X = B \]

for matrix $ X $. If there are any constraints $ C\:X = D $ they are incorporated.

If an error occurs, the error handler is invoked unless error_code is not NULL, in which case the error code is passed back in the error_code pointer. In either case GAN_FALSE is returned to indicate the error.

See also:
gan_pseudoinv_alloc(), gan_pseudoinv_increment().

Gan_PseudoInverseStruct_f* gan_pseudoinvf_alloc long  max_asize,
long  max_bsize
 

Macro: Allocates a pseudo-inverse equation solving structure.

Parameters:
max_asize The envisaged largest size of the matrix
max_bsize The envisaged largest number of solution vectors
Returns:
Pointer to the allocated structure, or NULL on failure.
Allocates/fills a structure with initial values to compute the pseudo-inverse solution of a system of linear equations.

Macro call to gan_pseudoinvf_form().

See also:
gan_pseudoinvf_form().

Gan_Bool gan_pseudoinvf_decrement Gan_PseudoInverseStruct_f pis,
float  scale,
  ...
 

Decrements a pseudo-inverse equation solver.

Parameters:
pis A pointer to a structure
scale A scaling for the equations
... A variable argument list of vector components
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Decrements a system of linear equations

\[ A\:X = B \]

to be solved by pseudo-inverse:

\[ X = (A^{\top} A)^{-1} A^{\top} B \]

This function takes the variable argument list of elements of a vectors a and b, of sizes equal to the asize and bsize arguments to the most recent call to gan_pseudoinvf_reset() on the pis structure. The matrix $ (A^{\top} A) $ is decremented by $ s\:a\:a^{\top} $, where $ s $ is the value scale, and $ (A^{\top} B) $ is decremented by $ s\:a\:b^{\top} $. This function is used to remove data added using gan_pseudoinvf_increment().

See also:
gan_pseudoinvf_alloc().

Gan_PseudoInverseStruct_f * gan_pseudoinvf_form Gan_PseudoInverseStruct_f psi,
long  max_asize,
long  max_bsize
 

Forms a pseudo-inverse equation solving structure.

Parameters:
pis A pointer to a structure or NULL
max_asize The envisaged largest size of the matrix
max_bsize The envisaged largest number of solution vectors
Returns:
Pointer to structure, or NULL on failure.
Allocates/fills a structure with initial values to compute the pseudo-inverse solution of a system of linear equations.

See also:
gan_pseudoinvf_alloc().

void gan_pseudoinvf_free Gan_PseudoInverseStruct_f pis  ) 
 

Frees a pseudo-inverse equation solving structure.

Parameters:
pis A pointer to a structure
Returns:
No value.
Frees a structure created to compute the pseudo-inverse solution of a system of linear equations.

See also:
gan_pseudoinvf_alloc().

Gan_Vector_f * gan_pseudoinvf_get_null_vector Gan_PseudoInverseStruct_f pis  ) 
 

Return a null vector from the solution space.

Parameters:
pis A pointer to the structure containing the equations
Returns:
The null-space vector, or NULL on failure.
Returns a null vector from the solution space of the given system of linear equations, on which The returned matrix is returned directly from the pis structure, so should not be freed by the calling program.

See also:
gan_pseudoinvf_solve().

Gan_Matrix_f * gan_pseudoinvf_get_solution Gan_PseudoInverseStruct_f pis  ) 
 

Return solution of an accumulated system of linear equations.

Parameters:
pis A pointer to the structure containing the equations
Returns:
Pointer to the solution matrix, or NULL on failure.
Returns the solution computed by gan_pseudoinvf_solve(). The returned matrix is returned directly from the pis structure, so should not be freed by the calling program.

See also:
gan_pseudoinvf_solve().

Gan_Bool gan_pseudoinvf_increment Gan_PseudoInverseStruct_f pis,
float  scale,
  ...
 

Decrements a pseudo-inverse equation solver.

Parameters:
pis A pointer to a structure
scale A scaling for the equations
... A variable argument list of vector components
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Increments a system of linear equations

\[ A X = B \]

to be solved by pseudo-inverse:

\[ X = (A^{\top} A)^{-1} A^{\top} B \]

This function takes the variable argument list of elements of a vectors a and b, of sizes equal to the asize and bsize arguments to the most recent call to gan_pseudoinvf_reset() on the pis structure. The matrix $ A^{\top} A $ is incremented by $ s\:a\:a^{\top} $, where $ s $ is the scale value, and $ A^{\top} B $ is incremented by $ s\:a\:b^{\top} $.

See also:
gan_pseudoinvf_alloc().

Gan_Bool gan_pseudoinvf_reset Gan_PseudoInverseStruct_f pis,
long  asize,
long  bsize
 

Initialises a pseudo-inverse equation solver to zero.

Parameters:
pis A pointer to a structure
asize The size of the matrix (number of solution elements)
bsize The number of solution vectors
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Initialises a structure to compute the pseudo-inverse solution of a system of linear equations. The size of the matrix and the number of solutions is also set.

See also:
gan_pseudoinvf_alloc().

Gan_Bool gan_pseudoinvf_set_constraint Gan_PseudoInverseStruct_f pis,
Gan_Matrix_f C,
Gan_Matrix_f D
 

Build a constraint into a system of linear equations.

Parameters:
pis A pointer to the structure containing the equations
C a pointer to a LHS constraint matrix
D a pointer to an RHS constraint matrix
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Applies the constraint

\[ C\:X = D \]

to any subsequently computed slution of the equations being built in the pis structure.

See also:
gan_pseudoinvf_solve().

Gan_Bool gan_pseudoinvf_set_low_values_allowed Gan_PseudoInverseStruct_f pis,
int  low_values_allowed
 

Sets the number of allowed low singular values.

Parameters:
pis A pointer to the structure containing the equations
low_values_allowed The number of low singular values allowed
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Sets the number of small singular values allowed when solving for the pseudo-inverse solution of a set of equations, where "small" is in the sense of the singular value ratio threshold between the tested value and the largest singular value, compared with the value set by gan_pseudoinvf_set_ratio_thres(). Values within the allowed number threshold defined here are set to zero on inverting the system matrix.

The default value for this parameter is zero, effectively nullifying its effect. If it is set to a non-zero value then gan_pseudoinvf_set_ratio_thres() should also be used to set the singular value ratio threshold.

See also:
gan_pseudoinvf_set_ratio_thres().

Gan_Bool gan_pseudoinvf_set_null_space Gan_PseudoInverseStruct_f pis,
int  null_space
 

Sets the size of the null space in a system of linear equations.

Parameters:
pis A pointer to the structure containing the equations
null_space The dimension of the null space
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Indicates that the solution of an accumulated system of linear equations has a null-space with the given dimension.

See also:
gan_pseudoinvf_solve().

Gan_Bool gan_pseudoinvf_set_ratio_thres Gan_PseudoInverseStruct_f pis,
float  ratio_thres
 

Sets the threshold on singular value ratios.

Parameters:
pis A pointer to the structure containing the equations
ratio_thres The threshold
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Sets a threshold so that when the Moore-Penrose pseudo-inverse is calculated, the singular values are compared with the highest singular values. If they are less than ratio_thres times the highest singular value, the low singular values are effectively set to infinity for the purpose of inverse.

The default value for ratio_thres is zero, eliminating its effect.

See also:
gan_pseudoinvf_solve().

Gan_Bool gan_pseudoinvf_solve Gan_PseudoInverseStruct_f pis,
int *  error_code
 

Solve an accumulated system of linear equations.

Parameters:
pis A pointer to the structure containing the equations
error_code A pointer to be filled with an error code or NULL
Returns:
GAN_TRUE on success, GAN_FALSE on failure.
Solves the set of equations

\[ A\:X = B \]

for matrix $ X $. If there are any constraints $ C\:X = D $ they are incorporated.

If an error occurs, the error handler is invoked unless error_code is not NULL, in which case the error code is passed back in the error_code pointer. In either case GAN_FALSE is returned to indicate the error.

See also:
gan_pseudoinvf_alloc(), gan_pseudoinvf_increment().


Generated on Fri Mar 17 12:44:59 2006 by  doxygen 1.3.9.1