PLAPACK C INTERFACE


Index to Chapters


Chapter 2: Templates and Linear Algebra Objects

Back to Index to Chapters -- Back to Index to Chapters -- Forward to Chapter 3

Section 2.1: Initializing PLAPACK
PLA_Init
PLA_Finalize
PLA_Initialized
PLA_Base_comm
PLA_Comm_1D_to_2D
PLA_Comm_1D_to_2D_ratio

Section 2.2: Distribution Templates
PLA_Temp_create
PLA_Temp_free
PLA_Temp_comm_all_info
PLA_Temp_comm_row_info
PLA_Temp_comm_col_info
PLA_Temp_nb
PLA_Temp_zero_or_one

Section 2.3: Linear Algebra Objects
PLA_Vector_create
PLA_Mvector_create
PLA_Matrix_create
PLA_Mscalar_create
PLA_Pvector_create
PLA_Pmvector_create
PLA_Obj_free
PLA_Obj_objtype
PLA_Obj_datatype
PLA_Obj_template
PLA_Obj_global_info
PLA_Obj_global_length
PLA_Obj_global_width
PLA_Obj_global_size
PLA_Obj_global_numvecs
PLA_Obj_project_onto
PLA_Obj_owner_row
PLA_Obj_owner_col
PLA_Obj_global_align
PLA_Obj_global_align_row
PLA_Obj_global_align_col
PLA_Obj_local_info
PLA_Obj_local_length
PLA_Obj_local_width
PLA_Obj_local_buffer
PLA_Obj_local_stride
PLA_Obj_local_ldim
PLA_Obj_get_local_contents
PLA_Obj_set_local_contents
PLA_Obj_set
PLA_Obj_set_to_zero
PLA_Obj_set_to_one
PLA_Obj_set_to_minus_one

int PLA_Init(MPI_Comm     comm)

Purpose : Initialize PLAPACK library.

IN     comm        base communicator to be used by PLAPACK



int PLA_Finalize ( )
Purpose : Exit PLAPACK library.




int PLA_Initialized (int *initialized )
Purpose : Check if PLAPACK is initialized.

OUT     initialized     indicates whether PLAPACK is already initialized     




int PLA_Base_comm(MPI_Comm *comm)


Purpose : Extract the PLAPACK base communicator.

OUT   comm            PLAPACK base communicator



int PLA_Comm_1D_to_2D(MPI_Comm comm1D,   int           nprows, 
                      int npcols,        MPI_Comm      *comm2D)


Purpose : Create a communicator with a nprows by npcols topology.

IN    comm1D          communicator from which to create 2D communictor
IN    nprows          row dimension of 2D topology
IN    npcols          column dimension of 2D topology
OUT   comm2D          communicator with 2D topology



int PLA_Comm_1D_to_2D_ratio(MPI_Comm comm1D,   float       ratio, 
                            MPI_Comm      *comm2D)


Purpose : Create a communicator with a suggested ratio (nprows/npcols = ratio).

IN    comm1D          communicator from which to create 2D communictor
IN    ratio           suggested ratio of row and column dimensions
OUT   comm2D          communicator with 2D topology



int PLA_Temp_create(int           nb,      int zero_or_one, 
                    PLA_Template *template)


Purpose : Create template for vector and matrix alignment

IN    nb              length of subvectors of inducing vector and vector template
IN    zero_or_one     indexing starts with zero or one
OUT   template        template for matrix and vector distribution 


int PLA_Temp_free(PLA_Template *template) 

Purpose : Free a template

IN/OUT template template for vector and matrix distribution



int PLA_Temp_comm_all_info(PLA_Template template, MPI_Comm *comm, 
                           int          *rank,    int      *numnodes)



Purpose : Extract communicator, calling node's rank in communicator, 
          and number of nodes in communicator.

IN      template      template for vector and matrix distribution
OUT     comm          communicator of node mesh 
OUT     rank          rank of calling node within node mesh
OUT     numnodes      number of nodes within node mesh




int PLA_Temp_comm_row_info(PLA_Template template, MPI_Comm *comm, 
                           int          *rank,    int      *numnodes)


Purpose : Extract row communictor, calling node's rank in communicator, 
          and number of nodes in communicator.

IN     template    template for vector and matrix distribution
OUT    comm        communicator for calling node's row of nodes
OUT    rank        rank of calling node within row of nodes
OUT    numnodes    number of nodes within row of nodes



int PLA_Temp_comm_col_info(PLA_Template template, MPI_Comm *comm, 
                           int          *rank,    int      *numnodes)



Purpose : Extract column communictor, calling node's rank in communicator, 
          and number of nodes in communicator.

IN     template    template for vector and matrix distribution
OUT    comm        communicator for calling node's column of nodes
OUT    rank        rank of calling node within column of nodes
OUT    numnodes    number of nodes within column of nodes



int PLA_Temp_nb   (PLA_Template     template,     int    *nb)



Purpose : Extract template block size 
 

IN     template         template for vector and matrix distribution
OUT    nb               block size of template


int PLA_Temp_zero_or_one   (PLA_Template     template,     int    *zero_or_one)



Purpose : Extract index start parameter 
 
 
IN     template         template for vector and matrix distribution
OUT    zero_or_one      indexing may start with zero or one



int PLA_Vector_create   (MPI_Datatype   datatype,   int    global_length,
                         PLA_Template   template,   int    global_align,
                         PLA_Obj       *new_obj)



Purpose : Create distributed vector. 
 
 
IN     datatype          datatype of object
IN     global_length     global length of vector
IN     template          template for vector and matrix distribution
IN     global_align      alignment to template
OUT    new_obj           object describing created vector



int PLA_Mvector_create   (MPI_Datatype   datatype,        int            global_length,
                          int            global_width,    PLA_Template   template,   
                          int            global_align,    PLA_Obj       *new_obj)



Purpose : Create distributed multi-vector. 
 
 
IN     datatype          datatype of object
IN     global_length     global length of multi-vector
IN     global_width      global width of multi-vector
IN     template          template for vector and matrix distribution
IN     global_align      alignment to template
OUT    new_obj           object describing created multi-vector



int PLA_Matrix_create   (MPI_Datatype   datatype,          int            global_length,
                         int            global_width,      PLA_Template   template,   
                         int            global_align_row,  int            global_align_col,
                         PLA_Obj       *new_matrix)



Purpose : Create distributed matrix. 
 
 
IN     datatype          datatype of object
IN     global_length     global length of matrix
IN     global_width      global width of matrix
IN     template          template for vector and matrix distribution
IN     global_align_row  row alignment to template
IN     global_align_col  column alignment to template
OUT    new_matrix        object describing created matrix



int PLA_Mscalar_create  (MPI_Datatype   datatype,          int            owner_row,
                         int            owner_col,         int            length,
                         int            width,             PLA_Template   template,   
                         PLA_Obj       *new_mscalar)



Purpose : Create distributed mutltiscalar. 
 
 
IN     datatype          datatype of object
IN     owner_row         index of row of nodes with contains owning node(s)
IN     owner_col         index of column of nodes with contains owning node(s)
IN     length            length of mscalar
IN     width             width of mscalar
IN     template          template for vector and matrix distribution
OUT    new_mscalar       object describing created multiscalar



int PLA_Pvector_create  (MPI_Datatype   datatype,          int            project_onto,
                         int            owner,             int            global_length,
                         PLA_Template   template,          int            global_align,
                         PLA_Obj       *new_proj_vector)



Purpose : Create projected vector. 
 
 
IN     datatype          datatype of object
IN     project_onto      direction onto which to project 
IN     owner             index of row or column of nodes wich containts projected vector
IN     global_length     length of (projected) vector
IN     global_align      alignment to template
IN     template          template for vector and matrix distribution
OUT    new_proj_vector   object describing created projected vector



int PLA_Pmvector_create  (MPI_Datatype   datatype,           int            project_onto,
                          int            owner,              int            global_proj_length,
                          int            global_proj_width,  PLA_Template   template,          
                          int            global_align,       PLA_Obj       *new_proj_mvector)



Purpose : Create projected multi-vector. 
 
 
IN     datatype              datatype of object
IN     project_onto          direction onto which to project 
IN     owner                 index of row or column of nodes wich containts projected vector
IN     global_proj_length    length of (projected) vector
IN     global_proj_width     width of (projected) vector
IN     global_align          alignment to template
IN     template              template for vector and matrix distribution
OUT    new_proj_mvector      object describing created projected multi-vector



int PLA_Obj_free   (PLA_Obj   *obj)



Purpose : Linear algebra object destructor. 
 
 
IN/OUT     object      object to be freet



int PLA_Obj_objtype  (PLA_Obj     obj,    int *objtype)



Purpose : Extract object type from object. 
 
 
IN         obj        object to be queried
OUT        objtype    object type of object



