tsutterley · tsutterley · Jan 13, 2024 · Dec 22, 2023 · Dec 22, 2023 · Dec 23, 2023
diff --git a/doc/source/api_reference/arguments.rst b/doc/source/api_reference/arguments.rst
@@ -3,19 +3,31 @@ arguments
 =========
 
 - Calculates the nodal corrections for tidal constituents
-- Based on Richard Ray's ``ARGUMENTS`` fortran subroutine
+- Originally based on Richard Ray's ``ARGUMENTS`` fortran subroutine
 
 Calling Sequence
 ----------------
 
 .. code-block:: python
 
     import pyTMD.arguments
-    pu,pf,G = pyTMD.arguments(MJD, constituents,
+    pu,pf,G = pyTMD.arguments.arguments(MJD, constituents,
         deltat=DELTAT, corrections=CORRECTIONS)
 
 `Source code`__
 
 .. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/arguments.py
 
-.. autofunction:: pyTMD.arguments
+.. autofunction:: pyTMD.arguments.arguments
+
+.. autofunction:: pyTMD.arguments.minor_arguments
+
+.. autofunction:: pyTMD.arguments.doodson_number
+
+.. autofunction:: pyTMD.arguments._arguments_table
+
+.. autofunction:: pyTMD.arguments._minor_table
+
+.. autofunction:: pyTMD.arguments._to_doodson_number
+
+.. autofunction:: pyTMD.arguments._from_doodson_number
diff --git a/doc/source/api_reference/astro.rst b/doc/source/api_reference/astro.rst
@@ -2,8 +2,7 @@
 astro
 =====
 - Astronomical and nutation routines
-- Computes the basic astronomical mean longitudes: `S`, `H`, `P`, `N` and `PP`
-- Computes astronomical phase angles for the sun and moon:  `S`, `H`, `P`, `TAU`, `ZNS` and `PS`
+- Computes the basic astronomical mean longitudes and other fundamental orbital parameters
 - Computes the solar and lunar positions in Earth-Centered Earth-Fixed (ECEF) coordinates
 
 Calling Sequence
@@ -24,7 +23,7 @@ Calling Sequence
 
 .. autofunction:: pyTMD.astro.mean_longitudes
 
-.. autofunction:: pyTMD.astro.phase_angles
+.. autofunction:: pyTMD.astro.doodson_arguments
 
 .. autofunction:: pyTMD.astro.delaunay_arguments
 

diff --git a/doc/source/api_reference/convert_crs.rst b/doc/source/api_reference/convert_crs.rst
diff --git a/doc/source/api_reference/crs.rst b/doc/source/api_reference/crs.rst
@@ -0,0 +1,16 @@
+===
+crs
+===
+
+Coordinates Reference System (CRS) routines
+
+`Source code`__
+
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/crs.py
+
+General Attributes and Methods
+==============================
+
+.. autoclass:: pyTMD.crs
+   :members:
+   :private-members:
diff --git a/doc/source/api_reference/solve.rst b/doc/source/api_reference/solve.rst
@@ -0,0 +1,19 @@
+=====
+solve
+=====
+
+- Routines for estimating the harmonic constants for ocean tides
+
+Calling Sequence
+----------------
+
+.. code-block:: python
+
+    import pyTMD.solve
+    amp, phase = pyTMD.solve.constants(time, h, con)
+
+`Source code`__
+
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/solve.py
+
+.. autofunction:: pyTMD.solve.constants
diff --git a/doc/source/getting_started/Background.rst b/doc/source/getting_started/Background.rst
@@ -8,7 +8,7 @@ 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 <https://www.esr.org/data-products/antarctic_tg_database/ocean-tide-and-ocean-tide-loading/>`_.
-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 [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 [Doodson1921]_ [Meeus1998]_.
 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.
 
@@ -21,7 +21,7 @@ or 3) an unconstrained hydrodynamic model [Stammer2014]_.
 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]_ [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 [Agnew2015]_ [Doodson1921]_ [Meeus1998]_ [Montenbruck1989]_.
 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]_.
 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 <https://ssd.jpl.nasa.gov/planets/orbits.html>`_.
@@ -81,6 +81,30 @@ As opposed to simple vertical offsets, changing the terrestial reference system
 This involves converting from a geographic coordinate system into a Cartesian coordinate system.
 Within ``pyTMD``, solid Earth tides are calculated using ECEF coordinates, and pole tides are calculated using geocentric coordinates.
 
