# Moraine
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
> Modern Radar Interferometry Environment; A simple, stupid InSAR
> postprocessing tool in big data era
This package provide functions for InSAR post-processing which refers as
processing after SAR images co-registration and geocoding. The functions
include PS/DS identification, coherence matrix estimation, phase linking
etc.
<div>
> **Warning**
>
> Due to the heavy dependence on CuPy and CUDA, this package only works
> on device with Nivida GPU.
</div>
<div>
> **Warning**
>
> This package is under intensive development. API is subjected to
> change without any noticement.
</div>
## Principle[^1]
### Simplicity
There is no perfect workflow that always generate satisfactory InSAR
result, mostly due to decorrelation, strong atmospheric artifact and
high deformation gradient. Different methods implemented in different
packages need to be tried which is frustrating especially when the
packages are over-encapsulated and no detailed documentations are
provided. Furthermore, it brings more dirty work when users need to save
intermediate data from one software and prepared them in a designated
format and structure required by another software.
Moraine defines simplicity as *without complex data structure and
over-encapsulation*. Most data in Moraine is just the basic
multi-dimentional array, i.e., [NumPy](https://numpy.org/) array or
[CuPy](https://cupy.dev/) array in memory, or
[Zarr](https://zarr.readthedocs.io/en/stable/) on disk. Instead of
providing a standard workflow as
[StamPS](https://homepages.see.leeds.ac.uk/~earahoo/stamps/) and
[MintPy](https://mintpy.readthedocs.io/en/latest/), Moraine is designed
as a collection of functions that implement specific InSAR processing
techniques and data manipulation infrastructure.
### Modernity
Moraine strives to implement state-of-art InSAR techniques, including
advanced PS/DS identification, phase linking and deep-learning-based
methods.
Moraine also emphasizes performance, especially in this big data era.
Most Moraine functions are implemented with well-optimized GPU code or
OpenMP code. Furthermore, with the support of
[Dask](https://docs.dask.org/en/stable/), Moraine can be runed on
multi-GPUs to further accelerate the processing, get rid of the
limitation of memory and achieve asynchronous IO.
### Pragmatism
Moraine is a pragmatic library rather than an ideological workflow. The
large number of functions in MOraine offer free and open source
implementation for many InSAR techniques. Ultimately, workflow designs
are made on a case-by-case basis by the user. We provide the necessary
infrastructure and your role is to be innovative!
### User centrality
Whereas many InSAR packages attempt to be more user-friendly, Moraine
has always been, and shall always remain user-centric. This package is
intended to fill the needs of those contributing to it, rather than
trying to appeal to as many users as possible. It is targeted at the
proficient InSAR user, or anyone with a do-it-yourself attitude who is
willing to read the documentation, and solve their own problems.
All users are encouraged to participate and contribute to this package.
Reporting bugs and requesting new features by raising a Github
[issue](https://github.com/kanglcn/moraine/issues) is highly valued and
bugs fixing, documentation improving and features implementation by make
a Github [pull request](https://github.com/kanglcn/moraine/pulls) are
very appreciated. Users can also freely ask questions, provide technical
assistance to others or just exchange opinions in the
[discussions](https://github.com/kanglcn/moraine/discussions).
## Install
Because of GPU driver and CUDA Version Compatibility, there is no simple
solution for CUDA related packages installation. Users need to
successfully install
[cupy](https://docs.cupy.dev/en/stable/install.html#installation) and
[dask_cuda](https://docs.rapids.ai/api/dask-cuda/stable/) first.
Here is some tips for installing them. Generally, the cuda driver is
alrealy installed and maintained by the system administrator. Users only
need to determine the right cudatoolkit version. Frist run
``` bash
nvidia-smi
```
It will prints something like:
...
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 525.105.17 Driver Version: 525.105.17 CUDA Version: 12.0 |
|-------------------------------+----------------------+----------------------+
...
The `CUDA Version` is the maxminum cudatoolkit version that supported by
the current CUDA driver. Here we use version 11.8 as an example. Then
you can install the needed `cudatoolkit`, `cupy`, `dask_cuda` by:
``` bash
conda install -c "nvidia/label/cuda-11.8.0" cuda-toolkit
conda install -c conda-forge cupy cuda-version=11.8
conda install -c rapidsai -c conda-forge -c nvidia dask-cuda cuda-version=11.8
```
Then
With conda:
``` bash
conda install -c conda-forge moraine
```
Or with pip:
``` bash
pip install moraine
```
In development mode:
``` bash
git clone git@github.com:kanglcn/moraine.git ./moraine
cd ./moraine
pip install -e '.[dev]'
```
## How to use
Read the [software
architecture](./Introduction/software_architecture.ipynb) for an
overview of the software design. Refer to [Tutorials](./Tutorials) for
the examples. Refer to [API](./API/) and [CLI](./CLI) for the detailed
usage of every functions.
## Contact us
- Most discussion happens on
[GitHub](https://github.com/kanglcn/moraine). Feel free to [open an
issue](https://github.com/kanglcn/moraine/issues/new) or comment on
any open issue or pull request.
- use github
[discussions](https://github.com/kanglcn/moraine/discussions) to ask
questions or leave comments.
## General Guidelines for Making a Pull Request (PR)[^2]
We follow the [git pull request
workflow](https://www.asmeurer.com/git-workflow/) to make changes to our
codebase.
Before you make a PR, have a quick look at the titles of all the
existing issues first. If there is already an issue that matches your
PR, leave a comment there to let us know what you plan to do. Otherwise,
open an issue describing what you want to do.
What should be included in a PR
- Each pull request should consist of a small and logical collection of
changes; larger changes should be broken down into smaller parts and
integrated separately.
- Bug fixes should be submitted in separate PRs.
How to write and submit a PR
- This package is developed with the [nbdev](https://nbdev.fast.ai/), a
notebook-driven development platform. Developers should write or edit
the notebooks rather than the `.py` files. After than, run
`nbdev_export` to export the code in the notebooks to `.py` files and
run `nbdev_clean` to clean the notebooks.
- The github bot to generate docs do not support GPU, so all GPU related
packages (`dask_cuda`) should be prevented in import cells and export
cells. `cupy` v13 now allow `import cupy` on a cpu-only machine. So it
can be used now.
- Describe what your PR changes and why this is a good thing. Be as
specific as you can. The PR description is how we keep track of the
changes made to the project over time.
- Do not commit changes to files that are irrelevant to your feature or
bugfix (e.g.: .gitignore, IDE project files, etc).
- Write descriptive commit messages. Chris Beams has written a
[guide](https://cbea.ms/git-commit/) on how to write good commit
messages.
PR review
Be willing to accept criticism and work on improving your code; we don’t
want to break other users’ code, so care must be taken not to introduce
bugs.
Be aware that the pull request review process is not immediate, and is
generally proportional to the size of the pull request.
[^1]: The pronciples are modified from the
[principle](https://wiki.archlinux.org/title/Arch_Linux) of Arch
Linux.
[^2]: this is modified from the [Contributers
Guide](https://www.pygmt.org/latest/contributing.html) of
[PyGMT](https://www.pygmt.org/latest/index.html).
Raw data
{
"_id": null,
"home_page": "https://github.com/kanglcn/moraine",
"name": "moraine",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "InSAR PS DS CUDA Deep-learning",
"author": "kanglcn",
"author_email": "kanglcn@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e2/f9/e75679c60fbd3c6478bd3999c8fab61c1fe2f26b83e0cd58cf5663a1586d/moraine-0.8.1.tar.gz",
"platform": null,
"description": "# Moraine\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\n> Modern Radar Interferometry Environment; A simple, stupid InSAR\n> postprocessing tool in big data era\n\nThis package provide functions for InSAR post-processing which refers as\nprocessing after SAR images co-registration and geocoding. The functions\ninclude PS/DS identification, coherence matrix estimation, phase linking\netc.\n\n<div>\n\n> **Warning**\n>\n> Due to the heavy dependence on CuPy and CUDA, this package only works\n> on device with Nivida GPU.\n\n</div>\n\n<div>\n\n> **Warning**\n>\n> This package is under intensive development. API is subjected to\n> change without any noticement.\n\n</div>\n\n## Principle[^1]\n\n### Simplicity\n\nThere is no perfect workflow that always generate satisfactory InSAR\nresult, mostly due to decorrelation, strong atmospheric artifact and\nhigh deformation gradient. Different methods implemented in different\npackages need to be tried which is frustrating especially when the\npackages are over-encapsulated and no detailed documentations are\nprovided. Furthermore, it brings more dirty work when users need to save\nintermediate data from one software and prepared them in a designated\nformat and structure required by another software.\n\nMoraine defines simplicity as *without complex data structure and\nover-encapsulation*. Most data in Moraine is just the basic\nmulti-dimentional array, i.e., [NumPy](https://numpy.org/) array or\n[CuPy](https://cupy.dev/) array in memory, or\n[Zarr](https://zarr.readthedocs.io/en/stable/) on disk. Instead of\nproviding a standard workflow as\n[StamPS](https://homepages.see.leeds.ac.uk/~earahoo/stamps/) and\n[MintPy](https://mintpy.readthedocs.io/en/latest/), Moraine is designed\nas a collection of functions that implement specific InSAR processing\ntechniques and data manipulation infrastructure.\n\n### Modernity\n\nMoraine strives to implement state-of-art InSAR techniques, including\nadvanced PS/DS identification, phase linking and deep-learning-based\nmethods.\n\nMoraine also emphasizes performance, especially in this big data era.\nMost Moraine functions are implemented with well-optimized GPU code or\nOpenMP code. Furthermore, with the support of\n[Dask](https://docs.dask.org/en/stable/), Moraine can be runed on\nmulti-GPUs to further accelerate the processing, get rid of the\nlimitation of memory and achieve asynchronous IO.\n\n### Pragmatism\n\nMoraine is a pragmatic library rather than an ideological workflow. The\nlarge number of functions in MOraine offer free and open source\nimplementation for many InSAR techniques. Ultimately, workflow designs\nare made on a case-by-case basis by the user. We provide the necessary\ninfrastructure and your role is to be innovative!\n\n### User centrality\n\nWhereas many InSAR packages attempt to be more user-friendly, Moraine\nhas always been, and shall always remain user-centric. This package is\nintended to fill the needs of those contributing to it, rather than\ntrying to appeal to as many users as possible. It is targeted at the\nproficient InSAR user, or anyone with a do-it-yourself attitude who is\nwilling to read the documentation, and solve their own problems.\n\nAll users are encouraged to participate and contribute to this package.\nReporting bugs and requesting new features by raising a Github\n[issue](https://github.com/kanglcn/moraine/issues) is highly valued and\nbugs fixing, documentation improving and features implementation by make\na Github [pull request](https://github.com/kanglcn/moraine/pulls) are\nvery appreciated. Users can also freely ask questions, provide technical\nassistance to others or just exchange opinions in the\n[discussions](https://github.com/kanglcn/moraine/discussions).\n\n## Install\n\nBecause of GPU driver and CUDA Version Compatibility, there is no simple\nsolution for CUDA related packages installation. Users need to\nsuccessfully install\n[cupy](https://docs.cupy.dev/en/stable/install.html#installation) and\n[dask_cuda](https://docs.rapids.ai/api/dask-cuda/stable/) first.\n\nHere is some tips for installing them. Generally, the cuda driver is\nalrealy installed and maintained by the system administrator. Users only\nneed to determine the right cudatoolkit version. Frist run\n\n``` bash\nnvidia-smi\n```\n\nIt will prints something like:\n\n ...\n +-----------------------------------------------------------------------------+\n | NVIDIA-SMI 525.105.17 Driver Version: 525.105.17 CUDA Version: 12.0 |\n |-------------------------------+----------------------+----------------------+\n ...\n\nThe `CUDA Version` is the maxminum cudatoolkit version that supported by\nthe current CUDA driver. Here we use version 11.8 as an example. Then\nyou can install the needed `cudatoolkit`, `cupy`, `dask_cuda` by:\n\n``` bash\nconda install -c \"nvidia/label/cuda-11.8.0\" cuda-toolkit\nconda install -c conda-forge cupy cuda-version=11.8\nconda install -c rapidsai -c conda-forge -c nvidia dask-cuda cuda-version=11.8\n```\n\nThen\n\nWith conda:\n\n``` bash\nconda install -c conda-forge moraine\n```\n\nOr with pip:\n\n``` bash\npip install moraine\n```\n\nIn development mode:\n\n``` bash\ngit clone git@github.com:kanglcn/moraine.git ./moraine\ncd ./moraine\npip install -e '.[dev]'\n```\n\n## How to use\n\nRead the [software\narchitecture](./Introduction/software_architecture.ipynb) for an\noverview of the software design. Refer to [Tutorials](./Tutorials) for\nthe examples. Refer to [API](./API/) and [CLI](./CLI) for the detailed\nusage of every functions.\n\n## Contact us\n\n- Most discussion happens on\n [GitHub](https://github.com/kanglcn/moraine). Feel free to [open an\n issue](https://github.com/kanglcn/moraine/issues/new) or comment on\n any open issue or pull request.\n- use github\n [discussions](https://github.com/kanglcn/moraine/discussions) to ask\n questions or leave comments.\n\n## General Guidelines for Making a Pull Request (PR)[^2]\n\nWe follow the [git pull request\nworkflow](https://www.asmeurer.com/git-workflow/) to make changes to our\ncodebase.\n\nBefore you make a PR, have a quick look at the titles of all the\nexisting issues first. If there is already an issue that matches your\nPR, leave a comment there to let us know what you plan to do. Otherwise,\nopen an issue describing what you want to do.\n\nWhat should be included in a PR\n\n- Each pull request should consist of a small and logical collection of\n changes; larger changes should be broken down into smaller parts and\n integrated separately.\n\n- Bug fixes should be submitted in separate PRs.\n\nHow to write and submit a PR\n\n- This package is developed with the [nbdev](https://nbdev.fast.ai/), a\n notebook-driven development platform. Developers should write or edit\n the notebooks rather than the `.py` files. After than, run\n `nbdev_export` to export the code in the notebooks to `.py` files and\n run `nbdev_clean` to clean the notebooks.\n\n- The github bot to generate docs do not support GPU, so all GPU related\n packages (`dask_cuda`) should be prevented in import cells and export\n cells. `cupy` v13 now allow `import cupy` on a cpu-only machine. So it\n can be used now.\n\n- Describe what your PR changes and why this is a good thing. Be as\n specific as you can. The PR description is how we keep track of the\n changes made to the project over time.\n\n- Do not commit changes to files that are irrelevant to your feature or\n bugfix (e.g.: .gitignore, IDE project files, etc).\n\n- Write descriptive commit messages. Chris Beams has written a\n [guide](https://cbea.ms/git-commit/) on how to write good commit\n messages.\n\nPR review\n\nBe willing to accept criticism and work on improving your code; we don\u2019t\nwant to break other users\u2019 code, so care must be taken not to introduce\nbugs.\n\nBe aware that the pull request review process is not immediate, and is\ngenerally proportional to the size of the pull request.\n\n[^1]: The pronciples are modified from the\n [principle](https://wiki.archlinux.org/title/Arch_Linux) of Arch\n Linux.\n\n[^2]: this is modified from the [Contributers\n Guide](https://www.pygmt.org/latest/contributing.html) of\n [PyGMT](https://www.pygmt.org/latest/index.html).\n",
"bugtrack_url": null,
"license": "GNU General Public License v3.0 only",
"summary": "Modern Radar Interferometry Environment, A simple, stupid InSAR postprocessing tool in big data era",
"version": "0.8.1",
"project_urls": {
"Homepage": "https://github.com/kanglcn/moraine"
},
"split_keywords": [
"insar",
"ps",
"ds",
"cuda",
"deep-learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9428967a9a5afc187b23fd4c1713ffb50e7888f935f6a35a3d93fa4654903c93",
"md5": "8bf8848cb9628529e3cee941d69ad00c",
"sha256": "6ad70208e2e9218c51a3cb12208528c2c481fb1c04520b4aacefdd43292e3c66"
},
"downloads": -1,
"filename": "moraine-0.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8bf8848cb9628529e3cee941d69ad00c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 80779,
"upload_time": "2024-08-12T23:10:21",
"upload_time_iso_8601": "2024-08-12T23:10:21.516702Z",
"url": "https://files.pythonhosted.org/packages/94/28/967a9a5afc187b23fd4c1713ffb50e7888f935f6a35a3d93fa4654903c93/moraine-0.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e2f9e75679c60fbd3c6478bd3999c8fab61c1fe2f26b83e0cd58cf5663a1586d",
"md5": "ec47cf55cde970d3bd1a61c46b8e6f11",
"sha256": "be8956eb9fd7b1bed51141aaaa4284c3d5f991dfaede162bc4f1dd35c2747bcb"
},
"downloads": -1,
"filename": "moraine-0.8.1.tar.gz",
"has_sig": false,
"md5_digest": "ec47cf55cde970d3bd1a61c46b8e6f11",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 74167,
"upload_time": "2024-08-12T23:10:22",
"upload_time_iso_8601": "2024-08-12T23:10:22.992800Z",
"url": "https://files.pythonhosted.org/packages/e2/f9/e75679c60fbd3c6478bd3999c8fab61c1fe2f26b83e0cd58cf5663a1586d/moraine-0.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-12 23:10:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kanglcn",
"github_project": "moraine",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "moraine"
}
JSON
