Redo environment files as .txt instead of YAML

.dockerignore

@@ -3,3 +3,4 @@
 build/
 data/
 dist/
+.nox

.github/workflows/test-build-push.yml

@@ -52,8 +52,9 @@ jobs:
       - name: Setup environment
         uses: mamba-org/setup-micromamba@v1
         with:
-          environment-file: conda-env.yml
+          environment-file: conda-env.txt
           environment-name: dolphin-env
+          cache-environment: true
           create-args: ${{ matrix.deps.spec }}
           condarc: |
             channels:

.readthedocs.yaml

@@ -14,7 +14,7 @@ build:
     python: "mambaforge-4.10"
 
 conda:
-  environment: conda-env.yml
+  environment: conda-env.txt
 
 python:
   install:

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Unreleased
 
+
+# [0.4.0](https://github.com/isce-framework/dolphin/compare/v0.2.0...v0.3.0) - 2023-09-07
+
 **Changed**
 
 - Split apart OPERA-specific needs from more general library/workflow functionality
@@ -17,7 +20,7 @@ Dropped:
 Now optional:
 - isce3 (for unwrapping)
 
-# [0.3.0](https://github.com/opera-adt/dolphin/compare/v0.2.0...v0.3.0) - 2023-08-23
+# [0.3.0](https://github.com/isce-framework/dolphin/compare/v0.2.0...v0.3.0) - 2023-08-23
 
 **Added**
 
@@ -34,7 +37,7 @@ Now optional:
 
 - pydantic >= 2.1
 
-# [0.2.0](https://github.com/opera-adt/dolphin/compare/v0.1.0...v0.2.0) - 2023-07-25
+# [0.2.0](https://github.com/isce-framework/dolphin/compare/v0.1.0...v0.2.0) - 2023-07-25
 
 **Added**
 
@@ -80,7 +83,7 @@ Added testing requirements:
 - pillow>=7.0
 
 
-# [0.1.0](https://github.com/opera-adt/dolphin/compare/v0.0.4...v0.1.0) - 2023-03-31
+# [0.1.0](https://github.com/isce-framework/dolphin/compare/v0.0.4...v0.1.0) - 2023-03-31
 
 - First version of the `_product.py` module to output the combined NetCDF product file.
 - `_pge_runconfig.py` module to handle the separate PGE-compatible configuration, which translates to-from the `Workflow` object.
@@ -111,7 +114,7 @@ Added requirements:
 - h5netcdf>=1.1
 - Avoid HDF5 version 1.12.1 until NetCDF loading issue is fixed
 
-# [0.0.4](https://github.com/opera-adt/dolphin/compare/v0.0.3...v0.0.4) - 2023-03-17
+# [0.0.4](https://github.com/isce-framework/dolphin/compare/v0.0.3...v0.0.4) - 2023-03-17
 
 **Added**
 
@@ -160,7 +163,7 @@ Removed requirements:
 - tqdm
 
 
-# [0.0.3](https://github.com/opera-adt/dolphin/compare/v0.0.2...v0.0.3) - 2023-01-26
+# [0.0.3](https://github.com/isce-framework/dolphin/compare/v0.0.2...v0.0.3) - 2023-01-26
 
 **Added**
 
@@ -176,7 +179,7 @@ Removed requirements:
 - Renamed module to `_log.py`
 - `workflows/wrapped_phase.py` absorbed much logic formerly in `s1_disp_stack.py`.
 
-# [0.0.2](https://github.com/opera-adt/dolphin/compare/v0.0.1...v0.0.2) - 2023-01-24
+# [0.0.2](https://github.com/isce-framework/dolphin/compare/v0.0.1...v0.0.2) - 2023-01-24
 
 **Added**
 

README.md

@@ -1,5 +1,6 @@
 # dolphin
