ALP User Documentation 0.7.alpha
Algebraic Programming User Documentation
Loading...
Searching...
No Matches
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( Vector< DataType, backend, Coords > &x,
1129 const T val,
1130 const size_t i,
1131 const Phase &phase = EXECUTE,
1132 const typename std::enable_if< !grb::is_object< DataType >::value &&
1133 !grb::is_object< T >::value, void >::type * const = nullptr
1134 ) {
1135#ifndef NDEBUG
1136 const bool should_not_call_base_setElement = false;
1137 assert( should_not_call_base_setElement );
1138#endif
1139 (void) x;
1140 (void) val;
1141 (void) i;
1142 (void) phase;
1143 return UNSUPPORTED;
1144 }
1145
1152 template<
1153 Descriptor descr = descriptors::no_operation,
1154 typename InputType, typename fwd_iterator,
1155 Backend backend, typename Coords
1156 >
1157 RC buildVector(
1158 Vector< InputType, backend, Coords > &x,
1159 fwd_iterator start, const fwd_iterator end,
1160 const IOMode mode
1161 ) {
1162 operators::right_assign< InputType > accum;
1163 return buildVector< descr >( x, accum, start, end, mode );
1164 }
1165
1173 template< Descriptor descr = descriptors::no_operation,
1174 typename InputType,
1175 class Merger = operators::right_assign< InputType >,
1176 typename fwd_iterator1, typename fwd_iterator2,
1177 Backend backend, typename Coords
1178 >
1179 RC buildVector( Vector< InputType, backend, Coords > &x,
1180 fwd_iterator1 ind_start, const fwd_iterator1 ind_end,
1181 fwd_iterator2 val_start, const fwd_iterator2 val_end,
1182 const IOMode mode, const Merger & merger = Merger()
1183 ) {
1184 operators::right_assign< InputType > accum;
1185 return buildVector< descr >( x, accum, ind_start, ind_end, val_start, val_end,
1186 mode, merger );
1187 }
1188
1220 template<
1221 Descriptor descr = descriptors::no_operation,
1222 typename InputType,
1223 class Merger = operators::right_assign< InputType >,
1224 typename fwd_iterator1, typename fwd_iterator2,
1225 Backend backend, typename Coords
1226 >
1227 RC buildVectorUnique(
1228 Vector< InputType, backend, Coords > &x,
1229 fwd_iterator1 ind_start, const fwd_iterator1 ind_end,
1230 fwd_iterator2 val_start, const fwd_iterator2 val_end,
1231 const IOMode mode
1232 ) {
1233 return buildVector< descr | descriptors::no_duplicates >(
1234 x,
1235 ind_start, ind_end,
1236 val_start, val_end,
1237 mode
1238 );
1239 }
1240
1327 template<
1328 Descriptor descr = descriptors::no_operation,
1329 typename InputType,
1330 typename fwd_iterator1 = const size_t * __restrict__,
1331 typename fwd_iterator2 = const size_t * __restrict__,
1332 typename fwd_iterator3 = const InputType * __restrict__,
1333 Backend implementation = config::default_backend
1334 >
1335 RC buildMatrixUnique(
1336 Matrix< InputType, implementation > &A,
1337 fwd_iterator1 I, const fwd_iterator1 I_end,
1338 fwd_iterator2 J, const fwd_iterator2 J_end,
1339 fwd_iterator3 V, const fwd_iterator3 V_end,
1340 const IOMode mode
1341 ) {
1342 // derive synchronized iterator
1343 auto start = internal::makeSynchronized(
1344 I, J, V,
1345 I_end, J_end, V_end
1346 );
1347 const auto end = internal::makeSynchronized(
1348 I_end, J_end, V_end,
1349 I_end, J_end, V_end
1350 );
1351 // defer to other signature
1352 return buildMatrixUnique< descr >( A, start, end, mode );
1353 }
1354
1359 template<
1360 Descriptor descr = descriptors::no_operation,
1361 typename InputType,
1362 typename fwd_iterator1 = const size_t * __restrict__,
1363 typename fwd_iterator2 = const size_t * __restrict__,
1364 typename fwd_iterator3 = const InputType * __restrict__,
1365 Backend implementation = config::default_backend
1366 >
1367 RC buildMatrixUnique(
1368 Matrix< InputType, implementation > &A,
1369 fwd_iterator1 I, fwd_iterator2 J, fwd_iterator3 V,
1370 const size_t nz, const IOMode mode
1371 ) {
1372 return buildMatrixUnique< descr >(
1373 A,
1374 I, I + nz,
1375 J, J + nz,
1376 V, V + nz,
1377 mode
1378 );
1379 }
1380
1385 template<
1386 Descriptor descr = descriptors::no_operation,
1387 typename InputType, typename RIT, typename CIT, typename NIT,
1388 typename fwd_iterator1 = const size_t * __restrict__,
1389 typename fwd_iterator2 = const size_t * __restrict__,
1390 typename length_type = size_t,
1391 Backend implementation = config::default_backend
1392 >
1393 RC buildMatrixUnique(
1394 Matrix< InputType, implementation, RIT, CIT, NIT > &A,
1395 fwd_iterator1 I, fwd_iterator2 J,
1396 const length_type nz, const IOMode mode
1397 ) {
1398 // derive synchronized iterator
1399 auto start = internal::makeSynchronized( I, J, I + nz, J + nz );
1400 const auto end = internal::makeSynchronized(
1401 I + nz, J + nz, I + nz, J + nz );
1402 // defer to other signature
1403 return buildMatrixUnique< descr >( A, start, end, mode );
1404 }
1405
1447 template<
1448 Descriptor descr = descriptors::no_operation,
1449 typename InputType, typename RIT, typename CIT, typename NIT,
1450 typename fwd_iterator,
1451 Backend implementation = config::default_backend
1452 >
1453 RC buildMatrixUnique(
1454 Matrix< InputType, implementation, RIT, CIT, NIT > &A,
1455 fwd_iterator start, const fwd_iterator end,
1456 const IOMode mode
1457 ) {
1458 (void) A;
1459 (void) start;
1460 (void) end;
1461 (void) mode;
1462#ifndef NDEBUG
1463 std::cerr << "Should not call base grb::buildMatrixUnique" << std::endl;
1464 const bool should_not_call_base_buildMatrixUnique = false;
1465 assert( should_not_call_base_buildMatrixUnique );
1466#endif
1467 return PANIC;
1468 }
1469
1516 template< Backend backend = config::default_backend >
1517 RC wait() {
1518#ifndef NDEBUG
1519 const bool should_not_call_base_wait = false;
1520 assert( should_not_call_base_wait );
1521#endif
1522 return UNSUPPORTED;
1523 }
1524
1550 template<
1551 Backend backend, typename InputType, typename Coords,
1552 typename... Args
1553 >
1554 RC wait(
1555 const Vector< InputType, backend, Coords > &x,
1556 const Args &... args
1557 ) {
1558#ifndef NDEBUG
1559 const bool should_not_call_base_vector_wait = false;
1560 assert( should_not_call_base_vector_wait );
1561#endif
1562 (void) x;
1563 return wait( args... );
1564 }
1565
1591 template<
1592 Backend backend,
1593 typename InputType, typename RIT, typename CIT, typename NIT,
1594 typename... Args
1595 >
1596 RC wait(
1597 const Matrix< InputType, backend, RIT, CIT, NIT > &A,
1598 const Args &... args
1599 ) {
1600#ifndef NDEBUG
1601 const bool should_not_call_base_matrix_wait = false;
1602 assert( should_not_call_base_matrix_wait );
1603#endif
1604 (void) A;
1605 return wait( args... );
1606 }
1607
1610} // namespace grb
1611
1612#endif // end _H_GRB_IO_BASE
1613
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:116
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:1227
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:1157
grb::wait
RC wait()
Depending on the backend, ALP/GraphBLAS primitives may be non-blocking, meaning that the operation im...
Definition: io.hpp:1517
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::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::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::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:1335
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::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::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::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::clear
RC clear(Vector< DataType, backend, Coords > &x) noexcept
Clears a given vector of all nonzeroes.
Definition: io.hpp:574
grb::size
size_t size(const Vector< DataType, backend, Coords > &x) noexcept
Request the size of a given vector.
Definition: io.hpp:235
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:450
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 Thu Jan 26 2023 17:44:42 for ALP User Documentation by doxygen 1.9.6