Loading...
Searching...
No Matches
Matrices

## Functions

cpl_error_code | cpl_matrix_add (cpl_matrix *matrix1, const cpl_matrix *matrix2)
| Add two matrices.
cpl_error_code | cpl_matrix_add_scalar (cpl_matrix *matrix, double value)
| Add a scalar to a matrix.
cpl_error_code | cpl_matrix_append (cpl_matrix *matrix1, const cpl_matrix *matrix2, int mode)
| Append a matrix to another.
cpl_error_code | cpl_matrix_copy (cpl_matrix *matrix, const cpl_matrix *submatrix, cpl_size row, cpl_size col)
| Write the values of a matrix into another matrix.
cpl_error_code | cpl_matrix_decomp_chol (cpl_matrix *self)
| Replace a matrix by its Cholesky-decomposition, L * transpose(L) = A.
void | cpl_matrix_delete (cpl_matrix *matrix)
| Delete a matrix.
cpl_error_code | cpl_matrix_divide (cpl_matrix *matrix1, const cpl_matrix *matrix2)
| Divide a matrix by another element by element.
cpl_error_code | cpl_matrix_divide_scalar (cpl_matrix *matrix, double value)
| Divide a matrix by a scalar.
void | cpl_matrix_dump (const cpl_matrix *matrix, FILE *stream)
| Print a matrix.
cpl_matrix * | cpl_matrix_duplicate (const cpl_matrix *matrix)
| Make a copy of a matrix.
cpl_error_code | cpl_matrix_erase_columns (cpl_matrix *matrix, cpl_size start, cpl_size count)
| Delete columns from a matrix.
cpl_error_code | cpl_matrix_erase_rows (cpl_matrix *matrix, cpl_size start, cpl_size count)
| Delete rows from a matrix.
cpl_error_code | cpl_matrix_exponential (cpl_matrix *matrix, double base)
| Compute the exponential of matrix elements.
cpl_matrix * | cpl_matrix_extract (const cpl_matrix *matrix, cpl_size start_row, cpl_size start_column, cpl_size step_row, cpl_size step_column, cpl_size nrows, cpl_size ncolumns)
| Extract a submatrix from a matrix.
cpl_matrix * | cpl_matrix_extract_column (const cpl_matrix *matrix, cpl_size column)
| Copy a matrix column.
cpl_matrix * | cpl_matrix_extract_diagonal (const cpl_matrix *matrix, cpl_size diagonal)
| Extract a matrix diagonal.
cpl_matrix * | cpl_matrix_extract_row (const cpl_matrix *matrix, cpl_size row)
| Extract a matrix row.
cpl_error_code | cpl_matrix_fill (cpl_matrix *matrix, double value)
| Write the same value to all matrix elements.
cpl_error_code | cpl_matrix_fill_column (cpl_matrix *matrix, double value, cpl_size column)
| Write the same value to a matrix column.
cpl_error_code | cpl_matrix_fill_diagonal (cpl_matrix *matrix, double value, cpl_size diagonal)
| Write a given value to all elements of a given matrix diagonal.
cpl_error_code | cpl_matrix_fill_row (cpl_matrix *matrix, double value, cpl_size row)
| Write the same value to a matrix row.
cpl_error_code | cpl_matrix_fill_window (cpl_matrix *matrix, double value, cpl_size row, cpl_size col, cpl_size nrow, cpl_size ncol)
| Write the same value into a submatrix of a matrix.
cpl_error_code | cpl_matrix_flip_columns (cpl_matrix *matrix)
| Reverse order of columns in matrix.
cpl_error_code | cpl_matrix_flip_rows (cpl_matrix *matrix)
| Reverse order of rows in matrix.
double | cpl_matrix_get (const cpl_matrix *matrix, cpl_size row, cpl_size column)
| Get the value of a matrix element.
double * | cpl_matrix_get_data (cpl_matrix *matrix)
| Get the pointer to a matrix data buffer, or `NULL` in case of error.
const double * | cpl_matrix_get_data_const (const cpl_matrix *matrix)
| Get the pointer to a matrix data buffer, or `NULL` in case of error.
double | cpl_matrix_get_determinant (const cpl_matrix *matrix)
| Compute the determinant of a matrix.
double | cpl_matrix_get_max (const cpl_matrix *matrix)
| Find the maximum value of matrix elements.
cpl_error_code | cpl_matrix_get_maxpos (const cpl_matrix *matrix, cpl_size *row, cpl_size *column)
| Find position of the maximum value of matrix elements.
double | cpl_matrix_get_mean (const cpl_matrix *matrix)
| Find the mean of all matrix elements.
double | cpl_matrix_get_median (const cpl_matrix *matrix)
| Find the median of matrix elements.
double | cpl_matrix_get_min (const cpl_matrix *matrix)
| Find the minimum value of matrix elements.
cpl_error_code | cpl_matrix_get_minpos (const cpl_matrix *matrix, cpl_size *row, cpl_size *column)
| Find position of minimum value of matrix elements.
cpl_size | cpl_matrix_get_ncol (const cpl_matrix *matrix)
| Get the number of columns of a matrix.
cpl_size | cpl_matrix_get_ncol_ (const cpl_matrix *matrix)
| Get the number of columns of a matrix.
cpl_size | cpl_matrix_get_nrow (const cpl_matrix *matrix)
| Get the number of rows of a matrix.
double | cpl_matrix_get_stdev (const cpl_matrix *matrix)
| Find the standard deviation of matrix elements.
cpl_matrix * | cpl_matrix_invert_create (const cpl_matrix *matrix)
| Find a matrix inverse.
int | cpl_matrix_is_diagonal (const cpl_matrix *matrix, double tolerance)
| Check if a matrix is diagonal.
int | cpl_matrix_is_identity (const cpl_matrix *matrix, double tolerance)
| Check for identity matrix.
int | cpl_matrix_is_zero (const cpl_matrix *matrix, double tolerance)
| Check for zero matrix.
cpl_error_code | cpl_matrix_logarithm (cpl_matrix *matrix, double base)
| Compute the logarithm of matrix elements.
cpl_error_code | cpl_matrix_multiply (cpl_matrix *matrix1, const cpl_matrix *matrix2)
| Multiply two matrices element by element.
cpl_error_code | cpl_matrix_multiply_scalar (cpl_matrix *matrix, double value)
| Multiply a matrix by a scalar.
cpl_matrix * | cpl_matrix_new (cpl_size rows, cpl_size columns)
| Create a zero matrix of given size.
cpl_error_code | cpl_matrix_power (cpl_matrix *matrix, double exponent)
| Compute a power of matrix elements.
cpl_matrix * | cpl_matrix_product_create (const cpl_matrix *matrix1, const cpl_matrix *matrix2)
| Rows-by-columns product of two matrices.
cpl_error_code | cpl_matrix_resize (cpl_matrix *matrix, cpl_size top, cpl_size bottom, cpl_size left, cpl_size right)
| Reframe a matrix.
void | cpl_matrix_set_ (cpl_matrix *matrix, cpl_size row, cpl_size column, double value)
| Write a value to a matrix element.
cpl_error_code | cpl_matrix_set_size (cpl_matrix *matrix, cpl_size rows, cpl_size columns)
| Resize a matrix.
cpl_error_code | cpl_matrix_shift (cpl_matrix *matrix, cpl_size rshift, cpl_size cshift)
| Shift matrix elements.
cpl_matrix * | cpl_matrix_solve (const cpl_matrix *coeff, const cpl_matrix *rhs)
| Solution of a linear system.
cpl_error_code | cpl_matrix_solve_chol (const cpl_matrix *self, cpl_matrix *rhs)
| Solve a L*transpose(L)-system.
cpl_matrix * | cpl_matrix_solve_normal (const cpl_matrix *coeff, const cpl_matrix *rhs)
| Solution of overdetermined linear equations in a least squares sense.
cpl_matrix * | cpl_matrix_solve_svd (const cpl_matrix *coeff, const cpl_matrix *rhs)
| Solve a linear system in a least square sense using an SVD factorization.
cpl_matrix * | cpl_matrix_solve_svd_threshold (const cpl_matrix *coeff, const cpl_matrix *rhs, int mode, double tolerance)
| Solve a linear system in a least square sense using an SVD factorization discarding singular values below a given threshold.
cpl_error_code | cpl_matrix_sort_columns (cpl_matrix *matrix, int mode)
| Sort matrix by columns.
cpl_error_code | cpl_matrix_sort_rows (cpl_matrix *matrix, int mode)
| Sort matrix by rows.
cpl_error_code | cpl_matrix_subtract (cpl_matrix *matrix1, const cpl_matrix *matrix2)
| Subtract a matrix from another.
cpl_error_code | cpl_matrix_subtract_scalar (cpl_matrix *matrix, double value)
| Subtract a scalar to a matrix.
cpl_error_code | cpl_matrix_swap_columns (cpl_matrix *matrix, cpl_size column1, cpl_size column2)
| Swap two matrix columns.
cpl_error_code | cpl_matrix_swap_rowcolumn (cpl_matrix *matrix, cpl_size row)
| Swap a matrix column with a matrix row.
cpl_error_code | cpl_matrix_swap_rows (cpl_matrix *matrix, cpl_size row1, cpl_size row2)
| Swap two matrix rows.
cpl_error_code | cpl_matrix_threshold_small (cpl_matrix *matrix, double tolerance)
| Rounding to zero very small numbers in matrix.
cpl_matrix * | cpl_matrix_transpose_create (const cpl_matrix *matrix)
| Create transposed matrix.
void * | cpl_matrix_unwrap (cpl_matrix *matrix)
| Delete a matrix, but not its data buffer.
cpl_matrix * | cpl_matrix_wrap (cpl_size rows, cpl_size columns, double *data)
| Create a new matrix from existing data.

