roms-tools 1.4.1__tar.gz → 1.5.0__tar.gz

roms_tools-1.5.0/.github/workflows/pre-commit.yaml

@@ -0,0 +1,18 @@
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v4
+    - name: Install specific pre-commit version
+      run: pip install pre-commit==3.8.0
+    - uses: pre-commit/action@v3.0.1
+      with:
+        extra_args: --all-files

roms_tools-1.5.0/.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+default_stages: [commit, push]
+ci:
+  autoupdate_schedule: monthly
+
+exclude: roms_tools/tests/test_setup/test_data/
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-docstring-first
+      - id: check-json
+      - id: check-yaml
+#      - id: double-quote-string-fixer  # seems to argue with black-jupyter
+      - id: debug-statements
+      - id: mixed-line-ending
+
+  - repo: https://github.com/MarcoGorelli/absolufy-imports
+    rev: v0.3.1
+    hooks:
+      - id: absolufy-imports
+        name: absolufy-imports
+        files: ^roms_tools/
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: 'v0.1.4'
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+
+  - repo: https://github.com/psf/black
+    rev: 22.8.0
+    hooks:
+      - id: black-jupyter
+
+  - repo: https://github.com/keewis/blackdoc
+    rev: v0.3.6
+    hooks:
+      - id: blackdoc
+
+  - repo: https://github.com/PyCQA/docformatter
+    rev: v1.7.5
+    hooks:
+      - id: docformatter
+        args: ["--in-place", "--recursive", "--wrap-summaries=88", "--wrap-descriptions=88"]

