source: CIVL/examples/mpi-omp/AMG2013/IJ_mv/HYPRE_IJ_mv.h

/*BHEADER**********************************************************************
 * Copyright (c) 2008,  Lawrence Livermore National Security, LLC.
 * Produced at the Lawrence Livermore National Laboratory.
 * This file is part of HYPRE.  See file COPYRIGHT for details.
 *
 * HYPRE is free software; you can redistribute it and/or modify it under the
 * terms of the GNU Lesser General Public License (as published by the Free
 * Software Foundation) version 2.1 dated February 1999.
 *
 * $Revision: 2.4 $
 ***********************************************************************EHEADER*/




#ifndef HYPRE_IJ_MV_HEADER
#define HYPRE_IJ_MV_HEADER

#include "HYPRE_utilities.h"

#ifdef __cplusplus
extern "C" {
#endif

/*--------------------------------------------------------------------------
 *--------------------------------------------------------------------------*/

/**
 * @name IJ System Interface
 *
 * This interface represents a linear-algebraic conceptual view of a
 * linear system.  The 'I' and 'J' in the name are meant to be
 * mnemonic for the traditional matrix notation A(I,J).
 *
 * @memo A linear-algebraic conceptual interface
 **/
/*@{*/

/*--------------------------------------------------------------------------
 *--------------------------------------------------------------------------*/

/**
 * @name IJ Matrices
 **/
/*@{*/

struct hypre_IJMatrix_struct;
/**
 * The matrix object.
 **/
typedef struct hypre_IJMatrix_struct *HYPRE_IJMatrix;

/**
 * Create a matrix object.  Each process owns some unique consecutive
 * range of rows, indicated by the global row indices {\tt ilower} and
 * {\tt iupper}.  The row data is required to be such that the value
 * of {\tt ilower} on any process $p$ be exactly one more than the
 * value of {\tt iupper} on process $p-1$.  Note that the first row of
 * the global matrix may start with any integer value.  In particular,
 * one may use zero- or one-based indexing.
 *
 * For square matrices, {\tt jlower} and {\tt jupper} typically should
 * match {\tt ilower} and {\tt iupper}, respectively.  For rectangular
 * matrices, {\tt jlower} and {\tt jupper} should define a
 * partitioning of the columns.  This partitioning must be used for
 * any vector $v$ that will be used in matrix-vector products with the
 * rectangular matrix.  The matrix data structure may use {\tt jlower}
 * and {\tt jupper} to store the diagonal blocks (rectangular in
 * general) of the matrix separately from the rest of the matrix.
 *
 * Collective.
 **/
int HYPRE_IJMatrixCreate(MPI_Comm        comm,
                         HYPRE_BigInt    ilower,
                         HYPRE_BigInt    iupper,
                         HYPRE_BigInt    jlower,
                         HYPRE_BigInt    jupper,
                         HYPRE_IJMatrix *matrix);

/**
 * Destroy a matrix object.  An object should be explicitly destroyed
 * using this destructor when the user's code no longer needs direct
 * access to it.  Once destroyed, the object must not be referenced
 * again.  Note that the object may not be deallocated at the
 * completion of this call, since there may be internal package
 * references to the object.  The object will then be destroyed when
 * all internal reference counts go to zero.
 **/
int HYPRE_IJMatrixDestroy(HYPRE_IJMatrix matrix);

/**
 * Prepare a matrix object for setting coefficient values.  This
 * routine will also re-initialize an already assembled matrix,
 * allowing users to modify coefficient values.
 **/
int HYPRE_IJMatrixInitialize(HYPRE_IJMatrix matrix);

/**
 * Sets values for {\tt nrows} rows or partial rows of the matrix.  
 * The arrays {\tt ncols}
 * and {\tt rows} are of dimension {\tt nrows} and contain the number
 * of columns in each row and the row indices, respectively.  The
 * array {\tt cols} contains the column indices for each of the {\tt
 * rows}, and is ordered by rows.  The data in the {\tt values} array
 * corresponds directly to the column entries in {\tt cols}.  Erases
 * any previous values at the specified locations and replaces them
 * with new ones, or, if there was no value there before, inserts a
 * new one.
 *
 * Not collective.
 **/
int HYPRE_IJMatrixSetValues(HYPRE_IJMatrix  matrix,
                            int             nrows,
                            int            *ncols,
                            const HYPRE_BigInt *rows,
                            const HYPRE_BigInt *cols,
                            const double   *values);

/**
 * Adds to values for {\tt nrows} rows or partial rows of the matrix.  
 * Usage details are
 * analogous to \Ref{HYPRE_IJMatrixSetValues}.  Adds to any previous
 * values at the specified locations, or, if there was no value there
 * before, inserts a new one.
 *
 * Not collective.
 **/
int HYPRE_IJMatrixAddToValues(HYPRE_IJMatrix  matrix,
                              int             nrows,
                              int            *ncols,
                              const HYPRE_BigInt *rows,
                              const HYPRE_BigInt *cols,
                              const double   *values);

/**
 * Finalize the construction of the matrix before using.
 **/
int HYPRE_IJMatrixAssemble(HYPRE_IJMatrix matrix);

/**
 * Gets number of nonzeros elements for {\tt nrows} rows specified in {\tt rows}
 * and returns them in {\tt ncols}, which needs to be allocated by the
 * user.
 **/
int HYPRE_IJMatrixGetRowCounts(HYPRE_IJMatrix  matrix,
                               int             nrows,
                               HYPRE_BigInt   *rows,
                               int            *ncols);

/**
 * Gets values for {\tt nrows} rows or partial rows of the matrix.  
 * Usage details are
 * analogous to \Ref{HYPRE_IJMatrixSetValues}.
 **/
int HYPRE_IJMatrixGetValues(HYPRE_IJMatrix  matrix,
                            int             nrows,
                            int            *ncols,
                            HYPRE_BigInt   *rows,
                            HYPRE_BigInt   *cols,
                            double         *values);

/**
 * Set the storage type of the matrix object to be constructed.
 * Currently, {\tt type} can only be {\tt HYPRE\_PARCSR}.
 *
 * Not collective, but must be the same on all processes.
 *
 * @see HYPRE_IJMatrixGetObject
 **/
int HYPRE_IJMatrixSetObjectType(HYPRE_IJMatrix matrix,
                                int            type);

/**
 * Get the storage type of the constructed matrix object.
 **/
int HYPRE_IJMatrixGetObjectType(HYPRE_IJMatrix  matrix,
                                int            *type);

/**
 * Gets range of rows owned by this processor and range
 * of column partitioning for this processor.
 **/
int HYPRE_IJMatrixGetLocalRange(HYPRE_IJMatrix  matrix,
                                HYPRE_BigInt   *ilower,
                                HYPRE_BigInt   *iupper,
                                HYPRE_BigInt   *jlower,
                                HYPRE_BigInt   *jupper);

/**
 * Get a reference to the constructed matrix object.
 *
 * @see HYPRE_IJMatrixSetObjectType
 **/
int HYPRE_IJMatrixGetObject(HYPRE_IJMatrix   matrix,
                            void           **object);

/**
 * (Optional) Set the max number of nonzeros to expect in each row.
 * The array {\tt sizes} contains estimated sizes for each row on this
 * process.  This call can significantly improve the efficiency of
 * matrix construction, and should always be utilized if possible.
 *
 * Not collective.
 **/
int HYPRE_IJMatrixSetRowSizes(HYPRE_IJMatrix  matrix,
                              const int      *sizes);

/**
 * (Optional) Set the max number of nonzeros to expect in each row of
 * the diagonal and off-diagonal blocks.  The diagonal block is the
 * submatrix whose column numbers correspond to rows owned by this
 * process, and the off-diagonal block is everything else.  The arrays
 * {\tt diag\_sizes} and {\tt offdiag\_sizes} contain estimated sizes
 * for each row of the diagonal and off-diagonal blocks, respectively.
 * This routine can significantly improve the efficiency of matrix
 * construction, and should always be utilized if possible.
 *
 * Not collective.
 **/
int HYPRE_IJMatrixSetDiagOffdSizes(HYPRE_IJMatrix  matrix,
                                   const int      *diag_sizes,
                                   const int      *offdiag_sizes);

/**
 * (Optional) Sets the maximum number of elements that are expected to be set
 * (or added) on other processors from this processor
 * This routine can significantly improve the efficiency of matrix
 * construction, and should always be utilized if possible.
 *
 * Not collective.
 **/
int HYPRE_IJMatrixSetMaxOffProcElmts(HYPRE_IJMatrix  matrix,
                                     int max_off_proc_elmts);

/**
 * Read the matrix from file.  This is mainly for debugging purposes.
 **/
int HYPRE_IJMatrixRead(const char     *filename,
                       MPI_Comm        comm,
                       int             type,
                       HYPRE_IJMatrix *matrix);

/**
 * Print the matrix to file.  This is mainly for debugging purposes.
 **/
int HYPRE_IJMatrixPrint(HYPRE_IJMatrix  matrix,
                        const char     *filename);

/*@}*/

/*--------------------------------------------------------------------------
 *--------------------------------------------------------------------------*/

/**
 * @name IJ Vectors
 **/
/*@{*/

struct hypre_IJVector_struct;
/**
 * The vector object.
 **/
typedef struct hypre_IJVector_struct *HYPRE_IJVector;

/**
 * Create a vector object.  Each process owns some unique consecutive
 * range of vector unknowns, indicated by the global indices {\tt
 * jlower} and {\tt jupper}.  The data is required to be such that the
 * value of {\tt jlower} on any process $p$ be exactly one more than
 * the value of {\tt jupper} on process $p-1$.  Note that the first
 * index of the global vector may start with any integer value.  In
 * particular, one may use zero- or one-based indexing.
 *
 * Collective.
 **/
int HYPRE_IJVectorCreate(MPI_Comm        comm,
                         HYPRE_BigInt    jlower,
                         HYPRE_BigInt    jupper,
                         HYPRE_IJVector *vector);

/**
 * Destroy a vector object.  An object should be explicitly destroyed
 * using this destructor when the user's code no longer needs direct
 * access to it.  Once destroyed, the object must not be referenced
 * again.  Note that the object may not be deallocated at the
 * completion of this call, since there may be internal package
 * references to the object.  The object will then be destroyed when
 * all internal reference counts go to zero.
 **/
int HYPRE_IJVectorDestroy(HYPRE_IJVector vector);

/**
 * Prepare a vector object for setting coefficient values.  This
 * routine will also re-initialize an already assembled vector,
 * allowing users to modify coefficient values.
 **/
int HYPRE_IJVectorInitialize(HYPRE_IJVector vector);

/**
 * (Optional) Sets the maximum number of elements that are expected to be set
 * (or added) on other processors from this processor
 * This routine can significantly improve the efficiency of matrix
 * construction, and should always be utilized if possible.
 *
 * Not collective.
 **/
int HYPRE_IJVectorSetMaxOffProcElmts(HYPRE_IJVector  vector,
                                     int max_off_proc_elmts);

/**
 * Sets values in vector.  The arrays {\tt values} and {\tt indices}
 * are of dimension {\tt nvalues} and contain the vector values to be
 * set and the corresponding global vector indices, respectively.
 * Erases any previous values at the specified locations and replaces
 * them with new ones.
 *
 * Not collective.
 **/
int HYPRE_IJVectorSetValues(HYPRE_IJVector  vector,
                            int             nvalues,
                            const HYPRE_BigInt *indices,
                            const double   *values);

/**
 * Adds to values in vector.  Usage details are analogous to
 * \Ref{HYPRE_IJVectorSetValues}.
 *
 * Not collective.
 **/
int HYPRE_IJVectorAddToValues(HYPRE_IJVector  vector,
                              int             nvalues,
                              const HYPRE_BigInt *indices,
                              const double   *values);

/**
 * Finalize the construction of the vector before using.
 **/
int HYPRE_IJVectorAssemble(HYPRE_IJVector vector);

/**
 * Gets values in vector.  Usage details are analogous to
 * \Ref{HYPRE_IJVectorSetValues}.
 *
 * Not collective.
 **/
int HYPRE_IJVectorGetValues(HYPRE_IJVector  vector,
                            int             nvalues,
                            const HYPRE_BigInt *indices,
                            double         *values);

/**
 * Set the storage type of the vector object to be constructed.
 * Currently, {\tt type} can only be {\tt HYPRE\_PARCSR}.
 *
 * Not collective, but must be the same on all processes.
 *
 * @see HYPRE_IJVectorGetObject
 **/
int HYPRE_IJVectorSetObjectType(HYPRE_IJVector vector,
                                int            type);

/**
 * Get the storage type of the constructed vector object.
 **/
int HYPRE_IJVectorGetObjectType(HYPRE_IJVector  vector,
                                int            *type);

/**
 * Returns range of the part of the vector owned by this processor.
 **/
int HYPRE_IJVectorGetLocalRange(HYPRE_IJVector  vector,
                                HYPRE_BigInt   *jlower,
                                HYPRE_BigInt   *jupper);

/**
 * Get a reference to the constructed vector object.
 *
 * @see HYPRE_IJVectorSetObjectType
 **/
int HYPRE_IJVectorGetObject(HYPRE_IJVector   vector,
                            void           **object);

/**
 * Read the vector from file.  This is mainly for debugging purposes.
 **/
int HYPRE_IJVectorRead(const char     *filename,
                       MPI_Comm        comm,
                       int             type,
                       HYPRE_IJVector *vector);

/**
 * Print the vector to file.  This is mainly for debugging purposes.
 **/
int HYPRE_IJVectorPrint(HYPRE_IJVector  vector,
                        const char     *filename);

/*@}*/
/*@}*/

#ifdef __cplusplus
}
#endif

#endif