Getting started

The gdf repository directory comes with a main.py driver Python file and a init_gdf_default.py initialization file. It is expected that the user would only need to change (normally, just a few) of the parameters in the initialization file to obtain the distributions and associated moments in a desired time interval.

A example GDF reconstruction

To get started with your first reconstruction using the gdf repository, run the following in your terminal from the repository directory. Make sure you have activated your environment where you have installed gdf.

python main.py init_gdf_default

This should generate a few diagnostic figures, plots of reconstruction and super-resolution under the Figures/ directory, as well as a pkl file under the Outputs/ directory. Two of these generated figures that we would like to highlight at the outset are

• Fig. 1 which shows a comparison between the SPAN-Ai grids in field aligned coordinates (FAC) and the corresponding reconstructed distribution at the same grid points from the polar-cap Slepian reconstruction. These are plotted using matplotlib.pyplot.tricontourf since the data is on an irregular grid. This figure can be found in Figures/span_rec_contour/.

• Fig. 2 which shows the final reconstructed GDF after being super-resolved on a fine Cartesian grid. This figure can be found in Figures/super_res/. All subsequent moments are computed using super-resolved distributions and not the crude SPAN-Ai FAC distributions.

Fig. 1 Left: A matplotlib.pyplot.tricontourf representation of the SPAN-Ai VDF after rotating the grids into field aligned coordinates (FAC). Right: Same, but for the polar cap reconstructed GDF evaluated at the FAC grid locations. The colorbar is obtained from normalizing the log-scaled distributions.

Fig. 2 Final super-resolved image from the Slepians-on-a-polar-cap basis reconstruction. The background colormap is obtained from a matplotlib.pyplot.tricontourf of the high-resolution Cartesian super-resolved grid. The overplotted colored grids denote the SPAN-Ai measurements for visual comparison to assess goodness-of-fit. The colorbar is in log-scale but in original VDF units.

Understanding the initialization file

# init_gdf_default.py
# This is a template for primary initization file.
# 'global': parameters needed for any method of reconstruction
# 'polcap', 'cartesian', 'hybrid' are parameters specific to particular methods of reconstruction

config = {
    'global': {                                                             #--------GLOBAL PARAMETERS FOR GDF-----------#
        'METHOD'          : 'hybrid',                                       # choose a method. Use 'hybrid' if unsure
        'TRANGE'          : ['2020-01-26T14:28:00', '2020-01-26T14:30:00'], # Define the time range to load in from pyspedas
        'SYNTHDATA_FILE'  : None,                                           # Path to a data file containing synthetic observation
        'CLIP'            : True,                                           # If you want to clip the loaded day's data to the specified TRANGE
        'START_INDEX'     : 0,                                              # Starting index with respect to the first timestamp in TRANGE
        'NSTEPS'          : 1,                                              # use None for entire TRANGE interval
        'CREDS_PATH'      : './config.json',                                # path to the <.json> file containing credentials
        'COUNT_THRESHOLD' : 2,                                              # the minimum counts per grid point to be consider in the reconstruction
        'SAVE_FIGS'       : True,                                           # flag for saving final figures. Default extension is .png
        'SAVE_PKL'        : False,                                          # flag for saving the reconstructed moments for the NSTEPS reconstruction
        'SAVE_SUPRES'     : False,                                          # if you want to save the super-resolved GDF and the corresponding grids
        'MIN_METHOD'      : 'L-BFGS-B',                                     # minimization method to find gyro-centroid
        'NPTS_SUPER'      : 49,                                             # the number of grids in the super-resolved GDF. Taken scalar or a tuple
        'MCMC'            : False,                                          # flag for using MCMC based gyro-centroid refinement
        'MCMC_WALKERS'    : 6,                                              # number of inpendent walkers to be used in MCMC
        'MCMC_STEPS'      : 200,                                            # number of steps each walker will take
    },
    'polcap': {                                                             #-----------POLAR CAP METHOD PARAMETERS---------#
        'TH'              : None,                                           # the one-sided angle for the polar cap. None = use adaptive calculation
        'LMAX'            : 12,                                             # maximum angular degree for polar cap Slepians, instrument-based choice
        'N2D_POLCAP'      : None,                                           # total number of 1D polcap cap Slepian functions to use. None = Shannon
        'P'               : 3,                                              # order for the piecewise B-spline. 
        'SPLINE_MINCOUNT' : 7,                                              # minimum number of gridpoints for each knot. If lower, then merge knots
    },
    'cartesian': {                                                          #------------CARTESIAN METHOD PARAMETERS---------#
        'N2D_CART'        : None,                                           # default choice for the number of Cartesian Slepian functions.
        'N2D_CART_MAX'    : 100,                                            # maximum value for N2D_CART. Useful for very high calculated kmax
    },
    'hybrid': {                                                             #--------------HYBRID METHOD PARAMETERS-----------#
        'LAMBDA'          : None,                                           # default choice for similarity parameters. None = use L-curve method
    },
    'quadrature': {                                                         #--------------GAUSS-LEGENDRE QUADRATURE----------# [not used currently]
        'NQ_V'             : 2,                                             # number of nodes in velocity
        'NQ_T'             : 2,                                             # number of nodes in elevation (theta)
        'NQ_P'             : 2,                                             # number of nodes in azimuth (phi)
    }
}

