matrix.hpp 13.2 KB
Newer Older
1
// Software License for MTL
2
//
3
4
5
6
7
// Copyright (c) 2007 The Trustees of Indiana University.
//               2008 Dresden University of Technology and the Trustees of Indiana University.
//               2010 SimuNova UG (haftungsbeschränkt), www.simunova.com.
// All rights reserved.
// Authors: Peter Gottschling and Andrew Lumsdaine
8
//
9
// This file is part of the Matrix Template Library
10
//
11
12
13
14
15
16
17
18
19
20
// See also license.mtl.txt in the distribution.

#ifndef MTL_MATRIX_CONCEPT_INCLUDE
#define MTL_MATRIX_CONCEPT_INCLUDE

#include <boost/numeric/mtl/mtl_fwd.hpp>
#include <boost/numeric/mtl/concept/collection.hpp>

#ifdef __GXX_CONCEPTS__
#  include <concepts>
21
#else
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
#  include <boost/numeric/linear_algebra/pseudo_concept.hpp>
#endif

namespace mtl {

/** @addtogroup Concepts
 *  @{
 */

#ifdef __GXX_CONCEPTS__
    concept Matrix<typename T>
      : AlgebraicCollection<T>
    {
	const_reference T::operator() (size_type row, size_type col) const;

	size_type nnz(T);

	// A[r][c] equivalent to A(r, c)
    };
#else
    /// Concept Matrix
    /**
        \par Refinement of:
	- AlgebraicCollection < T >
	\par Notation:
	- X is a type that models Matrix
	- A is an object of type X
	- r, c are objects of size_type
	\par Valid expressions:
51
	- Element access: \n A(r, c) \n Return Type: const_reference
52
53
54
55
56
57
58
59
60
61
62
63
	  \n Semantics: Element in row \p r and column \p c
	- Element access: \n A[r][c] \n Equivalent to A(r, c)
	\par Models:
	- dense2D
	- morton_dense
	- compressed2D
	\note
	-# The access via A[r][c] is supposed to be implemented by means of A(r, c) (typically via CRTP and proxies).
	  If it would become (extremely) important to support 2D C arrays, it might be necessary to drop the requirement
	  of element access by A(r, c).
	-# The name const_reference does not imply that the return type is necessarily referrable. For instance compressed2D
	   returns value_type.
64
     */
65
66
67
68
69
70
71
72
73
    template <typename T>
    struct Matrix
	: public AlgebraicCollection<T>
    {
	/// Element access
	const_reference T::operator() (size_type row, size_type col) const;
    };
#endif

74

75
76
77
78
79
80
81
82

#ifdef __GXX_CONCEPTS__
    concept MatrixInserter<typename T>
    {
	typename matrix_type;
	// typename T::matrix_type;

	requires Matrix<matrix_type>;
83

84
85
	typename proxy_type;
	proxy_type operator() (Matrix<matrix_type>::size_type row, Matrix<matrix_type>::size_type col);
86

87
88
89
90
	T operator<< (proxy_type, Matrix<matrix_type>::value_type>);
    };
#else
    /// Concept MatrixInserter: classes that enable efficient insertion into matrices, esp. compressed sparse.
91
    /**
92
93
94
95
96
97
98
99
100
	Used to fill non-mutable matrices like compressed2D. Matrix inserters might be parametrizable with
	update functor. This allow to perform different operations when entry already exist, e.g. overwriting,
	incrementing, minimum, ... The most important updates are certainly overwrite and increment (add).

	\par Associated types
	- matrix_type

	\par Requires:
	- Matrix<matrix_type>
101

102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
	\par Notation:
	- X is a type that models MatrixInserter
	- A is an object of type X
	- r, c are objects of type Matrix<matrix_type>::size_type
	- v is an object of type Matrix<matrix_type>::value_type

	\par Valid expressions:
	- Insertion with shift operator: \n
	   A(r, c) << v \n
	   Return type: T
	\par Models:
	- mtl::matrix::inserter < T >
	\note
	-# Used in concept InsertableMatrix
     */
    template <typename T>
    struct MatrixInserter
    {
	/// Type  of matrix into which is inserted
	typedef associated_type matrix_type;

