SHTOOLS Versions Save

Version 4.12.2

New Datasets!

• Added new ultra-high degree shape models of the Moon in both principal axis and mean Earth/polar axis coordinate systems (LOLA_shape and LOLA_shape_pa) and moved MoonTopo2600p to historical.
• Added new ultra-high degree shape model of Mars (MOLA_shape) and moved MarsTopo2600 and MarsTopo719 to historical.
• Added a new ultra-high degree shape model of Mercury based on the USGS SPG DTM (USGS_SPG_shape).
• Added a new ultra-high degree shape model of Vesta based on the DLR SPG DTM (DLR_SPG_shape).
• Added a new ultra-high degree shape model of Ceres based on the DLR SPG DTM (DLR_SPG_shape) and a high-degree shape model based on the JPL SPC DTM (JPL_SPG_shape).
• Added historical degree-2 gravity models of Io, Europa, Ganymede, and Callisto derived from data collected by the Galileo mission.
• Added two shape models of Titan (Mitri2014_shape and Corlies2017_shape) and a degree 5 gravity model of Durante et al. 2019 (Durante2019_gravity).
• Added two gravity models of Enceladus (Iess2014_gravity and Park2024_gravity) and a high-degree shape model based on the JPL SPC DTM (JPL_SPG_shape).
• Added two shape models of Eros (NLR_shape and SPC_shape) and the JPL gravity model JGE15A01.
• Updated all constants to reflect the most recent datasets, and added new constant modules for Eros, Io, Europa, Ganymede, Callisto, Titan and Enceladus.
• Added the property volume_equivalent_radius and volume to the constants modules.
• Renamed the constant attributes density to mean_density and g0 to gravity_mean_radius.
• Updated all datasets that download from zenodo to use the Pooch DOIDownloader.

Bug fixes

• When importing an xarray grid with SHGrid.from_xarray(), check if the first row is 90 or -90 and flip accordingly.
• Fixed a bug in SHCoeffs.convert() when coefficient errors are present.
• Fixed a bug in spectralanalysis.cross_spectrum() when using real unnormalized coefficients.

Plotting improvements

• Added the optional parameter rectangle to the SHGrid.plotgmt() method that allows the use of rectangular projections that are specified by the lower-left and upper-right coordinates.
• Added the optional parameter cmap_background_foreground to SHGrid.plotgmt() that controls how data are plotted when they exceed the limits of the colormap.
• Added the optional parameter title_offset to SHGrid.plotgmt() and SHGrid.plot() that specifies how much space to add between the plot and title.
• Cleaned up the SHGrid.plotgmt() shading options based on changes made in pygmt 0.7, including the use of xarrays directly instead of creating temporary files.
• Added the optional argument cmap_rlimits and cmap_rlimits_complex to SHGrid.plot(), SHGrid.plotgmt() and SHGrid.plot3d() to specify colorbar limits with respect to the maximum value of the data.
• Added the optional argument cmap_scale to SHGrid.plot() and SHGrid.plotgmt() to allow using either a linear or logarithmic color map.
• Add the optional argument cb_power to SHGrid.plotgmt() to allow plotting annotations as powers of 10.
• Added an option to SHCoeffs.plot_spectrum() to plot the error spectrum (if present) or not.

Other changes

• Added "ifx" to the list of possible Fortran compilers in the Makefile.
• Added the optional argument r to SHMagCoeffs.expand() and SHGravCoeffs.expand() that allows one to compute the field at an arbitrary list of (r, lat, lon) points.
• Allow the passing of pathlib.Path objects to all methods that require a filename.
• Added jupyter-core as a build dependency in pyproject.toml.
• Changed the behaviour of the fortan function MakeCircleCoord when the angular radius is zero.

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, D. Minton, I. Oshchepkov, P.-L. Phan, O. Poplawski, M. Reinecke, E. Sales de Andrade, E. Schnetter, S. Schröder, J. Sierra, A. Vasishta, A. Walker, xoviat, B. Xu (2024). SHTOOLS: Version 4.12, Zenodo, doi:10.5281/zenodo.592762

Version 4.11.10

Support for Python 3.12 using the Meson build system

This version no longer relies on distutils (which was deprecated in python 3.12) and instead makes use of Meson and Meson-Python to build and test the pyshtools package. The package can be built from source using pip as before, however, if you need to create an editable install, it will be necessary to use the slightly modified command

pip install --no-build-isolation -e .

Please see the online documentation for instructions on how to run the test suites and benchmarks.

Other changes

• We no longer use versioneer to determine the package version, but instead set the version in the main meson.build file using setuptools_scm. At the present time, it is not possible to determine the version when using a source tarball, and for this case, the build will fail. Please ensure that when building from source that you are doing so from a git versioned repository.
• Fixed a problem with SHCoeffs.volume() when the coefficient normalization was ortho.
• Fixed a potential LAPACK underscore problem when compiling with LAPACK_UNDERSCORE specified.
• Minor changes were made to the python source files to ensure numpy v2 compatibility.

M. A. Wieczorek, M. Meschede, A. Broquet, T. Brugere, A. Corbin, EricAtORS, A. Hattori, A. Kalinin, J. Kohler, D. Kutra, K. Leinweber, P. Lobo, I. Oshchepkov, P.-L. Phan, O. Poplawski, M. Reinecke, E. Sales de Andrade, E. Schnetter, S. Schröder, J. Sierra, A. Vasishta, A. Walker, xoviat, B. Xu (2024). SHTOOLS: Version 4.11.10, Zenodo, doi:10.5281/zenodo.592762

Version 4.10.4

Bug fixes, minor enhancements, and deprecations

• The module pyshtools.shtools has been removed, and is now accessible at pyshtools.backends.shtools.
• Fixed a bug in the Fortran source code of MakeGravGradGridDH and MakeMagGradGridDH, both of which are used in the pyshtools tensor method of the classes SHGravCoeffs and SHMagCoeffs. This bug only affected the southern hemisphere, and is most noticeable close to the south pole.
• Updated the urls for the Earth 2012/2014 datasets.
• Changed the order of the imports in pyshtools/__init__.py that led to a circular import problem on some systems.
• Updated how the shtools routines were wrapped using functools.wraps.

M. A. Wieczorek, M. Meschede, A. Broquet, T. Brugere, A. Corbin, EricAtORS, A. Hattori, A. Kalinin, J. Kohler, D. Kutra, K. Leinweber, P. Lobo, I. Oshchepkov, P.-L. Phan, O. Poplawski, M. Reinecke, E. Sales de Andrade, E. Schnetter, S. Schröder, J. Sierra, A. Vasishta, A. Walker, xoviat, B. Xu (2023). SHTOOLS: Version 4.10.4, Zenodo, doi:10.5281/zenodo.592762

Version 4.10.3

Minor packaging enhancement

• The release modifies the way that the python doc strings are generated for the wrapped fortran functions. In previous releases the doc strings were generated at the time the package was built. Now, the doc strings are included directly in the repo, similar to the unix man pages. This minor change will help in making the macOS ARM conda builds, as well as in our transition from distutils to meson.

Future deprecation

The module pyshtools.shtools will be deprecated in the v4.11 release. This module represents 1 of 2 possible backends for pyshtools, and has been located at pyshtools.backends.shtools since version 4.9. Unless explicitly required, the user should avoid using the backends modules directly, and should instead call the routines that are located in the top level modules such as pyshtools.expand and pyshtools.rotate. Setting the backend by use of the routine pyshtools.backends.selected_preferred_backend() determines which backend to use when calling the routines in these top level modules.

M. A. Wieczorek, M. Meschede, T. Brugere, A. Corbin, A. Hattori, A. Kalinin, J. Kohler, D. Kutra, K. Leinweber, P. Lobo, I. Oshchepkov, P.-L. Phan, O. Poplawski, M. Reinecke, E. Sales de Andrade, E. Schnetter, S. Schröder, J. Sierra, A. Vasishta, A. Walker, xoviat, B. Xu (2023). SHTOOLS: Version 4.10.3, Zenodo, doi:10.5281/zenodo.592762

Version 4.10.2