The initialization file is supposed to be the primary interface for a standard user. While there are a number of listed parameters, TRANGE, START_INDEX and NTEPS are the three primary parameters which we think the user would interact with the most. Descriptions for all the parameters are provided in the table below.

Table 1 Description of parameters in the init_gdf_default.py initialization file.

Parameter	Type	Description
TRANGE	list of str	Start and end times in ISO 8601 standard format in UTC YYYY-MM-DD-Thh:mm:ss
CLIP	bool	Whether to clip to specified TRANGE or keep entire day’s data.
START_INDEX	int	Index of first desired time stamp for gdf with respect to the start time in TRANGE.
NSTEPS	int or None	Number of timestamps to analyze starting at START_INDEX. Use None for entire TRANGE.
CREDS_PATH	str or None	Path to a json file containing credentials to access SWEAP and FIELDS proprietary data.
COUNT_THRESHOLD	int	Particle count threshold below which grid points are ignored from reconstructions.
SAVE_FIGS	bool	Flag if the final (and diagnostic) figures should be saved under directories in Figures/.
SAVE_PKL	bool	Flag if the final metadata should be stored as a pkl file in the Outputs/ directory.
MIN_METHOD	str	Minimization method used in the scipy.optimize.minimize. Optimal choice is ‘L-BFGS-B’.
NPTS_SUPER	int or tuple of ints	Number of super-resolved points in a uniform Cartesian grid of (\(v_{\perp},\, v_{\parallel}\)). This can be a tuple if (NPTSx, NPTSy) where \(x\) is along \(v_{\perp}\) and \(y\) is along \(v_{\parallel}\).
MCMC	bool	Flag to use a MCMC refinement of the gyroaxis, provides error esimtates on the gyro-centroid.
MCMC_WALKERS	int	Number of MCMC walkers to be used. Need to use 3 minimum walkers.
MCMC_STEPS	int	Number of MCMC steps for each walker. Optimal choice: (6 MCMC_WALKERS, 200 MCMC_STEPS).
TH	float	Polar cap extent in degrees about the magnetic field axis used for generating Slepians.
LMAX	int	Maximum angular degree for constructing the 1D Slepian basis on a polar cap..
N2D_POLCAP	int or None	The number of polar-cap Slepian functions to be used for reconstructions.
P	int (default: 3)	The degree of the B-spline used for discretizing in velocity phase space.
SPLINE_MINCOUNT	int	Minimum number of grid points to be contained in each B-spline shell.
N2D_CART	int	The Shannon number for the Cartesian Slepian basis.
LAMBDA	float	The imposed similarity in the cost function term \(\lambda \left(G_1 \, m_1 - G_2 \, m_2 \right)^2\).