Vesion 4.13

Makefile

@@ -126,7 +126,7 @@
 ###############################################################################
 
 # The VERSION number is used only for generating the man pages
-VERSION = 4.12
+VERSION = 4.13
 
 LIBNAME = SHTOOLS
 LIBNAMEMP = SHTOOLS-mp

binder/environment.yml

@@ -3,5 +3,5 @@ channels:
     - conda-forge
 dependencies:
     - python=3.12
-    - pyshtools>=4.12.0
+    - pyshtools>=4.13.0
     - palettable>=3.3

docs/Gemfile.lock

@@ -1,7 +1,7 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.1.3.2)
+    activesupport (7.1.3.4)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
@@ -11,19 +11,19 @@ GEM
       minitest (>= 5.1)
       mutex_m
       tzinfo (~> 2.0)
-    addressable (2.8.6)
-      public_suffix (>= 2.0.2, < 6.0)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
     base64 (0.2.0)
-    bigdecimal (3.1.7)
+    bigdecimal (3.1.8)
     coffee-script (2.4.1)
       coffee-script-source
       execjs
     coffee-script-source (1.12.2)
     colorator (1.1.0)
     commonmarker (0.23.10)
-    concurrent-ruby (1.2.3)
+    concurrent-ruby (1.3.3)
     connection_pool (2.4.1)
-    dnsruby (1.71.0)
+    dnsruby (1.72.1)
       simpleidn (~> 0.2.1)
     drb (2.2.1)
     em-websocket (0.5.3)
@@ -33,11 +33,13 @@ GEM
       ffi (>= 1.15.0)
     eventmachine (1.2.7)
     execjs (2.9.1)
-    faraday (2.9.0)
+    faraday (2.10.0)
       faraday-net_http (>= 2.0, < 3.2)
+      logger
     faraday-net_http (3.1.0)
       net-http
-    ffi (1.16.3)
+    ffi (1.17.0-arm64-darwin)
+    ffi (1.17.0-x86_64-darwin)
     forwardable-extended (2.6.0)
     gemoji (4.1.0)
     github-pages (231)
@@ -95,7 +97,7 @@ GEM
       activesupport (>= 2)
       nokogiri (>= 1.4)
     http_parser.rb (0.8.0)
-    i18n (1.14.4)
+    i18n (1.14.5)
       concurrent-ruby (~> 1.0)
     jekyll (3.9.5)
       addressable (~> 2.4)
@@ -213,30 +215,32 @@ GEM
     listen (3.9.0)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.6.0)
     mercenary (0.3.6)
     minima (2.5.1)
       jekyll (>= 3.5, < 5.0)
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
-    minitest (5.22.3)
+    minitest (5.24.1)
     mutex_m (0.2.0)
     net-http (0.4.1)
       uri
-    nokogiri (1.16.2-arm64-darwin)
+    nokogiri (1.16.6-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.16.2-x86_64-darwin)
+    nokogiri (1.16.6-x86_64-darwin)
       racc (~> 1.4)
     octokit (4.25.1)
       faraday (>= 1, < 3)
       sawyer (~> 0.9)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    public_suffix (5.0.4)
-    racc (1.7.3)
+    public_suffix (5.1.1)
+    racc (1.8.0)
     rb-fsevent (0.11.2)
-    rb-inotify (0.10.1)
+    rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rexml (3.2.6)
+    rexml (3.3.1)
+      strscan
     rouge (3.30.0)
     rubyzip (2.3.2)
     safe_yaml (1.0.5)
@@ -248,17 +252,14 @@ GEM
     sawyer (0.9.2)
       addressable (>= 2.3.5)
       faraday (>= 0.17.3, < 3)
