# SRC/slu_util.h File Reference

Utility header file. More...

`#include <stdio.h>`
`#include <stdlib.h>`
`#include <string.h>`
`#include <assert.h>`
`#include "superlu_enum_consts.h"`

Go to the source code of this file.

## Data Structures
struct | superlu_options_t
struct | e_node
| Headers for 4 types of dynamatically managed memory. More...
struct | LU_stack_t
struct | SuperLUStat_t
struct | mem_usage_t
## Defines
#define | FIRSTCOL_OF_SNODE(i) (xsup[i])
#define | NO_MARKER 3
#define | NUM_TEMPV(m, w, t, b) ( SUPERLU_MAX(m, (t + b)*w) )
#define | USER_ABORT(msg) superlu_abort_and_exit(msg)
#define | ABORT(err_msg)
#define | USER_MALLOC(size) superlu_malloc(size)
#define | SUPERLU_MALLOC(size) USER_MALLOC(size)
#define | USER_FREE(addr) superlu_free(addr)
#define | SUPERLU_FREE(addr) USER_FREE(addr)
#define | CHECK_MALLOC(where)
#define | SUPERLU_MAX(x, y) ( (x) > (y) ? (x) : (y) )
#define | SUPERLU_MIN(x, y) ( (x) < (y) ? (x) : (y) )
#define | L_SUB_START(col) ( Lstore->rowind_colptr[col] )
#define | L_SUB(ptr) ( Lstore->rowind[ptr] )
#define | L_NZ_START(col) ( Lstore->nzval_colptr[col] )
#define | L_FST_SUPC(superno) ( Lstore->sup_to_col[superno] )
#define | U_NZ_START(col) ( Ustore->colptr[col] )
#define | U_SUB(ptr) ( Ustore->rowind[ptr] )
#define | EMPTY (-1)
#define | FALSE 0
#define | TRUE 1
#define | NO_MEMTYPE 4
#define | GluIntArray(n) (5 * (n) + 5)
#define | NODROP ( 0x0000 )
#define | DROP_BASIC ( 0x0001 )
#define | DROP_PROWS ( 0x0002 )
#define | DROP_COLUMN ( 0x0004 )
#define | DROP_AREA ( 0x0008 )
#define | DROP_SECONDARY ( 0x000E )
#define | DROP_DYNAMIC ( 0x0010 )
#define | DROP_INTERP ( 0x0100 )
#define | MILU_ALPHA (1.0e-2)
## Typedefs
typedef float | flops_t
typedef unsigned char | Logical
typedef struct e_node | ExpHeader
## Functions
void | Destroy_SuperMatrix_Store (SuperMatrix *)
| Deallocate the structure pointing to the actual storage of the matrix.
void | Destroy_CompCol_Matrix (SuperMatrix *)
void | Destroy_CompRow_Matrix (SuperMatrix *)
void | Destroy_SuperNode_Matrix (SuperMatrix *)
void | Destroy_CompCol_Permuted (SuperMatrix *)
| A is of type Stype==NCP.
void | Destroy_Dense_Matrix (SuperMatrix *)
| A is of type Stype==DN.
void | get_perm_c (int, SuperMatrix *, int *)
void | set_default_options (superlu_options_t *options)
| Set the default values for the options argument.
void | ilu_set_default_options (superlu_options_t *options)
| Set the default values for the options argument for ILU.
void | sp_preorder (superlu_options_t *, SuperMatrix *, int *, int *, SuperMatrix *)
void | superlu_abort_and_exit (char *)
| Global statistics variale.
void * | superlu_malloc (size_t)
int * | intMalloc (int)
int * | intCalloc (int)
void | superlu_free (void *)
void | SetIWork (int, int, int, int *, int **, int **, int **, int **, int **, int **, int **)
| Set up pointers for integer working arrays.
int | sp_coletree (int *, int *, int *, int, int, int *)
void | relax_snode (const int, int *, const int, int *, int *)
void | heap_relax_snode (const int, int *, const int, int *, int *)
int | mark_relax (int, int *, int *, int *, int *, int *, int *)
void | ilu_relax_snode (const int, int *, const int, int *, int *, int *)
void | ilu_heap_relax_snode (const int, int *, const int, int *, int *, int *)
void | resetrep_col (const int, const int *, int *)
| Reset repfnz[] for the current column.
int | spcoletree (int *, int *, int *, int, int, int *)
int * | TreePostorder (int, int *)
double | SuperLU_timer_ ()
| Timer function.
int | sp_ienv (int)
int | lsame_ (char *, char *)
int | xerbla_ (char *, int *)
void | ifill (int *, int, int)
| Fills an integer array with a given value.
void | snode_profile (int, int *)
void | super_stats (int, int *)
void | check_repfnz (int, int, int, int *)
| Check whether repfnz[] == EMPTY after reset.
void | PrintSumm (char *, int, int, int)
| Print a summary of the testing results.
void | StatInit (SuperLUStat_t *)
void | StatPrint (SuperLUStat_t *)
void | StatFree (SuperLUStat_t *)
void | print_panel_seg (int, int, int, int, int *, int *)
| Diagnostic print of segment info after panel_dfs().
int | print_int_vec (char *, int, int *)
int | slu_PrintInt10 (char *, int, int *)

