Add preconditioning to the ALP CG solvers (#309)

This MR resolves a feature request for a preconditioned CG accessible via a transition path. To enable this feature, this MR adds the following:
- standard left-sided preconditioning to the ALP CG has been added. There are now two entry points `grb::algorithms::conjugate_gradient` for non-preconditioned CG, and `grb::algorithms::preconditioned_conjugate_gradient` for PCG. They are kept separate since PCG requires one more work-space vector. The preconditioner is given as an `std::function` that returns a `grb::RC`, takes an output `grb::Vector` and an input `const grb::Vector`. Given it's an `std::function`, any state required by the preconditioner can be embedded into the function (there is no additional argument required for this).
- the sparse solver transition path API now can take preconditioners also. Since this is a C API, the preconditioner is given as a function pointer. The return type is an `int` where `0` indicates successful application of the preconditioner. The first argument is a raw output vector, the second a const input vector, and the third a `void *` argument to any state required by the preconditioner.
- the kml_iss.h transition path API now also takes preconditioners, given as a function pointer with signature according to the current KML solver specification.

The MR also expands and improves documentation regarding the transition path libraries.

This MR adds the following smoke test:
- preconditioned CG with simple Jacobi preconditioning, both for real (`double`) and the complex case. Note that for the complex case, Jacobi preconditioning may not be a good choice; it is not encouraged to use outside of smoke testing.

To enable the smoke tests, this MR additionally includes the following bugfixes:
- the vector-to-vector foldr was not implemented in the BSP1D and hybrid backends, herewith fixed;
- the eWiseLambda(vector) for BSP1D and hybrid was using local indexing, while it should have been global;
- a meta-bug in the distributed implementation of `grb::set(BSP1D,hybrid)` erroneously relied on local indexing of eWiseLambda.

As always and additionally, the MR include code style fixes in both related and unrelated files.

Author: anyzelman

include/graphblas.hpp

@@ -38,16 +38,36 @@
  *  -# generalised sparse linear algebra, \ref GraphBLAS;
  *  -# vertex-centric programming, \ref Pregel.
  *
- * Additionally, to ease integration with existing software, ALP defines
- * so-called \ref TRANS libraries, which presently includes (partial)
- * implementations of the \ref SPARSEBLAS and \ref SPBLAS (de-facto) standards,
- * as well as an interface for numerical \ref TRANS_SOLVERS.
- *
  * Several other programming interfaces are under design at present.
  *
- * For authors who contributed to ALP, please see the NOTICE file.
- *
- * Contact:
+ * Additionally, to ease integration with existing software, ALP defines
+ * so-called \ref TRANS libraries. Such libraries may be employed to replace
+ * existing libraries, therefore benefitting of ALP-optimised software without
+ * having to change any source code-- simply switch out the library linked
+ * against, and transparently enjoy speedups such as enabled by the nonblocking
+ * backend.
+ *
+ * The \ref TRANS libraries are presently in a prototype stage. Presently, the
+ * following interfaces are (partially) implemented:
+ *  -# the \ref SPARSEBLAS standard (partial);
+ *  -# the \ref SPBLAS de-facto standard (partial);
+ *  -# the \ref TRANS_SOLVERS CRS/CSR-based sparse solver API (CG and PCG); and
+ *  -# the \ref kml_iss.h "KML Sparse Solver API".
+ *
+ * These transition path libraries are built and installed by default. Both
+ * sequential and shared-memory parallel libraries are provided.
+ *
+ * The maintainers are happy to consider requests for expanding the currently
+ * available transition paths, both in terms of missing functions in the
+ * presently available libraries, as well as of additional libraries; please
+ * feel free to submit feature requests on GitHub or Gitee, and/or to contact
+ * the maintainers.
+ *
+ * For the many authors who contributed to ALP, please see the NOTICE file
+ * distributed with ALP. The underwrited would like to take the opportunity here
+ * to express their sincere thanks for the many contributors over the years.
+ *
+ * Project contact information:
  *  - https://github.com/Algebraic-Programming/ALP
  *  - https://gitee.com/CSL-ALP/graphblas/
  *  - [email protected]