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.

The pyshtools constants are organized primarily by planet: Mercury, Venus, Earth, Moon, and Mars. Each planet has several attributes, such as mean_radius (aliased as r), mass, and flattening f. 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 = MarsTopo2600: Wieczorek, M. A. (2015). Gravity and topography of the terrestrial planets. In T. Spohn & G. Schubert (Eds.), Treatise on Geophysics, 2nd ed., Vol. 10, pp. 153-193). Oxford, Elsevier-Pergamon, doi:10.1016/B978-0-444-53802-4.00169-X.

To use the value of a constant in a calculation, it is only necessary to access its value attribute:

In [2]: 2 * pysh.constants.Mars.mean_radius.value
6779000.0

Physical constants from the Committee on Data for Science and Technology are provided in the submodule codata. 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:

Mercury

Venus

Earth

The Moon

Mars

Vesta

Ceres