Skip to content

redplanet.Mag.sh.load 

load(model: str = None, lmax: int = 134) -> None

Load a magnetic field model for Mars.

Parameters:

Name Type Description Default
model str

Name of the magnetic field model to load. Options are:

  • 'Langlais2019' (0.081 MiB) — Spherical harmonic model of the magnetic field of Mars with a spatial resolution of ~160 km at the surface, corresponding to spherical harmonic degree 134. Integrates data from MGS magnetometer, MGS electron reflectometer, and MAVEN magnetometer.
    • Dataset downloaded from Langlais (2019). The full paper discusses/analyzes the models in detail (Langlais et al., 2019).
    • We process spherical harmonic coefficients with pyshtools (Wieczorek et al., 2024; Wieczorek & Meschede, 2018).
 None
lmax int

The maximum spherical harmonic degree of the coefficients to load. Default is 134 (maximum for 'Langlais2019').

 134

Raises:

Type Description
ValueError

If an invalid model name is provided.
References
  1. Langlais, B. (2019). Spherical harmonic model of the magnetic field of Mars to degree 134 [Dataset]. Zenodo. https://doi.org/10.5281/zenodo.3876714
  2. Langlais, B., Thébault, E., Houliez, A., Purucker, M. E., & Lillis, R. J. (2019). A New Model of the Crustal Magnetic Field of Mars Using MGS and MAVEN. Journal of Geophysical Research: Planets, 124(6), 1542-1569. https://doi.org/10.1029/2018JE005854
  3. Wieczorek, M. A., & Meschede, M. (2018). SHTools: Tools for Working with Spherical Harmonics. Geochemistry, Geophysics, Geosystems, 19(8), 2574-2592. https://doi.org/10.1029/2018GC007529
  4. Wieczorek, M. A., Meschede, M., Broquet, A., Brugere, T., Corbin, A., EricAtORS, Hattori, A., Kalinin, A., Kohler, J., Kutra, D., Leinweber, K., Lobo, P., Maia, J., Mentzer, E., Minton, D., Oshchepkov, I., Phan, P. L., Poplawski, O., Reinecke, M., Sales de Andrade, E., Schnetter, E., Schröder, S., Shin, D., Sierra, J., Vasishta, A., Walker, A., xoviat, & Xu, B. (2024). SHTOOLS/SHTOOLS: Version 4.13.1. Zenodo. https://doi.org/10.5281/zenodo.12698962
Source code in src/redplanet/Mag/sh/loader.py 
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
@substitute_docstrings
def load(
    model : str = None,
    lmax  : int = 134,
) -> None:
    """
    Load a magnetic field model for Mars.

    Parameters
    ----------
    model : str
        Name of the magnetic field model to load. Options are:

        - `'Langlais2019'` (0.081 MiB) — Spherical harmonic model of the magnetic field of Mars with a spatial resolution of ~160 km at the surface, corresponding to spherical harmonic degree 134. Integrates data from MGS magnetometer, MGS electron reflectometer, and MAVEN magnetometer.
            - Dataset downloaded from {@Langlais2019_data.n}. The full paper discusses/analyzes the models in detail ({@Langlais2019_paper.p}).
            - We process spherical harmonic coefficients with `pyshtools` ({@shtools_code.p}; {@shtools_paper.p}).
    lmax : int, optional
        The maximum spherical harmonic degree of the coefficients to load. Default is 134 (maximum for 'Langlais2019').

    Raises
    ------
    ValueError
        If an invalid model name is provided.
    """

    ## I expect to add more later, so users should explicitly choose Genova2016 for forward compatibility. Mittelholz might be publishing hers soon.
    info = {
        'Langlais2019': {
            'metadata': {
                'description': 'Martian magnetic field model, based on 14386 ESD, inversion using MGS MAG, MGS ER and MAVEN MAG, field predicted at 150km altitude. SH model, ref surface =3393.5 km, from Langlais/Thebault/Houliez/Purucker/Lillis internal coefficients.',
                'units'      : 'nT',
                'lmax'       : lmax,
                'links'      : {
                    'data' : 'https://doi.org/10.5281/zenodo.3876714',
                    'paper': 'https://doi.org/10.1029/2018JE005854',
                },
            },
        },
    }

    if model not in info:
        raise ValueError(f"Invalid magnetic field model: '{model}'. Options are: {list(info.keys())}.")



    if model == 'Langlais2019':

        fpath = _get_fpath_dataset(model)

        '''
        - Arguments for `from_file` are taken directly from the `pyshtools` source code (`pyshools.datasets.Mars.Langlais2019()`).
            - I rewrite it so the dataset is downloaded to `redplanet` cache rather than `pyshtools` cache, ensuring `redplanet` can fully manage/clear its own dataset cache.
        '''
        ds = (
            pysh.shclasses.SHMagCoeffs.from_file(
                fpath,
                lmax       = lmax,
                skip       = 4,
                r0         = 3393.5e3,
                header     = False,
                file_units = 'nT',
                units      = 'nT',
                encoding   = 'utf-8',
            )
            .expand()
            .to_xarray()
            .isel(lat=slice(None, None, -1))  ## in pysh, lats are always decreasing at first
        )


        data_dict = {}
        for data_var in list(ds.data_vars):
            data_dict[data_var] = ds[data_var].values

        metadata = info[model]['metadata']
        metadata['fpath'] = fpath


        global _dat_mag
        _dat_mag = GriddedData(
            lon       = ds.lon.values,
            lat       = ds.lat.values,
            is_slon   = False,
            data_dict = data_dict,
            metadata  = metadata,
        )



    else:
        raise ValueError(f"THE DEVELOPER MESSED UP. THIS SHOULD NOT HAPPEN.")

    return