## Detailed Description

-- SuperLU routine (version 4.1) -- Univ. of California Berkeley, Xerox Palo Alto Research Center, and Lawrence Berkeley National Lab. November, 2010

## Define Documentation

#define ABORT | ( | err_msg |  | ) |

Value:

    { char msg[256];\
       sprintf(msg,"%s at line %d in file %s\n",err_msg,__LINE__, __FILE__);\
       USER_ABORT(msg); }

#define CHECK_MALLOC | ( | where |  | ) |

Value:

    {                 \
        extern int superlu_malloc_total;        \
        printf("%s: malloc_total %d Bytes\n",     \
               where, superlu_malloc_total); \
    }

#define DROP_AREA ( 0x0008 )

#define DROP_BASIC ( 0x0001 )

#define DROP_COLUMN ( 0x0004 )

#define DROP_DYNAMIC ( 0x0010 )

#define DROP_INTERP ( 0x0100 )

#define DROP_PROWS ( 0x0002 )

#define DROP_SECONDARY ( 0x000E )

#define EMPTY (-1)

#define FALSE 0

#define FIRSTCOL_OF_SNODE | ( | i |  | ) | (xsup[i])

#define GluIntArray | ( | n |  | ) | (5 * (n) + 5)

#define L_FST_SUPC | ( | superno |  | ) | ( Lstore->sup_to_col[superno] )

#define L_NZ_START | ( | col |  | ) | ( Lstore->nzval_colptr[col] )

#define L_SUB | ( | ptr |  | ) | ( Lstore->rowind[ptr] )

#define L_SUB_START | ( | col |  | ) | ( Lstore->rowind_colptr[col] )

#define MILU_ALPHA (1.0e-2)

#define NO_MARKER 3

#define NO_MEMTYPE 4

#define NODROP ( 0x0000 )

#define NUM_TEMPV | ( | m,
|  | w,
|  | t,
|  | b |  | ) | ( SUPERLU_MAX(m, (t + b)*w) )

#define SUPERLU_FREE | ( | addr |  | ) | USER_FREE(addr)

#define SUPERLU_MALLOC | ( | size |  | ) | USER_MALLOC(size)

#define SUPERLU_MAX | ( | x,
|  | y |  | ) | ( (x) > (y) ? (x) : (y) )

#define SUPERLU_MIN | ( | x,
|  | y |  | ) | ( (x) < (y) ? (x) : (y) )

#define TRUE 1

#define U_NZ_START | ( | col |  | ) | ( Ustore->colptr[col] )

#define U_SUB | ( | ptr |  | ) | ( Ustore->rowind[ptr] )

#define USER_ABORT | ( | msg |  | ) | superlu_abort_and_exit(msg)

#define USER_FREE | ( | addr |  | ) | superlu_free(addr)

#define USER_MALLOC | ( | size |  | ) | superlu_malloc(size)

## Typedef Documentation

typedef struct e_node ExpHeader

typedef float flops_t

typedef unsigned char Logical

## Function Documentation

void check_repfnz | ( | int | ,
|  | int | ,
|  | int | ,
|  | int * |  |
| ) |  |  |

void Destroy_CompCol_Matrix | ( | SuperMatrix * |  | ) |

void Destroy_CompCol_Permuted | ( | SuperMatrix * |  | ) |

void Destroy_CompRow_Matrix | ( | SuperMatrix * |  | ) |

void Destroy_Dense_Matrix | ( | SuperMatrix * |  | ) |

void Destroy_SuperMatrix_Store | ( | SuperMatrix * |  | ) |

void Destroy_SuperNode_Matrix | ( | SuperMatrix * |  | ) |