roms_tools-1.5.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.1
+Name: roms-tools
+Version: 1.5.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
+Project-URL: Home, https://github.com/CWorthy-ocean/roms-tools
+Project-URL: Documentation, https://roms-tools.readthedocs.io/en/latest/
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: xarray>=2022.6.0
+Requires-Dist: numpy
+Requires-Dist: pooch
+Requires-Dist: matplotlib
+Requires-Dist: cartopy
+Requires-Dist: packaging
+Requires-Dist: scipy
+Requires-Dist: gcm_filters
+Requires-Dist: netcdf4
+Requires-Dist: PyYAML
+Requires-Dist: pyamg
+Requires-Dist: bottleneck
+Provides-Extra: dask
+Requires-Dist: dask; extra == "dask"
+
+# ROMS-Tools
+[![PyPI version](https://img.shields.io/pypi/v/roms-tools.svg)](https://pypi.org/project/roms-tools/)
+[![codecov](https://codecov.io/gh/CWorthy-ocean/roms-tools/graph/badge.svg?token=5S1oNu39xE)](https://codecov.io/gh/CWorthy-ocean/roms-tools)
+[![Documentation Status](https://readthedocs.org/projects/roms-tools/badge/?version=latest)](https://roms-tools.readthedocs.io/en/latest/?badge=latest)
+![Run Tests](https://github.com/CWorthy-ocean/roms-tools/actions/workflows/tests.yaml/badge.svg)
+![Supported Python Versions](https://img.shields.io/pypi/pyversions/roms-tools)
+
+
+## Overview
+
+A suite of python tools for setting up a [ROMS](https://github.com/CESR-lab/ucla-roms) simulation.
+
+<mark>**DISCLAIMER**: This project is **ALPHA** and will be **EXPERIMENTAL** at least throughout Fall 2024. We do not recommend to use this software before this ALPHA development and test phase is completed.</mark>
+
+## Installation
+
+### Installation 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:
+
+```bash
+pip install roms-tools[dask]
+```
+
+### Installation from GitHub
+
+To obtain the latest development version, first clone the source repository:
+
+```bash
+git clone https://github.com/CWorthy-ocean/roms-tools.git
+cd roms-tools
+```
+
+Next, install and activate the following conda environment:
+
+```bash
+conda env create -f ci/environment.yml
+conda activate romstools
+```
+
+Finally, install `ROMS-Tools` in the same environment:
+
+```bash
+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:
+
+```bash
+pip install -e .[dask]
+```
+
+
+### Run the tests
+
+Before running the tests, you can activate the conda environment created in the previous section:
+
+```bash
+conda activate romstools
+```
+
+Check the installation of `ROMS-Tools` has worked by running the test suite
+```bash
+cd roms-tools
+pytest
+```
+
+## Getting Started
+
+To learn how to use `ROMS-Tools`, check out the [documentation](https://roms-tools.readthedocs.io/en/latest/).
+
+## Feedback and contributions
+
+**If you find a bug, have a feature suggestion, or any other kind of feedback, please start a Discussion.**
+
+We also accept contributions in the form of Pull Requests.
+
+
+## See also
+
+- [ROMS source code](https://github.com/CESR-lab/ucla-roms)
+- [C-Star](https://github.com/CWorthy-ocean/C-Star)

roms_tools-1.5.0/README.md

@@ -0,0 +1,88 @@
+# ROMS-Tools
+[![PyPI version](https://img.shields.io/pypi/v/roms-tools.svg)](https://pypi.org/project/roms-tools/)
+[![codecov](https://codecov.io/gh/CWorthy-ocean/roms-tools/graph/badge.svg?token=5S1oNu39xE)](https://codecov.io/gh/CWorthy-ocean/roms-tools)
+[![Documentation Status](https://readthedocs.org/projects/roms-tools/badge/?version=latest)](https://roms-tools.readthedocs.io/en/latest/?badge=latest)
+![Run Tests](https://github.com/CWorthy-ocean/roms-tools/actions/workflows/tests.yaml/badge.svg)
+![Supported Python Versions](https://img.shields.io/pypi/pyversions/roms-tools)
+
+
+## Overview
+
+A suite of python tools for setting up a [ROMS](https://github.com/CESR-lab/ucla-roms) simulation.
+
+<mark>**DISCLAIMER**: This project is **ALPHA** and will be **EXPERIMENTAL** at least throughout Fall 2024. We do not recommend to use this software before this ALPHA development and test phase is completed.</mark>
+
+## Installation
+
+### Installation 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:
+
+```bash
+pip install roms-tools[dask]
+```
+
+### Installation from GitHub
+
+To obtain the latest development version, first clone the source repository:
+
+```bash
+git clone https://github.com/CWorthy-ocean/roms-tools.git
+cd roms-tools
+```
+
+Next, install and activate the following conda environment:
+
+```bash
+conda env create -f ci/environment.yml
+conda activate romstools
+```
+
+Finally, install `ROMS-Tools` in the same environment:
+
+```bash
+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:
+
+```bash
+pip install -e .[dask]
+```
+
+
+### Run the tests
+
+Before running the tests, you can activate the conda environment created in the previous section:
+
+```bash
+conda activate romstools
+```
+
+Check the installation of `ROMS-Tools` has worked by running the test suite
+```bash
+cd roms-tools
+pytest
+```
+
+## Getting Started
+
+To learn how to use `ROMS-Tools`, check out the [documentation](https://roms-tools.readthedocs.io/en/latest/).
+
+## Feedback and contributions
+
+**If you find a bug, have a feature suggestion, or any other kind of feedback, please start a Discussion.**
+
+We also accept contributions in the form of Pull Requests.
+
+
+## See also
+
+- [ROMS source code](https://github.com/CESR-lab/ucla-roms)
+- [C-Star](https://github.com/CWorthy-ocean/C-Star)

roms_tools-1.5.0/conftest.py

@@ -0,0 +1,366 @@
+import pytest
+from datetime import datetime
+from roms_tools import (
+    Grid,
+    TidalForcing,
+    InitialConditions,
+    BoundaryForcing,
+    SurfaceForcing,
+)
+from roms_tools.setup.download import download_test_data
+import hashlib
+
+
+def pytest_addoption(parser):
+    parser.addoption(
+        "--overwrite",
+        action="append",
+        default=[],
+        help="Specify which fixtures to overwrite. Use 'all' to overwrite all fixtures.",
+    )
+    parser.addoption(
+        "--use_dask", action="store_true", default=False, help="Run tests with Dask"
+    )
+
+
+def pytest_configure(config):
+    if "all" in config.getoption("--overwrite"):
+        # If 'all' is specified, overwrite everything
+        config.option.overwrite = ["all"]
+
+
+@pytest.fixture(scope="session")
+def use_dask(request):
+    return request.config.getoption("--use_dask")
+
+
+@pytest.fixture(scope="session")
+def grid():
+
+    grid = Grid(nx=1, ny=1, size_x=100, size_y=100, center_lon=-20, center_lat=0, rot=0)
+
+    return grid
+
+
+@pytest.fixture(scope="session")
+def grid_that_straddles_dateline():
+
+    grid = Grid(nx=1, ny=1, size_x=100, size_y=100, center_lon=0, center_lat=0, rot=20)
+
+    return grid
+
+
+@pytest.fixture(scope="session")
+def tidal_forcing(request, use_dask):
+
+    grid = Grid(
+        nx=3, ny=3, size_x=1500, size_y=1500, center_lon=235, center_lat=25, rot=-20
+    )
+    fname = download_test_data("TPXO_regional_test_data.nc")
+
+    return TidalForcing(
+        grid=grid, source={"name": "TPXO", "path": fname}, ntides=1, use_dask=use_dask
+    )
+
+
+@pytest.fixture(scope="session")
+def initial_conditions(request, use_dask):
+    """Fixture for creating an InitialConditions object."""
+
+    grid = Grid(
+        nx=2,
+        ny=2,
+        size_x=500,
+        size_y=1000,
+        center_lon=0,
+        center_lat=55,
+        rot=10,
+        N=3,  # number of vertical levels
+        theta_s=5.0,  # surface control parameter
+        theta_b=2.0,  # bottom control parameter
+        hc=250.0,  # critical depth
+    )
+
+    fname = download_test_data("GLORYS_coarse_test_data.nc")
+
+    return InitialConditions(
+        grid=grid,
+        ini_time=datetime(2021, 6, 29),
+        source={"path": fname, "name": "GLORYS"},
+        use_dask=use_dask,
+    )
+
+
+@pytest.fixture(scope="session")
+def initial_conditions_with_bgc(request, use_dask):
+    """Fixture for creating an InitialConditions object."""
+
+    grid = Grid(
+        nx=2,
+        ny=2,
+        size_x=500,
+        size_y=1000,
+        center_lon=0,
+        center_lat=55,
+        rot=10,
+        N=3,  # number of vertical levels
+        theta_s=5.0,  # surface control parameter
+        theta_b=2.0,  # bottom control parameter
+        hc=250.0,  # critical depth
+    )
+
+    fname = download_test_data("GLORYS_coarse_test_data.nc")
+    fname_bgc = download_test_data("CESM_regional_test_data_one_time_slice.nc")
+
+    return InitialConditions(
+        grid=grid,
+        ini_time=datetime(2021, 6, 29),
+        source={"path": fname, "name": "GLORYS"},
+        bgc_source={"path": fname_bgc, "name": "CESM_REGRIDDED"},
+        use_dask=use_dask,
+    )
+
+
+@pytest.fixture(scope="session")
+def initial_conditions_with_bgc_from_climatology(request, use_dask):
+    """Fixture for creating an InitialConditions object."""
+
+    grid = Grid(
+        nx=2,
+        ny=2,
+        size_x=500,
+        size_y=1000,
+        center_lon=0,
+        center_lat=55,
+        rot=10,
+        N=3,  # number of vertical levels
+        theta_s=5.0,  # surface control parameter
+        theta_b=2.0,  # bottom control parameter
+        hc=250.0,  # critical depth
+    )
+
+    fname = download_test_data("GLORYS_coarse_test_data.nc")
+    fname_bgc = download_test_data("CESM_regional_test_data_climatology.nc")
+
+    return InitialConditions(
+        grid=grid,
+        ini_time=datetime(2021, 6, 29),
+        source={"path": fname, "name": "GLORYS"},
+        bgc_source={
+            "path": fname_bgc,
+            "name": "CESM_REGRIDDED",
+            "climatology": True,
+        },
+        use_dask=use_dask,
+    )
+
+
+@pytest.fixture(scope="session")
+def boundary_forcing(request, use_dask):
+    """Fixture for creating a BoundaryForcing object."""
+
+    grid = Grid(
+        nx=2,
+        ny=2,
+        size_x=500,
+        size_y=1000,
+        center_lon=0,
+        center_lat=55,
+        rot=10,
+        N=3,  # number of vertical levels
+        theta_s=5.0,  # surface control parameter
+        theta_b=2.0,  # bottom control parameter
+        hc=250.0,  # critical depth
+    )
+
+    fname = download_test_data("GLORYS_coarse_test_data.nc")
+
+    return BoundaryForcing(
+        grid=grid,
+        start_time=datetime(2021, 6, 29),
+        end_time=datetime(2021, 6, 30),
+        source={"name": "GLORYS", "path": fname},
+        use_dask=use_dask,
+    )
+
+
+@pytest.fixture(scope="session")
+def bgc_boundary_forcing_from_climatology(request, use_dask):
+    """Fixture for creating a BoundaryForcing object."""
+
+    grid = Grid(
+        nx=2,
+        ny=2,
+        size_x=500,
+        size_y=1000,
+        center_lon=0,
+        center_lat=55,
+        rot=10,
+        N=3,  # number of vertical levels
+        theta_s=5.0,  # surface control parameter
+        theta_b=2.0,  # bottom control parameter
+        hc=250.0,  # critical depth
+    )
+
+    fname_bgc = download_test_data("CESM_regional_coarse_test_data_climatology.nc")
+
+    return BoundaryForcing(
+        grid=grid,
+        start_time=datetime(2021, 6, 29),
+        end_time=datetime(2021, 6, 30),
+        source={"path": fname_bgc, "name": "CESM_REGRIDDED", "climatology": True},
+        type="bgc",
+        use_dask=use_dask,
+    )
+
+
+@pytest.fixture(scope="session")
+def surface_forcing(request, use_dask):
+    """Fixture for creating a SurfaceForcing object."""
+
+    grid = Grid(
+        nx=5,
+        ny=5,
+        size_x=1800,
+        size_y=2400,
+        center_lon=180,
+        center_lat=61,
+        rot=20,
+    )
+
+    start_time = datetime(2020, 1, 31)
+    end_time = datetime(2020, 2, 2)
+
+    fname = download_test_data("ERA5_global_test_data.nc")
+
+    return SurfaceForcing(
+        grid=grid,
+        start_time=start_time,
+        end_time=end_time,
+        source={"name": "ERA5", "path": fname},
+        use_dask=use_dask,
+    )
+
+
+@pytest.fixture(scope="session")
+def coarse_surface_forcing(request, use_dask):
+    """Fixture for creating a SurfaceForcing object."""
+
+    grid = Grid(
+        nx=5,
+        ny=5,
+        size_x=1800,
+        size_y=2400,
+        center_lon=180,
+        center_lat=61,
+        rot=20,
+    )
+
+    start_time = datetime(2020, 1, 31)
+    end_time = datetime(2020, 2, 2)
+
+    fname = download_test_data("ERA5_global_test_data.nc")
+
+    return SurfaceForcing(
+        grid=grid,
+        start_time=start_time,
+        end_time=end_time,
+        use_coarse_grid=True,
+        source={"name": "ERA5", "path": fname},
+        use_dask=use_dask,
+    )
+
+
+@pytest.fixture(scope="session")
+def corrected_surface_forcing(request, use_dask):
+    """Fixture for creating a SurfaceForcing object with shortwave radiation
+    correction."""
+
+    grid = Grid(
+        nx=5,
+        ny=5,
+        size_x=1800,
+        size_y=2400,
+        center_lon=180,
+        center_lat=61,
+        rot=20,
+    )
+
+    start_time = datetime(2020, 1, 31)
+    end_time = datetime(2020, 2, 2)
+
+    fname = download_test_data("ERA5_global_test_data.nc")
+
+    return SurfaceForcing(
+        grid=grid,
+        start_time=start_time,
+        end_time=end_time,
+        source={"name": "ERA5", "path": fname},
+        correct_radiation=True,
+        use_dask=use_dask,
+    )
+
+
+@pytest.fixture(scope="session")
+def bgc_surface_forcing(request, use_dask):
+    """Fixture for creating a SurfaceForcing object with BGC."""
+    grid = Grid(
+        nx=5,
+        ny=5,
+        size_x=1800,
+        size_y=2400,
+        center_lon=180,
+        center_lat=61,
+        rot=20,
+    )
+
+    start_time = datetime(2020, 2, 1)
+    end_time = datetime(2020, 2, 1)
+
+    fname_bgc = download_test_data("CESM_surface_global_test_data.nc")
+
+    return SurfaceForcing(
+        grid=grid,
+        start_time=start_time,
+        end_time=end_time,
+        source={"name": "CESM_REGRIDDED", "path": fname_bgc},
+        type="bgc",
+        use_dask=use_dask,
+    )
+
+
+@pytest.fixture(scope="session")
+def bgc_surface_forcing_from_climatology(request, use_dask):
+    """Fixture for creating a SurfaceForcing object with BGC from climatology."""
+    grid = Grid(
+        nx=5,
+        ny=5,
+        size_x=1800,
+        size_y=2400,
+        center_lon=180,
+        center_lat=61,
+        rot=20,
+    )
+
+    start_time = datetime(2020, 2, 1)
+    end_time = datetime(2020, 2, 1)
+
+    fname_bgc = download_test_data("CESM_surface_global_test_data_climatology.nc")
+
+    return SurfaceForcing(
+        grid=grid,
+        start_time=start_time,
+        end_time=end_time,
+        source={"name": "CESM_REGRIDDED", "path": fname_bgc, "climatology": True},
+        type="bgc",
+        use_dask=use_dask,
+    )
+
+
+def calculate_file_hash(filepath, hash_algorithm="sha256"):
+    """Calculate the hash of a file using the specified hash algorithm."""
+    hash_func = hashlib.new(hash_algorithm)
+    with open(filepath, "rb") as f:
+        for chunk in iter(lambda: f.read(4096), b""):
+            hash_func.update(chunk)
+    return hash_func.hexdigest()

roms_tools-1.5.0/docs/_templates/autosummary/class.rst

@@ -0,0 +1,30 @@
+{{ objname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: Methods
+   .. autosummary::
+      :toctree:
+   {% for item in all_methods %}
+      {%- if not item.startswith('_') or item in ['__call__',
+                                                  ] %}
+      {{ name }}.{{ item }}
+
+      {% endif %}
+   {% endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+   .. autosummary::
+   {% for item in attributes %}
+      {{ name }}.{{ item }}
+   {% endfor %}
+   {% endif %}
+   {% endblock %}