algebra.c File Reference

Detailed Description

Definition of the lineal algebra routines used in the CuikSuite.

Simple 2D/3D operations are defined in geom.c

Basic vector/matrix operations are defined in basic_algebra.c

Here we define high level linear algebra routines. These are the only routines if we ever change the support linear algebra library (right now GSL is used).

Definition in file algebra.c.

Functions

unsigned int AnalyzeKernel (unsigned int nr, unsigned int nc, double *mT, unsigned int dof, double epsilon, boolean computeRank, boolean checkRank, boolean getT, boolean getBase, boolean *singular, unsigned int *rank, boolean **IR, double **T)
 Analyzes the kernel of a matrix. More...
 
unsigned int FindRank (double epsilon, unsigned int nr, unsigned int nc, double *mT)
 Determines the row-rank of a matrix. More...
 
unsigned int FindKernel (unsigned int nr, unsigned int nc, double *mT, unsigned int dof, boolean check, double epsilon, double **T)
 Computes the kernel of a matrix. More...
 
unsigned int FindKernelAndIndependentRows (unsigned int nr, unsigned int nc, double *mT, unsigned int dof, double epsilon, boolean *singular, boolean **IR, double **T)
 Computes the kernel of a matrix and determines the independent rows of this matrix. More...
 
double * GetNewtonMatrixBuffer (TNewton *n)
 Buffer to store the Newton matrix. More...
 
double * GetNewtonRHBuffer (TNewton *n)
 Buffer to store the Newton right hand. More...
 
void NewtonSetMatrix (unsigned int i, unsigned int j, double v, TNewton *n)
 Defines the matrix being used in a Newton step. More...
 
void NewtonSetRH (unsigned int i, double v, TNewton *n)
 Defines the vector being used in a Newton step. More...
 
double * GetLSMatrixBuffer (TLinearSystem *ls)
 Buffer to store the A matrix. More...
 
double * GetLSRHBuffer (TLinearSystem *ls)
 Buffer to store the linear system right hand (RH). More...
 
double * GetLSSolutionBuffer (TLinearSystem *ls)
 Buffer to store the linear system solution. More...
 
void LSSetMatrix (unsigned int i, unsigned int j, double v, TLinearSystem *ls)
 Defines the matrix being used in a linear system. More...
 
void LSSetRH (unsigned int i, double v, TLinearSystem *ls)
 Defines the vector being used in a linear system. More...
 

Function Documentation

unsigned int AnalyzeKernel ( unsigned int  nr,
unsigned int  nc,
double *  mT,
unsigned int  dof,
double  epsilon,
boolean  computeRank,
boolean  checkRank,
boolean  getT,
boolean  getBase,
boolean singular,
unsigned int *  rank,
boolean **  IR,
double **  T 
)

Analyzes the kernel of a matrix and extract different information, as requested by the caller. This function for many purposes

Parameters
nrNumber of rows of the matrix (no transposed).
ncNumber of columns of the matrix (no transposed).
mTThe TRANSPOSED matrix stored as a vector.
dofExpected dimension of the kernel. Can be zero if the getRank is TRUE.
epsilonValues below epsilon are taken as zero.
computeRankIf the rank has to be computed from the kernel analysis. Otherwise the information provided by 'dof' is taken as good.
checkRankTRUE if an error has to be triggered if the rank is different from the expected one. This only has effect if computeRank is FALSE.
getTTRUE if we have to return a basis of the kernel.
getBaseTRUE if we have to return a basis of the input matrix (selected rows).
singularTRUE if the matrix is singular (has more null eigen values than the expected ones). Output.
rankRank of the input matrix. Computed in this function if computeRank is TRUE. Otherwise it is just deduced relying on the 'dof' parameter.
IRThe set of independent rows as a boolean vector with as many entriees as rows in the input matrix and TRUE for the independent rows. The space for this vector is allocated here but must be deallocated externally. If the matrix is singular this contains the most likely basis of the matrix (up to the numerical accuracy). Caution must be taken to use this output in this case. This is only allocated if getBase is TRUE.
TThe output kernel. This is a (nc x dof) matrix (stored as a vector). The space for this matrix is allocated in this function but must be de-allocated externally. Only allocated if getT is TRUE.
Returns
0 if all the operations are correct, 1 if the kernel is larger than expected, 2 if it is smaller than expected, 3 if there is an error in the QR decomposition.

Referenced by FindKernel(), FindKernelAndIndependentRows(), and FindRank().

unsigned int FindRank ( double  epsilon,
unsigned int  nr,
unsigned int  nc,
double *  mT 
)

Determines the rank of a matrix, i.e. the dimension of the space spanned by the rows/column of the matrix.

For a given problem, the number of variables minus the rank of the Jacobian gives the dimensionality of the solution space, assuming that the Jacobian is evaluated in a regular point. The dimensionality of the solution space is the same as that of its tangent space.

Parameters
epsilonNumerical accuracy.
nrNumber of rows of the matrix (no transposed).
ncNumber of columns of the matrix (no transposed).
mTThe TRANSPOSED matrix.
Returns
The rank of the matrix. NO_UINT if the rank can not be computed.

Definition at line 1105 of file algebra.c.

References AnalyzeKernel(), FALSE, and TRUE.

Referenced by ManifoldDimension().

unsigned int FindKernel ( unsigned int  nr,
unsigned int  nc,
double *  mT,
unsigned int  dof,
boolean  check,
double  epsilon,
double **  T 
)

Defines a basis of the null space of a matrix.

