Adding Covariant/Contravariant Vector Documentation and Visualization

docs/src/math_framework.md

@@ -74,6 +74,58 @@ while the _contravariant basis_ is the opposite: gradient in ``x`` of the coordi
 \mathbf{e}^i = \nabla_x \xi^i
 ```
 
+Here is an intuitive example of how the _contravariant basis_ and _covariant basis_ changes when a coordinate is being transformed.
+
+![Different bases supported in ClimaCore.jl](controva_cova.png)
+
+Start with the _contravariant basis_, which is the case that most of us is more familier. As it can be seen in the figure below, we have 2D vector $\vec{a}$, 
+and two unit vectors $\vec{e_{1}}$ and $\vec{e_{2}}$, served as two basis. Thus we can represent vector $\vec{a}$ as:
+```math
+\vec{a} = a^{1} \vec{e_{1}} + a^{2} \vec{e_{2}}
+```
+
+And now we set amplify one of the basis $\vec{a}$ by 2 times, that is $\vec{e_{1}}^{'} = 2\vec{e_{1}}$. If we want to maintain the vector $\vec{a}$ to stay still, 
+obviously we need to set $a^{1}$ to its half:
+```math
+a^{1'}  = \frac{1}{2} a^{1}
+```
+
+With this being said, the components we use to describe a certain vector are changing in the opposite manner of the the basis, and we are calling these 
+components _contravariant components_. The _contravariant vector_ is a vector with _contravariant components_. 
+
+Now consider the _covariant basis_. We still have a 2D vector, but calling it $\vec{b}$. So if with the unit vectors $\vec{e_{1}}$ and $\vec{e_{2}}$, we can still 
+represent vector $\vec{b}$ in a "controvariant component" manner:
+```math
+\vec{b} = b^{1} \vec{e_{1}} + b^{2} \vec{e_{2}}
+```
+
+Then we try to project vector $\vec{b}$ onto the two unit vectors, and we have the following:
+```math
+b_{1} = \vec{b}\cdot  \vec{e_{1}}
+```
+```math
+b_{2} = \vec{b}\cdot  \vec{e_{2}}
+```
+
+If we plug $\vec{b} = b^{1} \vec{e_{1}} + b^{2} \vec{e_{2}}$ into the above two equations, we can have:
+```math
+b_{1} = \vec{b}\cdot  \vec{e_{1}} = b^{1} \vec{e_{1}} \cdot \vec{e_{1}}+ b^{2} \vec{e_{2}}\cdot \vec{e_{1}} 
+```
+```math
+b_{2} = \vec{b}\cdot  \vec{e_{2}} = b^{2} \vec{e_{2}} \cdot \vec{e_{1}}+ b^{2} \vec{e_{2}}\cdot \vec{e_{2}} 
+```
+
+And in this case, if we still amplify one of the basis $\vec{a}$ by 2 times, it is not difficult to find that $b_{1}$ would also be amplified by 2 times!
+```math
+b_{1}^{'} = b^{1} \vec{e_{1}}^{'} \cdot \vec{e_{1}}+ b^{2} \vec{e_{2}}\cdot \vec{e_{1}}^{'} = 2 (b^{1} \vec{e_{1}} \cdot \vec{e_{1}}+ b^{2} \vec{e_{2}}\cdot \vec{e_{1}} )
+```
+
+In this case, the components of this vector are changing in the same manner of the the basis, and we are calling these 
+components _covariant components_. The _covariant vector_ is a vector with _covariant components_. 
+
+To summarize, from what we can see from the figure as well, parallel projections would lead to controvariant components, while perpendicular projection would lead to covariant components.
+
+
 
 **Note**:
 
@@ -85,6 +137,9 @@ while the _contravariant basis_ is the opposite: gradient in ``x`` of the coordi
 
 * things get a little more complicated in the presence of terrain, but ``\xi^3`` is radially aligned
   - the 3rd covariant component is aligned with W, but the 3rd contravariant component may not be (e.g. at the surface it is normal to the boundary).
+
+
+
 
 ### Cartesian bases
 Analogously to `CartesianPoint`s, in ClimaCore, there are also `CartesianVector`s: