Function

SparseIterate(_:_:_:_:_:_:_:_:_:)

Performs a single iteration of the specified iterative method for double-precision matrices, applying a preconditioner.

Declaration

func SparseIterate(_ method: SparseIterativeMethod, _ iteration: Int32, _ converged: UnsafePointer<Bool>, _ state: UnsafeMutableRawPointer, _ ApplyOperator: @escaping (Bool, CBLAS_TRANSPOSE, DenseMatrix_Double, DenseMatrix_Double) -> Void, _ B: DenseMatrix_Double, _ R: DenseMatrix_Double, _ X: DenseMatrix_Double, _ Preconditioner: SparseOpaquePreconditioner_Double)

Parameters

method

Iterative method specification, for example, the return value of SparseConjugateGradient().

Note that the options related to convergence testing (for example, maxIterations, atol, rtol) are ignored because convergence tests must be performed by the user.

iteration

The current iteration number, starting from 0. If iteration<0, then the current iteration is finalized, and the value of X is updated (note that this may force some methods to restart, slowing convergence).

converged

Convergence status of each right-hand-side. converged[j] = true indicates that the vector stored as column j of X has converged, and it should be ignored in this iteration.

state

A pointer to a state-space of size SparseGetStateSize_Double(_:_:_:_:_:). It must not be altered by the user between iterations, but may be safely discarded after the final call to SparseIterate.

ApplyOperator

The apply operator block to run. The block takes the following parameters:

accumulate

Indicates whether to perform y += op(A)x (if true) or y = op(A)x (if false).

trans

Indicates whether op(A) is the application of A if CblasNoTrans or Aᵀ if CblasTrans.

x

The vector to multiply.

y

The vector in which to accumulate or store the result.

B

The right-hand-sides to solve for.

R

Residual estimate. On entry with iteration = 0, it must hold the residuals b-Ax (equal to B if X = 0). On return from each call with iteration >= 0, the first entries of each vector contain various estimates of norms to be used in convergence testing.

For CG and GMRES:

  • R(0,j) holds an estimate of ‖ b-Ax ‖₂ for the j-th right-hand-side.

For LSMR:

  • R(0,j) holds an estimate of ‖ Aᵀ(b-Ax) ‖₂ for the j-th right-hand-side.

  • R(1,j) holds an estimate of ‖ b-Ax ‖₂ for the j-th right-hand-side.

  • R(2,j) holds an estimate of ‖ A ‖ꜰ, the Frobenius norm of A, estimated using calculations related to the j-th right-hand-side.

  • R(3,j) holds an estimate of cond(A), the condition number of A, estimated using calculations related to the j-th right-hand-side.

Other entries of R may be used by the routine as a workspace. On return from a call with iteration < 0, the exact residual vector b-Ax is returned.

X

The current estimate of the solution vectors X.

On entry with iteration = 0, this should be an initial estimate for the solution. If no good estimate is available, use X = 0.0.

Depending on the method used, X may not be updated at each iteration. The user should make a call with iteration < 0 once convergence has been achieved to bring X up to date.

Preconditioner

Preconditioner to apply.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software