Constants and datasets

Constants

The constants subpackage defines physical constants related to the terrestrial planets and moons. Each constant is an instance of an astropy Constant class, which has the attributes name, value, uncertainty, unit, and reference.

Each body can have several attributes, including

• gm,
• mass,
• mean_radius (aliased as r),
• volume_equivalent_radius,
• volume
• mean_density
• gravity_mean_radius
• omega (rotation rate)

Additional parameters are defined when appropriate. To see all information about an individual constant, it is only necessary to use the print function:

In [1]: print(pysh.constants.Mars.mean_radius)
  Name   = Mean radius of Mars
  Value  = 3389500.0
  Uncertainty  = 0.0
  Unit  = m
  Reference = MOLA_shape: Wieczorek, M. (2024). Spherical harmonic models of the shape of Mars (1.0.0) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.10794059

To use the value of a constant in a calculation, such as in this simple calculation of the circumference in kilometers, it is only necessary to access its value attribute:

In [2]: 2 * np.pi * pysh.constants.Mars.mean_radius.value / 1000
21296.856598685208

Physical constants from the Committee on Data for Science and Technology are provided in the submodule codata, and a few of these (such as G and mu0) are referenced in the main constants namespace.

Datasets

pyshtools provides easy access to many research-grade gravity, topography, and magnetic field datasets of the terrestrial planets. To load a dataset, it is only necessary to call the relevant method from the datasets submodule as in these examples:

    hlm = pysh.datasets.Venus.VenusTopo719()  # Venus shape
    clm = pysh.datasets.Earth.EGM2008()  # Earth gravity
    glm = pysh.datasets.Earth.WDMAM2_800()  # Earth magnetic field
    clm = pysh.datasets.Moon.GRGM1200B()  # Gravity of the Moon

When accessing a dataset, the file will first be downloaded from the original source using pooch and then stored in the pyshtools subdirectory of the user’s cache directory (if it had not been done previously). The file hash will be verified to ensure that it has not been modified, and the file will then be used to initialize and return an SHCoeffs, SHGravCoeffs or SHMagCoeffs class instance. In most cases the files are stored in their original form: If they need to be decompressed or unzipped, this is done on the fly when they are used. Only when zip archives contain several files are the files stored in unzipped form.

The coefficients can be read up to a maximum specified degree by providing the optional variable lmax. For IGRF magnetic field coefficients, the year of the output coefficients can be specified by the optional argument year (the default is 2020).

The following is the list of implemented datasets. Additional older or deprecated datasets can be found in the historical module for each body.

Mercury

Venus

Earth

The Moon

Mars

(1) Ceres

(4) Vesta

(433) Eros

Io (Jupiter)

Europa (Jupiter)

Ganymede (Jupiter)

Callisto (Jupiter)

Titan (Saturn)

Enceladus (Saturn)