## Detailed Description

This module provides functions to create, destroy and use a cpl_matrix. The elements of a cpl_matrix with M rows and N columns are counted from 0,0 to M-1,N-1. The matrix element 0,0 is the one at the upper left corner of a matrix. The CPL matrix functions work properly only in the case the matrices elements do not contain garbage (such as `NaN` or infinity).

Synopsis:
  #include <cpl_matrix.h>

## Function Documentation

## cpl_matrix_add()

cpl_error_code cpl_matrix_add | ( | cpl_matrix * | matrix1,
|  | const cpl_matrix * | matrix2 )

Add two matrices.

Parameters

  matrix1 | Pointer to first matrix.
  matrix2 | Pointer to second matrix.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | An input matrix is a NULL pointer.
  CPL_ERROR_INCOMPATIBLE_INPUT | The specified matrices do not have the same size.

Add two matrices element by element. The two matrices must have identical sizes. The result is written to the first matrix.

References CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_add_scalar()

cpl_error_code cpl_matrix_add_scalar | ( | cpl_matrix * | matrix,
|  | double | value )

Add a scalar to a matrix.

Parameters

  matrix | Pointer to matrix.
  value | Value to add.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

Add the same value to each matrix element.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_append()

cpl_error_code cpl_matrix_append | ( | cpl_matrix * | matrix1,
|  | const cpl_matrix * | matrix2,
|  | int | mode )

Append a matrix to another.

Parameters

  matrix1 | Pointer to first matrix.
  matrix2 | Pointer to second matrix.
  mode | Matrices connected horizontally (0) or vertically (1).

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | An input matrix is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | mode is neither 0 nor 1.
  CPL_ERROR_INCOMPATIBLE_INPUT | Matrices cannot be joined as indicated by mode.

If mode is set to 0, the matrices must have the same number of rows, and are connected horizontally with the first matrix on the left. If mode is set to 1, the matrices must have the same number of columns, and are connected vertically with the first matrix on top. The first matrix is expanded to include the values from the second matrix, while the second matrix is left untouched.

Note
  The pointer to the first matrix data buffer may change, therefore pointers previously retrieved by calling `cpl_matrix_get_data()` should be discarded.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_matrix_copy(), and cpl_matrix_resize().

## cpl_matrix_copy()

cpl_error_code cpl_matrix_copy | ( | cpl_matrix * | matrix,
|  | const cpl_matrix * | submatrix,
|  | cpl_size | row,
|  | cpl_size | col )

Write the values of a matrix into another matrix.

Parameters

  matrix | Pointer to matrix to be modified.
  submatrix | Pointer to matrix to get the values from.
  row | Position of row 0 of submatrix in matrix.
  col | Position of column 0 of submatrix in matrix.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix or submatrix are NULL pointers.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | No overlap exists between the two matrices.

The values of submatrix are written to matrix starting at the indicated row and column. There are no restrictions on the sizes of submatrix: just the parts of submatrix overlapping matrix are copied. There are no restrictions on row and col either, that can also be negative. If the two matrices do not overlap, nothing is done, but an error condition is set.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_matrix_append(), cpl_matrix_duplicate(), and cpl_matrix_resize().

## cpl_matrix_decomp_chol()

cpl_error_code cpl_matrix_decomp_chol | ( | cpl_matrix * | self | ) |

Replace a matrix by its Cholesky-decomposition, L * transpose(L) = A.

Parameters

  self | N by N symmetric positive-definite matrix to decompose

Returns
  CPL_ERROR_NONE on success, or the relevant CPL error code

Note
  Only the upper triangle of self is read, L is written in the lower triangle
  If the matrix is singular the elements of self become undefined

See also
  Golub & Van Loan, Matrix Computations, Algorithm 4.2.1 (Cholesky: Gaxpy Version).

Errors

  CPL_ERROR_NULL_INPUT | An input pointer is NULL.
  CPL_ERROR_ILLEGAL_INPUT | self is not an n by n matrix.
  CPL_ERROR_SINGULAR_MATRIX | self is not symmetric, positive definite.

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_ERROR_SINGULAR_MATRIX, cpl_matrix_get_ncol_(), and CPL_SIZE_FORMAT.

## cpl_matrix_delete()

void cpl_matrix_delete | ( | cpl_matrix * | matrix | ) |

Delete a matrix.

Parameters

  matrix | Pointer to a matrix to be deleted.

Returns
  Nothing.

This function frees all the memory associated to a matrix. If matrix is `NULL`, nothing is done.

References cpl_free().

Referenced by cpl_fit_image_gaussian(), cpl_matrix_get_determinant(), cpl_matrix_invert_create(), cpl_matrix_solve(), cpl_matrix_solve_normal(), cpl_matrix_solve_svd(), cpl_matrix_solve_svd_threshold(), cpl_vector_fit_gaussian(), cpl_wcs_delete(), and cpl_wcs_platesol().

## cpl_matrix_divide()

cpl_error_code cpl_matrix_divide | ( | cpl_matrix * | matrix1,
|  | const cpl_matrix * | matrix2 )

