Adjusting the size of a general size matrix

Once a matrix has been created, its size may be adjusted dynamically as needs arise. Gandalf stores the currently allocated maximum size of a matrix in the matrix structure, so it can determine when the size of the result of a computation will exceed the current size, and reallocate accordingly. This happens automatically when a matrix is the result of a calculation, but sometimes it is necessary to explicitly set the size of a matrix. This is done using the following routine.

      Gan_Marix mA;

      /* create matrix A using e.g. gan_mat_form() */
      gan_mat_set_size ( &mA, 3 );

This resets the size of the matrix mA to 3. If the size of a matrix created by gan_mat_alloc() or gan_mat_form() is increased in size in this way beyond its originally allocated size, gan_mat_set_size() will automatically reallocate the matrix to the new size. On the other hand, if gan_mat_form_data() was used to create the matrix, it cannot be increased in size beyond the size of the array passed as the last argument into gan_mat_form_data().

For square matrices there are similar routines for specific matrix types, for instance

      Gan_SquMarix smA;

      /* create matrix A using e.g. gan_squmat_form() */
      gan_symmat_set_size ( &mA, 3 ); /* set A to be a symmetric matrix with size 3 */

An important feature here is that Gandalf allows both the size and type of the matrix to be changed. For instance, the following code is valid:

      Gan_SquMarix smA;

      gan_diagmat_form ( &smA, 2 ); /* create matrix A as diagonal with size 2 */
      gan_symmat_set_size ( &mA, 3 ); /* set A to be a symmetric matrix with size 3 */

Gandalf will reallocate the matrix internally if necessary. The main proviso here is that if the matrix was created using a ..._form_data() routine, setting it to a type and size which requires more independent elements than the size of the data array passed in is an error, so for instance

      Gan_SquMarix smA;
      double adAdata[10];

      /* create matrix A as diagonal with size 2 */
      gan_diagmat_form_data ( &smA, 2, adAdata, 10 );

      /* set A to be a symmetric matrix with size 4 */
      gan_symmat_set_size ( &mA, 4 );

is OK, because a $4\times 4$ symmetric matrix has ten independent elements, but an additional line

      gan_ltmat_set_size ( &smA, 5 ); /* set A to be a lower triangular matrix with size 5 */

will fail (return NULL), because a $5\times 5$ triangular matrix has fifteen independent elements (see Equation 3.1), and the array adAdata passed into the matrix originally has only ten elements.

The complete list of routines for setting a square matrix to a specific size (here 5) and type is

      gan_symmat_set_size ( &smA, 5 ); /* set A to be a 5x5 symmetric matrix */
      gan_ltmat_set_size ( &smA, 5 ); /* set A to be a 5x5 lower triangular matrix */
      gan_utmat_set_size ( &smA, 5 ); /* set A to be a 5x5 upper triangular matrix */
      gan_diagmat_set_size ( &smA, 5 ); /* set A to be a 5x5 diagonal matrix */
      gan_scalImat_set_size ( &smA, 5 ); /* set A to be a 5x5 scaled identity matrix */

and there is also a function for setting a matrix with a variable type:

      /* set A to be a symmetric matrix with size 5 */
      gan_squmat_set_type_size ( &smA, GAN_SYMMETRIC_MATRIX, 5 );

and routines to set only the type, or only the size, of the matrix:

      /* set A to be a symmetric matrix, size unchanged */
      gan_squmat_set_type ( &smA, GAN_SYMMETRIC_MATRIX );

      /* set A to be size 4, type unchanged */
      gan_squmat_set_size ( &smA, 4 );

Error detection: NULL is returned and the error handler is invoked on failure. The most likely failure mode is failing to reallocate the matrix data, i.e. failure of a call to realloc().