Skip to content

Commit

Permalink
Merge pull request #16 from abhimhamane/106-prereview
Browse files Browse the repository at this point in the history 
removed indentation, consolodated theory into single section
  • Loading branch information
@abhimhamane
abhimhamane authored Apr 26, 2024
2 parents bbb0423 + 33b0625 commit 44891eb
Show file tree
Hide file tree
Showing 5 changed files with 291 additions and 293 deletions.
112 changes: 56 additions & 56 deletions docs/contributing.md
View file
Original file line number Diff line number Diff line change
@@ -1,102 +1,102 @@
# Contributing

Contributions are welcome, and they are greatly appreciated! Every
little bit helps, and credit will always be given.
Contributions are welcome, and they are greatly appreciated! Every
little bit helps, and credit will always be given.

You can contribute in many ways.
You can contribute in many ways.

## Types of Contributions

### Report Bugs

Report bugs at <https://github.com/mn5hk/pyshbundle/issues>.
Report bugs at <https://github.com/mn5hk/pyshbundle/issues>.

If you are reporting a bug, please include:
If you are reporting a bug, please include:

- Your operating system name and version.
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.
- Your operating system name and version.
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.

### Found Bugs!!!

Look through the GitHub issues for bugs. Anything tagged with `bug` and
`help wanted` is open to whoever wants to implement it.
Look through the GitHub issues for bugs. Anything tagged with `bug` and
`help wanted` is open to whoever wants to implement it.

### Want New Functionality?

Look through the GitHub issues for features. Anything tagged with
`enhancement` and `help wanted` is open to whoever wants to implement it.
Look through the GitHub issues for features. Anything tagged with
`enhancement` and `help wanted` is open to whoever wants to implement it.

### Let's Improve Documentation

pyshbundle could always use more documentation,
whether as part of the official pyshbundle docs,
in docstrings, or even on the web in blog posts, articles, and such.<br>
pyshbundle could always use more documentation,
whether as part of the official pyshbundle docs,
in docstrings, or even on the web in blog posts, articles, and such.<br>

Another prefered way is to create explainatory tutorials. Using the `PySHBundle` functions to explain the `Spherical Harmonics` and `GRACE Data Processing`.
Another prefered way is to create explainatory tutorials. Using the `PySHBundle` functions to explain the `Spherical Harmonics` and `GRACE Data Processing`.

### Feedback

The best way to send feedback is to file an issue at
<https://github.com/mn5hk/pyshbundle/issues>.
The best way to send feedback is to file an issue at
<https://github.com/mn5hk/pyshbundle/issues>.

If you are proposing a feature:
If you are proposing a feature:

- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Remember that this is a volunteer-driven project, and that contributions are welcome :)
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Remember that this is a volunteer-driven project, and that contributions are welcome :)

## Get Started!

Ready to contribute? Here's how to set up pyshbundle for local development.
Ready to contribute? Here's how to set up pyshbundle for local development.

1. Fork the pyshbundle repo on GitHub.
1. Fork the pyshbundle repo on GitHub.

2. Setup a seperate development environment.
```shell
# clone the repo and fetch the dev branch
$ git clone [email protected]:mn5hk/pyshbundle.git
2. Setup a seperate development environment.
```shell
# clone the repo and fetch the dev branch
$ git clone [email protected]:mn5hk/pyshbundle.git

# creating a new virtual environment
$ python3 -m venv <name-env>
# creating a new virtual environment
$ python3 -m venv <name-env>

# install the dependencies from the requirements-dev file
$ pip install -r ../pyshbundle/requirements-dev.txt
# install the dependencies from the requirements-dev file
$ pip install -r ../pyshbundle/requirements-dev.txt

# activate the virtual environment environment
$ source </location-of-virt-env/name-env/bin/activate>
```
# activate the virtual environment environment
$ source </location-of-virt-env/name-env/bin/activate>
```