Divide a matrix by another element by element.

Parameters

  matrix1 | Pointer to first matrix.
  matrix2 | Pointer to second matrix.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | An input matrix is a NULL pointer.
  CPL_ERROR_INCOMPATIBLE_INPUT | The specified matrices do not have the same size.

Divide each element of the first matrix by the corresponding element of the second one. The two matrices must have the same number of rows and columns. The result is written to the first matrix. No check is made against a division by zero.

References CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_divide_scalar()

cpl_error_code cpl_matrix_divide_scalar | ( | cpl_matrix * | matrix,
|  | double | value )

Divide a matrix by a scalar.

Parameters

  matrix | Pointer to matrix.
  value | Divisor.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_DIVISION_BY_ZERO | The input value is 0.0.

Divide each matrix element by the same value.

References CPL_ERROR_DIVISION_BY_ZERO, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_dump()

void cpl_matrix_dump | ( | const cpl_matrix * | matrix,
|  | FILE * | stream )

Print a matrix.

Parameters

  matrix | The matrix to print
  stream | The output stream

Returns
  Nothing.

This function is intended just for debugging. It just prints the elements of a matrix, ordered in rows and columns, to the specified stream or FILE pointer. If the specified stream is NULL, it is set to stdout. The function used for printing is the standard C `fprintf()`.

References CPL_SIZE_FORMAT.

## cpl_matrix_duplicate()

cpl_matrix * cpl_matrix_duplicate | ( | const cpl_matrix * | matrix | ) |

Make a copy of a matrix.

Parameters

  matrix | Matrix to be duplicated.

Returns
  Pointer to the new matrix, or `NULL` in case of error.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

A copy of the input matrix is created. To destroy the duplicated matrix the function `cpl_matrix_delete()` should be used.

References CPL_ERROR_NULL_INPUT, cpl_malloc(), and cpl_matrix_copy().

Referenced by cpl_matrix_get_determinant(), cpl_matrix_invert_create(), cpl_matrix_solve(), cpl_matrix_solve_svd(), and cpl_matrix_solve_svd_threshold().

## cpl_matrix_erase_columns()

cpl_error_code cpl_matrix_erase_columns | ( | cpl_matrix * | matrix,
|  | cpl_size | start,
|  | cpl_size | count )

Delete columns from a matrix.

Parameters

  matrix | Pointer to matrix to be modified.
  start | First column to delete.
  count | Number of columns to delete.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The specified start is outside the matrix boundaries.
  CPL_ERROR_ILLEGAL_INPUT | count is not positive.
  CPL_ERROR_ILLEGAL_OUTPUT | Attempt to delete all the columns of matrix.

A portion of the matrix data is physically removed. The pointer to matrix data may change, therefore pointers previously retrieved by calling `cpl_matrix_get_data()` should be discarded. The specified segment can extend beyond the end of the matrix, but the attempt to remove all matrix columns is flagged as an error because zero length matrices are illegal. Columns are counted starting from 0.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_realloc().

## cpl_matrix_erase_rows()

cpl_error_code cpl_matrix_erase_rows | ( | cpl_matrix * | matrix,
|  | cpl_size | start,
|  | cpl_size | count )

Delete rows from a matrix.

Parameters

  matrix | Pointer to matrix to be modified.
  start | First row to delete.
  count | Number of rows to delete.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The specified start is outside the matrix boundaries.
  CPL_ERROR_ILLEGAL_INPUT | count is not positive.
  CPL_ERROR_ILLEGAL_OUTPUT | Attempt to delete all the rows of matrix.

A portion of the matrix data is physically removed. The pointer to matrix data may change, therefore pointers previously retrieved by calling `cpl_matrix_get_data()` should be discarded. The specified segment can extend beyond the end of the matrix, but the attempt to remove all matrix rows is flagged as an error because zero length matrices are illegal. Rows are counted starting from 0.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_realloc().

## cpl_matrix_exponential()

cpl_error_code cpl_matrix_exponential | ( | cpl_matrix * | matrix,
|  | double | base )

Compute the exponential of matrix elements.

Parameters

  matrix | Target matrix.
  base | Exponential base.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The input base is not positive.

Each matrix element is replaced by its exponential in the specified base. The base must be positive.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_extract()

cpl_matrix * cpl_matrix_extract | ( | const cpl_matrix * | matrix,
|  | cpl_size | start_row,
|  | cpl_size | start_column,
|  | cpl_size | step_row,
|  | cpl_size | step_column,
|  | cpl_size | nrows,
|  | cpl_size | ncolumns )

Extract a submatrix from a matrix.

Parameters

  matrix | Pointer to the input matrix.
  start_row | Matrix row where to begin extraction.
  start_column | Matrix column where to begin extraction.
  step_row | Step between extracted rows.
  step_column | Step between extracted columns.
  nrows | Number of rows to extract.
  ncolumns | Number of columns to extract.

Returns
  Pointer to the new matrix, or `NULL` in case of error.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The start position is outside the matrix boundaries.
  CPL_ERROR_ILLEGAL_INPUT | While nrows and ncolumns are greater than 1, the specified steps are not positive.

The new matrix will include the nrows x ncolumns values read from the input matrix elements starting from position (start_row, start_column), in a grid of steps step_row and step_column. If the extraction parameters exceed the input matrix boundaries, just the overlap is returned, and this matrix would have sizes smaller than nrows x ncolumns. To destroy the new matrix the function `cpl_matrix_delete()` should be used.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and cpl_malloc().

Referenced by cpl_matrix_extract_column(), and cpl_matrix_extract_row().

## cpl_matrix_extract_column()

cpl_matrix * cpl_matrix_extract_column | ( | const cpl_matrix * | matrix,
|  | cpl_size | column )

Copy a matrix column.

Parameters

  matrix | Pointer to matrix containing the column.
  column | Sequence number of column to copy.

Returns
  Pointer to new matrix, or `NULL` in case of error.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The column is outside the matrix boundaries.

If a MxN matrix is given in input, the extracted row is a new Mx1 matrix. The column number is counted from 0. To destroy the new matrix the function `cpl_matrix_delete()` should be used.

References CPL_ERROR_NULL_INPUT, and cpl_matrix_extract().

## cpl_matrix_extract_diagonal()

cpl_matrix * cpl_matrix_extract_diagonal | ( | const cpl_matrix * | matrix,
|  | cpl_size | diagonal )

Extract a matrix diagonal.

Parameters

  matrix | Pointer to the matrix containing the diagonal.
  diagonal | Sequence number of the diagonal to copy.

Returns
  Pointer to the new matrix, or `NULL` in case of error.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The diagonal is outside the matrix boundaries (see description below).

If a MxN matrix is given in input, the extracted diagonal is a Mx1 matrix if N >= M, or a 1xN matrix if N < M. The diagonal number is counted from 0, corresponding to the matrix diagonal starting at element (0,0). A square matrix has just one diagonal; if M != N, the number of diagonals in the matrix is |M - N| + 1. To specify a diagonal sequence number outside this range would set an error condition, and a `NULL` pointer would be returned. To destroy the new matrix the function `cpl_matrix_delete()` should be used.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NULL_INPUT, and cpl_malloc().

## cpl_matrix_extract_row()

cpl_matrix * cpl_matrix_extract_row | ( | const cpl_matrix * | matrix,
|  | cpl_size | row )

Extract a matrix row.

Parameters

  matrix | Pointer to the matrix containing the row.
  row | Sequence number of row to copy.

