ALP User Documentation  0.8.preview
Algebraic Programming User Documentation
solver.h
Go to the documentation of this file.
1 
2 /*
3  * Copyright 2023 Huawei Technologies Co., Ltd.
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
107 #ifndef _H_ALP_SPARSE_LINSOLVERS
108 #define _H_ALP_SPARSE_LINSOLVERS
109 
110 #include <stddef.h> // for size_t
111 
112 
113 #ifdef __cplusplus
114 extern "C" {
115 #endif
116 
120 typedef enum {
121 
124 
129 
134 
139 
145 
153 
154 } sparse_err_t;
155 
159 typedef void * sparse_cg_handle_t;
160 
183  float * const,
184  const float * const,
185  void * const
186 );
187 
210  double * const,
211  const double * const,
212  void * const
213 );
214 
249  sparse_cg_handle_t * const handle, const size_t n,
250  const float * const a, const int * const ja, const int * const ia
251 );
252 
262  sparse_cg_handle_t * const handle, const size_t n,
263  const double * const a, const int * const ja, const int * const ia
264 );
265 
276  sparse_cg_handle_t * const handle, const size_t n,
277  const float * const a, const int * const ja, const size_t * const ia
278 );
279 
290  sparse_cg_handle_t * const handle, const size_t n,
291  const double * const a, const int * const ja, const size_t * const ia
292 );
293 
304  sparse_cg_handle_t * const handle, const size_t n,
305  const float * const a, const size_t * const ja, const size_t * const ia
306 );
307 
318  sparse_cg_handle_t * const handle, const size_t n,
319  const double * const a, const size_t * const ja, const size_t * const ia
320 );
321 
322 // Note that szi and dzi are skipped on purpose. Such variants would not seem
323 // sensible, though could easily be provided if they do turn out to be needed
324 
348  sparse_cg_handle_t const handle, size_t * const size
349 );
350 
374  sparse_cg_handle_t const handle, size_t * const size
375 );
376 
400  sparse_cg_handle_t const handle, size_t * const size
401 );
402 
426  sparse_cg_handle_t const handle, size_t * const size
427 );
428 
452  sparse_cg_handle_t const handle, size_t * const size
453 );
454 
478  sparse_cg_handle_t const handle, size_t * const size
479 );
480 
504  const sparse_cg_handle_t handle, float * const tol );
505 
517  const sparse_cg_handle_t handle, float * const tol );
518 
530  const sparse_cg_handle_t handle, float * const tol );
531 
543  const sparse_cg_handle_t handle, double * const tol );
544 
556  const sparse_cg_handle_t handle, double * const tol );
557 
569  const sparse_cg_handle_t handle, double * const tol );
570 
571 
592  sparse_cg_handle_t handle, const float tol );
593 
605  sparse_cg_handle_t handle, const float tol );
606 
618  sparse_cg_handle_t handle, const float tol );
619 
631  sparse_cg_handle_t handle, const double tol );
632 
644  sparse_cg_handle_t handle, const double tol );
645 
657  sparse_cg_handle_t handle, const double tol );
658 
679  sparse_cg_handle_t handle, const size_t max_iters );
680 
692  sparse_cg_handle_t handle, const size_t max_iters );
693 
705  sparse_cg_handle_t handle, const size_t max_iters );
706 
718  sparse_cg_handle_t handle, const size_t max_iters );
719 
731  sparse_cg_handle_t handle, const size_t max_iters );
732 
744  sparse_cg_handle_t handle, const size_t max_iters );
745 
746 // other variants of sparse_cg_set_max_iter_count could take int, uint, etc.
747 // inputs
748 
749 
779  const sparse_cg_handle_t handle, float * const tol );
780 
798  const sparse_cg_handle_t handle, float * const tol );
799 
817  const sparse_cg_handle_t handle, float * const tol );
818 
836  const sparse_cg_handle_t handle, double * const tol );
837 
855  const sparse_cg_handle_t handle, double * const tol );
856 
874  const sparse_cg_handle_t handle, double * const tol );
875 
876 
906  const sparse_cg_handle_t handle, size_t * const iters );
907 
925  const sparse_cg_handle_t handle, size_t * const iters );
926 
944  const sparse_cg_handle_t handle, size_t * const iters );
945 
963  const sparse_cg_handle_t handle, size_t * const iters );
964 
982  const sparse_cg_handle_t handle, size_t * const iters );
983 
1001  const sparse_cg_handle_t handle, size_t * const iters );
1002 
1003 // another variant of sparse_cg_get_iter_count could provide output as an int,
1004 // uint, etc.
1005 
1035  const sparse_cg_handle_t handle,
1036  sparse_cg_preconditioner_sxx_t * const preconditioner,
1037  void * * const data
1038 );
1039 
1069  const sparse_cg_handle_t handle,
1070  sparse_cg_preconditioner_sxx_t * const preconditioner,
1071  void * * const data
1072 );
1073 
1103  const sparse_cg_handle_t handle,
1104  sparse_cg_preconditioner_sxx_t * const preconditioner,
1105  void * * const data
1106 );
1107 
1137  const sparse_cg_handle_t handle,
1138  sparse_cg_preconditioner_dxx_t * const preconditioner,
1139  void * * const data
1140 );
1141 
1171  const sparse_cg_handle_t handle,
1172  sparse_cg_preconditioner_dxx_t * const preconditioner,
1173  void * * const data
1174 );
1175 
1205  const sparse_cg_handle_t handle,
1206  sparse_cg_preconditioner_dxx_t * const preconditioner,
1207  void * * const data
1208 );
1209 
1237  const sparse_cg_handle_t handle,
1238  const sparse_cg_preconditioner_sxx_t preconditioner,
1239  void * const data
1240 );
1241 
1269  const sparse_cg_handle_t handle,
1270  const sparse_cg_preconditioner_dxx_t preconditioner,
1271  void * const data
1272 );
1273 
1301  const sparse_cg_handle_t handle,
1302  const sparse_cg_preconditioner_sxx_t preconditioner,
1303  void * const data
1304 );
1305 
1333  const sparse_cg_handle_t handle,
1334  const sparse_cg_preconditioner_dxx_t preconditioner,
1335  void * const data
1336 );
1337 
1365  const sparse_cg_handle_t handle,
1366  const sparse_cg_preconditioner_sxx_t preconditioner,
1367  void * const data
1368 );
1369 
1397  const sparse_cg_handle_t handle,
1398  const sparse_cg_preconditioner_dxx_t preconditioner,
1399  void * const data
1400 );
1401 
1444  sparse_cg_handle_t handle, float * const x, const float * const b );
1445 
1470  sparse_cg_handle_t handle, float * const x, const float * const b );
1471 
1496  sparse_cg_handle_t handle, float * const x, const float * const b );
1497 
1522  sparse_cg_handle_t handle, double * const x, const double * const b );
1523 
1548  sparse_cg_handle_t handle, double * const x, const double * const b );
1549 
1574  sparse_cg_handle_t handle, double * const x, const double * const b );
1575 
1576 
1594 
1606 
1618 
1630 
1642 
1654  // ends doxygen page for the solver library
1656 
1657 #ifdef __cplusplus
1658 } // end extern "C"
1659 #endif
1660 
1661 #endif // end ifdef _H_ALP_LINSOLVERS
1662 
sparse_err_t sparse_cg_get_preconditioner_dii(const sparse_cg_handle_t handle, sparse_cg_preconditioner_dxx_t *const preconditioner, void **const data)
Retrieves the currently active preconditioner.
sparse_err_t sparse_cg_solve_dii(sparse_cg_handle_t handle, double *const x, const double *const b)
Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x.
Illegal NULL pointer provided as argument.
Definition: solver.h:128
sparse_err_t sparse_cg_get_size_dii(sparse_cg_handle_t const handle, size_t *const size)
Retrieves the system size for a given CG solver handle.
sparse_err_t sparse_cg_set_max_iter_count_siz(sparse_cg_handle_t handle, const size_t max_iters)
Sets the current maximum number of iterations for the given CG solver.
sparse_err_t sparse_cg_set_tolerance_siz(sparse_cg_handle_t handle, const float tol)
Sets the current accepted relative tolerance for the given CG solver.
sparse_err_t sparse_cg_destroy_siz(sparse_cg_handle_t handle)
Destroys a valid CG solver handle.
sparse_err_t sparse_cg_init_szz(sparse_cg_handle_t *const handle, const size_t n, const float *const a, const size_t *const ja, const size_t *const ia)
Initialises a sparse_cg_handle_t object.
sparse_err_t sparse_cg_set_preconditioner_dii(const sparse_cg_handle_t handle, const sparse_cg_preconditioner_dxx_t preconditioner, void *const data)
Sets a new preconditioner to apply during a next solve call.
sparse_err_t sparse_cg_get_preconditioner_diz(const sparse_cg_handle_t handle, sparse_cg_preconditioner_dxx_t *const preconditioner, void **const data)
Retrieves the currently active preconditioner.
sparse_err_t sparse_cg_solve_sii(sparse_cg_handle_t handle, float *const x, const float *const b)
Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x.
sparse_err_t sparse_cg_get_preconditioner_dzz(const sparse_cg_handle_t handle, sparse_cg_preconditioner_dxx_t *const preconditioner, void **const data)
Retrieves the currently active preconditioner.
sparse_err_t sparse_cg_get_residual_dzz(const sparse_cg_handle_t handle, double *const tol)
Retrieves the residual the given CG solve has achieved.
sparse_err_t sparse_cg_get_size_dzz(sparse_cg_handle_t const handle, size_t *const size)
Retrieves the system size for a given CG solver handle.
sparse_err_t sparse_cg_destroy_sii(sparse_cg_handle_t handle)
Destroys a valid CG solver handle.
sparse_err_t sparse_cg_get_tolerance_siz(const sparse_cg_handle_t handle, float *const tol)
Gets the current accepted relative tolerance for the given CG solver.
int(* sparse_cg_preconditioner_sxx_t)(float *const, const float *const, void *const)
A user-defined preconditioner function type for CG solver that employ single-precision floating-point...
Definition: solver.h:182
sparse_err_t sparse_cg_set_tolerance_dii(sparse_cg_handle_t handle, const double tol)
Sets the current accepted relative tolerance for the given CG solver.
sparse_err_t sparse_cg_get_size_szz(sparse_cg_handle_t const handle, size_t *const size)
Retrieves the system size for a given CG solver handle.
sparse_err_t sparse_cg_init_dii(sparse_cg_handle_t *const handle, const size_t n, const double *const a, const int *const ja, const int *const ia)
Initialises a sparse_cg_handle_t object.
sparse_err_t sparse_cg_init_dzz(sparse_cg_handle_t *const handle, const size_t n, const double *const a, const size_t *const ja, const size_t *const ia)
Initialises a sparse_cg_handle_t object.
sparse_err_t sparse_cg_destroy_szz(sparse_cg_handle_t handle)
Destroys a valid CG solver handle.
sparse_err_t sparse_cg_get_iter_count_szz(const sparse_cg_handle_t handle, size_t *const iters)
Retrieves the number of iterations the given CG solver has employed.
sparse_err_t sparse_cg_destroy_dii(sparse_cg_handle_t handle)
Destroys a valid CG solver handle.
void * sparse_cg_handle_t
A solver handle for the Conjugate Gradient algorithm.
Definition: solver.h:159
sparse_err_t sparse_cg_get_preconditioner_siz(const sparse_cg_handle_t handle, sparse_cg_preconditioner_sxx_t *const preconditioner, void **const data)
Retrieves the currently active preconditioner.
sparse_err_t sparse_cg_get_residual_diz(const sparse_cg_handle_t handle, double *const tol)
Retrieves the residual the given CG solve has achieved.
sparse_err_t sparse_cg_solve_diz(sparse_cg_handle_t handle, double *const x, const double *const b)
Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x.
sparse_err_t sparse_cg_get_tolerance_sii(const sparse_cg_handle_t handle, float *const tol)
Gets the current accepted relative tolerance for the given CG solver.
sparse_err_t sparse_cg_set_preconditioner_diz(const sparse_cg_handle_t handle, const sparse_cg_preconditioner_dxx_t preconditioner, void *const data)
Sets a new preconditioner to apply during a next solve call.
sparse_err_t sparse_cg_get_size_diz(sparse_cg_handle_t const handle, size_t *const size)
Retrieves the system size for a given CG solver handle.
An unknown error has been encountered.
Definition: solver.h:152
sparse_err_t sparse_cg_get_residual_siz(const sparse_cg_handle_t handle, float *const tol)
Retrieves the residual the given CG solve has achieved.
sparse_err_t sparse_cg_destroy_diz(sparse_cg_handle_t handle)
Destroys a valid CG solver handle.
sparse_err_t sparse_cg_destroy_dzz(sparse_cg_handle_t handle)
Destroys a valid CG solver handle.
sparse_err_t sparse_cg_get_preconditioner_szz(const sparse_cg_handle_t handle, sparse_cg_preconditioner_sxx_t *const preconditioner, void **const data)
Retrieves the currently active preconditioner.
sparse_err_t sparse_cg_get_iter_count_sii(const sparse_cg_handle_t handle, size_t *const iters)
Retrieves the number of iterations the given CG solver has employed.
sparse_err_t sparse_cg_set_tolerance_szz(sparse_cg_handle_t handle, const float tol)
Sets the current accepted relative tolerance for the given CG solver.
sparse_err_t sparse_cg_set_preconditioner_dzz(const sparse_cg_handle_t handle, const sparse_cg_preconditioner_dxx_t preconditioner, void *const data)
Sets a new preconditioner to apply during a next solve call.
sparse_err_t sparse_cg_set_max_iter_count_szz(sparse_cg_handle_t handle, const size_t max_iters)
Sets the current maximum number of iterations for the given CG solver.
sparse_err_t sparse_cg_set_preconditioner_sii(const sparse_cg_handle_t handle, const sparse_cg_preconditioner_sxx_t preconditioner, void *const data)
Sets a new preconditioner to apply during a next solve call.
sparse_err_t sparse_cg_set_tolerance_sii(sparse_cg_handle_t handle, const float tol)
Sets the current accepted relative tolerance for the given CG solver.
sparse_err_t sparse_cg_get_tolerance_dii(const sparse_cg_handle_t handle, double *const tol)
Gets the current accepted relative tolerance for the given CG solver.
sparse_err_t sparse_cg_set_max_iter_count_dii(sparse_cg_handle_t handle, const size_t max_iters)
Sets the current maximum number of iterations for the given CG solver.
sparse_err_t sparse_cg_solve_szz(sparse_cg_handle_t handle, float *const x, const float *const b)
Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x.
sparse_err_t sparse_cg_init_siz(sparse_cg_handle_t *const handle, const size_t n, const float *const a, const int *const ja, const size_t *const ia)
Initialises a sparse_cg_handle_t object.
sparse_err_t sparse_cg_get_residual_dii(const sparse_cg_handle_t handle, double *const tol)
Retrieves the residual the given CG solve has achieved.
The call has completed successfully.
Definition: solver.h:123
sparse_err_t sparse_cg_set_preconditioner_szz(const sparse_cg_handle_t handle, const sparse_cg_preconditioner_sxx_t preconditioner, void *const data)
Sets a new preconditioner to apply during a next solve call.
sparse_err_t sparse_cg_get_residual_szz(const sparse_cg_handle_t handle, float *const tol)
Retrieves the residual the given CG solve has achieved.
sparse_err_t
The various error codes sparse solver library functions may return.
Definition: solver.h:120
sparse_err_t sparse_cg_set_max_iter_count_dzz(sparse_cg_handle_t handle, const size_t max_iters)
Sets the current maximum number of iterations for the given CG solver.
sparse_err_t sparse_cg_get_size_sii(sparse_cg_handle_t const handle, size_t *const size)
Retrieves the system size for a given CG solver handle.
sparse_err_t sparse_cg_get_iter_count_dii(const sparse_cg_handle_t handle, size_t *const iters)
Retrieves the number of iterations the given CG solver has employed.
Out of memory error detected during call.
Definition: solver.h:138
sparse_err_t sparse_cg_set_tolerance_diz(sparse_cg_handle_t handle, const double tol)
Sets the current accepted relative tolerance for the given CG solver.
sparse_err_t sparse_cg_set_tolerance_dzz(sparse_cg_handle_t handle, const double tol)
Sets the current accepted relative tolerance for the given CG solver.
sparse_err_t sparse_cg_get_residual_sii(const sparse_cg_handle_t handle, float *const tol)
Retrieves the residual the given CG solve has achieved.
sparse_err_t sparse_cg_get_iter_count_diz(const sparse_cg_handle_t handle, size_t *const iters)
Retrieves the number of iterations the given CG solver has employed.
sparse_err_t sparse_cg_init_sii(sparse_cg_handle_t *const handle, const size_t n, const float *const a, const int *const ja, const int *const ia)
Initialises a sparse_cg_handle_t object.
sparse_err_t sparse_cg_init_diz(sparse_cg_handle_t *const handle, const size_t n, const double *const a, const int *const ja, const size_t *const ia)
Initialises a sparse_cg_handle_t object.
int(* sparse_cg_preconditioner_dxx_t)(double *const, const double *const, void *const)
A user-defined preconditioner function type for CG solver that employ double-precision floating-point...
Definition: solver.h:209
sparse_err_t sparse_cg_solve_siz(sparse_cg_handle_t handle, float *const x, const float *const b)
Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x.
sparse_err_t sparse_cg_get_size_siz(sparse_cg_handle_t const handle, size_t *const size)
Retrieves the system size for a given CG solver handle.
sparse_err_t sparse_cg_set_max_iter_count_sii(sparse_cg_handle_t handle, const size_t max_iters)
Sets the current maximum number of iterations for the given CG solver.
size_t size(const Vector< DataType, backend, Coords > &x) noexcept
Request the size of a given vector.
Definition: io.hpp:235
sparse_err_t sparse_cg_set_max_iter_count_diz(sparse_cg_handle_t handle, const size_t max_iters)
Sets the current maximum number of iterations for the given CG solver.
sparse_err_t sparse_cg_get_iter_count_siz(const sparse_cg_handle_t handle, size_t *const iters)
Retrieves the number of iterations the given CG solver has employed.
sparse_err_t sparse_cg_get_tolerance_dzz(const sparse_cg_handle_t handle, double *const tol)
Gets the current accepted relative tolerance for the given CG solver.
sparse_err_t sparse_cg_get_tolerance_diz(const sparse_cg_handle_t handle, double *const tol)
Gets the current accepted relative tolerance for the given CG solver.
sparse_err_t sparse_cg_get_iter_count_dzz(const sparse_cg_handle_t handle, size_t *const iters)
Retrieves the number of iterations the given CG solver has employed.
sparse_err_t sparse_cg_solve_dzz(sparse_cg_handle_t handle, double *const x, const double *const b)
Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x.
The algorithm has failed achieving its intended result.
Definition: solver.h:144
Illegal argument provided.
Definition: solver.h:133
sparse_err_t sparse_cg_set_preconditioner_siz(const sparse_cg_handle_t handle, const sparse_cg_preconditioner_sxx_t preconditioner, void *const data)
Sets a new preconditioner to apply during a next solve call.
sparse_err_t sparse_cg_get_tolerance_szz(const sparse_cg_handle_t handle, float *const tol)
Gets the current accepted relative tolerance for the given CG solver.
sparse_err_t sparse_cg_get_preconditioner_sii(const sparse_cg_handle_t handle, sparse_cg_preconditioner_sxx_t *const preconditioner, void **const data)
Retrieves the currently active preconditioner.