(git:c09f6e5)
Loading...
Searching...
No Matches
dbm_matrix.h
Go to the documentation of this file.
1/*----------------------------------------------------------------------------*/
2/* CP2K: A general program to perform molecular dynamics simulations */
3/* Copyright 2000-2025 CP2K developers group <https://cp2k.org> */
4/* */
5/* SPDX-License-Identifier: BSD-3-Clause */
6/*----------------------------------------------------------------------------*/
7#ifndef DBM_MATRIX_H
8#define DBM_MATRIX_H
9
10#include "dbm_distribution.h"
11#include "dbm_shard.h"
12
13#include <stdbool.h>
14
15/*******************************************************************************
16 * \brief Internal struct for storing a matrix.
17 * \author Ole Schuett
18 ******************************************************************************/
29
30/*******************************************************************************
31 * \brief Internal struct for storing a block iterator.
32 * \author Ole Schuett
33 ******************************************************************************/
34typedef struct {
35 const dbm_matrix_t *matrix;
36 int next_block;
37 int next_shard;
38} dbm_iterator_t;
39
40/*******************************************************************************
41 * \brief Creates a new matrix.
42 * \author Ole Schuett
43 ******************************************************************************/
44void dbm_create(dbm_matrix_t **matrix_out, dbm_distribution_t *dist,
45 const char name[], const int nrows, const int ncols,
46 const int row_sizes[nrows], const int col_sizes[ncols]);
47
48/*******************************************************************************
49 * \brief Releases a matrix and all its ressources.
50 * \author Ole Schuett
51 ******************************************************************************/
52void dbm_release(dbm_matrix_t *matrix);
53
54/*******************************************************************************
55 * \brief Copies content of matrix_b into matrix_a.
56 * Matrices must have the same row/col block sizes and distribution.
57 * \author Ole Schuett
58 ******************************************************************************/
59void dbm_copy(dbm_matrix_t *matrix_a, const dbm_matrix_t *matrix_b);
60
61/*******************************************************************************
62 * \brief Copies content of matrix_b into matrix_a.
63 * Matrices may have different distributions.
64 * \author Ole Schuett
65 ******************************************************************************/
66void dbm_redistribute(const dbm_matrix_t *matrix, dbm_matrix_t *redist);
67
68/*******************************************************************************
69 * \brief Looks up a block from given matrics. This routine is thread-safe.
70 * If the block is not found then a null pointer is returned.
71 * \author Ole Schuett
72 ******************************************************************************/
73void dbm_get_block_p(dbm_matrix_t *matrix, const int row, const int col,
74 double **block, int *row_size, int *col_size);
75
76/*******************************************************************************
77 * \brief Adds a block to given matrix. This routine is thread-safe.
78 * If block already exist then it gets overwritten (or summed).
79 * \author Ole Schuett
80 ******************************************************************************/
81void dbm_put_block(dbm_matrix_t *matrix, const int row, const int col,
82 const bool summation, const double *block);
83
84/*******************************************************************************
85 * \brief Remove all blocks from matrix, but does not release underlying memory.
86 * \author Ole Schuett
87 ******************************************************************************/
88void dbm_clear(dbm_matrix_t *matrix);
89
90/*******************************************************************************
91 * \brief Removes all blocks from the matrix whose norm is below the threshold.
92 * Blocks of size zero are always kept.
93 * \author Ole Schuett
94 ******************************************************************************/
95void dbm_filter(dbm_matrix_t *matrix, const double eps);
96
97/*******************************************************************************
98 * \brief Adds list of blocks efficiently. The blocks will be filled with zeros.
99 * This routine must always be called within an OpenMP parallel region.
100 * \author Ole Schuett
101 ******************************************************************************/
102void dbm_reserve_blocks(dbm_matrix_t *matrix, const int nblocks,
103 const int rows[], const int cols[]);
104
105/*******************************************************************************
106 * \brief Multiplies all entries in the given matrix by the given factor alpha.
107 * \author Ole Schuett
108 ******************************************************************************/
109void dbm_scale(dbm_matrix_t *matrix, const double alpha);
110
111/*******************************************************************************
112 * \brief Sets all blocks in the given matrix to zero.
113 * \author Ole Schuett
114 ******************************************************************************/
115void dbm_zero(dbm_matrix_t *matrix);
116
117/*******************************************************************************
118 * \brief Adds matrix_b to matrix_a.
119 * \author Ole Schuett
120 ******************************************************************************/
121void dbm_add(dbm_matrix_t *matrix_a, const dbm_matrix_t *matrix_b);
122
123/*******************************************************************************
124 * \brief Creates an iterator for the blocks of the given matrix.
125 * The iteration order is not stable.
126 * This routine must always be called within an OpenMP parallel region.
127 * \author Ole Schuett
128 ******************************************************************************/
129void dbm_iterator_start(dbm_iterator_t **iter_out, const dbm_matrix_t *matrix);
130
131/*******************************************************************************
132 * \brief Returns number of blocks the iterator will provide to calling thread.
133 * \author Ole Schuett
134 ******************************************************************************/
135int dbm_iterator_num_blocks(const dbm_iterator_t *iter);
136
137/*******************************************************************************
138 * \brief Tests whether the given iterator has any block left.
139 * \author Ole Schuett
140 ******************************************************************************/
141bool dbm_iterator_blocks_left(const dbm_iterator_t *iter);
142
143/*******************************************************************************
144 * \brief Returns the next block from the given iterator.
145 * \author Ole Schuett
146 ******************************************************************************/
147void dbm_iterator_next_block(dbm_iterator_t *iter, int *row, int *col,
148 double **block, int *row_size, int *col_size);
149
150/*******************************************************************************
151 * \brief Releases the given iterator.
152 * \author Ole Schuett
153 ******************************************************************************/
154void dbm_iterator_stop(dbm_iterator_t *iter);
155
156/*******************************************************************************
157 * \brief Computes a checksum of the given matrix.
158 * \author Ole Schuett
159 ******************************************************************************/
160double dbm_checksum(const dbm_matrix_t *matrix);
161
162/*******************************************************************************
163 * \brief Returns the absolute value of the larges element of the entire matrix.
164 * \author Ole Schuett
165 ******************************************************************************/
166double dbm_maxabs(const dbm_matrix_t *matrix);
167
168/*******************************************************************************
169 * \brief Calculates maximum relative difference between matrix_a and matrix_b.
170 * \author Hans Pabst
171 ******************************************************************************/
172double dbm_maxeps(const dbm_matrix_t *matrix_a, const dbm_matrix_t *matrix_b);
173
174/*******************************************************************************
175 * \brief Returns the name of the matrix of the given matrix.
176 * \author Ole Schuett
177 ******************************************************************************/
178const char *dbm_get_name(const dbm_matrix_t *matrix);
179
180/*******************************************************************************
181 * \brief Returns the number of local Non-Zero Elements of the given matrix.
182 * \author Ole Schuett
183 ******************************************************************************/
184int dbm_get_nze(const dbm_matrix_t *matrix);
185
186/*******************************************************************************
187 * \brief Returns the number of local blocks of the given matrix.
188 * \author Ole Schuett
189 ******************************************************************************/
190int dbm_get_num_blocks(const dbm_matrix_t *matrix);
191
192/*******************************************************************************
193 * \brief Returns the row block sizes of the given matrix.
194 * \author Ole Schuett
195 ******************************************************************************/
196void dbm_get_row_sizes(const dbm_matrix_t *matrix, int *nrows,
197 const int **row_sizes);
198
199/*******************************************************************************
200 * \brief Returns the column block sizes of the given matrix.
201 * \author Ole Schuett
202 ******************************************************************************/
203void dbm_get_col_sizes(const dbm_matrix_t *matrix, int *ncols,
204 const int **col_sizes);
205
206/*******************************************************************************
207 * \brief Returns the local row block sizes of the given matrix.
208 * \author Ole Schuett
209 ******************************************************************************/
210void dbm_get_local_rows(const dbm_matrix_t *matrix, int *nlocal_rows,
211 const int **local_rows);
212
213/*******************************************************************************
214 * \brief Returns the local column block sizes of the given matrix.
215 * \author Ole Schuett
216 ******************************************************************************/
217void dbm_get_local_cols(const dbm_matrix_t *matrix, int *nlocal_cols,
218 const int **local_cols);
219
220/*******************************************************************************
221 * \brief Returns the MPI rank on which the given block should be stored.
222 * \author Ole Schuett
223 ******************************************************************************/
224int dbm_get_stored_coordinates(const dbm_matrix_t *matrix, const int row,
225 const int col);
226
227/*******************************************************************************
228 * \brief Returns the distribution of the given matrix.
229 * \author Ole Schuett
230 ******************************************************************************/
231const dbm_distribution_t *dbm_get_distribution(const dbm_matrix_t *matrix);
232
233/*******************************************************************************
234 * \brief Internal routine that returns the number of shards for given matrix.
235 * \author Ole Schuett
236 ******************************************************************************/
237static inline int dbm_get_num_shards(const dbm_matrix_t *matrix) {
238 return matrix->dist->rows.nshards * matrix->dist->cols.nshards;
239}
240
241/*******************************************************************************
242 * \brief Internal routine for getting a block's shard index.
243 * \author Ole Schuett
244 ******************************************************************************/
245static inline int dbm_get_shard_index(const dbm_matrix_t *matrix, const int row,
246 const int col) {
247 const int shard_row = row % matrix->dist->rows.nshards;
248 const int shard_col = col % matrix->dist->cols.nshards;
249 return shard_row * matrix->dist->cols.nshards + shard_col;
250}
251
252#endif
253
254// EOF
dbm_distribution.h
dbm_get_shard_index
static int dbm_get_shard_index(const dbm_matrix_t *matrix, const int row, const int col)
Internal routine for getting a block's shard index.
Definition dbm_matrix.h:245
dbm_get_num_shards
static int dbm_get_num_shards(const dbm_matrix_t *matrix)
Internal routine that returns the number of shards for given matrix.
Definition dbm_matrix.h:237
dbm_get_col_sizes
void dbm_get_col_sizes(const dbm_matrix_t *matrix, int *ncols, const int **col_sizes)
Returns the column block sizes of the given matrix.
Definition dbm_matrix.c:648
dbm_get_row_sizes
void dbm_get_row_sizes(const dbm_matrix_t *matrix, int *nrows, const int **row_sizes)
Returns the row block sizes of the given matrix.
Definition dbm_matrix.c:638
dbm_maxeps
double dbm_maxeps(const dbm_matrix_t *matrix_a, const dbm_matrix_t *matrix_b)
Calculates maximum relative difference between matrix_a and matrix_b.
Definition dbm_matrix.c:566
dbm_shard.h
dbm_dist_1d_t::nshards
int nshards
Definition dbm_distribution.h:24
dbm_distribution_t
Internal struct for storing a two dimensional distribution.
Definition dbm_distribution.h:31
dbm_distribution_t::rows
dbm_dist_1d_t rows
Definition dbm_distribution.h:33
dbm_distribution_t::cols
dbm_dist_1d_t cols
Definition dbm_distribution.h:34
dbm_iterator_t
Internal struct for storing a block iterator.
Definition dbm_matrix.h:34
dbm_iterator_t::next_shard
int next_shard
Definition dbm_matrix.h:37
dbm_iterator_t::matrix
const dbm_matrix_t * matrix
Definition dbm_matrix.h:35
dbm_iterator_t::next_block
int next_block
Definition dbm_matrix.h:36
dbm_matrix_t
Internal struct for storing a matrix.
Definition dbm_matrix.h:19
dbm_matrix_t::row_sizes
int * row_sizes
Definition dbm_matrix.h:24
dbm_matrix_t::name
char * name
Definition dbm_matrix.h:21
dbm_matrix_t::nrows
int nrows
Definition dbm_matrix.h:22
dbm_matrix_t::col_sizes
int * col_sizes
Definition dbm_matrix.h:25
dbm_matrix_t::ncols
int ncols
Definition dbm_matrix.h:23
dbm_matrix_t::shards
dbm_shard_t * shards
Definition dbm_matrix.h:27
dbm_matrix_t::dist
dbm_distribution_t * dist
Definition dbm_matrix.h:20
dbm_shard_t
Internal struct for storing a matrix shard.
Definition dbm_shard.h:30