/**
 * @file tool_spmat.h
 * @brief 稀疏矩阵的函数原型。此模块是稀疏线性代数模块的一部分。
 * This is function prototypes for sparse matrix. This module serves as part of sparse linear algebra module.
 * @version 0.1
 * @date 2021-09-17
 * 
 * @copyright Copyright (c) 2021
 * 
 */

#ifndef __TOOL_SPMAT_H__
#define __TOOL_SPMAT_H__

#include "csocp_config.h"

/*
 * Creating and deleting methods
 */

/** 创建新稀疏矩阵 Create a new sparse matrix */
c_spmat *c_spmat_create(c_int nRow, /**< 行数 Number of rows */
                        c_int nCol, /**< 列数 Number of columns */
                        c_int nElem /**< 非零元素数量 Number of elements */
);

/** 从已有数据中生成稀疏矩阵 Generate a sparse matrix from existing arrays */
c_spmat *c_spmat_generate(c_int nRow,     /**< 行数 Number of rows */
                          c_int nCol,     /**< 列数 Number of columns */
                          c_int nElem,    /**< 非零元素数量 Number of elements */
                          c_int *colBeg,  /**< CSC矩阵的begin指针 Begin pointer of column-wise matrix */
                          c_int *colIdx,  /**< CSC矩阵的index指针 Index pointer of column-wise matrix */
                          c_real *colElem /**< CSC矩阵的element指针 Element pointer of column-wise matrix */
);

/** 将数据加载到系数矩阵中 Load data to sparse matrix */
void c_spmat_loaddata(c_spmat *dstMat, /**< 需要加载数据的稀疏矩阵 Matrix to load data */
                      c_int *colBeg,   /**< CSC矩阵的begin指针 Begin pointer of column-wise matrix */
                      c_int *colIdx,   /**< CSC矩阵的index指针 Index pointer of column-wise matrix */
                      c_real *colElem  /**< CSC矩阵的element指针 Element pointer of column-wise matrix */
);

/** 析构一个稀疏矩阵 Free a sparse matrix */
void c_spmat_free(c_spmat **p_Mat);

/*
 * Advanced operation methods
 */

/** 寻找行/列中的最大值 Find maximal values for rows/columns of sparse matrix */
void c_spmat_findmax(c_spmat *srcMat, /**< 输入：稀疏矩阵 Input sparse matrix */
                     c_real *dstVal,  /**< 输出：值 Output values */
                     c_int ifCol      /**< 行/列 Whether to compute for rows/columns */
);

/** 计算行/列的平方和 Calculate sum of squares for rows/columns of sparse matrix */
void c_spmat_sumsquare(c_spmat *srcMat, /**< 输入：稀疏矩阵Input sparse matrix */
                       c_real *dstVal,  /**< 输出：值Output values */
                       c_int ifCol      /**< 行/列 Whether to compute for rows/columns */
);

/** 缩放行/列 Scale rows/columns of sparse matrix */
void c_spmat_setscale(c_spmat *srcMat,   /**< 输入：稀疏矩阵 Input sparse matrix */
                      c_real *srcFactor, /**< 输入：缩放系数 Input scaling factors */
                      c_int ifCol        /**< 行/列 Whether to compute for rows/columns */
);

/** 矩阵转置 Transpose a sparse matrix and return transposed sparse matrix */
c_spmat *c_spmat_transpose(c_spmat *srcMat /**< 输入：稀疏矩阵 Input sparse matrix */
);

/** 对称矩阵置换（仅保存上三角部分）Permutes a symmetric matrix with only the upper triangular part stored */
void c_spmat_permute(c_spmat *srcMat, /**< 输入：对称稀疏矩阵 Input sparse matrix */
                     c_int *srcInvP,  /**< 输入：逆转置 Input inverse permutation */
                     c_spmat *dstMat, /**< 输出：上三角矩阵 Output upper triangular sparse matrix */
                     c_int *srcDstMap /**< Index map between input and output */
);

/** 稀疏矩阵-向量乘法 Sparse matrix-vector multiplication */
void c_spmat_matvec(c_spmat *srcMat, /**< 输入：稀疏矩阵 Input sparse matrix */
                    c_real *srcX,    /**< 输入：稠密向量 Input dense vector */
                    c_real *srcDstY, /**< 输入输出：稠密向量 Output + Input dense vector */
                    c_int nSign,     /**< 是否进行加/减 Whether to do summation or subtraction */
                    c_int ifNewVec   /**< 是否使用新向量Y存储结果 Whether to use vector Y for output only */
);

/** 稀疏矩阵转置-向量乘法 Sparse matrix-transpose-vector multiplication */
void c_spmat_matvecm(c_spmat *srcMat, /**< 输入：稀疏矩阵 Input sparse matrix */
                     c_real *srcX,    /**< 输入：稠密向量 Input dense vector */
                     c_real *srcDstY, /**< 输入输出：稠密向量 Output + Input dense vector */
                     c_int ifNewVec,  /**< 是否使用新向量Y存储结果 Whether to use vector Y for output only */
                     c_int ifSkipDiag /**< 是否跳过对角元素 Whether to skip diagonal elements */
);

/*
 * Auxiliary methods
 */

/** 存储稀疏矩阵 调试功能 Dump sparse matrix to file for debug purpose */
void c_spmat_dump(c_spmat *srcMat, /**< 输入：稀疏矩阵 Input sparse matrix */
                  char *matFile    /**< 存储稀疏矩阵文件 Dumped matrix file */
);

/** 获取稀疏矩阵的内存需求量 Get memory requirment of sparse matrix */
c_int c_spmat_getmem(c_int nCol, /**< 列数 Number of columns */
                     c_int nElem /**< 非零元素数量 Number of elements */
);

#endif