aoclsparse_set_*_hint() - 5.2 English - 68552

Record hints of the expected number and types of calls to optimize the input matrix for.

Any of the aoclsparse_set_*_hint functions may be used to indicate that a given number of calls to the same Sparse BLAS API will be performed. When aoclsparse_optimize() is invoked, the input matrix might be tuned to accelerate the hinted calls.

Parameters:

• mat – [in] Input sparse matrix to be tuned.

• trans – [in] Matrix operation to perform during the calls.

• descr – [in] Descriptor of the sparse matrix used during the calls.

• expected_no_of_calls – [in] A rough estimate of the number of the calls.

Return values:

• aoclsparse_status_success – the operation completed successfully.

• aoclsparse_status_invalid_value – mat, trans, descr or expected_no_of_calls is invalid. Expecting expected_no_of_calls > 0.

• aoclsparse_status_invalid_pointer – mat or descr is invalid.

• aoclsparse_status_memory_error – internal memory allocation failure.

Provides hints to optimize preconditioning matrices.

Set hints for analysis and optimization of preconditioning-related factorizations and/or accelerate the application of such preconditioner, this can also include hints for “fused” operations that accelerate two operations in a single call.

Parameters:

• mat – [in] A sparse matrix

• trans – [in] Whether in transposed state or not. Transpose operation is not yet supported.

• descr – [in] Descriptor of the sparse matrix.

• expected_no_of_calls – [in] Expected number of call to an API that uses matrix mat.

Return values:

• aoclsparse_status_success – the operation completed successfully.

• aoclsparse_status_invalid_size – indicates that mat is invalid.

• aoclsparse_status_invalid_pointer – at least one of the input pointers is invalid.

• aoclsparse_status_internal_error – Indicates that an internal error occurred.

Record a hint of the expected number of calls to aoclsparse_strsm() and variants to optimize the input matrix for the hinted operations.

aoclsparse_set_sm_hint() may be used to indicate that a given number of calls to the triangular solver aoclsparse_strsm() or other variant will be performed. When aoclsparse_optimize() is invoked, the input matrix might be tuned to accelerate the hinted calls. The hints include not only the estimated number of calls to the API solver, but also other (matrix) parameters. The hinted matrix should not be modified after the call to optimize and before the call to the solver.

Parameters:

• mat – [in] Input sparse matrix to be tuned.

• trans – [in] Matrix operation to perform during the calls.

• descr – [in] Descriptor of the sparse matrix used during the calls.

• order – [in] Layout of the right-hand-side input matrix used during the calls, valid options are aoclsparse_order_row and aoclsparse_order_column.

• expected_no_of_calls – [in] A rough estimate of the number of the calls.

Return values:

• aoclsparse_status_success – the operation completed successfully.

• aoclsparse_status_invalid_value – expected_no_of_calls, order, mat, trans or descr is invalid.

• aoclsparse_status_invalid_pointer – mat or descr is invalid.

• aoclsparse_status_memory_error – internal memory allocation failure.

Record a hint of the expected number of aoclsparse_sorv() calls to optimize the input matrix for the hinted operations.

aoclsparse_set_sorv_hint may be used to indicate that a given number of calls to the SOR preconditioner aoclsparse_sorv() will be performed. When aoclsparse_optimize() is invoked, the input matrix might be tuned to accelerate the hinted calls. The hints include not only the estimated number of the API calls but also their other parameters which should match the actual calls.

Parameters:

• mat – [in] Input sparse matrix to be tuned.

• descr – [in] Descriptor of the sparse matrix used during the calls.

• type – [in] The operation to perform by the SOR preconditioner.

• expected_no_of_calls – [in] A rough estimate of the number of the calls.

Return values:

• aoclsparse_status_success – the operation completed successfully.

• aoclsparse_status_invalid_value – expected_no_of_calls, descr, type or mat type is invalid.

• aoclsparse_status_invalid_pointer – mat or descr is NULL.

• aoclsparse_status_memory_error – internal memory allocation failure.

Record user’s attitude to the memory consumption while optimizing the input matrix for the hinted operations.

aoclsparse_set_memory_hint may be used to indicate how much memory can be allocated during the optimization process of the input matrix for the previously hinted operations. In particular, aoclsparse_memory_usage_minimal suggests that the new memory should be only of order of vectors, whereas aoclsparse_memory_usage_unrestricted allows even new copies of the whole matrix. The unrestricted memory policy is the default. Any change to the memory policy applies only to any new optimizations for the new hints which have not been processed by aoclsparse_optimize() yet. The optimizations from any previous calls are unaffected. Note that the memory policy is only an indication rather than rule.

Parameters:

• mat – [in] Input sparse matrix to be tuned.

• policy – [in] Memory usage policy for future optimizations.

Return values:

• aoclsparse_status_success – the operation completed successfully.

• aoclsparse_status_invalid_value – policy type is invalid.

• aoclsparse_status_invalid_pointer – pointer mat is invalid.