SuperLU 6.0.1
Data Structures | Macros | Typedefs | Functions
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"
Include dependency graph for slu_util.h:
This graph shows which files directly or indirectly include this file:

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
 
struct  GlobalLU_t
 

Macros

#define SUPERLU_MAJOR_VERSION   6
 
#define SUPERLU_MINOR_VERSION   0
 
#define SUPERLU_PATCH_VERSION   1
 
#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 GluIntArray(n)   (5 * (n) + 5)
 
#define NODROP   ( 0x0000 )
 
#define DROP_BASIC   ( 0x0001 ) /* ILU(tau) */
 
#define DROP_PROWS   ( 0x0002 ) /* ILUTP: keep p maximum rows */
 
#define DROP_COLUMN
 
#define DROP_AREA
 
#define DROP_SECONDARY   ( 0x000E ) /* PROWS | COLUMN | AREA */
 
#define DROP_DYNAMIC   ( 0x0010 ) /* adaptive tau */
 
#define DROP_INTERP   ( 0x0100 ) /* use interpolation */
 
#define MILU_ALPHA   (1.0e-2) /* multiple of drop_sum to be added to diagonal */
 

Typedefs

typedef float flops_t
 
typedef unsigned char Logical
 
typedef struct e_node ExpHeader
 Headers for 4 types of dynamatically managed memory. More...
 

Functions

int input_error (char *, int *)
 
void Destroy_SuperMatrix_Store (SuperMatrix *)
 Deallocate the structure pointing to the actual storage of the matrix. More...
 
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. More...
 
void Destroy_Dense_Matrix (SuperMatrix *)
 A is of type Stype==DN. More...
 
void get_perm_c (int, SuperMatrix *, int *)
 
void set_default_options (superlu_options_t *options)
 Set the default values for the options argument. More...
 
void ilu_set_default_options (superlu_options_t *options)
 Set the default values for the options argument for ILU. More...
 
void sp_preorder (superlu_options_t *, SuperMatrix *, int *, int *, SuperMatrix *)
 
void superlu_abort_and_exit (char *)
 Global statistics variale. More...
 
void * superlu_malloc (size_t)
 
int * int32Malloc (int)
 
int * int32Calloc (int)
 
int_tintMalloc (int_t)
 
int_tintCalloc (int_t)
 
void superlu_free (void *)
 
void SetIWork (int, int, int, int *, int **, int **, int_t **xplore, int **, int **, int_t **xprune, int **)
 Set up pointers for integer working arrays. More...
 
int sp_coletree (int_t *, int_t *, int_t *, 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_t *, int_t *, int_t *, int *)
 
void countnz (const int n, int_t *xprune, int_t *nnzL, int_t *nnzU, GlobalLU_t *)
 Count the total number of nonzeros in factors L and U, and in the symmetrically reduced L. More...
 
void ilu_countnz (const int, int_t *, int_t *, GlobalLU_t *)
 Count the total number of nonzeros in factors L and U. More...
 
void fixupL (const int, const int *, GlobalLU_t *)
 Fix up the data storage lsub for L-subscripts. It removes the subscript sets for structural pruning, and applies permuation to the remaining subscripts. More...
 
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. More...
 
int spcoletree (int *, int *, int *, int, int, int *)
 
int * TreePostorder (int, int *)
 
double SuperLU_timer_ (void)
 Timer function. More...
 
int sp_ienv (int)
 sp_ienv() is inquired to choose machine-dependent parameters for the local environment. More...
 
int xerbla_ (char *, int *)
 
void ifill (int *, int, int)
 Fills an integer array with a given value. More...
 
void snode_profile (int, int *)
 
void super_stats (int, int *)
 
void check_repfnz (int, int, int, int *)
 Check whether repfnz[] == EMPTY after reset. More...
 
void PrintSumm (char *, int, int, int)
 Print a summary of the testing results. More...
 
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(). More...
 
int print_int_vec (char *, int, int *)
 
int slu_PrintInt10 (char *, int, int *)
 
int check_perm (char *what, int n, int *perm)
 

Detailed Description

Copyright (c) 2003, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from U.S. Dept. of Energy)

All rights reserved.

The source code is distributed under BSD license, see the file License.txt at the top-level directory.

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

Macro Definition Documentation