3. Build the latest repo in the development virtual environment.
```shell
# install package into virtual environment
$ pip install ../pyshbundle/dist/<required-version>.tar.gz
3. Build the latest repo in the development virtual environment.
```shell
# install package into virtual environment
$ pip install ../pyshbundle/dist/<required-version>.tar.gz
# you also have the option to build the module using, be careful of
$ python setup.py sdist
```
# you also have the option to build the module using, be careful of
$ python setup.py sdist
```


4. Create a branch for local development:
4. Create a branch for local development:

```shell
$ git checkout -b name-of-your-bugfix-or-feature
```
```shell
$ git checkout -b name-of-your-bugfix-or-feature
```

Now you can make your changes lo cally.
Now you can make your changes lo cally.

5. Commit your changes and push your branch to GitHub:
5. Commit your changes and push your branch to GitHub:

```shell
$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature
```
```shell
$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature
```

6. Submit a pull request through the GitHub website.
6. Submit a pull request through the GitHub website.

## Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:
Before you submit a pull request, check that it meets these guidelines:

TBD...
TBD...
48 changes: 0 additions & 48 deletions docs/convert_data_formats.md
View file
Original file line number Diff line number Diff line change
@@ -1,53 +1,5 @@
# Convert Data Formats

Spherical harmonic functions or coefficients, Legendre functions and their derivatives can be arranged in different ways. There are multiple functions in SHBundle for reordering from one format to another. Some of them have been translated to Python in PySHBundle. Couple of new ones have also been added.

## Spherical Harmonics Data Formats

### clm-format

This is a standard format to store spherical harmonic coefficients in the indexed column-vector-format (abbreviatedL clm-format)

\begin{equation}
\left( n, m, \overline{C}_{n, m}, \overline{S}_{n, m}, \left[ \sigma_{\overline{C}_{n, m}}, \sigma_{\overline{S}_{n, m}} \right] \right)
\end{equation}

The first column represents the degree $n$, the second column represents the order $m$ (both n,m are integers), followed by the coefficients $\overline{C}_{n, m}, \overline{S}_{n, m}$ and the last two columns contain their respective standard deviations $\sigma_{\overline{C}_{n, m}}, \sigma_{\overline{S}_{n, m}}$

### klm-format

This is a variation of the clm-format for compact notation with just 3 or 4 columns. The coefficients are sorted first w.r.t. degree and then the order, particularly the sine-coefficients are arranged starting first with negative orders. The following matrix represents the klm-format:

```math
\begin{bmatrix}
0 & 0 & \overline{C}_{0, 0} & \sigma_{\overline{C}_{0, 0}} \\
0 & 0 & \overline{C}_{0, 0} & \sigma_{\overline{C}_{0, 0}} \\
0 & 0 & \overline{C}_{0, 0} & \sigma_{\overline{C}_{0, 0}} \\
0 & 0 & \overline{C}_{0, 0} & \sigma_{\overline{C}_{0, 0}} \\
0 & 0 & \overline{C}_{0, 0} & \sigma_{\overline{C}_{0, 0}} \\
0 & 0 & \overline{C}_{0, 0} & \sigma_{\overline{C}_{0, 0}} \\
0 & 0 & \overline{C}_{0, 0} & \sigma_{\overline{C}_{0, 0}} \\
0 & 0 & \overline{C}_{0, 0} & \sigma_{\overline{C}_{0, 0}} \\
0 & 0 & \overline{C}_{0, 0} & \sigma_{\overline{C}_{0, 0}} \\
\vdots & & & \vdots \\
N_{max} & N_{max} & \overline{C}_{N_{max}, N_{max}} & \sigma_{\overline{C}_{N_{max}, N_{max}}} \\
\begin{bmatrix}
```

### $\left | C \backslash S \right |$-format

This is another well known arrangement of Spherical Harmonic coefficients. This is a square matrix of size $n_{max}, n_{max}$.

The lower traingular terms are made of the cosine terms


### $\left / S | C \right \backslash$-format

This is yet another popular format where the sine-coefficients are flipped from left to right, to obtain a triangular arrangement which is completed by zeros.

The following figure illustrates the $\left | C \backslash S \right |$ and $\left / S | C \right \backslash$ format respectively.

