| ADPCG 1.0.0

Macros | Functions
adpcg.c File Reference

Header for basic types and routine list. More...

`#include <string.h>`
`#include <stdio.h>`
`#include <stdlib.h>`
`#include <sys/time.h>`
`#include "adpcg.h"`

## Macros
#define | adpcg_free(var) do {free((var)); (var) = NULL;} while (0)

## Functions
static double | my_clock (void)
| Get time stamp for now. More...
static cgint | cg_prepare_preconditioner (adpcg *cg)
| Prepare pre-conditioner for the CG solver. More...
static cgint | cg_precondition (adpcg *cg, void *v)
| Apply pre-conditioning. More...
static cgint | cg_decision (adpcg *cg)
| Decide whether to update pre-conditioner. More...
cgint | cg_iteration (adpcg *cg, void *b, cgint warm)
| Implement conjugate gradinet. More...
void | cg_init (adpcg *cg)
| Initialize the conjugate gradient solver. More...
cgint | cg_alloc (adpcg *cg, cgint n, cgint vsize)
| Allocate internal memory for CG solver. More...
void | cg_register (adpcg *cg, void *A, void *diag, void *chol)
| Link pointers to LHS matrix, diagonal, and Cholesky pre-conditioner. More...
void | cg_free (adpcg *cg)
| Free the internal memory of CG solver. More...
void | cg_setparam (adpcg *cg, double tol, cgint reuse, cgint maxiter, cgint restart)
| Set parameters for the CG solver. More...
void | cg_getstats (adpcg *cg, cgint *status, cgint *niter, double *rnrm, double *avgsvtime, double *avgfctime, cgint *nused, cgint *nmaixter, cgint *nfactors, cgint *nrounds, cgint *nsolverd, cgint *nsolves)
| Extract CG statistics after some solve. More...
cgint | cg_start (adpcg *cg)
| Start a round of solves. More...
void | cg_finish (adpcg *cg)
| Finish a round of solve. More...
cgint | cg_solve (adpcg *cg, void *b, void *x0)
| Solve linear system using adaptive pre-conditioned conjugate gradient with restart. More...

## Detailed Description

Header for basic types and routine list.

Solve a sequence of linear systems by either pre-conditioned conjugate gradient or direct solver, which is chosen heuristically based on problem conditioning. The routine also implements an adaptive pre-conditioning mechanism that updates the pre-conditioner automatically. Diagonal and Cholesky pre-conditioners are implemented

Author
  Wenzhi Gao, Shanghai University of Finance and Economics

Date
  Aug 29th, 2022

## Function Documentation

## ◆ cg_alloc()

cgint cg_alloc | ( | adpcg * | cg,
|  | cgint | n,
|  | cgint | vsize
| ) |  |

Allocate internal memory for CG solver.

Parameters

  [in] | cg | Adaptive CG solver
  [in] | n | Dimension of the linear system
  [in] | vsize | Size of vector structure

Returns
  CG_OK if memory is successfully allocated

Allocate the internal memory for the CG solver.

## ◆ cg_decision()

static cgint cg_decision | ( | adpcg * | cg | ) |
| static

Decide whether to update pre-conditioner.

Parameters

  [in] | cg | CG solver

1.If the system is classified as ill-conditioned or indefinite by some user-defined criterion 2.If the diagonal pre-conditioner is used 3.If latesttime > 1.5 average solution time 4.If ADP-CG is asked to perform direct solve 5.If average solution time > average factorization time 6.If the "nused" property of the current pre-conditioner exceeds the user-defined threshold

## ◆ cg_finish()

void cg_finish | ( | adpcg * | cg | ) |

Finish a round of solve.

Parameters

  [in] | cg | CG solver

At the end of each round,

1. nused increases by 1
2. currenttime overwrites latesttime
3. nsolverd is reset

## ◆ cg_free()

void cg_free | ( | adpcg * | cg | ) |

Free the internal memory of CG solver.

Parameters

  [in] | cg | CG solver

Free all the internal memory allocated by adaptive CG solver. The solver pointer itself has to be freed by user.

## ◆ cg_getstats()

void cg_getstats | ( | adpcg * | cg,
|  | cgint * | status,
|  | cgint * | niter,
|  | double * | rnrm,
|  | double * | avgsvtime,
|  | double * | avgfctime,
|  | cgint * | nused,
|  | cgint * | nmaixter,
|  | cgint * | nfactors,
|  | cgint * | nrounds,
|  | cgint * | nsolverd,
|  | cgint * | nsolves
| ) |  |

Extract CG statistics after some solve.

Parameters

  [in] | cg | CG solver
  [out] | status | CG solution status
  [out] | niter | Number of CG iterations
  [out] | rnrm | Residual norm
  [out] | avgsvtime | Current avarage solution time
  [out] | avgfctime | Current average factorization time
  [out] | nused | Current number of iterations the pre-conditioner is used
  [out] | nmaixter | Number of iterations CG fails to solve the system
  [out] | nfactors | Number of factorizations
  [out] | nrounds | Number of rounds
  [out] | nsolverd | Number of solves in the current round
  [out] | nsolves | Number of solves

Collect different CG statistics. If some statistic is not needed, just let it be NULL.

## ◆ cg_init()

void cg_init | ( | adpcg * | cg | ) |

Initialize the conjugate gradient solver.

Parameters

  [in] | cg | Adaptive CG solver Initlaize all the pointers to NULL and values to 0

## ◆ cg_iteration()

cgint cg_iteration | ( | adpcg * | cg,
|  | void * | b,
|  | cgint | warm
| ) |  |

Implement conjugate gradinet.

Parameters

  [in] | cg | CG solver
  [in] | b | RHS vector
  [in] | warm | If there is warm start?

Implement pre-conditioned CG with restart

## ◆ cg_precondition()

static cgint cg_precondition | ( | adpcg * | cg,
|  | void * | v
| ) |  |
| static

Apply pre-conditioning.

Parameters

  [in] | cg | CG solver
  [in] | v | Overwritten by P \ v

Returns
  CG_OK if pre-conditioning is done successfully

## ◆ cg_prepare_preconditioner()

static cgint cg_prepare_preconditioner | ( | adpcg * | cg | ) |
| static

Prepare pre-conditioner for the CG solver.

Parameters

  [in] | cg | CG solver

Returns
  CG_OK if the pre-conditioner is successfully collected

The method invokes internal preparation routine of pre-conditioner. The time computing pre-conditioner is counted into avgsvtime

## ◆ cg_register()

void cg_register | ( | adpcg * | cg,
|  | void * | A,
|  | void * | diag,
|  | void * | chol
| ) |  |

Link pointers to LHS matrix, diagonal, and Cholesky pre-conditioner.

Parameters

  [in] | cg | CG Solver
  [in] | A | Left hand side matrix
  [in] | diag | Diagonal matrix
  [in] | chol | Cholesky factor

Register pointers for coefficient data, diagonal matrix and Cholesky factor

## ◆ cg_setparam()

void cg_setparam | ( | adpcg * | cg,
|  | double | tol,
|  | cgint | reuse,
|  | cgint | maxiter,
|  | cgint | restart
| ) |  |

Set parameters for the CG solver.

Parameters

  [in] | cg | CG solver
  [in] | tol | Relative solution tolerance
  [in] | reuse | The maximum reuse number
  [in] | maxiter | Maximum of iteration
  [in] | restart | Restart frequency of CG. -1 if automatically decided

Set CG parameters

## ◆ cg_solve()

cgint cg_solve | ( | adpcg * | cg,
|  | void * | b,
|  | void * | x0
| ) |  |

Solve linear system using adaptive pre-conditioned conjugate gradient with restart.

Parameters

  [in] | cg | CG Solver
  [in] | b | RHS vector. Overwritten when solved
  [in] | x0 | Initial point

Solve the linear system by adaptive pre-conditioning and restart.

## ◆ cg_start()

cgint cg_start | ( | adpcg * | cg | ) |

Start a round of solves.

Parameters

  [in] | cg | CG solver

Several rules decide whether to update the current pre-conditioner

## ◆ my_clock()

static double my_clock | ( | void |  | ) |
| static

Get time stamp for now.

Returns
  Current time stamp