◆ ABORT

#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); }

◆ CHECK_MALLOC

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

◆ DROP_AREA

#define DROP_AREA
Value:
( 0x0008 ) /* ILUTP: for j-th column, use
nnz(F(:,1:j)) / nnz(A(:,1:j))
to limit memory growth */

◆ DROP_BASIC

#define DROP_BASIC   ( 0x0001 ) /* ILU(tau) */

◆ DROP_COLUMN

#define DROP_COLUMN
Value:
( 0x0004 ) /* ILUTP: for j-th column,
p = gamma * nnz(A(:,j)) */

◆ DROP_DYNAMIC

#define DROP_DYNAMIC   ( 0x0010 ) /* adaptive tau */

◆ DROP_INTERP

#define DROP_INTERP   ( 0x0100 ) /* use interpolation */

◆ DROP_PROWS

#define DROP_PROWS   ( 0x0002 ) /* ILUTP: keep p maximum rows */

◆ DROP_SECONDARY

#define DROP_SECONDARY   ( 0x000E ) /* PROWS | COLUMN | AREA */

◆ EMPTY

#define EMPTY   (-1)

◆ FALSE

#define FALSE   0

◆ FIRSTCOL_OF_SNODE

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

◆ GluIntArray

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

◆ L_FST_SUPC

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

◆ L_NZ_START

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

◆ L_SUB

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

◆ L_SUB_START

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

◆ MILU_ALPHA

#define MILU_ALPHA   (1.0e-2) /* multiple of drop_sum to be added to diagonal */

◆ NO_MARKER

#define NO_MARKER   3

◆ NODROP

#define NODROP   ( 0x0000 )

◆ NUM_TEMPV

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

◆ SUPERLU_FREE

#define SUPERLU_FREE (   addr)    USER_FREE(addr)

◆ SUPERLU_MAJOR_VERSION

#define SUPERLU_MAJOR_VERSION   6

◆ SUPERLU_MALLOC

#define SUPERLU_MALLOC (   size)    USER_MALLOC(size)

◆ SUPERLU_MAX

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

◆ SUPERLU_MIN

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

◆ SUPERLU_MINOR_VERSION

#define SUPERLU_MINOR_VERSION   0

◆ SUPERLU_PATCH_VERSION

#define SUPERLU_PATCH_VERSION   1

◆ TRUE

#define TRUE   1

◆ U_NZ_START

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

◆ U_SUB

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

◆ USER_ABORT

#define USER_ABORT (   msg)    superlu_abort_and_exit(msg)

◆ USER_FREE

#define USER_FREE (   addr)    superlu_free(addr)

◆ USER_MALLOC

#define USER_MALLOC (   size)    superlu_malloc(size)

Typedef Documentation

◆ ExpHeader

typedef struct e_node ExpHeader

◆ flops_t

typedef float flops_t

◆ Logical

typedef unsigned char Logical

Function Documentation

◆ check_perm()

int check_perm ( char *  what,
int  n,
int *  perm 
)
Here is the call graph for this function:

◆ check_repfnz()

void check_repfnz ( int  n,
int  w,
int  jcol,
int *  repfnz 
)

◆ countnz()

void countnz ( const int  n,
int_t xprune,
int_t nnzL,
int_t nnzU,
GlobalLU_t Glu 
)

◆ Destroy_CompCol_Matrix()

void Destroy_CompCol_Matrix ( SuperMatrix A)

◆ Destroy_CompCol_Permuted()

void Destroy_CompCol_Permuted ( SuperMatrix A)

◆ Destroy_CompRow_Matrix()

void Destroy_CompRow_Matrix ( SuperMatrix A)

◆ Destroy_Dense_Matrix()

void Destroy_Dense_Matrix ( SuperMatrix A)

◆ Destroy_SuperMatrix_Store()

void Destroy_SuperMatrix_Store ( SuperMatrix A)

◆ Destroy_SuperNode_Matrix()

void Destroy_SuperNode_Matrix ( SuperMatrix A)

◆ fixupL()

void fixupL ( const int  n,
const int *  perm_r,
GlobalLU_t Glu 
)

◆ get_perm_c()

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.
Here is the call graph for this function:

◆ heap_relax_snode()

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.
Here is the call graph for this function:

◆ ifill()

