41.2 Allocation

The functions for allocating memory for a sparse matrix follow the style of malloc and free. They also perform their own error checking. If there is insufficient memory available to allocate a matrix then the functions call the GSL error handler with an error code of GSL_ENOMEM in addition to returning a null pointer.

Function: gsl_spmatrix * gsl_spmatrix_alloc (const size_t n1, const size_t n2)

This function allocates a sparse matrix of size n1-by-n2 and initializes it to all zeros. If the size of the matrix is not known at allocation time, both n1 and n2 may be set to 1, and they will automatically grow as elements are added to the matrix. This function sets the matrix to the triplet representation, which is the easiest for adding and accessing matrix elements. This function tries to make a reasonable guess for the number of non-zero elements (nzmax) which will be added to the matrix by assuming a sparse density of 10\%. The function gsl_spmatrix_alloc_nzmax can be used if this number is known more accurately. The workspace is of size O(nzmax).

Function: gsl_spmatrix * gsl_spmatrix_alloc_nzmax (const size_t n1, const size_t n2, const size_t nzmax, const size_t sptype)

This function allocates a sparse matrix of size n1-by-n2 and initializes it to all zeros. If the size of the matrix is not known at allocation time, both n1 and n2 may be set to 1, and they will automatically grow as elements are added to the matrix. The parameter nzmax specifies the maximum number of non-zero elements which will be added to the matrix. It does not need to be precisely known in advance, since storage space will automatically grow using gsl_spmatrix_realloc if nzmax is not large enough. Accurate knowledge of this parameter reduces the number of reallocation calls required. The parameter sptype specifies the storage format of the sparse matrix. Possible values are

GSL_SPMATRIX_TRIPLET

This flag specifies triplet storage.

GSL_SPMATRIX_CCS

This flag specifies compressed column storage.

GSL_SPMATRIX_CRS

This flag specifies compressed row storage.

The allocated gsl_spmatrix structure is of size O(nzmax).

Function: int gsl_spmatrix_realloc (const size_t nzmax, gsl_spmatrix * m)

This function reallocates the storage space for m to accomodate nzmax non-zero elements. It is typically called internally by gsl_spmatrix_set if the user wants to add more elements to the sparse matrix than the previously specified nzmax.

Function: void gsl_spmatrix_free (gsl_spmatrix * m)

This function frees the memory associated with the sparse matrix m.