## 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 the the mean planetary radius 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.r)
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.r.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

Dataset Description
GTMES150 GSFC 150 degree and order spherical harmonic model of the shape of the planet Mercury.
JGMESS160A JPL 160 degree and order spherical harmonic model of the gravitational potential of Mercury (Konopliv et al. 2020). This model applies a Kaula law constraint to all degrees.
JGMESS160A_ACCEL JPL 160 degree and order spherical harmonic model of the gravitational potential of Mercury (Konopliv et al. 2020). This model applies a surface acceleration constraint that is based on the degree strength given by the coefficient covariance.
JGMESS160A_TOPOSIG JPL 160 degree and order spherical harmonic model of the gravitational potential of Mercury (Konopliv et al. 2020). This model applies a constraint similar to the Kaula constraint except that the uncertainty is given by the corresponding magnitude of the gravity derived from topography.
GGMES100V08 GSFC 100 degree and order spherical harmonic model of the gravitational potential of Mercury (Genova et al. 2019). This model applies a Kaula constraint to all degrees.

### Venus

Dataset Description
VenusTopo719 719 degree and order spherical harmonic model of the shape of the planet Venus (Wieczorek 2015).
MGNP180U JPL 180 degree and order spherical harmonic model of the gravitational potential of Venus (Konopliv et al. 1999).

### Earth

Dataset Description
Earth2012 Shape and topography (with respect to mean sea level) of Earth expanded to degree and order 2160 (Hirt et al. 2012).
Earth2014 Topography of Earth with respect to mean sea level, expanded to degree and order 2160 (Hirt and Rexer 2015).
EGM2008 Degree 2190 model of the Earth’s gravity field in a tide-free system. This model is based on data from altimetry, ground-based measurements, and the satellite GRACE (Pavlis et al. 2012).
EIGEN_6C4 Degree 2190 model of the Earth’s gravity field in a tide-free system (Förste et al. 2014). This model is based on data from altimetry, ground-based measurements, and the satellites GOCE, GRACE, and LAGEOS.
GGM05C Degree 360 model of the Earth’s gravity field in a zero-tide system (Ries et al. 2016). This model is based on data from altimetry, ground-based measurements, and the satellites GOCE and GRACE.
GOCO06S Degree 300 model of the Earth’s gravity field in a zero-tide system (Kvas et al. 2019). This model is based solely on satellite data.
EIGEN_GRGS_RL04_MEAN_FIELD Degree 300 model of the Earth’s gravity field in a tide-free system (Lemoine et al. 2019). This model is based solely on satellite data.
XGM2019E Degree 2190 model of the Earth’s gravity field in a zero-tide system (Zingerle et al. 2020). This combined model is based on data from altimetry, ground-based measurements, topography, and satellites.
IGRF_13 Degree 13 time-variable model of the Earth’s main magnetic field that is valid between 1900 and 2020 (Thébault et al. 2015).
SWARM_MLI_2D_0501 Degree 133 magnetic field model of the Earth’s lithsophere that is based largely on satellite data (Thébault et al. 2013). Though this model is based largely on data from the SWARM mission, data from the CHAMP mission and some ground-based measurements are also used.
NGDC_720_V3 Degree 740 magnetic field model of the Earth’s lithsophere that was compiled from satellite, marine, aeromagnetic and ground-based magnetic surveys (Maus 2010).
WDMAM2_800 Degree 800 model of the Earth’s lithospheric magnetic field that is based on a worldwide compilation of near-surface magnetic data. This is the second version of the World Digital Magnetic Anomaly Map (WDMAM) (Lesur et al. 2016).

### The Moon

Dataset Description
MoonTopo2600p 2600 degree and order spherical harmonic model of the shape of Earth’s Moon in a principal axis coordinate system (Wieczorek 2015).
GRGM900C GSFC 900 degree and order spherical harmonic model of the gravitational potential of the Moon. This model applies a Kaula constraint for degrees greater than 600 (Lemoine et al. 2014).
GRGM1200B GSFC 1200 degree and order spherical harmonic model of the gravitational potential of the Moon (Goossens et al. 2020). This model applies a Kaula constraint for degrees greater than 600.
GRGM1200B_RM1_1E0 GSFC 1200 degree and order spherical harmonic model of the gravitational potential of the Moon (Goossens et al. 2020). This model uses a rank-minus-1 constraint based on gravity from surface topography for degrees greater than 600 with a value of lambda equal to 1.
GL0900D JPL 900 degree and order spherical harmonic model of the gravitational potential of the Moon (Konopliv et al. 2014). This model applies a Kaula constraint for degrees greater than 700.
GL1500E JPL 1500 degree and order spherical harmonic model of the gravitational potential of the Moon (Konopliv et al. 2014). This model applies a Kaula constraint for degrees greater than 700.
T2015_449 449 degree and order spherical harmonic model of the magnetic potential of the Moon. This model was used in Wieczorek (2018) and is a spherical harmonic expansion of the global magnetic field model of Tsunakawa et al. (2015).
Ravat2020 450 degree and order spherical harmonic model of the magnetic potential of the Moon. This model is based on using magnetic monopoles with an L1-norm regularisation.

### Mars

Dataset Description
MarsTopo2600 2600 degree and order spherical harmonic model of the shape of the planet Mars (Wieczorek 2015).
GMM3 GSFC 120 degree and order spherical harmonic model of the gravitational potential of Mars (Genova et al. 2016). This model applies a Kaula constraint for degrees greater than 90.
GMM3_RM1_1E0 GSFC 150 degree and order spherical harmonic model of the gravitational potential of Mars (Goossens et al. 2017). This model uses the same data as GMM3, but with a rank-minus-1 constraint based on gravity from surface topography for degrees greater than 50 with a value of lambda equal to 1.
MRO120D JPL 120 degree and order spherical harmonic model of the gravitational potential of Mars (Konopliv et al. 2016). This model applies a Kaula constraint for degrees greater than 80.
Langlais2019 134 degree and order spherical harmonic model of the magnetic potential of Mars (Langlais et al. 2019). This model makes use of data from MGS MAG, MGS ER and MAVEN MAG.
Morschhauser2014 110 degree and order spherical harmonic model of the magnetic potential of Mars (Morschhauser et al. 2014).

### Vesta

Dataset Description
VESTA20H JPL 20 degree and order spherical harmonic model of the gravitational potential of (4) Vesta (Konopliv et al. 2014).

### Ceres

Dataset Description
CERES18D JPL 18 degree and order spherical harmonic model of the gravitational potential of (1) Ceres (Konopliv et al. 2018).