From 9f8df0d92160347d7f269c054d033f9c0453ab64 Mon Sep 17 00:00:00 2001 From: rainmaker6 Date: Thu, 4 Nov 2021 10:01:48 +0530 Subject: [PATCH 1/2] Added CI for asciidoc documentation compilation --- .github/workflows/documentation.yml | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 .github/workflows/documentation.yml diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 000000000..ebbb2fb3d --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,21 @@ +name: documentation +'on': + push: + paths: + - doc/** + pull_request: + paths: + - doc/** +jobs: + asciidoc: + runs-on: ubuntu-latest + name: asciidoc-documentation + steps: + - uses: actions/checkout@v2 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: 2.7 + - uses: reitzig/actions-asciidoctor@v2.0.0 + with: + version: 2.0.10 + - run: asciidoctor doc/ublas.adoc From 4f96fdd599d3d21c6e089b6821c737e15c0f7eff Mon Sep 17 00:00:00 2001 From: Shikhar Vashistha Date: Sat, 18 Dec 2021 07:13:11 +0000 Subject: [PATCH 2/2] Improved Index, Introduced syntax hilighting, Aggregrated contributors List at the end, Added tutorial & Improved formatting --- doc/ublas.adoc | 64 ++------ doc/ublas/banded.adoc | 13 +- doc/ublas/blas.adoc | 12 +- doc/ublas/bounded_array.adoc | 15 +- doc/ublas/container_concept.adoc | 14 +- doc/ublas/contributors.adoc | 30 ++++ doc/ublas/expression_concept.adoc | 9 -- doc/ublas/hermitian.adoc | 11 -- doc/ublas/index.adoc | 145 ++---------------- doc/ublas/iterator_concept.adoc | 9 -- doc/ublas/matrix-index.adoc | 36 +++++ doc/ublas/matrix.adoc | 15 +- doc/ublas/matrix_expression.adoc | 12 +- doc/ublas/matrix_proxy.adoc | 9 -- doc/ublas/matrix_sparse.adoc | 13 +- doc/ublas/misc.adoc | 46 ++++++ doc/ublas/operations_overview.adoc | 26 +--- doc/ublas/options.adoc | 12 -- doc/ublas/overview.adoc | 13 +- doc/ublas/products.adoc | 29 ++-- doc/ublas/range.adoc | 12 +- doc/ublas/release.adoc | 21 +++ doc/ublas/release_notes.adoc | 15 +- doc/ublas/storage_concept.adoc | 12 -- doc/ublas/storage_sparse.adoc | 9 -- doc/ublas/symmetric.adoc | 13 +- doc/ublas/tensor-index.adoc | 31 ++++ doc/ublas/tensor.adoc | 17 +-- doc/ublas/tensor/extents.adoc | 10 +- doc/ublas/tensor/strides.adoc | 19 +-- doc/ublas/tensor/tensor_expression.adoc | 11 -- doc/ublas/tensor/tensor_index.adoc | 13 +- doc/ublas/triangular.adoc | 11 -- doc/ublas/tutorial.adoc | 190 ++++++++++++++++++++++++ doc/ublas/types_overview.adoc | 11 -- doc/ublas/unbounded_array.adoc | 14 +- doc/ublas/vector-index.adoc | 29 ++++ doc/ublas/vector.adoc | 13 +- doc/ublas/vector_expression.adoc | 13 +- doc/ublas/vector_proxy.adoc | 11 +- doc/ublas/vector_sparse.adoc | 9 -- 41 files changed, 456 insertions(+), 561 deletions(-) create mode 100644 doc/ublas/contributors.adoc create mode 100644 doc/ublas/matrix-index.adoc create mode 100644 doc/ublas/misc.adoc create mode 100644 doc/ublas/release.adoc create mode 100644 doc/ublas/tensor-index.adoc create mode 100644 doc/ublas/tutorial.adoc create mode 100644 doc/ublas/vector-index.adoc diff --git a/doc/ublas.adoc b/doc/ublas.adoc index 94dac0c92..ba7150cfd 100644 --- a/doc/ublas.adoc +++ b/doc/ublas.adoc @@ -5,74 +5,34 @@ Distributed under the Boost Software License, Version 1.0. (http://www.boost.org/LICENSE_1_0.txt) //// -# Boost.Ublas: The Boost Ublas Library +# Boost.uBlas: The Boost uBlas Library :toc: left :toclevels: 2 :idprefix: :listing-caption: Code Example :docinfo: private-footer +:source-highlighter: rouge +:source-language: c++ :leveloffset: +1 -include::ublas/overview.adoc[] - include::ublas/index.adoc[] -include::ublas/vector.adoc[] - -include::ublas/vector_sparse.adoc[] - -include::ublas/vector_proxy.adoc[] - -include::ublas/vector_expression.adoc[] - -include::ublas/matrix.adoc[] - -include::ublas/triangular.adoc[] - -include::ublas/symmetric.adoc[] - -include::ublas/hermitian.adoc[] - -include::ublas/banded.adoc[] - -include::ublas/matrix_sparse.adoc[] - -include::ublas/matrix_proxy.adoc[] - -include::ublas/matrix_expression.adoc[] - -include::ublas/tensor.adoc[] - -include::ublas/tensor/tensor_expression.adoc[] - -include::ublas/unbounded_array.adoc[] - -include::ublas/bounded_array.adoc[] - -include::ublas/range.adoc[] - -include::ublas/tensor/extents.adoc[] - -include::ublas/tensor/strides.adoc[] - -include::ublas/tensor/tensor_expression.adoc[] - -include::ublas/tensor/tensor_index.adoc[] +include::ublas/overview.adoc[] -include::ublas/storage_sparse.adoc[] +include::ublas/vector-index.adoc[] -include::ublas/products.adoc[] +include::ublas/matrix-index.adoc[] -include::ublas/blas.adoc[] +include::ublas/tensor-index.adoc[] -include::ublas/container_concept.adoc[] +include::ublas/misc.adoc[] -include::ublas/expression_concept.adoc[] +include::ublas/tutorial.adoc[] -include::ublas/storage_concept.adoc[] +include::ublas/release.adoc[] -include::ublas/iterator_concept.adoc[] +include::ublas/contributors.adoc[] :leveloffset: -1 @@ -81,6 +41,6 @@ include::ublas/iterator_concept.adoc[] This documentation is -* Copyright 2021 Shikhar Vashistha +* Copyright 2021 link:https://github.com/shikharvashistha[Shikhar Vashistha] and is distributed under the http://www.boost.org/LICENSE_1_0.txt[Boost Software License, Version 1.0]. diff --git a/doc/ublas/banded.adoc b/doc/ublas/banded.adoc index a48e003e1..6456969a5 100644 --- a/doc/ublas/banded.adoc +++ b/doc/ublas/banded.adoc @@ -1,8 +1,5 @@ == Banded Matrix -[[toc]] - -=== [#banded_matrix]#Banded Matrix# ==== Description @@ -383,12 +380,4 @@ to the beginning of the reversed `banded_adaptor`. |`reverse_iterator2 rend2 ()` |Returns a `reverse_iterator2` pointing to the end of the reversed `banded_adaptor`. -|=== - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt). \ No newline at end of file +|=== \ No newline at end of file diff --git a/doc/ublas/blas.adoc b/doc/ublas/blas.adoc index 13b54bc2b..81763735f 100644 --- a/doc/ublas/blas.adoc +++ b/doc/ublas/blas.adoc @@ -1,6 +1,5 @@ == Level 3 BLAS -[[toc]] ''''' @@ -218,13 +217,4 @@ _m3^H^_) + (_m3_ * (_t2_ * _m2_)^H^) *Todo:*:: use opb_prod() -|=== - -''''' - -Copyright (©) 2000-2004 Michael Stevens, Mathias Koch, Joerg Walter, -Gunter Winkler + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt). +|=== \ No newline at end of file diff --git a/doc/ublas/bounded_array.adoc b/doc/ublas/bounded_array.adoc index 37ce3cd20..9f063946e 100644 --- a/doc/ublas/bounded_array.adoc +++ b/doc/ublas/bounded_array.adoc @@ -1,8 +1,5 @@ == Bounded Array Storage -[[toc]] - -=== [#bounded_array]#Bounded Array# ==== Description @@ -69,7 +66,7 @@ of the concept. [cols=",,",] |=== -|Member |Where defined |Description +|Member |Where defined |Description |`value_type`| https://www.boost.org/sgi/stl/Container.html[Container] | @@ -93,7 +90,7 @@ of the concept. |`const_revere_iterator` |https://www.boost.org/sgi/stl/Container.html[Container] |Defined as `std::reverse_iterator` -|`bounded_array ()` |link:storage_concept.html[Storage] |Creates an `unbounded_array` that holds *zero* elements. +|`bounded_array ()` |link:storage_concept.html[Storage] |Creates an `unbounded_array` that holds *zero* elements. |`bounded_array (size_type size)` |link:storage_concept.html[Storage] |Creates a uninitialized `bounded_array` that holds `size` elements. All the elements are default constructed. @@ -136,11 +133,3 @@ of the concept. |`reverse_iterator rend ()` |https://www.boost.org/sgi/stl/ReversibleContainer.html[Reversible Container] |Returns a `reverse_iterator` pointing to the end of the reversed `bounded_array`. |=== -''''' - -Copyright (©) 2000-2004 Michael Stevens, Mathias Koch, Joerg Walter, -Gunter Winkler + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/container_concept.adoc b/doc/ublas/container_concept.adoc index 1c03e729a..5b75eeac8 100644 --- a/doc/ublas/container_concept.adoc +++ b/doc/ublas/container_concept.adoc @@ -1,6 +1,5 @@ == Container Concepts -[[toc]] === [#vector]#Vector# @@ -214,11 +213,11 @@ Expression] . [width="100%",cols=",,,,",options="header",] |=== -|Name |Expression |Precondition |Semantics |Postcondition +|Name |Expression |Precondition |Semantics |Postcondition |Sizing constructor |`M m (n1, n2)` |`n1 >= 0` and `n2 >= 0` |Allocates a matrix of `n1` rows and `n2` columns. |`m.size1 () == n1` and `m.size2 () == n2`. -|Insert |`m.insert_element (i, j, t)` |`0 < = i < m.size1 ()`, + `0 < = j < m.size2 ()`. |Inserts an element at `m (i, j)` with value `t`. The storage requirement of the Matrix may be increased. `m (i, j)` is equal to `t`. |`m(i,j)` is equal to `t`. +|Insert |`m.insert_element (i, j, t)` |`0 < = i < m.size1 ()`, + `0 < = j < m.size2 ()`. |Inserts an element at `m (i, j)` with value `t`. The storage requirement of the Matrix may be increased. `m (i, j)` is equal to `t`. |`m(i,j)` is equal to `t`. |Erase |`m.erase_element (i, j)` |`0 <= i < m.size1 ()`and ` 0 <= j < m.size2` |Destroys the element as `m (i, j)` and replaces it with the default `value_type ()`. The storage requirement of the Matrix may be decreased. |`m (i, j)` is equal to `value_type ()`. @@ -384,12 +383,3 @@ The run-time complexity of resize is at most linear in the tensor's size being a refinement of the TensorExpression. Being a refinement of the TensorExpression is only important for the template-expression engine but not the user. - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2018 Cem Bassoy + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/contributors.adoc b/doc/ublas/contributors.adoc new file mode 100644 index 000000000..3bdaf80e7 --- /dev/null +++ b/doc/ublas/contributors.adoc @@ -0,0 +1,30 @@ +//// +Copyright 2021 Shikhar Vashistha + +Distributed under the Boost Software License, Version 1.0. +(http://www.boost.org/LICENSE_1_0.txt) +//// + +# CONTRIBUTORS +:toc: left +:toclevels: 2 +:idprefix: +:listing-caption: Code Example +:docinfo: private-footer +:source-highlighter: rouge +:source-language: c++ + +:leveloffset: +1 +''''' +Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + +Copyright (©) 2000-2004 Michael Stevens, Gunter Winkler + +Copyright (©) 2000-2011 link:https://github.com/yimyom[David Bellot] + +Copyright (©) 2018 link:https://github.com/bassoy[Cem Bassoy] + +Copyright (©) 2021 link:https://github.com/shikharvashistha[Shikhar Vashistha] + +Use, modification and distribution are subject to the Boost Software +License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at +http://www.boost.org/LICENSE_1_0.txt ). + + + +:leveloffset: -1 diff --git a/doc/ublas/expression_concept.adoc b/doc/ublas/expression_concept.adoc index 3270e48ce..8f82bea86 100644 --- a/doc/ublas/expression_concept.adoc +++ b/doc/ublas/expression_concept.adoc @@ -1,6 +1,5 @@ == Expression Concepts -[[toc]] === [#scalar_expression]#Scalar Expression# @@ -594,11 +593,3 @@ from `m.rbegin2 ()` to `m.rend2 ()`. * `matrix_binary_scalar1` * `matrix_binary_scalar2` * `matrix_matrix_binary` - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/hermitian.adoc b/doc/ublas/hermitian.adoc index 4634816cd..bf0e10a57 100644 --- a/doc/ublas/hermitian.adoc +++ b/doc/ublas/hermitian.adoc @@ -1,8 +1,5 @@ == Hermitian Matrix -[[toc]] - -=== [#hermitian_matrix]#Hermitian Matrix# ==== Description @@ -399,11 +396,3 @@ the end of the reversed `hermitian_adaptor`. [#hermitian_adaptor_1]#[1]# Supported parameters for the type of the hermitian adaptor are `lower` and `upper`. - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/index.adoc b/doc/ublas/index.adoc index be89ef3c8..37d6e79d8 100644 --- a/doc/ublas/index.adoc +++ b/doc/ublas/index.adoc @@ -6,7 +6,6 @@ Distributed under the Boost Software License, Version 1.0. (http://www.boost.org/LICENSE_1_0.txt) //// -# Boost.Ublas: The Boost Ublas Library :toc: left :toclevels: 2 :idprefix: @@ -17,132 +16,21 @@ Distributed under the Boost Software License, Version 1.0. [[toc]] -uBLAS is a C++ template class library that provides http://www.netlib.org/blas[BLAS] level 1, 2, 3 functionality for dense, packed and sparse matrices. -The design and implementation unify mathematical notation via operator overloading and efficient code generation via expression templates. -Since 2018, uBLAS also supports basic operations for multilinear algebra operations such as the outer and inner product of higher-order tensors. +uBLAS is a C++ template class library that provides http://www.netlib.org/blas[BLAS] level 1, 2, 3 functionality for dense, packed and sparse matrices. +The design and implementation unify mathematical notation via operator overloading and efficient code generation via expression templates. +Since 2018, uBLAS also supports basic operations for multilinear algebra operations such as the outer and inner product of higher-order tensors. The goal of the new tensor extension is to provide basic operations that simplify the implementation of e.g. machine learning and quantum computing algorithms. === Functionality -uBLAS provides templated C++ classes for dense, unit and sparse vectors, dense, identity, triangular, banded, symmetric, hermitian and sparse matrices. -Views into vectors and matrices can be constructed via ranges, slices, adaptor classes and indirect arrays. -The library covers the usual basic linear and multilinear algebra operations on vectors, matrices and tensors: -reductions like different norms, addition and subtraction of vectors and matrices and multiplication with a scalar, inner and outer products of vectors, matrix vector and matrix matrix products and triangular solver. +uBLAS provides templated C++ classes for dense, unit and sparse vectors, dense, identity, triangular, banded, symmetric, hermitian and sparse matrices. +Views into vectors and matrices can be constructed via ranges, slices, adaptor classes and indirect arrays. +The library covers the usual basic linear and multilinear algebra operations on vectors, matrices and tensors: +reductions like different norms, addition and subtraction of vectors and matrices and multiplication with a scalar, inner and outer products of vectors, matrix vector and matrix matrix products and triangular solver. Similar operations are also provided for the tensor type. The glue between containers, views and expression templated operations is a mostly https://en.wikipedia.org/wiki/Standard_Template_Library[STL] conforming iterator interface. - - -=== Documentation - -* link:overview.html[Overview] -** link:overview.html#rationale[Rationale] -** link:overview.html#functionality[Functionality] -** link:types_overview.html[Overview of Tensor, Matrix- and Vector -Types] -** link:operations_overview.html[Overview of Tensor, Matrix and Vector -Operations] -** link:#further_information[Effective uBLAS and further information] -** link:options.html[Macros and Preprocessor Options] -* link:vector.html[Vector] -** link:vector.html#vector[Vector] -** link:vector.html#unit_vector[Unit Vector] -** link:vector.html#zero_vector[Zero Vector] -** link:vector.html#scalar_vector[Scalar Vector] -* link:vector_sparse.html[Sparse Vector] -** link:vector_sparse.html#mapped_vector[Mapped Vector] -** link:vector_sparse.html#compressed_vector[Compressed Vector] -** link:vector_sparse.html#coordinate_vector[Coordinate Vector] -* link:vector_proxy.html[Vector Proxies] -** link:vector_proxy.html#vector_range[Vector Range] -** link:vector_proxy.html#vector_slice[Vector Slice] -* link:vector_expression.html[Vector Expressions] -** link:vector_expression.html#vector_expression[Vector Expression] -** link:vector_expression.html#vector_references[Vector References] -** link:vector_expression.html#vector_operations[Vector Operations] -** link:vector_expression.html#vector_reductions[Vector Reductions] -* link:matrix.html[Matrix] -** link:matrix.html#matrix[Matrix] -** link:matrix.html#identity_matrix[Identity Matrix] -** link:matrix.html#zero_matrix[Zero Matrix] -** link:matrix.html#scalar_matrix[Scalar Matrix] -* link:triangular.html[Triangular Matrix] -** link:triangular.html#triangular_matrix[Triangular Matrix] -** link:triangular.html#triangular_adaptor[Triangular Adaptor] -* link:symmetric.html[Symmetric Matrix] -** link:symmetric.html#symmetric_matrix[Symmetric Matrix] -** link:symmetric.html#symmetric_adaptor[Symmetric Adaptor] -* link:hermitian.html[Hermitian Matrix] -** link:hermitian.html#hermitian_matrix[Hermitian Matrix] -** link:hermitian.html#hermitian_adaptor[Hermitian Adaptor] -* link:banded.html[Banded Matrix] -** link:banded.html#banded_matrix[Banded Matrix] -** link:banded.html#banded_adaptor[Banded Adaptor] -* link:matrix_sparse.html[Sparse Matrix] -** link:matrix_sparse.html#mapped_matrix[Mapped Matrix] -** link:matrix_sparse.html#compressed_matrix[Compressed Matrix] -** link:matrix_sparse.html#coordinate_matrix[Coordinate Matrix] -* link:matrix_proxy.html[Matrix Proxies] -** link:matrix_proxy.html#matrix_row[Matrix Row] -** link:matrix_proxy.html#matrix_column[Matrix Column] -** link:matrix_proxy.html#vector_range[Vector Range] -** link:matrix_proxy.html#vector_slice[Vector Slice] -** link:matrix_proxy.html#matrix_range[Matrix Range] -** link:matrix_proxy.html#matrix_slice[Matrix Slice] -* link:matrix_expression.html[Matrix Expressions] -** link:matrix_expression.html#matrix_expression[Matrix Expression] -** link:matrix_expression.html#matrix_references[Matrix References] -** link:matrix_expression.html#matrix_operations[Matrix Operations] -** link:matrix_expression.html#matrix_vector_operations[Matrix Vector -Operations] -** link:matrix_expression.html#matrix_matrix_operations[Matrix Matrix -Operations] -* link:tensor.html[Tensor] -** link:tensor.html#tensor[Tensor] -* link:tensor/tensor_expression.html[Tensor Expressions] -** link:tensor/tensor_expression.html#tensor_expression[Tensor -Expression] -** link:tensor/tensor_expression.html#binary_tensor_expression[Binary -Tensor Expression] -** link:tensor/tensor_expression.html#unary_tensor_expression[Unary -Tensor Expression] -* Storage and special containers -** link:unbounded_array.html[Unbounded Array] -** link:bounded_array.html[Bounded Array] -** link:range.html#range[Range] -** link:range.html#slice[Slice] -** link:tensor/extents.html#extents[Extents] -** link:tensor/strides.html#strides[Strides] -* link:storage_sparse.html[Sparse Storage] -** link:storage_sparse.html#map_std[Default Standard Map] -** link:storage_sparse.html#map_array[Map Array] -* Operations & Functions -** link:products.html[Special Products] -** link:blas.html[BLAS] -* uBLAS Concept definitions -** link:container_concept.html[Container Concepts] -*** link:container_concept.html#vector[Vector] -*** link:container_concept.html#matrix[Matrix] -*** link:container_concept.html#tensor[Tensor] -** link:expression_concept.html[Expression Concepts] -*** link:expression_concept.html#scalar_expression[Scalar Expression] -*** link:expression_concept.html#vector_expression[Vector Expression] -*** link:expression_concept.html#matrix_expression[Matrix Expression] -** link:storage_concept.html[Storage Concept] -** link:iterator_concept.html[Iterator Concepts] -*** link:iterator_concept.html#indexed_bidirectional_iterator[Indexed -Bidirectional Iterator] -*** link:iterator_concept.html#indexed_random_access_iterator[Indexed -Random Access Iterator] -*** link:iterator_concept.html#indexed_bidirectional_cr_iterator[Indexed -Bidirectional Column/Row Iterator] -*** link:iterator_concept.html#indexed_random_access_cr_iterator[Indexed -Random Access Column/Row Iterator] - -=== Release notes - -Release notes can be found link:release_notes.html[here]. [further_information] === Known limitations @@ -158,13 +46,13 @@ Release notes can be found link:release_notes.html[here]. ==== Authors and Credits -uBLAS initially was written by Joerg Walter and Mathias Koch. +uBLAS initially was written by Joerg Walter and Mathias Koch. We would like thank all contributors who has supported this library. -Amongst many contributors around the world, David Abrahams, Ed Brey, Fernando Cacciola, Juan Jose Gomez Cadenas, Beman Dawes, Matt Davies, Bob Fletcher, Kresimir Fresl, Joachim Kessel, Patrick Kowalzick, Toon Knapen, Hendrik Kueck, John Maddock, Jens Maurer, Alexei Novakov, Gary Powell, Joachim Pyras, Peter Schmitteckert, Jeremy Siek, Markus Steffl, Michael Stevens, Benedikt Weber, Martin Weiser, Gunter Winkler, Marc Zimmermann, Marco Guazzone, Nasos Iliopoulus and the members of http://www.boost.org[Boost] had a great impact and contribution helping the library to grow and mature. +Amongst many contributors around the world, David Abrahams, Ed Brey, Fernando Cacciola, Juan Jose Gomez Cadenas, Beman Dawes, Matt Davies, Bob Fletcher, Kresimir Fresl, Joachim Kessel, Patrick Kowalzick, Toon Knapen, Hendrik Kueck, John Maddock, Jens Maurer, Alexei Novakov, Gary Powell, Joachim Pyras, Peter Schmitteckert, Jeremy Siek, Markus Steffl, Michael Stevens, Benedikt Weber, Martin Weiser, Gunter Winkler, Marc Zimmermann, Marco Guazzone, Nasos Iliopoulus and the members of http://www.boost.org[Boost] had a great impact and contribution helping the library to grow and mature. -Starting with the https://github.com/BoostGSoC18/tensor/wiki[GSoC 2018 project], uBlas has been extended by a flexible tensor data type and basic tensor operations supporting general tensor contractions and the Einstein notation. +Starting with the https://github.com/BoostGSoC18/tensor/wiki[GSoC 2018 project], uBlas has been extended by a flexible tensor data type and basic tensor operations supporting general tensor contractions and the Einstein notation. The goal of the new tensor extension is to support the implementation of algorithms for e.g. machine learning and quantum computing applications. -The initial implementation of this extension is written by Cem Bassoy. +The initial implementation of this extension is written by Cem Bassoy. Contributors of the uBLAS extension are Amit Singh, Ashar Khan, Stefan Seefeld, Cem Bassoy and the members of http://www.boost.org[Boost]. This library is currently maintained by David Bellot, Cem Bassoy and Stefan Seefeld. @@ -217,14 +105,3 @@ How can I disable expression templates? + A: You do not need to disable expression templates. Please try reintroducing temporaries using either `prod (A,` `matrix_type` `(prod (B, C)))` or `prod (A, prod<``matrix_type` `> (B, C))`. - -''''' - -Copyright (©) 2000-2011 Joerg Walter, Mathias Koch, Gunter Winkler, -David Bellot + -Copyright (©) 2021 Shikhar Vashistha + -Copyright (©) 2021 Cem Bassoy + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). - diff --git a/doc/ublas/iterator_concept.adoc b/doc/ublas/iterator_concept.adoc index f89b4ba2e..ee2da5f41 100644 --- a/doc/ublas/iterator_concept.adoc +++ b/doc/ublas/iterator_concept.adoc @@ -1,6 +1,5 @@ == Iterator Concepts -[[toc]] An Iterator is a restricted pointer-like object pointing into a vector or matrix container. @@ -629,11 +628,3 @@ then `it1 == it2 + (it1 - it2)`. * `matrix::iterator1` * `matrix::iterator2` - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/matrix-index.adoc b/doc/ublas/matrix-index.adoc new file mode 100644 index 000000000..1279e86e3 --- /dev/null +++ b/doc/ublas/matrix-index.adoc @@ -0,0 +1,36 @@ +//// +Copyright 2021 Shikhar Vashistha + +Distributed under the Boost Software License, Version 1.0. +(http://www.boost.org/LICENSE_1_0.txt) +//// + +# Matrix +:toc: left +:toclevels: 2 +:idprefix: +:listing-caption: Code Example +:docinfo: private-footer +:source-highlighter: rouge +:source-language: c++ + +:leveloffset: +1 + +include::matrix.adoc[] + +include::triangular.adoc[] + +include::symmetric.adoc[] + +include::hermitian.adoc[] + +include::banded.adoc[] + +include::matrix_sparse.adoc[] + +include::matrix_proxy.adoc[] + +include::matrix_expression.adoc[] + + +:leveloffset: -1 \ No newline at end of file diff --git a/doc/ublas/matrix.adoc b/doc/ublas/matrix.adoc index e369e4b5d..10d063697 100644 --- a/doc/ublas/matrix.adoc +++ b/doc/ublas/matrix.adoc @@ -1,8 +1,5 @@ -== Matrix +== Matrix Abstract -[[toc]] - -=== [#matrix]#Matrix# ==== Description @@ -541,12 +538,4 @@ to the end of the `scalar_matrix`. |`const_reverse_iterator2 rend2 () const` |Returns a `const_reverse_iterator2` pointing to the end of the reversed `scalar_matrix`. -|=== - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). +|=== \ No newline at end of file diff --git a/doc/ublas/matrix_expression.adoc b/doc/ublas/matrix_expression.adoc index 942100d65..c91b55262 100644 --- a/doc/ublas/matrix_expression.adoc +++ b/doc/ublas/matrix_expression.adoc @@ -1,8 +1,6 @@ == Matrix Expressions -[[toc]] -=== [#matrix_expression]#Matrix Expression# ==== Description @@ -1302,12 +1300,4 @@ int main () { std::cout << solve (m1, m2, lower_tag ()) << std::endl; } -.... - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). +.... \ No newline at end of file diff --git a/doc/ublas/matrix_proxy.adoc b/doc/ublas/matrix_proxy.adoc index 0b02e54eb..9af23373d 100644 --- a/doc/ublas/matrix_proxy.adoc +++ b/doc/ublas/matrix_proxy.adoc @@ -1,6 +1,5 @@ == Matrix Proxies -[[toc]] === [#matrix_row]#Matrix Row# @@ -1134,11 +1133,3 @@ int main () { std::cout << project (m, slice (0, 1, 3), slice (0, 1, 3)) << std::endl; } .... - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/matrix_sparse.adoc b/doc/ublas/matrix_sparse.adoc index 945b7f676..2613b4985 100644 --- a/doc/ublas/matrix_sparse.adoc +++ b/doc/ublas/matrix_sparse.adoc @@ -1,6 +1,5 @@ == Sparse Matricies -[[toc]] === [#mapped_matrix]#Mapped Matrix# @@ -12,7 +11,7 @@ xn_)-dimensional sparse matrix and _0 < = i < m_, _0 < = j < n_ the non-zero elements __h__~_i,j_~ are mapped via _(i x n + j)_ for row major orientation or via _(i + j x m)_ for column major orientation to consecutive elements of the associative container, i.e. for elements _k_ -= __m__~_i1,j1_~ and __k + 1 = __m__~_i2,j2_~ += __m__~_i1,j1_~ and __k + 1 = __m__~_i2,j2_~ of the container holds __i__~_1_~ __< i__~_2_~ or __(i__~_1_~ __= i__~_2_~ and __j__~_1_~ __< j__~_2_~_)_ with row major orientation or __j__~_1_~ __< j__~_2_~ or __(j__~_1_~ __= j__~_2_~ and @@ -649,12 +648,4 @@ organization are `row_major` and `column_major`. `0` and `1` at least. [#coordinate_matrix_3]#[3]# Supported parameters for the adapted array -are `unbounded_array<>` , `bounded_array<>` and `std::vector<>` . - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). +are `unbounded_array<>` , `bounded_array<>` and `std::vector<>` . \ No newline at end of file diff --git a/doc/ublas/misc.adoc b/doc/ublas/misc.adoc new file mode 100644 index 000000000..4a426a382 --- /dev/null +++ b/doc/ublas/misc.adoc @@ -0,0 +1,46 @@ +//// +Copyright 2021 Shikhar Vashistha + +Distributed under the Boost Software License, Version 1.0. +(http://www.boost.org/LICENSE_1_0.txt) +//// + +# Miscellaneous +:toc: left +:toclevels: 2 +:idprefix: +:listing-caption: Code Example +:docinfo: private-footer +:source-highlighter: rouge +:source-language: c++ + +:leveloffset: +1 + +include::unbounded_array.adoc[] + +include::bounded_array.adoc[] + +include::types_overview.adoc[] + +include::range.adoc[] + +include::options.adoc[] + +include::storage_sparse.adoc[] + +include::range.adoc[] + +include::products.adoc[] + +include::blas.adoc[] + +include::container_concept.adoc[] + +include::expression_concept.adoc[] + +include::storage_concept.adoc[] + +include::iterator_concept.adoc[] + + +:leveloffset: -1 \ No newline at end of file diff --git a/doc/ublas/operations_overview.adoc b/doc/ublas/operations_overview.adoc index 64c107864..c675c6f94 100644 --- a/doc/ublas/operations_overview.adoc +++ b/doc/ublas/operations_overview.adoc @@ -1,6 +1,5 @@ == Overview of Tensor, Matrix and Vector Operations -[[toc]] Contents::: link:#blas[Basic Linear Algebra] @@ -40,11 +39,11 @@ w = t * u; w = u * t; w = u / t; ==== computed assignments .... -X += Y; X -= Y; -C += A; C -= A; -w += u; w -= u; -X *= t; X /= t; -C *= t; C /= t; +X += Y; X -= Y; +C += A; C -= A; +w += u; w -= u; +X *= t; X /= t; +C *= t; C /= t; w *= t; w /= t; .... @@ -87,7 +86,7 @@ t = norm_inf(v); i = index_norm_inf(v); t = norm_1(v); t = norm_2(v); t = norm_2_square(v); t = norm_inf(A); i = index_norm_inf(A); -t = norm_1(A); t = norm_frobenius(A); +t = norm_1(A); t = norm_frobenius(A); t = norm(X); .... @@ -241,7 +240,7 @@ What is the complexity (the number of add and multiply operations) required to compute the following? .... - R = prod(A, prod(B,C)); + R = prod(A, prod(B,C)); .... Firstly the complexity depends on matrix size. Also since prod is @@ -271,13 +270,4 @@ The 'temp_type' is important. Given A,B,C are all of the same type. Say matrix, the choice is easy. However if the value_type is mixed (int with float or double) or the matrix type is mixed (sparse with symmetric) the best solution is not so obvious. It is up to you! It -depends on numerical properties of A and the result of the prod(B,C). - -''''' - -Copyright (©) 2000-2007 Joerg Walter, Mathias Koch, Gunter Winkler, -Michael Stevens + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). +depends on numerical properties of A and the result of the prod(B,C). \ No newline at end of file diff --git a/doc/ublas/options.adoc b/doc/ublas/options.adoc index a9e26bad9..a8b294175 100644 --- a/doc/ublas/options.adoc +++ b/doc/ublas/options.adoc @@ -1,8 +1,5 @@ == Boost Basic Linear Algebra - Configuration Options -[[toc]] - -link:index.html[back to uBLAS home] === NDEBUG @@ -175,14 +172,5 @@ effect._ ** BOOST_UBLAS_SINGULAR_CHECK _Check the for singularity in triangular solve() functions_ -''''' - -[[copyright]] -Copyright (©) 2000-2009 Joerg Walter, Mathias Koch, Gunter Winkler + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). - [[revision]] Last modified: Wed Sep 16 23:16:45 CEST 2009 diff --git a/doc/ublas/overview.adoc b/doc/ublas/overview.adoc index da86f1dd2..14cafd667 100644 --- a/doc/ublas/overview.adoc +++ b/doc/ublas/overview.adoc @@ -1,6 +1,5 @@ -== uBLAS Overview +== Overview -[[toc]] === Rationale @@ -571,12 +570,4 @@ penalty For larger vectors and matrices the general abstraction penalty for using classes seems to decrease, the small loss when using generic vector and matrix classes seems to remain. The difference w.r.t. alias -assumptions remains visible, too. - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). +assumptions remains visible, too. \ No newline at end of file diff --git a/doc/ublas/products.adoc b/doc/ublas/products.adoc index 5c7af1a59..7c9b200e9 100644 --- a/doc/ublas/products.adoc +++ b/doc/ublas/products.adoc @@ -1,21 +1,19 @@ == Special Products -[[toc]] - === Functions [width="100%",cols=">50%,50%",] |=== -|template BOOST_UBLAS_INLINE V & +|template BOOST_UBLAS_INLINE V & |link:#product_1[axpy_prod] (const matrix_expression< E1 > &e1, const vector_expression< E2 > &e2, V &v, bool init=true) computes `v += A x` or `v = A x` in an optimized fashion. -|template BOOST_UBLAS_INLINE V & +|template BOOST_UBLAS_INLINE V & |link:#product_2[axpy_prod] (const vector_expression< E1 > &e1, const matrix_expression< E2 > &e2, V &v, bool init=true) computes `v += AT x` or `v = AT x` in an optimized fashion. -|template BOOST_UBLAS_INLINE M & +|template BOOST_UBLAS_INLINE M & |link:#product_3[axpy_prod] (const matrix_expression< E1 > &e1, const matrix_expression< E2 > &e2, M &m, bool init=true) computes `M += A X` or `M = A X` in an optimized fashion. -|template BOOST_UBLAS_INLINE M & +|template BOOST_UBLAS_INLINE M & |link:#product_4[opb_prod] (const matrix_expression< E1 > &e1, const matrix_expression< E2 > &e2, M &m, bool init=true) computes `M += A X` or `M = A X` in an optimized fashion. |=== @@ -28,7 +26,7 @@ a| [cols=",,,",] !=== -!BOOST_UBLAS_INLINE V& axpy_prod !( !const matrix_expression< E1 > & +!BOOST_UBLAS_INLINE V& axpy_prod !( !const matrix_expression< E1 > & !_e1_, ! ! !const vector_expression< E2 > & !_e2_, @@ -71,7 +69,7 @@ give a large speed up compared to prod. a| [cols=",,,",] !=== -!BOOST_UBLAS_INLINE V& axpy_prod !( !const vector_expression< E1 > & +!BOOST_UBLAS_INLINE V& axpy_prod !( !const vector_expression< E1 > & !_e1_, ! ! !const matrix_expression< E2 > & !_e2_, @@ -113,7 +111,7 @@ give a large speed up compared to prod. a| [cols=",,,",] !=== -!BOOST_UBLAS_INLINE M& axpy_prod !( !const matrix_expression< E1 > & +!BOOST_UBLAS_INLINE M& axpy_prod !( !const matrix_expression< E1 > & !_e1_, ! ! !const matrix_expression< E2 > & !_e2_, @@ -155,7 +153,7 @@ Up to now there are no specialisations. a| [cols=",,,",] !=== -!BOOST_UBLAS_INLINE M& opb_prod !( !const matrix_expression< E1 > & +!BOOST_UBLAS_INLINE M& opb_prod !( !const matrix_expression< E1 > & !_e1_, ! ! !const matrix_expression< E2 > & !_e2_, @@ -188,13 +186,4 @@ the future. This function may give a speedup if `A` has less columns than rows, because the product is computed as a sum of outer products. -|=== - -''''' - -Copyright (©) 2000-2004 Michael Stevens, Mathias Koch, Joerg Walter, -Gunter Winkler + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). \ No newline at end of file +|=== \ No newline at end of file diff --git a/doc/ublas/range.adoc b/doc/ublas/range.adoc index ad2e8b869..0692023f5 100644 --- a/doc/ublas/range.adoc +++ b/doc/ublas/range.adoc @@ -1,6 +1,5 @@ == Range and Slice Storage -[[toc]] === [#range]#Range# @@ -179,13 +178,4 @@ the end of the `slice`. * None all strides are vaild. However when an index is returned or an iterator is dereferenced its value must be representable as the -size_type. - -''''' - -Copyright (©) 2000-2004 Michael Stevens, Mathias Koch, Joerg Walter, -Gunter Winkler + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). +size_type. \ No newline at end of file diff --git a/doc/ublas/release.adoc b/doc/ublas/release.adoc new file mode 100644 index 000000000..93ebe4c90 --- /dev/null +++ b/doc/ublas/release.adoc @@ -0,0 +1,21 @@ +//// +Copyright 2021 Shikhar Vashistha + +Distributed under the Boost Software License, Version 1.0. +(http://www.boost.org/LICENSE_1_0.txt) +//// +# Release Notes +:toc: left +:toclevels: 2 +:idprefix: +:listing-caption: Code Example +:docinfo: private-footer +:source-highlighter: rouge +:source-language: c++ + +:leveloffset: +1 + +include::release_notes.adoc[] + + +:leveloffset: -1 \ No newline at end of file diff --git a/doc/ublas/release_notes.adoc b/doc/ublas/release_notes.adoc index 05fda74bc..4c6d48490 100644 --- a/doc/ublas/release_notes.adoc +++ b/doc/ublas/release_notes.adoc @@ -1,8 +1,5 @@ -== Boost Basic Linear Algebra - Release Notes +== Boost Basic Linear Algebra -link:index.html[back to uBLAS home] - -[[toc]] === Release 1.70.0 @@ -69,12 +66,4 @@ DefaultConstructible to concept checks === Release 1.40.0 and before -* Release notes were not available in this form. - -''''' - -Copyright (©) 2000-2009 Joerg Walter, Mathias Koch, Gunter Winkler + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). +* Release notes were not available in this form. \ No newline at end of file diff --git a/doc/ublas/storage_concept.adoc b/doc/ublas/storage_concept.adoc index dc85bc83c..4dfda8f0e 100644 --- a/doc/ublas/storage_concept.adoc +++ b/doc/ublas/storage_concept.adoc @@ -1,9 +1,5 @@ == Storage concept -[[toc]] - -=== [#range]#Storage concept# - ==== Description Storage is a variable-size container whose elements are arranged in a @@ -99,11 +95,3 @@ omitted" in section 5.3.4 paragraph 15 of the ISO C++ standard. |size()==n * link:bounded_array.html[bounded_array] ===== Notes - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/storage_sparse.adoc b/doc/ublas/storage_sparse.adoc index 884dac190..45cee21a2 100644 --- a/doc/ublas/storage_sparse.adoc +++ b/doc/ublas/storage_sparse.adoc @@ -1,6 +1,5 @@ == Sparse Storage -[[toc]] === [#map_std]#Default Standard Map# @@ -200,11 +199,3 @@ the beginning of the reversed `map_array`. |`reverse_iterator rend ()` |Returns a `reverse_iterator` pointing to the end of the reversed `map_array`. |=== - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/symmetric.adoc b/doc/ublas/symmetric.adoc index ddab2c6f8..cfdaabd85 100644 --- a/doc/ublas/symmetric.adoc +++ b/doc/ublas/symmetric.adoc @@ -1,8 +1,5 @@ == Symmetric Matrix -[[toc]] - -=== [#symmetric_matrix]#Symmetric Matrix# ==== Description @@ -390,12 +387,4 @@ the end of the reversed `symmetric_adaptor`. ==== Notes [#symmetric_adaptor_1]#[1]# Supported parameters for the type of the -symmetric adaptor are `lower` and `upper`. - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). +symmetric adaptor are `lower` and `upper`. \ No newline at end of file diff --git a/doc/ublas/tensor-index.adoc b/doc/ublas/tensor-index.adoc new file mode 100644 index 000000000..1a06a4a25 --- /dev/null +++ b/doc/ublas/tensor-index.adoc @@ -0,0 +1,31 @@ +//// +Copyright 2021 Shikhar Vashistha + +Distributed under the Boost Software License, Version 1.0. +(http://www.boost.org/LICENSE_1_0.txt) +//// + +# Tensor +:toc: left +:toclevels: 2 +:idprefix: +:listing-caption: Code Example +:docinfo: private-footer +:source-highlighter: rouge +:source-language: c++ + +:leveloffset: +1 + +include::tensor/tensor_index.adoc[] + +include::tensor.adoc[] + +include::tensor/tensor_expression.adoc[] + +include::tensor/extents.adoc[] + +include::tensor/strides.adoc[] + +include::tensor/tensor_expression.adoc[] + +:leveloffset: -1 \ No newline at end of file diff --git a/doc/ublas/tensor.adoc b/doc/ublas/tensor.adoc index 43d0656bf..dba6facf9 100644 --- a/doc/ublas/tensor.adoc +++ b/doc/ublas/tensor.adoc @@ -1,6 +1,5 @@ -== Tensor +== Tensor Abstract -[[toc]] . Tensor + .. link:#tensor_1[Description] + @@ -27,7 +26,7 @@ The templated class `tensor` is the base -container adaptor for dense tensors. Every element +container adaptor for dense tensors. Every element $(t_/ i_1, i_2, \dots, i_p)$ of a $p$-order $(n_1 \times n_2 \times \cdots \times n_p)$-dimensional tensor $T$ is mapped to $j$-th element of a one-dimensional container where $(j = \sum_ /{r=1}^p i_r \cdot w_r)$ with @@ -48,7 +47,7 @@ int main () { for (auto j = 0ul; j < t.size (1); ++ j) for (auto i = 0ul; i < t.size (0); ++ i) t.at(i,j,k) = 3*i + 2*j + 5*k; - + std::cout << t << std::endl; } .... @@ -340,12 +339,4 @@ greater than `tensor::size()`, the tensor is resized with `v`. `first_order` and `last_order`. [#tensor_2]#[2]# Common parameters for the storage array are -`std::array` and `std::vector`. - -''''' - -Copyright (©) 2018 Cem Bassoy + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). \ No newline at end of file +`std::array` and `std::vector`. \ No newline at end of file diff --git a/doc/ublas/tensor/extents.adoc b/doc/ublas/tensor/extents.adoc index 618edb554..4715ba491 100644 --- a/doc/ublas/tensor/extents.adoc +++ b/doc/ublas/tensor/extents.adoc @@ -1,6 +1,5 @@ -== Extents +== Tensor Extents -[[toc]] === [#extents]#basic_extents# @@ -127,10 +126,3 @@ None. |`std::vector base() const` |Returns a const reference to the private member sequence container holding all elements. |=== -''''' - -Copyright (©) 2018 Cem Bassoy + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/tensor/strides.adoc b/doc/ublas/tensor/strides.adoc index 1386a46db..e3153458a 100644 --- a/doc/ublas/tensor/strides.adoc +++ b/doc/ublas/tensor/strides.adoc @@ -1,6 +1,5 @@ -== Strides +== Tensor Strides -[[toc]] === [#extents]#basic_strides# @@ -20,13 +19,13 @@ int main () { using namespace boost::numeric::ublas; auto wf = strides(shape{4,3,2}); for (auto i = 0u; i < wf.size(); ++i) - std::cout << wf.at(i) << std::endl; + std::cout << wf.at(i) << std::endl; // 1,4,12 - + auto wl = strides(shape{4,3,2}); for (auto i = 0u; i < wl.size(); ++i) - std::cout << wl.at(i) << std::endl; - // 6,2,1 + std::cout << wl.at(i) << std::endl; + // 6,2,1 } .... @@ -145,11 +144,3 @@ sequence container holding all elements. |Returns relative memory location depending on the indices `i`, `is ...` and stride vector `w` (recursive function). |=== - -''''' - -Copyright (©) 2018 Cem Bassoy + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/tensor/tensor_expression.adoc b/doc/ublas/tensor/tensor_expression.adoc index 7971dcc24..0a596b3aa 100644 --- a/doc/ublas/tensor/tensor_expression.adoc +++ b/doc/ublas/tensor/tensor_expression.adoc @@ -1,8 +1,5 @@ == Tensor Expressions -[[toc]] - -=== [#tensor_expression]#Tensor Expression# ==== Description @@ -165,11 +162,3 @@ None. |`decltype(auto) operator()(std::size_t i) const` |Returns a `const` reference to the i-th element of the expression. |=== - -''''' - -Copyright (©) 2018 Cem Bassoy + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/tensor/tensor_index.adoc b/doc/ublas/tensor/tensor_index.adoc index b8e9198af..7271bf120 100644 --- a/doc/ublas/tensor/tensor_index.adoc +++ b/doc/ublas/tensor/tensor_index.adoc @@ -1,6 +1,5 @@ -== Tensor Index +== Tensor Idealogy -[[toc]] === [#tensor index]#tensor_index# @@ -42,12 +41,4 @@ None. |`format_t` |Storage organization of the tensor. | |`storage_t` |The type of the storage array of the tensor. | |`N` |Number of indices provided. | -|=== - -''''' - -Copyright (©) 2018 Cem Bassoy + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). +|=== \ No newline at end of file diff --git a/doc/ublas/triangular.adoc b/doc/ublas/triangular.adoc index 71259914e..94b4ecee3 100644 --- a/doc/ublas/triangular.adoc +++ b/doc/ublas/triangular.adoc @@ -1,8 +1,5 @@ == Triangular Matrix -[[toc]] - -=== [#triangular_matrix]#Triangular Matrix# ==== Description @@ -406,11 +403,3 @@ the end of the reversed `triangular_adaptor`. [#triangular_adaptor_1]#[1]# Supported parameters for the type of the triangular adaptor are `lower` , `unit_lower`, `upper` and `unit_upper` . - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/tutorial.adoc b/doc/ublas/tutorial.adoc new file mode 100644 index 000000000..ab66b4a1e --- /dev/null +++ b/doc/ublas/tutorial.adoc @@ -0,0 +1,190 @@ += Boost.uBlas Tutorial + +For the official Boost.uBlas documentation visit https://boostorg.github.io/ublas/[here] + +You can find a set of tutorials and educational materials by the Boost community at link:abc.com[Boost.uBlas Tutorials]. +The goal of this page is to provide high-quality resources by the Boost.uBlas project, both for self-learning and for teaching classes with, in the format of https://godbolt.org/[Godbolt]. +If you're interested in adding your own content, check the Boost.uBlas repository on https://github.com/boostorg/ublas[GitHub]. + +== Boost.uBlas Vector + +=== What is a vector ? + +Vectors are sequence containers representing arrays that can change in size. +Just like arrays, vectors use contiguous storage locations for their elements, which means that their elements can also be accessed using offsets on regular pointers to its elements, and just as efficiently as in arrays. +But unlike arrays, their size can change dynamically, with their storage being handled automatically by the container. +Internally, vectors use a dynamically allocated array to store their elements. +This array may need to be reallocated in order to grow in size when new elements are inserted, which implies allocating a new array and moving all elements to it. +This is a relatively expensive task in terms of processing time, and thus, vectors do not reallocate each time an element is added to the container. +Instead, vector containers may allocate some extra storage to accommodate for possible growth, and thus the container may have an actual capacity greater than the storage strictly needed to contain its elements (i.e., its size). +Libraries can implement different strategies for growth to balance between memory usage and reallocations, but in any case, reallocations should only happen at logarithmically growing intervals of size so that the insertion of individual elements at the end of the vector can be provided with amortized constant time complexity (see push_back). +Therefore, compared to arrays, vectors consume more memory in exchange for the ability to manage storage and grow dynamically in an efficient way. +Compared to the other dynamic sequence containers (deques, lists and forward_lists), vectors are very efficient accessing its elements (just like arrays) and relatively efficient adding or removing elements from its end. +For operations that involve inserting or removing elements at positions other than the end, they perform worse than the others, and have less consistent iterators and references than lists and forward_lists. + +=== Why a vector ? + +The elements are stored contiguously, which means that elements can be accessed not only through iterators, but also using offsets to regular pointers to elements. +This means that a pointer to an element of a vector may be passed to any function that expects a pointer to an element of an array. +The storage of the vector is handled automatically, being expanded and contracted as needed. +Vectors usually occupy more space than static arrays, because more memory is allocated to handle future growth. +This way a vector does not need to reallocate each time an element is inserted, but only when the additional memory is exhausted. +The complexity (efficiency) of common operations on vectors is as follows: + +* Random access - constant 𝓞(1) +* Insertion or removal of elements at the end - amortized constant 𝓞(1) +* Insertion or removal of elements - linear in the distance to the end of the vector 𝓞(n) + +=== How to create a vector in Boost.uBlas ? + +---- +#include +#include + +int main () { + using namespace boost::numeric::ublas; + vector v (3); + for (unsigned i = 0; i < v.size (); ++ i) { + v (i) = i; + } + std::cout << v << '\n'; +} +---- + +== Boost.uBlas Matrix + +=== What is a matrix ? + +A matrix is a specialized 2-D array that retains its 2-D nature through operations. +It has certain special operators, such as *(matrix multiplication)* and *(matrix power)*. +Just like vectors, matrix use contiguous storage locations for their elements, which means that their elements can also be accessed using offsets on regular pointers to its elements, and just as efficiently as in vectors. +But unlike vectors, their size can change dynamically, with their storage being handled automatically by the container. +Internally, matrix use a dynamically allocated array to store their elements. +This array may need to be reallocated in order to grow in size when new elements are inserted, which implies allocating a new array and moving all elements to it. +This is a relatively expensive task in terms of processing time, and thus, vectors do not reallocate each time an element is added to the container. +Instead, vector containers may allocate some extra storage to accommodate for possible growth, and thus the container may have an actual capacity greater than the storage strictly needed to contain its elements (i.e., its size). +Libraries can implement different strategies for growth to balance between memory usage and reallocations, but in any case, reallocations should only happen at logarithmically growing intervals of size so that the insertion of individual elements at the end of the vector can be provided with amortized constant time complexity (see push_back). +Therefore, compared to vectors, vectors consume more memory in exchange for the ability to manage storage and grow dynamically in an efficient way. +Compared to the other dynamic sequence containers (deques, lists and forward_lists), vectors are very efficient accessing its elements (just like vectors) and relatively efficient adding or removing elements from its end. +For operations that involve inserting or removing elements at positions other than the end, they perform worse than the others, and have less consistent iterators and references than lists and forward_lists. + +=== Why a matrix ? + +The elements are stored contiguously, which means that elements can be accessed not only through iterators, but also using offsets to regular pointers to elements. +This means that a pointer to an element of a vector may be passed to any function that expects a pointer to an element of an array. +The storage of the vector is handled automatically, being expanded and contracted as needed. +Vectors usually occupy more space than static arrays, because more memory is allocated to handle future growth. +This way a vector does not need to reallocate each time an element is inserted, but only when the additional memory is exhausted. +The complexity (efficiency) of common operations on vectors is as follows: + +* Random access - constant 𝓞(1) +* Insertion or removal of elements at the end - amortized constant 𝓞(1) +* Insertion or removal of elements - linear in the distance to the end of the vector 𝓞(n) + +=== How to create a matrix in Boost.uBlas ? + +---- +#include +#include + +int main () { + using namespace boost::numeric::ublas; + matrix m (3, 3); + for (unsigned i = 0; i < m.size1(); ++ i){ + for (unsigned j = 0; j < m.size2(); ++ j){ + m (i, j) = 3 * i + j; + } + } + std::cout << m << std::endl; +} +---- + +== Boost.uBlas Matrix + +=== What is a matrix ? + +In mathematics, a matrix (plural matrices) is a rectangular array or table of numbers, symbols, or expressions, arranged in rows and columns, which is used to represent a mathematical object or a property of such an object. +For example, + +is a matrix with two rows and three columns; +one say often a "two by three matrix", a "2×3-matrix", or a matrix of dimension 2×3. + +Without further specifications, matrices represent linear maps, and allow explicit computations in linear algebra. +Therefore, the study of matrices is a large part of linear algebra, and most properties and operations of abstract linear algebra can be expressed in terms of matrices. +For example, matrix multiplication represents composition of linear maps. + +=== Why a matrix ? + +Working with matrices is a way to deal with a lot of numbers at the same time in a reduced space and practical way. +Suppose we have a system of equations: + +We can see that it has a repeating pattern, that for every equation, we have values multiplied by x, y and z. +With matrices we have a way to write this system without repeating these and in a much more elegant way: + +With this, adding one more equation to the system is a matter of adding numbers to the first and the last matrix, without touching the [x y z] matrix, since they keep repeating. +(Those who already did endless exercise lists of equation systems knows how boring is to keep writing x, y, z over and over and over hehe) Neural networks often use too many values and operations, and write down every one of them would be impractical, so we need a way to compact things as much as possible to make them easier. +Matrices help us with it. + +Of course, these are not the only reasons to use function notations and matrices: With these we can write theorems and equations that generalize to any rule or any quantity of values. +Another nice reason is that matrices are cpu/gpu friendly; +computers take advantage of matrices to speed up processing their expressions. + +=== How to create a matrix in Boost.uBlas ? + +---- +#include +#include + +int main () { + using namespace boost::numeric::ublas; + matrix m (3, 3); + for (unsigned i = 0; i < m.size1 (); ++ i) + for (unsigned j = 0; j < m.size2 (); ++ j) + m (i, j) = 3 * i + j; + std::cout << m << std::endl; +} +---- + +== Boost.uBlas Tensor + +In mathematics, a tensor is an algebraic object that describes a multilinear relationship between sets of algebraic objects related to a vector space. +Objects that tensors may map between include vectors and scalars, and even other tensors. +There are many types of tensors, including scalars and vectors, dual vectors, multilinear maps between vector spaces, and even some operations such as the dot product. +Tensors are defined independent of any basis, although they are often referred to by their components in a basis related to a particular coordinate system. +Tensors have become important in physics because they provide a concise mathematical framework for formulating and solving physics problems in areas such as mechanics, electrodynamics, or general relativity and others. +In applications, it is common to study situations in which a different tensor can occur at each point of an object; + +=== Why a Tensor ? + +One way to understand the importance of tensor calculus is to consider geometric complications when drawing right angles. +If you are developing a system that uses the flat-earth model, you can draw right angles using the Pythagorean Theorem. +The limits of the Pythagorean Theorem become clear when you try to draw a right angle on a spherical surface. +In this case, the Pythagorean Theorem no longer works. +It's here that the metric tensor comes to the rescue. +It generalizes coordinates and geometries so that distance can be measured in any given space. +The magic of tensors comes from their special transformational properties that enable them to describe the same physics in all reference frames. + +Think of a tensor as a multi-linear map. +Given a set of coordinates (or expand out to functions or other objects), each of these coordinates can be transformed according to a set of rules (linear transformations) into a new set of coordinates. +The key here is that each coordinate can have a unique transformation. +For example, you can stretch or distort different coordinates in different ways. +If we take a rectangular piece of bubble gum with edges on the x, y, and z-axes, and then squeeze the bubble gum on the x-axis (one-dimension input), the x dimension will compress a certain amount, while the y and z dimensions will expand a given amount. +This results in output changes in three dimensions while maintaining a constant volume. +Assuming a linearity of the squeezing reaction, the behavior can also be calculated using a metric tensor if the gum is squeezed off-axis. + +=== How to create a tensor in Boost.uBlas ? + +---- +#include + +int main () { + using namespace boost::numeric::ublas; + tensor t{4,2,3}; + for (auto k = 0ul; k < t.size (2); ++ k) + for (auto j = 0ul; j < t.size (1); ++ j) + for (auto i = 0ul; i < t.size (0); ++ i) + t.at(i,j,k) = 3*i + 2*j + 5*k; + + std::cout << t << std::endl; +} +---- diff --git a/doc/ublas/types_overview.adoc b/doc/ublas/types_overview.adoc index 00c7220af..b094d1492 100644 --- a/doc/ublas/types_overview.adoc +++ b/doc/ublas/types_overview.adoc @@ -1,7 +1,5 @@ == Overview of Tensor, Matrix- and Vector Types -[[toc]] - Contents: + link:#vectors[Vectors] @@ -341,12 +339,3 @@ The storage layout usually is BLAS compliant. coordinate matrix, orientation is column major. + The storage layout usually is BLAS compliant. |=== - -''''' - -Copyright (©) 2000-2004 Joerg Walter, Mathias Koch, Gunter Winkler, -Michael Stevens + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/unbounded_array.adoc b/doc/ublas/unbounded_array.adoc index a64b2368e..6164102ca 100644 --- a/doc/ublas/unbounded_array.adoc +++ b/doc/ublas/unbounded_array.adoc @@ -1,9 +1,5 @@ == Unbounded Array Storage -[[toc]] - -=== [#unbounded_array]#Unbounded Array# - ==== Description The templated class `unbounded_array` implements a unbounded @@ -130,18 +126,10 @@ of the concept. |`const_reverse_iterator rbegin () const` |https://www.boost.org/sgi/stl/ReversibleContainer.html[ReversibleContainer] |Returns a `const_reverse_iterator` pointing to the beginning of the reversed `unbounded_array`. -|`const_reverse_iterator rend () const` |https://www.boost.org/sgi/stl/ReversibleContainer.html[ReversibleContainer] |Returns a `const_reverse_iterator` pointing to the end of the reversed `unbounded_array`. +|`const_reverse_iterator rend () const` |https://www.boost.org/sgi/stl/ReversibleContainer.html[ReversibleContainer] |Returns a `const_reverse_iterator` pointing to the end of the reversed `unbounded_array`. |`reverse_iterator rbegin ()` |https://www.boost.org/sgi/stl/ReversibleContainer.html[ReversibleContainer] |Returns a `reverse_iterator` pointing to the beginning of the reversed `unbounded_array`. |`reverse_iterator rend ()` |https://www.boost.org/sgi/stl/ReversibleContainer.html[ReversibleContainer] |Returns a `reverse_iterator` pointing to the end of the reversed `unbounded_array`. |=== - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/vector-index.adoc b/doc/ublas/vector-index.adoc new file mode 100644 index 000000000..c3ed03a67 --- /dev/null +++ b/doc/ublas/vector-index.adoc @@ -0,0 +1,29 @@ +//// +Copyright 2021 Shikhar Vashistha + +Distributed under the Boost Software License, Version 1.0. +(http://www.boost.org/LICENSE_1_0.txt) +//// + +# Vector +:toc: left +:toclevels: 2 +:idprefix: +:listing-caption: Code Example +:docinfo: private-footer +:source-highlighter: rouge +:source-language: c++ + +:leveloffset: +1 + + +include::vector.adoc[] + +include::vector_sparse.adoc[] + +include::vector_proxy.adoc[] + +include::vector_expression.adoc[] + + +:leveloffset: -1 \ No newline at end of file diff --git a/doc/ublas/vector.adoc b/doc/ublas/vector.adoc index d395d44fc..8b4e1a2db 100644 --- a/doc/ublas/vector.adoc +++ b/doc/ublas/vector.adoc @@ -1,8 +1,5 @@ -== Vector +== Vector Abstract -[[toc]] - -=== [#vector]#Vector# ==== Description @@ -545,11 +542,3 @@ the end of the `scalar_vector`. `const_reverse_iterator` pointing to the end of the reversed `scalar_vector`. |=== - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). diff --git a/doc/ublas/vector_expression.adoc b/doc/ublas/vector_expression.adoc index 6ae7bbf3c..a0bcca8bf 100644 --- a/doc/ublas/vector_expression.adoc +++ b/doc/ublas/vector_expression.adoc @@ -1,8 +1,5 @@ == Vector Expressions -[[toc]] - -=== [#vector_expression]#Vector Expression# ==== Description @@ -902,12 +899,4 @@ int main () { std::cout << inner_prod (v1, v2) << std::endl; } -.... - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). +.... \ No newline at end of file diff --git a/doc/ublas/vector_proxy.adoc b/doc/ublas/vector_proxy.adoc index f230c7da6..cbb34585a 100644 --- a/doc/ublas/vector_proxy.adoc +++ b/doc/ublas/vector_proxy.adoc @@ -1,6 +1,5 @@ == Vector Proxies -[[toc]] === [#vector_range]#Vector Range# @@ -432,12 +431,4 @@ int main () { project (v, slice (0, 1, 3)) (i) = i; std::cout << project (v, slice (0, 1, 3)) << std::endl; } -.... - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ). +.... \ No newline at end of file diff --git a/doc/ublas/vector_sparse.adoc b/doc/ublas/vector_sparse.adoc index e22d11cfd..b88685d9d 100644 --- a/doc/ublas/vector_sparse.adoc +++ b/doc/ublas/vector_sparse.adoc @@ -1,6 +1,5 @@ == Sparse Vector -[[toc]] === [#mapped_vector]#Mapped Vector# @@ -541,11 +540,3 @@ the end of the reversed `coordinate_vector`. [#coordinate_vector_2]#[2]# Supported parameters for the adapted array are `unbounded_array<>` , `bounded_array<>` and `std::vector<>` . - -''''' - -Copyright (©) 2000-2002 Joerg Walter, Mathias Koch + -Copyright (©) 2021 Shikhar Vashistha + -Use, modification and distribution are subject to the Boost Software -License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at -http://www.boost.org/LICENSE_1_0.txt ).