int PLA_Obj_datatype  (PLA_Obj     obj,    MPI_Datatype *datatype)



Purpose : Extract datatype from object. 
 
 
IN         obj         object to be queried
OUT        datatype    datatype of object



int PLA_Obj_template   (PLA_Obj   obj,     PLA_Template    *template)



Purpose : Extract template from object. 
 
 
IN         obj               object to be queried
OUT        template          template



int PLA_Obj_global_info   (PLA_Obj   obj,             int    *global_length,
                           int       *global_width,   int    *project_onto,
                           int       *owner_row,      int    *owner_col,
                           int       *global_align(_row),
                           int       *global_align_col)



Purpose :  Extract global information from linear algebra object.  

Note that the individual fields can be queried (separately) through calls to PLA_Obj_global(_field-name).
IN obj object to be queried OUT global_length global row dimension of object OUT global_width global column dimension of object OUT project_onto direction of projection OUT owner_row row index of owning node(s) OUT owner_col column index of owning node(s) OUT global_align(_row) (row) alignment to template OUT global_align_col column alignment to template



int PLA_Obj_global_length (PLA_Obj   obj,             int    *global_length )



Purpose :  Extract global length from linear algebra object.

IN         obj                 object to be queried
OUT        global_length       global row dimension of object



int PLA_Obj_global_width (PLA_Obj   obj,             int    *global_width )



Purpose :  Extract global width from linear algebra object.

IN         obj                 object to be queried
OUT        global_width        global column dimension of object



int PLA_Obj_project_onto  (PLA_Obj   obj,         int    *project_onto )



Purpose :  Extract projection information from linear algebra object.  
 

IN         obj                 object to be queried
OUT        project_onto        direction of projection



int PLA_Obj_owner_row     (PLA_Obj   obj,           int       *owner_row )



Purpose :  Extract mesh row owner information rom linear algebra object.  
 

IN         obj                 object to be queried
OUT        owner_row           row index of owning node(s)
OUT        owner_col           column index of owning node(s)




int PLA_Obj_owner_col     (PLA_Obj   obj,           int       *owner_col )



Purpose :  Extract mesh column owner information rom linear algebra object.  
 

IN         obj                 object to be queried
OUT        owner_col           column index of owning node(s)



int PLA_Obj_global_align  (PLA_Obj   obj,      int       *global_align )



Purpose :  Extract global alignment from linear algebra object.  
 

IN         obj                 object to be queried
OUT        global_align        Alignment to template



int PLA_Obj_global_align_row  
                     (PLA_Obj   obj,      int       *global_align_row )



Purpose :  Extract global row alignment from linear algebra object.  
 

IN         obj                 object to be queried
OUT        global_align_row  row alignment to template



int PLA_Obj_global_align_col  
          (PLA_Obj   obj,      int       *global_align_col )



Purpose :  Extract global column alignment from linear algebra object.  
 

IN         obj                 object to be queried
OUT        global_align_col    column alignment to template




int PLA_Obj_local_info   (PLA_Obj   obj,             int    *local_length,
                          int       *local_width,    void   **local_buffer,
                          int       *local_stride,   int    *local_ldim)



Purpose :  Extract local information from linear algebra object.  

Note that the individual fields can be queried (separately) through calls to PLA_Obj_local(_field-name).
IN obj object to be queried OUT local_length local row dimension of object OUT local_width local column dimension of object OUT local_buffer address of local data OUT local_stride stride between entries in a column or vector OUT local_ldim leading dimension of array holding local data



int PLA_Obj_get_local_contents   (PLA_Obj       laobject,         int      transpose,
                                  int           *rows_in_buf,     int      *cols_in_buf,
                                  void          *buf,             int      leading_dim_buf,
                                  int           stride_buf)



Purpose : Extract the local data from the given object. 
 
 
IN     laobject          global object
IN     transpose         indicates whether to transpose data
OUT    rows_in_buf       row dimension of extracted data
OUT    cols_in_buf       column dimension of extracted data
OUT    buf               address where data is to be put
IN     leading_dim       leading dimension of buffer where data is put
IN     stride_buf        stride of buffer where data is put


PLA_Obj_set_local_contents

int PLA_Obj_set_local_contents   (int      transpose,             int      rows_in_buf,     
                                  int      cols_in_buf,           void     *buf,             
                                  int      leading_dim_buf,       int      stride_buf,
                                  PLA_Obj  laobject)



Purpose : Set the local data from the given object. 
 
 
IN        transpose         indicates whether to transpose data
IN        rows_in_buf       row dimension of data buffer
IN        cols_in_buf       column dimension of data buffer
IN        buf               address of data buffer
IN        leading_dim       leading dimension of data buffer
IN        stride_buf        stride of data buffer where data is put
IN/OUT    laobject          global object



int PLA_Obj_set   (PLA_Obj      obj,    MPI_Datatype   datatype,
                   void         *value )



Purpose : Sets all entries in the linear algebra object to value given
by value. The value is cast to the given MPI_Datatype via the datatype
parameter. 
 
 
IN/OUT          obj          linear algebra object
IN              datatype     datatype of value
IN             *value        value to be used for initialization



int PLA_Obj_set_to_zero   (PLA_Obj      obj)



Purpose : Sets all entries in the linear algebra object to zero (0).
The value is cast to the appropriate type (MPI_FLOAT, MPI_DOUBLE, etc.)
where the datatype is the same as that of obj. 
 
 
IN/OUT          obj          linear algebra object



int PLA_Obj_set_to_one   (PLA_Obj      obj)



Purpose : Sets all entries in the linear algebra object to one (1).
The value is cast to the appropriate type (MPI_FLOAT, MPI_DOUBLE, etc.)
where the datatype is the same as that of obj. 
 
 
IN/OUT          obj          linear algebra object



int PLA_Obj_set_to_minus_one   (PLA_Obj      obj)



Purpose : Sets all entries in the linear algebra object to negative
one (-1). The value is cast to the appropriate type (MPI_FLOAT, MPI_DOUBLE,
etc.) where the datatype is the same as that of obj. 
 
 
IN/OUT          obj          linear algebra object


Chapter 3: Advanced Linear Algebra Object Manipulation

Back to Index to Chapters -- Back to Chapter 2 -- Forward to Chapter 4

Section 3.1: Creating Views into Objects
PLA_Obj_view
PLA_Obj_view_all
PLA_Obj_view_swap


Section 3.2: Splitting of LAObjs
PLA_Obj_split_4
PLA_Obj_horz_split_2
PLA_Obj_vert_split_2


Section 3.3: Shifting of LAObjs
PLA_Obj_view_shift


Section 3.4: Determining Where to Split
PLA_Obj_split_size
Section 3.5: Creating Objects "Conformal to" ...
PLA_Vector_create_conf_to
PLA_Mvector_create_conf_to
PLA_Pvector_create_conf_to
PLA_Pmvector_create_conf_to
PLA_Matrix_create_conf_to
PLA_Mscalar_create_conf_to
PLA_Create_constants_conf_to


Section 3.6: Annotating Object Orientation
PLA_Obj_set_orientation
PLA_Obj_get_orientation



Section 3.7: Casting Object Types
PLA_Obj_objtype_cast


int PLA_Obj_view   (PLA_Obj     old_obj,         int      global_length,
                    int         global_width,    int      align_row,
                    int         align_col,       PLA_Obj *new_obj)


Purpose : Create a view (reference) into an existing linear algebra
object. 
 

IN     old_obj          object into which view is taken
IN     global_length    row dimension of view
IN     global_width     column dimension of view
IN     align_row        row index in old object of upper-left-hand element of view
IN     align_col        column index in old object of upper-left-hand element of view
IN/OUT new_obj          created view



int PLA_Obj_view_all   (PLA_Obj     old_obj,      PLA_Obj     *new_obj)



Purpose : Create a view (reference) into all of existing linear algebra
object. 
 
 
IN          old_obj          object into which view is taken
IN/OUT      new_obj          created view



int PLA_Obj_view_swap    ( PLA_Obj     *obj1,        PLA_Obj   *obj2)



Purpose : Swaps two views. 
 
 
IN/OUT      obj1          linear algebra object
IN/OUT      obj2          linear algebra object



int PLA_Obj_split_4  (PLA_Obj       obj,
                      int           length,            int           width,
                      PLA_Obj       *upper_left_obj,   PLA_Obj       *upper_right_obj,
                      PLA_Obj       *lower_left_obj,   PLA_Obj       *lower_right_obj)



Purpose : Split linear algebra object into four quadrants 
 
 
IN         obj               object to be split
IN         length            row dimension of block (as indicated below) 
IN         width             column dimension of block (as indicated below) 
OUT        upper_left_obj    new object for upper-left block
OUT        upper_right_obj   new object for upper-right block
OUT        lower_left_obj    new object for lower-left block
OUT        lower_right_obj   new object for lower-right block

