Manipulation and Setup

The first routine that should be called is BSmain_perm(), which takes the context and the user's sparse matrix as arguments. This routine colors and permutes the sparse matrix to create a new version of the sparse matrix appropriate for parallel computation. The user's sparse matrix is not permanently changed during this routine, but may be manipulated and restored during execution. If BSmain_perm() has already been called with the ``retain'' parameter set to true, then the user can call BSmain_reperm() to permute a matrix with the same structure as was permuted in the original call to BSmain_perm().

After calling BSmain_perm(), the matrix can then be diagonally scaled by calling BSscale_diag().

Prior to either factoring or solving the matrix, the communication patterns used by BlockSolve must be created. For factorization this can be done by calling BSsetup_factor(). For matrix solution, this is done by calling BSsetup_forward(). Both routines return the communication pattern. The communication patterns may be freed by calling BSfree_comm().

If an incomplete factor is to be created, then a copy of the matrix must be made. In addition, if the factorization fails as a result of a zero or negative diagonal being encountered during the factorization, the matrix must be recopied and the factorization retried. The following loop accomplishes this task. It is important to note that the copy of the sparse matrix shares the clique storage space with the matrix that it is copied from (for more information see the ``man'' page on BScopy_par_mat()). The routine BSset_diag() is used to change the entire diagonal to alpha; in other words, we are shifting the diagonal of the matrix by 0.1 every time the factorization fails. Other strategies are certainly possible and could easily be implemented by the user.

    alpha = 1.0;
    /* get a copy of the sparse matrix */
    f_pA = BScopy_par_mat(pA);
    /* factor the matrix until successful */
    while (BSfactor(f_pA,f_comm,procinfo) != 0) {
        /* recopy just the nonzero values */
        BScopy_nz(pA,f_pA);
        /* increment the diagonal shift */
        alpha += 0.1;
        BSset_diag(f_pA,alpha,procinfo);
    }

To free the parallel matrix created by BSmain_perm(), call the routine BSfree_par_mat(). To free a copy of a parallel matrix created by BScopy_par_mat(), call the routine BSfree_copy_par_mat().