4. Setting up ForeCAT magnetic field

We’ve now exhausted all of the features within the IP version of OSPREI so we will now move on to the full version that includes ForeCAT. ForeCAT uses a PFSS magnetic background that we create before running the CME simulation. We generate the background PFSS magnetic field from a magnetogram and save it as a pickle. ForeCAT opens the pickle and just looks up/interpolates the magnetic field wherever it needs it. The standard approach is to use HMI daily synchronic magnetograms from the JSOC catalog, but the processing scripts can also use HMI synoptic magnetograms or GONG magnetograms.

4.1 Getting a Synchronic Magnetogram

To get a HMI magnetogram go to the JSOC catalog here, which can be difficult to navigate the different fields and figure out the correct syntax but this link should autofill some important details.

The ? field should already have hmi.mrdailysynframe_720s filled in, which is the generic file name for the radial daily synoptic frame. The first and last record section shows examples of how to format the date on these files. For the test case edit the ? field to say hmi.Mrdailysynframe_720s[2021.09.23_12:00:00_TAI] and hit GetRecordCount, which will process for a second, then should turn yellow and show that it found one record. Hit Fetch Keyword Values for RecordSet at the bottom, it will shift to the Values Display tab. Click on Export Data and click Export and it will open a new browser tab with most of the information filled in. Add your email address in the Notify field and hit Check Parameters. You will need to confirm your email address if this is the first time you are requesting from JSOC but afterward it should automatically recognize you. Assuming you get the OK click on the green submit button. It shouldn’t take long to process, you can click Submit Status Request and once it is ready you will get a url to download the fits file.

4.2 Making the PFSS Pickle

Move the fits file into the PickleJar folder and rename it HMI20210923sync.fits. Open mag2PFSS.py from the helperCode folder and make mainpath and magpath (at the top) match your system. This program will convert a magnetogram into harmonic coefficients then use these to set up the magnetic field pickle. There is some flexibility in the name of the fits file. The program will check if it has either “HMI” or “GONG” to identify the observatory and for “sync” to check if it’s a synchronic magnetogram. The remaining portion (“20210923” in this example) is assumed to be an identifier for this magnetogram. I default to using the 8 digit date as the tag, but you any string should work. The full magnetic field preparation is executed by a single call:

python helperCode/mag2PFSS.py HMI20210923sync.fits

Note since mag2PFSS already has the pickle folder name you just need to pass it the file name, not the full path. Synchronic magnetograms take the first full synoptic magentogram prior to the chosen date and replace the data at longitudes within ±60° of the central meridian with the observations from that date. In the HMI fits file, the magnetogram is shifted so that 0-120° longitude contain the new data. sync2carr (within mag2PFSS) will shift the magnetogram to Carrington longitudes. The shifted magnetogram is saved as HMI20210923syncCL.fits.

The function harmonics (within mag2PFSS) then takes either the shifted synchronic fits file or the input fits file and calculates the harmonic coefficients, which get saved in a text file as “OBS + identifier [+ CL] + coeffs.data” where OBS represents the observatory and CL indicate Carrington longitudes. For our example the file is HMI20210923syncCLcoeffs.dat. harmonics assumes that the input magnetogram is in sine latitude rather than latitude (as is the case for HMI data). If your magnetogram is not in sine latitude then add isSinLat=False after nHarmonics in the call to harmonics in line 424 (bottom of the file below the coeff_file= line).

The function makedapickle uses the harmonic coefficient file to calculate the PFSS magnetic field and stores the results in pickle save files. The pickles are named “PFSS_ + identifier [+ CL] + X.pkl” where X can be a3, b3, or SS3 (e.g. PFSS_HMI20210923syncCLa3.pkl). The PFSS data is split into a lower and upper half based on radial distance (“a” and “b” tags) and we save the values at the source surface height (SS). The 3 indicates that the pickles were created using python3 as there can be issues between python2 and python3. Finally, calcHCSdist determines the minimum distance of each lat/lon from the heliospheric current sheet, which is needed by the background density model in ForeCAT, and saves it in “PFSS_ + identifier [+ CL] + dists3.pkl”.

Our PFSS procedure defaults to harmonic coefficients up to order 90 and a source surface at 2.5 Rs. These values can be changed in lines 15 and 16 of mag2PFSS.py. We also hardcode the PFSS resolution with nR = 151 (radial distance), nTheta = 361 (latitude), and nPhi = 720 (longitude) in lines 20-22. This gives 0.5° resolution in latitude and longitude and 0.01 Rs in radial distance. calcHCSdist is hardcoded to work with 0.5° resolution so it is not recommended to change nTheta and nPhi, but nR and rSS can be varied.

The full mag2PFSS procedure should take 10-30 minutes to run depending on your computer. Calculating the harmonic coefficients takes a few minutes then tens of minutes to make the pickles. The four .pkl files (“a”, “b”, “SS”, and “dists”) are what ForeCAT needs to run.