-    simpleidn (0.2.1)
-      unf (~> 0.1.4)
+    simpleidn (0.2.3)
+    strscan (3.1.0)
     terminal-table (1.8.0)
       unicode-display_width (~> 1.1, >= 1.1.1)
     typhoeus (1.4.1)
       ethon (>= 0.9.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unf (0.1.4)
-      unf_ext
-    unf_ext (0.0.9.1)
     unicode-display_width (1.8.0)
     uri (0.13.0)
     webrick (1.8.1)

docs/_data/sidebars/fortran_sidebar.yml

@@ -3,7 +3,7 @@
 entries:
 - title: sidebar
   product: SHTOOLS
-  version: '4.12'
+  version: '4.13'
   folders:
 
   - title:

docs/_data/sidebars/mydoc_sidebar.yml

@@ -3,7 +3,7 @@
 entries:
 - title: sidebar
   product: pyshtools
-  version: '4.12'
+  version: '4.13'
   folders:
 
   - title:

docs/pages/fortran/fdoc/normalgravity.md

@@ -9,7 +9,7 @@ toc: false
 editdoc: fdoc
 ---
 
-Calculate the normal gravity on a flattened ellipsoid in geocentric coordinates using the formula of Somigliana.
+Calculate the normal gravity on an ellipsoid or sphere using geocentric coordinates.
 
 ## Usage
 
@@ -30,14 +30,18 @@ Calculate the normal gravity on a flattened ellipsoid in geocentric coordinates
 :   The angular rotation rate of the planet.
 
 `a` : input, real(dp)
-:   The semi-major axis of the flattened ellipsoid on which the normal gravity is computed.
+:   The semi-major axis of the ellipsoid on which the normal gravity is computed.
 
 `b` : input, real(dp)
-:   The semi-minor axis of the flattened ellipsoid on which the normal gravity is computed.
+:   The semi-minor axis of the ellipsoid on which the normal gravity is computed.
 
 ## Description
 
-`NormalGravity` will calculate the magnitude of the predicted gravity (in m/s^2) on a flattened ellipsoid using Somigliana's formula. The latitude is input in geocentric coordinates in degrees, which is later converted to geodetic coordinates in the routine for use with Somigliana's formula. Other input parameters include `gm`, the product of the gravitational constant and the planet's mass, and the semi-major and semi-minor axes of the planet, `a` and `b`, respectively. For further details, see sections 2.7 and 2.8 of Physical Geodesy (Hofmann-Wellenhof and Moritz).
+`NormalGravity` will compute the magnitude of the total gravity (gravitation and centrifugal) on the surface of a rotating ellipsoid (in m/s^2).  The latitude is input in geocentric coordinates in degrees.
+
+For a rotating ellipsoid, the surface corresponds to a constant potential, and the gravity vector is normal to the surface. The normal gravity is computed using Somigliana's formula, as taken from Physical Geodesy (Hofmann-Wellenhof and Moritz, 2nd ed., sections 2.7 and 2.8). In this routine, the geodetic latitude is computed internally from the input geocentric latitude.
+
+For the case of a sphere (a is equal to b), the normal gravity is defined as the magnitude of the sum of the normal gravitation (GM/r^2) and the centrifugal gravity. For a rotating sphere, the surface does not correspond to a constant potential and the gravity vector is not normal to the surface.
 
 ## References
 

docs/pages/fortran/fdoc/shbiasadmitcorr.md

@@ -13,7 +13,7 @@ Calculate the expected multitaper admittance and correlation spectra associated
 
 ## Usage
 
-call SHAdmitCorr (`sgt`, `sgg`, `stt`, `lmax`, `tapers`, `lwin`, `k`, `admit`, `corr`, `mtdef`, `taper_wt`, `exitstatus`)
+call SHBiasAdmitCorr (`sgt`, `sgg`, `stt`, `lmax`, `tapers`, `lwin`, `k`, `admit`, `corr`, `mtdef`, `taper_wt`, `exitstatus`)
 
 ## Parameters
 
@@ -38,10 +38,10 @@ call SHAdmitCorr (`sgt`, `sgg`, `stt`, `lmax`, `tapers`, `lwin`, `k`, `admit`, `
 `k` : input, integer(int32)
 :   The number of localizing windows to use. Only the first `k` columns of `tapers` will be employed, which corresponds to the `k` best-concentrated localizing windows.
 
-`admit` : output, real(dp), dimension (`lmax`-`lwin`+1) 
+`admit` : output, real(dp), dimension (`lmax`-`lwin`+1)
 :   The biased admittance spectrum obtained using the localized (cross-)power spectra of Sgt and Stt.
 
-`corr` : output, real(dp), dimension (`lmax`-`lwin`+1) 
+`corr` : output, real(dp), dimension (`lmax`-`lwin`+1)
 :   The biased correlation spectrum obtained using the localized (cross-)power spectra of Sgt, Stt, and Sgg.
 
 `mtdef` : optional, input, integer(int32), default = 1
@@ -65,9 +65,9 @@ The default is to apply equal weights to each individual windowed estimate of th
 
 Wieczorek, M. A. and F. J. Simons, Minimum-variance multitaper spectral estimation on the sphere, J. Fourier Anal. Appl., 13, doi:10.1007/s00041-006-6904-1, 665-692, 2007.
 
-Simons, F. J., F. A. Dahlen and M. A. Wieczorek, Spatiospectral concentration on the sphere, SIAM Review, 48, 504-536, doi:10.1137/S0036144504445765, 2006. 
+Simons, F. J., F. A. Dahlen and M. A. Wieczorek, Spatiospectral concentration on the sphere, SIAM Review, 48, 504-536, doi:10.1137/S0036144504445765, 2006.
 
-Wieczorek, M. A. and F. J. Simons, Localized spectral analysis on the sphere, 
+Wieczorek, M. A. and F. J. Simons, Localized spectral analysis on the sphere,
 Geophys. J. Int., 162, 655-675.
 
 ## See also

docs/pages/fortran/fdoc/shrotatecoef.md

@@ -53,18 +53,20 @@ The rotation of a coordinate system or body can be viewed in two complementary w
 (II) Rotation about the initial y axis by beta.
 (III) Rotation about the initial z axis by alpha.
 
-The rotations can further be viewed either as a rotation of the coordinate system or the physical body. For a rotation of the coordinate system without rotation of the physical body, use 
+The rotations can further be viewed either as a rotation of the coordinate system or the physical body. For a rotation of the coordinate system without rotation of the physical body, use
 
 `x(alpha, beta, gamma)`.
 
-For a rotation of the physical body without rotation of the coordinate system, use 
+For a rotation of the physical body without rotation of the coordinate system, use
 
 `x(-gamma, -beta, -alpha)`.
 
 To perform the inverse transform of `x(alpha, beta, gamma)`, use `x(-gamma, -beta, -alpha)`.
 
 Note that this routine uses the "y convention", where the second rotation is with respect to the new y axis. If alpha, beta, and gamma were orginally defined in terms of the "x convention", where the second rotation was with respect to the newx axis, the Euler angles according to the y convention would be `alpha_y=alpha_x-pi/2`, `beta_x=beta_y`, and `gamma_y=gamma_x+pi/2`.
 
+This routine is accurate to about spherical harmonic degree 1200.
+
 
 ## See also
 

docs/pages/fortran/fdoc/shrotaterealcoef.md

@@ -53,11 +53,11 @@ The rotation of a coordinate system or body can be viewed in two complementary w
 (II) Rotation about the initial y axis by beta.
 (III) Rotation about the initial z axis by alpha.
 
-The rotations can further be viewed either as a rotation of the coordinate system or the physical body. For a rotation of the coordinate system without rotation of the physical body, use 
+The rotations can further be viewed either as a rotation of the coordinate system or the physical body. For a rotation of the coordinate system without rotation of the physical body, use
 
 `x(alpha, beta, gamma)`.
 
-For a rotation of the physical body without rotation of the coordinate system, use 
+For a rotation of the physical body without rotation of the coordinate system, use
 
 `x(-gamma, -beta, -alpha)`.
 
@@ -67,6 +67,8 @@ Note that this routine uses the "y convention", where the second rotation is wit
 
 This routine first converts the real coefficients to complex form using `SHrtoc`. Then the coefficients are converted to indexed form using `SHCilmToCindex`, these are sent to `SHRotateCoef`, the result if converted back to `cilm` complex form using `SHCindexToCilm`, and these are finally converted back to real form using `SHctor`.
 
+This routine is accurate to about spherical harmonic degree 1200.
+
 ## See also
 
 [djpi2](djpi2.html), [shrotatecoef](shrotatecoef.html), [shctor](shctor.html), [shrtoc](shrtoc.html), [shcilmtocindex](shcilmtocindex.html), [shcindextocilm](shcindextocilm.html)

docs/pages/fortran/fortran-release-notes-v4.md

@@ -7,6 +7,53 @@ summary:
 toc: true
 folder: fortran
 ---
+## Version 4.13.0
+
+**More constants**
+* Added mean orbital elements (a, e, i) for all of the planets, Pluto, and the asteroids in the constants submodule.
+* Added the mean orbital elements of the Galilean satellites, Titan, and Enceladus (including the tilt with respect to the Laplace plane).
+* Added constants for the Sun, Pluto, and Charon.
+* Added `orbit_period` and `orbit_angular_velocity`, which are estimated using Kepler's third law, the mass of the Sun, the mass of the body, and the semimajor axis.
+* Renamed the `omega` constant to `angular_velocity`.
+* Divided the web documentation page "Constants and Datasets" into two separate web pages.
+
+**Datasets**
+* Added gravity datasets of Jupiter (`Kaspi2023_gravity`), Saturn (`Jacobson2022_gravity`), Uranus (`Jacobson2014_gravity`), and Neptune (`Jacobson2009_gravity`).
+* Added two shape models of Psyche: `Shepard2017`  and `Shepard2021`.
+* Added a new ultrahigh degree principal-axis shape model of the Moon `LDEM_pa`, and moved the previous `LOLA_pa` shape model to historical.
+* Allow passing a negative `lmax` to get the maximum resolution model (when several resolution models are available).
+
+**Better least squares**
+* The fortran weighted least squares routine in `SHExpandLSQ` has been modified and is now just as fast as the method without weights. LAPACK DGELS is used to perform the inversion after appropriately scaling the data kernel matrix and input data.
+* Added a new fortran routine `LSQ_G` and python wrapped function to precompute the data kernel matrix.
+* The fortran routine `SHExpandLSQ` now accepts as an optional argument a precomputed data matrix kernel, which offers some improvement in speed for high degrees.
+* Added python wrapped functions `SHExpandLSQ_G` and `SHExpandWLSQ_G` that require passing the data kernel matrix.
+* Added a new pure python routine `shlsq` that is a convenience function for calling the various fortran routines with or without data weights, and with or without the data kernel matrix. This function only works with real spherical harmonics.
+* Added a new class method `SHCoeffs.from_least_squares()` that allows one to initialize an `SHCoeffs` instance by performing a least squares inversion of irregularly space data.
+
+**Change of normal gravity for rotating spheres**
+The normal gravity is defined as the magnitude of the total gravity (gravitation + centrifugal) on the surface of a reference ellipsoid. Previously, the fortran `NormalGravity` routine set the centrifugal term to zero when the reference ellipsoid was a sphere. For the case of a sphere, it should be noted that the surface does not correspond to an equipotential surface, and the gravity vector is not normal to the surface.
+
+**Packaging**
+We have migrated from using multibuild and Appveyor to cibuildwheel to build our wheels for distribution on pypi.org. We are currently distributing wheels for macOS (intel and Apple silicon), windows, and linux (intel and ARM).
+
+**Other changes**
+* Replaced the undefined attribute `self._vii_units` in `Tensor.to_xarray()` by `self.units`, and added a demo using the fixed `Tensor.to_xarray` method in the tutorial notebook `gravity-and-magnetic-fields.ipynb`.
+* `isinstance` is now used when comparing python types.
+* `except Exception` is now used to avoid a bare python except.
+* Improved `setuptools_scm` version detection when working with non-git-versioned projects.
+* Improved handling of the class attribute `name`. This attribute was added to classes that did not previously define `name`, and every method that returns a class instance now has the ability to set the name of the new instance. When creating grids from coefficients, the name of the grid class is inherited from the name of the coefficient class.
+* Added the option to rotate the ellipsoid generated by `SHGrid.from_ellipsoid()` about the z axis by the angle `alpha`.
+* Added `legend_title`, `legend_titlesize`, and `legend_fontsize` arguments to all `plot_spectrum()` and `plot_cross_spectrum()` methods.
+* Allow to pass dictionaries of optional arguments for all methods that previously accepted the generic `**kwargs` catch all. For the plotting routines, this allows to specify separate optional parameters for `numpy.plot()`, `numpy.errorbar()`, and `numpy.legend()`.
+* Replaced the deprecated matplotlib `cm.get_cmap()` method with the pyplot method `get_cmap()`.
+* Fixed a bug when using `SHGrid.plotgmt()` with `cmap_scale='log'` but without setting `cb_tick_interval`. The default is set to use `cb_tick_interval=1` when left unspecified.
+* Updated the fortran documentation to note the accuracy limitations of the `SHRotate` routines at degrees close to 1200.
+
+**Reference**
+
+M. A. Wieczorek, M. Meschede, A. Broquet, T. Brugere, A. Corbin, EricAtORS, A. Hattori, A. Kalinin, J. Kohler, D. Kutra, K. Leinweber, P. Lobo, J. Maia, E. Mentzer, D. Minton, I. Oshchepkov, P.-L. Phan, O. Poplawski, M. Reinecke, E. Sales de Andrade, E. Schnetter, S. Schröder, D. Shin, J. Sierra, A. Vasishta, A. Walker, xoviat, B. Xu (2024). SHTOOLS: Version 4.13, Zenodo, doi:[10.5281/zenodo.592762](https://doi.org/10.5281/zenodo.592762).
+
 
 ## Version 4.12
 

docs/pages/mydoc/pydoc/pynormalgravity.md

@@ -9,7 +9,7 @@ toc: false
 editdoc: pydoc
 ---
 
-Calculate the normal gravity on a flattened ellipsoid in geocentric coordinates using the formula of Somigliana.
+Calculate the normal gravity on an ellipsoid or sphere using geocentric coordinates.
 
 ## Usage
 
@@ -39,7 +39,11 @@ b : float
 
 ## Description
 
-NormalGravity will calculate the magnitude of the predicted gravity (in m/s^2) on a flattened ellipsoid using Somigliana's formula. The latitude is input in geocentric coordinates in degrees, which is later converted to geodetic coordinates in the routine for use with Somigliana's formula. Other input parameters include gm, the product of the gravitational constant and the planet's mass, and the semi-major and semi-minor axes of the planet, a and b, respectively. For further details, see sections 2.7 and 2.8 of Physical Geodesy (Hofmann-Wellenhof and Moritz).
+NormalGravity will compute the magnitude of the total gravity (gravitation and centrifugal) on the surface of a rotating ellipsoid (in m/s^2).  The latitude is input in geocentric coordinates in degrees.
+
+For a rotating ellipsoid, the surface corresponds to a constant potential, and the gravity vector is normal to the surface. The normal gravity is computed using Somigliana's formula, as taken from Physical Geodesy (Hofmann-Wellenhof and Moritz, 2nd ed., sections 2.7 and 2.8). In this routine, the geodetic latitude is computed internally from the input geocentric latitude.
+
+For the case of a sphere (a is equal to b), the normal gravity is defined as the magnitude of the sum of the normal gravitation (GM/r^2) and the centrifugal gravity. For a rotating sphere, the surface does not correspond to a constant potential and the gravity vector is not normal to the surface.
 
 ## References