diff --git a/README.rst b/README.rst index e5f9f1c7..ba02e52c 100644 --- a/README.rst +++ b/README.rst @@ -33,25 +33,32 @@ pyTMD Python-based tidal prediction software for estimating ocean, load, solid Earth and pole tides -Ocean and load tidal predictions using OTIS, GOT and FES formatted tidal solutions - -- `OSU Tidal Prediction Software (OTPS) `_ -- `ESR Tide Model Driver (TMD) Matlab Toolbox `_ -- `OSU Global and Regional Tide Models `_ -- `ESR Polar Tide Models `_ -- `A Global Ocean Tide Model From TOPEX/POSEIDON Altimetry: GOT99.2 `_ -- `Finite Element Solution (FES) tide models `_ -- `Delta times from US Naval Observatory (USNO) Earth Orientation Products `_ -- `Delta times from NASA Crustal Dynamics Data Information System (CDDIS) `_ - -Radial solid Earth and pole tide displacements following IERS conventions - -- `IERS Conventions (2010) `_ -- `IERS Mean Pole Location `_ -- `IERS Pole Coordinates to Calculate Mean Pole `_ -- `IERS Daily Earth Orientation Parameters (EOP) from USNO `_ -- `IERS Daily Earth Orientation Parameters (EOP) from NASA CDDIS `_ -- `IERS Ocean Pole Load Tide Coefficients Map `_ +For more information: see the documentation at `pytmd.readthedocs.io `_ + +Installation +############ + +From PyPI: + +.. code-block:: bash + + python3 -m pip install pyTMD + +Using `conda` or `mamba` from conda-forge: + +.. code-block:: bash + + conda install -c conda-forge pytmd + +.. code-block:: bash + + mamba install -c conda-forge pytmd + +Development version from GitHub: + +.. code-block:: bash + + python3 -m pip install git+https://github.com/tsutterley/pyTMD.git Dependencies ############ @@ -87,11 +94,11 @@ Download Alternative Software #################### -| perth5 from NASA Goddard Space Flight Center is available at: +| perth5 from NASA Goddard Space Flight Center: | https://codeberg.org/rray/perth5 -| Matlab Tide Model Driver from Earth & Space Research is available at: +| Matlab Tide Model Driver from Earth & Space Research: | https://github.com/EarthAndSpaceResearch/TMD_Matlab_Toolbox_v2.5 -| Fortran OSU Tidal Prediction Software OTPS is available at: +| Fortran OSU Tidal Prediction Software: | https://www.tpxo.net/otps Disclaimer @@ -102,10 +109,15 @@ It is not sponsored or maintained by the Universities Space Research Association The software is provided here for your convenience but *with no guarantees whatsoever*. It should not be used for coastal navigation or any application that may risk life or property. +Contributing +############ + +This project contains work and contributions from the `scientific community <./CONTRIBUTORS.rst>`_. +If you would like to contribute to the project, please have a look at the `open issues `_ and the project `code of conduct <./CODE_OF_CONDUCT.rst>`_. + Credits ####### -This project contains work and contributions from the `scientific community <./CONTRIBUTORS.rst>`_. The Tidal Model Driver (`TMD `_) Matlab Toolbox was developed by Laurie Padman, Lana Erofeeva and Susan Howard. An updated version of the TMD Matlab Toolbox (`TMD3 `_) was developed by Chad Greene. The OSU Tidal Inversion Software (OTIS) and OSU Tidal Prediction Software (`OTPS `_) were developed by Lana Erofeeva and Gary Egbert (`copyright OSU `_, licensed for non-commercial use). diff --git a/doc/source/getting_started/Getting-Started.rst b/doc/source/getting_started/Getting-Started.rst index 4c8e5026..1b333fd2 100644 --- a/doc/source/getting_started/Getting-Started.rst +++ b/doc/source/getting_started/Getting-Started.rst @@ -19,12 +19,32 @@ GOT formatted data use ascii files for each height constituent (``z``). FES formatted data use either ascii (1999, 2004) or netCDF4 (2012, 2014) files for each constituent and variable type (``z``, ``u``, ``v``). The FES models can be downloaded using the `aviso_fes_tides.py `_ program for users registered with AVISO. +Model Database +############## + +``pyTMD`` comes parameterized with models for the prediction of tidal elevations and currents. +All presently available models are stored within a `JSON database `_: + +.. code-block:: python + + >>> import pyTMD + >>> pyTMD.models.current.get('CATS2008') + {'format': 'OTIS', 'grid_file': 'CATS2008/grid_CATS2008', + 'model_file': {'u': 'CATS2008/uv.CATS2008.out'}, 'name': 'CATS2008', + 'projection': 'CATS2008', 'reference': 'https://doi.org/10.15784/601235', + 'type': ['u', 'v']} + >>> pyTMD.models.elevation.get('CATS2008') + {'format': 'OTIS', 'grid_file': 'CATS2008/grid_CATS2008', + 'model_file': 'CATS2008/hf.CATS2008.out', 'name': 'CATS2008', + 'projection': 'CATS2008', 'reference': 'https://doi.org/10.15784/601235', + 'type': 'z', 'variable': 'tide_ocean'} + Directories ########### ``pyTMD`` uses a tree structure for storing the tidal constituent data. This structure was chosen based on the different formats of each tide model. -Presently, the following models and their directories are parameterized within ``pyTMD`` in a JSON database. +Presently, the following models and their directories are parameterized within ``pyTMD``. - Circum-Antarctic Tidal Simulations [Padman2008]_ @@ -133,14 +153,14 @@ elevations or currents (zonal and meridional) for each point. Definition Files ################ -For models within the ``pyTMD`` database, the parameters can be set with a model definition file in JSON format. +For models not currently within the ``pyTMD`` `database <./Getting-Started.html#model-database>`_, the model parameters can be set with a definition file in JSON format. The JSON definition files follow a similar structure as the main ``pyTMD`` database, but for individual entries. The JSON format directly maps the parameter names with their values stored in the appropriate data type (strings, lists, numbers, booleans, etc). For FES-type models of currents, the two lists of model files (``u`` and ``v``) are stored in a name-value pair objects (similar to a python dictionary). While still human readable, the JSON format is both interoperable and more easily machine readable. -Each definition file regardless of the format should have ``name``, ``format`` and ``type`` parameters. -Each model type also requires specific sets of parameters for the model reader. +Each definition file should have ``name``, ``format`` and ``type`` parameters. +Each model type may also require specific sets of parameters for the individual model reader. For models with multiple constituent files, the files can be found using a ``glob`` string to search a directory. - ``OTIS``, ``ATLAS-compact`` and ``TMD3`` @@ -154,7 +174,7 @@ For models with multiple constituent files, the files can be found using a ``glo - ``ATLAS-netcdf`` - * ``compressed``: model files are gzip compressed + * ``compressed``: model files are ``gzip`` compressed * ``format``: ``ATLAS-netcdf`` * ``grid_file``: path to model grid file * ``model_file``: path to model constituent files or a ``glob`` string @@ -164,7 +184,7 @@ For models with multiple constituent files, the files can be found using a ``glo - ``GOT-ascii`` and ``GOT-netcdf`` - * ``compressed``: model files are gzip compressed + * ``compressed``: model files are ``gzip`` compressed * ``format``: ``GOT-ascii`` or ``GOT-netcdf`` * ``model_file``: path to model constituent files or a ``glob`` string * ``name``: tide model name @@ -173,7 +193,7 @@ For models with multiple constituent files, the files can be found using a ``glo - ``FES-ascii`` and ``FES-netcdf`` - * ``compressed``: model files are gzip compressed + * ``compressed``: model files are ``gzip`` compressed * ``format``: ``FES-ascii`` or ``FES-netcdf`` * ``model_file``: path to model constituent files or a ``glob`` string * ``name``: tide model name diff --git a/doc/source/getting_started/Install.rst b/doc/source/getting_started/Install.rst index 65dd19b0..87ca4daa 100644 --- a/doc/source/getting_started/Install.rst +++ b/doc/source/getting_started/Install.rst @@ -52,13 +52,7 @@ To use the development repository, please fork ``pyTMD`` into your own account a git clone https://github.com/tsutterley/pyTMD.git -``pyTMD`` can then be installed within the package directory using ``setuptools``: - -.. code-block:: bash - - python3 setup.py install - -or ``pip`` +``pyTMD`` can then be installed within the package directory using ``pip``: .. code-block:: bash diff --git a/doc/source/release_notes/release-v2.1.6.rst b/doc/source/release_notes/release-v2.1.6.rst new file mode 100644 index 00000000..c946303c --- /dev/null +++ b/doc/source/release_notes/release-v2.1.6.rst @@ -0,0 +1,27 @@ +################## +`Release v2.1.6`__ +################## + +* ``refactor``: use JSON database for known model parameters for `#328 `_ (`#329 `_) +* ``feat``: added new ``TPXO10-atlas-v2`` to list of models (`#329 `_) +* ``feat``: generalize hash function to use any available algorithm (`#329 `_) +* ``fix``: use model name in default output filename for definition file case (`#329 `_) +* ``refactor``: create database from providers (`#329 `_) +* ``refactor``: drop support for the ascii definition file format (`#329 `_) +* ``docs``: add model providers section to contributions (`#329 `_) +* ``ci``: add GitHub Action to update ``database.json`` (`#330 `_) +* ``feat``: Add additional models to provider JSON (`#331 `_) +* ``fix``: add parse constituents back to model load (`#331 `_) +* ``fix``: drop constituents from database (`#331 `_) +* ``ci``: only run ``pytest`` action if secrets are accessible (`#331 `_) +* ``refactor``: use idealized Azimuthal equidistant for Arctic models (`#332 `_) +* ``fix``: deprecation in case where an array is output to scalars (`#332 `_) +* ``fix``: j1 and theta for FES type models for `#335 `_ (`#336 `_) +* ``fix``: nodal corrections for ``eps2`` and ``eta2`` when inferring for GOT5.5 (`#336 `_) +* ``feat``: use model class attributes for file format and corrections (`#336 `_) +* ``feat``: add option to select nodal corrections type (`#336 `_) +* ``feat``: export database as ``dataclass`` (`#337 `_) +* ``docs``: update getting started and ``README.rst`` (`#337 `_) +* ``test``: add test for reading model database (`#337 `_) + +.. __: https://github.com/tsutterley/pyTMD/releases/tag/2.1.6 diff --git a/providers/ESR.json b/providers/ESR.json index 9111592c..30cbb329 100644 --- a/providers/ESR.json +++ b/providers/ESR.json @@ -80,6 +80,7 @@ }, "name": "CATS2008", "projection": "CATS2008", + "reference": "https://doi.org/10.15784/601235", "type": [ "u", "v" diff --git a/providers/README.rst b/providers/README.rst index 5f7ba786..d27088cd 100644 --- a/providers/README.rst +++ b/providers/README.rst @@ -8,4 +8,4 @@ The main database is created by merging the model provider JSON files - ``ESR``: `Earth and Space Research Polar Tide Models `_ - ``GSFC``: `NASA Goddard Space Flight Center Global Tide Models `_ - ``TPXO``: `Oregon State University TPXO Tide Models `_ -- ``providers``: Additional or stand-alone model providers +- ``providers``: Additional or stand-alone model providers diff --git a/providers/providers.json b/providers/providers.json index 9c7eb02b..326fa3d9 100644 --- a/providers/providers.json +++ b/providers/providers.json @@ -8,23 +8,13 @@ }, "name": "CATS2008-v2023", "projection": "CATS2008", + "reference": "https://doi.org/10.15784/601772", "type": [ "u", "v" ] }, "HAMTIDE11": { - "constituents": [ - "2n2", - "k1", - "k2", - "m2", - "n2", - "o1", - "p1", - "q1", - "s2" - ], "format": "FES-netcdf", "model_file": { "u": [ @@ -67,30 +57,11 @@ "model_file": "CATS2008_v2023/CATS2008_v2023.nc", "name": "CATS2008-v2023", "projection": "CATS2008", - "reference": "https://www.esr.org/research/polar-tide-models/list-of-polar-tide-models/cats2008/", + "reference": "https://doi.org/10.15784/601772", "type": "z", "variable": "tide_ocean" }, "EOT20": { - "constituents": [ - "2n2", - "j1", - "k1", - "k2", - "m2", - "m4", - "mf", - "mm", - "n2", - "o1", - "p1", - "q1", - "s1", - "s2", - "sa", - "ssa", - "t2" - ], "format": "FES-netcdf", "model_file": [ "EOT20/ocean_tides/2N2_ocean_eot20.nc", @@ -119,25 +90,6 @@ "version": "EOT20" }, "EOT20_load": { - "constituents": [ - "2n2", - "j1", - "k1", - "k2", - "m2", - "m4", - "mf", - "mm", - "n2", - "o1", - "p1", - "q1", - "s1", - "s2", - "sa", - "ssa", - "t2" - ], "format": "FES-netcdf", "model_file": [ "EOT20/load_tides/2N2_load_eot20.nc", @@ -166,17 +118,6 @@ "version": "EOT20" }, "HAMTIDE11": { - "constituents": [ - "2n2", - "k1", - "k2", - "m2", - "n2", - "o1", - "p1", - "q1", - "s2" - ], "format": "FES-netcdf", "model_file": [ "hamtide/2n.hamtide11a.nc", diff --git a/pyTMD/__init__.py b/pyTMD/__init__.py index aeb5e208..a1bdbe26 100644 --- a/pyTMD/__init__.py +++ b/pyTMD/__init__.py @@ -44,3 +44,5 @@ # get semantic version from setuptools-scm __version__ = pyTMD.version.version +# read model database +models = io.load_database() diff --git a/pyTMD/data/database.json b/pyTMD/data/database.json index 70c26fb7..1549cdea 100644 --- a/pyTMD/data/database.json +++ b/pyTMD/data/database.json @@ -80,6 +80,7 @@ }, "name": "CATS2008", "projection": "CATS2008", + "reference": "https://doi.org/10.15784/601235", "type": [ "u", "v" @@ -93,6 +94,7 @@ }, "name": "CATS2008-v2023", "projection": "CATS2008", + "reference": "https://doi.org/10.15784/601772", "type": [ "u", "v" @@ -214,17 +216,6 @@ "version": "v1" }, "HAMTIDE11": { - "constituents": [ - "2n2", - "k1", - "k2", - "m2", - "n2", - "o1", - "p1", - "q1", - "s2" - ], "format": "FES-netcdf", "model_file": { "u": [ @@ -836,7 +827,7 @@ "model_file": "CATS2008_v2023/CATS2008_v2023.nc", "name": "CATS2008-v2023", "projection": "CATS2008", - "reference": "https://www.esr.org/research/polar-tide-models/list-of-polar-tide-models/cats2008/", + "reference": "https://doi.org/10.15784/601772", "type": "z", "variable": "tide_ocean" }, @@ -851,25 +842,6 @@ "variable": "tide_load" }, "EOT20": { - "constituents": [ - "2n2", - "j1", - "k1", - "k2", - "m2", - "m4", - "mf", - "mm", - "n2", - "o1", - "p1", - "q1", - "s1", - "s2", - "sa", - "ssa", - "t2" - ], "format": "FES-netcdf", "model_file": [ "EOT20/ocean_tides/2N2_ocean_eot20.nc", @@ -898,25 +870,6 @@ "version": "EOT20" }, "EOT20_load": { - "constituents": [ - "2n2", - "j1", - "k1", - "k2", - "m2", - "m4", - "mf", - "mm", - "n2", - "o1", - "p1", - "q1", - "s1", - "s2", - "sa", - "ssa", - "t2" - ], "format": "FES-netcdf", "model_file": [ "EOT20/load_tides/2N2_load_eot20.nc", @@ -1601,17 +1554,6 @@ "version": "v1" }, "HAMTIDE11": { - "constituents": [ - "2n2", - "k1", - "k2", - "m2", - "n2", - "o1", - "p1", - "q1", - "s2" - ], "format": "FES-netcdf", "model_file": [ "hamtide/2n.hamtide11a.nc", diff --git a/pyTMD/io/model.py b/pyTMD/io/model.py index 7c0555c8..44232dc3 100644 --- a/pyTMD/io/model.py +++ b/pyTMD/io/model.py @@ -9,6 +9,7 @@ Updated 09/2024: use JSON database for known model parameters drop support for the ascii definition file format add file_format and nodal correction attributes + export database as a dataclass for easier access Updated 08/2024: added attribute for minor constituents to infer allow searching over iterable glob strings in definition files added option to try automatic detection of definition file format @@ -62,9 +63,32 @@ import pyTMD.io.constituents from pyTMD.utilities import get_data_path from collections.abc import Iterable +from dataclasses import dataclass + +@dataclass +class DataBase: + """Class for pyTMD model database""" + current: dict + elevation: dict + + def keys(self): + """Returns the keys of the model database""" + return self.__dict__.keys() + + def values(self): + """Returns the values of the model database""" + return self.__dict__.values() + + def items(self): + """Returns the items of the model database""" + return self.__dict__.items() + + def __getitem__(self, key): + return getattr(self, key) + # PURPOSE: load the JSON database of model files -def load_database(extra_databases: list = []) -> dict: +def load_database(extra_databases: list = []): """ Load the JSON database of model files @@ -88,7 +112,7 @@ def load_database(extra_databases: list = []) -> dict: with open(db, 'r', encoding='utf-8') as fid: parameters.update(json.load(fid)) # return parameters - return parameters + return DataBase(**parameters) class model: """Retrieves tide model parameters for named models or diff --git a/test/test_model.py b/test/test_model.py index 57768a0e..f4647e01 100644 --- a/test/test_model.py +++ b/test/test_model.py @@ -685,3 +685,19 @@ def test_parse_TPXO9_currents(MODEL): assert all(c in m.constituents for c in ['mf','mm']) if m.name in ('TPXO9-atlas-v5',): assert all(c in m.constituents for c in ['s1',]) + +# PURPOSE: test reading of model database +def test_read_database(): + """Tests the reading of the pyTMD model database + """ + database = pyTMD.io.load_database() + # for each database entry + for key, val in database.items(): + assert isinstance(key, str) + assert val == pyTMD.models[key] + # assert DataBase class entries + pyTMD.models.current == database['current'] + pyTMD.models.elevation == database['elevation'] + # assert that models are accessible + assert pyTMD.models.elevation.get('CATS2008') is not None + assert pyTMD.models.current.get('CATS2008') is not None diff --git a/version.txt b/version.txt index cd57a8b9..399088bf 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -2.1.5 +2.1.6