Bug fixes and minor enhancements

• Add the optional parameter lmax to pysh.SHWindow.to_shgrid().
• Replace libtool by ar and ranlib in the fortran makefile.
• Replace PWD by CURDIR in the main makefile.
• Add method .change_units to the SHMagCoeffs class.
• Copy all routines from the shtools module to backends.shtools (the top-level shtools module will be deprecated in v4.11).
• Use pkg_resources instead of setuptools.version.pkg_resources in setup.py.
• Fix a couple bugs where _np.int_ was mistakenly _np.int.
• Move unix man pages from section 1 to section 3.
• Modify fortran test programs to accept command line arguments, such as the location of the example data files and program input files.
• Remove pypandoc as a dependency in setup.py and don't convert the readme to reST format for pypi.
• Add a Ganymede gravity model to the datasets module.
• Minor updates to documentation and refactoring of the project README.

Future deprecation

The module pyshtools.shtools will be deprecated in the v4.11 release. This module represents 1 of 2 possible backends for pyshtools, and has been located at pyshtools.backends.shtools since version 4.9. Unless explicitly required, the user should avoid using the backends modules directly, and should instead call the routines that are located in the top level modules such as pyshtools.expand and pyshtools.rotate. Setting the backend by use of the routine pyshtools.backends.selected_preferred_backend() determines which backend to use when calling the routines in these top level modules.

M. A. Wieczorek, M. Meschede, T. Brugere, A. Corbin, A. Hattori, A. Kalinin, J. Kohler, D. Kutra, K. Leinweber, P. Lobo, I. Oshchepkov, P.-L. Phan, O. Poplawski, M. Reinecke, E. Sales de Andrade, E. Schnetter, S. Schröder, J. Sierra, A. Vasishta, A. Walker, xoviat, B. Xu (2023). SHTOOLS: Version 4.10.2, Zenodo, doi:10.5281/zenodo.592762

Version 4.10.1

Bug fixes and minor enhancements

• Simplify the code for backend management and improve handing of the default backend when ducc0 isn't installed.
• Changing the backend now changes which functions are referenced in the expand and rotate submodules.
• Fix setup.py to work with all versions of setuptools.
• Add the MarsTopo719 dataset for use in CI checks (using MarsTopo2600 often would timeout during download).
• Fix a bug in SHGravRealCoeffs.expand and SHGravRealCoeffs.expand that did not correctly compute the radius of the flattened ellipsoid when an array of latitudes was provided.
• Remove -static option from compiler options.
• Convert some strings to raw format when they contain latex backslashes.
• And other minor changes...

Future deprecation

The module pyshtools.shtools will be deprecated in the v4.11 release. This module represents 1 of 2 possible backends for pyshtools, and has been located at pyshtools.backends.shtools since version 4.9. Unless explicitly required, the user should avoid using the backends modules directly, and should instead call the routines that are located in the top level modules such as pyshtools.expand and pyshtools.rotate. Setting the backend by use of the routine pyshtools.backends.selected_preferred_backend() determines which backend to use when calling the routines in these top level modules.

M. A. Wieczorek, M. Meschede, T. Brugere, A. Corbin, A. Hattori, K. Leinweber, I. Oshchepkov, M. Reinecke, E. Sales de Andrade, E. Schnetter, S. Schröder, A. Vasishta, A. Walker, B. Xu, J. Sierra (2022). SHTOOLS: Version 4.10.1, Zenodo, doi:10.5281/zenodo.592762

Version 4.10

Enhancements

• Change the preferred backend from 'shtools' to 'ducc'.
• Improve handing of switching backends. Changing backends will dynamically link the correct routine to the top level modules found in pyshtools.expand and pyshools.rotate.
• Update python examples so that they don't call routines directly in the shtools backend. [See deprecation note below.]
• Add historical lunar topography dataset GLTM-2B.
• Add historical martian magnetic field models FSU50 and FSU90.
• Add new Mars gravity model MRO120F as well as several historical Mars gravity models.
• Add historical Venus topography datasets SHTJV360A01 and SHTJV360A02.
• Add Thebault2021 Earth magnetic field dataset.
• Add Mars topography dataset MarsTopo719, which is a truncated version of MarsTopo2600.
• Update urls for databases hosted at GSFC.
• Reorder optional arguments in docs for makegravgradgriddh and makemaggravgradgrid for consistency with code.
• Allow 'shtools' and 'dov' file formats to contain floats for degree and order.
• Minor changes and enhancements to the documentation.