void get_perm_c | ( | int | ispec,
|  | SuperMatrix * | A,
|  | int * | perm_c |
| ) |  |  |

     Purpose
     =======

     GET_PERM_C obtains a permutation matrix Pc, by applying the multiple
     minimum degree ordering code by Joseph Liu to matrix A'*A or A+A'.
     or using approximate minimum degree column ordering by Davis et. al.
     The LU factorization of A*Pc tends to have less fill than the LU
     factorization of A.

     Arguments
     =========

     ispec   (input) int
             Specifies the type of column ordering to reduce fill:
             = 1: minimum degree on the structure of A^T * A
             = 2: minimum degree on the structure of A^T + A
             = 3: approximate minimum degree for unsymmetric matrices
             If ispec == 0, the natural ordering (i.e., Pc = I) is returned.

     A       (input) SuperMatrix*
             Matrix A in A*X=B, of dimension (A->nrow, A->ncol). The number
             of the linear equations is A->nrow. Currently, the type of A
             can be: Stype = NC; Dtype = _D; Mtype = GE. In the future,
             more general A can be handled.

     perm_c  (output) int*
    	   Column permutation vector of size A->ncol, which defines the
             permutation matrix Pc; perm_c[i] = j means column i of A is
             in position j in A*Pc.

void heap_relax_snode | ( | const int | n,
|  | int * | et,
|  | const int | relax_columns,
|  | int * | descendants,
|  | int * | relax_end |
| ) |  |  |

     Purpose
     =======
        relax_snode() - Identify the initial relaxed supernodes, assuming that
        the matrix has been reordered according to the postorder of the etree.

void ifill | ( | int * | ,
|  | int | ,
|  | int |  |
| ) |  |  |

void ilu_heap_relax_snode | ( | const int | n,
|  | int * | et,
|  | const int | relax_columns,
|  | int * | descendants,
|  | int * | relax_end,
|  | int * | relax_fsupc |
| ) |  |  |

     Purpose
     =======
        ilu_heap_relax_snode() - Identify the initial relaxed supernodes,
        assuming that the matrix has been reordered according to the postorder
        of the etree.

void ilu_relax_snode | ( | const int | n,
|  | int * | et,
|  | const int | relax_columns,
|  | int * | descendants,
|  | int * | relax_end,
|  | int * | relax_fsupc |
| ) |  |  |

     Purpose
     =======
        ilu_relax_snode() - Identify the initial relaxed supernodes, assuming
        that the matrix has been reordered according to the postorder of the
        etree.

void ilu_set_default_options | ( | superlu_options_t * | options | ) |

int* intCalloc | ( | int |  | ) |

int* intMalloc | ( | int |  | ) |

int lsame_ | ( | char * | ca,
|  | char * | cb |
| ) |  |  |

        Purpose
        =======

        LSAME returns .TRUE. if CA is the same letter as CB regardless of case.

        Arguments
        =========

        CA      (input) CHARACTER*1
        CB      (input) CHARACTER*1
                CA and CB specify the single characters to be compared.

       =====================================================================

int mark_relax | ( | int | n,
|  | int * | relax_end,
|  | int * | relax_fsupc,
|  | int * | xa_begin,
|  | int * | xa_end,
|  | int * | asub,
|  | int * | marker |
| ) |  |  |

     Purpose
     =======
        mark_relax() - record the rows used by the relaxed supernodes.

int print_int_vec | ( | char * | ,
|  | int | ,
|  | int * |  |
| ) |  |  |

void print_panel_seg | ( | int | ,
|  | int | ,
|  | int | ,
|  | int | ,
|  | int * | ,
|  | int * |  |
| ) |  |  |

void PrintSumm | ( | char * | ,
|  | int | ,
|  | int | ,
|  | int |  |
| ) |  |  |

void relax_snode | ( | const int | n,
|  | int * | et,
|  | const int | relax_columns,
|  | int * | descendants,
|  | int * | relax_end |
| ) |  |  |

     Purpose
     =======
        relax_snode() - Identify the initial relaxed supernodes, assuming that
        the matrix has been reordered according to the postorder of the etree.

void resetrep_col | ( | const | int,
|  | const int * | ,
|  | int * |  |
| ) |  |  |

void set_default_options | ( | superlu_options_t * | options | ) |

void SetIWork | ( | int | ,
|  | int | ,
|  | int | ,
|  | int * | ,
|  | int ** | ,
|  | int ** | ,
|  | int ** | ,
|  | int ** | ,
|  | int ** | ,
|  | int ** | ,
|  | int ** |  |
| ) |  |  |

int slu_PrintInt10 | ( | char * | ,
|  | int | ,
|  | int * |  |
| ) |  |  |

void snode_profile | ( | int | ,
|  | int * |  |
| ) |  |  |

int sp_coletree | ( | int * | ,
|  | int * | ,
|  | int * | ,
|  | int | ,
|  | int | ,
|  | int * |  |
| ) |  |  |