Here the value of length and width determine the size of one block while
their sign determines which block the length and widht refer to.
If :
length >= 0        width >= 0            upper_left_obj
length <  0        width >= 0            lower_left_obj
length >= 0        width <  0            upper_right_obj
length <  0        width <  0            lower_right_obj



int PLA_Obj_horz_split_2   (  PLA_Obj     obj,      int          length,
                                                    PLA_Obj      *upper_obj,
                                                    PLA_Obj      *lower_obj)



Purpose : Split linear algebra object into top and bottom 
 
 
IN         obj               object to be split
IN         length            row dimension of block (as indicated below) 
OUT        upper_obj         new object for upper block
OUT        lower_obj         new object for lower block

If : 
length >= 0     length specifies   upper_obj
length <  0     length specifies   lower_obj



int PLA_Obj_vert_split_2   (  PLA_Obj     obj,           int          width,
                              PLA_Obj      *left_obj,    PLA_Obj      *right_obj)



Purpose : Split linear algebra object into left and right 
 
 
IN         obj               object to be split
IN         width             column dimension of block (as indicated below) 
OUT        left_obj          new object for left block
OUT        right_obj         new object for right block

If : 
width >= 0     width specifies   left_obj
width <  0     width specifies   right_obj



int PLA_Obj_view_shift   (PLA_Obj      obj,           int      length_top,
                          int          width_left,    int      width_right,
                          int          length_bottom)



Purpose : Shift the boundaries of the view of the linear algebra object

 
 
IN/OUT       obj           object to be grown [shifted]
IN           length_top    length to shift top boundary  
IN           width_left    width to shift left boundary  
IN           width_right   width to shift right boundary 
IN           length_bottom length to shift bottom boundary