Returns
  Pointer to new matrix, or `NULL` in case of error.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The row is outside the matrix boundaries.

If a MxN matrix is given in input, the extracted row is a new 1xN matrix. The row number is counted from 0. To destroy the new matrix the function `cpl_matrix_delete()` should be used.

References CPL_ERROR_NULL_INPUT, and cpl_matrix_extract().

## cpl_matrix_fill()

cpl_error_code cpl_matrix_fill | ( | cpl_matrix * | matrix,
|  | double | value )

Write the same value to all matrix elements.

Parameters

  matrix | Pointer to the matrix to access
  value | Value to write

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

Write the same value to all matrix elements.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_fill_column()

cpl_error_code cpl_matrix_fill_column | ( | cpl_matrix * | matrix,
|  | double | value,
|  | cpl_size | column )

Write the same value to a matrix column.

Parameters

  matrix | Pointer to the matrix to access
  value | Value to write
  column | Sequence number of column to overwrite

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The specified column is outside the matrix boundaries.

Write the same value to a matrix column. Columns are counted starting from 0.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_fill_diagonal()

cpl_error_code cpl_matrix_fill_diagonal | ( | cpl_matrix * | matrix,
|  | double | value,
|  | cpl_size | diagonal )

Write a given value to all elements of a given matrix diagonal.

Parameters

  matrix | Matrix to modify
  value | Value to write to diagonal
  diagonal | Number of diagonal to overwrite, 0 for main, positive for above main, negative for below main

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The specified diagonal is outside the matrix boundaries (see description below).

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and CPL_SIZE_FORMAT.

## cpl_matrix_fill_row()

cpl_error_code cpl_matrix_fill_row | ( | cpl_matrix * | matrix,
|  | double | value,
|  | cpl_size | row )

Write the same value to a matrix row.

Parameters

  matrix | Matrix to access
  value | Value to write
  row | Sequence number of row to overwrite.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The specified row is outside the matrix boundaries.

Write the same value to a matrix row. Rows are counted starting from 0.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_fill_window()

cpl_error_code cpl_matrix_fill_window | ( | cpl_matrix * | matrix,
|  | double | value,
|  | cpl_size | row,
|  | cpl_size | col,
|  | cpl_size | nrow,
|  | cpl_size | ncol )

Write the same value into a submatrix of a matrix.

Parameters

  matrix | Pointer to matrix to be modified.
  value | Value to write.
  row | Start row of matrix submatrix.
  col | Start column of matrix submatrix.
  nrow | Number of rows of matrix submatrix.
  ncol | Number of columns of matrix submatrix.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The specified start position is outside the matrix boundaries.
  CPL_ERROR_ILLEGAL_INPUT | nrow or ncol are not positive.

The specified value is written to matrix starting at the indicated row and column; nrow and ncol can exceed the input matrix boundaries, just the range overlapping the matrix is used in that case.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_flip_columns()

cpl_error_code cpl_matrix_flip_columns | ( | cpl_matrix * | matrix | ) |

Reverse order of columns in matrix.

Parameters

  matrix | Pointer to matrix to be reversed.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

The order of the columns in the matrix is reversed in place.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_matrix_swap_columns().

## cpl_matrix_flip_rows()

cpl_error_code cpl_matrix_flip_rows | ( | cpl_matrix * | matrix | ) |

Reverse order of rows in matrix.

Parameters

  matrix | Pointer to matrix to be reversed.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

The order of the rows in the matrix is reversed in place.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_get()

double cpl_matrix_get | ( | const cpl_matrix * | matrix,
|  | cpl_size | row,
|  | cpl_size | column )

Get the value of a matrix element.

Parameters

  matrix | Pointer to a matrix.
  row | Matrix element row.
  column | Matrix element column.

Returns
  Value of the specified matrix element, or 0.0 in case of error.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The accessed element is beyond the matrix boundaries.

Get the value of a matrix element. The matrix rows and columns are counted from 0,0.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_wcs_platesol().

## cpl_matrix_get_data()

double * cpl_matrix_get_data | ( | cpl_matrix * | matrix | ) |

Get the pointer to a matrix data buffer, or `NULL` in case of error.

Parameters

  matrix | Input matrix.

Returns
  Pointer to the matrix data buffer.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

A cpl_matrix object includes an array of values of type double. This function returns a pointer to this internal array, whose first element corresponds to the cpl_matrix element 0,0. The internal array contains in sequence all the cpl_matrix rows. For instance, in the case of a 3x4 matrix, the array elements

0 1 2 3 4 5 6 7 8 9 10 11

would correspond to the following matrix elements:

0 1 2 3
4 5 6 7
8 9 10 11

Note
  Use at your own risk: direct manipulation of matrix data rules out any check performed by the matrix object interface, and may introduce
  inconsistencies between the information maintained internally, and the actual matrix data and structure.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_matrix_solve_svd_threshold().

## cpl_matrix_get_data_const()

const double * cpl_matrix_get_data_const | ( | const cpl_matrix * | matrix | ) |

Get the pointer to a matrix data buffer, or `NULL` in case of error.

Parameters

  matrix | Input matrix.

Returns
  Pointer to the matrix data buffer.

See also
  cpl_matrix_get_data

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_image_filter(), and cpl_wcs_platesol().

## cpl_matrix_get_determinant()

double cpl_matrix_get_determinant | ( | const cpl_matrix * | matrix | ) |

Compute the determinant of a matrix.

Parameters

  matrix | Pointer to n by n matrix.

Returns
  Matrix determinant. In case of error, 0.0 is returned.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The input matrix is not square.
  CPL_ERROR_UNSPECIFIED | The input matrix is near-singular with a determinant so close to zero that it cannot be represented by a double.

The input matrix must be a square matrix. In case of a 1x1 matrix, the matrix single element value is returned.

References cpl_array_delete(), cpl_array_wrap_int(), cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, CPL_ERROR_SINGULAR_MATRIX, CPL_ERROR_UNSPECIFIED, cpl_errorstate_get(), cpl_errorstate_set(), cpl_malloc(), cpl_matrix_delete(), cpl_matrix_duplicate(), and CPL_SIZE_FORMAT.

## cpl_matrix_get_max()

double cpl_matrix_get_max | ( | const cpl_matrix * | matrix | ) |

Find the maximum value of matrix elements.

Parameters

  matrix | Pointer to matrix.

Returns
  Maximum value. In case of error, 0.0 is returned.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

The maximum value of all matrix elements is found.

References cpl_matrix_get_maxpos().

## cpl_matrix_get_maxpos()

cpl_error_code cpl_matrix_get_maxpos | ( | const cpl_matrix * | matrix,
|  | cpl_size * | row,
|  | cpl_size * | column )

Find position of the maximum value of matrix elements.

Parameters

  matrix | Input matrix.
  row | Returned row position of maximum.
  column | Returned column position of maximum.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

The position of the maximum value of all matrix elements is found. If more than one matrix element have a value corresponding to the maximum, the lowest element row number is returned in row. If more than one maximum matrix elements have the same row number, the lowest element column number is returned in column.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_matrix_get_max().

## cpl_matrix_get_mean()

double cpl_matrix_get_mean | ( | const cpl_matrix * | matrix | ) |

Find the mean of all matrix elements.

Parameters

  matrix | Pointer to matrix.

Returns
  Mean. In case of error 0.0 is returned.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

The mean value of all matrix elements is calculated.

