# spacepy.irbempy.get_Lstar

spacepy.irbempy.get_Lstar(ticks, loci, alpha=90, extMag='T01STORM', options=[1, 0, 0, 0, 0], omnivals=None, landi2lstar=False)

  This will call make_lstar1 or make_lstar_shell_splitting_1 from the irbem library and will lookup omni values for given time if not provided (optional). If pitch angles are provided, drift shell splitting will be calculated and “Bmirr” will be returned. If they are not provided, then no drift shell splitting is calculated and “Blocal” is returned.

  Parameters
    - ticks (Ticktock class)containing time information
    - loci (Coords class)containing spatial information
    - alpha (list or ndarray)optional pitch angles in degrees (default is 90);

      if provided will calculate shell splitting; max 25 values

    - extMag (string)optional; will choose the external magnetic field model

      possible values [‘0’, ‘MEAD’, ‘T87SHORT’, ‘T87LONG’, ‘T89’, ‘OPQUIET’, ‘OPDYN’, ‘T96’, ‘OSTA’, ‘T01QUIET’, ‘T01STORM’, ‘T05’, ‘ALEX’, ‘TS07’]

    - options (optional list or array of integers length=5)explained below
    - omni values as dictionary (optional)if not provided, will use lookup table
    - landi2lstar if True, will use the faster landi2lstar routine if possible. This

      routine can only be used with OPQUIET+IGRF magnetic field models.

  Returns
    - results (dictionary)containing keys: Lm, Lstar, Bmin, Blocal (or Bmirr), Xj, MLT

      if pitch angles provided in “alpha” then drift shells are calculated and “Bmirr” is returned if not provided, then “Blocal” at spacecraft is returned. A negative value for Lm indicates the field line is closed but particles are lost to the atmosphere; the absolute value indicates the L value. A negative value for Lstar indicates the field line is closed but particles are lost to the atmosphere before completing a drift orbit; the absolute value indicates the drift shell.

  Notes

  External Field

    - 0 : no external field

    - MEAD : Mead & Fairfield [1975] (uses 0<=Kp<=9 - Valid for rGEO<=17. Re)

    - T87SHORT: Tsyganenko short [1987] (uses 0<=Kp<=9 - Valid for rGEO<=30. Re)

    - T87LONG : Tsyganenko long [1987] (uses 0<=Kp<=9 - Valid for rGEO<=70. Re)

    - T89 : Tsyganenko [1989] (uses 0<=Kp<=9 - Valid for rGEO<=70. Re)

    - OPQUIET : Olson & Pfitzer quiet [1977] (default - Valid for rGEO<=15. Re)

    - OPDYNOlson & Pfitzer dynamic [1988] (uses 5.<=dens<=50., 300.<=velo<=500.,

        -100.<=Dst<=20. - Valid for rGEO<=60. Re)

    - T96Tsyganenko [1996] (uses -100.<=Dst (nT)<=20., 0.5<=Pdyn (nPa)<10.,

        abs(ByIMF) (nT)<1=0., abs(BzIMF) (nT)<=10. - Valid for rGEO<=40. Re)

    - OSTAOstapenko & Maltsev [1997] (uses dst,Pdyn,BzIMF, Kp)

        T01QUIET: Tsyganenko [2002a,b] (uses -50.<Dst (nT)<20., 0.5<Pdyn (nPa)<=5., abs(ByIMF) (nT)<=5., abs(BzIMF) (nT)<=5., 0.<=G1<=10., 0.<=G2<=10. - Valid for xGSM>=-15. Re)

    - T01STORM: Tsyganenko, Singer & Kasper [2003] storm (uses Dst, Pdyn, ByIMF, BzIMF, G2, G3 -

        there is no upper or lower limit for those inputs - Valid for xGSM>=-15. Re)

    - T05Tsyganenko & Sitnov [2005] storm (uses Dst, Pdyn, ByIMF, BzIMF,

        W1, W2, W3, W4, W5, W6 - no upper or lower limit for inputs - Valid for xGSM>=-15. Re)

  OMNI contents

    - Kp: value of Kp as in OMNI2 files but has to be double instead of integer type

    - Dst: Dst index (nT)

    - dens: Solar Wind density (cm-3)

    - velo: Solar Wind velocity (km/s)

    - Pdyn: Solar Wind dynamic pressure (nPa)

    - ByIMF: GSM y component of IMF mag. field (nT)

    - BzIMF: GSM z component of IMF mag. field (nT)

    - G1: G1=< Vsw*(Bperp/40)2/(1+Bperp/40)*sin3(theta/2) > where the <> mean an average over the

        previous 1 hour, Vsw is the solar wind speed, Bperp is the transverse IMF component (GSM) and theta it’s clock angle.

    - G2: G2=< a*Vsw*Bs > where the <> mean an average over the previous 1 hour,

        Vsw is solar wind speed, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0, a=0.005.

    - G3: G3=< Vsw*Dsw*Bs /2000.> where the <> mean an average over the previous 1 hour,

        Vsw is the solar wind speed, Dsw is the solar wind density, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0.

    - W1 - W6: see definition in (JGR-A, v.110(A3), 2005.) (PDF 1.2MB)

    - AL: the auroral index

  Options

    - 1st element: 0 - don’t compute L* or phi ; 1 - compute L*; 2- compute phi

    - 2nd element: 0 - initialize IGRF field once per year (year.5);

        n - n is the frequency (in days) starting on January 1st of each year (i.e. if options(2nd element)=15 then IGRF will be updated on the following days of the year: 1, 15, 30, 45 …)

    - 3rd element: resolution to compute L* (0 to 9) where 0 is the recomended value to ensure a

        good ratio precision/computation time (i.e. an error of ~2% at L=6). The higher the value the better will be the precision, the longer will be the computing time. Generally there is not much improvement for values larger than 4. Note that this parameter defines the integration step (theta) along the field line such as dtheta=(2pi)/(720*[options(3rd element)+1])

    - 4th element: resolution to compute L* (0 to 9). The higher the value the better will be

        the precision, the longer will be the computing time. It is recommended to use 0 (usually sufficient) unless L* is not computed on a LEO orbit. For LEO orbit higher values are recommended. Note that this parameter defines the integration step (phi) along the drift shell such as dphi=(2pi)/(25*[options(4th element)+1])

    - 5th element: allows to select an internal magnetic field model (default is set to IGRF)

        - 0 = IGRF

        - 1 = Eccentric tilted dipole

        - 2 = Jensen&Cain 1960

        - 3 = GSFC 12/66 updated to 1970

        - 4 = User-defined model (Default: Centred dipole + uniform [Dungey open model] )

        - 5 = Centred dipole

  Examples

      >>> t = Ticktock(['2002-02-02T12:00:00', '2002-02-02T12:10:00'], 'ISO')
      >>> y = Coords([[3,0,0],[2,0,0]], 'GEO', 'car')
      >>> spacepy.irbempy.Lstar(t,y)
      {'Blocal': array([ 1020.40493286,  3446.08845227]),
          'Bmin': array([ 1019.98404311,  3437.63865243]),
          'Lm': array([ 3.08948304,  2.06022102]),
          'Lstar': array([ 2.97684043,  1.97868577]),
          'MLT': array([ 23.5728333 ,  23.57287944]),
          'Xj': array([ 0.00112884,  0.00286955])}