-[![Pytest and build docker image](https://github.com/opera-adt/dolphin/actions/workflows/test-build-push.yml/badge.svg?branch=main)](https://github.com/opera-adt/dolphin/actions/workflows/test-build-push.yml)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/isce-framework/dolphin/main.svg)](https://results.pre-commit.ci/latest/github/isce-framework/dolphin/main)
+[![Pytest and build docker image](https://github.com/isce-framework/dolphin/actions/workflows/test-build-push.yml/badge.svg?branch=main)](https://github.com/isce-framework/dolphin/actions/workflows/test-build-push.yml)
 
 High resolution wrapped phase estimation for InSAR using combined PS/DS processing.
 
@@ -29,16 +30,22 @@ To install locally:
 
 1. Download source code:
 ```bash
-git clone https://github.com/opera-adt/dolphin.git && cd dolphin
+git clone https://github.com/isce-framework/dolphin.git && cd dolphin
 ```
+
 2. Install dependencies:
 ```bash
-mamba env create --file conda-env.yml
+mamba create -c conda-forge --name dolphin-env --file conda-env.txt
 ```
 
 or if you have an existing environment:
 ```bash
-mamba env update --name my-existing-env --file conda-env.yml
+mamba install --name my-existing-env --file conda-env.txt
+```
+
+If you'd like to also install the `isce3` unwrappers, you can pass both files to the install command:
+```bash
+mamba create -c conda-forge --name dolphin-env --file conda-env.txt --file conda-env-unwrapping.txt
 ```
 
 3. Install `dolphin` via pip:

conda-env-gpu-extras.txt

@@ -0,0 +1,10 @@
+# Can be used to install the GPU dependences with
+#
+#     mamba create -c conda-forge -n dolphin-gpu-env --file conda-env.txt --file conda-env-gpu-extras.txt
+# See also for numba's GPU installation instructions:
+# https://numba.pydata.org/numba-doc/latest/user/installing.html#installing-using-conda-on-x86-x86-64-power-platforms
+# NOTE: the `cudatoolkit` version must match the CUDA runtime version you have installed
+# See the `Getting Started` in the docs
+cupy>=11.0
+cudatoolkit
+pynvml>=11.0

conda-env-unwrapping.txt

@@ -0,0 +1,4 @@
+# Can be used to update the environment with the following command:
+#     mamba install --file conda-env-unwrapping.yml
+isce3>=0.14
+# tophu  # Once tophu added to conda forge, this will be installed

conda-env.txt

@@ -0,0 +1,17 @@
+python>=3.8
+pip>=21.3  # https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/#editable-installation
+git  # for pip install, due to setuptools_scm
+gdal>=3.3
+h5py>=3.6
+hdf5!=1.12.2 # https://github.com/SciTools/iris/issues/5187 and https://github.com/pydata/xarray/issues/7549
+numba>=0.54
+numpy>=1.20
+pydantic>=2.1
+pymp-pypi>=0.4.5
+pyproj>=3.3
+rich>=12.0
+ruamel.yaml>=0.15
+scipy>=1.5 # "scipy 0.16+ is required for linear algebra", numba. 1.5 is the oldest version that supports Python 3.7
+shapely>=1.8
+tbb>=2021.6.0 # Module for numba threading which prevents `fork()` crashes
+threadpoolctl>=3.0

docker/Dockerfile

@@ -13,8 +13,8 @@ ARG BASE
 # https://github.com/opencontainers/image-spec/blob/main/annotations.md
 LABEL org.opencontainers.image.description="Container for InSAR PS/DS phase analysis using dolphin"
 LABEL org.opencontainers.image.authors="Scott Staniewicz <[email protected]>"
-LABEL org.opencontainers.image.url="https://github.com/opera-adt/dolphin"
-LABEL org.opencontainers.image.source="https://github.com/opera-adt/dolphin"
+LABEL org.opencontainers.image.url="https://github.com/isce-framework/dolphin"
+LABEL org.opencontainers.image.source="https://github.com/isce-framework/dolphin"
 LABEL org.opencontainers.image.documentation="https://dolphin-insar.readthedocs.io/en/latest/"
 LABEL org.opencontainers.image.licenses="BSD-3-Clause OR Apache-2.0"
 

docker/build-docker-image.sh

@@ -40,7 +40,7 @@ if [ -z "$TAG" ]; then
 fi
 
 # Build the Docker image
-CMD_BASE="docker build --network=host --tag opera-adt/dolphin:$TAG --file docker/Dockerfile"
+CMD_BASE="docker build --network=host --tag isce-framework/dolphin:$TAG --file docker/Dockerfile"
 
 # append --build-arg if specified:
 if [ -z "${BASE+x}" ]; then
@@ -64,16 +64,14 @@ eval $CMD_BASE
 
 # To run the image and see the help message....
 echo "To run the image and see the help message:"
-echo "docker run --rm -it opera-adt/dolphin:$TAG dolphin --help"
+echo "docker run --rm -it isce-framework/dolphin:$TAG dolphin --help"
 #
 echo "To run the workflow on a configuration in the current directory...."
-echo "docker run --user \$(id -u):\$(id -g) -v \$PWD:/work --rm -it opera-adt/dolphin:$TAG dolphin run dolphin_config.yaml"
-echo "To run on a PGE runconfig:"
-echo "docker run --user \$(id -u):\$(id -g) -v \$PWD:/work --rm -it opera-adt/dolphin:$TAG dolphin run --pge runconfig.yaml"
+echo "docker run --user \$(id -u):\$(id -g) -v \$PWD:/work --rm -it isce-framework/dolphin:$TAG dolphin run dolphin_config.yaml"
 # where...
 #     --user $(id -u):$(id -g)  # Needed to avoid permission issues when writing to the mounted volume.
 #     -v $PWD:/work  # Mounts the current directory to the /work directory in the container.
 #     --rm  # Removes the container after it exits.
 #     -it  # Needed to keep the container running after the command exits.
-#     opera-adt/dolphin:latest  # The name of the image to run.
+#     isce-framework/dolphin:latest  # The name of the image to run.
 #     dolphin run dolphin_config.yaml # The `dolphin` command that is run in the container

docs/getting-started.md

@@ -4,9 +4,16 @@
 `dolphin` is available on conda-forge:
 
 ```bash
+# if mamba is not already installed: conda install -n base mamba
 mamba install -c conda-forge dolphin
 ```
 
+`dolphin` has the ability to unwrap interferograms, but requires the optional dependency of `isce3` to use the python bindings to [SNAPHU](https://web.stanford.edu/group/radar/softwareandlinks/sw/snaphu/).
+To install both dolphin and isce3 through conda-forge, run
+```bash
+mamba install -c conda-forge isce3 dolphin
+```
+
 
 ## Usage
 
@@ -50,31 +57,18 @@ To install locally,
 
 1. Download source code:
 ```bash
-git clone https://github.com/opera-adt/dolphin.git && cd dolphin
+git clone https://github.com/isce-framework/dolphin.git && cd dolphin
 ```
 2. Install dependencies:
 ```bash
-mamba env create --file conda-env.yml
-```
-
-or if you have an existing environment:
-```bash
-mamba env update --name my-existing-env --file conda-env.yml
+mamba create -c conda-forge --name dolphin-env --file conda-env.txt --file conda-env-unwrapping.txt
 ```
 
 3. Install `dolphin` via pip:
 ```bash
 mamba activate dolphin-env
 python -m pip install -e .
 ```
-
-
-If you have access to a GPU, you can install the extra requirements from running the GPU accelerated algorithms:
-```bash
-mamba env update --name dolphin-env --file conda-env-gpu-extras.yml
-```
-
-
 The extra packages required for testing and building the documentation can be installed:
 ```bash
 # Run "pip install -e" to install with extra development requirements
@@ -94,6 +88,21 @@ python -m pytest
 ```
 
 
+## GPU setup
+If you have access to a GPU, you can install the extra requirements from running the GPU accelerated algorithms:
+```bash
+mamba install -c conda-forge --file conda-env-gpu-extras.yml
+```
+Note that the version of `cudatoolkit` must match the drivers installed for your GPU.
+See the [numba](https://numba.readthedocs.io/en/stable/cuda/overview.html#software) and [cupy](https://docs.cupy.dev/en/stable/install.html) installation instructions for more details on getting set up.
+
+To check whether you have successfully installed `numba` and `cupy`, run
+```bash
+python -c 'from dolphin import utils; print(utils.gpu_available())'
+```
+
+
+
 ### Creating Documentation
 
 

src/dolphin/_log.py

@@ -86,6 +86,11 @@ def setup_logging(debug: bool = False) -> None:
     logger.setLevel(log_level)
 
 
+# NOTE: once python 3.10 is minimum, we can preserve wrapped types using
+# def log_runtime(f: Callable[P, T]) -> Callable[P, T]:
+# https://stackoverflow.com/a/74080156/4174466
+
+
 def log_runtime(f: Callable) -> Callable:
     """Decorate a function to time how long it takes to run.
 

src/dolphin/_show_versions.py

@@ -32,7 +32,7 @@ def _get_sys_info() -> dict[str, str]:
 
 
 def _get_opera_info() -> dict[str, Optional[str]]:
-    """Information on system on core modules.
+    """Information on isce/opera specific modules.
 
     Returns
     -------
@@ -43,7 +43,7 @@ def _get_opera_info() -> dict[str, Optional[str]]:
         "dolphin": dolphin.__version__,
         # optionals
         "isce3": _get_version("isce3"),
-        "compass": _get_version("compass"),
+        "tophu": _get_version("tophu"),
     }
     return blob
 
@@ -82,6 +82,21 @@ def _get_deps_info() -> dict[str, Optional[str]]:
     return {name: _get_version(name) for name in deps}
 
 
+def _get_gpu_info() -> dict[str, Optional[str]]:
+    """Overview of the optional GPU packages.
+
+    Returns
+    -------
+    dict:
+        version information on relevant Python libraries
+    """
+    deps = [
+        "cudatoolkit",
+        "cupy",
+    ]
+    return {name: _get_version(name) for name in deps}
+
+
 def _print_info_dict(info_dict: dict) -> None:
     """Print the information dictionary."""
     for key, stat in info_dict.items():
@@ -95,9 +110,14 @@ def show_versions() -> None:
     --------
     > python -c "import dolphin; dolphin.show_versions()"
     """
-    print("dolphin info:")
+    from dolphin.utils import gpu_is_available
+
+    print("dolphin/isce info:")
     _print_info_dict(_get_opera_info())
     print("\nSystem:")
     _print_info_dict(_get_sys_info())
     print("\nPython deps:")
     _print_info_dict(_get_deps_info())
+    print("optional GPU info:")
+    print(f"{gpu_is_available() = }")
+    _print_info_dict(_get_gpu_info())