diff --git a/doc/environment.yml b/doc/environment.yml index 5fc68e3e..52eea214 100644 --- a/doc/environment.yml +++ b/doc/environment.yml @@ -19,6 +19,7 @@ dependencies: - setuptools_scm - sphinx - sphinx-argparse>=0.4 + - sphinxcontrib-bibtex - sphinx-design - sphinx_rtd_theme - timescale>=0.0.3 diff --git a/doc/source/_assets/pytmd-refs.bib b/doc/source/_assets/pytmd-refs.bib new file mode 100644 index 00000000..f51fa982 --- /dev/null +++ b/doc/source/_assets/pytmd-refs.bib @@ -0,0 +1,574 @@ +@inbook{Agnew:2015kw, +author = {Agnew, D C}, +title = {{Earth Tides}}, +journal = {Treatise on Geophysics}, +year = {2015}, +url = {https://doi.org/10.1016/b978-0-444-53802-4.00058-0}, +doi = {10.1016/B978-0-444-53802-4.00058-0}, +pages = {151--178}, +publisher = {Elsevier}, +} +@article{Bowring:1976jh, +author = {Bowring, B R}, +title = {{TRANSFORMATION FROM SPATIAL TO GEOGRAPHICAL COORDINATES}}, +journal = {Survey Review}, +year = {1976}, +month = jul, +volume = {23}, +number = {181}, +issn = {0039-6265}, +url = {https://doi.org/10.1179/sre.1976.23.181.323}, +doi = {10.1179/sre.1976.23.181.323}, +pages = {323--327}, +publisher = {Informa UK Limited}, +} +@article{Bowring:1985du, +author = {Bowring, B R}, +title = {{THE ACCURACY OF GEODETIC LATITUDE AND HEIGHT EQUATIONS}}, +journal = {Survey Review}, +year = {1985}, +month = oct, +volume = {28}, +number = {218}, +issn = {0039-6265}, +url = {https://doi.org/10.1179/sre.1985.28.218.202}, +doi = {10.1179/sre.1985.28.218.202}, +pages = {202--206}, +publisher = {Informa UK Limited}, +} +@article{Capitaine:2003fx, +author = {Capitaine, N and Wallace, P T and Chapront, J}, +title = {{Expressions for IAU 2000 precession quantities}}, +journal = {Astronomy & Astrophysics}, +year = {2003}, +month = dec, +volume = {412}, +number = {2}, +issn = {0004-6361}, +url = {https://doi.org/10.1051/0004-6361:20031539}, +doi = {10.1051/0004-6361:20031539}, +pages = {567--586}, +publisher = {EDP Sciences}, +} +@article{Capitaine:2003fw, +author = {Capitaine, N and Chapront, J and Lambert, S and Wallace, P T}, +title = {{Expressions for the Celestial Intermediate Pole and Celestial Ephemeris Origin consistent with the IAU 2000A precession-nutation model}}, +journal = {Astronomy & Astrophysics}, +year = {2003}, +month = mar, +volume = {400}, +number = {3}, +issn = {0004-6361}, +url = {https://doi.org/10.1051/0004-6361:20030077}, +doi = {10.1051/0004-6361:20030077}, +pages = {1145--1154}, +publisher = {EDP Sciences}, +} +@article{Cartwright:1971iz, +author = {Cartwright, D E and Tayler, R J}, +title = {{New Computations of the Tide-generating Potential}}, +journal = {Geophysical Journal of the Royal Astronomical Society}, +year = {1971}, +month = jun, +volume = {23}, +number = {1}, +issn = {0956-540X}, +url = {http://dx.doi.org/10.1111/j.1365-246X.1971.tb01803.x}, +doi = {10.1111/j.1365-246X.1971.tb01803.x}, +pages = {45--73}, +} +@article{Cartwright:1973em, +author = {Cartwright, D E and Edden, A C}, +title = {{Corrected Tables of Tidal Harmonics}}, +journal = {Geophysical Journal International}, +year = {1973}, +month = sep, +volume = {33}, +number = {3}, +issn = {0956-540X}, +url = {https://doi.org/10.1111/j.1365-246x.1973.tb03420.x}, +doi = {10.1111/j.1365-246X.1973.tb03420.x}, +pages = {253--264}, +publisher = {Oxford University Press (OUP)}, +} +@book{Cartwright:1999tj, +author = {Cartwright, David Edgar}, +title = {{Tides : a scientific history}}, +year = {1999}, +isbn = {0521621453}, +publisher = {Cambridge University Press}, +address = {New York, NY}, +} +@book{Dehant:2015vb, +author = {Dehant, V and Mathews, P M}, +title = {{Precession, nutation, and wobble of the Earth}}, +year = {2015}, +isbn = {9781107092549}, +publisher = {Cambridge University Press}, +address = {Cambridge, UK}, +} +@book{Dershowitz:2007cc, +author = {Dershowitz, N and Reingold, E M}, +title = {{Calendrical Calculations}}, +year = {2007}, +url = {https://doi.org/10.1017/CBO9781107051119}, +doi = {10.1017/CBO9781107051119}, +publisher = {Cambridge University Press}, +edition = {3}, +} +@article{Desai:2002ev, +author = {Desai, S}, +title = {{Observing the pole tide with satellite altimetry}}, +journal = {Journal of Geophysical Research: Oceans}, +year = {2002}, +month = nov, +volume = {107}, +number = {C11}, +issn = {0148-0227}, +url = {https://doi.org/10.1029/2001jc001224}, +doi = {10.1029/2001JC001224}, +publisher = {American Geophysical Union (AGU)}, +} +@article{Desai:2015jr, +author = {Desai, S and Wahr, J and Beckley, B}, +title = {{Revisiting the pole tide for and from satellite altimetry}}, +journal = {Journal of Geodesy}, +year = {2015}, +month = dec, +volume = {89}, +number = {12}, +issn = {0949-7714}, +url = {https://doi.org/10.1007/s00190-015-0848-7}, +doi = {10.1007/s00190-015-0848-7}, +pages = {1233--1243}, +publisher = {Springer Science and Business Media LLC}, +} +@article{Doodson:1921kt, +author = {Doodson, A T and Lamb, H}, +title = {{The harmonic development of the tide-generating potential}}, +journal = {Proceedings of the Royal Society of London. Series A, Containing Papers of a Mathematical and Physical Character}, +year = {1921}, +month = dec, +volume = {100}, +number = {704}, +url = {https://doi.org/10.1098/rspa.1921.0088}, +doi = {10.1098/rspa.1921.0088}, +pages = {305--329}, +publisher = {Royal Society}, +} +@book{Doodson:1941td, +author = {Doodson, A T and Warburg, H D}, +title = {{Admiralty Manual of Tides}}, +year = {1941}, +publisher = {His Majesty's Stationery Office}, +address = {London}, +} +@article{Egbert:2002ge, +author = {Egbert, G D and Erofeeva, S Y}, +title = {{Efficient Inverse Modeling of Barotropic Ocean Tides}}, +journal = {Journal of Atmospheric and Oceanic Technology}, +year = {2002}, +month = feb, +volume = {19}, +number = {2}, +issn = {0739-0572}, +url = {https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2}, +doi = {10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2}, +pages = {183--204}, +publisher = {American Meteorological Society}, +} +@article{Foreman:1989dt, +author = {Foreman, M G and Henry, R F}, +title = {{The harmonic analysis of tidal model time series}}, +journal = {Advances in Water Resources}, +year = {1989}, +month = sep, +volume = {12}, +number = {3}, +issn = {0309-1708}, +url = {https://doi.org/10.1016/0309-1708(89)90017-1}, +doi = {10.1016/0309-1708(89)90017-1}, +pages = {109--120}, +publisher = {Elsevier BV}, +} +@article{HartDavis:2021dx, +author = {Hart-Davis, M G and Piccioni, G and Dettmering, D and Schwatke, C and Passaro, M and Seitz, F}, +title = {{EOT20: a global ocean tide model from multi-mission satellite altimetry}}, +journal = {Earth System Science Data}, +year = {2021}, +month = aug, +volume = {13}, +number = {8}, +issn = {1866-3516}, +url = {https://doi.org/10.5194/essd-13-3869-2021}, +doi = {10.5194/essd-13-3869-2021}, +pages = {3869--3884}, +publisher = {Copernicus GmbH}, +} +@article{Hatcher:1984uo, +author = {Hatcher, D A}, +title = {{Simple Formulae for Julian Day Numbers and Calendar Dates}}, +journal = {Quarterly Journal of the Royal Astronomical Society}, +year = 1984, +month = mar, +url = {https://ui.adsabs.harvard.edu/abs/1984QJRAS..25...53H}, +key = {1984QJRAS..25...53H}, +volume = {25}, +pages = {53--55}, +publisher = {Royal Astronomical Society}, +note = {Provided by the SAO/NASA Astrophysics Data System} +} +@book{HofmannWellenhof:2006hy, +author = {Hofmann-Wellenhof, B and Moritz, H}, +title = {{Physical Geodesy}}, +year = {2006}, +isbn = {9783211335444}, +url = {https://doi.org/10.1007/978-3-211-33545-1}, +doi = {10.1007/978-3-211-33545-1}, +publisher = {Springer Vienna}, +} +@article{Horner:1819br, +author = {Horner, W G and Gilbert, D}, +title = {{XXI. A new method of solving numerical equations of all orders, by continuous approximation}}, +journal = {Philosophical Transactions of the Royal Society of London}, +year = {1819}, +volume = {109}, +url = {https://doi.org/10.1098/rstl.1819.0023}, +doi = {10.1098/rstl.1819.0023}, +pages = {308--335}, +publisher = {Royal Society}, +} +@book{Kantha:2000vo, +author = {Kantha, L H and Clayson, C A}, +title = {{Numerical models of oceans and oceanic processes}}, +year = {2000}, +volume = {66}, +isbn = {0124340687}, +publisher = {Academic Press}, +address = {San Diego, CA}, +} +@article{Lyard:2021fk, +author = {Lyard, F H and Allain, D J and Cancet, M and Carr{\`e}re, L and Picot, N}, +title = {{FES2014 global ocean tide atlas: design and performance}}, +journal = {Ocean Science}, +year = {2021}, +volume = {17}, +number = {3}, +url = {https://doi.org/10.5194/os-17-615-2021}, +doi = {10.5194/os-17-615-2021}, +pages = {615--649}, +} +@article{Mathews:1991kv, +author = {Mathews, P M and Buffett, B A and Herring, T A and Shapiro, I I}, +title = {{Forced nutations of the Earth: Influence of inner core dynamics: 1. Theory}}, +journal = {Journal of Geophysical Research: Solid Earth}, +year = {1991}, +month = may, +volume = {96}, +number = {B5}, +issn = {0148-0227}, +url = {https://doi.org/10.1029/90jb01955}, +doi = {10.1029/90JB01955}, +pages = {8219--8242}, +publisher = {American Geophysical Union (AGU)}, +} +@article{Mathews:1995go, +author = {Mathews, P M and Buffett, B A and Shapiro, I I}, +title = {{Love numbers for diurnal tides: Relation to wobble admittances and resonance expansions}}, +journal = {Journal of Geophysical Research: Solid Earth}, +year = {1995}, +month = jun, +volume = {100}, +number = {B6}, +issn = {0148-0227}, +url = {https://doi.org/10.1029/95jb00670}, +doi = {10.1029/95jb00670}, +pages = {9935--9948}, +publisher = {American Geophysical Union (AGU)}, +} +@article{Mathews:1997js, +author = {Mathews, P M and Dehant, V and Gipson, J M}, +title = {{Tidal station displacements}}, +journal = {Journal of Geophysical Research: Solid Earth}, +year = {1997}, +month = sep, +volume = {102}, +number = {B9}, +issn = {0148-0227}, +url = {https://doi.org/10.1029/97jb01515}, +doi = {10.1029/97JB01515}, +pages = {20469--20477}, +publisher = {American Geophysical Union (AGU)}, +} +@book{Meeus:1991vh, +author = {Meeus, J H}, +title = {{Astronomical Algorithms}}, +year = {1991}, +isbn = {0943396352}, +publisher = {Willmann-Bell, Inc.}, +address = {Richmond, VA}, +} +@book{Montenbruck:1989uk, +author = {Montenbruck, O}, +title = {{Practical Ephemeris Calculations}}, +year = {1989}, +url = {https://ui.adsabs.harvard.edu/abs/1989pec..book.....M}, +publisher = {Springer-Verlag}, +address = {New York, NY}, +note = {Provided by the SAO/NASA Astrophysics Data System}, +key = {1989pec..book.....M}, +} +@article{Munk:1966go, +author = {Munk, W H and Cartwright, D E and Bullard, E C}, +title = {{Tidal spectroscopy and prediction}}, +journal = {Philosophical Transactions of the Royal Society of London. Series A, Mathematical and Physical Sciences}, +year = {1966}, +volume = {259}, +number = {1105}, +url = {https://doi.org/10.1098/rsta.1966.0024}, +doi = {10.1098/rsta.1966.0024}, +pages = {533--581}, +publisher = {Royal Society}, +} +@article{Padman:2004hv, +author = {Padman, L and Erofeeva, S}, +title = {{A barotropic inverse tidal model for the Arctic Ocean}}, +journal = {Geophysical Research Letters}, +year = {2004}, +month = jan, +volume = {31}, +number = {2}, +issn = {0094-8276}, +url = {https://doi.org/10.1029/2003gl019003}, +doi = {10.1029/2003GL019003}, +publisher = {American Geophysical Union (AGU)}, +} +@article{Padman:2008ec, +author = {Padman, L and Erofeeva, S Y and Fricker, H A}, +title = {{Improving Antarctic tide models by assimilation of ICESat laser altimetry over ice shelves}}, +journal = {Geophysical Research Letters}, +year = {2008}, +month = nov, +volume = {35}, +number = {22}, +issn = {0094-8276}, +url = {https://doi.org/10.1029/2008gl035592}, +doi = {10.1029/2008GL035592}, +publisher = {American Geophysical Union (AGU)}, +} +@article{Padman:2018cv, +author = {Padman, L and Siegfried, M R and Fricker, H A}, +title = {{Ocean Tide Influences on the Antarctic and Greenland Ice Sheets}}, +journal = {Reviews of Geophysics}, +year = {2018}, +month = mar, +volume = {56}, +number = {1}, +issn = {8755-1209}, +url = {https://doi.org/10.1002/2016rg000546}, +doi = {10.1002/2016RG000546}, +pages = {142--184}, +publisher = {American Geophysical Union (AGU)}, +} +@article{Park:2021fa, +author = {Park, R S and Folkner, W M and Williams, J G and Boggs, D H}, +title = {{The JPL Planetary and Lunar Ephemerides DE440 and DE441}}, +journal = {The Astronomical Journal}, +year = {2021}, +month = mar, +volume = {161}, +number = {3}, +issn = {0004-6256}, +url = {https://doi.org/10.3847/1538-3881/abd414}, +doi = {10.3847/1538-3881/abd414}, +pages = {105}, +publisher = {American Astronomical Society}, +} +@techreport{Petit:2010tp, +author = {Petit, G and Luzum, B}, +title = {{IERS Conventions (2010)}}, +year = {2010}, +number = {36}, +url = {http://www.iers.org/nn_11216/IERS/EN/Publications/TechnicalNotes/tn36.html}, +publisher = {International Earth Rotation and Reference Systems Service (IERS)}, +affiliation = {Frankfurt am Main: Verlag des Bundesamts f{\:u}r Kartographie und Geod{\:a}sie}, +institution = {Bureau International des Poids et Mesures (BIPM), US Naval Observatory (USNO)}, +} +@book{Press:1988we, +author = {Press, W H}, +editor = {Flannery, Brian P and Teukolsky, Saul A and Vetterling, William, T}, +title = {{Numerical Recipes in C}}, +year = {1988}, +url = {https://numerical.recipes}, +publisher = {Cambridge University Press}, +address = {New York, NY}, +} +@techreport{Ray:1999vm, +author = {Ray, R D}, +title = {{A global ocean tide model from Topex/Poseidon altimetry: GOT99.2}}, +year = {1999}, +month = sep, +number = {TM-1999-209478}, +url = {https://ntrs.nasa.gov/citations/19990089548}, +institution = {NASA Goddard Space Flight Center}, +publisher = {NASA Goddard Space Flight Center}, +address = {Greenbelt, MD}, +} +@article{Ray:2014fu, +author = {Ray, R D and Erofeeva, S Y}, +title = {{Long-period tidal variations in the length of day}}, +journal = {Journal of Geophysical Research: Solid Earth}, +year = {2014}, +month = feb, +volume = {119}, +number = {2}, +issn = {2169-9313}, +url = {https://doi.org/10.1002/2013jb010830}, +doi = {10.1002/2013JB010830}, +pages = {1498--1509}, +publisher = {American Geophysical Union (AGU)}, +} +@article{Ray:2017jx, +author = {Ray, R D}, +title = {{On Tidal Inference in the Diurnal Band}}, +journal = {Journal of Atmospheric and Oceanic Technology}, +year = {2017}, +month = feb, +volume = {34}, +number = {2}, +issn = {0739-0572}, +url = {https://doi.org/10.1175/jtech-d-16-0142.1}, +doi = {10.1175/jtech-d-16-0142.1}, +pages = {437--446}, +publisher = {American Meteorological Society}, +} +@article{Ries:1992ip, +author = {Ries, J C and Eanes, R J and Shum, C K and Watkins, M M}, +title = {{Progress in the determination of the gravitational coefficient of the Earth}}, +journal = {Geophysical Research Letters}, +year = {1992}, +month = mar, +volume = {19}, +number = {6}, +issn = {0094-8276}, +url = {https://doi.org/10.1029/92gl00259}, +doi = {10.1029/92GL00259}, +pages = {529--531}, +publisher = {American Geophysical Union (AGU)}, +} +@techreport{Schureman:1958ty, +author = {Schureman, P}, +title = {{Manual of Harmonic Analysis and Prediction of Tides}}, +year = {1958}, +number = {Special Edition No. 98}, +url = {https://tidesandcurrents.noaa.gov/publications/SpecialPubNo98.pdf}, +institution = {US Coast and Geodetic Survey}, +publisher = {United States Government Printing Office}, +address = {Washington, DC}, +} +@article{Simon:1994vo, +author = {Simon, J L and Bretagnon, P and Chapront, J and Chapront-Touz{\'e}, M and Francou, G and Laskar, J}, +title = {{Numerical expressions for precession formulae and mean elements for the Moon and the planets}}, +journal = {Astronomy and Astrophysics}, +year = {1994}, +month = feb, +volume = {282}, +url = {https://ui.adsabs.harvard.edu/abs/1994A&A...282..663S}, +key = {1994A&A...282..663S}, +pages = {663--683}, +note = {Provided by the SAO/NASA Astrophysics Data System}, +keywords = {Celestial Mechanics, Moon, Numerical Analysis, Orbital Elements, Planets, Precession, Eccentricity, Ephemerides, Occultation, Perihelions, Secular Variations, PLANETS, MOON, NUMERICAL METHODS, PRECESSION, SATELLITES, TECHNIQUES, CELESTIAL MECHANICS, MASS, OBLIQUITY, EPHEMERIDES, CALCULATIONS, DATA, PARAMETERS, ORBITAL ELEMENTS, ORBIT, Astrophysics; Planets}, +} +@techreport{Snyder:1982gf, +author = {Snyder, J P}, +title = {{Map projections used by the U.S. Geological Survey}}, +year = {1982}, +number = {Geological Survey Bulletin 1532}, +url = {https://pubs.usgs.gov/publication/b1532}, +doi = {10.3133/b1532}, +institution = {United States Geological Survey}, +publisher = {United States Government Printing Office}, +} +@article{Stammer:2014ci, +author = {Stammer, D and Ray, R D and Andersen, O B and Arbic, B K and Bosch, W and Carr{\`e}re, L and Cheng, Y and Chinn, D S and Dushaw, B D and Egbert, G D and Erofeeva, S Y and Fok, H S and Green, J A M and Griffiths, S and King, M A and Lapin, V and Lemoine, F G and Luthcke, S B and Lyard, F and Morison, J and M{\"u}ller, M and Padman, L and Richman, J G and Shriver, J F and Shum, C K and Taguchi, E and Yi, Y}, +title = {{Accuracy assessment of global barotropic ocean tide models}}, +journal = {Reviews of Geophysics}, +year = {2014}, +month = sep, +volume = {52}, +number = {3}, +issn = {8755-1209}, +url = {https://doi.org/10.1002/2014rg000450}, +doi = {10.1002/2014RG000450}, +pages = {243--282}, +publisher = {American Geophysical Union (AGU)}, +} +@article{Taguchi:2014ht, +author = {Taguchi, E and Stammer, D and Zahel, W}, +title = {{Inferring deep ocean tidal energy dissipation from the global high-resolution data-assimilative HAMTIDE model}}, +journal = {Journal of Geophysical Research: Oceans}, +year = {2014}, +month = jul, +volume = {119}, +number = {7}, +issn = {2169-9275}, +url = {https://doi.org/10.1002/2013jc009766}, +doi = {10.1002/2013JC009766}, +pages = {4573--4592}, +publisher = {American Geophysical Union (AGU)}, +} +@article{Wahr:1981ea, +author = {Wahr, J M}, +title = {{Body tides on an elliptical, rotating, elastic and oceanless Earth}}, +journal = {Geophysical Journal of the Royal Astronomical Society}, +year = {1981}, +volume = {64}, +number = {3}, +issn = {1365-246X}, +url = {http://dx.doi.org/10.1111/j.1365-246X.1981.tb02690.x}, +doi = {10.1111/j.1365-246X.1981.tb02690.x}, +pages = {677--703}, +publisher = {Blackwell Publishing Ltd}, +} +@article{Wahr:1981if, +author = {Wahr, J M and Sasao, T}, +title = {{A diurnal resonance in the ocean tide and in the Earth's load response due to the resonant free `core nutation'}}, +journal = {Geophysical Journal of the Royal Astronomical Society}, +year = {1981}, +month = mar, +volume = {64}, +number = {3}, +issn = {0016-8009}, +url = {https://doi.org/10.1111/j.1365-246x.1981.tb02693.x}, +doi = {10.1111/j.1365-246X.1981.tb02693.x}, +pages = {747--765}, +publisher = {Oxford University Press (OUP)}, +} +@article{Wahr:1985gr, +author = {Wahr, J M}, +title = {{Deformation induced by polar motion}}, +journal = {Journal of Geophysical Research: Solid Earth}, +year = {1985}, +month = sep, +volume = {90}, +number = {B11}, +issn = {0148-0227}, +url = {https://doi.org/10.1029/jb090ib11p09363}, +doi = {10.1029/JB090iB11p09363}, +pages = {9363--9368}, +publisher = {American Geophysical Union (AGU)}, +} +@article{Zhu:1993ja, +author = {Zhu, J}, +title = {{Exact conversion of earth-centered, earth-fixed coordinates to geodetic coordinates}}, +journal = {Journal of Guidance, Control, and Dynamics}, +year = {1993}, +month = mar, +volume = {16}, +number = {2}, +issn = {0731-5090}, +url = {https://doi.org/10.2514/3.21016}, +doi = {10.2514/3.21016}, +pages = {389--391}, +publisher = {American Institute of Aeronautics and Astronautics (AIAA)}, +} diff --git a/doc/source/api_reference/check_points.rst b/doc/source/api_reference/check_points.rst deleted file mode 100644 index 81bec012..00000000 --- a/doc/source/api_reference/check_points.rst +++ /dev/null @@ -1,22 +0,0 @@ -============ -check_points -============ - -- Check if points are within a tide model domain -- Can check OTIS format tidal solutions provided by Oregon State University and ESR -- Can check Global Tide Model (GOT) solutions provided by Richard Ray at GSFC -- Can check Finite Element Solution (FES) models provided by AVISO - -Calling Sequence ----------------- - -.. code-block:: python - - import pyTMD - valid = pyTMD.check_points(x, y, DIRECTORY=DIRECTORY, MODEL=MODEL, EPSG=3031) - -`Source code`__ - -.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/check_points.py - -.. autofunction:: pyTMD.check_points diff --git a/doc/source/api_reference/compute.rst b/doc/source/api_reference/compute.rst index b677674b..8e2fc7d1 100644 --- a/doc/source/api_reference/compute.rst +++ b/doc/source/api_reference/compute.rst @@ -47,6 +47,8 @@ Calling Sequence .. autofunction:: pyTMD.compute.tide_currents +.. autofunction:: pyTMD.compute.tide_masks + .. autofunction:: pyTMD.compute.LPET_elevations .. autofunction:: pyTMD.compute.LPT_displacements diff --git a/doc/source/api_reference/compute_LPET_elevations.rst b/doc/source/api_reference/compute_LPET_elevations.rst index dbc1f238..714dd687 100644 --- a/doc/source/api_reference/compute_LPET_elevations.rst +++ b/doc/source/api_reference/compute_LPET_elevations.rst @@ -3,7 +3,7 @@ compute_LPET_elevation.py ========================= - Calculates long-period equilibrium tides for an input file -- Uses the summation of fifteen tidal spectral lines from [Cartwright1971]_ [Cartwright1973]_ +- Uses the summation of fifteen tidal spectral lines from :cite:p:`Cartwright:1971iz` :cite:p:`Cartwright:1973em` - Can read and write ascii, netCDF4, HDF5, (cloud optimized) geotiff and (geo)parquet formats `Source code`__ @@ -52,17 +52,3 @@ Calling Sequence --projection : @after * ``4326``: latitude and longitude coordinates on WGS84 reference ellipsoid - -References -########## - -.. [Cartwright1971] D. E. Cartwright and R. J. Tayler, - "New Computations of the Tide-generating Potential," - *Geophysical Journal of the Royal Astronomical Society*, - 23(1), 45--73. (1971). `doi: 10.1111/j.1365-246X.1971.tb01803.x - `_ -.. [Cartwright1973] D. E. Cartwright and A. C. Edden, - "Corrected Tables of Tidal Harmonics," - *Geophysical Journal of the Royal Astronomical Society*, - 33(3), 253--264, (1973). `doi: 10.1111/j.1365-246X.1973.tb03420.x - `_ diff --git a/doc/source/api_reference/compute_LPT_displacements.rst b/doc/source/api_reference/compute_LPT_displacements.rst index d22c9e6c..0634fbeb 100644 --- a/doc/source/api_reference/compute_LPT_displacements.rst +++ b/doc/source/api_reference/compute_LPT_displacements.rst @@ -2,7 +2,7 @@ compute_LPT_displacements.py ============================ -- Calculates radial pole load tide displacements for an input file following IERS Convention (2010) guidelines +- Calculates radial pole load tide displacements for an input file following :cite:p:`Petit:2010tp` * `https://iers-conventions.obspm.fr/chapter7.php `_ - Can read and write ascii, netCDF4, HDF5, (cloud optimized) geotiff and (geo)parquet formats diff --git a/doc/source/api_reference/compute_OPT_displacements.rst b/doc/source/api_reference/compute_OPT_displacements.rst index d5d4d389..9ad4be34 100644 --- a/doc/source/api_reference/compute_OPT_displacements.rst +++ b/doc/source/api_reference/compute_OPT_displacements.rst @@ -2,7 +2,7 @@ compute_OPT_displacements.py ============================ -- Calculates radial ocean pole load tide displacements for an input file following IERS Convention (2010) guidelines +- Calculates radial ocean pole load tide displacements for an input file following :cite:p:`Petit:2010tp` * `https://iers-conventions.obspm.fr/chapter7.php `_ * `ftp://tai.bipm.org/iers/conv2010/chapter7/opoleloadcoefcmcor.txt.gz `_ diff --git a/doc/source/api_reference/compute_SET_displacements.rst b/doc/source/api_reference/compute_SET_displacements.rst index a9009da0..31acf71e 100644 --- a/doc/source/api_reference/compute_SET_displacements.rst +++ b/doc/source/api_reference/compute_SET_displacements.rst @@ -2,7 +2,7 @@ compute_SET_displacements.py ============================ -- Calculates radial solid Earth tide displacements for an input file following IERS Convention (2010) guidelines +- Calculates radial solid Earth tide displacements for an input file following :cite:p:`Petit:2010tp` * `https://iers-conventions.obspm.fr/chapter7.php `_ - Can read and write ascii, netCDF4, HDF5, (cloud optimized) geotiff and (geo)parquet formats diff --git a/doc/source/api_reference/compute_tidal_currents.rst b/doc/source/api_reference/compute_tidal_currents.rst index 55b1b9ea..88e0424d 100644 --- a/doc/source/api_reference/compute_tidal_currents.rst +++ b/doc/source/api_reference/compute_tidal_currents.rst @@ -2,7 +2,7 @@ compute_tidal_currents.py ========================= -- Calculates tidal currents for an input file following [Egbert2002]_ +- Calculates tidal currents for an input file following :cite:p:`Egbert:2002ge` - Can use OTIS format tidal solutions provided by Oregon State University and ESR - Can use Finite Element Solution (FES) models provided by AVISO - Can read and write ascii, netCDF4, HDF5, (cloud optimized) geotiff and (geo)parquet formats @@ -56,13 +56,3 @@ Calling Sequence --cutoff -c : @after * set to ``'inf'`` to extrapolate for all points - -References -########## - -.. [Egbert2002] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of - Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic - Technology*, 19(2), 183--204, (2002). - `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__ - -.. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2 diff --git a/doc/source/api_reference/compute_tidal_elevations.rst b/doc/source/api_reference/compute_tidal_elevations.rst index 20f2b06b..9f9cbcef 100644 --- a/doc/source/api_reference/compute_tidal_elevations.rst +++ b/doc/source/api_reference/compute_tidal_elevations.rst @@ -2,7 +2,7 @@ compute_tidal_elevations.py =========================== -- Calculates tidal elevations for an input file following [Egbert2002]_ +- Calculates tidal elevations for an input file following :cite:p:`Egbert:2002ge` - Can use OTIS format tidal solutions provided by Oregon State University and ESR - Can use Global Tide Model (GOT) solutions provided by Richard Ray at GSFC - Can use Finite Element Solution (FES) models provided by AVISO @@ -60,14 +60,3 @@ Calling Sequence --apply-flexure : @after Only valid for models containing flexure fields - -References -########## - -.. [Egbert2002] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of - Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic - Technology*, 19(2), 183--204, (2002). - `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__ - -.. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2 - diff --git a/doc/source/api_reference/crs.rst b/doc/source/api_reference/crs.rst index f2c841f7..6dc9d129 100644 --- a/doc/source/api_reference/crs.rst +++ b/doc/source/api_reference/crs.rst @@ -3,7 +3,7 @@ crs === - Coordinates Reference System (CRS) routines -- Gravitational and ellipsoidal parameters [1]_ [2]_ +- Gravitational and ellipsoidal parameters :cite:p:`HofmannWellenhof:2006hy` :cite:p:`Petit:2010tp` `Source code`__ @@ -18,12 +18,3 @@ General Attributes and Methods .. autoclass:: pyTMD.datum :members: - -References ----------- -.. [1] B. Hofmann-Wellenhof and H. Moritz, *Physical Geodesy*, 2nd Edition, - 403 pp., (2006). `doi: 10.1007/978-3-211-33545-1 - `_ -.. [2] G. Petit and B. Luzum (eds.), *IERS Conventions (2010)*, - International Earth Rotation and Reference Systems Service (IERS), - `IERS Technical Note No. 36 `_ diff --git a/doc/source/api_reference/predict.rst b/doc/source/api_reference/predict.rst index 43d1e67a..3c206638 100644 --- a/doc/source/api_reference/predict.rst +++ b/doc/source/api_reference/predict.rst @@ -10,7 +10,7 @@ predict - Predicts tidal values from minor constituents inferred using major constituents - Predicts long-period equilibrium ocean tides -- Predicts solid earth tidal values following IERS Conventions +- Predicts solid earth tides Calling Sequence ---------------- diff --git a/doc/source/conf.py b/doc/source/conf.py index be4c24b3..9f7d5fbc 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -40,6 +40,7 @@ extensions = [ "myst_nb", "numpydoc", + 'sphinxcontrib.bibtex', "sphinx.ext.autodoc", "sphinx.ext.graphviz", "sphinx.ext.viewcode", @@ -70,6 +71,8 @@ autodoc_member_order = 'bysource' numpydoc_show_class_members = False pygments_style = 'native' +bibtex_bibfiles = ['_assets/pytmd-refs.bib'] +bibtex_default_style = 'plain' # -- Options for HTML output ------------------------------------------------- diff --git a/doc/source/getting_started/Background.rst b/doc/source/getting_started/Background.rst index ff8b014b..eee32d95 100644 --- a/doc/source/getting_started/Background.rst +++ b/doc/source/getting_started/Background.rst @@ -8,29 +8,29 @@ Ocean and Load Tides The rise and fall of the oceanic tides are a major source of the vertical variability of the ocean surface. Ocean tides are typically observed using float gauges, GPS stations, gravimeters, tiltmeters, pressure recorders, and satellite altimeters. For each of these measurements, it is important to note the `vertical datum of the measurement technique `_. -Ocean tides are driven by gravitational undulations due to the relative positions of the Earth, moon and sun, and the centripetal acceleration due to the Earth's rotation [Doodson1921]_ [Meeus1998]_. +Ocean tides are driven by gravitational undulations due to the relative positions of the Earth, moon and sun, and the centripetal acceleration due to the Earth's rotation :cite:p:`Doodson:1921kt` :cite:p:`Meeus:1991vh`. A secondary tidal effect, known as load tides, is due to the elastic response of the Earth's crust to ocean tidal loading, which produces deformation of both the sea floor and adjacent land areas. Tidal oscillations for both ocean and load tides can be decomposed into a series of tidal constituents (or partial tides) of particular frequencies. Ocean tide models are typically one of following categories: 1) an empirically adjusted model, 2) a barotropic hydrodynamic model constrained by data assimilation, -or 3) an unconstrained hydrodynamic model [Stammer2014]_. -``pyTMD`` is not an ocean or load tide model, but rather a tool for using constituents from ocean and load tide models to calculate the tide deflections or currents at particular locations and times [Egbert2002]_. +or 3) an unconstrained hydrodynamic model :cite:p:`Stammer:2014ci`. +``pyTMD`` is not an ocean or load tide model, but rather a tool for using constituents from ocean and load tide models to calculate the tide deflections or currents at particular locations and times :cite:p:`Egbert:2002ge`. Solid Earth Tides ################# -Similar to ocean tides, solid Earth tides are tidal deformations due to gravitational undulations based on the relative positions of the Earth, moon and sun [Agnew2015]_ [Doodson1921]_ [Meeus1998]_ [Montenbruck1989]_. +Similar to ocean tides, solid Earth tides are tidal deformations due to gravitational undulations based on the relative positions of the Earth, moon and sun :cite:p:`Agnew:2015kw` :cite:p:`Doodson:1921kt` :cite:p:`Meeus:1991vh` :cite:p:`Montenbruck:1989uk`. However, while ocean tides are apparent to observers on the coast, solid Earth tides are typically more difficult to observe due to the reference frame of the observer moving. -The total gravitational potential at a position on the Earth's surface due to a celestial object is directly related to the distance between the Earth and the object, and the mass of that object [Agnew2015]_ [Wahr1981]_. +The total gravitational potential at a position on the Earth's surface due to a celestial object is directly related to the distance between the Earth and the object, and the mass of that object :cite:p:`Agnew:2015kw` :cite:p:`Wahr:1981ea`. Analytical approximate positions for the sun and moon can be calculated within ``pyTMD``, and high-resolution numerical ephemerides for the sun and moon can be downloaded from the `Jet Propulsion Laboratory `_. -Within ``pyTMD``, the tidal deformation of the Earth is modeled using the Load Love/Shida numbers formalism described in the `IERS Conventions `_, which are based on [Mathews1997]_. +Within ``pyTMD``, the tidal deformation of the Earth is modeled using the Load Love/Shida numbers formalism described in the `IERS Conventions `_, which are based on :cite:p:`Mathews:1997js`. Love and Shida numbers describe the elastic response of the Earth in terms of vertical displacement (*h*), gravitational potential (*k*) and horizontal displacement (*l*). -For a spherical, non-rotating Earth, the Love and Shida numbers are largely independent of tidal frequency [Wahr1981]_. -However, for a rotating, ellipsoidal Earth, the Love and Shida numbers are dependent on tidal frequency, with resonances in the diurnal and semi-diurnal bands [Wahr1981]_. -``pyTMD`` computes these frequency-dependent corrections along with the dissipative mantle anelasticity corrections following [Mathews1997]_. +For a spherical, non-rotating Earth, the Love and Shida numbers are largely independent of tidal frequency :cite:p:`Wahr:1981ea`. +However, for a rotating, ellipsoidal Earth, the Love and Shida numbers are dependent on tidal frequency, with resonances in the diurnal and semi-diurnal bands :cite:p:`Wahr:1981ea`. +``pyTMD`` computes these frequency-dependent corrections along with the dissipative mantle anelasticity corrections following :cite:p:`Mathews:1997js`. In addition to the ups and downs of tides, there is a considerable portion of tidal potential and displacement that does not vary in time, a *permanent tide* that is due to the Earth being in the presence of the Sun and Moon (and other planetary bodies). The `Earth is lower in polar areas and higher in equatorial areas `_ than it would without those gravitational effects. @@ -47,9 +47,9 @@ The radial difference in terms of latitude between the mean-tide and tide-free s Pole Tides ########## -Load and ocean pole tides are driven by variations in the Earth's figure axis (e.g. Chandler wobble and annual variations) [Wahr1985]_ [Desai2002]_ [Agnew2015]_. +Load and ocean pole tides are driven by variations in the Earth's figure axis (e.g. Chandler wobble and annual variations) :cite:p:`Wahr:1985gr` :cite:p:`Desai:2002ev` :cite:p:`Agnew:2015kw`. These pole tides are due to Earth's ellipsoidal shape shifting as the rotation axis of the Earth -moves with respect to the mean pole location, and for the case of ocean pole tides the centripetal effects of polar motion on the ocean [Desai2002]_ [Desai2015]_. +moves with respect to the mean pole location, and for the case of ocean pole tides the centripetal effects of polar motion on the ocean :cite:p:`Desai:2002ev` :cite:p:`Desai:2015jr`. The formalism for estimating the pole tides is also based upon `IERS Conventions `_. ``pyTMD`` uses the ``timescale`` library for reading the Earth Orientation Parameters (EOPs) necessary for computing load pole and ocean pole tide variations. The currently accepted formalism for estimating the reference position of the Earth's figure axis at a given date is the `IERS 2018 secular pole model `_: @@ -73,7 +73,7 @@ The time-dependent offsets from the reference rotation pole position, are then c Terrestrial Reference Systems ############################# -Locations of planetary bodies and satellites can be determined in an Earth-centered Earth-Fixed (ECEF) coordinate system [Montenbruck1989]_. +Locations of planetary bodies and satellites can be determined in an Earth-centered Earth-Fixed (ECEF) coordinate system :cite:p:`Montenbruck:1989uk`. ECEF is a Cartesian coordinate system representing *X*, *Y*, and *Z* measurements from the Earth's center of mass. The *Z* axis is aligned with the Earth's rotation axis, the *X* axis is aligned with the intersection of the prime meridian and the equator, and the *Y* axis is aligned with 90 degrees east longitude and the equator. @@ -104,30 +104,3 @@ Time in Julian centuries (36525 days) are calculated relative to noon on January :label: 5 T = \frac{JD - 2451545.0}{36525} - -References -########## - -.. [Agnew2015] D. C. Agnew, "Earth Tides", *Treatise on Geophysics (Second Edition)*, 3.06, 151--178, (2015). `doi: 10.1016/B978-0-444-53802-4.00058-0 `_ - -.. [Desai2002] S. Desai, "Observing the pole tide with satellite altimetry", *Journal of Geophysical Research: Oceans*, 107(C11), (2002). `doi: 10.1029/2001JC001224 `_ - -.. [Desai2015] S. Desai, J. Wahr and B. Beckley "Revisiting the pole tide for and from satellite altimetry", *Journal of Geodesy*, 89(12), p1233-1243, (2015). `doi: 10.1007/s00190-015-0848-7 `_ - -.. [Doodson1921] A. T. Doodson and H. Lamb, "The harmonic development of the tide-generating potential", *Proceedings of the Royal Society of London. Series A, Containing Papers of a Mathematical and Physical Character*, 100(704), 305--329, (1921). `doi: 10.1098/rspa.1921.0088 `_ - -.. [Egbert2002] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of Barotropic Ocean Tides", *Journal of Atmospheric and Oceanic Technology*, 19(2), 183--204, (2002). `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__ - -.. [Mathews1997] P. M. Mathews, V. Dehant and J. M. Gipson, "Tidal station displacements", *Journal of Geophysical Research: Solid Earth*, 102(B9), 20469--20477, (1997). `doi: 10.1029/97JB01515 `_ - -.. [Meeus1998] J. Meeus, *Astronomical Algorithms*, 2nd edition, 477 pp., (1998). - -.. [Montenbruck1989] O. Montenbruck, *Practical Ephemeris Calculations*, 146 pp., (1989). - -.. [Stammer2014] D. Stammer et al., "Accuracy assessment of global barotropic ocean tide models", *Reviews of Geophysics*, 52, 243--282, (2014). `doi: 10.1002/2014RG000450 `_ - -.. [Wahr1981] J. M. Wahr, "Body tides on an elliptical, rotating, elastic and oceanless Earth", *Geophysical Journal of the Royal Astronomical Society*, 64(3), 677--703, (1981). `doi: 10.1111/j.1365-246X.1981.tb02690.x `_ - -.. [Wahr1985] J. M. Wahr, "Deformation induced by polar motion", *Journal of Geophysical Research: Solid Earth*, 90(B11), 9363--9368, (1985). `doi: 10.1029/JB090iB11p09363 `_ - -.. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2 diff --git a/doc/source/getting_started/Bibliography.rst b/doc/source/getting_started/Bibliography.rst new file mode 100644 index 00000000..73b0782c --- /dev/null +++ b/doc/source/getting_started/Bibliography.rst @@ -0,0 +1,5 @@ +============ +Bibliography +============ + +.. bibliography:: diff --git a/doc/source/getting_started/Getting-Started.rst b/doc/source/getting_started/Getting-Started.rst index 693cf88c..5f74317c 100644 --- a/doc/source/getting_started/Getting-Started.rst +++ b/doc/source/getting_started/Getting-Started.rst @@ -40,14 +40,14 @@ Directories This structure was chosen based on the different formats of each tide model. Presently, the following models and their directories are parameterized within ``pyTMD``. -- Circum-Antarctic Tidal Simulations [Padman2008]_ +- Circum-Antarctic Tidal Simulations :cite:p:`Padman:2008ec` * CATS0201: ``/cats0201_tmd/`` * `CATS2008 `_: ``/CATS2008/`` * CATS2008_load: ``/CATS2008a_SPOTL_Load/`` * `CATS2008-v2023 `_: ``/CATS2008_v2023/`` -- Arctic Ocean and Greenland Coast Tidal Simulations [Padman2004]_ +- Arctic Ocean and Greenland Coast Tidal Simulations :cite:p:`Padman:2004hv` * `AODTM-5 `_: ``/aodtm5_tmd/`` * `AOTIM-5 `_: ``/aotim5_tmd/`` @@ -55,7 +55,7 @@ Presently, the following models and their directories are parameterized within ` * `Arc2kmTM `_: ``/Arc2kmTM/`` * Gr1km-v2: ``/greenlandTMD_v2/`` -- TOPEX/POSEIDON global tide models [Egbert2002]_ +- TOPEX/POSEIDON global tide models :cite:p:`Egbert:2002ge` * TPXO7.2: ``/TPXO7.2_tmd/`` * TPXO7.2_load: ``/TPXO7.2_load/`` @@ -68,7 +68,7 @@ Presently, the following models and their directories are parameterized within ` * `TPXO9-atlas-v5 `_: ``/TPXO9_atlas_v5/`` * `TPXO10-atlas-v2 `_: ``/TPXO10_atlas_v2/`` -- Global Ocean Tide models [Ray1999]_ +- Global Ocean Tide models :cite:p:`Ray:1999vm` * GOT4.7: ``/GOT4.7/grids_oceantide/`` * GOT4.7_load: ``/GOT4.7/grids_loadtide/`` @@ -81,19 +81,19 @@ Presently, the following models and their directories are parameterized within ` * `GOT5.6 `_: ``/GOT5.6/ocean_tides/`` * `RE14 `_: ``/RE14_LongPeriodTides_rel/oceantides/`` -- Finite Element Solution tide models [Lyard2020]_ +- Finite Element Solution tide models :cite:p:`Lyard:2021fk` * `FES2014 `_: ``/fes2014/ocean_tide/`` * `FES2014_load `_: ``/fes2014/load_tide/`` * `FES2022 `_: ``/fes2022b/ocean_tide/`` * `FES2022_load `_: ``/fes2022b/load_tide/`` -- Empirical Ocean Tide models [HartDavis2020]_ +- Empirical Ocean Tide models :cite:p:`HartDavis:2021dx` * `EOT20 `_: ``/EOT20/ocean_tides/`` * `EOT20_load `_: ``/EOT20/load_tides/`` -- Hamburg direct data Assimilation Methods for Tides models [Taguchi2014]_ +- Hamburg direct data Assimilation Methods for Tides models :cite:p:`Taguchi:2014ht` * `HAMTIDE11 `_: ``/hamtide/`` @@ -205,7 +205,7 @@ For pole tide programs, the epoch is 1858-11-17T00:00:00 (Modified Julian Days). - LORAN time: Atomic timing system for the Loran-C chain transmitter sites used in terrestrial radionavigation. LORAN time and UTC time were equal on January 1, 1958. TAI time is ahead of LORAN time by 10 seconds. ``timescale`` also keeps updated `tables of delta times `_ for converting between dynamic (TT) and universal (UT1) times. -Delta times (TT - UT1) are the differences between Dynamic Time (TT) and Universal Time (UT1) [Meeus1998]_. +Delta times (TT - UT1) are the differences between Dynamic Time (TT) and Universal Time (UT1) :cite:p:`Meeus:1991vh`. Universal Time (UT1) is based on the rotation of the Earth, which varies irregularly, and so UT1 is adjusted periodically. Dynamic Time (TT) is a uniform, monotonically increasing time standard based on atomic clocks that is @@ -235,29 +235,4 @@ For coastal or near-grounded points, the model can be extrapolated using a `nearest-neighbor `_ routine. The default maximum extrapolation distance is 10 kilometers. This default distance may not be a large enough extrapolation for some applications and models. -The extrapolation cutoff can be set to any distance in kilometers, but should be used with caution in cases such as narrow fjords or ice sheet grounding zones [Padman2018]_. - -References -########## - -.. [Egbert2002] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of Barotropic Ocean Tides", *Journal of Atmospheric and Oceanic Technology*, 19(2), 183--204, (2002). `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__ - -.. [HartDavis2020] M. G. Hart-Davis, G. Piccioni, D. Dettmering, C. Schwatke, M. Passaro, and F. Seitz, "EOT20: a global ocean tide model from multi-mission satellite altimetry", *Earth System Science Data*, 13(8), 3869--3884, (2020). `doi: 10.5194/essd-13-3869-2021 `_ - -.. [Lyard2020] F. H. Lyard, D. J. Allain, M. Cancet, L. Carr\ |egrave|\ re, and N. Picot, "FES2014 global ocean tides atlas: design and performances", *Ocean Science Discussions*, in review, (2020). `doi: 10.5194/os-2020-96 `_ - -.. [Meeus1998] J. Meeus, *Astronomical Algorithms*, 2nd edition, 477 pp., (1998). - -.. [Padman2004] L. Padman and S. Y. Erofeeva, "A barotropic inverse tidal model for the Arctic Ocean", *Geophysical Research Letters*, 31(2), L02303. (2004). `doi: 10.1029/2003GL019003 `_ - -.. [Padman2008] L. Padman, S. Y. Erofeeva, and H. A. Fricker, "Improving Antarctic tide models by assimilation of ICESat laser altimetry over ice shelves", *Geophysical Research Letters*, 35, L22504, (2008). `doi: 10.1029/2008GL035592 `_ - -.. [Padman2018] L. Padman, M. R. Siegfried, and H. A. Fricker, "Ocean Tide Influences on the Antarctic and Greenland Ice Sheets", *Reviews of Geophysics*, 56, (2018). `doi: 10.1002/2016RG000546 `_ - -.. [Ray1999] R. D. Ray, "A Global Ocean Tide Model From TOPEX/POSEIDON Altimetry: GOT99.2", *NASA Technical Memorandum*, `NASA/TM--1999-209478 `_. - -.. [Taguchi2014] E. Taguchi, D. Stammer, and W. Zahel, "Inferring deep ocean tidal energy dissipation from the global high-resolution data-assimilative HAMTIDE model", *Journal of Geophysical Research: Oceans*, 119, 4573--4592, (2014). `doi: 10.1002/2013JC009766 `_ - -.. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2 - -.. |egrave| unicode:: U+00E8 .. LATIN SMALL LETTER E WITH GRAVE +The extrapolation cutoff can be set to any distance in kilometers, but should be used with caution in cases such as narrow fjords or ice sheet grounding zones :cite:p:`Padman:2018cv`. diff --git a/doc/source/index.rst b/doc/source/index.rst index 8b88f0f8..43f36a19 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -32,7 +32,6 @@ ocean, load, solid Earth and pole tides api_reference/arguments.rst api_reference/astro.rst - api_reference/check_points.rst api_reference/compute.rst api_reference/crs.rst api_reference/ellipse.rst @@ -68,6 +67,13 @@ ocean, load, solid Earth and pole tides api_reference/compute_tidal_currents.rst api_reference/compute_tidal_elevations.rst +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Bibliography + + getting_started/Bibliography.rst + .. toctree:: :maxdepth: 1 :hidden: diff --git a/pyTMD/__init__.py b/pyTMD/__init__.py index 00148696..def0775b 100644 --- a/pyTMD/__init__.py +++ b/pyTMD/__init__.py @@ -24,7 +24,6 @@ import pyTMD.version from pyTMD import io from pyTMD import solve -from pyTMD.check_points import check_points from pyTMD.crs import ( crs, datum, @@ -32,6 +31,7 @@ ) # Deprecated functions +from pyTMD.check_points import check_points from pyTMD.compute_tide_corrections import ( compute_corrections, compute_tide_corrections, diff --git a/pyTMD/arguments.py b/pyTMD/arguments.py index 68dc510d..c54ad890 100755 --- a/pyTMD/arguments.py +++ b/pyTMD/arguments.py @@ -112,7 +112,7 @@ def arguments( ): """ Calculates the nodal corrections for tidal constituents - [1]_ [2]_ [3]_ [4]_ + :cite:p:`Doodson:1941td` :cite:p:`Schureman:1958ty` :cite:p:`Foreman:1989dt` :cite:p:`Egbert:2002ge` Parameters ---------- @@ -139,23 +139,6 @@ def arguments( nodal factor correction G: np.ndarray phase correction in degrees - - References - ---------- - .. [1] A. T. Doodson and H. D. Warburg, "Admiralty Manual of Tides", - HMSO, London, (1941). - .. [2] P. Schureman, "Manual of Harmonic Analysis and Prediction of Tides," - *US Coast and Geodetic Survey*, Special Publication, 98, (1958). - .. [3] M. G. G. Foreman and R. F. Henry, "The harmonic analysis of tidal - model time series," *Advances in Water Resources*, 12(3), 109--120, - (1989). `doi: 10.1016/0309-1708(89)90017-1 - `_ - .. [4] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of - Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic - Technology*, 19(2), 183--204, (2002). - `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__ - - .. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2 """ # set default keyword arguments kwargs.setdefault('deltat', 0.0) @@ -195,7 +178,9 @@ def minor_arguments( ): """ Calculates the nodal corrections for minor tidal constituents - in order to infer their values [1]_ [2]_ [3]_ [4]_ + in order to infer their values :cite:p:`Doodson:1941td` :cite:p:`Schureman:1958ty` + :cite:p:`Foreman:1989dt` :cite:p:`Egbert:2002ge` + Parameters ---------- @@ -214,23 +199,6 @@ def minor_arguments( nodal factor correction G: np.ndarray phase correction in degrees - - References - ---------- - .. [1] A. T. Doodson and H. D. Warburg, "Admiralty Manual of Tides", - HMSO, London, (1941). - .. [2] P. Schureman, "Manual of Harmonic Analysis and Prediction of Tides," - *US Coast and Geodetic Survey*, Special Publication, 98, (1958). - .. [3] M. G. G. Foreman and R. F. Henry, "The harmonic analysis of tidal - model time series," *Advances in Water Resources*, 12(3), 109--120, - (1989). `doi: 10.1016/0309-1708(89)90017-1 - `_ - .. [4] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of - Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic - Technology*, 19(2), 183--204, (2002). - `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__ - - .. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2 """ # set default keyword arguments kwargs.setdefault('deltat', 0.0) @@ -364,7 +332,8 @@ def coefficients_table( **kwargs ): """ - Doodson table coefficients for tidal constituents [1]_ [2]_ + Doodson table coefficients for tidal constituents + :cite:p:`Doodson:1921kt` :cite:p:`Doodson:1941td` Parameters ---------- @@ -379,16 +348,6 @@ def coefficients_table( ------- coef: np.ndarray Doodson coefficients (Cartwright numbers) for each constituent - - References - ---------- - .. [1] A. T. Doodson and H. Lamb, "The harmonic development of - the tide-generating potential", *Proceedings of the Royal Society - of London. Series A, Containing Papers of a Mathematical and - Physical Character*, 100(704), 305--329, (1921). - `doi: 10.1098/rspa.1921.0088 `_ - .. [2] A. T. Doodson and H. D. Warburg, "Admiralty Manual of Tides", - HMSO, London, (1941). """ # set default keyword arguments kwargs.setdefault('corrections', 'OTIS') @@ -437,7 +396,7 @@ def doodson_number( ): """ Calculates the Doodson or Cartwright number for - tidal constituents [1]_ + tidal constituents :cite:p:`Doodson:1921kt` Parameters ---------- @@ -458,14 +417,6 @@ def doodson_number( ------- numbers: float, np.ndarray or dict Doodson or Cartwright number for each constituent - - References - ---------- - .. [1] A. T. Doodson and H. Lamb, "The harmonic development of - the tide-generating potential", *Proceedings of the Royal Society - of London. Series A, Containing Papers of a Mathematical and - Physical Character*, 100(704), 305--329, (1921). - `doi: 10.1098/rspa.1921.0088 `_ """ # set default keyword arguments kwargs.setdefault('corrections', 'OTIS') @@ -530,7 +481,7 @@ def nodal( ): """ Calculates the nodal corrections for tidal constituents - [1]_ [2]_ [3]_ [4]_ + :cite:p:`Doodson:1941td` :cite:p:`Schureman:1958ty` :cite:p:`Foreman:1989dt` :cite:p:`Ray:1999vm` Calculates factors for compound tides using recursion @@ -557,20 +508,6 @@ def nodal( nodal factor correction u: np.ndarray nodal angle correction - - References - ---------- - .. [1] A. T. Doodson and H. D. Warburg, "Admiralty Manual of Tides", - HMSO, London, (1941). - .. [2] P. Schureman, "Manual of Harmonic Analysis and Prediction of Tides," - *US Coast and Geodetic Survey*, Special Publication, 98, (1958). - .. [3] M. G. G. Foreman and R. F. Henry, "The harmonic analysis of tidal - model time series," *Advances in Water Resources*, 12(3), 109--120, - (1989). `doi: 10.1016/0309-1708(89)90017-1 - `_ - .. [4] R. D. Ray, "A global ocean tide model from - Topex/Poseidon altimetry: GOT99.2", - NASA Goddard Space Flight Center, TM-1999-209478, (1999). """ # set default keyword arguments kwargs.setdefault('corrections', 'OTIS') @@ -1234,7 +1171,7 @@ def frequency( **kwargs ): """ - Calculates the angular frequency for tidal constituents [1]_ + Calculates the angular frequency for tidal constituents :cite:p:`Ray:1999vm` Parameters ---------- @@ -1253,12 +1190,6 @@ def frequency( ------- omega: np.ndarray angular frequency in radians per second - - References - ---------- - .. [1] R. D. Ray, "A global ocean tide model from - Topex/Poseidon altimetry: GOT99.2", - NASA Goddard Space Flight Center, TM-1999-209478, (1999). """ # set default keyword arguments kwargs.setdefault('corrections', 'OTIS') @@ -1331,7 +1262,7 @@ def aliasing_period( def _arguments_table(**kwargs): """ - Arguments table for tidal constituents [1]_ [2]_ + Arguments table for tidal constituents :cite:p:`Doodson:1921kt` :cite:p:`Doodson:1941td` Parameters ---------- @@ -1342,16 +1273,6 @@ def _arguments_table(**kwargs): ------- coef: np.ndarray Doodson coefficients (Cartwright numbers) for each constituent - - References - ---------- - .. [1] A. T. Doodson and H. Lamb, "The harmonic development of - the tide-generating potential", *Proceedings of the Royal Society - of London. Series A, Containing Papers of a Mathematical and - Physical Character*, 100(704), 305--329, (1921). - `doi: 10.1098/rspa.1921.0088 `_ - .. [2] A. T. Doodson and H. D. Warburg, "Admiralty Manual of Tides", - HMSO, London, (1941). """ # set default keyword arguments kwargs.setdefault('corrections', 'OTIS') @@ -1378,22 +1299,12 @@ def _arguments_table(**kwargs): def _minor_table(**kwargs): """ - Arguments table for minor tidal constituents [1]_ [2]_ + Arguments table for minor tidal constituents :cite:p:`Doodson:1921kt` :cite:p:`Doodson:1941td` Returns ------- coef: np.ndarray Doodson coefficients (Cartwright numbers) for each constituent - - References - ---------- - .. [1] A. T. Doodson and H. Lamb, "The harmonic development of - the tide-generating potential", *Proceedings of the Royal Society - of London. Series A, Containing Papers of a Mathematical and - Physical Character*, 100(704), 305--329, (1921). - `doi: 10.1098/rspa.1921.0088 `_ - .. [2] A. T. Doodson and H. D. Warburg, "Admiralty Manual of Tides", - HMSO, London, (1941). """ # modified Doodson coefficients for constituents # using 7 index variables: tau, s, h, p, n, pp, k @@ -1413,7 +1324,7 @@ def _minor_table(**kwargs): def _constituent_parameters(c: str, **kwargs): """ - Loads parameters for a given tidal constituent + Loads parameters for a given tidal constituent :cite:p:`Egbert:2002ge` Parameters ---------- @@ -1434,15 +1345,6 @@ def _constituent_parameters(c: str, **kwargs): load love number of tidal constituent species: float spherical harmonic dependence of quadrupole potential - - References - ---------- - .. [1] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of - Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic - Technology*, 19(2), 183--204, (2002). - `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__ - - .. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2 """ # default keyword arguments kwargs.setdefault('raise_error', False) @@ -1512,7 +1414,7 @@ def _love_numbers( ): """ Compute the body tide Love/Shida numbers for a given - frequency [1]_ [2]_ [3]_ + frequency :cite:p:`Wahr:1981ea` :cite:p:`Wahr:1981if` :cite:p:`Mathews:1995go` Parameters ---------- @@ -1534,25 +1436,6 @@ def _love_numbers( Degree-2 Love number of gravitational potential l2: float Degree-2 Love (Shida) number of horizontal displacement - - References - ---------- - .. [1] J. M. Wahr, "Body tides on an elliptical, rotating, elastic - and oceanless Earth", *Geophysical Journal of the Royal - Astronomical Society*, 64(3), 677--703, (1981). - `doi: 10.1111/j.1365-246X.1981.tb02690.x - `_ - .. [2] J. M. Wahr and T. Sasao, "A diurnal resonance in the ocean - tide and in the Earth's load response due to the resonant free - `core nutation`", *Geophysical Journal of the Royal Astronomical - Society*, 64(3), 747--765, (1981). - `doi: 10.1111/j.1365-246X.1981.tb02693.x - `_ - .. [3] P. M. Mathews, B. A. Buffett, and I. I. Shapiro, - "Love numbers for diurnal tides: Relation to wobble admittances - and resonance expansions", *Journal of Geophysical Research: - Solid Earth*, 100(B6), 9935--9948, (1995). - `doi: 10.1029/95jb00670 `_ """ # free core nutation frequencies (cycles per sidereal day) and # Love number parameters from Wahr (1981) table 6 @@ -1611,7 +1494,8 @@ def _love_numbers( _ce1973_table_1 = get_data_path(['data','ce1973_tab1.txt']) def _parse_tide_potential_table(table: str | pathlib.Path): - """Parse tables of tide-generating potential from [1]_ and [2]_ + """Parse tables of tide-generating potential from + :cite:p:`Cartwright:1971iz` and :cite:p:`Cartwright:1973em` Parameters ---------- @@ -1622,19 +1506,6 @@ def _parse_tide_potential_table(table: str | pathlib.Path): ------- CTE: float Cartwright-Tayler-Edden table values - - References - ---------- - .. [1] D. E. Cartwright and R. J. Tayler, - "New Computations of the Tide-generating Potential," - *Geophysical Journal of the Royal Astronomical Society*, - 23(1), 45--73. (1971). `doi: 10.1111/j.1365-246X.1971.tb01803.x - `_ - .. [2] D. E. Cartwright and A. C. Edden, - "Corrected Tables of Tidal Harmonics," - *Geophysical Journal of the Royal Astronomical Society*, - 33(3), 253--264, (1973). `doi: 10.1111/j.1365-246X.1973.tb03420.x - `_ """ # verify table path table = pathlib.Path(table).expanduser().absolute() diff --git a/pyTMD/astro.py b/pyTMD/astro.py index c5e75caf..41369f88 100644 --- a/pyTMD/astro.py +++ b/pyTMD/astro.py @@ -112,7 +112,7 @@ def mean_longitudes( ): r""" Computes the basic astronomical mean longitudes: - `S`, `H`, `P`, `N` and `PP` [1]_ [2]_ + `S`, `H`, `P`, `N` and `PP` :cite:p:`Meeus:1991vh` :cite:p:`Simon:1994vo` Note `N` is not `N'`, i.e. `N` is decreasing with time. @@ -137,18 +137,6 @@ def mean_longitudes( mean longitude of ascending lunar node (degrees) PP: np.ndarray longitude of solar perigee (degrees) - - References - ---------- - .. [1] J. Meeus, *Astronomical Algorithms*, 2nd edition, 477 pp., (1998). - .. [2] J. L. Simon, P. Bretagnon, J. Chapront, M. Chapront-Touz\ |eacute|\, - G. Francou, and J. Laskar "Numerical expressions for precession - formulae and mean elements for the Moon and the planets", - *Astronomy and Astrophysics*, 282(2), 663--683, (1994). - `bibcode: 1994A%26A...282..663S - `_ - - .. |eacute| unicode:: U+00E9 .. LATIN SMALL LETTER E WITH ACUTE """ if MEEUS: # convert from MJD to days relative to 2000-01-01T12:00:00 @@ -234,7 +222,7 @@ def doodson_arguments( """ Computes astronomical phase angles for the six Doodson Arguments: `tau`, `S`, `H`, `P`, and `N'`, and `Ps` - [1]_ [2]_ + :cite:p:`Doodson:1921kt` :cite:p:`Meeus:1991vh` Parameters ---------- @@ -259,15 +247,6 @@ def doodson_arguments( negative mean longitude of the ascending node (radians) Ps: np.ndarray mean longitude of solar perigee (radians) - - References - ---------- - .. [1] A. T. Doodson and H. Lamb, "The harmonic development of - the tide-generating potential", *Proceedings of the Royal Society - of London. Series A, Containing Papers of a Mathematical and - Physical Character*, 100(704), 305--329, (1921). - `doi: 10.1098/rspa.1921.0088 `_ - .. [2] J. Meeus, *Astronomical Algorithms*, 2nd edition, 477 pp., (1998). """ # degrees to radians dtr = np.pi/180.0 @@ -321,7 +300,8 @@ def doodson_arguments( def delaunay_arguments(MJD: np.ndarray): """ Computes astronomical phase angles for the five primary Delaunay - Arguments of Nutation: `l`, `l'`, `F`, `D`, and `N` [1]_ [2]_ [3]_ + Arguments of Nutation: `l`, `l'`, `F`, `D`, and `N` + :cite:p:`Meeus:1991vh` :cite:p:`Petit:2010tp` :cite:p:`Capitaine:2003fx` Parameters ---------- @@ -340,19 +320,6 @@ def delaunay_arguments(MJD: np.ndarray): mean elongation of the moon from the sun (radians) N: np.ndarray mean longitude of ascending lunar node (radians) - - References - ---------- - .. [1] J. Meeus, *Astronomical Algorithms*, 2nd edition, 477 pp., (1998). - .. [2] G. Petit and B. Luzum (eds.), *IERS Conventions (2010)*, - International Earth Rotation and Reference Systems Service (IERS), - `IERS Technical Note No. 36 - `_ - .. [3] N. Capitaine, P. T. Wallace, and J. Chapront, - "Expressions for IAU 2000 precession quantities", - *Astronomy & Astrophysics*, 412, 567--586, (2003). - `doi: 10.1051/0004-6361:20031539 - `_ """ # arcseconds to radians atr = np.pi/648000.0 @@ -386,26 +353,12 @@ def delaunay_arguments(MJD: np.ndarray): return (l, lp, F, D, N) def mean_obliquity(MJD: np.ndarray): - """Mean obliquity of the ecliptic + """Mean obliquity of the ecliptic :cite:p:`Capitaine:2003fx` :cite:p:`Capitaine:2003fw` Parameters ---------- MJD: np.ndarray Modified Julian Day (MJD) of input date - - References - ---------- - .. [1] N. Capitaine, P. T. Wallace, and J. Chapront, - "Expressions for IAU 2000 precession quantities", - *Astronomy & Astrophysics*, 412, 567--586, (2003). - `doi: 10.1051/0004-6361:20031539 - `_ - .. [1] N. Capitaine, J. Chapront, S. Lambert, and P. T. Wallace, - "Expressions for the Celestial Intermediate Pole and - Celestial Ephemeris Origin consistent with the IAU 2000A - precession-nutation model", *Astronomy & Astrophysics*, - 400, 1145--1154, (2003). `doi: 10.1051/0004-6361:20030077 - `_ """ # arcseconds to radians atr = np.pi/648000.0 @@ -421,7 +374,7 @@ def solar_ecef(MJD: np.ndarray, **kwargs): """ Wrapper function for calculating the positional coordinates of the sun in an Earth-centric, Earth-Fixed (ECEF) frame - [1]_ [2]_ [3]_ + :cite:p:`Meeus:1991vh` :cite:p:`Montenbruck:1989uk` :cite:p:`Park:2021fa` Parameters ---------- @@ -439,17 +392,6 @@ def solar_ecef(MJD: np.ndarray, **kwargs): ------- X, Y, Z: np.ndarray ECEF coordinates of the sun (meters) - - References - ---------- - .. [1] J. Meeus, *Astronomical Algorithms*, 2nd edition, 477 pp., (1998). - .. [2] O. Montenbruck, *Practical Ephemeris Calculations*, - 146 pp., (1989). - .. [3] R. S. Park, W. M. Folkner, and J. G. Williams, and D. H. Boggs, - "The JPL Planetary and Lunar Ephemerides DE440 and DE441", - *The Astronomical Journal*, 161(3), 105, (2021). - `doi: 10.3847/1538-3881/abd414 - `_ """ kwargs.setdefault('ephemerides', 'approximate') if (kwargs['ephemerides'].lower() == 'approximate'): @@ -460,7 +402,7 @@ def solar_ecef(MJD: np.ndarray, **kwargs): def solar_approximate(MJD, **kwargs): """ Computes approximate positional coordinates of the sun in an - Earth-centric, Earth-Fixed (ECEF) frame [1]_ [2]_ + Earth-centric, Earth-Fixed (ECEF) frame :cite:p:`Meeus:1991vh` :cite:p:`Montenbruck:1989uk` Parameters ---------- @@ -471,12 +413,6 @@ def solar_approximate(MJD, **kwargs): ------- X, Y, Z: np.ndarray ECEF coordinates of the sun (meters) - - References - ---------- - .. [1] J. Meeus, *Astronomical Algorithms*, 2nd edition, 477 pp., (1998). - .. [2] O. Montenbruck, *Practical Ephemeris Calculations*, - 146 pp., (1989). """ # create timescale from Modified Julian Day (MJD) ts = timescale.time.Timescale(MJD=MJD) @@ -510,7 +446,7 @@ def solar_approximate(MJD, **kwargs): def solar_ephemerides(MJD: np.ndarray, **kwargs): """ Computes positional coordinates of the sun in an Earth-centric, - Earth-Fixed (ECEF) frame using JPL ephemerides [1]_ [2]_ + Earth-Fixed (ECEF) frame using JPL ephemerides :cite:p:`Meeus:1991vh` :cite:p:`Park:2021fa` Parameters ---------- @@ -523,15 +459,6 @@ def solar_ephemerides(MJD: np.ndarray, **kwargs): ------- X, Y, Z: np.ndarray ECEF coordinates of the sun (meters) - - References - ---------- - .. [1] J. Meeus, *Astronomical Algorithms*, 2nd edition, 477 pp., (1998). - .. [2] R. S. Park, W. M. Folkner, and J. G. Williams, and D. H. Boggs, - "The JPL Planetary and Lunar Ephemerides DE440 and DE441", - *The Astronomical Journal*, 161(3), 105, (2021). - `doi: 10.3847/1538-3881/abd414 - `_ """ # set default keyword arguments kwargs.setdefault('kernel', _default_kernel) @@ -567,7 +494,7 @@ def lunar_ecef(MJD: np.ndarray, **kwargs): """ Wrapper function for calculating the positional coordinates of the moon in an Earth-centric, Earth-Fixed (ECEF) frame - [1]_ [2]_ [3]_ + :cite:p:`Meeus:1991vh` :cite:p:`Montenbruck:1989uk` :cite:p:`Park:2021fa` Parameters ---------- @@ -585,17 +512,6 @@ def lunar_ecef(MJD: np.ndarray, **kwargs): ------- X, Y, Z: np.ndarray ECEF coordinates of the moon (meters) - - References - ---------- - .. [1] J. Meeus, *Astronomical Algorithms*, 2nd edition, 477 pp., (1998). - .. [2] O. Montenbruck, *Practical Ephemeris Calculations*, - 146 pp., (1989). - .. [3] R. S. Park, W. M. Folkner, and J. G. Williams, and D. H. Boggs, - "The JPL Planetary and Lunar Ephemerides DE440 and DE441", - *The Astronomical Journal*, 161(3), 105, (2021). - `doi: 10.3847/1538-3881/abd414 - `_ """ kwargs.setdefault('ephemerides', 'approximate') if (kwargs['ephemerides'].lower() == 'approximate'): @@ -606,7 +522,7 @@ def lunar_ecef(MJD: np.ndarray, **kwargs): def lunar_approximate(MJD, **kwargs): """ Computes approximate positional coordinates of the moon in an - Earth-centric, Earth-Fixed (ECEF) frame [1]_ [2]_ + Earth-centric, Earth-Fixed (ECEF) frame :cite:p:`Meeus:1991vh` :cite:p:`Montenbruck:1989uk` Parameters ---------- @@ -617,12 +533,6 @@ def lunar_approximate(MJD, **kwargs): ------- X, Y, Z: np.ndarray ECEF coordinates of the moon (meters) - - References - ---------- - .. [1] J. Meeus, *Astronomical Algorithms*, 2nd edition, 477 pp., (1998). - .. [2] O. Montenbruck, *Practical Ephemeris Calculations*, - 146 pp., (1989). """ # create timescale from Modified Julian Day (MJD) ts = timescale.time.Timescale(MJD=MJD) @@ -690,7 +600,7 @@ def lunar_approximate(MJD, **kwargs): def lunar_ephemerides(MJD: np.ndarray, **kwargs): """ Computes positional coordinates of the moon in an Earth-centric, - Earth-Fixed (ECEF) frame using JPL ephemerides [1]_ [2]_ + Earth-Fixed (ECEF) frame using JPL ephemerides :cite:p:`Meeus:1991vh` :cite:p:`Park:2021fa` Parameters ---------- @@ -703,15 +613,6 @@ def lunar_ephemerides(MJD: np.ndarray, **kwargs): ------- X, Y, Z: np.ndarray ECEF coordinates of the moon (meters) - - References - ---------- - .. [1] J. Meeus, *Astronomical Algorithms*, 2nd edition, 477 pp., (1998). - .. [2] R. S. Park, W. M. Folkner, and J. G. Williams, and D. H. Boggs, - "The JPL Planetary and Lunar Ephemerides DE440 and DE441", - *The Astronomical Journal*, 161(3), 105, (2021). - `doi: 10.3847/1538-3881/abd414 - `_ """ # set default keyword arguments kwargs.setdefault('kernel', _default_kernel) @@ -741,30 +642,13 @@ def lunar_ephemerides(MJD: np.ndarray, **kwargs): return (X, Y, Z) def gast(T: float | np.ndarray): - """Greenwich Apparent Sidereal Time (GAST) [1]_ [2]_ [3]_ + """Greenwich Apparent Sidereal Time (GAST) + :cite:p:`Capitaine:2003fx` :cite:p:`Capitaine:2003fw` :cite:p:`Petit:2010tp` Parameters ---------- T: np.ndarray Centuries since 2000-01-01T12:00:00 - - References - ---------- - .. [1] N. Capitaine, P. T. Wallace, and J. Chapront, - "Expressions for IAU 2000 precession quantities", - *Astronomy & Astrophysics*, 412, 567--586, (2003). - `doi: 10.1051/0004-6361:20031539 - `_ - .. [2] N. Capitaine, J. Chapront, S. Lambert, and P. T. Wallace, - "Expressions for the Celestial Intermediate Pole and - Celestial Ephemeris Origin consistent with the IAU 2000A - precession-nutation model", *Astronomy & Astrophysics*, - 400, 1145--1154, (2003). `doi: 10.1051/0004-6361:20030077 - `_ - .. [3] G. Petit and B. Luzum (eds.), *IERS Conventions (2010)*, - International Earth Rotation and Reference Systems Service (IERS), - `IERS Technical Note No. 36 - `_ """ # create timescale from centuries relative to 2000-01-01T12:00:00 ts = timescale.time.Timescale(MJD=T*_century + _mjd_j2000) @@ -781,7 +665,8 @@ def gast(T: float | np.ndarray): def itrs(T: float | np.ndarray): """ - International Terrestrial Reference System (ITRS) [1]_ [2]_ [3]_: + International Terrestrial Reference System (ITRS) + :cite:p:`Capitaine:2003fx` :cite:p:`Capitaine:2003fw` :cite:p:`Petit:2010tp`: An Earth-centered Earth-fixed (ECEF) coordinate system combining the Earth's true equator and equinox of date, the Earth's rotation with respect to the stars, and the @@ -791,24 +676,6 @@ def itrs(T: float | np.ndarray): ---------- T: np.ndarray Centuries since 2000-01-01T12:00:00 - - References - ---------- - .. [1] N. Capitaine, P. T. Wallace, and J. Chapront, - "Expressions for IAU 2000 precession quantities", - *Astronomy & Astrophysics*, 412, 567--586, (2003). - `doi: 10.1051/0004-6361:20031539 - `_ - .. [2] N. Capitaine, J. Chapront, S. Lambert, and P. T. Wallace, - "Expressions for the Celestial Intermediate Pole and - Celestial Ephemeris Origin consistent with the IAU 2000A - precession-nutation model", *Astronomy & Astrophysics*, - 400, 1145--1154, (2003). `doi: 10.1051/0004-6361:20030077 - `_ - .. [3] G. Petit and B. Luzum (eds.), *IERS Conventions (2010)*, - International Earth Rotation and Reference Systems Service (IERS), - `IERS Technical Note No. 36 - `_ """ # create timescale from centuries relative to 2000-01-01T12:00:00 ts = timescale.time.Timescale(MJD=T*_century + _mjd_j2000) @@ -838,31 +705,13 @@ def itrs(T: float | np.ndarray): def _eqeq_complement(T: float | np.ndarray): """ - Compute complementary terms of the equation of the - equinoxes [1]_ [2]_ [3]_ + Compute complementary terms of the equation of the equinoxes + :cite:p:`Capitaine:2003fx` :cite:p:`Capitaine:2003fw` :cite:p:`Petit:2010tp` Parameters ---------- T: np.ndarray Centuries since 2000-01-01T12:00:00 - - References - ---------- - .. [1] N. Capitaine, P. T. Wallace, and J. Chapront, - "Expressions for IAU 2000 precession quantities", - *Astronomy & Astrophysics*, 412, 567--586, (2003). - `doi: 10.1051/0004-6361:20031539 - `_ - .. [2] N. Capitaine, J. Chapront, S. Lambert, and P. T. Wallace, - "Expressions for the Celestial Intermediate Pole and - Celestial Ephemeris Origin consistent with the IAU 2000A - precession-nutation model", *Astronomy & Astrophysics*, - 400, 1145--1154, (2003). `doi: 10.1051/0004-6361:20030077 - `_ - .. [3] G. Petit and B. Luzum (eds.), *IERS Conventions (2010)*, - International Earth Rotation and Reference Systems Service (IERS), - `IERS Technical Note No. 36 - `_ """ # create timescale from centuries relative to 2000-01-01T12:00:00 ts = timescale.time.Timescale(MJD=T*_century + _mjd_j2000) @@ -939,7 +788,7 @@ def _frame_bias_matrix(): def _nutation_angles(T: float | np.ndarray): """ Calculate nutation rotation angles using tables - from IERS Conventions [1]_ + from IERS Conventions :cite:p:`Petit:2010tp` Parameters ---------- @@ -952,13 +801,6 @@ def _nutation_angles(T: float | np.ndarray): Nutation in longitude deps: np.ndarray Obliquity of the ecliptic - - References - ---------- - .. [1] G. Petit and B. Luzum (eds.), *IERS Conventions (2010)*, - International Earth Rotation and Reference Systems Service (IERS), - `IERS Technical Note No. 36 - `_ """ # create timescale from centuries relative to 2000-01-01T12:00:00 ts = timescale.time.Timescale(MJD=T*_century + _mjd_j2000) @@ -1103,8 +945,9 @@ def _precession_matrix(T: float | np.ndarray): def _parse_table_5_2e(): """Parse table with expressions for Greenwich Sidereal Time - provided in `Chapter 5 of IERS Conventions + provided in `Chapter 5 `_ + of :cite:p:`Petit:2010tp` """ table_5_2e = get_data_path(['data','tab5.2e.txt']) with table_5_2e.open(mode='r', encoding='utf8') as f: @@ -1130,8 +973,9 @@ def _parse_table_5_2e(): def _parse_table_5_3a(): """Parse table with IAU 2000A lunisolar and planetary components - of nutation in longitude provided in `Chapter 5 of IERS Conventions - `_ + of nutation in longitude provided in `Chapter 5 + `_ + of :cite:p:`Petit:2010tp` """ table_5_3a = get_data_path(['data','tab5.3a.txt']) with table_5_3a.open(mode='r', encoding='utf8') as f: @@ -1157,8 +1001,9 @@ def _parse_table_5_3a(): def _parse_table_5_3b(): """Parse table with IAU 2000A lunisolar and planetary components - of nutation in obliquity provided in `Chapter 5 of IERS Conventions - `_ + of nutation in obliquity provided in `Chapter 5 + `_ + of :cite:p:`Petit:2010tp` """ table_5_3b = get_data_path(['data','tab5.3b.txt']) with table_5_3b.open(mode='r', encoding='utf8') as f: diff --git a/pyTMD/check_points.py b/pyTMD/check_points.py index 59147559..ae969055 100644 --- a/pyTMD/check_points.py +++ b/pyTMD/check_points.py @@ -1,7 +1,7 @@ #!/usr/bin/env python u""" check_points.py -Written by Tyler Sutterley (09/2024) +Written by Tyler Sutterley (12/2024) Check if points are within a tide model domain OTIS format tidal solutions provided by Oregon State University and ESR @@ -51,6 +51,7 @@ interpolate.py: interpolation routines for spatial data UPDATE HISTORY: + Updated 12/2024: deprecated in favor of compute.tide_masks Updated 09/2024: use JSON database for known model parameters drop support for the ascii definition file format Updated 07/2024: renamed format for ATLAS to ATLAS-compact @@ -76,31 +77,12 @@ """ from __future__ import print_function, annotations -import logging import pathlib -import numpy as np -import scipy.interpolate -import pyTMD.crs -import pyTMD.io -import pyTMD.io.model -import pyTMD.interpolate -import pyTMD.utilities -# attempt imports -pyproj = pyTMD.utilities.import_dependency('pyproj') - -__all__ = [ - 'check_points' -] +import warnings +import pyTMD.compute # PURPOSE: compute tides at points and times using tide model algorithms -def check_points(x: np.ndarray, y: np.ndarray, - DIRECTORY: str | pathlib.Path | None = None, - MODEL: str | None = None, - GZIP: bool = False, - DEFINITION_FILE: str | pathlib.Path | None = None, - EPSG: str | int = 3031, - METHOD: str = 'spline' - ): +def check_points(*args, **kwargs): """ Check if points are within a tide model domain @@ -132,93 +114,6 @@ def check_points(x: np.ndarray, y: np.ndarray, valid: bool array describing if input coordinate is within model domain """ - - # check that tide directory is accessible - if DIRECTORY is not None: - DIRECTORY = pathlib.Path(DIRECTORY).expanduser() - if not DIRECTORY.exists(): - raise FileNotFoundError("Invalid tide directory") - - # get parameters for tide model - if DEFINITION_FILE is not None: - model = pyTMD.io.model(DIRECTORY).from_file(DEFINITION_FILE) - else: - model = pyTMD.io.model(DIRECTORY, compressed=GZIP).elevation(MODEL) - - # input shape of data - idim = np.shape(x) - # converting x,y from input coordinate reference system - crs1 = pyTMD.crs().from_input(EPSG) - crs2 = pyproj.CRS.from_epsg(4326) - transformer = pyproj.Transformer.from_crs(crs1, crs2, always_xy=True) - lon, lat = transformer.transform( - np.atleast_1d(x).flatten(), np.atleast_1d(y).flatten() - ) - - # read tidal constants and interpolate to grid points - if model.format in ('OTIS','ATLAS-compact','TMD3'): - # if reading a single OTIS solution - xi, yi, hz, mz, iob, dt = pyTMD.io.OTIS.read_otis_grid( - pathlib.Path(model.grid_file).expanduser()) - # invert model mask - mz = np.logical_not(mz) - # adjust dimensions of input coordinates to be iterable - # run wrapper function to convert coordinate systems of input lat/lon - X, Y = pyTMD.crs().convert(lon, lat, model.projection, 'F') - elif (model.format == 'ATLAS-netcdf'): - # if reading a netCDF OTIS atlas solution - xi, yi, hz = pyTMD.io.ATLAS.read_netcdf_grid( - pathlib.Path(model.grid_file).expanduser(), - compressed=model.compressed, type=model.type) - # copy bathymetry mask - mz = np.copy(hz.mask) - # copy latitude and longitude and adjust longitudes - X,Y = np.copy([lon,lat]).astype(np.float64) - lt0, = np.nonzero(X < 0) - X[lt0] += 360.0 - elif model.format in ('GOT-ascii', 'GOT-netcdf'): - # if reading a NASA GOT solution - hc, xi, yi, c = pyTMD.io.GOT.read_ascii_file( - pathlib.Path(model.model_file[0]).expanduser(), - compressed=model.compressed) - # copy tidal constituent mask - mz = np.copy(hc.mask) - # copy latitude and longitude and adjust longitudes - X, Y = np.copy([lon,lat]).astype(np.float64) - lt0, = np.nonzero(X < 0) - X[lt0] += 360.0 - elif (model.format == 'FES-netcdf'): - # if reading a FES netCDF solution - hc, xi, yi = pyTMD.io.FES.read_netcdf_file( - pathlib.Path(model.model_file[0]).expanduser(), - compressed=model.compressed, type=model.type, - version=model.version) - # copy tidal constituent mask - mz = np.copy(hc.mask) - # copy latitude and longitude and adjust longitudes - X, Y = np.copy([lon,lat]).astype(np.float64) - lt0, = np.nonzero(X < 0) - X[lt0] += 360.0 - - # interpolate masks - if (METHOD == 'bilinear'): - # replace invalid values with nan - mz1 = pyTMD.interpolate.bilinear(xi, yi, mz, X, Y) - mask = np.floor(mz1).astype(mz.dtype) - elif (METHOD == 'spline'): - f1 = scipy.interpolate.RectBivariateSpline(xi, yi, mz.T, - kx=1, ky=1) - mask = np.floor(f1.ev(X, Y)).astype(mz.dtype) - else: - # use scipy regular grid to interpolate values - r1 = scipy.interpolate.RegularGridInterpolator((yi, xi), mz, - method=METHOD, bounds_error=False, fill_value=1) - mask = np.floor(r1.__call__(np.c_[y, x])).astype(mz.dtype) - - # reshape to original dimensions - valid = np.logical_not(mask).reshape(idim).astype(mz.dtype) - # replace points outside model domain with invalid - valid &= (X >= xi.min()) & (X <= xi.max()) - valid &= (Y >= yi.min()) & (Y <= yi.max()) - # return the valid mask - return valid + warnings.warn("Deprecated. Please use pyTMD.compute instead", + DeprecationWarning) + return pyTMD.compute.tide_masks(*args, **kwargs) diff --git a/pyTMD/compute.py b/pyTMD/compute.py index 8fcf6b39..ab325d28 100644 --- a/pyTMD/compute.py +++ b/pyTMD/compute.py @@ -1,7 +1,7 @@ #!/usr/bin/env python u""" compute.py -Written by Tyler Sutterley (11/2024) +Written by Tyler Sutterley (12/2024) Calculates tidal elevations for correcting elevation or imagery data Calculates tidal currents at locations and times @@ -60,6 +60,7 @@ interpolate.py: interpolation routines for spatial data UPDATE HISTORY: + Updated 12/2024: moved check points function as compute.tide_masks Updated 11/2024: expose buffer distance for cropping tide model data Updated 10/2024: compute delta times based on corrections type simplify by using wrapper functions to read and interpolate constants @@ -659,6 +660,137 @@ def tide_currents( # return the ocean tide currents return tide +# PURPOSE: check if points are within a tide model domain +def tide_masks(x: np.ndarray, y: np.ndarray, + DIRECTORY: str | pathlib.Path | None = None, + MODEL: str | None = None, + GZIP: bool = False, + DEFINITION_FILE: str | pathlib.Path | None = None, + EPSG: str | int = 3031, + METHOD: str = 'spline' + ): + """ + Check if points are within a tide model domain + + Parameters + ---------- + x: np.ndarray + x-coordinates in projection EPSG + y: np.ndarray + y-coordinates in projection EPSG + DIRECTORY: str or NoneType, default None + working data directory for tide models + MODEL: str or NoneType, default None + Tide model to use + GZIP: bool, default False + Tide model files are gzip compressed + DEFINITION_FILE: str or NoneType, default None + Tide model definition file for use + EPSG: str or int, default: 3031 (Polar Stereographic South, WGS84) + Input coordinate system + METHOD: str, default 'spline' + interpolation method + + - ```bilinear```: quick bilinear interpolation + - ```spline```: scipy bivariate spline interpolation + - ```linear```, ```nearest```: scipy regular grid interpolations + + Returns + ------- + valid: bool + array describing if input coordinate is within model domain + """ + + # check that tide directory is accessible + if DIRECTORY is not None: + DIRECTORY = pathlib.Path(DIRECTORY).expanduser() + if not DIRECTORY.exists(): + raise FileNotFoundError("Invalid tide directory") + + # get parameters for tide model + if DEFINITION_FILE is not None: + model = pyTMD.io.model(DIRECTORY).from_file(DEFINITION_FILE) + else: + model = pyTMD.io.model(DIRECTORY, compressed=GZIP).elevation(MODEL) + + # input shape of data + idim = np.shape(x) + # converting x,y from input coordinate reference system + crs1 = pyTMD.crs().from_input(EPSG) + crs2 = pyproj.CRS.from_epsg(4326) + transformer = pyproj.Transformer.from_crs(crs1, crs2, always_xy=True) + lon, lat = transformer.transform( + np.atleast_1d(x).flatten(), np.atleast_1d(y).flatten() + ) + + # read tidal constants and interpolate to grid points + if model.format in ('OTIS','ATLAS-compact','TMD3'): + # if reading a single OTIS solution + xi, yi, hz, mz, iob, dt = pyTMD.io.OTIS.read_otis_grid( + pathlib.Path(model.grid_file).expanduser()) + # invert model mask + mz = np.logical_not(mz) + # adjust dimensions of input coordinates to be iterable + # run wrapper function to convert coordinate systems of input lat/lon + X, Y = pyTMD.crs().convert(lon, lat, model.projection, 'F') + elif (model.format == 'ATLAS-netcdf'): + # if reading a netCDF OTIS atlas solution + xi, yi, hz = pyTMD.io.ATLAS.read_netcdf_grid( + pathlib.Path(model.grid_file).expanduser(), + compressed=model.compressed, type=model.type) + # copy bathymetry mask + mz = np.copy(hz.mask) + # copy latitude and longitude and adjust longitudes + X,Y = np.copy([lon,lat]).astype(np.float64) + lt0, = np.nonzero(X < 0) + X[lt0] += 360.0 + elif model.format in ('GOT-ascii', 'GOT-netcdf'): + # if reading a NASA GOT solution + hc, xi, yi, c = pyTMD.io.GOT.read_ascii_file( + pathlib.Path(model.model_file[0]).expanduser(), + compressed=model.compressed) + # copy tidal constituent mask + mz = np.copy(hc.mask) + # copy latitude and longitude and adjust longitudes + X, Y = np.copy([lon,lat]).astype(np.float64) + lt0, = np.nonzero(X < 0) + X[lt0] += 360.0 + elif (model.format == 'FES-netcdf'): + # if reading a FES netCDF solution + hc, xi, yi = pyTMD.io.FES.read_netcdf_file( + pathlib.Path(model.model_file[0]).expanduser(), + compressed=model.compressed, type=model.type, + version=model.version) + # copy tidal constituent mask + mz = np.copy(hc.mask) + # copy latitude and longitude and adjust longitudes + X, Y = np.copy([lon,lat]).astype(np.float64) + lt0, = np.nonzero(X < 0) + X[lt0] += 360.0 + + # interpolate masks + if (METHOD == 'bilinear'): + # replace invalid values with nan + mz1 = pyTMD.interpolate.bilinear(xi, yi, mz, X, Y) + mask = np.floor(mz1).astype(mz.dtype) + elif (METHOD == 'spline'): + f1 = scipy.interpolate.RectBivariateSpline(xi, yi, mz.T, + kx=1, ky=1) + mask = np.floor(f1.ev(X, Y)).astype(mz.dtype) + else: + # use scipy regular grid to interpolate values + r1 = scipy.interpolate.RegularGridInterpolator((yi, xi), mz, + method=METHOD, bounds_error=False, fill_value=1) + mask = np.floor(r1.__call__(np.c_[y, x])).astype(mz.dtype) + + # reshape to original dimensions + valid = np.logical_not(mask).reshape(idim).astype(mz.dtype) + # replace points outside model domain with invalid + valid &= (X >= xi.min()) & (X <= xi.max()) + valid &= (Y >= yi.min()) & (Y <= yi.max()) + # return the valid mask + return valid + # PURPOSE: compute long-period equilibrium tidal elevations def LPET_elevations( x: np.ndarray, y: np.ndarray, delta_time: np.ndarray, diff --git a/pyTMD/ellipse.py b/pyTMD/ellipse.py index b810e033..c2d21c79 100644 --- a/pyTMD/ellipse.py +++ b/pyTMD/ellipse.py @@ -44,7 +44,7 @@ def ellipse(u: np.ndarray, v: np.ndarray): """ Expresses the amplitudes and phases for the u and v components in terms of - four ellipse parameters using Foreman's formula [1]_ + four ellipse parameters using Foreman's formula :cite:p:`Foreman:1989dt` Parameters ---------- @@ -64,13 +64,6 @@ def ellipse(u: np.ndarray, v: np.ndarray): uphase: np.ndarray phase lag of the maximum current behind the maximum tidal potential of the individual constituent - - References - ---------- - .. [1] M. G. G. Foreman and R. F. Henry, "The harmonic analysis of tidal - model time series," *Advances in Water Resources*, 12(3), 109--120, - (1989). `doi: 10.1016/0309-1708(89)90017-1 - `_ """ # validate inputs u = np.atleast_1d(u) @@ -107,7 +100,7 @@ def inverse( ): """ Calculates currents u, v using the four tidal ellipse - parameters from Foreman's formula [1]_ + parameters from Foreman's formula :cite:p:`Foreman:1989dt` Parameters ---------- @@ -127,13 +120,6 @@ def inverse( zonal current (EW) v: np.ndarray meridional current (NS) - - References - ---------- - .. [1] M. G. G. Foreman and R. F. Henry, "The harmonic analysis of tidal - model time series," *Advances in Water Resources*, 12(3), 109--120, - (1989). `doi: 10.1016/0309-1708(89)90017-1 - `_ """ # validate inputs umajor = np.atleast_1d(umajor) diff --git a/pyTMD/eop.py b/pyTMD/eop.py index 1e6058a0..c07221c7 100644 --- a/pyTMD/eop.py +++ b/pyTMD/eop.py @@ -156,7 +156,7 @@ def update_finals_file(**kwargs): def iers_mean_pole(*args, **kwargs): """ Calculates the angular coordinates of the IERS Conventional Mean Pole (CMP) - or IERS Secular Pole (2018 convention) + or IERS Secular Pole (2018 convention) :cite:p:`Petit:2010tp` Parameters ---------- @@ -183,13 +183,6 @@ def iers_mean_pole(*args, **kwargs): Angular coordinate y of conventional mean pole or secular pole flag: np.ndarray epoch is valid for version and version number is valid - - References - ---------- - .. [1] G. Petit and B. Luzum (eds.), *IERS Conventions (2010)*, - International Earth Rotation and Reference Systems Service (IERS), - `IERS Technical Note No. 36 - `_ """ warnings.warn("Deprecated. Please use timescale.eop.iers_mean_pole", DeprecationWarning) @@ -199,6 +192,7 @@ def iers_mean_pole(*args, **kwargs): def iers_daily_EOP(**kwargs): """ Read daily earth orientation parameters (EOP) file from IERS + :cite:p:`Petit:2010tp` Parameters ---------- @@ -213,13 +207,6 @@ def iers_daily_EOP(**kwargs): Angular coordinate x [arcsec] y: np.ndarray Angular coordinate y [arcsec] - - References - ---------- - .. [1] G. Petit and B. Luzum (eds.), *IERS Conventions (2010)*, - International Earth Rotation and Reference Systems Service (IERS), - `IERS Technical Note No. 36 - `_ """ warnings.warn("Deprecated. Please use timescale.eop.iers_daily_EOP", DeprecationWarning) @@ -228,6 +215,7 @@ def iers_daily_EOP(**kwargs): def iers_polar_motion(*args, **kwargs): """ Interpolates daily earth orientation parameters (EOP) file from IERS + :cite:p:`Petit:2010tp` Parameters ---------- @@ -246,13 +234,6 @@ def iers_polar_motion(*args, **kwargs): Angular coordinate x [arcsec] py: np.ndarray Angular coordinate y [arcsec] - - References - ---------- - .. [1] G. Petit and B. Luzum (eds.), *IERS Conventions (2010)*, - International Earth Rotation and Reference Systems Service (IERS), - `IERS Technical Note No. 36 - `_ """ warnings.warn("Deprecated. Please use timescale.eop.iers_polar_motion", DeprecationWarning) diff --git a/pyTMD/io/IERS.py b/pyTMD/io/IERS.py index d7e58c44..17585108 100644 --- a/pyTMD/io/IERS.py +++ b/pyTMD/io/IERS.py @@ -76,8 +76,8 @@ def extract_coefficients( **kwargs ): """ - Reads ocean pole tide file from [1]_ [2]_ and spatially interpolates - to input coordinates + Reads ocean pole tide file from :cite:p:`Desai:2002ev` :cite:p:`Desai:2015jr` + and spatially interpolates to input coordinates Parameters ---------- @@ -101,15 +101,6 @@ def extract_coefficients( north ocean pole tide coefficients ue: np.ndarray east ocean pole tide coefficients - - References - ---------- - .. [1] S. Desai, "Observing the pole tide with satellite altimetry", *Journal of - Geophysical Research: Oceans*, 107(C11), (2002). - `doi: 10.1029/2001JC001224 `_ - .. [2] S. Desai, J. Wahr and B. Beckley "Revisiting the pole tide for and from - satellite altimetry", *Journal of Geodesy*, 89(12), p1233-1243, (2015). - `doi: 10.1007/s00190-015-0848-7 `_ """ # default keyword arguments kwargs.setdefault('model_file', _ocean_pole_tide_file) @@ -144,7 +135,8 @@ def extract_coefficients( # PURPOSE: read real and imaginary ocean pole tide coefficients def read_binary_file(**kwargs): """ - Read real and imaginary ocean pole tide coefficients from [1]_ [2]_ + Read real and imaginary ocean pole tide coefficients from + :cite:p:`Desai:2002ev` :cite:p:`Desai:2015jr` Parameters ---------- @@ -163,15 +155,6 @@ def read_binary_file(**kwargs): ocean grid longitude glat: np.ndarray ocean grid latitude - - References - ---------- - .. [1] S. Desai, "Observing the pole tide with satellite altimetry", *Journal of - Geophysical Research: Oceans*, 107(C11), (2002). - `doi: 10.1029/2001JC001224 `_ - .. [2] S. Desai, J. Wahr and B. Beckley "Revisiting the pole tide for and from - satellite altimetry", *Journal of Geodesy*, 89(12), p1233-1243, (2015). - `doi: 10.1007/s00190-015-0848-7 `_ """ # default keyword arguments kwargs.setdefault('model_file', _ocean_pole_tide_file) diff --git a/pyTMD/io/model.py b/pyTMD/io/model.py index dace713b..dba1c984 100644 --- a/pyTMD/io/model.py +++ b/pyTMD/io/model.py @@ -1175,7 +1175,7 @@ def interpolate_constants(self, def node_equilibrium(lat: np.ndarray): """ Compute the equilibrium amplitude and phase of the 18.6 year - node tide [1]_ [2]_ + node tide :cite:p:`Cartwright:1971iz` :cite:p:`Cartwright:1973em` Parameters ---------- @@ -1188,19 +1188,6 @@ def node_equilibrium(lat: np.ndarray): Tidal amplitude in meters phase: np.ndarray Tidal phase in degrees - - References - ---------- - .. [1] D. E. Cartwright and R. J. Tayler, - "New Computations of the Tide-generating Potential," - *Geophysical Journal of the Royal Astronomical Society*, - 23(1), 45--73. (1971). `doi: 10.1111/j.1365-246X.1971.tb01803.x - `_ - .. [2] D. E. Cartwright and A. C. Edden, - "Corrected Tables of Tidal Harmonics," - *Geophysical Journal of the Royal Astronomical Society*, - 33(3), 253--264, (1973). `doi: 10.1111/j.1365-246X.1973.tb03420.x - `_ """ # Cartwright and Edden potential amplitude amajor = 0.027929# node diff --git a/pyTMD/math.py b/pyTMD/math.py index c7b001ee..3206db69 100644 --- a/pyTMD/math.py +++ b/pyTMD/math.py @@ -33,7 +33,8 @@ def polynomial_sum( t: np.ndarray ): """ - Calculates the sum of a polynomial function using Horner's method [1]_ + Calculates the sum of a polynomial function using Horner's method + :cite:p:`Horner:1819br` Parameters ---------- @@ -41,13 +42,6 @@ def polynomial_sum( leading coefficient of polynomials of increasing order t: np.ndarray delta time in units for a given astronomical longitudes calculation - - References - ---------- - .. [1] W. G. Horner and D. Gilbert, "A new method of solving numerical - equations of all orders, by continuous approximation," *Philosophical - Transactions of the Royal Society of London*, 109, 308--335, (1819). - `doi: 10.1098/rstl.1819.0023 `_ """ # convert time to array if importing a single value t = np.atleast_1d(t) @@ -140,7 +134,7 @@ def legendre( ): """ Computes associated Legendre functions for a particular degree - and order [1]_ [2]_ + and order :cite:p:`Munk:1966go` :cite:p:`HofmannWellenhof:2006hy` Parameters ---------- @@ -157,17 +151,6 @@ def legendre( ------- Plm: np.ndarray Legendre polynomials of degree ``l`` and order ``m`` - - References - ---------- - .. [1] W. H. Munk, D. E. Cartwright, and E. C. Bullard, "Tidal - spectroscopy and prediction," *Philosophical Transactions of the - Royal Society of London. Series A, Mathematical and Physical - Sciences*, 259(1105), 533--581, (1966). - `doi: 10.1098/rsta.1966.0024 `_ - .. [2] B. Hofmann-Wellenhof and H. Moritz, *Physical Geodesy*, - 2nd Edition, 403 pp., (2006). `doi: 10.1007/978-3-211-33545-1 - `_ """ # verify values are integers l = np.int64(l) @@ -211,7 +194,7 @@ def sph_harm( ): """ Computes the spherical harmonics for a particular degree - and order [1]_ [2]_ + and order :cite:p:`Munk:1966go` :cite:p:`HofmannWellenhof:2006hy` Parameters ---------- @@ -228,17 +211,6 @@ def sph_harm( ------- Ylm: np.ndarray complex spherical harmonics of degree ``l`` and order ``m`` - - References - ---------- - .. [1] W. H. Munk, D. E. Cartwright, and E. C. Bullard, "Tidal - spectroscopy and prediction," *Philosophical Transactions of the - Royal Society of London. Series A, Mathematical and Physical - Sciences*, 259(1105), 533--581, (1966). - `doi: 10.1098/rsta.1966.0024 `_ - .. [2] B. Hofmann-Wellenhof and H. Moritz, *Physical Geodesy*, - 2nd Edition, 403 pp., (2006). `doi: 10.1007/978-3-211-33545-1 - `_ """ # verify dimensions singular_values = (np.ndim(theta) == 0) diff --git a/pyTMD/predict.py b/pyTMD/predict.py index e466541a..59c295dd 100644 --- a/pyTMD/predict.py +++ b/pyTMD/predict.py @@ -108,7 +108,7 @@ def map(t: float | np.ndarray, corrections: str = 'OTIS' ): """ - Predict tides at a single time using harmonic constants [1]_ + Predict tides at a single time using harmonic constants :cite:p:`Egbert:2002ge` Parameters ---------- @@ -127,15 +127,6 @@ def map(t: float | np.ndarray, ------- ht: np.ndarray tide values reconstructed using the nodal corrections - - References - ---------- - .. [1] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of - Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic - Technology*, 19(2), 183--204, (2002). - `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__ - - .. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2 """ # number of points and number of constituents npts, nc = np.shape(hc) @@ -175,7 +166,7 @@ def drift(t: float | np.ndarray, ): """ Predict tides at multiple times and locations using harmonic - constants [1]_ + constants :cite:p:`Egbert:2002ge` Parameters ---------- @@ -194,15 +185,6 @@ def drift(t: float | np.ndarray, ------- ht: np.ndarray tidal time series reconstructed using the nodal corrections - - References - ---------- - .. [1] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of - Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic - Technology*, 19(2), 183--204, (2002). - `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__ - - .. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2 """ nt = len(t) # load the nodal corrections @@ -241,7 +223,7 @@ def time_series(t: float | np.ndarray, ): """ Predict tidal time series at a single location using harmonic - constants [1]_ + constants :cite:p:`Egbert:2002ge` Parameters ---------- @@ -260,15 +242,6 @@ def time_series(t: float | np.ndarray, ------- ht: np.ndarray tidal time series reconstructed using the nodal corrections - - References - ---------- - .. [1] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of - Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic - Technology*, 19(2), 183--204, (2002). - `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__ - - .. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2 """ nt = len(t) # load the nodal corrections @@ -307,7 +280,8 @@ def infer_minor( ): """ Infer the tidal values for minor constituents using their - relation with major constituents [1]_ [2]_ [3]_ [4]_ + relation with major constituents :cite:p:`Doodson:1941td` :cite:p:`Schureman:1958ty` + :cite:p:`Foreman:1989dt` :cite:p:`Egbert:2002ge` Parameters ---------- @@ -332,23 +306,6 @@ def infer_minor( ------- dh: np.ndarray tidal time series for minor constituents - - References - ---------- - .. [1] A. T. Doodson and H. D. Warburg, "Admiralty Manual of Tides", - HMSO, London, (1941). - .. [2] P. Schureman, "Manual of Harmonic Analysis and Prediction of Tides," - *US Coast and Geodetic Survey*, Special Publication, 98, (1958). - .. [3] M. G. G. Foreman and R. F. Henry, "The harmonic analysis of tidal - model time series," *Advances in Water Resources*, 12(3), 109--120, - (1989). `doi: 10.1016/0309-1708(89)90017-1 - `_ - .. [4] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of - Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic - Technology*, 19(2), 183--204, (2002). - `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__ - - .. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2 """ # set default keyword arguments kwargs.setdefault('deltat', 0.0) @@ -378,7 +335,8 @@ def _infer_short_period( ): """ Infer the tidal values for short-period minor constituents - using their relation with major constituents [1]_ [2]_ + using their relation with major constituents + :cite:p:`Egbert:2002ge` :cite:p:`Ray:1999vm` Parameters ---------- @@ -401,18 +359,6 @@ def _infer_short_period( ------- dh: np.ndarray tidal time series for minor constituents - - References - ---------- - .. [1] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of - Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic - Technology*, 19(2), 183--204, (2002). - `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__ - .. [2] R. D. Ray, "A global ocean tide model from - Topex/Poseidon altimetry: GOT99.2", - NASA Goddard Space Flight Center, TM-1999-209478, (1999). - - .. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2 """ # set default keyword arguments kwargs.setdefault('deltat', 0.0) @@ -521,7 +467,8 @@ def _infer_semi_diurnal( ): """ Infer the tidal values for semi-diurnal minor constituents - using their relation with major constituents [1]_ [2]_ [3]_ + using their relation with major constituents :cite:p:`Munk:1966go` + :cite:p:`Ray:1999vm` :cite:p:`Cartwright:1971iz` Parameters ---------- @@ -547,22 +494,6 @@ def _infer_semi_diurnal( ------- dh: np.ndarray tidal time series for minor constituents - - References - ---------- - .. [1] W. H. Munk, D. E. Cartwright, and E. C. Bullard, "Tidal - spectroscopy and prediction," *Philosophical Transactions of the - Royal Society of London. Series A, Mathematical and Physical - Sciences*, 259(1105), 533--581, (1966). - `doi: 10.1098/rsta.1966.0024 `_ - .. [2] R. D. Ray, "A global ocean tide model from - Topex/Poseidon altimetry: GOT99.2", - NASA Goddard Space Flight Center, TM-1999-209478, (1999). - .. [3] D. E. Cartwright and A. C. Edden, - "Corrected Tables of Tidal Harmonics," - *Geophysical Journal of the Royal Astronomical Society*, - 33(3), 253--264, (1973). `doi: 10.1111/j.1365-246X.1973.tb03420.x - `_ """ # set default keyword arguments kwargs.setdefault('deltat', 0.0) @@ -689,7 +620,8 @@ def _infer_diurnal( """ Infer the tidal values for diurnal minor constituents using their relation with major constituents taking into - account resonance due to free core nutation [1]_ [2]_ [3]_ [4]_ + account resonance due to free core nutation + :cite:p:`Munk:1966go` :cite:p:`Ray:2017jx` :cite:p:`Wahr:1981if` :cite:p:`Cartwright:1973em` Parameters ---------- @@ -715,29 +647,6 @@ def _infer_diurnal( ------- dh: np.ndarray tidal time series for minor constituents - - References - ---------- - .. [1] W. H. Munk, D. E. Cartwright, and E. C. Bullard, "Tidal - spectroscopy and prediction," *Philosophical Transactions of the - Royal Society of London. Series A, Mathematical and Physical - Sciences*, 259(1105), 533--581, (1966). - `doi: 10.1098/rsta.1966.0024 `_ - .. [2] R. D. Ray, "On Tidal Inference in the Diurnal Band", - Journal of Atmospheric and Oceanic Technology, 34(2), 437--446, - (2017). `doi: 10.1175/jtech-d-16-0142.1 - `_ - .. [3] J. M. Wahr and T. Sasao, "A diurnal resonance in the ocean - tide and in the Earth's load response due to the resonant free - `core nutation`", *Geophysical Journal of the Royal Astronomical - Society*, 64(3), 747--765, (1981). - `doi: 10.1111/j.1365-246X.1981.tb02693.x - `_ - .. [4] D. E. Cartwright and A. C. Edden, - "Corrected Tables of Tidal Harmonics," - *Geophysical Journal of the Royal Astronomical Society*, - 33(3), 253--264, (1973). `doi: 10.1111/j.1365-246X.1973.tb03420.x - `_ """ # set default keyword arguments kwargs.setdefault('deltat', 0.0) @@ -875,7 +784,8 @@ def _infer_long_period( ): """ Infer the tidal values for long-period minor constituents - using their relation with major constituents [1]_ [2]_ [3]_ + using their relation with major constituents + :cite:p:`Ray:1999vm` :cite:p:`Ray:2014fu` :cite:p:`Cartwright:1973em` Parameters ---------- @@ -896,21 +806,6 @@ def _infer_long_period( ------- dh: np.ndarray tidal time series for minor constituents - - References - ---------- - .. [1] R. D. Ray, "A global ocean tide model from - Topex/Poseidon altimetry: GOT99.2", - NASA Goddard Space Flight Center, TM-1999-209478, (1999). - .. [2] R. D. Ray and S. Y. Erofeeva, "Long-period tidal - variations in the length of day", *Journal of Geophysical - Research: Solid Earth*, 119, 1498--1509, (2013). - `doi: 10.1002/2013JB010830 `_ - .. [3] D. E. Cartwright and A. C. Edden, - "Corrected Tables of Tidal Harmonics," - *Geophysical Journal of the Royal Astronomical Society*, - 33(3), 253--264, (1973). `doi: 10.1111/j.1365-246X.1973.tb03420.x - `_ """ # set default keyword arguments kwargs.setdefault('deltat', 0.0) @@ -1013,7 +908,8 @@ def equilibrium_tide( ): """ Compute the long-period equilibrium tides the summation of fifteen - tidal spectral lines from Cartwright-Tayler-Edden tables [1]_ [2]_ + tidal spectral lines from Cartwright-Tayler-Edden tables + :cite:p:`Cartwright:1971iz` :cite:p:`Cartwright:1973em` Parameters ---------- @@ -1032,19 +928,6 @@ def equilibrium_tide( ------- lpet: np.ndarray long-period equilibrium tide in meters - - References - ---------- - .. [1] D. E. Cartwright and R. J. Tayler, - "New Computations of the Tide-generating Potential," - *Geophysical Journal of the Royal Astronomical Society*, - 23(1), 45--73. (1971). `doi: 10.1111/j.1365-246X.1971.tb01803.x - `_ - .. [2] D. E. Cartwright and A. C. Edden, - "Corrected Tables of Tidal Harmonics," - *Geophysical Journal of the Royal Astronomical Society*, - 33(3), 253--264, (1973). `doi: 10.1111/j.1365-246X.1973.tb03420.x - `_ """ # set default keyword arguments cindex = ['node', 'sa', 'ssa', 'msm', '065.445', 'mm', @@ -1162,7 +1045,7 @@ def load_pole_tide( ): """ Estimate load pole tide displacements in Cartesian coordinates - following IERS Convention (2010) guidelines + :cite:p:`Petit:2010tp` Parameters ---------- @@ -1273,7 +1156,7 @@ def ocean_pole_tide( ): """ Estimate ocean pole tide displacements in Cartesian coordinates - following IERS Convention (2010) guidelines + :cite:p:`Desai:2002ev` :cite:p:`Desai:2015jr` :cite:p:`Petit:2010tp` Parameters ---------- @@ -1375,8 +1258,8 @@ def solid_earth_tide( **kwargs ): """ - Compute the solid Earth tides due to the gravitational attraction - of the moon and sun [1]_ [2]_ [3]_ [4]_ + Compute the solid Earth tides due to the gravitational attraction of + the moon and sun :cite:p:`Mathews:1991kv` :cite:p:`Mathews:1997js` :cite:p:`Ries:1992ip` :cite:p:`Wahr:1981ea` Parameters ---------- @@ -1400,28 +1283,6 @@ def solid_earth_tide( ------- dxt: np.ndarray Solid Earth tide in meters in Cartesian coordinates - - References - ---------- - .. [1] P. M. Mathews, B. A. Buffett, T. A. Herring and I. I Shapiro, - "Forced nutations of the Earth: Influence of inner core dynamics: - 1. Theory", *Journal of Geophysical Research: Solid Earth*, - 96(B5), 8219--8242, (1991). `doi: 10.1029/90JB01955 - `_ - .. [2] P. M. Mathews, V. Dehant and J. M. Gipson, - "Tidal station displacements", *Journal of Geophysical - Research: Solid Earth*, 102(B9), 20469--20477, (1997). - `doi: 10.1029/97JB01515 `_ - .. [3] J. C. Ries, R. J. Eanes, C. K. Shum and M. M. Watkins, - "Progress in the determination of the gravitational - coefficient of the Earth", *Geophysical Research Letters*, - 19(6), 529--531, (1992). `doi: 10.1029/92GL00259 - `_ - .. [4] J. M. Wahr, "Body tides on an elliptical, rotating, elastic - and oceanless Earth", *Geophysical Journal of the Royal - Astronomical Society*, 64(3), 677--703, (1981). - `doi: 10.1111/j.1365-246X.1981.tb02690.x - `_ """ # set default keyword arguments # nominal Love and Shida numbers diff --git a/pyTMD/solve/constants.py b/pyTMD/solve/constants.py index 8940ddd0..06c314ab 100644 --- a/pyTMD/solve/constants.py +++ b/pyTMD/solve/constants.py @@ -47,7 +47,8 @@ def constants(t: float | np.ndarray, max_iter: int | None = None ): """ - Estimate the harmonic constants for an elevation time series [1]_ + Estimate the harmonic constants for an elevation time series + :cite:p:`Egbert:2002ge` Parameters ---------- @@ -80,15 +81,6 @@ def constants(t: float | np.ndarray, amplitude of each harmonic constant (meters) phase: np.ndarray phase of each harmonic constant (degrees) - - References - ---------- - .. [1] G. D. Egbert and S. Y. Erofeeva, "Efficient Inverse Modeling of - Barotropic Ocean Tides," *Journal of Atmospheric and Oceanic - Technology*, 19(2), 183--204, (2002). - `doi: 10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2`__ - - .. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2 """ # check if input constituents is a string if isinstance(constituents, str): diff --git a/pyTMD/spatial.py b/pyTMD/spatial.py index f0882ab2..c39225bd 100644 --- a/pyTMD/spatial.py +++ b/pyTMD/spatial.py @@ -1381,7 +1381,8 @@ def convert_ellipsoid( itmax: int = 10 ): """ - Convert latitudes and heights to a different ellipsoid using Newton-Raphson + Convert latitudes and heights to a different ellipsoid using + Newton-Raphson :cite:p:`Meeus:1991vh` Parameters ---------- @@ -1409,10 +1410,6 @@ def convert_ellipsoid( latitude of output ellipsoid in degrees h2: np.ndarray height above output ellipsoid in meters - - References - ---------- - .. [1] J. Meeus, *Astronomical Algorithms*, 2nd edition, 477 pp., (1998). """ if (len(phi1) != len(h1)): raise ValueError('phi and h have incompatible dimensions') @@ -1531,7 +1528,7 @@ def compute_delta_h( ): """ Compute difference in elevation for two ellipsoids at a given - latitude using a simplified empirical relation + latitude using a simplified empirical relation :cite:p:`Meeus:1991vh` Parameters ---------- @@ -1550,10 +1547,6 @@ def compute_delta_h( ------- delta_h: np.ndarray difference in elevation for two ellipsoids - - References - ---------- - .. [1] J Meeus, *Astronomical Algorithms*, pp. 77--82, (1991). """ # force latitudes to be within -90 to 90 and convert to radians phi = np.clip(lat, -90.0, 90.0)*np.pi/180.0 @@ -1805,7 +1798,7 @@ def _moritz_iterative( ): """ Convert from cartesian coordinates to geodetic coordinates - using the iterative solution of [1]_ + using the iterative solution of :cite:p:`HofmannWellenhof:2006hy` Parameters ---------- @@ -1823,13 +1816,6 @@ def _moritz_iterative( tolerance for iterative method iterations: int, default 10 maximum number of iterations - - References - ---------- - .. [1] B. Hofmann-Wellenhof and H. Moritz, - *Physical Geodesy*, 2nd Edition, 403 pp., (2006). - `doi: 10.1007/978-3-211-33545-1 - `_ """ # Linear eccentricity and first numerical eccentricity lin_ecc = np.sqrt((2.0*flat - flat**2)*a_axis**2) @@ -1871,8 +1857,8 @@ def _bowring_iterative( iterations: int = 10 ): """ - Convert from cartesian coordinates to geodetic coordinates - using the iterative solution of [1]_ [2]_ + Convert from cartesian coordinates to geodetic coordinates using + the iterative solution of :cite:p:`Bowring:1976jh` :cite:p:`Bowring:1985du` Parameters ---------- @@ -1890,17 +1876,6 @@ def _bowring_iterative( tolerance for iterative method iterations: int, default 10 maximum number of iterations - - References - ---------- - .. [1] B. R. Bowring, "Transformation from spatial - to geodetic coordinates," *Survey Review*, 23(181), - 323--327, (1976). `doi: 10.1179/sre.1976.23.181.323 - `_ - .. [2] B. R. Bowring, "The Accuracy Of Geodetic - Latitude and Height Equations," *Survey Review*, 28(218), - 202--206, (1985). `doi: 10.1179/sre.1985.28.218.202 - `_ """ # semiminor axis of the WGS84 ellipsoid [m] b_axis = (1.0 - flat)*a_axis @@ -1949,7 +1924,7 @@ def _zhu_closed_form( ): """ Convert from cartesian coordinates to geodetic coordinates - using the closed-form solution of [1]_ + using the closed-form solution of :cite:p:`Zhu:1993ja` Parameters ---------- @@ -1963,14 +1938,6 @@ def _zhu_closed_form( semimajor axis of the ellipsoid flat: float, default 1.0/298.257223563 ellipsoidal flattening - - References - ---------- - .. [1] J. Zhu, "Exact conversion of Earth-centered, - Earth-fixed coordinates to geodetic coordinates," - *Journal of Guidance, Control, and Dynamics*, - 16(2), 389--391, (1993). `doi: 10.2514/3.21016 - `_ """ # semiminor axis of the WGS84 ellipsoid [m] b_axis = (1.0 - flat)*a_axis @@ -2256,7 +2223,8 @@ def scale_factors( ): """ Calculates scaling factors to account for polar stereographic - distortion including special case of at the exact pole [1]_ [2]_ + distortion including special case of at the exact pole + :cite:p:`Snyder:1982gf` Parameters ---------- @@ -2276,12 +2244,6 @@ def scale_factors( ------- scale: np.ndarray scaling factors at input latitudes - - References - ---------- - .. [1] J. P. Snyder, *Map Projections used by the U.S. Geological Survey*, - Geological Survey Bulletin 1532, U.S. Government Printing Office, (1982). - .. [2] JPL Technical Memorandum 3349-85-101 """ assert metric.lower() in ['distance', 'area'], 'Unknown metric' # convert latitude from degrees to positive radians diff --git a/pyTMD/time.py b/pyTMD/time.py index 2a2e171b..c5400b0f 100644 --- a/pyTMD/time.py +++ b/pyTMD/time.py @@ -271,7 +271,7 @@ def convert_calendar_dates(*args, **kwargs) -> np.ndarray: def convert_calendar_decimal(*args, **kwargs) -> np.ndarray: """ Converts from calendar date into decimal years taking into - account leap years + account leap years :cite:p:`Dershowitz:2007cc` Parameters ---------- @@ -294,12 +294,6 @@ def convert_calendar_decimal(*args, **kwargs) -> np.ndarray: ------- t_date: np.ndarray date in decimal-year format - - References - ---------- - .. [1] N. Dershowitz, and E. M. Reingold. - *Calendrical Calculations*, - Cambridge: Cambridge University Press, (2008). """ warnings.warn("Deprecated. Please use timescale.time.convert_calendar_decimal", DeprecationWarning) @@ -309,6 +303,7 @@ def convert_calendar_decimal(*args, **kwargs) -> np.ndarray: def convert_julian(*args, **kwargs): """ Converts from Julian day to calendar date and time + :cite:p:`Press:1988we` :cite:p:`Hatcher:1984uo` Parameters ---------- @@ -337,15 +332,6 @@ def convert_julian(*args, **kwargs): minute of the hour second: np.ndarray second of the minute - - References - ---------- - .. [1] W. H. Press, *Numerical Recipes in C*, - Brian P. Flannery, Saul A. Teukolsky, and William T. Vetterling. - Cambridge University Press, (1988). - .. [2] D. A. Hatcher, "Simple Formulae for Julian Day Numbers and - Calendar Dates", *Quarterly Journal of the Royal Astronomical - Society*, 25(1), 1984. """ warnings.warn("Deprecated. Please use timescale.time.convert_calendar_decimal", DeprecationWarning) diff --git a/pyproject.toml b/pyproject.toml index 8957b635..dddaa247 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -59,7 +59,7 @@ Repository = "https://github.com/tsutterley/pyTMD" Issues = "https://github.com/tsutterley/pyTMD/issues" [project.optional-dependencies] -doc = ["docutils", "fontconfig", "freetype", "graphviz", "myst-nb", "numpydoc", "sphinx", "sphinx-argparse>=0.4", "sphinx-design", "sphinx_rtd_theme"] +doc = ["docutils", "fontconfig", "freetype", "graphviz", "myst-nb", "numpydoc", "sphinx", "sphinx-argparse>=0.4", "sphinxcontrib-bibtex", "sphinx-design", "sphinx_rtd_theme"] all = ["cartopy", "gdal", "h5py", "ipyleaflet", "ipywidgets", "jplephem", "matplotlib", "mpi4py", "notebook", "pandas", "pyyaml"] dev = ["flake8", "pytest>=4.6", "pytest-cov", "oct2py", "boto3"] diff --git a/test/test_download_and_read.py b/test/test_download_and_read.py index 08e0716e..66d62833 100644 --- a/test/test_download_and_read.py +++ b/test/test_download_and_read.py @@ -63,7 +63,6 @@ import pyTMD.compute import pyTMD.predict import pyTMD.utilities -import pyTMD.check_points import pyTMD.ellipse import pyTMD.solve import timescale.time @@ -413,7 +412,7 @@ def test_read_CATS2008(self, ny=2026, nx=1663): def test_check_CATS2008(self): lons = np.zeros((10)) + 178.0 lats = -45.0 - np.arange(10)*5.0 - obs = pyTMD.check_points(lons, lats, DIRECTORY=filepath, + obs = pyTMD.compute.tide_masks(lons, lats, DIRECTORY=filepath, MODEL='CATS2008', EPSG=4326) exp = np.array([False, False, False, False, True, True, True, True, False, False]) diff --git a/test/test_equilibrium_tide.py b/test/test_equilibrium_tide.py index 663d49f8..519459ee 100644 --- a/test/test_equilibrium_tide.py +++ b/test/test_equilibrium_tide.py @@ -26,20 +26,7 @@ def test_equilibrium_tide(TYPE): """ Test the computation of the long-period equilibrium tides from the summation of fifteen tidal spectral lines from - Cartwright-Tayler-Edden tables [1]_ [2]_ - - References - ---------- - .. [1] D. E. Cartwright and R. J. Tayler, - "New Computations of the Tide-generating Potential," - *Geophysical Journal of the Royal Astronomical Society*, - 23(1), 45--73. (1971). `doi: 10.1111/j.1365-246X.1971.tb01803.x - `_ - .. [2] D. E. Cartwright and A. C. Edden, - "Corrected Tables of Tidal Harmonics," - *Geophysical Journal of the Royal Astronomical Society*, - 33(3), 253--264, (1973). `doi: 10.1111/j.1365-246X.1973.tb03420.x - `_ + Cartwright-Tayler-Edden tables """ # create a test dataset for data type if (TYPE == 'drift'): @@ -112,19 +99,6 @@ def test_equilibrium_tide(TYPE): def test_node_tide(): """ Test the computation of the equilibrium node tides - - References - ---------- - .. [1] D. E. Cartwright and R. J. Tayler, - "New Computations of the Tide-generating Potential," - *Geophysical Journal of the Royal Astronomical Society*, - 23(1), 45--73. (1971). `doi: 10.1111/j.1365-246X.1971.tb01803.x - `_ - .. [2] D. E. Cartwright and A. C. Edden, - "Corrected Tables of Tidal Harmonics," - *Geophysical Journal of the Royal Astronomical Society*, - 33(3), 253--264, (1973). `doi: 10.1111/j.1365-246X.1973.tb03420.x - `_ """ # create a test dataset for data type # number of data points diff --git a/test/test_fes_predict.py b/test/test_fes_predict.py index e562f7f0..b19db5cb 100644 --- a/test/test_fes_predict.py +++ b/test/test_fes_predict.py @@ -40,10 +40,10 @@ import numpy as np import pyTMD.io import pyTMD.io.model +import pyTMD.compute import pyTMD.utilities import pyTMD.predict import pyTMD.arguments -import pyTMD.check_points import timescale.time # current file path @@ -87,7 +87,7 @@ def download_model(aws_access_key_id,aws_secret_access_key,aws_region_name): def test_check_FES2014(): lons = np.zeros((10)) + 178.0 lats = -45.0 - np.arange(10)*5.0 - obs = pyTMD.check_points(lons, lats, DIRECTORY=filepath, + obs = pyTMD.compute.tide_masks(lons, lats, DIRECTORY=filepath, MODEL='FES2014', GZIP=True, EPSG=4326) exp = np.array([True, True, True, True, True, True, True, True, False, False]) diff --git a/test/test_perth3_read.py b/test/test_perth3_read.py index b2ffd83d..d65d171b 100644 --- a/test/test_perth3_read.py +++ b/test/test_perth3_read.py @@ -48,7 +48,6 @@ import pyTMD.utilities import pyTMD.compute import pyTMD.predict -import pyTMD.check_points import timescale.time # current file path @@ -233,7 +232,7 @@ def test_compare_GOT47(METHOD): def test_check_GOT47(): lons = np.zeros((10)) + 178.0 lats = -45.0 - np.arange(10)*5.0 - obs = pyTMD.check_points(lons, lats, DIRECTORY=filepath, + obs = pyTMD.compute.tide_masks(lons, lats, DIRECTORY=filepath, MODEL='GOT4.7', GZIP=True, EPSG=4326) exp = np.array([True, True, True, True, True, True, True, True, False, False])