Repository files navigation

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

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. Seefluxrope.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 (seeDr. 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 3 | Numpy | SciPy | pandas | Matplotlib | ai.cdas | SpacePy |CDF Library

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.gzcd PyGS-1.0.0python3 setup.py install# Launch Python3 to see if it worksimport PyGS

*Pip3 install will be available shortly.

• Option 2:
  • Step 1: Save thePyGS 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 fileGSD.py orGSR.py.
  • Step 4: Open terminal or wherever you use Python, runpython3 GSD.py orpython3 GSR.py.

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

  • Please seeinstruction_gsd for more information.

  fromdatetimeimportdatetimefromPyGS.FluxRopeDetectionimportdetectionrootDir='/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 seeinstruction_gsr_example for more information.

  """It may be better to copy all these lines into a script file and run python3 script.py"""importpickleimportpandasaspdfromdatetimeimportdatetimefromPyGS.ReconstructionMiscimportreconstruction# 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 parametersSFR_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 seeinstruction_HT_analysis.
  • For MVAB frame, please seeinstruction_mvab.

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

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

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