Global Namespace¶

Overview¶

// typedefs

typedef struct XJPCG_ObjectStruct XJPCG_Handle_t
typedef enum XJPCG_Mode_t XJPCG_Mode_t

// enums

enum XJPCG_Mode_t
enum XJPCG_Status_t

// structs

struct XJPCG_Metric_t

// macros

#define XILINX_PCG_LINKAGE_DECL

Typedefs¶

typedef struct XJPCG_ObjectStruct XJPCG_Handle_t

dummy struct for XJPCG object type safety

Opaque struct for holding the state of JPCG operations

typedef enum XJPCG_Mode_t XJPCG_Mode_t

List of XJPCG solver modes.

Global Functions¶

xJPCG_getErrorString¶

#include "pcg.h"

const char* xJPCG_getErrorString (const XJPCG_Status_t code)

xJPCG_getErrorString get the string presentation of a given status code

Parameters:

code	status code

Returns:

error message string

xJPCG_createHandle¶

#include "pcg.h"

XJPCG_Status_t xJPCG_createHandle (
    XJPCG_Handle_t** handle,
    const int deviceId,
    const char* xclbinPath
    )

xJPCG_createHandle create a JPCG handle

Parameters:

handle	a pointer to the JPCG handle variable that will receive the PCG handle
deviceId	the ID of the device used for JPCG solver
xclbinPath	the path to xclbin file

Returns:

API status If the initialization fails, *handle may remain unchanged from its original value.

xJPCG_destroyHandle¶

#include "pcg.h"

XJPCG_Status_t xJPCG_destroyHandle (XJPCG_Handle_t* handle)

xJPCG_destroyHandle destroies a given JPCG handle

Parameters:

handel

JPCG handle to be destroyed

Returns:

API status

xJPCG_cscSymSolver¶

#include "pcg.h"

XJPCG_Status_t xJPCG_cscSymSolver (
    XJPCG_Handle_t* handle,
    const int64_t p_n,
    const int64_t p_nnz,
    const int64_t* p_rowIdx,
    const int64_t* p_colptr,
    const double* p_data,
    const double* p_diagA,
    const double* p_b,
    const double* p_x,
    const int64_t p_maxIter,
    const double p_tol,
    int64_t* p_iter,
    double* p_res,
    const XJPCG_Mode_t mode
    )

xJPCG_cscSymSolver solves a system Ax = b with sparse SPD (Symmetric Positive Definite) matrix A in CSC format

Convergency issue:

conjugate gradient method may suffer convergency issue for matrices with large condition number. Jacobi preconditioner adopted in this product is used to address this issue. However, for some matrices, even with Jacobi preconditioner the solver is not able to converge. If the returned value in parameter p_iter is equal to the maximum iteration numbers given by parameter p_maxIter , that means the solver cannot converge.

Mismatch issue:

for some matrices, the solver can terminate within the given number of iterations set by parameter p_maxIter , but produce the solution x that have some mismatches compared to the golden reference. This issue can be addressed by further reducing the relative tolerance value set by parameter p_tol . For example, using p_tol = 1e-15 might get the solver to produce correct results.

Parameters:

