PyGS

Magnetic flux rope detection & reconstruction based on the extended Grad-Shafranov equation.

Introduction

This package consists of two key products to serve as a set of comprehensive tools for the investigation of magnetic flux ropes (FRs) in space plasmas based on in-situ spacecraft measurements. See fluxrope.info for details.

• The Grad-Shafranov (GS)-based detection (GSD):

  • Automatedly identify flux ropes and output their parameters
  • Support the purpose of the statistical analysis
  • Rely on the generalized version of the GS equation (Teh 2018)
  • Applicable to FRs with a broad definition including both static and dynamic structures
  • Applicable to PSP, Solar Orbiter, Ulysses, ACE, and WIND spacecraft datasets
  • Enhanced and streamlined from the original automated GSD (see Dr. Jinlei Zheng's GitHub)
  • Final outputs:
    • an event list including selected flux rope parameters
    • a time-series plot showing flux rope intervals and selected plots showing part of the analysis results

• The Grad-Shafranov (GS) type reconstruction (GSR, Hu & Sonnerup 2002):

  • Visualize and characterize the 2D magnetic field configuration from 1D time-series data
  • Confirm the SFR detection results
  • Derive flux rope parameters, e.g., the poloidal and toroidal magnetic fluxes, the relative helicity, average twist, etc.
  • Useful for case studies
  • Final outputs: a set of figures characterizing flux rope properties

Python & Dependencies

Python 3 | Numpy | SciPy | pandas | Matplotlib | ai.cdas | SpacePy | CDF Library

Installations

For non-Python users*:

• Option 1

# Download PyGS & find where the file is, usually in downloads folder
# Also download "examples" folder since it includes necessary inputs for testing.
# On your terminal:
tar -zxvf PyGS-1.0.0.tar.gz
cd PyGS-1.0.0
python3 setup.py install
# Launch Python3 to see if it works
import PyGS

*Pip3 install will be available shortly.

• Option 2:
  • Step 1: Save the PyGS folder.
  • Step 2: In the local PyGS folder, create a script file containing lines as shown in the next session (within gray block).
  • Step 3: Let's name this file GSD.py or GSR.py.
  • Step 4: Open terminal or wherever you use Python, run python3 GSD.py or python3 GSR.py.

Basic Examples

• The Grad-Shafranov (GS)-based detection (GSD)

  • Please see instruction_gsd for more information.

  from datetime import datetime
  from PyGS.FluxRopeDetection import detection
  
  rootDir = '/home/ychen/Desktop/PyGS/examples/'
  # Notice the shock list file is needed.
  # Please make sure if you have specified the correct path to this file.
  shockList = rootDir + 'IPShock_ACE_or_WIND_or_Ulysses_1996_2016_DF.p' 
  
  if __name__ == "__main__":
      detection(rootDir, spacecraftID='WIND',
          timeStart=datetime(2018,10,31,18,0,0), timeEnd=datetime(2018,10,31,22,0,0),
          duration=(10,30),
          includeTe=True, includeNe=False,
          Search=True, CombineRawResult=True, GetMoreInfo=True,
          LabelFluxRope=True,B_mag_threshold=5.0, shockList_DF_path=shockList, allowIntvOverlap=False)

  

• The Grad-Shafranov (GS)-based reconstruction (GSR)

  • Please see instruction_gsr_example for more information.

  """It may be better to copy all these lines into a script file and run python3 script.py"""
  
  import pickle
  import pandas as pd
  from datetime import datetime
  from PyGS.ReconstructionMisc import reconstruction
  
  # Please specify the path to where the "examples" folder is saved.
  # Parameter settings here are supported by files in the "examples" folder.
  # You may follow the instruction to start over with the initial settings.
  
  rootDir = '/home/ychen/Desktop/PyGS/examples/'
  inputFileName = 'detailed_info.p' # The file includes the flux rope parameters
  
  SFR_detection_list = pd.read_pickle(open(rootDir + inputFileName,'rb'))
  reconstruction(rootDir, spacecraftID='WIND', FR_list=SFR_detection_list, eventNo=0,
                 timeStart=datetime(2018,8,28,0,24,0), timeEnd=datetime(2018,8,28,0,32,0), 
                 adjustAxis=False, 
                 grid_x=15, grid_y=131, 
                 get_Ab=1, pressureSwitch=1, polyOrder=3, dmid=0, dAl0=0.0, dAr0=0.0,
                 includeTe=False, includeNe=False, saveFig=False, plotJz=False, 
                 plotHodogram=False, checkHT=False, plotWalenRelation=False, 
                 plotSpacecraftTimeSeries=False, adjustInterval=False, 
                 checkPtAFitting=False, helicityTwist=False)

  

• The GSR function includes some calculations, e.g., HT frame analysis, MVAB, etc., which can be run independently.

  • For HT analysis, please see instruction_HT_analysis.
  • For MVAB frame, please see instruction_mvab.

Citations and References

• If using GSD, please cite Zheng and Hu 2018, Hu et al. 2018, & Chen and Hu 2022.
• If using GSR, please cite Sonnerup & Guo 1996, Hau & Sonnerup 1999, Hu & Sonnerup 2002, & Chen and Hu 2022.
• Flux rope events using the original GSD are available on flux rope database.
• Python files for the original GSD are available on Dr. Jinlei Zheng's GitHub.

Acknowledgements

We appreciate the help and previous work of Dr. Jinlei Zheng who created the original GSD, and acknowledge the NASA grant 80NSSC23K0256 for funding.

Notes

Please reach out to Dr. Yu Chen (yc0020@uah.edu) for any bugs.