Note
  This function works properly only in the case all the elements of the input matrix do not contain garbage (such as `NaN` or infinity).

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_vector_fit_gaussian().

## cpl_matrix_get_median()

double cpl_matrix_get_median | ( | const cpl_matrix * | matrix | ) |

Find the median of matrix elements.

Parameters

  matrix | Pointer to matrix.

Returns
  Median. In case of error 0.0 is returned.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

The median value of all matrix elements is calculated.

References CPL_ERROR_NULL_INPUT, cpl_free(), and cpl_malloc().

## cpl_matrix_get_min()

double cpl_matrix_get_min | ( | const cpl_matrix * | matrix | ) |

Find the minimum value of matrix elements.

Parameters

  matrix | Pointer to matrix.

Returns
  Minimum value. In case of error, 0.0 is returned.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

The minimum value of all matrix elements is found.

References cpl_matrix_get_minpos().

## cpl_matrix_get_minpos()

cpl_error_code cpl_matrix_get_minpos | ( | const cpl_matrix * | matrix,
|  | cpl_size * | row,
|  | cpl_size * | column )

Find position of minimum value of matrix elements.

Parameters

  matrix | Input matrix.
  row | Returned row position of minimum.
  column | Returned column position of minimum.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

The position of the minimum value of all matrix elements is found. If more than one matrix element have a value corresponding to the minimum, the lowest element row number is returned in row. If more than one minimum matrix elements have the same row number, the lowest element column number is returned in column.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_matrix_get_min().

## cpl_matrix_get_ncol()

cpl_size cpl_matrix_get_ncol | ( | const cpl_matrix * | matrix | ) |

Get the number of columns of a matrix.

Parameters

  matrix | Pointer to the matrix to examine.

Returns
  Number of matrix columns, or zero in case of failure.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

Determine the number of columns in a matrix.

References CPL_ERROR_NULL_INPUT, and cpl_matrix_get_ncol_().

Referenced by cpl_image_filter(), cpl_test_get_bytes_matrix(), and cpl_wcs_convert().

## cpl_matrix_get_ncol_()

cpl_size cpl_matrix_get_ncol_ | ( | const cpl_matrix * | matrix | ) |

Get the number of columns of a matrix.

Parameters

  matrix | Pointer to the matrix to examine.

Returns
  Number of matrix columns, or zero in case of failure.

Note
  No error checking in this internal function!

See also
  cpl_matrix_get_ncol

Referenced by cpl_matrix_decomp_chol(), cpl_matrix_get_ncol(), cpl_matrix_solve_chol(), cpl_polynomial_fit(), cpl_ppm_match_points(), and cpl_vector_fill_polynomial_fit_residual().

## cpl_matrix_get_nrow()

cpl_size cpl_matrix_get_nrow | ( | const cpl_matrix * | matrix | ) |

Get the number of rows of a matrix.

Parameters

  matrix | Pointer to the matrix to examine.

Returns
  Number of matrix rows, or zero in case of failure.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

Determine the number of rows in a matrix.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_image_filter(), cpl_matrix_solve_svd_threshold(), cpl_polynomial_fit(), cpl_test_get_bytes_matrix(), cpl_wcs_convert(), and cpl_wcs_platesol().

## cpl_matrix_get_stdev()

double cpl_matrix_get_stdev | ( | const cpl_matrix * | matrix | ) |

Find the standard deviation of matrix elements.

Parameters

  matrix | Pointer to matrix.

Returns
  Standard deviation. In case of error, or if a matrix is 1x1, 0.0 is returned.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

The standard deviation of all matrix elements is calculated.

Note
  This function works properly only in the case all the elements of the input matrix do not contain garbage (such as `NaN` or infinity).

References CPL_ERROR_NULL_INPUT.

## cpl_matrix_invert_create()

cpl_matrix * cpl_matrix_invert_create | ( | const cpl_matrix * | matrix | ) |

Find a matrix inverse.

Parameters

  matrix | Pointer to matrix to invert.

Returns
  Inverse matrix. In case of error a `NULL` is returned.

Errors

  CPL_ERROR_NULL_INPUT | Any input is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | self is not an n by n matrix.
  CPL_ERROR_SINGULAR_MATRIX | matrix cannot be inverted.

The input must be a square matrix. To destroy the new matrix the function `cpl_matrix_delete()` should be used.

Note
  When calling `cpl_matrix_invert_create()` with a nearly singular matrix, it is possible to get a result containin NaN values without any error code being set.

References cpl_array_delete(), cpl_array_wrap_int(), cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_malloc(), cpl_matrix_delete(), cpl_matrix_duplicate(), cpl_matrix_new(), and cpl_matrix_set_().

## cpl_matrix_is_diagonal()

int cpl_matrix_is_diagonal | ( | const cpl_matrix * | matrix,
|  | double | tolerance )

Check if a matrix is diagonal.

Parameters

  matrix | Pointer to matrix to be checked.
  tolerance | Max tolerated rounding to zero.

Returns
  1 in case of diagonal matrix, 0 otherwise. If a `NULL` pointer is passed, or the input matrix is not square, -1 is returned.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

A threshold may be specified to consider zero any number that is close enough to zero. If the specified tolerance is negative, a default of `DBL_EPSILON` is used. A zero tolerance may also be specified. No error is set if the input matrix is not square.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_matrix_is_identity().

## cpl_matrix_is_identity()

int cpl_matrix_is_identity | ( | const cpl_matrix * | matrix,
|  | double | tolerance )

Check for identity matrix.

Parameters

  matrix | Pointer to matrix to be checked.
  tolerance | Max tolerated rounding to zero, or to one.

Returns
  1 in case of identity matrix, 0 otherwise. If a `NULL` pointer is passed, or the input matrix is not square, -1 is returned.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

A threshold may be specified to consider zero any number that is close enough to zero, and 1 any number that is close enough to 1. If the specified tolerance is negative, a default of `DBL_EPSILON` is used. A zero tolerance may also be specified. No error is set if the input matrix is not square.

References CPL_ERROR_NULL_INPUT, and cpl_matrix_is_diagonal().

## cpl_matrix_is_zero()

int cpl_matrix_is_zero | ( | const cpl_matrix * | matrix,
|  | double | tolerance )

Check for zero matrix.

Parameters

  matrix | Pointer to matrix to be checked.
  tolerance | Max tolerated rounding to zero.

Returns
  1 in case of zero matrix, 0 otherwise. If a `NULL` pointer is passed, -1 is returned.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

After specific manipulations of a matrix some of its elements may theoretically be expected to be zero. However, because of numerical noise, such elements may turn out not to be exactly zero. In this specific case, if any of the matrix element is not exactly zero, the matrix would not be classified as a null matrix. A threshold may be specified to consider zero any number that is close enough to zero. If the specified tolerance is negative, a default of `DBL_EPSILON` is used. A zero tolerance may also be specified.

References CPL_ERROR_NULL_INPUT.

## cpl_matrix_logarithm()

cpl_error_code cpl_matrix_logarithm | ( | cpl_matrix * | matrix,
|  | double | base )

Compute the logarithm of matrix elements.

Parameters

  matrix | Pointer to matrix.
  base | Logarithm base.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | The input base, or any matrix element, is not positive.

Each matrix element is replaced by its logarithm in the specified base. The base and all matrix elements must be positive. If this is not the case, the matrix would not be modified.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_multiply()