handle	pointer to a JPCG handle
p_n	dimension of given matrix and vectors
p_nnz	number of none-zero entries in p_data of sparse matrix A When using this API, only upper or lower triangular part and the main diagonal entries of the matrix A are stored. Therefore, the value of p_nnz should be equal to the (total_nnz + p_n) / 2, where total_nnz is the total number of none-zero entries in A, and the main diagonal entries in A are all none-zero entries. Users might need to pad the main diagoal entries when using this API.
p_rowIdx	row index of matrix A when parameter mode contains value XJPCG_MODE_FORTRAN_INDEX, the row indices start from 1. when parameter mode contains value XJPCG_MODE_C_INDEX, the row indices start from 0.
p_colptr	compressed col index pointer of matrix A when parameter mode contains value XJPCG_MODE_FORTRAN_INDEX, the col index pointer value starts from 1. when parameter mode contains value XJPCG_MODE_C_INDEX, the col index pointer value starts from 0.
p_data	data entries of matrix A, half matrix for symmetry
p_diagA	diagnal vector of matrix A
p_b	right-hand side vector
p_x	solution to the equation
p_maxIter	maximum number of iteration that solver could run
p_tol	the relative tolerence for solver to stop iteration
p_iter	the real iterations that solver takes
p_res	the relative residual when solver exits
mode	solver modes including date reuse and index type when using this API, the value of parameter mode normally contains two parts. One part is used for matrix reusage, the other for selecting C/Fortran storage. For example, setting mode with XJPCG_MODE_DEFAULT \| XJPCG_MODE_FORTRAN_INDEX means the matrix A will not be re-used to solve this system, and the matrix storage follows the convention in Fortran, namely indices start from 1.

Returns:

API status

xJPCG_cooSolver¶

#include "pcg.h"

XJPCG_Status_t xJPCG_cooSolver (
    XJPCG_Handle_t* handle,
    const uint32_t p_n,
    const uint32_t p_nnz,
    const uint32_t* p_rowIdx,
    const uint32_t* p_colIdx,
    const double* p_data,
    const double* p_diagA,
    const double* p_b,
    const double* p_x,
    const uint32_t p_maxIter,
    const double p_tol,
    uint32_t* p_iter,
    double* p_res,
    const XJPCG_Mode_t mode
    )

xJPCG_cooSolver solves equation Ax = b with sparse SPD matrix A in COO format

This function only supports C storage format. Hence the indices values start from 0.

Parameters:

handle	pointer to a JPCG handle
p_n	dimension of given matrix and vectors
p_nnz	number of non-zero entris in sparse matrix A
p_rowIdx	row index of matrix A
p_colIdx	col index of matrix A
p_data	data entries of matrix A, full matrix
p_diagA	diagnal vector of matrix A
p_b	right-hand side vector
p_x	solution to the equation
p_maxIter	maximum number of iteration that solve could run
p_tol	the relative tolerence for solver to stop iteration
p_iter	the real iterations that solver takes
p_res	the relative residual when solver exits
mode	solver modes including date reuse and index type

Returns:

API status

xJPCG_peekAtLastStatus¶

#include "pcg.h"

XJPCG_Status_t xJPCG_peekAtLastStatus (const XJPCG_Handle_t* handle)

xJPCG_peekAtLastStatus get the last status associated with handle

Parameters:

handle

JPCG handle

Returns:

API status

xJPCG_getLastMessage¶

#include "pcg.h"

const char* xJPCG_getLastMessage (const XJPCG_Handle_t* handle)

xJPCG_getLastMessage get the last status/error message associated with handle

NOTE: This function requires xJPCG_createHandle() to have progressed sufficiently far to produce a valid handle , except in the case of a dynamic loading error, for which even a null handle will produce a string for the cause of the loading error.

Note also that while dynamic loading operations themselves are thread safe, because there is only one global storage for the loading error, fetching the error message is not thread safe.

Parameters:

handle

pointer to a JPCG handle

Returns:

last status message

xJPCG_getMetrics¶

#include "pcg.h"

XJPCG_Status_t xJPCG_getMetrics (
    const XJPCG_Handle_t* handle,
    XJPCG_Metric_t* metric
    )

xJPCG_getMetrics get the last performance metrics associated with handle

This function fills the members of the given struct with performance metrics.

Parameters:

handle	JPCG handle
metric	pointer to a metric struct

Returns:

API status

Macros¶

#define XILINX_PCG_LINKAGE_DECL

Define this macro to make functions in pcg_loader.cpp inline instead of extern. You would use this macro when including pcg_loader.cpp in a header file, as opposed to linking with libXilinxPcg_loader.a.