Linear Algebra chapter added

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.

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 <https://wg21.link/P1385>`_
+    and its latest implementation from `GitHub <https://github.com/BobSteagall/wg21>`_
+    or `Conan <https://bintray.com/twonington/public-conan/linear_algebra%3Apublic-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<si::length<si::metre>, 3> v = { 1q_m, 2q_m, 3q_m };
+    fs_vector<si::length<si::metre>, 3> u = { 3q_m, 2q_m, 1q_m };
+    fs_vector<si::length<si::kilometre>, 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<si::length<si::metre>>(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<si::metre, fs_vector<int, 3>> v(fs_vector<int, 3>{ 1, 2, 3 });
+    si::length<si::metre, fs_vector<int, 3>> u(fs_vector<int, 3>{ 3, 2, 1 });
+    si::length<si::kilometre, fs_vector<int, 3>> t(fs_vector<int, 3>{ 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.

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<si::length<si::metre>>(t) = " << vector<si::length<si::metre>>(t) << "\n";
+  std::cout << "t[m]  = " << vector<si::length<si::metre>>(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<si::length<si::millimetre>>(v) =\n" << matrix<si::length<si::millimetre>>(v) << "\n";
+  // std::cout << "v[mm] =\n" << matrix<si::length<si::millimetre>>(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<si::metre>(t) = " << quantity_cast<si::metre>(t) << "\n";
+  std::cout << "t[m]  = " << quantity_cast<si::metre>(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<si::length<si::millimetre>>(v) =\n" << matrix<si::length<si::millimetre>>(v) << "\n";
+//   // std::cout << "v[mm] =\n" << matrix<si::length<si::millimetre>>(v) << "\n";
 // }
 
 // void quantity_of_matrix_multiply_same()