cpl_error_code cpl_matrix_multiply | ( | cpl_matrix * | matrix1,
|  | const cpl_matrix * | matrix2 )

Multiply two matrices element by element.

Parameters

  matrix1 | Pointer to first matrix.
  matrix2 | Pointer to second matrix.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | An input matrix is a NULL pointer.
  CPL_ERROR_INCOMPATIBLE_INPUT | The specified matrices do not have the same size.

Multiply the two matrices element by element. The two matrices must have identical sizes. The result is written to the first matrix.

Note
  To obtain the rows-by-columns product between two matrices, `cpl_matrix_product_create()` should be used instead.

References CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_multiply_scalar()

cpl_error_code cpl_matrix_multiply_scalar | ( | cpl_matrix * | matrix,
|  | double | value )

Multiply a matrix by a scalar.

Parameters

  matrix | Pointer to matrix.
  value | Multiplication factor.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

Multiply each matrix element by the same factor.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_new()

cpl_matrix * cpl_matrix_new | ( | cpl_size | rows,
|  | cpl_size | columns )

Create a zero matrix of given size.

Parameters

  rows | Number of matrix rows.
  columns | Number of matrix columns.

Returns
  Pointer to new matrix, or `NULL` in case of error.

Errors

  CPL_ERROR_ILLEGAL_INPUT | rows or columns are not positive numbers.

This function allocates and initialises to zero a matrix of given size. To destroy this matrix the function `cpl_matrix_delete()` should be used.

References cpl_calloc(), CPL_ERROR_ILLEGAL_INPUT, and cpl_malloc().

Referenced by cpl_fit_image_gaussian(), cpl_matrix_invert_create(), cpl_matrix_resize(), cpl_matrix_solve_svd(), and cpl_matrix_solve_svd_threshold().

## cpl_matrix_power()

cpl_error_code cpl_matrix_power | ( | cpl_matrix * | matrix,
|  | double | exponent )

Compute a power of matrix elements.

Parameters

  matrix | Pointer to matrix.
  exponent | Constant exponent.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | Any matrix element is not compatible with the specified exponent (see description below).

Each matrix element is replaced by its power to the specified exponent. If the specified exponent is not negative, all matrix elements must be not negative; if the specified exponent is negative, all matrix elements must be positive; otherwise, an error condition is set and the matrix will be left unchanged. If the exponent is exactly 0.5 the (faster) `sqrt()` will be applied instead of `pow()`. If the exponent is zero, then any (non negative) matrix element would be assigned the value 1.0.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_product_create()

cpl_matrix * cpl_matrix_product_create | ( | const cpl_matrix * | matrix1,
|  | const cpl_matrix * | matrix2 )

Rows-by-columns product of two matrices.

Parameters

  matrix1 | Pointer to left side matrix.
  matrix2 | Pointer to right side matrix.

Returns
  Pointer to product matrix, or `NULL` in case of error.

Errors

  CPL_ERROR_NULL_INPUT | An input matrix is a NULL pointer.
  CPL_ERROR_INCOMPATIBLE_INPUT | The number of columns of the first matrix is not equal to the number of rows of the second matrix.

Rows-by-columns product of two matrices. The number of columns of the first matrix must be equal to the number of rows of the second matrix. To destroy the new matrix the function `cpl_matrix_delete()` should be used.

References cpl_ensure, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NULL_INPUT, cpl_malloc(), and cpl_matrix_wrap().

Referenced by cpl_matrix_solve_normal(), cpl_matrix_solve_svd(), and cpl_matrix_solve_svd_threshold().

## cpl_matrix_resize()

cpl_error_code cpl_matrix_resize | ( | cpl_matrix * | matrix,
|  | cpl_size | top,
|  | cpl_size | bottom,
|  | cpl_size | left,
|  | cpl_size | right )

Reframe a matrix.

Parameters

  matrix | Pointer to matrix to be modified.
  top | Extra rows on top.
  bottom | Extra rows on bottom.
  left | Extra columns on left.
  right | Extra columns on right.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ILLEGAL_OUTPUT | Attempt to shrink matrix to zero size (or less).

The input matrix is reframed according to specifications. Extra rows and column on the sides might also be negative, as long as they are compatible with the matrix sizes: the input matrix would be reduced in size accordingly, but an attempt to remove all matrix columns and/or rows is flagged as an error because zero length matrices are illegal. The old matrix elements contained in the new shape are left unchanged, and new matrix elements added by the reshaping are initialised to zero. No reshaping (i.e., all the extra rows set to zero) would not be flagged as an error.

Note
  The pointer to the matrix data buffer may change, therefore pointers previously retrieved by calling `cpl_matrix_get_data()` should be discarded.

References CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_free(), cpl_matrix_copy(), cpl_matrix_new(), and cpl_matrix_unwrap().

Referenced by cpl_matrix_append(), and cpl_matrix_set_size().

## cpl_matrix_set_()

void cpl_matrix_set_ | ( | cpl_matrix * | matrix,
|  | cpl_size | row,
|  | cpl_size | column,
|  | double | value )

Write a value to a matrix element.

Parameters

  matrix | Input matrix.
  row | Matrix element row.
  column | Matrix element column.
  value | Value to write.

Returns
  void

Note
  No error checking in this internal function!

See also
  cpl_matrix_set

Referenced by cpl_fit_image_gaussian(), and cpl_matrix_invert_create().

## cpl_matrix_set_size()

cpl_error_code cpl_matrix_set_size | ( | cpl_matrix * | matrix,
|  | cpl_size | rows,
|  | cpl_size | columns )

Resize a matrix.

Parameters

  matrix | Pointer to matrix to be resized.
  rows | New number of rows.
  columns | New number of columns.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ILLEGAL_OUTPUT | Attempt to shrink matrix to zero size (or less).

The input matrix is resized according to specifications. The old matrix elements contained in the resized matrix are left unchanged, and new matrix elements added by an increase of the matrix number of rows and/or columns are initialised to zero.

Note
  The pointer to the matrix data buffer may change, therefore pointers previously retrieved by calling `cpl_matrix_get_data()` should be discarded.

References CPL_ERROR_NONE, and cpl_matrix_resize().

## cpl_matrix_shift()

cpl_error_code cpl_matrix_shift | ( | cpl_matrix * | matrix,
|  | cpl_size | rshift,
|  | cpl_size | cshift )

Shift matrix elements.

Parameters

  matrix | Pointer to matrix to be modified.
  rshift | Shift in the vertical direction.
  cshift | Shift in the horizontal direction.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

The performed shift operation is cyclical (toroidal), i.e., matrix elements shifted out of one side of the matrix get shifted in from its opposite side. There are no restrictions on the values of the shift. Positive shifts are always in the direction of increasing row/column indexes.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_free(), and cpl_malloc().

## cpl_matrix_solve()

cpl_matrix * cpl_matrix_solve | ( | const cpl_matrix * | coeff,
|  | const cpl_matrix * | rhs )

Solution of a linear system.

Parameters

  coeff | A non-singular N by N matrix.
  rhs | A matrix containing one or more right-hand-sides.

Note
  rhs must have N rows and may contain more than one column, which each represent an independent right-hand-side.

Returns
  A newly allocated solution matrix with the size as rhs, or `NULL` on error.

Errors

  CPL_ERROR_NULL_INPUT | Any input is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | coeff is not a square matrix.
  CPL_ERROR_INCOMPATIBLE_INPUT | coeff and rhs do not have the same number of rows.
  CPL_ERROR_SINGULAR_MATRIX | coeff is singular (to working precision).