Note : Positive is down/right negative is up/left (as if you were in quadrant IV
in the cartesian plane.



int PLA_Obj_split_size   (PLA_Obj      obj,      int      side,
                          int          *size,    int      *owner)



Purpose :
 
 
IN       obj       object to be split
IN       side      side of split
OUT      size      size to next template subblock split
OUT      owner     index of row or column of nodes that owns the split block


Purpose : Compute size of split to next block boundary. 



int PLA_Vector_create_conf_to   (PLA_Obj      obj,        PLA_Obj     *new_vector)



Purpose : Create vector conformal to given object. 
 
 
IN      obj          original object
OUT     new_vector   created object



int PLA_Mvector_create_conf_to   (PLA_Obj      obj,        int      global_width,
                                  PLA_Obj     *new_mvector)



Purpose : Create mvector conformal to given object. 
 
 
IN      obj                original object
IN      global_width       number of vectors in mvector
OUT     new_mvector        created object



int PLA_Pvector_create_conf_to   (PLA_Obj      obj,        int         project_onto,
                                  int          owner,      PLA_Obj     *new_pvector)



Purpose : Create projected vector conformal to given object. 
 
 
IN      obj                original object
IN      project_onto       mesh direction onto which to project
IN      owner              index of row or column of nodes which contains owning nodes
OUT     new_pvector        created object



int PLA_Pmvector_create_conf_to   (PLA_Obj      obj,        int         project_onto,
                                   int          owner,      int         num_vectors,
                                   PLA_Obj     *new_pmvector)



Purpose : Create projected mvector conformal to given object. 
 
 
IN      obj                original object
IN      project_onto       mesh direction onto which to project
IN      owner              index of row or column of nodes which contains owning nodes
IN      num_vectors        number of vectors in multivector
OUT     new_pmvector       created object



int PLA_Matrix_create_conf_to   (PLA_Obj      matrix,        PLA_Obj     *new_matrix)



Purpose : Create matrix conformal to given object (must be a matrix).

 
 
IN      matrix       original object
OUT     new_matrix   created object



int PLA_Mscalar_create_conf_to   (PLA_Obj      obj,        int         owner_row,
                                  int          owner_col,  PLA_Obj     *new_mscalar)



Purpose : Create multiscalar conformal to given object. 
 
 
IN      obj           original object
IN      owner_row     index of row of nodes that contains owning node(s)
IN      owner_col     index of column of nodes that contains owning node(s)
OUT     new_mscalar   created object (multiscalar)



int PLA_Obj_objtype_cast   (PLA_Obj      obj,         int      obj_type)



Purpose : Cast the linear algebra object to have given object type. 
 
 
IN/OUT        obj            original object
IN            objtype        new object type



int PLA_Obj_set_orientation   (PLA_Obj     obj,     int     project_onto)



Purpose : Set the orientation of a matrix panel. 
 
 
IN/OUT      obj              original object
IN          project_onto     annotation indicating orientation



int PLA_Obj_get_orientation   (PLA_Obj     obj,     int     *project_onto)


 
Purpose : Return the orientation of a matrix panel. 
 
 
IN/OUT      obj              original object
IN          project_onto     annotation indicating orientation



Chapter 4: Application Program Interface

Back to Index to Chapters -- Back to Chapter 3 -- Forward to Chapter 5

Section 4.2: API-Activation
PLA_API_begin
PLA_API_end
PLA_API_state

Section 4.3: Opening and Closing an Object
PLA_Obj_API_open
PLA_Obj_API_close
PLA_Obj_API_mode
Section 4.4: Accessing a Vector
PLA_API_axpy_vector_to_global
PLA_API_axpy_global_to_vector
PLA_API_multi_axpy_vector_to_global
PLA_API_multi_axpy_global_to_vector

Section 4.5: Accessing a Matrix
PLA_API_axpy_matrix_to_global
PLA_API_axpy_global_to_matrix
PLA_API_multi_axpy_matrix_to_global
PLA_API_multi_axpy_global_to_matrix

Section 4.6: Completion and Synchronization
PLA_API_sync


int PLA_API_begin()



Purpose : Activites the API active state.
 
 




int PLA_API_end()



Purpose : De-activates the API active state. 
 
 




int PLA_API_state(int    *state)



Purpose : Determines the state of a linear algebra object. 
 
 

OUT     state    State of linear algebra object



int PLA_Obj_API_open(PLA_Obj obj)



Purpose : Puts object into asynchronous mode(makes PLA_Obj_API_ operations
on the object allowable). 
 
 
IN/OUT     obj    Linear algebra object (to be) placed in asynchronous mode.



int PLA_Obj_API_close(PLA_Obj obj)



Purpose : Puts object into synchronous mode (disallows PLA_Obj_API_
operations on the object). 
 
 
IN/OUT     obj    Linear algebra object (to be) taken out of asynchronous mode.



int PLA_Obj_API_mode (PLA_Obj  obj,     int       *mode)



Purpose : Returns the mode of the linear algebra object (PLA_MODE_CLOSED
or PLA_MODE_OPEN). 
 
 
IN     obj       Linear algebra object
OUT    mode      Mode of linear algebra object





int PLA_API_axpy_vector_to_global(   int            size ,      
                                     void         * alpha ,     
                                     void         * local_obj , 
                                     int            local_inc , 
                                     PLA_Obj      laobj ,    
                                     int            disp );     



Purpose : Add local vector buffer data to global vector object. 
 
 
IN            size              Length of vector
IN          * alpha             Scalar in axpy operation
IN          * local_obj         Local vector values 
IN            local_inc         Local vector increment (stride)
IN/OUT        laobj             Global vector (target linear algebra object)
IN            disp              Global vector displacement




int PLA_API_axpy_global_to_vector(int           size ,
                                  void        * alpha ,
                                  PLA_Obj     laobj ,
                                  int           displ ,
                                  void        * local_obj ,
                                  int           local_inc );



Purpose : Add piece of global vector object to local linear algebra
object. 
 
 
IN            size              Length of vector
IN          * alpha             Scalar in axpy operation
IN            laobj             Global vector object
IN            displ             Displacement  (in global object)
IN/OUT      * local_obj         Local linear algebra object (target) buffer
IN            local_inc         Local vector increment (stride)



int PLA_API_multi_axpy_vector_to_global(int            nsub,
                                           int          * sizes ,      
                                           void         * alpha ,     
                                           void         * local_vector , 
                                           int            local_stride , 
                                           PLA_Obj      laobj ,    
                                           int          * displs );     



Purpose : Add local sub-vector buffer data chunks to global vector
object. 
 
 
IN            nsub              Number of subvectors
IN          * size              Length of subvectors
IN          * alpha             Scalar in axpy operation
IN          * local_vector      Local vector values 
IN            local_stride      Local vector increment (stride)
IN/OUT        laobj             Global vector (target linear algebra object)
IN          * displs            Global vector displacements



int PLA_API_multi_axpy_global_to_vector(int           nsub ,
                                           int         * sizes ,
                                           void        * alpha ,
                                           PLA_Obj     laobj ,
                                           int         * displs ,
                                           void        * local_vector ,
                                           int           local_stride );



Purpose : Add pieces of global vector object to local vector.
 
 IN            nsub              Number of subvectors
IN          * size              Length of subvectors
IN          * alpha             Scalar in axpy operation
IN            laobj             Global vector object
IN          * displs            Displacements  (in global object)
IN/OUT      * local_vector      Local linear algebra object (target) buffer
IN            local_stride      Local vector increment (stride)



int PLA_API_axpy_matrix_to_global(   int            size_row ,
                                     int            size_col ,
                                     void         * alpha ,     
                                     void         * local_matrix , 
                                     int            local_ldim , 
                                     PLA_Obj      obj ,    
                                     int            disp_row,
                                     int            disp_col );     



Purpose : Add local matrix buffer data to global matrix object. 
 
 
IN            size_row          Length of matrix
IN            size_col          Width of matrix
IN          * alpha             Scalar in axpy operation
IN          * local_obj         Local matrix values (buffer)
IN            local_ldim        Local matrix leading dimension
IN/OUT        obj               Global matrix (target linear algebra object)
IN            disp_row          Global matrix row displacement
IN            disp_col          Global matrix column displacement




int PLA_API_axpy_global_to_matrix(int           size_row ,
                                  int           size_col ,
                                  void        * alpha ,
                                  PLA_Obj     obj ,
                                  int           displ_row ,
                                  int           displ_col,
                                  void        * local_matrix ,
                                  int           local_ldim );



Purpose : Add piece of global matrix object to local linear algebra
object (matrix). 
 
 
IN            size_row          Length of matrix
IN            size_col          Width of matrix
IN          * alpha             Scalar in axpy operation
IN            obj               Global vector object
IN            displ_row         Row displacement  (in global object)
IN            displ_col         Column displacement  (in global object)
IN/OUT      * local_matrix      Local linear algebra object (target) buffer
IN            local_ldim         Local matrix leading dimension



int PLA_API_multi_axpy_matrix_to_global(   int            nsub_row,
                                           int            nsub_col,
                                           int          * size_row ,      
                                           int          * size_col ,
                                           void         * alpha ,     
                                           void         * local_matrix , 
                                           int            local_ldim , 
                                           PLA_Obj      obj ,    
                                           int          * disp_row,
                                           int          * disp_col );     



Purpose : Add local sub-matrix buffer data chunks to global matrix
object. 
 
 
IN            nsub_row          Number of row subblocks to map
IN            nsub_row          Number of column subblocks to map
IN          * size_row          Row block lengths
IN          * size_col          Column block widths
IN          * alpha             Scalar in axpy operation
IN          * local_matrix      Local matrix values 
IN            local_ldim        Local matrix leading dimension
IN/OUT        obj               Global matrix (target linear algebra object)
IN          * disp_row          Global matrix row displacements
IN          * disp_col          Global matrix column displacements




int PLA_API_multi_axpy_global_to_matrix(   int           nsub_row ,
                                           int           nsub_col
                                           int         * size_row ,
                                           int         * size_col ,
                                           void        * alpha ,
                                           PLA_Obj       obj ,
                                           int         * disp_row ,
                                           int         * disp_col ,
                                           void        * local_matrix ,
                                           int           local_ldim );



Purpose : Add pieces of global matrix object to local matrix. 
 
 



IN            nsub_row          Number of row subblocks to map
IN            nsub_row          Number of column subblocks to map
IN          * size_row          Row block lengths
IN          * size_col          Column block widths
IN          * alpha             Scalar in axpy operation
IN            obj               Global matrix
IN          * disp_row          Global matrix row displacements
IN          * disp_col          Global matrix column displacements
IN/OUT      * local_matrix      Local matrix values 
IN            local_ldim        Local matrix leading dimension




int PLA_API_sync(PLA_Obj   laboj)



Purpose : Synchronizes all nodes w.r.t. the given object and completes
all pending "API_axpy" operations on the object. 
 
 
IN/OUT    laobj      Linear algebra object




Chapter 5: Data Duplication and Consolidation

Back to Index to Chapters -- Back to Chapter 4 -- Forward to Chapter 6

Section 5.1: Copy
PLA_Copy
PLA_Copy_x

Section 5.2: Reduce
PLA_Reduce
PLA_Reduce_x
Section 5.3: Pipelining Computation and Communication
PLA_Temp_set_comm_dir
PLA_Temp_get_comm_dir


int PLA_Copy(PLA_Obj    obj_from,   PLA_Obj   obj_to)



Purpose : Copies the contents (not description) between linear algebra objects.

 
 
IN      obj_from     object to be copied
IN/OUT  obj_to       object into which to copy




int PLA_Copy_x(int   shape,   PLA_Obj    obj_from,   PLA_Obj   obj_to)



Purpose : Copy contents between linear algebra objects.  This version
allows a shape to be given for the input object, copying only part of the 
contents. 
 
 
IN      shape        shape of object
IN      obj_from     object to be copied
IN/OUT  obj_to       object into which to copy


Note that the shape parameter PLA_Shape_GENERAL makes this function equivalent to PLA_Copy.



int PLA_Reduce(PLA_Obj   obj_from,    MPI_Op    op,      PLA_Obj   obj_to)



Purpose : Reduce, using operator given by op, the contents in the duplicated
object given by obj_from and overwrite obj_to with the result. 
 
 
IN      obj_from     object to be reduced
IN      op           reduce operator to be used
IN/OUT  obj_to       object into which to reduce



int PLA_Reduce_x(int       shape,       PLA_Obj   obj_from,    
                 PLA_Obj   alpha,       PLA_Obj   obj_to)



Purpose : Reduce, using summation, the contents in the duplicated object
given by obj_from and overwrite obj_to with the result.  This verson reduces
part of the contents, as indicated by shape, and also scales the target 
object by alpha before the reduce.
 
 
IN      shape        shape of object
IN      obj_from     object to be reduced
IN      alpha        scaling factor for target object
IN/OUT  obj_to       object into which to reduce



int PLA_Temp_set_comm_dir(PLA_Template     template,     int      mesh_dimension,
                          int              direction )



Purpose : Passes "hints" the the PLA_Copy* and PLA_Reduce*
operations to indicate the direction that data should flow along the processor
mesh. Note that there is no guarantee that the library will obey these
directives. The directions may be up/down/right/left. 
 
 
IN/OUT      template             template for computation
IN          mesh_dimension       dimension of node mesh (row or column)
IN          direction            direction of flow of computation




int PLA_Temp_get_comm_dir(PLA_Template     template,     int      mesh_dimension,
                          int             *direction )



Purpose : Determines the current status of the "hints" passed
to the PLA_Copy* and PLA_Reduce* operations through PLA_Temp_set_comm_dir().

 
 
IN/OUT      template             template for computation
IN          mesh_dimension       dimension of node mesh (row or column)
IN          direction            direction of flow of computation



Chapter 6: Vector-Vector Operations

Back to Index to Chapters -- Back to Chapter 5 -- Forward to Chapter 7

Local level-1 BLAS:
PLA_Local_copy
PLA_Local_swap
PLA_Local_scal
PLA_Local_inv_scal
PLA_Local_axpy
PLA_Local_dot
PLA_Local_nrm2
PLA_Local_asum
PLA_Local_iamax
Global level-1 BLAS:

PLA_Swap
PLA_Scal
PLA_Inv_scal
PLA_Axpy
PLA_Dot
PLA_Nrm2
PLA_Asum
PLA_Iamax


int PLA_Local_copy(PLA_Obj    obj_from,   PLA_Obj   obj_to)



Purpose : Copies the local contents of one linear algebra object into
another (i.e. copies the local buffer of one object into the local buffer
of another).
 
 
IN      obj_from     object to be copied
IN/OUT  obj_to       object into which to copy


Note : The Global copy, PLA_Copy() is covered in Chapter5 and is not repeated on this web page.



int PLA_Local_swap(PLA_Obj    obj_x,   PLA_Obj   obj_y)



Purpose : Swaps the local contents of two linear algebra objects (i.e.
copies the local buffer of one object into the local buffer of the other
and vice versa). 
 
 
IN/OUT  obj_x        linear algebra object 1
IN/OUT  obj_y        linear algebra object 2




int PLA_Local_scal(PLA_Obj    alpha,   PLA_Obj   x)



Purpose : Scales the local contents of a linear algebra object (i.e.
scales its buffer contents through multiplication by alpha). 
 
 
IN      alpha        scaling factor (multiscalar)
IN/OUT  x            linear algebra object to scale




int PLA_Local_inv_scal(PLA_Obj    alpha,   PLA_Obj   x)



Purpose : Scales the local contents of a linear algebra object (i.e.
scales its buffer contents through multiplication by 1/alpha). 
 
 
IN      alpha        (inverse of) scaling factor (multiscalar)
IN/OUT  x            linear algebra object to scale




int PLA_Local_axpy(PLA_Obj    alpha,   PLA_Obj   x,
                   PLA_Obj    y)



Purpose : local(y) = alpha * local(x) + local(y) 
 
 
IN      alpha        scaling factor (multiscalar)
IN      x            linear algebra object to scale
IN/OUT  y            target 




int PLA_Local_dot(PLA_Obj    x,       PLA_Obj   y,
                  PLA_Obj    alpha)



Purpose : local(alpha) = local(x)T * local(y) 
 
 
IN      x            vector x (linear algebra object)
IN      y            vector y (linear algebra object)
IN/OUT  alpha        local contribution to result of xT * y




int PLA_Local_nrm2(PLA_Obj    x,       PLA_Obj    alpha)



Purpose : local(alpha) = ||local(x)|| 2 
 
 
IN      x            vector x (linear algebra object)
IN/OUT  alpha        local contribution to ||x||2




int PLA_Local_asum(PLA_Obj    x,       PLA_Obj    alpha)



Purpose : local(alpha) = ||local(Re(x))||1 + ||local(Im(x))||1

 
 
IN      x            vector x (linear algebra object)
IN/OUT  alpha        local contribution to ||x||1




int PLA_Local_iamax(PLA_Obj    x,       PLA_Obj    xmax,
                    PLA_Obj    k)



Purpose : local(xmax) = x(k) where |x(k)| = max(|x(j)|) for j ranging
from 1-size of local(x). 
 
 
IN          x        vector x (linear algebra object)
IN/OUT      xmax     local maximum 
IN/OUT      k        global index of local maximum




int PLA_Swap(PLA_Obj    x,   PLA_Obj   y)



Purpose : Swaps the contents (globally) of two linear algebra objects.
NOTE : Does not change any part of either object except the buffer (i.e.
global_length before = global length after etc.). 
 
 
IN/OUT  x       linear algebra object ("vector" x)
IN/OUT  y       linear algebra object ("vector" y)




int PLA_Scal(PLA_Obj    alpha,   PLA_Obj   x)



Purpose : Scales the local contents of a linear algebra object : x
<- alpha * x 
 
 
IN      alpha        scaling factor (multiscalar)
IN/OUT  x            linear algebra object to scale




int PLA_Inv_scal(PLA_Obj    alpha,   PLA_Obj   x)



Purpose : Scales the local contents of a linear algebra object x <-
1/alpha * x (i.e. scales its buffer contents through multiplication by
1/alpha). 
 
 
IN      alpha        (inverse of) scaling factor (multiscalar)
IN/OUT  x            linear algebra object to scale




int PLA_Axpy(PLA_Obj    alpha,   PLA_Obj   x,
             PLA_Obj    y)



Purpose : y = alpha * x + y 
 
 
IN      alpha        scaling factor (multiscalar)
IN      x            linear algebra object to scale
IN/OUT  y            target 




int PLA_Dot(PLA_Obj    x,       PLA_Obj   y,
            PLA_Obj    alpha)



Purpose : alpha = xT * y 
 
 
IN      x            vector x (linear algebra object)
IN      y            vector y (linear algebra object)
IN/OUT  alpha        result of xT * y




int PLA_Nrm2(PLA_Obj    x,       PLA_Obj    alpha)



Purpose : alpha = ||x|| 2 
 
 
IN      x            vector x (linear algebra object)
IN/OUT  alpha        result : ||x||2




int PLA_Asum(PLA_Obj    x,       PLA_Obj    alpha)



Purpose : alpha = ||Re(x)||1 + ||Im(x)||1 
 
 
IN      x            vector x (linear algebra object)
IN/OUT  alpha        result : ||x||1




int PLA_Iamax(PLA_Obj    x,       PLA_Obj    xmax,
              PLA_Obj    k)



Purpose : xmax = x(k) where |x(k)| = max(|x(j)|) for j ranging from
1-size of x. 
 
 
IN          x        vector x (linear algebra object)
IN/OUT      xmax     global maximum 
IN/OUT      k        global index of global maximum



Chapter 7: Matrix-Vector Operations

Back to Index to Chapters -- Back to Chapter 6 -- Forward to Chapter 8

Local level-2 BLAS:
PLA_Local_gemv
PLA_Local_symv
PLA_Local_trmv
PLA_Local_trsv
PLA_Local_ger
PLA_Local_syr
PLA_Local_syr2
Global level-2 BLAS:
PLA_Gemv
PLA_Symv
PLA_Trmv
PLA_Trsv
PLA_Ger
PLA_Syr
PLA_Syr2


int PLA_Local_gemv(int      trans, PLA_Obj   alpha,  PLA_Obj    a,
                   PLA_Obj  x,     PLA_Obj   beta,   PLA_Obj    y)



Purpose : local(y) <- a* local(A)*local(x)
+ b*local(y) OR local(y) <- a*
local(A)T*local(x) + b*local(y).

 
 
IN      trans         transpose (or no transpose) A (a)
IN      alpha         scaling factor for A*x
IN      a             matrix A
IN      x             "vector" x
IN      beta          scaling factor for y
IN/OUT  y             "vector" y




int PLA_Local_symv(int      uplo,  PLA_Obj   alpha,  PLA_Obj    a,
                   PLA_Obj  x,     PLA_Obj   beta,   PLA_Obj    y)



Purpose : local(y) <- a* local(A)*local(x)
+ b*local(y) with only the upper or lower portion
of (local) A stored in object a. 
 
 
IN      uplo          use only upper or lower triangular portion of A
IN      alpha         scaling factor for A*x
IN      a             matrix A
IN      x             "vector" x
IN      beta          scaling factor for y
IN/OUT  y             "vector" y




int PLA_Local_trmv(int      uplo,  int      trans,   int        diag,
                   PLA_Obj    a,   PLA_Obj    x)  



Purpose : local(x) <- local(A)*local(x) OR local(x) <- local(A)T
where local A is upper or lower triangular and may have a unit diagonal.

 
 
IN      uplo          (local) A is upper or lower triangular
IN      trans         transpose (or no transpose) A (a)
IN      diag          local A has unit or non-unit diagonal
IN      a             matrix A
IN      x             "vector" x





int PLA_Local_trsv(int      uplo,   int        trans,   int        diag,
                   PLA_Obj     a,   PLA_Obj    x)  



Purpose : local(x) <- local(A)-1*local(x) OR local(x)
<- local(A)-T*local(x) OR local(x) <- local(A)-H*local(x)
where local A is upper or lower triangular and may have a unit diagonal.

 
 
IN      uplo          (local) A is upper or lower triangular
IN      trans         transpose (or no transpose) A (a)
IN      diag          local A has unit or non-unit diagonal
IN      a             matrix A
IN      x             "vector" x





int PLA_Local_ger (PLA_Obj   alpha,  PLA_Obj    x,
                   PLA_Obj   y,      PLA_Obj    a)



Purpose : local(A) <- a*local(x)*local(y)T
+ local(A). 
 
 
IN       alpha         scaling factor
IN       x             "vector" x
IN       y             "vector" y
IN/OUT   a             matrix A




int PLA_Local_syr (int       uplo,   PLA_Obj   alpha,  
                   PLA_Obj    x,     PLA_Obj    a)



Purpose : local(A) <- a*local(x)*local(x)T
+ local(A) with only the upper or lower portion of (local) A stored in
object a. 
 
 
IN       uplo          use only the upper or lower portion of local A
IN       alpha         scaling factor for A*x
IN       x             "vector" x
IN/OUT   a             matrix A



int PLA_Local_syr2 (int       uplo,   PLA_Obj   alpha,  PLA_Obj    x,
                    PLA_Obj   y,      PLA_Obj    a)



Purpose : local(A) <- a*local(x)*local(y)T
+ local(A) with only the upper or lower portion of (local) A stored in
object a. 
 
 
IN       uplo          use only the upper or lower portion of local A
IN       alpha         scaling factor for A*x
IN       x             "vector" x
IN       y             "vector" y
IN/OUT   a             matrix A



int PLA_Gemv(int      trans, PLA_Obj   alpha,  PLA_Obj    a,
             PLA_Obj  x,     PLA_Obj   beta,   PLA_Obj    y)



Purpose : y <- a* A*x + b*y
OR y <- a* AT*x + b*y.

 
 
IN      trans         transpose (or no transpose) A (a)
IN      alpha         scaling factor for A*x
IN      a             matrix A
IN      x             "vector" x
IN      beta          scaling factor for y
IN/OUT  y             "vector" y




int PLA_Symv(int      uplo,  PLA_Obj   alpha,  PLA_Obj    a,
             PLA_Obj  x,     PLA_Obj   beta,   PLA_Obj    y)



Purpose : y <- a* A*x + b*y
with only the upper or lower portion of A stored in object a. 
 
 
IN      uplo          use only upper or lower triangular portion of A
IN      alpha         scaling factor for A*x
IN      a             matrix A
IN      x             "vector" x
IN      beta          scaling factor for y
IN/OUT  y             "vector" y




int PLA_Trmv(int      uplo,  int      trans,   int        diag,
             PLA_Obj    a,   PLA_Obj    x)  



Purpose : x <- A*x OR x <- AT where A is upper or
lower triangular and may have a unit diagonal. 
 
 
IN      uplo          A is upper or lower triangular
IN      trans         transpose (or no transpose) A (a)
IN      diag          A has unit or non-unit diagonal
IN      a             matrix A
IN      x             "vector" x





int PLA_Trsv(int      uplo,   int        trans,   int        diag,
             PLA_Obj     a,   PLA_Obj    x)  



Purpose : x <- A-1*x OR x <- A-T*x OR x
<- A-H*x where A is upper or lower triangular and may have
a unit diagonal. 
 
 
IN      uplo          A is upper or lower triangular
IN      trans         transpose (or no transpose) A (a)
IN      diag          A has unit or non-unit diagonal
IN      a             matrix A
IN      x             "vector" x





int PLA_Ger (PLA_Obj   alpha,  PLA_Obj    x,
             PLA_Obj   y,      PLA_Obj    a)



Purpose : A <- a*x*yT + A.

 
 
IN       alpha         scaling factor 
IN       x             "vector" x
IN       y             "vector" y
IN/OUT   a             matrix A



int PLA_Syr (int       uplo,   PLA_Obj   alpha,  
             PLA_Obj   x,      PLA_Obj    a)



Purpose : A <- a*x*xT + A
with only the upper or lower portion of A stored in object a. 
 
 
IN       uplo          use only the upper or lower portion of A
IN       alpha         scaling factor for A*x
IN       x             "vector" x
IN/OUT   a             matrix A



int PLA_Syr2 (int       uplo,   PLA_Obj   alpha,  PLA_Obj    x,
              PLA_Obj   y,      PLA_Obj    a)



Purpose : A <- a*x*yT + A
with only the upper or lower portion of A stored in object a. 
 
 
IN       uplo          use only the upper or lower portion of A
IN       alpha         scaling factor for A*x
IN       x             "vector" x
IN       y             "vector" y
IN/OUT   a             matrix A

Chapter 8: Matrix-Matrix Operations

Back to Index to Chapters -- Back to Chapter 7 -- Forward to Miscelaneous

Local level-3 BLAS:
PLA_Local_gemm
PLA_Local_symm
PLA_Local_syrk
PLA_Local_syr2k
PLA_Local_trmm
PLA_Local_trsm
Global level-3 BLAS:
PLA_Gemm
PLA_Symm
PLA_Syrk
PLA_Syr2k
PLA_Trmm
PLA_Trsm


int PLA_Local_gemm ( int transa,
	             int transb,
		     PLA_Obj alpha,
		     PLA_Obj A,
		     PLA_Obj B,
		     PLA_Obj beta,
		     PLA_Obj C)
	                                                                   

Purpose : Local matrix multiplication

IN     transa	   integer, PLA_TRANSPOSE or PLA_NO_TRANSPOSE
IN     transb	   integer, PLA_TRANSPOSE or PLA_NO_TRANSPOSE
IN     alpha	   multiscalar, scale factor for A and B
IN     A	   any object type, factor in product
IN     B	   any object type, factor in product
IN     beta	   multiscalar, scale factor for C
IN/OUT C	   any object type, overwritten with alpha*opA(A)*opB(B)+beta*C





int PLA_Gemm ( int transa,
               int transb,
	       PLA_Obj alpha,
	       PLA_Obj A,
	       PLA_Obj B,
	       PLA_Obj beta,
	       PLA_Obj C)
	                                                                   

Purpose : Parallel matrix multiplication

IN     transa	   integer, PLA_TRANSPOSE or PLA_NO_TRANSPOSE
IN     transb	   integer, PLA_TRANSPOSE or PLA_NO_TRANSPOSE
IN     alpha	   multiscalar, scale factor for A and B
IN     A	   matrix, factor in product
IN     B	   matrix, factor in product
IN     beta	   multiscalar, scale factor for C
IN/OUT C	   matrix, overwritten with alpha*opA(A)*opB(B)+beta*C





int PLA_Local_symm ( int side,
	             int uplo,
		     PLA_Obj alpha,
		     PLA_Obj A,
		     PLA_Obj B,
		     PLA_Obj beta,
		     PLA_Obj C)
	                                                                   

Purpose : Local symmetric matrix multiplication

IN     side	   integer, PLA_SIDE_LEFT or PLA_SIDE_RIGHT
IN     uplo	   integer, PLA_UPPER_TRIANGULAR or PLA_LOWER_TRIANGULAR
IN     alpha	   multiscalar, scale factor for A and B
IN     A	   any object type, factor in product
IN     B	   any object type, factor in product
IN     beta	   multiscalar, scale factor for C
IN/OUT C	   any object type, overwritten with alpha*opA(A)*opB(B)+beta*C





int PLA_Symm ( int side,
               int uplo,
	       PLA_Obj alpha,
	       PLA_Obj A,
	       PLA_Obj B,
	       PLA_Obj beta,
	       PLA_Obj C)
	                                                                   

Purpose : Parallel symmetric matrix multiplication

IN     side	   integer, PLA_SIDE_LEFT or PLA_SIDE_RIGHT
IN     uplo	   integer, PLA_UPPER_TRIANGULAR or PLA_LOWER_TRIANGULAR
IN     alpha	   multiscalar, scale factor for A and B
IN     A	   matrix, factor in product
IN     B	   matrix, factor in product
IN     beta	   multiscalar, scale factor for C
IN/OUT C	   matrix, overwritten with alpha*opA(A)*opB(B)+beta*C





int PLA_Local_syrk ( int uplo,
	             int trans,
		     PLA_Obj alpha,
		     PLA_Obj A,
		     PLA_Obj beta,
		     PLA_Obj C)
	                                                                   

Purpose : Local symmetric rank-k update

IN     uplo	   integer, PLA_UPPER_TRIANGULAR or PLA_LOWER_TRIANGULAR
IN     trans	   integer, PLA_TRANSPOSE or PLA_No_TRANPOSE
IN     alpha	   multiscalar, scale factor for A 
IN     A	   any object type, factor in product
IN     beta	   multiscalar, scale factor for C
IN/OUT C	   any object type, overwritten with alpha A*A^T + beta C





int PLA_Syrk ( int uplo,
               int trans,
	       PLA_Obj alpha,
	       PLA_Obj A,
	       PLA_Obj beta,
	       PLA_Obj C)
	                                                                   

Purpose : Parallel symmetric rank-k update

IN     uplo	   integer, PLA_UPPER_TRIANGULAR or PLA_LOWER_TRIANGULAR
IN     trans	   integer, PLA_TRANSPOSE or PLA_No_TRANPOSE
IN     alpha	   multiscalar, scale factor for A 
IN     A	   matrix, factor in product
IN     beta	   multiscalar, scale factor for C
IN/OUT C	   symmetric matrix, overwritten with alpha A*A^T + beta C






int PLA_Local_syr2k ( int uplo,
	             int trans,
		     PLA_Obj alpha,
		     PLA_Obj A,
		     PLA_Obj B,
		     PLA_Obj beta,
		     PLA_Obj C)
	                                                                   

Purpose : Local symmetric double rank-k update

IN     uplo	   integer, PLA_UPPER_TRIANGULAR or PLA_LOWER_TRIANGULAR
IN     trans	   integer, PLA_TRANSPOSE or PLA_No_TRANPOSE
IN     alpha	   multiscalar, scale factor for A and B
IN     A	   any object type, factor in product
IN     B	   any object type, factor in product
IN     beta	   multiscalar, scale factor for C
IN/OUT C	   any object type, overwritten with
                   alpha*(A*B^T + B*A^T)+beta*C





int PLA_Syr2k ( int uplo,
               int trans,
	       PLA_Obj alpha,
	       PLA_Obj A,
	       PLA_Obj B,
	       PLA_Obj beta,
	       PLA_Obj C)
	                                                                   

Purpose : Parallel symmetric double rank-k update

IN     uplo	   integer, PLA_UPPER_TRIANGULAR or PLA_LOWER_TRIANGULAR
IN     trans	   integer, PLA_TRANSPOSE or PLA_No_TRANPOSE
IN     alpha	   multiscalar, scale factor for A and B
IN     A	   matrix, factor in product
IN     B	   matrix, factor in product
IN     beta	   multiscalar, scale factor for C
IN/OUT C	   symmetric matrix, overwritten with 
                   alpha*(A*B^T + B*A^T)+beta*C





int PLA_Local_trmm ( int side, 
                     int uplo,
	             int trans,
	             int diag,
		     PLA_Obj alpha,
		     PLA_Obj A,
		     PLA_Obj B)

	                                                                   

Purpose : Local triangular matrix multiply

IN     side	   integer, PLA_SIDE_LEFT or PLA_SIDE_RIGHT
IN     uplo	   integer, PLA_UPPER_TRIANGULAR or PLA_LOWER_TRIANGULAR
IN     trans	   integer, PLA_TRANSPOSE or PLA_No_TRANPOSE
IN     diag	   integer, PLA_UNIT_DIAG or PLA_NONUNIT_DIAG
IN     alpha	   multiscalar, scale factor 
IN     A	   any object type, factor in product
IN/OUT B	   any object type, factor in product





int PLA_Trmm ( int side, 
               int uplo,
	       int trans,
	       int diag,
	       PLA_Obj alpha,
	       PLA_Obj A,
	       PLA_Obj B)


	                                                                   

Purpose : Parallel triangular matrix multiplication

IN     side	   integer, PLA_SIDE_LEFT or PLA_SIDE_RIGHT
IN     uplo	   integer, PLA_UPPER_TRIANGULAR or PLA_LOWER_TRIANGULAR
IN     trans	   integer, PLA_TRANSPOSE or PLA_No_TRANPOSE
IN     diag	   integer, PLA_UNIT_DIAG or PLA_NONUNIT_DIAG
IN     alpha	   multiscalar, scale factor 
IN     A	   matrix, factor in product
IN/OUT B	   matrix, factor in product





int PLA_Local_trsm ( int side, 
                     int uplo,
	             int trans,
	             int diag,
		     PLA_Obj alpha,
		     PLA_Obj A,
		     PLA_Obj B)

	                                                                   

Purpose : Local triangular solve with multiple right hand sides

IN     side	   integer, PLA_SIDE_LEFT or PLA_SIDE_RIGHT
IN     uplo	   integer, PLA_UPPER_TRIANGULAR or PLA_LOWER_TRIANGULAR
IN     trans	   integer, PLA_TRANSPOSE or PLA_No_TRANPOSE
IN     diag	   integer, PLA_UNIT_DIAG or PLA_NONUNIT_DIAG
IN     alpha	   multiscalar, scale factor
IN     A	   any object type, triangular matrix
IN/OUT B	   any object type, right hand sides





int PLA_Trsm ( int side,
               int uplo,
	       int trans,
	       int diag,
	       PLA_Obj alpha,
	       PLA_Obj A,
	       PLA_Obj B)




Purpose : Parallel triangular solve with multiple right hand sides

IN     side	   integer, PLA_SIDE_LEFT or PLA_SIDE_RIGHT
IN     uplo	   integer, PLA_UPPER_TRIANGULAR or PLA_LOWER_TRIANGULAR
IN     trans	   integer, PLA_TRANSPOSE or PLA_No_TRANPOSE
IN     diag	   integer, PLA_UNIT_DIAG or PLA_NONUNIT_DIAG
IN     alpha	   multiscalar, scale factor
IN     A	   matrix, triangular matrix
IN/OUT B	   matrix, right hand sides (overwritten with solution)




Miscelaneous Routiens

Back to Index to Chapters -- Back to Chapter 8 -- Forward to Solvers

PLA_Create_constants_conf_to
PLA_Obj_set_to_identity
PLA_Local_equal_zero
PLA_Local_sign
PLA_Local_invert_sign



int PLA_Create_constants_conf_to   (PLA_Obj      obj,        PLA_Obj *minus_one,
                                    PLA_Obj     *zero,       PLA_Obj      *one)



Purpose : Create multiscalars of the same datatype as the given object. 
 
 
IN      obj           original object
OUT     minus_one     mscalar containing -1
OUT     zero          mscalar containing 0
OUT     one           mscalar containing 1

Note : Any pointer coming in to this routine as NULL is untouched, so to only get the constant "one", call PLA_Create_constants_conf_to( A, NULL, &one, NULL)



int PLA_Obj_set_to_identity   (PLA_Obj      obj)



Purpose : Set object to identity matrix.
 
 
IN/OUT          obj          linear algebra object



int PLA_Local_equal_zero(PLA_Obj    x)



Purpose : Return TRUE (=1) or FALSE (=0) depending on
whether the local (scalar) object equals zero.
 
 
IN      x            scalar for which to determine if zero
RETURN value:        TRUE iff x == 0  



int PLA_Local_sign(PLA_Obj    x,       PLA_Obj    sign_x )



Purpose : local( sign_x ) = sign( local(x) 
 
 
IN      x            scalar for which to determine sign
IN/OUT  sign_x       scalar = sign of x ( = x / | x | so complex is 
                     covered )



int PLA_Local_invert_sign( PLA_Obj    x )



Purpose : local( x ) = - local(x) 
 
 
IN/OUT  x            object for which sign(s) of element(s) are
                     to be inverted.


Solvers

Back to Index to Chapters -- Back to Miscelaneous -- Back to Index to Chapters --

General Solve:
Symmetric Positive Definite Solve:
Linear Least Squares Solve:

General solve A X = B



int PLA_General_solve(PLA_Obj    A, PLA_Obj   ipiv,    PLA_Obj B )


Purpose : Solve linear system of equations  A X = B, overwriting B
with X, using LU factorization with partial pivoting.  B may have 
more than one column.

IN/OUT A            Matrix A.  Overwritten with LU factorization.
                    (PLA_MATRIX of size nxn)
IN/OUT ipiv         Object in which to store pivots encountered 
                    during LU factorization.
                    (PLA_MSCALAR of size 1xn, duplicated on all nodes)
IN/OUT B            (Multiple)right-hand-side(s).  Overwritten with
                    solution(s)
                    (PLA_MVECTOR or PLA_MATRIX with n rows)




Symmetric positive definite solve A X = B

PLA_Pos_def_solve
PLA_Chol


int PLA_Pos_def_solve(int uplo, PLA_Obj A, PLA_Obj B )


Purpose : Solve linear system of equations  A X = B, overwriting B
with X, using Cholesky factorization.  Matrix A must be symmetric 
positive definite.  B may have more than one column.

IN     uplo         If PLA_LOWER_TRIANGULAR or PLA_UPPER_TRIANGULAR, 
                    A is stored in lower or upper triangular part of 
                    object A, respectively. 
IN/OUT A            Matrix A.  Overwritten with Cholesky factorization.
                    (PLA_MATRIX of size nxn)
IN/OUT B            (Multiple)right-hand-side(s).  Overwritten with
                    solution(s)
                    (PLA_MVECTOR or PLA_MATRIX with n rows)





int PLA_Chol( int uplo, PLA_Obj A )


Purpose : Compute Cholesky factorization A -> L L^T of positive
symmetric matrix A.  Currently, only uplo = PLA_LOWER_TRIANGULAR
is supported, which means that the symmetric matrix is stored
in the the lower triangle of A and it is this part of A that
is overwritten with factor L.

IN     uplo         If PLA_LOWER_TRIANGULAR or PLA_UPPER_TRIANGULAR, 
                    A is stored in lower or upper triangular part of 
                    object A, respectively. 
IN/OUT A            Matrix A.  Overwritten with Cholesky factorization.
                    (PLA_MATRIX of size nxn)




Linear least square solve

PLA_Least_sqr_solve
PLA_QR
PLA_Compute_House_v
PLA_Compute_W_Y
PLA_Apply_W_Y
PLA_Form_Q
PLA_Q_solve


int PLA_Least_sqr_solve(PLA_Obj A, PLA_Obj s, PLA_Obj Q, PLA_Obj B )


Purpose : Solve linear least squares problem min || A X - B ||_2
using QR factorization.  B may have more than one column.

IN/OUT A            Matrix A.  Overwritten with R and the Householder
                    vectors.
                    (PLA_MATRIX of size mxn)
IN/OUT s            Object for storing the scaling factors for
                    the Householder transforms.
                    (PLA_Mvector of size nx1)
IN/OUT Q            Object for storing Q.  If it equals PLA_DUMMY,
                    Q is not computed.
                    (PLA_MATRIX of size mxm)
IN/OUT B            (Multiple)right-hand-side(s).  Overwritten with
                    solution(s)
                    (PLA_MVECTOR or PLA_MATRIX with m rows)




int PLA_QR(PLA_Obj A, PLA_Obj s )


Purpose : Factor A -> Q R, overwriting the uppertriangular part of
A with R and leaving the Householder vectors stored below the 
diagonal and in s.

IN/OUT A            Matrix A.  Overwritten with R and the Householder
                    vectors.
                    (PLA_MATRIX of size mxn)
IN/OUT s            Object for storing the scaling factors for
                    the Householder transforms.
                    (PLA_Mvector of size nx1)




int PLA_Compute_House_v(PLA_Obj x, PLA_Obj beta )


Purpose :   Compute vector u so that
      ( I - beta u u^T ) x = +- || x ||_2 e_1
u is normalized to have unit first element and beta = 2 / || u ||_2^2.

IN/OUT x            Vector x.  Overwritten with first entry +-|| x ||_2 
                    and the rest of the entries of u.
                    (PLA_MVECTOR of width 1)
IN/OUT beta         Object for storing the scaling factor beta.
                    (1x1 PLA_MSCALAR duplicated to all nodes)




int PLA_Compute_W_Y(PLA_Obj Amv, PLA_Obj s, PLA_Obj Wmv, PLA_Obj Ymv )


Purpose :   Compute WY transform from Householder vectors stored
           below diagonal of Amv and s.


IN     Amv          Panel of matrix which stores the current Householder
                    vectors from which to compute WY transform.
                    (mxn PLA_MVECTOR)
IN     s            Scaling factors for Householder transforms.
                    (nx1 PLA_MSCALAR duplicated to all nodes)
IN/OUT Wmv, Ymv     Matrices in which to compute W and Y.
                    (mxn PLA_MVECTOR)




int PLA_Apply_W_Y(int side, int trans,
                  PLA_Obj Wmv, PLA_Obj, Ymv, PLA_Obj A )


Purpose :  Compute one of the following:
   OPERATION             SIDE               TRANS
   ----------------------------------------------
   A <-- (1 + W Y') A    PLA_SIDE_LEFT      PLA_NO_TRANS
   A <-- A (1 + W Y')    PLA_SIDE_RIGHT     PLA_NO_TRANS
   A <-- (1 + Y W') A    PLA_SIDE_LEFT      PLA_TRANS
   A <-- A (1 + Y W')    PLA_SIDE_RIGHT     PLA_TRANS
  

IN     side         Side from which to apply WY transform.
                    (int)
IN     trans        Indicates whether to transpose WY transform.
                    (int)
IN     Wmv, Ymv     Matrices W and Y.
                    (mxn PLA_MVECTOR)
IN/OUT A            Matrix to be updated.
                    (PLA_MATRIX)




int PLA_Form_Q(int trans, PLA_Obj A, PLA_Obj s, PLA_Obj Q )


Purpose :  Compute Q = H_1 * H_2 * ... * H_n-1 where H_i is
the ith Householder transform stored in the ith column of A and 
ith entry in s.  If trans = PLA_NO_TRANS, Q is computed.  
Otherwise, Q^T is computed.

IN     trans        Indicates whether to compute Q or Q^T.
                    (int)
IN     A            Householder vectors are stored below diagonal of A.
                    (PLA_MATRIX)
IN     s            Scaling factors for Householder transformations.
                    (PLA_MVECTOR of width 1)
IN/OUT Q            Matrix in which to form Q.
                    (PLA_MATRIX)




int PLA_Q_solve( int side, int trans, PLA_Obj A, PLA_Obj s, PLA_Obj B )


Purpose: Solve one of the following:

       OPERATION             SIDE               TRANS
       ----------------------------------------------
       Q   X = B               PLA_SIDE_LEFT      PLA_NO_TRANS
       Q^T X = B               PLA_SIDE_LEFT      PLA_TRANS
       X Q   = B               PLA_SIDE_RIGHT     PLA_NO_TRANS
       X Q^T = B               PLA_SIDE_RIGHT     PLA_TRANS
       
    where Q is stored as Householder vectors below the diagonal of A and in s
    and B is given.  The solution X overwrites B.

IN     side         Indicates whether Q appears to left or right of X.
IN     trans        Indicates whether to transpose Q.
IN     A            Householder vectors are stored below diagonal of A.
                    (PLA_MATRIX)
IN     s            Scaling factors for Householder transformations.
                    (PLA_MVECTOR of width 1)
IN/OUT B            Right-hand-sides.
                    (PLA_MATRIX or PLA_MVECTOR) 




Alphabetical Index

- A -
PLA_API_axpy_global_to_matrix
PLA_API_axpy_global_to_vector
PLA_API_axpy_matrix_to_global
PLA_API_axpy_vector_to_global
PLA_API_begin
PLA_API_end
PLA_API_multi_axpy_global_to_matrix
PLA_API_multi_axpy_global_to_vector
PLA_API_multi_axpy_matrix_to_global
PLA_API_multi_axpy_vector_to_global
PLA_API_state
PLA_Apply_W_Y
PLA_Asum
PLA_Axpy

- B -
PLA_Base_comm

- C -
PLA_Chol
PLA_Comm_1D_to_2D
PLA_Comm_1D_to_2D_ratio
PLA_Compute_House_v
PLA_Compute_W_Y
PLA_Copy
PLA_Copy_x
PLA_Create_constants_conf_to

- D -
PLA_Dot

- E -
PLA_Environ_nb_alg

- F -
PLA_Finalize
PLA_Form_Q

- G -
PLA_Gemm
PLA_Gemv
PLA_Ger

- H -

- I -
PLA_Iamax
PLA_Init
PLA_Initialized
PLA_Inv_scal

- J -

- K -

- L -
PLA_Least_sqr_solve
PLA_Local_asum
PLA_Local_axpy
PLA_Local_copy
PLA_Local_dot
PLA_Local_equal_zero
PLA_Local_gemm
PLA_Local_gemv
PLA_Local_ger
PLA_Local_iamax
PLA_Local_inv_scal
PLA_Local_invert_sign
PLA_Local_nrm2
PLA_Local_scal
PLA_Local_sign
PLA_Local_swap
PLA_Local_symm
PLA_Local_symv
PLA_Local_syr
PLA_Local_syr2
PLA_Local_syr2k
PLA_Local_syrk
PLA_Local_trmm
PLA_Local_trmv
PLA_Local_trsm
PLA_Local_trsv

- M -
PLA_Matrix_create
PLA_Matrix_create_conf_to
PLA_Mscalar_create
PLA_Mscalar_create_conf_to
PLA_Mvector_create
PLA_Mvector_create_conf_to

- N -
PLA_Nrm2

- O -
PLA_Obj_API_close
PLA_Obj_API_mode
PLA_Obj_API_open
PLA_Obj_API_sync
PLA_Obj_datatype
PLA_Obj_free
PLA_Obj_get_local_contents
PLA_Obj_get_orientation
PLA_Obj_global_align
PLA_Obj_global_align_col
PLA_Obj_global_align_row
PLA_Obj_global_info
PLA_Obj_global_length
PLA_Obj_global_numvecs
PLA_Obj_global_size
PLA_Obj_global_width
PLA_Obj_horz_split_2
PLA_Obj_local_buffer
PLA_Obj_local_info
PLA_Obj_local_ldim
PLA_Obj_local_length
PLA_Obj_local_stride
PLA_Obj_local_width
PLA_Obj_objtype
PLA_Obj_objtype_cast
PLA_Obj_owner_col
PLA_Obj_owner_row
PLA_Obj_project_onto
PLA_Obj_set
PLA_Obj_set_local_contents
PLA_Obj_set_orientation
PLA_Obj_set_to_identity
PLA_Obj_set_to_minus_one
PLA_Obj_set_to_one
PLA_Obj_set_to_zero
PLA_Obj_split_4
PLA_Obj_split_size
PLA_Obj_template
PLA_Obj_vert_split_2
PLA_Obj_view
PLA_Obj_view_all
PLA_Obj_view_shift
PLA_Obj_view_swap

- P -
PLA_Pmvector_create
PLA_Pmvector_create_conf_to
PLA_Pvector_create_f
PLA_Pvector_create_conf_to_f

- Q -
PLA_QR
PLA_Q_solve

- R -
PLA_Reduce
PLA_Reduce_x

- S -
PLA_Scal
PLA_Swap
PLA_Symm
PLA_Symv
PLA_Syr
PLA_Syr2
PLA_Syr2k
PLA_Syrk

- T -
PLA_Temp_comm_all
PLA_Temp_comm_all_info
PLA_Temp_comm_all_rank
PLA_Temp_comm_all_size
PLA_Temp_comm_col
PLA_Temp_comm_col_info
PLA_Temp_comm_col_rank
PLA_Temp_comm_col_size
PLA_Temp_comm_row
PLA_Temp_comm_row_info
PLA_Temp_comm_row_rank
PLA_Temp_comm_row_size
PLA_Temp_create
PLA_Temp_free
PLA_Temp_get_comm_dir
PLA_Temp_nb
PLA_Temp_set_comm_dir
PLA_Temp_zero_or_one
PLA_Trmm
PLA_Trmv
PLA_Trsm
PLA_Trsv

- V -
PLA_Vector_create
PLA_Vector_create_conf_to


Back to PLAPACK page

Send mail to
plapack@cs.utexas.edu

Last Updated: Oct. 16, 1998