From 8ad06aa94619ab156bc8277073b8355363c6af09 Mon Sep 17 00:00:00 2001 From: LTLA Date: Mon, 26 Aug 2024 21:14:43 -0700 Subject: [PATCH] Improved the various docstrings related to parallelization. --- include/tatami/dense/convert_to_dense.hpp | 4 ++-- include/tatami/sparse/convert_to_compressed_sparse.hpp | 8 ++++---- include/tatami/sparse/convert_to_fragmented_sparse.hpp | 4 ++-- include/tatami/utils/parallelize.hpp | 3 ++- 4 files changed, 10 insertions(+), 9 deletions(-) diff --git a/include/tatami/dense/convert_to_dense.hpp b/include/tatami/dense/convert_to_dense.hpp index 15e56b2c..6a629724 100644 --- a/include/tatami/dense/convert_to_dense.hpp +++ b/include/tatami/dense/convert_to_dense.hpp @@ -29,7 +29,7 @@ namespace tatami { * @param row_major Whether to store the output as a row-major matrix. * @param[out] store Pointer to an array of length equal to the product of the dimensions of `matrix`. * On output, this is filled with values from `matrix` in row- or column-major format depending on `row_major`. - * @param threads Number of threads to use. + * @param threads Number of threads to use, for parallelization with `parallelize()`. */ template void convert_to_dense(const Matrix* matrix, bool row_major, StoredValue_* store, int threads = 1) { @@ -149,7 +149,7 @@ void convert_to_dense(const Matrix* matrix, bool row_m * * @param matrix Pointer to a `tatami::Matrix`. * @param row_major Whether to return a row-major matrix. - * @param threads Number of threads to use. + * @param threads Number of threads to use, for parallelization with `parallelize()`. * * @return A pointer to a new `tatami::DenseMatrix` with the same dimensions and type as the matrix referenced by `matrix`. * If `row_major = true`, the matrix is row-major, otherwise it is column-major. diff --git a/include/tatami/sparse/convert_to_compressed_sparse.hpp b/include/tatami/sparse/convert_to_compressed_sparse.hpp index d6194279..51df7f2f 100644 --- a/include/tatami/sparse/convert_to_compressed_sparse.hpp +++ b/include/tatami/sparse/convert_to_compressed_sparse.hpp @@ -233,7 +233,7 @@ void fill_compressed_sparse_matrix_inconsistent( * @param row Whether to count structural non-zeros by row. * @param[out] output Pointer to an array of length equal to the number of rows (if `row = true`) or columns (otherwise) of `matrix`. * On output, this stores the number of structural non-zeros in each row (if `row = true`) or column (otherwise). - * @param threads Number of threads to use. + * @param threads Number of threads to use, for parallelization with `parallelize()`. * * For sparse `matrix`, all structural non-zero elements are reported, even if they have actual values of zero. * In contrast, for dense `matrix`, only the non-zero values are counted; @@ -271,7 +271,7 @@ void count_compressed_sparse_non_zeros(const tatami::Matrix* mat * On output, this is used to store the values of those elements in a compressed sparse format (e.g., `CompressedSparseContents::value`). * @param[out] output_index Pointer to an array of length equal to the total number of structural non-zero elements. * On output, this is used to store the row/column indices of those elements in a compressed sparse format (e.g., `CompressedSparseContents::index`). - * @param threads Number of threads to use. + * @param threads Number of threads to use, for parallelization with `parallelize()`. */ template void fill_compressed_sparse_contents( @@ -333,7 +333,7 @@ struct CompressedSparseContents { * @param row Whether to retrieve the contents of `matrix` by row, i.e., the output is a compressed sparse row matrix. * @param two_pass Whether to perform the retrieval in two passes. * This requires another pass through `matrix` but is more memory-efficient. - * @param threads Number of threads to use. + * @param threads Number of threads to use, for parallelization with `parallelize()`. * * @return Contents of the sparse matrix in compressed form, see `CompressedSparseContents`. * @@ -429,7 +429,7 @@ CompressedSparseContents retrieve_co * @param matrix Pointer to a `tatami::Matrix`, possibly containing delayed operations. * @param row Whether to return a compressed sparse row matrix. * @param two_pass Whether to use a two-pass strategy that reduces peak memory usage at the cost of speed. - * @param threads Number of threads to use. + * @param threads Number of threads to use, for parallelization with `parallelize()`. * * @return A pointer to a new `tatami::CompressedSparseMatrix`, with the same dimensions and type as the matrix referenced by `matrix`. * If `row = true`, the matrix is in compressed sparse row format, otherwise it is compressed sparse column. diff --git a/include/tatami/sparse/convert_to_fragmented_sparse.hpp b/include/tatami/sparse/convert_to_fragmented_sparse.hpp index 00234de3..78370568 100644 --- a/include/tatami/sparse/convert_to_fragmented_sparse.hpp +++ b/include/tatami/sparse/convert_to_fragmented_sparse.hpp @@ -58,7 +58,7 @@ struct FragmentedSparseContents { * * @param matrix Pointer to a `tatami::Matrix`. * @param row Whether to retrieve the contents of `matrix` by row, i.e., the output is a fragmented sparse row matrix. - * @param threads Number of threads to use. + * @param threads Number of threads to use, for parallelization with `parallelize()`. * * @return Contents of the sparse matrix in fragmented form, see `FragmentedSparseContents`. */ @@ -172,7 +172,7 @@ FragmentedSparseContents retrieve_fragmented_sparse_ * * @param matrix Pointer to a `tatami::Matrix`, possibly containing delayed operations. * @param row Whether to return a fragmented sparse row matrix. - * @param threads Number of threads to use. + * @param threads Number of threads to use, for parallelization with `parallelize()`. * * @return A pointer to a new `tatami::FragmentedSparseMatrix`, with the same dimensions and type as the matrix referenced by `matrix`. * If `row = true`, the matrix is in fragmented sparse row format, otherwise it is fragmented sparse column. diff --git a/include/tatami/utils/parallelize.hpp b/include/tatami/utils/parallelize.hpp index c5eec69c..6ae647cd 100644 --- a/include/tatami/utils/parallelize.hpp +++ b/include/tatami/utils/parallelize.hpp @@ -18,7 +18,8 @@ namespace tatami { /** * Apply a function to a set of tasks in parallel, usually for iterating over a dimension of a `Matrix`. - * By default, this uses `subpar::parallelize()` internally but can be overridden by defining a `TATAMI_CUSTOM_PARALLEL` function-like macro. + * By default, this uses `subpar::parallelize()` internally, which uses OpenMP if available and `` otherwise. + * Advanced users can override the default parallelization mechanism by defining a `TATAMI_CUSTOM_PARALLEL` function-like macro. * The macro should accept the `fun`, `tasks` and `threads` arguments as described below. * * @tparam parallel_ Whether the tasks should be run in parallel.