Parameters
nrNumber of rows of the matrix (no transposed).
ncNumbe of columns of the matrix (no transposed).
mTThe TRANSPOSED matrix stored as a vector.
dofExpected dimension of the kernel.
checkIf TRUE the function introduces some consistancy checks (whether the kernel dimensionality is larger or smaller than the expected one).
epsilonValues below epsilon are taken as zero.
TThe output kernel. This is a (nc x dof) matrix (stored as a vector). The space for this matrix is allocated in this function but must be de-allocated externally.
Returns
0 if all the operations are correct, 1 if there the kernel is too large (i.e., the given point is singular), 2 if the chart could not be defined since the kernel is too small at the given point, and 3 if there is an error while performing QR decomposition. These outputs come directly from AnalyzeKernel.

Definition at line 1119 of file algebra.c.

References AnalyzeKernel(), FALSE, and TRUE.

Referenced by FindRightNullVector(), and RefineSingularPoint().

unsigned int FindKernelAndIndependentRows ( unsigned int  nr,
unsigned int  nc,
double *  mT,
unsigned int  dof,
double  epsilon,
boolean singular,
boolean **  IR,
double **  T 
)

Defines a basis of the null space of a matrix and determines a subset of the rows of the matrix that are independent.

This is useful because in our case most (all?) the matrices have redundancy (i.e., rows that are linearly dependent on other rows). However, for some purposes we need to determine a subset of the rows that are linearly independent.

Parameters
nrNumber of rows of the matrix (no transposed).
ncNumbe of columns of the matrix (no transposed).
mTThe TRANSPOSED matrix stored as a vector.
dofExpected dimension of the kernel. If zero, the function tries to determine the rank automatically.
epsilonValues below epsilon are taken as zero.
singularTRUE if the matrix is singular (has more null eigen values than the expected ones). Output.
IRThe set of independent rows as a boolean vector with as many entriees as rows in the input matrix and TRUE for the independent rows. The space for this vector is allocated here but must be deallocated externally. If the matrix is singular this contains the most likely basis of the matrix (up to the numerical accuracy). Caution must be taken to use this output in this case.
TThe output kernel. This is a (nc x dof) matrix (stored as a vector). The space for this matrix is allocated in this function but must be de-allocated externally.
Returns
0 if all the operations are correct, 1 if there the kernel is too large (i.e., the given point is singular), 2 if the chart could not be defined since the kernel is too small at the given point, and 3 if there is an error while performing QR decomposition. These outputs come directly from AnalyzeKernel.

Definition at line 1133 of file algebra.c.

References AnalyzeKernel(), FALSE, and TRUE.

Referenced by ComputeJacobianKernelBasis().

double* GetNewtonMatrixBuffer ( TNewton *  n)
inline

Buffer to store the Newton matrix.

This buffer must be accessed using the RC2INDEX macro since the matrix can be stored row major or column major depending on the underlying lineal algebra library being used.

Parameters
nThe Newton structure.
Returns
A pointer to the buffer where to store the matrix.

Definition at line 1147 of file algebra.c.

Referenced by CuikNewtonInBox(), CuikNewtonSimp(), Newton2ManifoldPlane(), and RefineSingularPoint().

double* GetNewtonRHBuffer ( TNewton *  n)
inline

Buffer to store the Newton RH.

Parameters
nThe Newton structure.
Returns
A pointer to the buffer where to store the RH.

Definition at line 1152 of file algebra.c.

Referenced by CuikNewtonInBox(), CuikNewtonSimp(), Newton2ManifoldPlane(), and RefineSingularPoint().

void NewtonSetMatrix ( unsigned int  i,
unsigned int  j,
double  v,
TNewton *  n 
)
inline

Sets one element of the matrix to be used in one Newton step. This matrix is typically initilized externally, but here we provide a mehtod to set it.

Parameters
iThe row.
jThe column.
vThe new value.
nThe Newton structure to set.

Definition at line 1157 of file algebra.c.

References RC2INDEX.

Referenced by CuikNewtonInBox().

void NewtonSetRH ( unsigned int  i,
double  v,
TNewton *  n 
)
inline

Sets one element of the vector to be used in one Newton step. This vector is typically initilized externally, but here we provide a mehtod to set it.

Parameters
iThe index in the vector.
vThe new value.
nThe Newton structure to set.

Definition at line 1162 of file algebra.c.

Referenced by CuikNewtonInBox().

double* GetLSMatrixBuffer ( TLinearSystem *  ls)
inline

Buffer to store the A matrix.

This buffer must be accessed using the RC2INDEX macro since the matrix can be stored row major or column major depending on the underlying lineal algebra library being used.

Parameters
lsThe linear system structure.
Returns
A pointer to the buffer where to store the matrix.

Definition at line 1167 of file algebra.c.

Referenced by Chart2Manifold().

double* GetLSRHBuffer ( TLinearSystem *  ls)
inline

Buffer to store the linear sytem RH.

Parameters
lsThe linear system structure.
Returns
A pointer to the buffer where to store the RH.

Definition at line 1172 of file algebra.c.

Referenced by Chart2Manifold().

double* GetLSSolutionBuffer ( TLinearSystem *  ls)
inline

Buffer to store the linear sytem solution.

Parameters
lsThe linear system structure.
Returns
A pointer to the buffer where to store the RH.

Definition at line 1177 of file algebra.c.

Referenced by Chart2Manifold().

void LSSetMatrix ( unsigned int  i,
unsigned int  j,
double  v,
TLinearSystem *  ls 
)
inline

Sets one element of the matrix to be used in a linear system.

Parameters
iThe row.
jThe column.
vThe new value.
lsThe linear system structure.

Definition at line 1182 of file algebra.c.

References RC2INDEX.

void LSSetRH ( unsigned int  i,
double  v,
TLinearSystem *  ls 
)
inline

Sets one element of the right hand vector of a linear system.

Parameters
iThe index in the vector.
vThe new value.
lsThe linear system structure.

Definition at line 1187 of file algebra.c.