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_PseudoInverseStruct *	gan_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_Matrix *	gan_pseudoinv_get_solution (Gan_PseudoInverseStruct *pis)
	Return solution of an accumulated system of linear equations.
Gan_Vector *	gan_pseudoinv_get_null_vector (Gan_PseudoInverseStruct *pis)
	Return a null vector from the solution space.
Gan_PseudoInverseStruct *	gan_pseudoinv_alloc (long max_asize, long max_bsize)
	Macro: Allocates a pseudo-inverse equation solving structure.
Gan_PseudoInverseStruct_f *	gan_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_f *	gan_pseudoinvf_get_solution (Gan_PseudoInverseStruct_f *pis)
	Return solution of an accumulated system of linear equations.
Gan_Vector_f *	gan_pseudoinvf_get_null_vector (Gan_PseudoInverseStruct_f *pis)
	Return a null vector from the solution space.
Gan_PseudoInverseStruct_f *	gan_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

1.3.9.1

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

Classes

Defines

Functions

Function Documentation

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