ALP User Documentation 0.7.0
Algebraic Programming User Documentation
io.hpp
Go to the documentation of this file.
1
2/*
3 * Copyright 2021 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
27#include <type_traits>
28#include <typeinfo>
29
30#ifndef _H_GRB_IO_BASE
31#define _H_GRB_IO_BASE
32
33#include <graphblas/rc.hpp>
34#include <graphblas/phase.hpp>
35#include <graphblas/iomode.hpp>
36#include <graphblas/SynchronizedNonzeroIterator.hpp>
37#include <graphblas/utils/iterators/type_traits.hpp>
38
39#include "matrix.hpp"
40#include "vector.hpp"
41
42#include <assert.h>
43
44
45namespace grb {
46
153 template<
154 typename ElementType, typename Coords,
155 Backend implementation = config::default_backend
156 >
157 uintptr_t getID(
158 const Vector< ElementType, implementation, Coords > &x
159 ) {
160 (void) x;
161#ifndef NDEBUG
162 const bool this_is_an_invalid_default_implementation = false;
163#endif
164 assert( this_is_an_invalid_default_implementation );
165 return static_cast< uintptr_t >(-1);
166 }
167
174 template<
175 typename ElementType, typename RIT, typename CIT, typename NIT,
176 Backend implementation = config::default_backend
177 >
178 uintptr_t getID(
179 const Matrix< ElementType, implementation, RIT, CIT, NIT > &x
180 ) {
181 (void) x;
182#ifndef NDEBUG
183 const bool this_is_an_invalid_default_implementation = false;
184#endif
185 assert( this_is_an_invalid_default_implementation );
186 return static_cast< uintptr_t >(-1);
187 }
188
231 template<
232 typename DataType,
233 Backend backend, typename Coords
234 >
235 size_t size( const Vector< DataType, backend, Coords > &x ) noexcept {
236#ifndef NDEBUG
237 const bool may_not_call_base_size = false;
238#endif
239 (void) x;
240 assert( may_not_call_base_size );
241 return SIZE_MAX;
242 }
243
282 template<
283 typename InputType, Backend backend,
284 typename RIT, typename CIT, typename NIT
285 >
286 size_t nrows(
287 const Matrix< InputType, backend, RIT, CIT, NIT > &A
288 ) noexcept {
289#ifndef NDEBUG
290 const bool may_not_call_base_nrows = false;
291#endif
292 (void) A;
293 assert( may_not_call_base_nrows );
294 return SIZE_MAX;
295 }
296
335 template<
336 typename InputType, Backend backend,
337 typename RIT, typename CIT, typename NIT
338 >
339 size_t ncols(
340 const Matrix< InputType, backend, RIT, CIT, NIT > &A
341 ) noexcept {
342#ifndef NDEBUG
343 const bool may_not_call_base_ncols = false;
344#endif
345 (void) A;
346 assert( may_not_call_base_ncols );
347 return SIZE_MAX;
348 }
349
385 template<
386 typename InputType, Backend backend, typename Coords
387 >
388 size_t capacity( const Vector< InputType, backend, Coords > &x ) noexcept {
389#ifndef NDEBUG
390 const bool should_not_call_base_vector_capacity = false;
391#endif
392 assert( should_not_call_base_vector_capacity );
393 (void) x;
394 return SIZE_MAX;
395 }
396
428 template<
429 typename InputType, Backend backend,
430 typename RIT, typename CIT, typename NIT
431 >
432 size_t capacity(
433 const Matrix< InputType, backend, RIT, CIT, NIT > &A
434 ) noexcept {
435#ifndef NDEBUG
436 const bool should_not_call_base_matrix_capacity = false;
437#endif
438 assert( should_not_call_base_matrix_capacity );
439 (void) A;
440 return SIZE_MAX;
441 }
442
478 template< typename DataType, Backend backend, typename Coords >
479 size_t nnz( const Vector< DataType, backend, Coords > &x ) noexcept {
480#ifndef NDEBUG
481 const bool should_not_call_base_vector_nnz = false;
482#endif
483 (void) x;
484 assert( should_not_call_base_vector_nnz );
485 return SIZE_MAX;
486 }
487
519 template<
520 typename InputType, Backend backend,
521 typename RIT, typename CIT, typename NIT
522 >
523 size_t nnz(
524 const Matrix< InputType, backend, RIT, CIT, NIT > &A
525 ) noexcept {
526#ifndef NDEBUG
527 const bool should_not_call_base_matrix_nnz = false;
528#endif
529 (void) A;
530 assert( should_not_call_base_matrix_nnz );
531 return SIZE_MAX;
532 }
533
573 template< typename DataType, Backend backend, typename Coords >
574 RC clear( Vector< DataType, backend, Coords > &x ) noexcept {
575#ifndef NDEBUG
576 const bool should_not_call_base_vector_clear = false;
577#endif
578 (void) x;
579 assert( should_not_call_base_vector_clear );
580 return UNSUPPORTED;
581 }
582
618 template<
619 typename InputType, Backend backend,
620 typename RIT, typename CIT, typename NIT
621 >
622 RC clear(
623 Matrix< InputType, backend, RIT, CIT, NIT > &A
624 ) noexcept {
625#ifndef NDEBUG
626 const bool should_not_call_base_matrix_clear = false;
627#endif
628 (void) A;
629 assert( should_not_call_base_matrix_clear );
630 return UNSUPPORTED;
631 }
632
699 template<
700 typename InputType,
701 Backend backend, typename Coords
702 >
703 RC resize(
704 Vector< InputType, backend, Coords > &x,
705 const size_t new_nz
706 ) noexcept {
707#ifndef NDEBUG
708 const bool should_not_call_base_vector_resize = false;
709#endif
710 (void) x;
711 (void) new_nz;
712 assert( should_not_call_base_vector_resize );
713 return UNSUPPORTED;
714 }
715
782 template<
783 typename InputType, Backend backend,
784 typename RIT, typename CIT, typename NIT
785 >
786 RC resize(
787 Matrix< InputType, backend, RIT, CIT, NIT > &A, const size_t new_nz
788 ) noexcept {
789#ifndef NDEBUG
790 const bool should_not_call_base_matrix_resize = false;
791#endif
792 (void) A;
793 (void) new_nz;
794 assert( should_not_call_base_matrix_resize );
795 return UNSUPPORTED;
796 }
797
852 template<
853 Descriptor descr = descriptors::no_operation,
854 typename DataType, typename T,
855 typename Coords, Backend backend
856 >
857 RC set(
858 Vector< DataType, backend, Coords > &x, const T val,
859 const Phase &phase = EXECUTE,
860 const typename std::enable_if<
861 !grb::is_object< DataType >::value &&
862 !grb::is_object< T >::value,
863 void >::type * const = nullptr
864 ) noexcept {
865#ifndef NDEBUG
866 const bool should_not_call_base_vector_set = false;
867 assert( should_not_call_base_vector_set );
868#endif
869 (void) x;
870 (void) val;
871 (void) phase;
872 return UNSUPPORTED;
873 }
874
936 template<
937 Descriptor descr = descriptors::no_operation,
938 typename DataType, typename MaskType, typename T,
939 Backend backend, typename Coords
940 >
941 RC set(
942 Vector< DataType, reference, Coords > &x,
943 const Vector< MaskType, backend, Coords > &mask,
944 const T val,
945 const Phase &phase = EXECUTE,
946 const typename std::enable_if<
947 !grb::is_object< DataType >::value && !grb::is_object< T >::value,
948 void >::type * const = nullptr
949 ) {
950#ifndef NDEBUG
951 const bool should_not_call_base_masked_vector_set = false;
952 assert( should_not_call_base_masked_vector_set );
953#endif
954 (void) x;
955 (void) mask;
956 (void) val;
957 (void) phase;
958 return UNSUPPORTED;
959 }
960
993 template<
994 Descriptor descr = descriptors::no_operation,
995 typename OutputType, typename InputType,
996 Backend backend, typename Coords
997 >
998 RC set(
999 Vector< OutputType, backend, Coords > &x,
1000 const Vector< InputType, backend, Coords > &y,
1001 const Phase &phase = EXECUTE
1002 ) {
1003#ifndef NDEBUG
1004 const bool should_not_call_base_vector_set_copy = false;
1005 assert( should_not_call_base_vector_set_copy );
1006#endif
1007 (void) x;
1008 (void) y;
1009 (void) phase;
1010 return UNSUPPORTED;
1011 }
1012
1054 template<
1055 Descriptor descr = descriptors::no_operation,
1056 typename OutputType, typename MaskType, typename InputType,
1057 Backend backend, typename Coords
1058 >
1059 RC set(
1060 Vector< OutputType, backend, Coords > &x,
1061 const Vector< MaskType, backend, Coords > &mask,
1062 const Vector< InputType, backend, Coords > &y,
1063 const Phase &phase = EXECUTE,
1064 const typename std::enable_if< !grb::is_object< OutputType >::value &&
1065 !grb::is_object< MaskType >::value &&
1066 !grb::is_object< InputType >::value,
1067 void >::type * const = nullptr
1068 ) {
1069#ifndef NDEBUG
1070 const bool should_not_call_base_vector_set_copy_masked = false;
1071 assert( should_not_call_base_vector_set_copy_masked );
1072#endif
1073 (void) x;
1074 (void) mask;
1075 (void) y;
1076 (void) phase;
1077 return UNSUPPORTED;
1078 }
1079
1123 template<
1124 Descriptor descr = descriptors::no_operation,
1125 typename DataType, typename T,
1126 Backend backend, typename Coords
1127 >
1128 RC setElement(
1129 Vector< DataType, backend, Coords > &x,
1130 const T val,
1131 const size_t i,
1132 const Phase &phase = EXECUTE,
1133 const typename std::enable_if< !grb::is_object< DataType >::value &&
1134 !grb::is_object< T >::value, void >::type * const = nullptr
1135 ) {
1136#ifndef NDEBUG
1137 const bool should_not_call_base_setElement = false;
1138 assert( should_not_call_base_setElement );
1139#endif
1140 (void) x;
1141 (void) val;
1142 (void) i;
1143 (void) phase;
1144 return UNSUPPORTED;
1145 }
1146
1153 template<
1154 Descriptor descr = descriptors::no_operation,
1155 typename InputType, typename fwd_iterator,
1156 Backend backend, typename Coords
1157 >
1158 RC buildVector(
1159 Vector< InputType, backend, Coords > &x,
1160 fwd_iterator start, const fwd_iterator end,
1161 const IOMode mode
1162 ) {
1163 operators::right_assign< InputType > accum;
1164 return buildVector< descr >( x, accum, start, end, mode );
1165 }
1166
1174 template< Descriptor descr = descriptors::no_operation,
1175 typename InputType,
1176 class Merger = operators::right_assign< InputType >,
1177 typename fwd_iterator1, typename fwd_iterator2,
1178 Backend backend, typename Coords
1179 >
1180 RC buildVector( Vector< InputType, backend, Coords > &x,
1181 fwd_iterator1 ind_start, const fwd_iterator1 ind_end,
1182 fwd_iterator2 val_start, const fwd_iterator2 val_end,
1183 const IOMode mode, const Merger & merger = Merger()
1184 ) {
1185 operators::right_assign< InputType > accum;
1186 return buildVector< descr >( x, accum, ind_start, ind_end, val_start, val_end,
1187 mode, merger );
1188 }
1189
1221 template<
1222 Descriptor descr = descriptors::no_operation,
1223 typename InputType,
1224 class Merger = operators::right_assign< InputType >,
1225 typename fwd_iterator1, typename fwd_iterator2,
1226 Backend backend, typename Coords
1227 >
1228 RC buildVectorUnique(
1229 Vector< InputType, backend, Coords > &x,
1230 fwd_iterator1 ind_start, const fwd_iterator1 ind_end,
1231 fwd_iterator2 val_start, const fwd_iterator2 val_end,
1232 const IOMode mode
1233 ) {
1234 return buildVector< descr | descriptors::no_duplicates >(
1235 x,
1236 ind_start, ind_end,
1237 val_start, val_end,
1238 mode
1239 );
1240 }
1241
1328 template<
1329 Descriptor descr = descriptors::no_operation,
1330 typename InputType,
1331 typename fwd_iterator1 = const size_t * __restrict__,
1332 typename fwd_iterator2 = const size_t * __restrict__,
1333 typename fwd_iterator3 = const InputType * __restrict__,
1334 Backend implementation = config::default_backend
1335 >
1336 RC buildMatrixUnique(
1337 Matrix< InputType, implementation > &A,
1338 fwd_iterator1 I, const fwd_iterator1 I_end,
1339 fwd_iterator2 J, const fwd_iterator2 J_end,
1340 fwd_iterator3 V, const fwd_iterator3 V_end,
1341 const IOMode mode
1342 ) {
1343 // derive synchronized iterator
1344 auto start = internal::makeSynchronized(
1345 I, J, V,
1346 I_end, J_end, V_end
1347 );
1348 const auto end = internal::makeSynchronized(
1349 I_end, J_end, V_end,
1350 I_end, J_end, V_end
1351 );
1352 // defer to other signature
1353 return buildMatrixUnique< descr >( A, start, end, mode );
1354 }
1355
1360 template<
1361 Descriptor descr = descriptors::no_operation,
1362 typename InputType,
1363 typename fwd_iterator1 = const size_t * __restrict__,
1364 typename fwd_iterator2 = const size_t * __restrict__,
1365 typename fwd_iterator3 = const InputType * __restrict__,
1366 Backend implementation = config::default_backend
1367 >
1368 RC buildMatrixUnique(
1369 Matrix< InputType, implementation > &A,
1370 fwd_iterator1 I, fwd_iterator2 J, fwd_iterator3 V,
1371 const size_t nz, const IOMode mode
1372 ) {
1373 return buildMatrixUnique< descr >(
1374 A,
1375 I, I + nz,
1376 J, J + nz,
1377 V, V + nz,
1378 mode
1379 );
1380 }
1381
1386 template<
1387 Descriptor descr = descriptors::no_operation,
1388 typename InputType, typename RIT, typename CIT, typename NIT,
1389 typename fwd_iterator1 = const size_t * __restrict__,
1390 typename fwd_iterator2 = const size_t * __restrict__,
1391 typename length_type = size_t,
1392 Backend implementation = config::default_backend
1393 >
1394 RC buildMatrixUnique(
1395 Matrix< InputType, implementation, RIT, CIT, NIT > &A,
1396 fwd_iterator1 I, fwd_iterator2 J,
1397 const length_type nz, const IOMode mode
1398 ) {
1399 // derive synchronized iterator
1400 auto start = internal::makeSynchronized( I, J, I + nz, J + nz );
1401 const auto end = internal::makeSynchronized(
1402 I + nz, J + nz, I + nz, J + nz );
1403 // defer to other signature
1404 return buildMatrixUnique< descr >( A, start, end, mode );
1405 }
1406
1448 template<
1449 Descriptor descr = descriptors::no_operation,
1450 typename InputType, typename RIT, typename CIT, typename NIT,
1451 typename fwd_iterator,
1452 Backend implementation = config::default_backend
1453 >
1454 RC buildMatrixUnique(
1455 Matrix< InputType, implementation, RIT, CIT, NIT > &A,
1456 fwd_iterator start, const fwd_iterator end,
1457 const IOMode mode
1458 ) {
1459 (void) A;
1460 (void) start;
1461 (void) end;
1462 (void) mode;
1463#ifndef NDEBUG
1464 std::cerr << "Should not call base grb::buildMatrixUnique" << std::endl;
1465 const bool should_not_call_base_buildMatrixUnique = false;
1466 assert( should_not_call_base_buildMatrixUnique );
1467#endif
1468 return PANIC;
1469 }
1470
1517 template< Backend backend = config::default_backend >
1518 RC wait() {
1519#ifndef NDEBUG
1520 const bool should_not_call_base_wait = false;
1521 assert( should_not_call_base_wait );
1522#endif
1523 return UNSUPPORTED;
1524 }
1525
1551 template<
1552 Backend backend, typename InputType, typename Coords,
1553 typename... Args
1554 >
1555 RC wait(
1556 const Vector< InputType, backend, Coords > &x,
1557 const Args &... args
1558 ) {
1559#ifndef NDEBUG
1560 const bool should_not_call_base_vector_wait = false;
1561 assert( should_not_call_base_vector_wait );
1562#endif
1563 (void) x;
1564 return wait( args... );
1565 }
1566
1592 template<
1593 Backend backend,
1594 typename InputType, typename RIT, typename CIT, typename NIT,
1595 typename... Args
1596 >
1597 RC wait(
1598 const Matrix< InputType, backend, RIT, CIT, NIT > &A,
1599 const Args &... args
1600 ) {
1601#ifndef NDEBUG
1602 const bool should_not_call_base_matrix_wait = false;
1603 assert( should_not_call_base_matrix_wait );
1604#endif
1605 (void) A;
1606 return wait( args... );
1607 }
1608
1611} // namespace grb
1612
1613#endif // end _H_GRB_IO_BASE
1614
grb::Matrix
An ALP/GraphBLAS matrix.
Definition: matrix.hpp:71
grb::Vector
A GraphBLAS vector.
Definition: vector.hpp:64
grb::operators::right_assign
This operator discards all left-hand side input and simply copies the right-hand side input to the ou...
Definition: ops.hpp:117
grb::set
RC set(Vector< DataType, backend, Coords > &x, const T val, const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< DataType >::value &&!grb::is_object< T >::value, void >::type *const =nullptr) noexcept
Sets all elements of a vector to the given value.
Definition: io.hpp:857
grb::buildMatrixUnique
RC buildMatrixUnique(Matrix< InputType, implementation > &A, fwd_iterator1 I, const fwd_iterator1 I_end, fwd_iterator2 J, const fwd_iterator2 J_end, fwd_iterator3 V, const fwd_iterator3 V_end, const IOMode mode)
Assigns nonzeroes to the matrix from a coordinate format.
Definition: io.hpp:1336
grb::getID
uintptr_t getID(const Vector< ElementType, implementation, Coords > &x)
Function that returns a unique ID for a given non-empty container.
Definition: io.hpp:157
grb::nnz
size_t nnz(const Vector< DataType, backend, Coords > &x) noexcept
Request the number of nonzeroes in a given vector.
Definition: io.hpp:479
grb::size
size_t size(const Vector< DataType, backend, Coords > &x) noexcept
Request the size of a given vector.
Definition: io.hpp:235
grb::ncols
size_t ncols(const Matrix< InputType, backend, RIT, CIT, NIT > &A) noexcept
Requests the column size of a given matrix.
Definition: io.hpp:339
grb::capacity
size_t capacity(const Vector< InputType, backend, Coords > &x) noexcept
Queries the capacity of the given ALP/GraphBLAS container.
Definition: io.hpp:388
grb::buildVectorUnique
RC buildVectorUnique(Vector< InputType, backend, Coords > &x, fwd_iterator1 ind_start, const fwd_iterator1 ind_end, fwd_iterator2 val_start, const fwd_iterator2 val_end, const IOMode mode)
Ingests a set of nonzeroes into a given vector x.
Definition: io.hpp:1228
grb::buildVector
RC buildVector(Vector< InputType, backend, Coords > &x, fwd_iterator start, const fwd_iterator end, const IOMode mode)
Constructs a dense vector from a container of exactly grb::size(x) elements.
Definition: io.hpp:1158
grb::setElement
RC setElement(Vector< DataType, backend, Coords > &x, const T val, const size_t i, const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< DataType >::value &&!grb::is_object< T >::value, void >::type *const =nullptr)
Sets the element of a given vector at a given position to a given value.
Definition: io.hpp:1128
grb::nrows
size_t nrows(const Matrix< InputType, backend, RIT, CIT, NIT > &A) noexcept
Requests the row size of a given matrix.
Definition: io.hpp:286
grb::wait
RC wait()
Depending on the backend, ALP/GraphBLAS primitives may be non-blocking, meaning that the operation im...
Definition: io.hpp:1518
grb::resize
RC resize(Vector< InputType, backend, Coords > &x, const size_t new_nz) noexcept
Resizes the nonzero capacity of this vector.
Definition: io.hpp:703
grb::clear
RC clear(Vector< DataType, backend, Coords > &x) noexcept
Clears a given vector of all nonzeroes.
Definition: io.hpp:574
grb::Backend
Backend
A collection of all backends.
Definition: backends.hpp:46
iomode.hpp
Defines the various I/O modes a user could employ with ALP data ingestion or extraction.
matrix.hpp
Specifies the ALP/GraphBLAS matrix container.
grb::descriptors::no_operation
static constexpr Descriptor no_operation
Indicates no additional pre- or post-processing on any of the GraphBLAS function arguments.
Definition: descriptors.hpp:63
grb
The ALP/GraphBLAS namespace.
Definition: graphblas.hpp:452
grb::IOMode
IOMode
The GraphBLAS input and output functionalities can either be used in a sequential or parallel fashion...
Definition: iomode.hpp:67
grb::RC
RC
Return codes of ALP primitives.
Definition: rc.hpp:47
grb::PANIC
@ PANIC
Generic fatal error code.
Definition: rc.hpp:68
grb::UNSUPPORTED
@ UNSUPPORTED
Indicates that the execution of the requested primitive with the given arguments is not supported by ...
Definition: rc.hpp:129
grb::Descriptor
unsigned int Descriptor
Descriptors indicate pre- or post-processing for some or all of the arguments to an ALP/GraphBLAS cal...
Definition: descriptors.hpp:54
grb::Phase
Phase
Primitives with sparse ALP/GraphBLAS output containers may run into the issue where an appropriate gr...
Definition: phase.hpp:152
grb::EXECUTE
@ EXECUTE
Speculatively assumes that the output container of the requested operation has enough capacity to com...
Definition: phase.hpp:257
phase.hpp
Defines the various phases an ALP/GraphBLAS primitive may be executed with.
rc.hpp
Defines the ALP error codes.
grb::is_object
Used to inspect whether a given type is an ALP/GraphBLAS object.
Definition: type_traits.hpp:130
vector.hpp
Specifies the ALP/GraphBLAS vector container.
Generated on Fri Apr 7 2023 00:29:11 for ALP User Documentation by doxygen 1.9.3