# spacepy.radbelt.RBmodel

class spacepy.radbelt.RBmodel(grid='L', NL=91, const_kp=False)

  1-D Radial diffusion class

  This module contains a class for performing and visualizing 1-D radial diffusion simulations of the radiation belts.

  Here is an example using the default settings of the model. Each instance must be initialized with (assuming import radbelt as rb):

      >>> rmod = rb.RBmodel()

  Next, set the start time, end time, and the size of the timestep:

      >>> import datetime
      >>> start = datetime.datetime(2003,10,14)
      >>> end = datetime.datetime(2003,12,26)
      >>> delta = datetime.timedelta(hours=1)
      >>> rmod.setup_ticks(start, end, delta, dtype='UTC')

  Now, run the model over the entire time range using the evolve method:

      >>> rmod.evolve()

  Finally, visualize the results:

      >>> rmod.plot_summary()

  `Gaussian_source`() | Gaussian source term added to radiation belt model.
  `add_Lmax`(Lmax_model) | add last closed drift shell Lmax
  `add_Lpp`(Lpp_model) | add last closed drift shell Lmax
  `add_PSD_obs`([time, PSD, Lstar, satlist]) | add PSD observations
  `add_PSD_twin`([dt, Lt]) | add observations from PSD database using the ticks list the arguments are the following:
  `add_omni`([keylist]) | add omni data to instance according to the tickrange in ticks
  `add_source`([source, A, mu, sigma]) | add source parameters A, mu, and sigma for the Gaussian source function
  `assimilate`([method, inflation]) | Assimilates data for the radiation belt model using the Ensemble Kalman Filter.
  `evolve`() | calculate the diffusion in L at constant mu,K coordinates
  `get_DLL`(Lgrid, params[, DLL_model]) | Calculate DLL as a simple power law function (alpha*L**Bbta) using alpha/beta values from popular models found in the literature and chosen with the kwarg "DLL_model".
  `plot`([Lmax, Lpp, Kp, Dst, clims, title, values]) | Create a summary plot of the RadBelt object distribution function.
  `plot_obs`([Lmax, Lpp, Kp, Dst, clims, title, ...]) | Create a summary plot of the observations.
  `set_lgrid`([NL]) | Using NL grid points, create grid in L.
  `setup_ticks`(start, end, delta[, dtype]) | Add time information to the simulation by specifying a start and end time, timestep, and time type (optional).

  Gaussian_source()

    Gaussian source term added to radiation belt model. The source term is given by the equation:

    S = A exp{-(L-mu)^2/(2*sigma^2)}

    with A=10^(-8), mu=5.0, and sigma=0.5 as default values

  add_Lmax(Lmax_model)

    add last closed drift shell Lmax

  add_Lpp(Lpp_model)

    add last closed drift shell Lmax

  add_PSD_obs(time=None, PSD=None, Lstar=None, satlist=None)

    add PSD observations

    Parameters:
      time Ticktock datetime array

        array of observation times

      PSD list of numpy arrays

        PSD observational data for each time. Each entry in the list is a numpy array with the observations for the corresponding time

      Lstar list of numpy arrays

        Lstar location of each PSD observations. Each entry in the list is a numpy array with the location of the observations for the corresponding time

      satlist list of satellite names
    Returns:
      out list of dicts

        Information of the observational data, where each entry contains the observations and locations of observations for each time specified in the time array. Each list entry is a dictionary with the following information:

      Ticks Ticktock array

        time of observations

      Lstar numpy array

        location of observations

      PSD numpy array

        PSD observation values

      sat list of strings

        satellite names

      MU scalar value

        Mu value for the observations

      K scalar value

        K value for the observations

  add_PSD_twin(dt=0, Lt=1)

    add observations from PSD database using the ticks list the arguments are the following:

    > dt = observation time delta in seconds Lt = observation space delta

  add_omni(keylist=None)

    add omni data to instance according to the tickrange in ticks

  add_source(source=True, A=1e-08, mu=5.0, sigma=0.5)

    add source parameters A, mu, and sigma for the Gaussian source function

  assimilate(method='EnKF', inflation=0)

    Assimilates data for the radiation belt model using the Ensemble Kalman Filter. The algorithm used is the SVD method presented by Evensen in 2003 (Evensen, G., Ocean dynamics, 53, pp.343–367, 2003). To compensate for model errors, three inflation algorithms are implemented. The inflation methodology is specified by the ‘inflation’ argument, and the options are the following:

    > inflation == 0: Add model error (perturbation for the ensemble) around model state values only where observations are available (DEFAULT).

    > inflation == 1: Add model error (perturbation for the ensemble) around observation values only where observations are available.

    > inflation == 2: Inflate around ensemble average for EnKF.

    Prior to assimilation, a set of data values has to be speficied by setting the start and end dates, and time step, using the setup_ticks funcion of the radiation belt model:

        >>> import spacepy
        >>> import datetime
        >>> from spacepy import radbelt

        >>> start = datetime.datetime(2002,10,23)
        >>> end = datetime.datetime(2002,11,4)
        >>> delta = datetime.timedelta(hours=0.5)
        >>> rmod.setup_ticks(start, end, delta, dtype='UTC')

    Once the dates and time step are specified, the data is added using the add_PSD function:

        >>> rmod.add_PSD()

    The observations are averaged over the time windows, whose interval is give by the time step.

    Once the dates and data are set, the assimiation is performed using the ‘assimilate’ function:

        >>> rmod.assimilate(inflation=1)

    This function will add the PSDa values, which are the analysis state of the radiation belt using the observations within the dates. To plot the analysis simply use the plot funtion:

        >>> rmod.plot(values=rmod.PSDa,clims=[-10,-6],Lmax=False,Kp=False,Dst=False)

  evolve()

    calculate the diffusion in L at constant mu,K coordinates

  get_DLL(Lgrid, params, DLL_model='BA2000')

    Calculate DLL as a simple power law function (alpha*L**Bbta) using alpha/beta values from popular models found in the literature and chosen with the kwarg “DLL_model”.

    The calculated DLL is returned, as is the alpha and beta values used in the calculationp.

    The output DLL is in units of units/day.

  plot(Lmax=True, Lpp=False, Kp=True, Dst=True, clims=[0, 10], title=None, values=None)

    Create a summary plot of the RadBelt object distribution function. For reference, the last closed drift shell, Dst, and Kp are all included. These can be disabled individually using the corresponding Boolean kwargs.

    The clims kwarg can be used to manually set the color bar range. To use, set it equal to a two-element list containing minimum and maximum Log_10 value to plot. Default action is to use [0,10] as the log_10 of the color range. This is good enough for most applications.

    The title of the top most plot defaults to ‘Summary Plot’ but can be customized using the title kwarg.

    The figure object and all three axis objects (PSD axis, Dst axis, and Kp axis) are all returned to allow the user to further customize the plots as necessary. If any of the plots are excluded, None is returned in their stead.

    Examples

        >>> rb.plot(Lmax=False, Kp=False, clims=[2,10], title='Good work!')

    This command would create the summary plot with a color bar range of 100 to 10^10. The Lmax line and Kp values would be excluded. The title of the topmost plot (phase space density) would be set to ‘Good work!’.

  plot_obs(Lmax=True, Lpp=False, Kp=True, Dst=True, clims=[0, 10], title=None, values=None)

    Create a summary plot of the observations. For reference, the last closed drift shell, Dst, and Kp are all included. These can be disabled individually using the corresponding boolean kwargs.

    The clims kwarg can be used to manually set the color bar range. To use, set it equal to a two-element list containing minimum and maximum Log_10 value to plot. Default action is to use [0,10] as the log_10 of the color range. This is good enough for most applications.

    The title of the top most plot defaults to ‘Summary Plot’ but can be customized using the title kwarg.

    The figure object and all three axis objects (PSD axis, Dst axis, and Kp axis) are all returned to allow the user to further customize the plots as necessary. If any of the plots are excluded, None is returned in their stead.

    Examples

        >>> rb.plot_obs(Lmax=False, Kp=False, clims=[2,10], title='Observations Plot')

    This command would create the summary plot with a color bar range of 100 to 10^10. The Lmax line and Kp values would be excluded. The title of the topmost plot (phase space density) would be set to ‘Good work!’.

  set_lgrid(NL=91)

    Using NL grid points, create grid in L. Default number of points is 91 (dL=0.1).

  setup_ticks(start, end, delta, dtype='ISO')

    Add time information to the simulation by specifying a start and end time, timestep, and time type (optional).

    Examples

        >>> start = datetime.datetime(2003,10,14)
        >>> end = datetime.datetime(2003,12,26)
        >>> delta = datetime.timedelta(hours=1)
        >>> rmod.setup_ticks(start, end, delta, dtype='UTC')