int sp_ienv | ( | int | ispec | ) |

        Purpose
        =======

        sp_ienv() is inquired to choose machine-dependent parameters for the
        local environment. See ISPEC for a description of the parameters.

        This version provides a set of parameters which should give good,
        but not optimal, performance on many of the currently available
        computers.  Users are encouraged to modify this subroutine to set
        the tuning parameters for their particular machine using the option
        and problem size information in the arguments.

        Arguments
        =========

        ISPEC   (input) int
                Specifies the parameter to be returned as the value of SP_IENV.
                = 1: the panel size w; a panel consists of w consecutive
    	         columns of matrix A in the process of Gaussian elimination.
    		 The best value depends on machine's cache characters.
                = 2: the relaxation parameter relax; if the number of
    	         nodes (columns) in a subtree of the elimination tree is less
    		 than relax, this subtree is considered as one supernode,
    		 regardless of their row structures.
                = 3: the maximum size for a supernode in complete LU;
    	    = 4: the minimum row dimension for 2-D blocking to be used;
    	    = 5: the minimum column dimension for 2-D blocking to be used;
    	    = 6: the estimated fills factor for L and U, compared with A;
    	    = 7: the maximum size for a supernode in ILU.

       (SP_IENV) (output) int
                >= 0: the value of the parameter specified by ISPEC
                < 0:  if SP_IENV = -k, the k-th argument had an illegal value.

        =====================================================================

void sp_preorder | ( | superlu_options_t * | options,
|  | SuperMatrix * | A,
|  | int * | perm_c,
|  | int * | etree,
|  | SuperMatrix * | AC |
| ) |  |  |

     Purpose
     =======

     sp_preorder() permutes the columns of the original matrix. It performs
     the following steps:

        1. Apply column permutation perm_c[] to A's column pointers to form AC;

        2. If options->Fact = DOFACT, then
           (1) Compute column elimination tree etree[] of AC'AC;
           (2) Post order etree[] to get a postordered elimination tree etree[],
               and a postorder permutation post[];
           (3) Apply post[] permutation to columns of AC;
           (4) Overwrite perm_c[] with the product perm_c * post.

     Arguments
     =========

     options (input) superlu_options_t*
             Specifies whether or not the elimination tree will be re-used.
             If options->Fact == DOFACT, this means first time factor A,
             etree is computed, postered, and output.
             Otherwise, re-factor A, etree is input, unchanged on exit.

     A       (input) SuperMatrix*
             Matrix A in A*X=B, of dimension (A->nrow, A->ncol). The number
             of the linear equations is A->nrow. Currently, the type of A can be:
             Stype = NC or SLU_NCP; Mtype = SLU_GE.
             In the future, more general A may be handled.

     perm_c  (input/output) int*
    	   Column permutation vector of size A->ncol, which defines the
             permutation matrix Pc; perm_c[i] = j means column i of A is
             in position j in A*Pc.
             If options->Fact == DOFACT, perm_c is both input and output.
             On output, it is changed according to a postorder of etree.
             Otherwise, perm_c is input.

     etree   (input/output) int*
             Elimination tree of Pc'*A'*A*Pc, dimension A->ncol.
             If options->Fact == DOFACT, etree is an output argument,
             otherwise it is an input argument.
             Note: etree is a vector of parent pointers for a forest whose
             vertices are the integers 0 to A->ncol-1; etree[root]==A->ncol.

     AC      (output) SuperMatrix*
             The resulting matrix after applied the column permutation
             perm_c[] to matrix A. The type of AC can be:
             Stype = SLU_NCP; Dtype = A->Dtype; Mtype = SLU_GE.

int spcoletree | ( | int * | ,
|  | int * | ,
|  | int * | ,
|  | int | ,
|  | int | ,
|  | int * |  |
| ) |  |  |

void StatFree | ( | SuperLUStat_t * |  | ) |

void StatInit | ( | SuperLUStat_t * |  | ) |

void StatPrint | ( | SuperLUStat_t * |  | ) |

void super_stats | ( | int | ,
|  | int * |  |
| ) |  |  |

void superlu_abort_and_exit | ( | char * |  | ) |

void superlu_free | ( | void * |  | ) |

void* superlu_malloc | ( | size_t | size | ) |

Precision-independent memory-related routines. (Shared by [sdcz]memory.c)

double SuperLU_timer_ | ( |  | ) |

int* TreePostorder | ( | int | ,
|  | int * |  |
| ) |  |  |

int xerbla_ | ( | char * | ,
|  | int * |  |
| ) |  |  |