Adding Covariant/Contravariant Vector Documentation and Visualization

.gitignore

@@ -44,4 +44,4 @@ docs/src/tutorials/
 *.gif
 *.gz
 *.mp4
-*.png
+# *.png

docs/src/math_framework.md

@@ -62,6 +62,19 @@ then may want to consider different bases, as not all operators accept all bases
 _Covariance_ and _contravariance_ describe how the quantitative description of
 certain geometric or physical entities changes with a change of basis.
 
+More specifically, 
+
+__Covariant objects__ —whether you mean covariant components (the coefficients that sit in front of the basis) 
+or the covariant basis vectors themselves—co-vary with the coordinate grid. In other words, when you change coordinates, 
+these quantities transform in the same way as the coordinate differentials. By convention they carry lower indices (subscripts).
+
+__Contravariant objects__—whether you mean contravariant components or the contravariant basis vectors—vary contra 
+to the coordinate grid. That is, they transform in the opposite way to the coordinate differentials so as to keep 
+tensorial expressions invariant. By convention they carry upper indices (superscripts).
+
+In ClimaCore.jl, `CovariantVector`s are aligned with the _contravariant basis vectors_, but have _covariant components_. 
+Conversely, `ContravariantVector`s are aligned with the _covariant basis vectors_, but have _contravariant components_. 
+
 In ClimaCore.jl, the _covariant basis_ is specified by the partial derivative
 of the transformation from the reference element ``\xi \in [-1,1]^d`` (where ``d``
 is the dimensionality of the domain ``\Omega``) to ``x`` in the physical space:
@@ -74,6 +87,101 @@ while the _contravariant basis_ is the opposite: gradient in ``x`` of the coordi
 \mathbf{e}^i = \nabla_x \xi^i
 ```
 
+If we plot these basis in a curvilinear space, _Covariant basis_ “ride along” the coordinate surfaces (parallel), 
+while _contravariant basis_ “stick out” of those surfaces (perpendicular). See the plot below:
+
+![normal and tangent](normal_tangent.png)
+
+Here is a visual representation of how vectors can be represented in _contravariant_ and _covariant_ components.
+
+![Different bases](controva_cova.png)
+
+Start with the _contravariant components_, which is exactly the definition of vectors we usually meet. 
+As it can be seen in the figure above, we have a 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_. This case corresponds to the definition of `ContravariantVector`s in ClimaCore.jl. 
+
+Now consider the _covariant components_. 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_. This case corresponds to the definition of `CovariantVector`s in ClimaCore.jl. 
+
+From these two illustrative examples, we can see that parallel projections would lead to controvariant components, 
+while perpendicular projection would lead to covariant components.
+
+As to better connect the original idea of _covariant components_ / _contravariant components_ with the real application in ClimaCore.jl, 
+we bring the case of __polar coordinates__ -- a classic example of a __curvilinear coordinate system__.
+
+First of all, we have the Polar‐to‐Cartesian mapping as following:
+```math
+\vec{r} (r,\theta ) = (r \cos \theta, r \sin \theta)
+```
+
+Then we have the _covariant basis_:
+```math
+\vec{e_{r} } = \frac{\partial \vec{r} }{\partial r}  = \frac{\partial (r \cos \theta, r \sin \theta) }{\partial r} = (\cos \theta, \sin \theta)
+```
+```math
+\vec{e_{\theta} } = \frac{\partial \vec{r} }{\partial \theta }  = \frac{\partial (r \cos \theta, r \sin \theta) }{\partial \theta } = (-r\sin \theta,r \cos \theta)
+```
+
+$\vec{e_{r} }$ represents the direction that is tangent to the "radius direction", and $\vec{e_{\theta} }$ is tangent to the circle curve itself.
+
+And the _contravariant basis_:
+
+since we have $r(x,y) = \sqrt{x^{2} +y^{2}  }$ and $\theta (x,y) = \arctan (\frac{y}{x} )$. Thus,
+
+```math
+\vec{e^{r} } = \nabla r(x,y) = (\frac{x}{\sqrt{x^{2} +y^{2}  }}, \frac{y}{\sqrt{x^{2} +y^{2}  }}) = (\frac{x}{r},\frac{y}{r} ) = (\cos \theta, \sin \theta)
+```
+```math
+\vec{e^{\theta } } = \nabla \theta(x,y) = (\frac{-y}{x^{2} +y^{2}}, \frac{x}{x^{2} +y^{2}})  = (\frac{-\sin \theta}{r} , \frac{\cos \theta}{r})
+```
+
+$\vec{e^{r} }$ represents the direction that is perpendicular to the circle curve, and $\vec{e^{\theta} }$ is perpendicular to the "radius direction".
+
+
+
+
 
 **Note**:
 
@@ -85,6 +193,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: