This page was created by the IDL library routine `mk_html_help2`.

Last modified: Tue Aug 5 18:17:40 2025.

# Directory Listing of Routines

# projects/maven/models

- MVN_MODEL_BCRUST
- MVN_MODEL_BCRUST_ALT
- MVN_MODEL_BCRUST_CALC
- MVN_MODEL_BCRUST_LOAD
- MVN_MODEL_BCRUST_RESTORE

# Routine Descriptions

## MVN_MODEL_BCRUST

[Next Routine] [List of Routines]

    PROCEDURE:       MVN_MODEL_BCRUST

    PURPOSE:         Computes magnetic field predictions from the Martian
                     crustal field model at the MAVEN location, an returns
                     the predicutions in a named data structure.

    INPUTS:

       TRANGE:       An array in any format accepted by time_double().
                     The minimum and maximum values in this array specify
                     the time range to calculate. If the elements of 1d
                     time range array are more than 2, the crustal field
                     model is calculated at the precise time steps.

    KEYWORDS:

       RESOLUTION:   Defines the time resolution. Default is 1sec.

             DATA:   Returns the calculated results as structure.

           ARKANI:   Uses Arkani-Hamed's spherical harmonic model.
                     (default nmax=62, but goes out to n=90)

        CAIN_2003:   Uses Cain's 2003 spherical harmonic model.
                     (default nmax=90)

        CAIN_2011:   Uses Cain's 2011 spherical harmonic model.
                     (default nmax=90)

         PURUCKER:   Uses Purucker's spherical harmonic model.

     MORSCHHAUSER:   Uses Morschhauser's 2014 spherical harmonic model.
                     (It is the default model to calculate).

         LANGLAIS:   Uses Langlais's 2019 spherical harmonic model.

             NMAX:   Specifies nmax for spherical harmonic model in the event
                     the user does not want to use the full model
                     (e.g. invoking /Cain defaults to nmax=90, but you
                      could change to nmax=60 by adding nmax=60 when calling)

          VERSION:   Specifies the version of the Cain 2011 model to be used.
                     Default = 0.

            TPLOT:   Generates the tplot variables of crustal field model.

             PATH:   Defines the file path which the IDL save file is stored.
                     In default, it is stored to the same place for this routine.

              POS:   If user wants to use a pseudo location, or to explicitly
                     define the MAVEN location, you can use this keyword.
                     The coordinate system must be IAU_MARS (planetocentric coordinates).
                     The format must be two-dimensional 3 x N or N x 3 elements array.

    MODEL REFERENCES:

        CAIN_2003:   Cain, J. C., B. B. Ferguson, and D. Mozzoni (2003),
                     An n = 90 internal potential function of the Martian crustal magnetic field,
                     J. Geophys. Res., 108(E2), 5008, doi:10.1029/2000JE001487.

        CAIN_2011:   There is a no official paper published any journals.

           ARKANI:   Arkani-Hamed, J. (2004),
                     A coherent model of the crustal magnetic field of Mars,
                     J. Geophys. Res., 109, E09005, doi:10.1029/2004JE002265.

         PURUCKER:  Lillis, R. J., M. E. Purucker, J. S. Halekas, K. L. Louzada,
                    S. T. Stewart-Mukhopadhyay, M. Manga, and H. V. Frey (2010),
                    Study of impact demagnetization at Mars using Monte Carlo modeling
                    and multipile altitude data,
                    J. Geophys. Res., 115, E07007, doi:10.1029/2009JE003556.

                    Purucker, M. E. (2008),
                    A global model of the internal magnetic field of the
                    Moon based on Lunar Prospector magnetometer observations,
                    Icarus, 197, 19-23, doi:10.1016/j.icarus.2008.03.016.

     MORSCHHAUSER:  Morschhauser, A., V. Lesur, and M. Grott (2014),
                    A spherical harmonic model of the lithospheric magnetic field of Mars,
                    J. Geophys. Res. Planets, 119, 1162-1188, doi:10.1002/2013JE004555.

         LANGLAIS:  Langlais, B., Thebault, 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, 1542– 1569. https://doi.org/10.1029/2018JE005854.

    NOTES:
       1. This routine is based on information from an IDL save file. The name
          of the save file is set as 'martiancrustmodels.sav' in the main procedure.

          1'. The latest IDL save file is generated by Robert Lillis.
              (This comment is noted by Takuya Hara.)

       2. Several supporting subroutines are included in this file, and appear
          BEFORE the main 'mvn_model_bcrust' routine.

       3. Use of the models using this routine DOES NOT imply that the modelers
          have given you permission to use their models. Do not be afraid to
          contact them - they are generally very happy to share the models.
          But they would like to know who is using their model - especially
          before any talks or publications.
          (This comment was noted by Dave Brain.)

    HISTORY:
    (YYYY-MM-DD)
     2004-07-27: Original version was written by Dave Brain.
                 It was optimized to use the Mars Global Surveyor (MGS) data.
     2004-08-24: Last modification date by Dave.
     2014-10-07: T. Hara revised to optimize for the MAVEN data.

    CREATED BY:	  Takuya Hara on 2015-02-12.

    LAST MODIFICATION:
     $LastChangedBy: hara $
     $LastChangedDate: 2020-07-07 11:33:30 -0700 (Tue, 07 Jul 2020) $
     $LastChangedRevision: 28857 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/models/mvn_model_bcrust.pro $

(See projects/maven/models/mvn_model_bcrust.pro)

## MVN_MODEL_BCRUST_ALT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:       MVN_MODEL_BCRUST_ALT

    PURPOSE:         Computes the Martian crustal magnetic field
                     2D (longitude - latitude) data at the same altitude level.
                     The computed result is returned by the "result" keyword.

    INPUTS:          Altitude level from the surface. Default is 400 km.

    KEYWORDS:

       RESOLUTION:   Lon-Lat grid resolution. Default is 1 deg.

           RESULT:   Returns the computed result.
                     If the computed data structure is supplied,
                     the Martian crustal field geographic map will be plotted.

           ARKANI:   Uses Arkani-Hamed's 62-deg and order spherical harmonic model.

        CAIN_2003:   Uses Cain's 2003 90-deg and order spherical harmonic model.

        CAIN_2011:   Uses Cain's 2011 90-deg and order spherical harmonic model.

         PURUCKER:   Uses Purucker's spherical harmonic model.

     MORSCHHAUSER:   Uses Morschhauser's 2014 110-deg and order spherical harmonic model.
                     (It is the default model to be calculated).

         LANGLAIS:   Uses Langlais's 2019 134-deg and order spherical harmonic model.

    CREATED BY:      Takuya Hara on 2015-11-04.

    LAST MODIFICATION:
     $LastChangedBy: hara $
     $LastChangedDate: 2023-03-14 08:32:44 -0700 (Tue, 14 Mar 2023) $
     $LastChangedRevision: 31626 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/models/mvn_model_bcrust_alt.pro $

(See projects/maven/models/mvn_model_bcrust_alt.pro)

## MVN_MODEL_BCRUST_CALC

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:        MVN_MODEL_BCRUST_CALC

    PURPOSE:         Calculates vector magnetic field at a given location (a_over_r, sct, scp)
                     in spherical coordinates from a spherical harmonic crustal model.

    INPUTS:

          G, H:      The coefficients, in square arrays with dimensions [nmax+1, nmax+1].
                     Coeffs are stored according to [n, m].

      A_OVER_R:      The value of a/r in the spherical harmonic expansion,
                     or the mean Martian radius by the radius at which
                     you are calculating the field.

      SCT, SCP:      The colatitude and east longitude at which you are calculating
                     the field, IN RADIANS.

    OUTPUTS:         [Br, Bt, Bp] at scr, sct, scp.

    KEYWORDS:        None.

    NOTE:            It originally comes from sph_b.pro, which is a subroutine included in mvn_model_bcrust.pro.
                     The original sph_b.pro was written by Dave Brain on 2001-10-08.
                     It is vectorized to perform the fast calculation.

    CREATED BY:      Takuya Hara on 2020-07-07.

    LAST MODIFICATION:
     $LastChangedBy: hara $
     $LastChangedDate: 2020-07-07 11:27:32 -0700 (Tue, 07 Jul 2020) $
     $LastChangedRevision: 28856 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/models/mvn_model_bcrust_calc.pro $

(See projects/maven/models/mvn_model_bcrust_calc.pro)

## MVN_MODEL_BCRUST_LOAD

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:       MVN_MODEL_BCRUST_LOAD

    PURPOSE:         Loads the Martian crustal magnetic field model(s) at
                     the MAVEN location. It is a simple wrapper of
                     'mvn_model_bcrust' and 'mvn_model_bcrust_restore'.

    INPUTS:

           TRANGE:   An array in any format accepted by time_double().
                     The minimum and maximum values in this array specify
                     the time range to load.

    KEYWORDS:

            ORBIT:   Loads the Martian crustal magnetic field model(s) by orbit number
                     or range of orbit numbers (trange is ignored). Orbits are numbered
                     using the NAIF convention, where the orbit number increments
                     at periapsis. Data are loaded from the apoapsis preceding
                     the first orbit (periapsis) number to the apoapsis following
                     the last orbit number.

     MORSCHHAUSER:   Loads Morschhauser's 2014 spherical harmonic model.
                     (It is the default model to resotre).

           ARKANI:   Loads Arkani-Hamed's spherical harmonic model.

        CAIN_2003:   Loads Cain's 2003 spherical harmonic model.

        CAIN_2011:   Loads Cain's 2011 spherical harmonic model.

         PURUCKER:   Loads Purucker's spherical harmonic model.

         LANGLAIS:   Loads Langlais's 2019 spherical harmonic model.

             CALC:   If there are no tplot save files to load, the Martian
                     crustal magnetic field is calculated by 'mvn_model_bcrust'.

           NOCALC:   If there are no tplot save files to load, then don't
                     try to calculate them, and don't ask.  (Allows non-
                     interactive calls.)  Takes precedence over CALC.

           STATUS:   Returns the loading status:
                     0 = Failure.
                     1 = Success.

    RELATED ROUTINES:
                     'mvn_model_bcrust', 'mvn_model_bcrust_restore'.

    CREATED BY:      Takuya Hara on 2015-02-18.

    LAST MODIFICATION:
     $LastChangedBy: hara $
     $LastChangedDate: 2021-12-03 16:40:11 -0800 (Fri, 03 Dec 2021) $
     $LastChangedRevision: 30448 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/models/mvn_model_bcrust_load.pro $

(See projects/maven/models/mvn_model_bcrust_load.pro)

## MVN_MODEL_BCRUST_RESTORE

[Previous Routine] [List of Routines]

    PROCEDURE:       MVN_MODEL_BCRUST_RESTORE

    PURPOSE:         Restores tplot save file(s) associated with the
                     Martian crustal magnetic field model(s).

    INPUTS:

           TRANGE:   Restores tplot save files spanning this time range.

    KEYWORDS:

            ORBIT:   Restores tplot save files by orbit number or range
                     of orbit numbers (trange is ignored). Orbits are numbered
                     using the NAIF convention, where the orbit number increments
                     at periapsis. Data are loaded from the apoapsis preceding
                     the first orbit (periapsis) number to the apoapsis following
                     the last orbit number.

     MORSCHHAUSER:   Restores Morschhauser's 2014 spherical harmonic model.
                     (It is the default model to resotre).

           ARKANI:   Restores Arkani-Hamed's spherical harmonic model.

        CAIN_2003:   Restores Cain's 2003 spherical harmonic model.

        CAIN_2011:   Restores Cain's 2011 spherical harmonic model.

         PURUCKER:   Restores Purucker's spherical harmonic model.

         LANGLAIS:   Restores Langlais's 2019 spherical harmonic model.

    CREATED BY:      Takuya Hara on 2015-02-18.

    LAST MODIFICATION:
     $LastChangedBy: rjolitz $
     $LastChangedDate: 2024-02-09 13:38:58 -0800 (Fri, 09 Feb 2024) $
     $LastChangedRevision: 32442 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/models/mvn_model_bcrust_restore.pro $

(See projects/maven/models/mvn_model_bcrust_restore.pro)