Bug fixes

• Fix typo regarding nthreads in SHMagCoeffs.rotate() method.
• Fix bug with SHGravCoeffs.admittance() when using function='geoid'.
• Fix bug in python wrapper of the routine MakeGrid2D concerning the mandatory variable interval.
• Add workaround to use pygmt with shading for versions >=0.4.
• Convert all grids to float before using the ducc backend.
• SHGeoid.to_netcdf() now outputs double precision by default (consistent with the other grid classes).
• Fix bug with SHWindow.multitaper_cross_spectrum() when using arbitrary localization regions.
• Fix bug with the c-wrapper for cMakeGradientDH regarding the optional radius parameter.
• Minor changes to remove deprecation warnings.
• Fixed setup.py to work with setuptools 62.0.0 and 62.1.0.

Note: The module pyshtools.shtools will be deprecated in the v4.11 release. This module represents 1 of 2 possible backends for pyshtools, and will henceforth be located at pyshtools.backends.shtools. Unless explicitly required, the user should avoid using the backends modules directly, and should instead call the routines that are located in the top level modules such as pyshtools.expand. Setting the backend by use of the routine pyshtools.backends.selected_preferred_backend() determines which backed to use when calling the routines in the top level modules.

M. A. Wieczorek, M. Meschede, T. Brugere, A. Corbin, A. Hattori, K. Leinweber, I. Oshchepkov, M. Reinecke, E. Sales de Andrade, E. Schnetter, S. Schröder, A. Vasishta, A. Walker, B. Xu, J. Sierra (2022). SHTOOLS: Version 4.10, Zenodo, doi:10.5281/zenodo.592762

Version 4.9

Backends

Implemented the option to use a different backend when performing certain operations requiring spherical harmonic transforms. At present, only 'shtools' (default) and the Distinctly Useful Code Collection ('ducc') are supported.

• Introduced a new module backends that has functions allowing the user to control which backend is used. To set the backend for all subsequent operations, use backends.select_preferred_backend().
• Added the optional parameters backend and nthreads ('ducc' only) to all methods of the pyshtools classes that allow multiple backends (such as SHGrid and SHCoeffs).
• Added a new backends web documentation page that describes the use of the new module.

Plotting routines

• Added the new methods SHGrid.histogram() and SHGrid.plot_histogram() for generating area-weighted histograms.
• Renamed a few instances of variable names used in the plotting routines from title_labelsize to titlesize for consistency. This affects the methods Slepian.plot_coupling_matrix(), Slepian.plot_spectra(), and SHWindow.plot_coupling_matrix().
• Modified some plotting routines so that fontsizes can be specified using standard matplotlib strings.
• Replaced the deprecated matplotlib get_geometry with get_subplotspec.
• Replaced the pygmt option I with the alias shading for colorbars.

IO and datasets

• Updated the Venus rotation period using data from Margot et al. (2021).
• Renamed constants variables r to mean_radius (but kept r as an alias for backwards compatibility).
• Improved the reading of ICGEM formatted files of gravitational potential models. Fixed a bug where the time variable contribution was not computed when the coefficients had an associated trnd or dot term. When a line in the data section starts with an unknown key, a warning is now printed to the screen (which can be turned off by specifying quiet=True). For files formatted as icgem2.0, time variable terms were simply ignored if the specified epoch fell outside of the allowed range. Now, the routine will instead raise an error. Finally, the documentation was improved by describing the allowable keyword entries of the header and data section of the file.
• Added the option encoding for all routines and methods that read or write text-based spherical harmonic files.
• Hard coded all datasets to use utf-8 in order to avoid problems with the XGM2019E dataset that has a character that can not be decoded by the GBK encoding that is the default in some Chinese installations.
• Added a few historical lunar gravity fields to the module datasets.Moon.historical.gravity.