Compute the solution of a system of N equations with N unknowns:

coeff * X = rhs

coeff must be an NxN matrix, and rhs a NxM matrix. M greater than 1 means that multiple independent right-hand-sides are solved for. To destroy the solution matrix the function `cpl_matrix_delete()` should be used.

References cpl_array_delete(), cpl_array_wrap_int(), cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NULL_INPUT, cpl_malloc(), cpl_matrix_delete(), and cpl_matrix_duplicate().

## cpl_matrix_solve_chol()

cpl_error_code cpl_matrix_solve_chol | ( | const cpl_matrix * | self,
|  | cpl_matrix * | rhs )

Solve a L*transpose(L)-system.

Parameters

  self | N by N L*transpose(L)-matrix from cpl_matrix_decomp_chol()
  rhs | M right-hand-sides to be replaced by their solution

Returns
  CPL_ERROR_NONE on success, or the relevant CPL error code

See also
  cpl_matrix_decomp_chol()

Note
  Only the lower triangle of self is accessed

Errors

  CPL_ERROR_NULL_INPUT | An input pointer is NULL.
  CPL_ERROR_ILLEGAL_INPUT | self is not an n by n matrix.
  CPL_ERROR_INCOMPATIBLE_INPUT | The specified matrices do not have the same number of rows.
  CPL_ERROR_DIVISION_BY_ZERO | The main diagonal of L contains a zero. This error can only occur if the L*transpose(L)-matrix does not come from a successful call to cpl_matrix_decomp_chol().

References cpl_ensure_code, CPL_ERROR_DIVISION_BY_ZERO, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_matrix_get_ncol_().

## cpl_matrix_solve_normal()

cpl_matrix * cpl_matrix_solve_normal | ( | const cpl_matrix * | coeff,
|  | const cpl_matrix * | rhs )

Solution of overdetermined linear equations in a least squares sense.

Parameters

  coeff | The N by M matrix of coefficients, where N >= M.
  rhs | An N by K matrix containing K right-hand-sides.

Note
  rhs may contain more than one column, which each represent an independent right-hand-side.

Returns
  A newly allocated M by K solution matrix, or `NULL` on error.

Errors

  CPL_ERROR_NULL_INPUT | Any input is a NULL pointer.
  CPL_ERROR_INCOMPATIBLE_INPUT | coeff and rhs do not have the same number of rows.
  CPL_ERROR_SINGULAR_MATRIX | The matrix is (near) singular and a solution cannot be computed.

The following linear system of N equations and M unknowns is given:

coeff * X = rhs

where coeff is the NxM matrix of the coefficients, X is the MxK matrix of the unknowns, and rhs the NxK matrix containing the K right hand side(s).

The solution to the normal equations is known to be a least-squares solution, i.e. the 2-norm of coeff * X - rhs is minimized by the solution to transpose(coeff) * coeff * X = transpose(coeff) * rhs.

In the case that coeff is square (N is equal to M) it gives a faster and more accurate result to use cpl_matrix_solve().

The solution matrix should be deallocated with the function `cpl_matrix_delete()`.

References cpl_ensure, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NULL_INPUT, cpl_matrix_delete(), cpl_matrix_product_create(), and cpl_matrix_transpose_create().

## cpl_matrix_solve_svd()

cpl_matrix * cpl_matrix_solve_svd | ( | const cpl_matrix * | coeff,
|  | const cpl_matrix * | rhs )

Solve a linear system in a least square sense using an SVD factorization.

Parameters

  coeff | An N by M matrix of linear system coefficients, where N >= M
  rhs | An N by 1 matrix with the right hand side of the system

Returns
  A newly allocated M by 1 matrix containing the solution vector or `NULL` on error.

Errors

  CPL_ERROR_NULL_INPUT | Any input is a NULL pointer.
  CPL_ERROR_INCOMPATIBLE_INPUT | coeff and rhs do not have the same number of rows.
  CPL_ILLEGAL_INPUT | The matrix rhs has more than one column.

The function solves a linear system of the form Ax = b for the solution vector x, where `A` is represented by the argument coeff and `b` by the argument rhs. The linear system is solved using the singular value decomposition (SVD) of the coefficient matrix, based on a one-sided Jacobi orthogonalization. When solving the linear system all singular values are taken into account, regardless of their magnitude. This is equivalent to calling cpl_matrix_solve_svd_threshold() with mode set to `2` and a threshold value of `0`.

The returned solution matrix should be deallocated using cpl_matrix_delete().

See also
  cpl_matrix_solve_svd_threshold()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set_where, cpl_matrix_delete(), cpl_matrix_duplicate(), cpl_matrix_new(), cpl_matrix_product_create(), cpl_matrix_transpose_create(), cpl_vector_delete(), cpl_vector_get_data_const(), and cpl_vector_new().

## cpl_matrix_solve_svd_threshold()

cpl_matrix * cpl_matrix_solve_svd_threshold | ( | const cpl_matrix * | coeff,
|  | const cpl_matrix * | rhs,
|  | int | mode,
|  | double | tolerance )

Solve a linear system in a least square sense using an SVD factorization discarding singular values below a given threshold.

Parameters

  coeff | An N by M matrix of linear system coefficients, where N >= M
  rhs | An N by 1 matrix with the right hand side of the system
  mode | Cutoff mode selector for small singular values.
  tolerance | Factor used to compute the cutoff value if mode is set to `2`.

Returns
  A newly allocated M by 1 matrix containing the solution vector or `NULL` on error.

Errors

  CPL_ERROR_NULL_INPUT | coeff or rhs is a NULL pointer.
  CPL_ERROR_INCOMPATIBLE_INPUT | coeff and rhs do not have the same number of rows.
  CPL_ILLEGAL_INPUT | The matrix rhs has more than one column, or an illegal mode or tolerance was given.

The function solves a linear system of the form Ax = b for the solution vector x, where `A` is represented by the argument coeff and `b` by the argument rhs. The linear system is solved using the singular value decomposition (SVD) of the coefficient matrix, based on a one-sided Jacobi orthogonalization. When solving the linear system singular values which are less or equal than a given cutoff value are treated as zero.

The argument mode is used to select the computation of the cutoff value for small singular values. If mode is set to `0` the machine precision (`DBL_EPSILON`) is used as the cutoff factor. If mode is `1`, the cutoff factor is computed as , and if mode is `2` the argument tolerance, a value in the range . is used as the cutoff factor. The actual cutoff value, is then given by the cutoff factor times the biggest singular value obtained from the SVD of the input matrix coeff.

The returned solution matrix should be deallocated using cpl_matrix_delete().

See also
  cpl_matrix_solve_svd()

References cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set_where, cpl_matrix_delete(), cpl_matrix_duplicate(), cpl_matrix_get_data(), cpl_matrix_get_nrow(), cpl_matrix_new(), cpl_matrix_product_create(), cpl_matrix_transpose_create(), CPL_MAX, cpl_vector_delete(), cpl_vector_get_data_const(), cpl_vector_get_max(), and cpl_vector_new().

## cpl_matrix_sort_columns()

cpl_error_code cpl_matrix_sort_columns | ( | cpl_matrix * | matrix,
|  | int | mode )

Sort matrix by columns.

Parameters

  matrix | Pointer to matrix to be sorted.
  mode | Sorting mode: 0, by absolute value, otherwise by value.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

