diff --git a/docs/use_cases/custom_representation_types.rst b/docs/use_cases/custom_representation_types.rst index f5d39476..60d66095 100644 --- a/docs/use_cases/custom_representation_types.rst +++ b/docs/use_cases/custom_representation_types.rst @@ -301,4 +301,4 @@ representation types with:: .. seealso:: For more examples of custom representation types usage please refer to the - :ref:`Linear Algebra of Quantities` chapter and :ref:`measurement` example. + :ref:`Linear Algebra vs. Quantities` chapter and the :ref:`measurement` example. diff --git a/docs/use_cases/linear_algebra.rst b/docs/use_cases/linear_algebra.rst index d8451387..402f3851 100644 --- a/docs/use_cases/linear_algebra.rst +++ b/docs/use_cases/linear_algebra.rst @@ -1,5 +1,87 @@ .. namespace:: units -Linear Algebra of Quantities -============================ +Linear Algebra vs. Quantities +============================= +Even though **mp-units** library does not implement any Linear Algebra types it is generic +enough to be used with other Linear Algebra libraries existing on the market. + +.. note:: + + All of the examples provided in this chapter refer to the official proposal of the + Linear Algebra Library for the C++23 defined in `P1385 `_ + and its latest implementation from `GitHub `_ + or `Conan `_. + Also, to simplify the examples all of them assume:: + + using namespace std::experimental::math; + + +Linear Algebra of Quantities +---------------------------- + +The official :term:`quantity` definition states: + + *A quantity as defined here is a scalar. However, a vector or a tensor, the components of + which are quantities, is also considered to be a quantity.* + +So the most common use case would be to create a vector or matrix of quantities:: + + fs_vector, 3> v = { 1q_m, 2q_m, 3q_m }; + fs_vector, 3> u = { 3q_m, 2q_m, 1q_m }; + fs_vector, 3> t = { 3q_km, 2q_km, 1q_km }; + +Having such definitions we can perform full dimensional analysis operations for the operations +allowed by the Linear Algebra rules. For example:: + + std::cout << "v + u = " << v + u << "\n"; + std::cout << "v + t = " << v + t << "\n"; + std::cout << "t[m] = " << vector>(t) << "\n"; + std::cout << "v * u = " << v * u << "\n"; + std::cout << "2q_m * v = " << 2q_m * v << "\n"; + +The above code works as expected and produces the following output: + +.. code-block:: text + + v + u = | 4 m 4 m 4 m | + v + t = | 3001 m 2002 m 1003 m | + t[m] = | 3000 m 2000 m 1000 m | + v * u = 10 m² + 2q_m * v = | 2 m² 4 m² 6 m² | + + +Quantities of Linear Algebra Types +---------------------------------- + +The previous chapter should address most of the Linear Algebra related requirements. +However, it is also possible to use Linear Algebra entities as custom representation +types provided to a `quantity` class template. + +.. seealso:: + + More information on providing custom representation types for `quantity` can be + found in the :ref:`Using Custom Representation Types` chapter. + +With this the above vector definitions can be rewritten as follows:: + + si::length> v(fs_vector{ 1, 2, 3 }); + si::length> u(fs_vector{ 3, 2, 1 }); + si::length> t(fs_vector{ 3, 2, 1 }); + +Now the same code doing basic Linear Algebra operations will provide the following +output: + +.. code-block:: text + + v + u = | 4 4 4 | m + v + t = | 3001 2002 1003 | m + t[m] = | 3000 2000 1000 | m + v * u = 10 m² + 2q_m * v = | 2 4 6 | m² + + +.. seealso:: + + For more examples of Linear Algebra definition and operations please refer to + the :ref:`linear_algebra` example. \ No newline at end of file diff --git a/example/linear_algebra.cpp b/example/linear_algebra.cpp index 478394f1..76fdf2c8 100644 --- a/example/linear_algebra.cpp +++ b/example/linear_algebra.cpp @@ -79,7 +79,7 @@ void vector_of_quantity_add() std::cout << "v + u = " << v + u << "\n"; std::cout << "v + t = " << v + t << "\n"; - std::cout << "vector>(t) = " << vector>(t) << "\n"; + std::cout << "t[m] = " << vector>(t) << "\n"; } void vector_of_quantity_multiply_same() @@ -92,7 +92,7 @@ void vector_of_quantity_multiply_same() std::cout << "v = " << v << "\n"; std::cout << "u = " << u << "\n"; - std::cout << "v * u = " << v * u << "\n"; + std::cout << "v * u = " << v * u << "\n"; std::cout << "2q_m * v = " << 2q_m * v << "\n"; } @@ -106,9 +106,9 @@ void vector_of_quantity_multiply_different() std::cout << "v = " << v << "\n"; std::cout << "u = " << u << "\n"; - std::cout << "v * u = " << v * u << "\n"; + std::cout << "v * u = " << v * u << "\n"; std::cout << "2q_N * u = " << 2q_N * u << "\n"; - std::cout << "2 * u = " << 2 * u << "\n"; + std::cout << "2 * u = " << 2 * u << "\n"; } void vector_of_quantity_divide_by_scalar() @@ -148,7 +148,7 @@ void matrix_of_quantity_add() std::cout << "v + t =\n" << v + t << "\n"; // TODO Uncomment when fixed in the LA lib - // std::cout << "matrix>(v) =\n" << matrix>(v) << "\n"; + // std::cout << "v[mm] =\n" << matrix>(v) << "\n"; } void matrix_of_quantity_multiply_same() @@ -221,7 +221,7 @@ void quantity_of_vector_add() std::cout << "v + u = " << v + u << "\n"; std::cout << "v + t = " << v + t << "\n"; - std::cout << "quantity_cast(t) = " << quantity_cast(t) << "\n"; + std::cout << "t[m] = " << quantity_cast(t) << "\n"; } void quantity_of_vector_multiply_same() @@ -234,7 +234,7 @@ void quantity_of_vector_multiply_same() std::cout << "v = " << v << "\n"; std::cout << "u = " << u << "\n"; - std::cout << "v * u = " << v * u << "\n"; + std::cout << "v * u = " << v * u << "\n"; std::cout << "2q_m * v = " << 2q_m * v << "\n"; } @@ -248,9 +248,9 @@ void quantity_of_vector_multiply_different() std::cout << "v = " << v << "\n"; std::cout << "u = " << u << "\n"; - std::cout << "v * u = " << v * u << "\n"; + std::cout << "v * u = " << v * u << "\n"; std::cout << "2q_N * u = " << 2q_N * u << "\n"; - std::cout << "2 * u = " << 2 * u << "\n"; + std::cout << "2 * u = " << 2 * u << "\n"; } void quantity_of_vector_divide_by_scalar() @@ -293,7 +293,7 @@ void quantity_of_vector_tests() // std::cout << "v + t =\n" << v + t << "\n"; // // TODO Uncomment when fixed in the LA lib -// // std::cout << "matrix>(v) =\n" << matrix>(v) << "\n"; +// // std::cout << "v[mm] =\n" << matrix>(v) << "\n"; // } // void quantity_of_matrix_multiply_same()