void ifill ( int *  a,
int  alen,
int  ival 
)

◆ ilu_countnz()

void ilu_countnz ( const int  n,
int_t nnzL,
int_t nnzU,
GlobalLU_t Glu 
)

◆ ilu_heap_relax_snode()

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.
Here is the call graph for this function:

◆ ilu_relax_snode()

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.
Here is the call graph for this function:

◆ ilu_set_default_options()

void ilu_set_default_options ( superlu_options_t options)
Here is the call graph for this function:

◆ input_error()

int input_error ( char *  srname,
int *  info 
)
Purpose   
=======   

INPUT_ERROR is called if an input parameter has an   
invalid value.  A message is printed and execution stops.   

Arguments   
=========   

srname  (input) character*6
        The name of the routine which called INPUT_ERROR.

info    (input) int
        The position of the invalid parameter in the parameter list   
        of the calling routine.

◆ int32Calloc()

int * int32Calloc ( int  n)

◆ int32Malloc()

int * int32Malloc ( int  n)

◆ intCalloc()

int_t * intCalloc ( int_t  n)

◆ intMalloc()

int_t * intMalloc ( int_t  n)

◆ mark_relax()

int mark_relax ( int  n,
int *  relax_end,
int *  relax_fsupc,
int_t xa_begin,
int_t xa_end,
int_t asub,
int *  marker 
)
Purpose
=======
   mark_relax() - record the rows used by the relaxed supernodes.

◆ print_int_vec()

int print_int_vec ( char *  what,
int  n,
int *  vec 
)

◆ print_panel_seg()

void print_panel_seg ( int  n,
int  w,
int  jcol,
int  nseg,
int *  segrep,
int *  repfnz 
)

◆ PrintSumm()

void PrintSumm ( char *  type,
int  nfail,
int  nrun,
int  nerrs 
)

◆ relax_snode()

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.
Here is the call graph for this function:

◆ resetrep_col()

void resetrep_col ( const int  nseg,
const int *  segrep,
int *  repfnz 
)

◆ set_default_options()

void set_default_options ( superlu_options_t options)

◆ SetIWork()

void SetIWork ( int  m,
int  n,
int  panel_size,
int *  iworkptr,
int **  segrep,
int **  parent,
int_t **  xplore,
int **  repfnz,
int **  panel_lsub,
int_t **  xprune,
int **  marker 
)
Here is the call graph for this function:

◆ slu_PrintInt10()

int slu_PrintInt10 ( char *  name,
int  len,
int *  x 
)

◆ snode_profile()

void snode_profile ( int  ,
int *   
)

◆ sp_coletree()

int sp_coletree ( int_t acolst,
int_t acolend,
int_t arow,
int  nr,
int  nc,
int *  parent 
)
Here is the call graph for this function:

◆ sp_ienv()

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. 

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

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.

Parameters
[in]ispecSpecifies 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.
Returns
>= 0: the value of the parameter specified by ispec.
< 0: if SP_IENV = -k, the k-th argument had an illegal value.

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.

Parameters
[in]ispecSpecifies 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 the their row structures.
= 3: the maximum size for a supernode;
= 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;
Returns
>= 0: the value of the parameter specified by ISPEC
< 0: if SP_IENV = -k, the k-th argument had an illegal value.
Here is the call graph for this function:

◆ sp_preorder()

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.
Here is the call graph for this function:

◆ spcoletree()

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

◆ StatFree()

void StatFree ( SuperLUStat_t stat)

◆ StatInit()

void StatInit ( SuperLUStat_t stat)
Here is the call graph for this function:

◆ StatPrint()

void StatPrint ( SuperLUStat_t stat)

◆ super_stats()

void super_stats ( int  nsuper,
int *  xsup 
)
Here is the call graph for this function:

◆ superlu_abort_and_exit()

void superlu_abort_and_exit ( char *  msg)

◆ superlu_free()

void superlu_free ( void *  addr)

◆ superlu_malloc()

void * superlu_malloc ( size_t  size)

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

◆ SuperLU_timer_()

double SuperLU_timer_ ( void  )

◆ TreePostorder()

int * TreePostorder ( int  n,
int *  parent 
)
Here is the call graph for this function:

◆ xerbla_()

int xerbla_ ( char *  ,
int *   
)