Other changes

• Added a C wrapper for the function MakeGradientDH().
• Changed the default behavior of the Fortran routine MakeGradientDH() and SHCoeffs.gradient(). The original behavior was to compute the gradient on a sphere of radius r, where r was the degree 0 coefficient of the function. The new behaviour is to compute the gradient on the unit sphere. This radius can be modified by supplying the optional argument radius.
• Added the option 'per_lm' for generating random spherical harmonic coefficients in the .from_random() methods of SHCoeffs, SHGravCoeffs, and SHMagCoeffs.
• Fixed two bugs related to complex spherical harmonic transforms. First, for complex grids, the last coefficient coeffs[1, lmax, lmax] was in error when lmax was odd and when using DH grids. Second, when using SHGrid.expand() with grid type DH2 the parameter sampling=2 was not passed to the Fortran routine.
• Updated makefile install to include example data files, and to place them in the correct directories when installing with homebrew.
• Updated a few dependencies, including astropy>=4.0 and pygmt>=0.3.0.
• Fixed a floating point error-caused bug in SHGrid that could arise if the value input to arccos was greater than 1.
• Converted np.float_ and np.complex_ to np.float64 and np.complex128 to avoid numpy deprectation warning.
• Added threadsafe to numpy signature files.

M. A. Wieczorek, M. Meschede, T. Brugere, A. Corbin, A. Hattori, K. Leinweber, I. Oshchepkov, M. Reinecke, E. Sales de Andrade, E. Schnetter, S. Schröder, A. Vasishta, A. Walker, B. Xu (2021). SHTOOLS: Version 4.9, Zenodo, doi:10.5281/zenodo.592762

Version 4.9

Backends

Implemented the option to use a different backend when performing certain operations requiring spherical harmonic transforms. At present, only 'shtools' (default) and the Distinctly Useful Code Collection ('ducc') are supported.

• Introduced a new module backends that has functions allowing the user to control which backend is used. To set the backend for all subsequent operations, use backends.select_preferred_backend().
• Added the optional parameters backend and nthreads ('ducc' only) to all methods of the pyshtools classes that allow multiple backends (such as SHGrid and SHCoeffs).
• Added a new backends web documentation page that describes the use of the new module.

Plotting routines

• Added the new methods SHGrid.histogram() and SHGrid.plot_histogram() for generating area-weighted histograms.
• Renamed a few instances of variable names used in the plotting routines from title_labelsize to titlesize for consistency. This affects the methods Slepian.plot_coupling_matrix(), Slepian.plot_spectra(), and SHWindow.plot_coupling_matrix().
• Modified some plotting routines so that fontsizes can be specified using standard matplotlib strings.
• Replaced the deprecated matplotlib get_geometry with get_subplotspec.
• Replaced the pygmt option I with the alias shading for colorbars.

IO and datasets

• Updated the Venus rotation period using data from Margot et al. (2021).
• Renamed constants variables r to mean_radius (but kept r as an alias for backwards compatibility).
• Improved the reading of ICGEM formatted files of gravitational potential models. Fixed a bug where the time variable contribution was not computed when the coefficients had an associated trnd or dot term. When a line in the data section starts with an unknown key, a warning is now printed to the screen (which can be turned off by specifying quiet=True). For files formatted as icgem2.0, time variable terms were simply ignored if the specified epoch fell outside of the allowed range. Now, the routine will instead raise an error. Finally, the documentation was improved by describing the allowable keyword entries of the header and data section of the file.
• Added the option encoding for all routines and methods that read or write text-based spherical harmonic files.
• Hard coded all datasets to use utf-8 in order to avoid problems with the XGM2019E dataset that has a character that can not be decoded by the GBK encoding that is the default in some Chinese installations.
• Added a few historical lunar gravity fields to the module datasets.Moon.historical.gravity.

Other changes