The matrix elements of the top row are used as reference for the column sorting, if there are identical the values of the second row are considered, etc. Columns with the largest values go on the right. If mode is equal to zero, the columns are sorted according to their absolute values (zeroes at left).

References cpl_calloc(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_free(), and cpl_malloc().

## cpl_matrix_sort_rows()

cpl_error_code cpl_matrix_sort_rows | ( | cpl_matrix * | matrix,
|  | int | mode )

Sort matrix by rows.

Parameters

  matrix | Pointer to matrix to be sorted.
  mode | Sorting mode: 0, by absolute value, otherwise by value.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

The matrix elements of the leftmost column are used as reference for the row sorting, if there are identical the values of the second column are considered, etc. Rows with the greater values go on top. If mode is equal to zero, the rows are sorted according to their absolute values (zeroes at bottom).

References cpl_calloc(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_free(), and cpl_malloc().

## cpl_matrix_subtract()

cpl_error_code cpl_matrix_subtract | ( | cpl_matrix * | matrix1,
|  | const cpl_matrix * | matrix2 )

Subtract a matrix from another.

Parameters

  matrix1 | Pointer to first matrix.
  matrix2 | Pointer to second matrix.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | An input matrix is a NULL pointer.
  CPL_ERROR_INCOMPATIBLE_INPUT | The specified matrices do not have the same size.

Subtract the second matrix from the first one element by element. The two matrices must have identical sizes. The result is written to the first matrix.

References CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_subtract_scalar()

cpl_error_code cpl_matrix_subtract_scalar | ( | cpl_matrix * | matrix,
|  | double | value )

Subtract a scalar to a matrix.

Parameters

  matrix | Pointer to matrix.
  value | Value to subtract.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

Subtract the same value to each matrix element.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_swap_columns()

cpl_error_code cpl_matrix_swap_columns | ( | cpl_matrix * | matrix,
|  | cpl_size | column1,
|  | cpl_size | column2 )

Swap two matrix columns.

Parameters

  matrix | Pointer to matrix to be modified.
  column1 | One matrix column.
  column2 | Another matrix column.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | Any of the specified columns is outside the matrix boundaries.

The values of two given matrix columns are exchanged. Columns are counted starting from 0. If the same column number is given twice, nothing is done and no error is set.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_matrix_flip_columns().

## cpl_matrix_swap_rowcolumn()

cpl_error_code cpl_matrix_swap_rowcolumn | ( | cpl_matrix * | matrix,
|  | cpl_size | row )

Swap a matrix column with a matrix row.

Parameters

  matrix | Pointer to matrix to be modified.
  row | Matrix row.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | The specified row is outside the matrix boundaries.
  CPL_ERROR_ILLEGAL_INPUT | The input matrix is not square.

The values of the indicated row are exchanged with the column having the same sequence number. Rows and columns are counted starting from 0.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_swap_rows()

cpl_error_code cpl_matrix_swap_rows | ( | cpl_matrix * | matrix,
|  | cpl_size | row1,
|  | cpl_size | row2 )

Swap two matrix rows.

Parameters

  matrix | Pointer to matrix to be modified.
  row1 | One matrix row.
  row2 | Another matrix row.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.
  CPL_ERROR_ACCESS_OUT_OF_RANGE | Any of the specified rows is outside the matrix boundaries.

The values of two given matrix rows are exchanged. Rows are counted starting from 0. If the same row number is given twice, nothing is done and no error is set.

References cpl_ensure_code, CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_threshold_small()

cpl_error_code cpl_matrix_threshold_small | ( | cpl_matrix * | matrix,
|  | double | tolerance )

Rounding to zero very small numbers in matrix.

Parameters

  matrix | Pointer to matrix to be chopped.
  tolerance | Max tolerated rounding to zero.

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

After specific manipulations of a matrix some of its elements may theoretically be expected to be zero (for instance, as a result of multiplying a matrix by its inverse). However, because of numerical noise, such elements may turn out not to be exactly zero. With this function any very small number in the matrix is turned to exactly zero. If the tolerance is zero or negative, a default threshold of `DBL_EPSILON` is used.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_matrix_transpose_create()

cpl_matrix * cpl_matrix_transpose_create | ( | const cpl_matrix * | matrix | ) |

Create transposed matrix.

Parameters

  matrix | Pointer to matrix to be transposed.

Returns
  Pointer to transposed matrix. If a `NULL` pointer is passed, a `NULL` pointer is returned.

Errors

  CPL_ERROR_NULL_INPUT | The input matrix is a NULL pointer.

The transposed of the input matrix is created. To destroy the new matrix the function `cpl_matrix_delete()` should be used.

References CPL_ERROR_NULL_INPUT, cpl_malloc(), and cpl_matrix_wrap().

Referenced by cpl_matrix_solve_normal(), cpl_matrix_solve_svd(), and cpl_matrix_solve_svd_threshold().

## cpl_matrix_unwrap()

void * cpl_matrix_unwrap | ( | cpl_matrix * | matrix | ) |

Delete a matrix, but not its data buffer.

Parameters

  matrix | Pointer to a matrix to be deleted.

Returns
  Pointer to the internal data buffer.

This function deallocates all the memory associated to a matrix, with the exception of its data buffer. This type of destructor should be used on matrices created with the `cpl_matrix_wrap()` constructor, if the data buffer specified then was not allocated using the functions of the `cpl_memory` module. In such a case, the data buffer should be deallocated separately. See the documentation of the function `cpl_matrix_wrap()`. If matrix is `NULL`, nothing is done, and a `NULL` pointer is returned.

References cpl_free().

Referenced by cpl_fit_image_gaussian(), cpl_matrix_resize(), and cpl_vector_fit_gaussian().

## cpl_matrix_wrap()

cpl_matrix * cpl_matrix_wrap | ( | cpl_size | rows,
|  | cpl_size | columns,
|  | double * | data )

Create a new matrix from existing data.

Parameters

  data | Existing data buffer.
  rows | Number of matrix rows.
  columns | Number of matrix columns.

Returns
  Pointer to new matrix, or `NULL` in case of error.

Errors

  CPL_ERROR_NULL_INPUT | The input data is a NULL pointer.
  CPL_ERROR_ILLEGAL_INPUT | rows or columns are not positive numbers.

This function creates a new matrix that will encapsulate the given data. At any error condition, a `NULL` pointer would be returned. Note that the size of the input data array is not checked in any way, and it is expected to match the specified matrix sizes. The input array is supposed to contain in sequence all the new cpl_matrix rows. For instance, in the case of a 3x4 matrix, the input array should contain 12 elements

0 1 2 3 4 5 6 7 8 9 10 11

that would correspond to the matrix elements

0 1 2 3
4 5 6 7
8 9 10 11

The data buffer is not copied, so it should not be deallocated while the matrix is still in use: the function `cpl_matrix_delete()` would take care of deallocating it. To avoid problems with the memory managment, the specified data buffer should be allocated using the functions of the `cpl_memory` module, and also statically allocated data should be strictly avoided. If this were not the case, this matrix should not be destroyed using `cpl_matrix_delete()`, but `cpl_matrix_unwrap()` should be used instead; moreover, functions implying memory handling (as `cpl_matrix_set_size()`, or `cpl_matrix_delete_row()` ) should not be used.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and cpl_malloc().

Referenced by cpl_fit_image_gaussian(), cpl_matrix_product_create(), cpl_matrix_transpose_create(), cpl_vector_fit_gaussian(), and cpl_wcs_convert().