![Spherical Harmonic Formats](img/sh_formats.png)

::: pyshbundle.cs2sc
::: pyshbundle.sc2cs
Expand Down
161 changes: 5 additions & 156 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,13 @@
# Welcome to PySHbundle


[![image](https://img.shields.io/pypi/v/pyshbundle.svg)](https://pypi.python.org/pypi/pyshbundle)


**PySHbundle: A Python implementation of MATLAB codes SHbundle**

Our package, `PySHbundle` has been developed in a modularized manner. The package provides tools to process GRACE data, such as, the computation of anomalies, substitution of poor quality low degree coefficients, reducing noise in GRACE data using filtering approaches, signal leakage correction using `GDDC`, etc. In addition, the package provides a flexibility for future development and addition of further processing choices for handling GRACE data for hydrological application.<br>

- Free software: GNU General Public License v3
- Documentation: <https://mn5hk.github.io/pyshbundle>

It is hoped the contribution will make GRACE L2 data processing more accessible to a wider audience of young researchers. Our python package is titled `PySHbundle` and the working code can be accessed at [GitHub](https://github.com/mn5hk/pyshbundle). <br>


## How to install <br>
Expand All @@ -27,163 +25,14 @@ $ git clone [email protected]:mn5hk/pyshbundle.git
For more details refer to the installation section.


Convert [SHbundle matlab codes](https://www.gis.uni-stuttgart.de/en/research/downloads/shbundle/) to python<br>
[Geodesy for Earth system science (GESS) research Group at ICWaR, IISc](https://ultra-pluto-7f6d1.netlify.app/)
![](https://visitor-badge.glitch.me/badge?page_id=mn5hk.mat2py)


### Mathematics

In this section, we present a mathematical representation of the spherical harmonics analysis. According to potential theory, the gravitational field of a body fulfils the Laplace equation $\nabla^2\phi = 0$. Laplace's equation in spherical coordinates can be written as follows:

\begin{equation}
\frac{1}{r^2}\frac{\partial}{\partial r}\bigg( r^2\frac{\partial \phi}{\partial r}\bigg)
+
\frac{1}{r^2\sin\vartheta}\frac{\partial}{\partial \vartheta}\bigg(\sin\vartheta\frac{\partial \phi}{\partial \vartheta}\bigg)
+
\frac{1}{r^2\sin^2\vartheta}\frac{\partial^2 \phi}{\partial \lambda^2}
= 0 ,
\end{equation}


where
$\phi$ is the potential,
$r$ is the radius,
$\vartheta$ is the co-latitude and
$\lambda$ is the longitude.

We perform a separation of variables and insert $\phi(r, \vartheta, \lambda) =f(r)g(\vartheta)h(\lambda)$ into the Laplace equation to get three independent equations:


\begin{equation}
r^2\frac{d^2f}{dr^2}+2r\frac{df}{dr} - n(n+1)f = 0,
\end{equation}



\begin{equation}
\frac{d^2g}{d\vartheta^2}
+
\frac{dg}{d\vartheta}\cot\vartheta
+
\bigg( n(n+1) - \frac{m^2}{\sin^2\vartheta} \bigg) g = 0 ,
\end{equation}



\begin{equation}
\frac{d^2h}{d\lambda^2} + m^2h = 0,
\end{equation}


where $m$ and $n$ are the degree and order respectively. Solving $(2), (3)$ and $(4)$, we obtain:


\begin{equation}
f(r) \in \{r^n, r^{-(n+1)}\},
\end{equation}



\begin{equation}
g(\vartheta) \in \{P_{n,m}(\cos \vartheta), Q_{n,m}(\cos \vartheta)\} ,
\end{equation}

## Group


\begin{equation}
h(\lambda) \in \{\cos m\lambda, \sin m\lambda\}.
\end{equation}\\


Thus, the Laplace equation's solution takes the following form:


\begin{equation}
\phi(r, \vartheta, \lambda) = \sum_{n=0}^{\infty} \sum_{m=0}^{n}
\alpha_{n,m}
\begin{Bmatrix}
P_{n,m}(\cos\vartheta)\\
Q_{n,m}(\cos\vartheta)\\
\end{Bmatrix}
\dot{•}
\begin{Bmatrix}
\cos m\lambda\\
\sin m\lambda\\
\end{Bmatrix}
\dot{•}
\begin{Bmatrix}
r^n\\
r^{(n+1)}\\
\end{Bmatrix}
.
\end{equation}


Solutions for $f(r)$ and $h(\lambda)$ are fairly straightforward. Eq - (3) for $g(\vartheta)$ is in the form of a Legendre differential equation and its solutions are $P_{n,m}(\cos \vartheta)$ and $Q_{n,m}(\cos \vartheta)$, the associated Legendre functions of the first and second kind. We now apply two constraints to the solution:

* $\phi \rightarrow 0$ when $r \rightarrow \infty$,
* $\phi$ is limited on the sphere,

which leads us to eliminate $Q_{n,m}(\cos \vartheta)$ and $r^n$.The $4\pi$ normalization of the Associated Legendre functions [8] is utilized in our package and is given by:


\begin{equation}
\bar{P}_{n,m}(\cos\vartheta) = P_{n,m}(\cos\vartheta)\sqrt{(2-\delta_{m0})(2n+1)\frac{(n-m)!}{(n+m)!}},
\end{equation}

where $\delta_{m0}$ is the Kronecker delta function,

\begin{equation}
P_{n,m}(t) = (1-t^2)^{\frac{m}{2}}\frac{d^mP_n(t)}{dt^m},
\end{equation}

and

\begin{equation}
nP_n(t)=-(n-1)P_{n-2}(t) + (2n-1)tP_{n-1}(t).
\end{equation}


Spherical harmonics are the angular portion of a set of solutions to Laplace's equation. They take into account $\vartheta$ and $\lambda$. They are functions modelled on the surface of a sphere, denoted by $Y_{n,m}(\vartheta,\lambda)$. They are of three kinds:

* Zonal harmonics: $m=0$ - they are only latitude dependent,
* Tesseral harmonics: $0 < m < n$, and
* Sectorial harmonics: $m=n$.

Quantities like the gravitational potential, height of water column, gravity anomaly and so on are the functionals of the gravity field which are obtained by differentiating the potential $\phi$ with respect to the spherical coordinates.

The gravitational potential anomaly $V$ is given by:


\begin{equation}
V(r, \vartheta, \lambda) =
\frac{GM}{r} \sum_{n=0} ^{N_{max}} \sum_{m=0} ^{n}
\left(\frac{R}{r}\right) ^{n+1}
\bar{P}_{n,m}(\cos \vartheta) [C_{n,m}\cos m\lambda+S_{n,m}\sin m\lambda].
\end{equation}


Here, $R$ refers to the radius of the Earth,
$\bar{P}_ {n,m}$ refers to the Associated Legendre functions with $4\pi$ normalization,
$C_{lm}$ and $S_{lm}$ refer to the spherical harmonic coefficients. Similarly, another functional, the change in surface mass density, is represented by:
[Geodesy for Earth system science (GESS) research Group at ICWaR, IISc](https://ultra-pluto-7f6d1.netlify.app/)


\begin{equation}
\Delta\sigma(\vartheta, \lambda) =
\frac{a\rho_{ave}}{3}
\sum_{n=0}^{N_{max}}\sum_{m=0}^{n}
\left(\frac{R}{r}\right)^{n+1}
\bar{P}_{n,m}(\cos\vartheta)
\frac{2n+1}{1+k_l}
[C_{n,m}\cos m\lambda + S_{n,m}\sin m\lambda],
\end{equation}


where
$\rho_{ave}$ refers to the average density of the Earth in $g/cm^3$ and
$k_n$ refers to the load Love number of degree $n$.

## Credits
### Credits for the theme

This package was created with [Cookiecutter](https://github.com/cookiecutter/cookiecutter) and the [giswqs/pypackage](https://github.com/giswqs/pypackage) project template.
Loading

0 comments on commit 44891eb

Please sign in to comment.