• Added a C wrapper for the function MakeGradientDH().
• Changed the default behavior of the Fortran routine MakeGradientDH() and SHCoeffs.gradient(). The original behavior was to compute the gradient on a sphere of radius r, where r was the degree 0 coefficient of the function. The new behaviour is to compute the gradient on the unit sphere. This radius can be modified by supplying the optional argument radius.
• Added the option 'per_lm' for generating random spherical harmonic coefficients in the .from_random() methods of SHCoeffs, SHGravCoeffs, and SHMagCoeffs.
• Fixed two bugs related to complex spherical harmonic transforms. First, for complex grids, the last coefficient coeffs[1, lmax, lmax] was in error when lmax was odd and when using DH grids. Second, when using SHGrid.expand() with grid type DH2 the parameter sampling=2 was not passed to the Fortran routine.
• Updated makefile install to include example data files, and to place them in the correct directories when installing with homebrew.
• Updated a few dependencies, including astropy>=4.0 and pygmt>=0.3.0.
• Fixed a floating point error-caused bug in SHGrid that could arise if the value input to arccos was greater than 1.
• Converted np.float_ and np.complex_ to np.float64 and np.complex128 to avoid numpy deprectation warning.
• Added threadsafe to numpy signature files.

M. A. Wieczorek, M. Meschede, T. Brugere, A. Corbin, A. Hattori, K. Leinweber, I. Oshchepkov, M. Reinecke, E. Sales de Andrade, E. Schnetter, S. Schröder, A. Vasishta, A. Walker, B. Xu (2021). SHTOOLS: Version 4.9, Zenodo, doi:10.5281/zenodo.592762

Version 4.8

• Several functions have been vectorized using numpy.vectorize(). These include: spharm_lm(), legendre_lm(), MakeGridPoint(), MakeGridPointC(), DownContFilterMA(), DownContFilterMC(), NormalGravity(), SHConfidence(), and PlmIndex().
• A new Fortran routine MakeGradientDH was added to compute the horizontal gradient of a real scalar function. The method .gradient() was added to the SHCoeffs class, and a new class SHGradient was created to store and plot the two horizontal components of the gradient.
• Added new Fortran functions MakeGravGridPoint and MakeMagGridPoint to compute the gravity and magnetic field vector at a single point.
• Added the option to compute the gravity and magnetic field vectors at a single point using the python class methods SHGravCoeffs.expand() and SHMagCoeffs.expand().
• The plot_spectrum2d() routines have been updated to include more plotting options, including placement of the origin, tick intervals, and colormaps. Most optional parameters are the same as in the SHGrid.plot() method.
• Added the option to including intensity shading in the SHGrid.plotgmt() routine. The shading can be derived from the gradient of the input grid (by setting shading=True) or from a different map by supplying an SHGrid class instance. Optional parameters include the azimuth of the shading (shading_azimuth), as well as the maximum amplitude of the intensity (shading_amplitude).
• Modified all the Fortran routines to use a slightly more efficient way to compute the radius of an ellipsoid as a function of geocentric latitude.
• Fixed a bug in SHCoeffs.expand() when colat was specified in radians.
• All declarations of integers in the Fortran code are now made using the types defined in the module iso_fortran_env. Furthermore, the python wrapper and signature files have been updated to be explicit when defining the Fortran variables.
• Fixed a bug where the old module name constant needed to be updated to constants in the method SHCoeffs.centroid().
• Corrected the parameterization used when generating ellipsoids in SHGrid.from_ellipsoid(). Though this method was introduced in v4.7, it was not mentioned in the release notes.
• Changed the default behavior of SHCoeffs.to_array() so that the default value is not to return the errors by setting errors=False.
• Added the optional attribute name to the coefficient classes SHGrid, SHGravCoeffs, SHMagCoeffs and SlepianCoeffs. All datasets now explicity set name to the function call of the dataset.
• Moved the file shtools.h from src/ to include/ and updated the Makefiles accordingly.

M. A. Wieczorek, M. Meschede, E. Sales de Andrade, A. Corbin, I. Oshchepkov, B. Xu, and A. Walker, A. Hattori, S. Schröder, K. Leinweber, A. Vasishta (2021). SHTOOLS: Version 4.8, Zenodo, doi:10.5281/zenodo.592762