	/// Return type of element access; only proxy
	typedef associated_type  proxy_type;
	/// Element access; returns a proxy that handles insertion
	proxy_type operator() (Matrix<matrix_type>::size_type row, Matrix<matrix_type>::size_type col);
    };
#endif

#ifdef __GXX_CONCEPTS__
    concept InsertableMatrix<typename T>
      : Matrix<T>
    {
	requires MatrixInserter<mtl::matrix::inserter<T> >;
    };
#else
    /// Concept InsertableMatrix: %matrix that can be filled by means of inserter
138
    /**
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
	\par Requires:
	- MatrixInserter < mtl::matrix::inserter< T > >
	\par Models:
	- dense2D
	- morton_dense
	- compressed2D
	\note
	-# All matrices in MTL model this concept in order and all future matrices are supposed to.
    */
    template <typename T>
    struct InsertableMatrix
      : Matrix < T >
    {};
#endif


#ifdef __GXX_CONCEPTS__
    concept MutableMatrix<typename T>
      : Matrix<T>,
	MutableCollection<T>
    {
	reference T::operator() (size_type row, size_type col);

	// A[r][c] equivalent to A(r, c)
    };
#else
    /// Concept MutableMatrix
    /**
        \par Refinement of:
	- Matrix < T >
	- MutableCollection < T >
	\par Notation:
	- X is a type that models MutableMatrix
	- A is an object of type X
	- r, c are objects of size_type
	\par Valid expressions:
175
	- Element access: \n A(r, c) \n Return Type: reference
176
177
178
179
180
181
182
183
184
	  \n Semantics: Element in row \p r and column \p c
	- Element access: \n A[r][c] \n Equivalent to A(r, c)
	\par Models:
	- dense2D
	- morton_dense
	\note
	-# The access via A[r][c] is supposed to be implemented by means of A(r, c) (typically via CRTP and proxies).
	  If it would become (extremely) important to support 2D C arrays, it might be necessary to drop the requirement
	  of element access by A(r, c).
185
     */
186
187
188
189
190
191
192
193
194
195
    template <typename T>
    struct MutableMatrix
	: public Matrix<T>,
	  public MutableCollection<T>
    {
	/// Element access (in addition to const access)
	reference T::operator() (size_type row, size_type col);
    };
#endif

196

197
198
199
200
201
202
203
204
205
206
207
#ifdef __GXX_CONCEPTS__
    concept ConstantSizeMatrix<typename T>
      : Matrix<T>,
	ConstantSizeAlgebraicCollection<T>
    {};
#else
    /// Concept ConstantSizeMatrix
    /**
        \par Refinement of:
	- Matrix < T >
	- ConstantSizeAlgebraicCollection < T >
208
     */
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
    template <typename T>
    struct ConstantSizeMatrix
      : public Matrix<T>,
	public ConstantSizeAlgebraicCollection<T>
    {};
#endif


#ifdef __GXX_CONCEPTS__
    concept ResizeableMatrix<typename T>
      : Matrix<T>
    {
	void T::resize(size_type r, size_type c);
    };
#else
    /// Concept ResizeableMatrix
    /**
        \par Refinement of:
	- Matrix < T >
228
     */
229
230
231
232
233
234
235
236
237
238
239
240
241
242
    template <typename T>
    struct ResizeableMatrix
      : public Matrix<T>
    {
	/// Resize function
	/** If new memory should be allocated only if total size changes */
	void resize(size_type r, size_type c);
    };
#endif


#ifdef __GXX_CONCEPTS__
    concept RowTraversableMatrix<typename M>
      : Matrix<M>,
243
        TraversableCollection<mtl::tag::row, M>
244
245
246
247
248
249
    {};
#else
    /// Concept RowTraversableMatrix: provides begin and end cursor to traverse rows
    /**
        \par Refinement of:
	- Matrix < M >
250
251
	- TraversableCollection <mtl::tag::row, M>
     */
252
253
254
255
256
257
258
    template <typename M>
    struct RowTraversableMatrix
      : public Matrix<M>,
        public TraversableCollection<mtl::tag::row, M>
    {};
#endif

259

260
261
262
#ifdef __GXX_CONCEPTS__
    concept ColumnTraversableMatrix<typename M>
      : Matrix<M>,
263
        TraversableCollection<mtl::tag::col, M>
264
265
266
267
268
269
    {};
#else
    /// Concept ColumnTraversableMatrix: provides begin and end cursor to traverse columns
    /**
        \par Refinement of:
	- Matrix < M >
270
271
	- TraversableCollection <mtl::tag::col, M>
     */
272
273
274
275
276
277
278
279
280
281
282
    template <typename M>
    struct ColumnTraversableMatrix
      : public Matrix<M>,
        public TraversableCollection<mtl::tag::col, M>
    {};
#endif


#ifdef __GXX_CONCEPTS__
    concept MajorTraversableMatrix<typename M>
      : Matrix<M>,
283
        TraversableCollection<mtl::tag::major, M>
284
285
286
287
288
289
290
291
292
    {};
#else
    /// Concept MajorTraversableMatrix: traversable on major dimension
    /**
        Concept for matrices that are traversable along the major dimension, i.e.
	traversing the rows of a row-major matrix and the columns of a column-major matrices.
	The cursors begin and end are provided.
        \par Refinement of:
	- Matrix < M >
293
	- TraversableCollection <mtl::tag::major, M>
294
295
	\note
	-# This traversal corresponds to the iterator design in MTL 2.
296
     */
297
298
299
300
301
302
    template <typename M>
    struct MajorTraversableMatrix
      : public Matrix<M>,
        public TraversableCollection<mtl::tag::major, M>
    {};
#endif
303

304
305
306
307

#ifdef __GXX_CONCEPTS__
    concept MinorTraversableMatrix<typename M>
      : Matrix<M>,
308
        TraversableCollection<mtl::tag::minor, M>
309
310
311
312
313
314
315
316
317
    {};
#else
    /// Concept MinorTraversableMatrix: traversable on minor dimension
    /**
        Concept for matrices that are traversable along the minor dimension, i.e.
	traversing the columns of a row-major matrix and the rows of a column-major matrices.
	The cursors begin and end are provided.
        \par Refinement of:
	- Matrix < M >
318
	- TraversableCollection <mtl::tag::minor, M>
319
320
	\note
	-# This traversal corresponds to the iterator design in MTL 2.
321
     */
322
323
324
325
326
327
    template <typename M>
    struct MinorTraversableMatrix
      : public Matrix<M>,
        public TraversableCollection<mtl::tag::minor, M>
    {};
#endif
328

329
330
331
332

#ifdef __GXX_CONCEPTS__
    concept AllTraversableMatrix<typename M>
      : Matrix<M>,
333
        TraversableCollection<mtl::tag::all, M>
334
335
336
337
338
339
340
341
342
    {};
#else
    /// Concept AllTraversableMatrix: provides traversion over all elements
    /**
        All elements of a matrix are traversed, including structural zeros. Can be used, e.g.,
	for printing.
	The cursors begin and end are provided.
        \par Refinement of:
	- Matrix < M >
343
	- TraversableCollection <mtl::tag::all, M>
344
345
	\note
	-# For dense matrices the concept is equivalent to NonZeroTraversableMatrix.
346
     */
347
348
349
350
351
352
    template <typename M>
    struct AllTraversableMatrix
      : public Matrix<M>,
        public TraversableCollection<mtl::tag::all, M>
    {};
#endif
353

354
355
356
357

#ifdef __GXX_CONCEPTS__
    concept NonZeroTraversableMatrix<typename M>
      : Matrix<M>,
358
        TraversableCollection<mtl::tag::nz, M>
359
360
361
362
363
364
365
366
367
    {};
#else
    /// Concept NonZeroTraversableMatrix: provides traversion over all structural non-zeros
    /**
        All structural non-zero elements of a matrix are traversed. Can be used, e.g.,
	for copying.
	The cursors begin and end are provided.
        \par Refinement of:
	- Matrix < M >
368
	- TraversableCollection <mtl::tag::all, M>
369
370
	\note
	-# For dense matrices the concept is equivalent to AllTraversableMatrix.
371
     */
372
373
374
375
376
377
    template <typename M>
    struct AllTraversableMatrix
      : public Matrix<M>,
        public TraversableCollection<mtl::tag::all, M>
    {};
#endif
378

379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394

#ifdef __GXX_CONCEPTS__
    concept AllTraversableSubMatrix<typename Tag, typename M>
      : Matrix<M>,
        TraversableCollection<Tag, M>,
	TraversableCollection<mtl::tag::all, TraversableCollection<Tag, M>::result_type>
    {};
#else
    /// Concept AllTraversableSubMatrix: provides traversion of rows, columns of matrices
    /**
        All elements of a row or a column, according to the Tag, are traversed.
	The cursors begin and end are provided.
        \par Refinement of:
	- Matrix < M >
        - TraversableCollection<Tag, M>,
	- TraversableCollection<mtl::tag::all, TraversableCollection<Tag, M>::result_type>
395
     */
396
397
398
399
400
401
402
    template <typename Tag, typename M>
    struct AllTraversableMatrix
      : public Matrix<M>,
        public TraversableCollection<Tag, M>,
	public TraversableCollection<mtl::tag::all, TraversableCollection<Tag, M>::result_type>
    {};
#endif
403
404


405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420

#ifdef __GXX_CONCEPTS__
    concept NonZeroTraversableSubMatrix<typename Tag, typename M>
      : Matrix<M>,
        TraversableCollection<Tag, M>,
	TraversableCollection<mtl::tag::nz, TraversableCollection<Tag, M>::result_type>
    {};
#else
    /// Concept NonZeroTraversableSubMatrix: provides traversion of non-zero in rows or columns of matrices
    /**
        All structural non-zero elements of a row or a column, according to the Tag, are traversed.
	The cursors begin and end are provided.
        \par Refinement of:
	- Matrix < M >
        - TraversableCollection<Tag, M>,
	- TraversableCollection<mtl::tag::nz, TraversableCollection<Tag, M>::result_type>
421
     */
422
423
424
425
426
427
428
    template <typename Tag, typename M>
    struct NonZeroTraversableSubMatrix
      : public Matrix<M>,
        public TraversableCollection<Tag, M>,
	public TraversableCollection<mtl::tag::nz, TraversableCollection<Tag, M>::result_type>
    {};
#endif
429

430
431
432
433
434
435
436
437
438
439
440
441

#ifdef __GXX_CONCEPTS__
    concept IteratableSubMatrix<typename Tag, typename ITag, typename M>
      : Matrix<M>,
        TraversableCollection<Tag, M>,
	TraversableCollection<ITag, TraversableCollection<Tag, M>::result_type>
    {};
#else
    /// Concept IteratableSubMatrix: provides iteration over elements within rows or columns of matrices
    /**
        This concepts actually combines four sub-concepts. The iteration can be either performed over
	all elements or only over structural non-zero elements whereby the iterator can be a const-iterator
442
	or a mutable iterator. These four combinations are specified by the tags mtl::tag::iter::all,
443
444
445
446
447
448
449
	mtl::tag::iter::nz, mtl::tag::const_iter::all,  and
	mtl::tag::const_iter::nz for ITag. The template parameter Tag can be mtl::tag::major or mtl::tag::column.
	The cursors begin and end are provided.
        \par Refinement of:
	- Matrix < M >
        - TraversableCollection<Tag, M>,
	- TraversableCollection<ITag, TraversableCollection<Tag, M>::result_type>
450
     */
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
    template <typename Tag, typename ITag, typename M>
    struct IteratableSubMatrix
      : public Matrix<M>,
        public TraversableCollection<Tag, M>,
	public TraversableCollection<ITag, TraversableCollection<Tag, M>::result_type>
    {};
#endif






/*@}*/ // end of group Concepts

} // namespace mtl

#endif // MTL_MATRIX_CONCEPT_INCLUDE