roms-tools 2.5.0__tar.gz → 2.6.0__tar.gz

{roms_tools-2.5.0 → roms_tools-2.6.0}/.github/workflows/tests.yaml

@@ -44,19 +44,6 @@ jobs:
            python -V
            coverage run --rcfile=coverage.toml -m pytest --verbose roms_tools/tests/*
 
-      - name: Get coverage report
-        shell: bash -l {0}
-        run: |
-          coverage report -m
-          coverage xml
-
-      - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v4.0.1
-        with:
-          token: ${{ secrets.CODECOV_TOKEN }}
-          files: ./coverage.xml
-          flags: unittests # optional
-
   test-with-dask:
     name: 3.13-build-with-dask
     runs-on: ubuntu-latest
@@ -92,6 +79,41 @@ jobs:
            python -V
            coverage run --rcfile=coverage.toml -m pytest --use_dask --verbose roms_tools/tests/*
 
+  test-with-dask-and-xesmf:
+    name: 3.13-build-with-dask-and-xesmf
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create conda environment
+        uses: mamba-org/setup-micromamba@v1
+        with:
+          cache-downloads: true
+          cache-environment: true
+          micromamba-version: 'latest'
+          environment-file: ci/environment-with-xesmf.yml
+          create-args: |
+            python=${{ matrix.python-version }}
+          cache-key: micromamba-${{ matrix.python-version }}-${{ runner.os }}
+
+      - name: Conda info
+        run: conda info
+
+      - name: Install roms-tools
+        shell: micromamba-shell {0}
+        run: |
+           python -V
+           python -m pip install -e .[dask]  --force-reinstall
+
+      - name: Running Tests with Dask and Xesmf
+        shell: bash -l {0}
+        run: |
+           python -V
+           coverage run --rcfile=coverage.toml -m pytest --use_dask --verbose roms_tools/tests/*
+
       - name: Get coverage report
         shell: bash -l {0}
         run: |

{roms_tools-2.5.0/roms_tools.egg-info → roms_tools-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: roms-tools
-Version: 2.5.0
+Version: 2.6.0
 Summary: Tools for running and analysing UCLA-ROMS simulations
 Author-email: Nora Loose <nora.loose@gmail.com>, Thomas Nicholas <tom@cworthy.org>
 License: Apache-2
@@ -32,8 +32,11 @@ Requires-Dist: PyYAML
 Requires-Dist: pyamg
 Requires-Dist: bottleneck
 Requires-Dist: regionmask
+Requires-Dist: xgcm
+Requires-Dist: numba
 Provides-Extra: dask
 Requires-Dist: dask[diagnostics]; extra == "dask"
+Dynamic: license-file
 
 # ROMS-Tools
 [![Conda version](https://img.shields.io/conda/vn/conda-forge/roms-tools.svg)](https://anaconda.org/conda-forge/roms-tools)
@@ -46,37 +49,45 @@ Requires-Dist: dask[diagnostics]; extra == "dask"
 > [!Warning]
 > **This project is still in an early phase of development.**
 >
-> The [python API](https://roms-tools.readthedocs.io/en/latest/api.html) is not yet stable.
+> The [Python API](https://roms-tools.readthedocs.io/en/latest/api.html) is not yet stable.
 > Therefore whilst you are welcome to try out using the package, we cannot yet guarantee backwards compatibility.
 > We expect to reach a more stable version in Q1 2025.
 
 ## Overview
 
-A suite of Python tools for setting up a [ROMS](https://github.com/CESR-lab/ucla-roms) simulation.
+A suite of Python tools for setting up and analyzing a [UCLA-ROMS](https://github.com/CESR-lab/ucla-roms) simulation.
 
 ## Installation
 
-### Installation from conda forge
+### ⚡️ **Installation from Conda-Forge**
+
+To install `ROMS-Tools` with all dependencies, including `xesmf` and `dask`, use:
 
 ```bash
 conda install -c conda-forge roms-tools
 ```
 
-This command installs `ROMS-Tools` along with its `dask` dependency.
+> [!Note]
+>  Installation from Conda-Forge is the recommended installation method to ensure all features of `ROMS-Tools` are available.
+
+### 📦 **Installation from PyPI (pip)**
 
-### Installation from pip
+You can also install `ROMS-Tools` from `pip`:
 
 ```bash
 pip install roms-tools
 ```
 
-If you want to use `ROMS-Tools` together with dask (which we recommend), you can
-install `ROMS-Tools` along with the additional dependency via:
+If you want to use `ROMS-Tools` with `dask` (recommended for parallel and out-of-core computation), install it with the additional dependency:
 
 ```bash
 pip install roms-tools[dask]
 ```
 
+> [!Note]
+>  The PyPI versions of `ROMS-Tools` do not include `xesmf`, so some features will be unavailable.
+
+
 ### Installation from GitHub
 
 To obtain the latest development version, first clone the source repository:
@@ -89,7 +100,7 @@ cd roms-tools
 Next, install and activate the following conda environment:
 
 ```bash
-conda env create -f ci/environment.yml
+conda env create -f ci/environment-with-xesmf.yml
 conda activate romstools-test
 ```
 
@@ -99,7 +110,7 @@ Finally, install `ROMS-Tools` in the same environment:
 pip install -e .
 ```
 
-If you want to use `ROMS-Tools` together with dask (which we recommend), you can
+If you want to use `ROMS-Tools` with `dask` (recommended for parallel and out-of-core computation), you can
 install `ROMS-Tools` along with the additional dependency via:
 
 ```bash

{roms_tools-2.5.0 → roms_tools-2.6.0}/README.md

@@ -9,37 +9,45 @@
 > [!Warning]
 > **This project is still in an early phase of development.**
 >
-> The [python API](https://roms-tools.readthedocs.io/en/latest/api.html) is not yet stable.
+> The [Python API](https://roms-tools.readthedocs.io/en/latest/api.html) is not yet stable.
 > Therefore whilst you are welcome to try out using the package, we cannot yet guarantee backwards compatibility.
 > We expect to reach a more stable version in Q1 2025.
 
 ## Overview
 
-A suite of Python tools for setting up a [ROMS](https://github.com/CESR-lab/ucla-roms) simulation.
+A suite of Python tools for setting up and analyzing a [UCLA-ROMS](https://github.com/CESR-lab/ucla-roms) simulation.
 
 ## Installation
 
-### Installation from conda forge
+### ⚡️ **Installation from Conda-Forge**
+
+To install `ROMS-Tools` with all dependencies, including `xesmf` and `dask`, use:
 
 ```bash
 conda install -c conda-forge roms-tools
 ```
 
-This command installs `ROMS-Tools` along with its `dask` dependency.
+> [!Note]
+>  Installation from Conda-Forge is the recommended installation method to ensure all features of `ROMS-Tools` are available.
+
+### 📦 **Installation from PyPI (pip)**
 
-### Installation from pip
+You can also install `ROMS-Tools` from `pip`:
 
 ```bash
 pip install roms-tools
 ```
 
-If you want to use `ROMS-Tools` together with dask (which we recommend), you can
-install `ROMS-Tools` along with the additional dependency via:
+If you want to use `ROMS-Tools` with `dask` (recommended for parallel and out-of-core computation), install it with the additional dependency:
 
 ```bash
 pip install roms-tools[dask]
 ```
 
+> [!Note]
+>  The PyPI versions of `ROMS-Tools` do not include `xesmf`, so some features will be unavailable.
+
+
 ### Installation from GitHub
 
 To obtain the latest development version, first clone the source repository:
@@ -52,7 +60,7 @@ cd roms-tools
 Next, install and activate the following conda environment:
 
 ```bash
-conda env create -f ci/environment.yml
+conda env create -f ci/environment-with-xesmf.yml
 conda activate romstools-test
 ```
 
@@ -62,7 +70,7 @@ Finally, install `ROMS-Tools` in the same environment:
 pip install -e .
 ```
 
-If you want to use `ROMS-Tools` together with dask (which we recommend), you can
+If you want to use `ROMS-Tools` with `dask` (recommended for parallel and out-of-core computation), you can
 install `ROMS-Tools` along with the additional dependency via:
 
 ```bash

roms_tools-2.6.0/ci/environment-with-xesmf.yml

@@ -0,0 +1,16 @@
+name: romstools-test
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  - python>=3.10
+  - xesmf
+  # testing
+  - zarr
+  - pytest
+  - pytest-xdist
+  - h5py
+  - flake8
+  - black
+  - pre-commit==3.8.0
+  - coverage

{roms_tools-2.5.0 → roms_tools-2.6.0}/docs/api.rst

@@ -76,4 +76,4 @@ Utilities
 .. autosummary::
    :toctree: generated/
 
-   roms_tools.utils.partition
+   roms_tools.tiling.partition

{roms_tools-2.5.0 → roms_tools-2.6.0}/docs/boundary_forcing.ipynb

@@ -2947,7 +2947,7 @@
     "* If `adjust_depth_for_sea_surface_height = False` (default), a constant sea surface height is assumed: $\\zeta(x,y,t) = 0$.\n",
     "* If `adjust_depth_for_sea_surface_height = True`, the depth calculations account for spatial and temporal variations in SSH.\n",
     "\n",
-    "Setting `adjust_depth_for_sea_surface_height = True` increases the complexity in the depth coordinate generation, as depths become time-dependent. While this approach may seem more accurate, its effectiveness depends on how source datasets (e.g., GLORYS) define their depth coordinates. It is often unclear whether these datasets measure depth relative to the surface (consistent with `adjust_depth_for_sea_surface_height = False`) or elevation above the bottom (consistent with `adjust_depth_for_sea_surface_height = True`). Given this uncertainty and the unclear benefit of adjusting for sea surface height variations, the default setting is `adjust_depth_for_sea_surface_height = False` for simplicity, and this approach has been used until now in this notebook.\n",
+    "When `adjust_depth_for_sea_surface_height = True`, the depths become time-dependent. While this approach may seem more accurate, its effectiveness depends on how source datasets (e.g., GLORYS) define their depth coordinates. It is often unclear whether these datasets measure depth relative to the surface (consistent with `adjust_depth_for_sea_surface_height = False`) or elevation above the bottom (consistent with `adjust_depth_for_sea_surface_height = True`). Given this uncertainty and the unclear benefit of adjusting for sea surface height variations, the default setting is `adjust_depth_for_sea_surface_height = False` for simplicity, and this approach has been used until now in this notebook.\n",
     "\n",
     "<div class=\"alert alert-info\">\n",
     "\n",

{roms_tools-2.5.0 → roms_tools-2.6.0}/docs/conf.py

@@ -15,14 +15,6 @@ project = "ROMS-Tools"
 copyright = "2024, ROMS-Tools developers"
 author = "ROMS-Tools developers"
 
-# -- Early stage of development Warning banner -----------------------------------------------------
-rst_prolog = """.. attention::
-    **This project is still in an early phase of development.**
-    The `python API <https://roms-tools.readthedocs.io/en/latest/api.html>`_ is not yet stable.
-    Therefore whilst you are welcome to try out using the package, we cannot yet guarantee backwards compatibility.
-    We expect to reach a more stable version in Q1 2025.
-"""
-
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 

{roms_tools-2.5.0 → roms_tools-2.6.0}/docs/index.rst

@@ -7,7 +7,7 @@ Welcome to the ROMS-Tools Documentation!
 ========================================
 
 **ROMS-Tools** is a Python package designed for creating the input files necessary
-to run a `ROMS <https://github.com/CESR-lab/ucla-roms>`_ or ROMS-MARBL simulation. This tool simplifies the process of generating:
+to run a `UCLA-ROMS <https://github.com/CESR-lab/ucla-roms>`_ simulation, with or without MARBL. This tool simplifies the process of generating:
 
 - **Grid**
 - **Tidal forcing**
@@ -32,6 +32,8 @@ to run a `ROMS <https://github.com/CESR-lab/ucla-roms>`_ or ROMS-MARBL simulatio
 
 - **Nesting**
 
+Additionally, it provides several analysis tools.
+
 This Python package is inspired by the `UCLA MATLAB tools <https://github.com/nmolem/ucla-tools/tree/main>`_.
 
 
@@ -45,7 +47,7 @@ This Python package is inspired by the `UCLA MATLAB tools <https://github.com/nm
 
 .. toctree::
    :maxdepth: 1
-   :caption: Examples
+   :caption: Preparing a ROMS Simulation
 
    Creating a grid <grid>
    Creating tidal forcing <tides>
@@ -54,9 +56,19 @@ This Python package is inspired by the `UCLA MATLAB tools <https://github.com/nm
    Creating boundary forcing <boundary_forcing>
    Creating river forcing <river_forcing>
    Preparing nested simulations <nesting>
-   Analyzing ROMS output <roms_output>
-
    Partitioning the input files <partition>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Analyzing a ROMS Simulation
+
+   Reading ROMS Output <reading_roms_output>
+   Visualizing ROMS Output <plotting_roms_output>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Advanced Topics
+
    Using ROMS-Tools with Dask <using_dask>
 
 

{roms_tools-2.5.0 → roms_tools-2.6.0}/docs/initial_conditions.ipynb

@@ -7506,7 +7506,7 @@
     "* If `adjust_depth_for_sea_surface_height = False` (default), a constant sea surface height is assumed: $\\zeta(x,y,t) = 0$.\n",
     "* If `adjust_depth_for_sea_surface_height = True`, the depth calculations account for spatial and temporal variations in SSH.\n",
     "\n",
-    "Setting `adjust_depth_for_sea_surface_height = True` increases the complexity in the depth coordinate generation, as depths become time-dependent. While this approach may seem more accurate, its effectiveness depends on how source datasets (e.g., GLORYS) define their depth coordinates. It is often unclear whether these datasets measure depth relative to the surface (consistent with `adjust_depth_for_sea_surface_height = False`) or elevation above the bottom (consistent with `adjust_depth_for_sea_surface_height = True`). Given this uncertainty and the unclear benefit of adjusting for sea surface height variations, the default setting is `adjust_depth_for_sea_surface_height = False` for simplicity, and this approach has been used until now in this notebook.\n",
+    "When `adjust_depth_for_sea_surface_height = True`, the depths become time-dependent. While this approach may seem more accurate, its effectiveness depends on how source datasets (e.g., GLORYS) define their depth coordinates. It is often unclear whether these datasets measure depth relative to the surface (consistent with `adjust_depth_for_sea_surface_height = False`) or elevation above the bottom (consistent with `adjust_depth_for_sea_surface_height = True`). Given this uncertainty and the unclear benefit of adjusting for sea surface height variations, the default setting is `adjust_depth_for_sea_surface_height = False` for simplicity, and this approach has been used until now in this notebook.\n",
     "\n",
     "Now, let's proceed by setting `adjust_depth_for_sea_surface_height = True`."
    ]

roms_tools-2.6.0/docs/installation.rst

@@ -0,0 +1,49 @@
+Installation
+############
+
+Installation from Conda-Forge
+=============================
+
+To install ``ROMS-Tools`` with all dependencies, including ``xesmf`` and ``dask``, use::
+
+    conda install -c conda-forge roms-tools
+
+Installation from Conda-Forge is the recommended installation method to ensure all features of ``ROMS-Tools`` are available.
+
+
+Installation from PyPI (pip)
+============================
+
+``ROMS-Tools`` can be installed using pip::
+
+    pip install roms-tools
+
+If you want to use ``ROMS-Tools`` together with ``dask`` (which we recommend for parallel and out-of-core computation), you can install ``ROMS-Tools`` along with the additional dependency via::
+
+    pip install roms-tools[dask]
+
+Note: The PyPI versions of ``ROMS-Tools`` do not include ``xesmf``, so some features will be unavailable.
+
+
+Installation from GitHub
+========================
+
+To obtain the latest development version, first clone
+`the source repository <https://github.com/CWorthy-ocean/roms-tools.git>`_::
+
+    git clone https://github.com/CWorthy-ocean/roms-tools.git
+    cd roms-tools
+
+Then, install and activate the following conda environment::
+
+    conda env create -f ci/environment-with-xesmf.yml
+    conda activate romstools-test
+
+Finally, install ``ROMS-Tools`` in the same environment::
+
+    pip install -e .
+
+If you want to use ``ROMS-Tools`` together with ``dask`` (which we recommend), you can
+install ``ROMS-Tools`` along with the additional dependency via::
+
+    pip install ".[dask]"

{roms_tools-2.5.0 → roms_tools-2.6.0}/docs/methods.md

@@ -18,7 +18,9 @@ The horizontal grid parameters are as follows:
 | `center_lat` | Latitude of the center of the domain                              | Degrees                     |
 | `rot`        | Rotation of the grid's x-direction from lines of constant longitude | Degrees (counter-clockwise) |
 
-To generate the horizontal grid from these parameters, `ROMS-Tools` follows a series of steps to define the domain and coordinate system:
+Using these parameters, `ROMS-Tools` generates a curvilinear orthogonal grid designed to minimize variations in grid cell size across the domain. To achieve this, `ROMS-Tools` employs a Transverse Mercator projection.
+
+**Detailed Steps**:
 
 1. **Domain Orientation**: Given the `size_x` and `size_y` parameters, the domain is initially oriented to prioritize the x-direction as longer than the y-direction. This may involve swapping `size_x` with `size_y` and `nx` with `ny`. This step is performed to minimize grid distortion.
 
@@ -36,6 +38,7 @@ To generate the horizontal grid from these parameters, `ROMS-Tools` follows a se
 
 8. **Angle computation**: The angle between the positive x-axis of the local grid and East is computed to establish the orientation relative to geographic directions.
 
+
 ## Mask
 
 During the grid generation process, when an instance of the {py:obj}`roms_tools.Grid` class is created, `ROMS-Tools` also generates a land mask. For practical examples, refer to [this notebook](grid.ipynb).
@@ -63,7 +66,7 @@ The topography is generated via the following steps:
 1. **Regridding**: The topography from the specified `topography_source` is regridded onto the ROMS grid.
 2. **Domain-wide Smoothing**: The regridded topography is smoothed over the entire domain with a smoothing factor of 8. This step is carried out using the [GCM-Filters](https://gcm-filters.readthedocs.io/en/latest/) package, and ensures that the topography is smooth at the grid scale, a prerequisite for avoiding grid-scale instabilities during model runtime.
 3. **Depth Clipping**: In regions that correspond to land or where the ocean depth is shallower than $h_{min}$, the depth is clipped to $h_{min}$.
-4. **Local Smoothing**: The regridded, clipped, and smoothed topography field `h` undergoes further local (logarithmic) smoothing to limit the slope parameter `r` to a maximum value of 0.2. This slope parameter is calculcated as:
+4. **Local Smoothing**: The regridded, clipped, and smoothed topography field `h` undergoes further local (logarithmic) smoothing to limit the slope parameter `r` to a maximum value of 0.2. This step helps minimize pressure gradient errors. The slope parameter is calculcated as:
 
 $$