forked from GESS-research-group/pyshbundle
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #16 from abhimhamane/106-prereview
removed indentation, consolodated theory into single section
- Loading branch information
Showing
5 changed files
with
291 additions
and
293 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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... |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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> | ||
|
@@ -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. |
Oops, something went wrong.