+Nutation is the periodic oscillation of the Earth's rotation axis around its mean position.
+Nutation is often split into two components, the nutation in longitude and the nutation in obliquity.
+The angle between the equator and the orbital plane of Earth around the Sun (the ecliptic) defines the inclination of the Earth's rotation axis (obliquity of the ecliptic).
+
+Time
+####
+
+The Julian Day (JD) is the continuous count of days starting at noon on January 1, 4713 B.C (-4712-01-01T12:00:00).
+The Modified Julian Day (MJD) differs from the Julian Day by reducing the number of digits for modern periods, and by beginning at midnight.
+The MJD is calculated from the Julian Day by
+
+.. math::
+    :label: 4
+
+    MJD = JD - 2400000.5
+
+The start of the Modified Julian Day calendar is 1858-11-17T00:00:00.
+Time in Julian centuries (36525 days) are calculated relative to noon on January 1, 2000 (2000-01-01T12:00:00).
+
+.. math::
+    :label: 5
+
+    T = \frac{JD - 2451545.0}{36525}
+
 References
 ##########
 
@@ -90,6 +114,8 @@ References
 
 .. [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 <https://doi.org/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 <https://doi.org/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 <https://doi.org/10.1029/97JB01515>`_

diff --git a/doc/source/getting_started/Getting-Started.rst b/doc/source/getting_started/Getting-Started.rst
@@ -3,7 +3,7 @@ Getting Started
 ===============
 
 This documentation is intended to explain how to compute ocean, solid Earth, load and pole tide variations using the set of ``pyTMD`` programs.
-See the `background material <./Background.html>`_ for more information on the theory and methods used in ``pyTMD``.
+See the `background material <./Background.html>`_ and `glossary <./Glossary.html>`_ for more information on the theory and methods used in ``pyTMD``.
 
 Tide Model Formats
 ##################
@@ -43,15 +43,15 @@ Presently, the following models and their directories parameterized within ``pyT
 
 - TOPEX/POSEIDON global tide models [Egbert2002]_
 
+    * TPXO7.2: ``<path_to_tide_models>/TPXO7.2_tmd/``
+    * TPXO7.2_load: ``<path_to_tide_models>/TPXO7.2_load/``
+    * `TPXO8-atlas <https://www.tpxo.net/tpxo-products-and-registration>`_: ``<path_to_tide_models>/tpxo8_atlas/``
+    * `TPXO9.1 <https://www.tpxo.net/tpxo-products-and-registration>`_: ``<path_to_tide_models>/TPXO9.1/DATA/``
     * `TPXO9-atlas <https://www.tpxo.net/tpxo-products-and-registration>`_: ``<path_to_tide_models>/TPXO9_atlas/``
     * `TPXO9-atlas-v2 <https://www.tpxo.net/tpxo-products-and-registration>`_: ``<path_to_tide_models>/TPXO9_atlas_v2/``
     * `TPXO9-atlas-v3 <https://www.tpxo.net/tpxo-products-and-registration>`_: ``<path_to_tide_models>/TPXO9_atlas_v3/``
     * `TPXO9-atlas-v4 <https://www.tpxo.net/tpxo-products-and-registration>`_: ``<path_to_tide_models>/TPXO9_atlas_v4/``
     * `TPXO9-atlas-v5 <https://www.tpxo.net/tpxo-products-and-registration>`_: ``<path_to_tide_models>/TPXO9_atlas_v5/``
-    * `TPXO9.1 <https://www.tpxo.net/tpxo-products-and-registration>`_: ``<path_to_tide_models>/TPXO9.1/DATA/``
-    * `TPXO8-atlas <https://www.tpxo.net/tpxo-products-and-registration>`_: ``<path_to_tide_models>/tpxo8_atlas/``
-    * TPXO7.2: ``<path_to_tide_models>/TPXO7.2_tmd/``
-    * TPXO7.2_load: ``<path_to_tide_models>/TPXO7.2_load/``
 
 - Global Ocean Tide models [Ray1999]_
 

diff --git a/doc/source/getting_started/Glossary.rst b/doc/source/getting_started/Glossary.rst
@@ -0,0 +1,108 @@
+========
+Glossary
+========
+
+.. glossary::
+
+    Anomaly
+        angular distance between the perihelion and the position of a celestial body
+
+    Aphelion
+        point of an orbit where a celestial body is furthest from the sun
+
+    Ascending Node
+        point of an orbit where a celestial body intersects the ecliptic, and the latitude coordinate is increasing
+
+    Barycenter
+        center of mass of a system of bodies
+
+    Body Tide
+        see :term:`Solid Earth Tide`
+
+    Chandler Wobble
+        small, semi-periodic deviations in the motion of the pole of rotation
+
+    Constituent
+        tidal oscillation corresponding with a specific periodic motion of the Earth, Sun and Moon
+
+    Descending Node
+        point of an orbit where a celestial body intersects the ecliptic, and the latitude coordinate is decreasing
+
+    Diurnal Tide
+        tidal oscillations with a near-daily period
+
+    Ecliptic
+        plane of the orbit of the Earth around the sun
+
+    Ephemeris
+        table of positions and velocities of a celestial body at given instances in time
+
+    Ephemerides
+        plural of :term:`Ephemeris`
+
+    Epoch
+        fixed point in time used as a reference value
+
+    Load Tide
+        elastic deformation of the solid Earth due to ocean and atmospheric tides
+
+    Long Period Tide
+        tidal oscillations with periods much greater than one day
+
+    Love and Shida Numbers
+        dimensionless parameters relating the vertical (`h`), horizontal (`l`) and gravitational (`k`) elastic responses to tidal loading
+
+    Mean Tide
+        model with both direct and indirect permanent tidal effects retained
+
+    Nutation
+        short-period oscillations in the motion of the pole of rotation
+
+    Obliquity
+        angle between the equatorial and orbital planes
+
+    Ocean Tide
+        periodic movement in the level of sea surface due to gravitational and rotational forces
+
+    Perigee
+        point of an orbit where a celestial body is closest to Earth
+
+    Perihelion
+        point of an orbit where a celestial body is closest to the sun
+
+    Period
+        time it takes to make one complete revolution
+
+    Permanent Tide
+        permanent deformation of the Earth caused by the presence of the Sun and the Moon
+
+        see :term:`Mean Tide`, :term:`Tide-Free`, and :term:`Zero Tide`
+
+    Pole Tide
+        apparent tide due to variations in the Earth's figure axis about its mean
+
+    Semi-diurnal Tide
+        tidal oscillations with an approximate half-day period
+
+    Solid Earth Tide
+        deformation of the solid Earth due to gravitational forces
+
+    Tidal Current
+        horizontal movement of water due to periodic forces
+
+    Tidal Species
+        classification of tidal constituents based on period
+
+        see :term:`Semi-diurnal Tide`, :term:`Diurnal Tide`, and :term:`Long Period Tide`
+
+    Tidal Stream
+        see :term:`Tidal Current`
+
+    Tide-Free
+        model with direct and indirect permanent tidal effects removed
+
+    Vertical Datum
+        reference coordinate surface used for vertical positions
+
+    Zero Tide
+        model with permanent direct tidal effects removed, but indirect loading effects retained
diff --git a/doc/source/getting_started/Install.rst b/doc/source/getting_started/Install.rst
@@ -34,7 +34,7 @@ the `Python Package Index (pypi) <https://pypi.org/project/pyTMD/>`_,
 and from `conda-forge <https://anaconda.org/conda-forge/pytmd>`_.
 
 
-The simplest installation for most users will likely be using ``conda``:
+The simplest installation for most users will likely be using ``conda`` or ``mamba``:
 
 .. code-block:: bash
 

diff --git a/doc/source/getting_started/Resources.rst b/doc/source/getting_started/Resources.rst
@@ -29,6 +29,7 @@ Software
 
 - `ESR Tide Model Driver (TMD) Matlab Toolbox <https://www.esr.org/research/polar-tide-models/tmd-software/>`_
 - `TMD Matlab Toolbox Repository <https://github.com/EarthAndSpaceResearch/TMD_Matlab_Toolbox_v2.5>`_
+- `TMD3 Matlab Toolbox Repository <https://github.com/chadagreene/Tide-Model-Driver>`_
 - `Antarctic Tide Gauge (AntTG) Database Tools <https://github.com/EarthAndSpaceResearch/AntTG_Database_Tools>`_
 - `OSU Tidal Prediction Software (OTPS) <https://www.tpxo.net/otps>`_
 - `FES (Finite Element Solution) tide model software <https://github.com/CNES/aviso-fes>`_

diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -12,6 +12,7 @@ ocean, load, solid Earth and pole tides
     getting_started/Install.rst
     getting_started/Getting-Started.rst
     getting_started/Background.rst
+    getting_started/Glossary.rst
     getting_started/Contributing.rst
     getting_started/Code-of-Conduct.rst
     getting_started/Resources.rst
@@ -34,7 +35,7 @@ ocean, load, solid Earth and pole tides
     api_reference/check_points.rst
     api_reference/compute_tide_corrections.rst
     api_reference/constants.rst
-    api_reference/convert_crs.rst
+    api_reference/crs.rst
     api_reference/ellipse.rst
     api_reference/eop.rst
     api_reference/interpolate.rst
@@ -46,6 +47,7 @@ ocean, load, solid Earth and pole tides
     api_reference/io/model.rst
     api_reference/io/ocean_pole_tide.rst
     api_reference/predict.rst
+    api_reference/solve.rst
     api_reference/spatial.rst
     api_reference/time.rst
     api_reference/utilities.rst